이 페이지는 Cloud Translation API를 통해 번역되었습니다.

생성형 AI 애플리케이션용 Spanner 사용 시작하기

이 튜토리얼에서는 Spanner와 Vertex AI를 사용하여 생성형 AI 애플리케이션을 빌드하는 방법을 보여줍니다.

이 애플리케이션을 사용하면 시맨틱 유사성 검색을 실행하여 자연어 쿼리와 일치하는 제품을 찾을 수 있습니다. 이를 위해 단어의 의미와 맥락을 포착하는 텍스트의 숫자 표현인 임베딩을 사용합니다. Vertex AI 모델을 사용하여 이러한 임베딩을 생성한 다음 Spanner에 임베딩을 저장하고 검색합니다. 이 접근 방식은 사용자가 특정 키워드 대신 자연어로 원하는 것을 설명할 수 있는 제품 검색과 같은 사용 사례에 특히 유용합니다.

다음 주제에서는 다음 작업을 수행하는 방법을 안내합니다.

Google Cloud 프로젝트 만들기
Spanner 인스턴스 만들기
데이터베이스 만들기
임베딩 모델 만들기
Spanner에 데이터 로드
데이터의 임베딩 생성하기
KNN 벡터 유사성 검색 수행
벡터 색인을 사용하여 벡터 검색 확장
리소스 정리

Spanner 가격 책정 세부정보는 Spanner 가격 책정을 참조하세요.

Codelab을 사용해 보려면 Spanner 벡터 검색 시작하기를 참고하세요.

시작하기 전에

결제 계정에 연결된 Google Cloud 프로젝트를 만들어야 합니다.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Spanner API가 자동으로 사용 설정됩니다. 그렇지 않으면 다음과 같이 수동으로 사용 설정합니다.
Spanner API 사용 설정
Vertex AI API가 자동으로 사용 설정됩니다. 그렇지 않으면 다음과 같이 수동으로 사용 설정합니다.
Vertex AI API 사용 설정

인스턴스 및 데이터베이스를 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Cloud Spanner 관리자(roles/spanner.admin) IAM 역할을 부여해 달라고 요청하세요.

Cloud Spanner 관리자 역할이 부여되지 않은 경우 Spanner 그래프를 쿼리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Cloud Spanner 데이터베이스 리더(roles/spanner.databaseReader) IAM 역할을 부여해 달라고 요청하세요.

인스턴스 만들기

Spanner를 처음 사용할 때는 인스턴스를 만들어야 합니다. 이 인스턴스는 Spanner 데이터베이스에서 사용하는 리소스를 할당한 것입니다. 이 섹션에서는 Google Cloud 콘솔을 사용하여 인스턴스를 만드는 방법을 보여줍니다.

Google Cloud 콘솔에서 Spanner 페이지로 이동합니다.

Spanner로 이동
아직 만들지 않았으면 Google Cloud 프로젝트를 선택하거나 만듭니다.
다음 중 하나를 수행합니다.
1. 이전에 Spanner 인스턴스를 만들지 않았으면 Spanner 시작 페이지에서 프로비저닝된 인스턴스 만들기를 클릭합니다.
2. Spanner 인스턴스를 만들었으면 인스턴스 페이지에서 인스턴스 만들기를 클릭합니다.
버전 선택 페이지에서 Enterprise Plus 또는 Enterprise를 선택합니다.

Spanner 벡터 검색은 Enterprise 버전 또는 Enterprise Plus 버전에서만 사용할 수 있습니다. 여러 버전을 비교하려면 버전 비교를 클릭합니다. 자세한 내용은 Spanner 버전 개요를 참조하세요.
계속을 클릭합니다.
인스턴스 이름에 인스턴스 이름을 입력합니다(예: test-instance).
인스턴스 ID에서 인스턴스 ID를 그대로 두거나 변경합니다. 인스턴스 ID는 기본적으로 인스턴스 이름으로 설정되지만 변경할 수 있습니다. 인스턴스 이름과 인스턴스 ID는 동일할 수도 있고 다를 수도 있습니다.
계속을 클릭합니다.
구성 선택에서 다음을 수행합니다.
1. 리전은 선택한 상태로 둡니다.
2. 구성 선택에서 리전을 선택합니다. 선택한 리전은 인스턴스가 저장되고 복제되는 장소입니다.
3. 계속을 클릭합니다.
컴퓨팅 용량 구성에서 다음을 수행합니다.
1. 단위 선택에서 처리 단위(PU)를 선택합니다.
2. 확장 모드 선택에서 수동 할당을 선택한 상태로 두고 수량에서 처리 단위를 1,000개로 둡니다.
만들기를 클릭합니다. Google Cloud 콘솔에 생성된 인스턴스의 개요 페이지가 표시됩니다.

데이터베이스 만들기

인스턴스가 실행되면 데이터베이스를 만들 수 있습니다. 데이터베이스에서 스키마를 정의합니다 .

Google Cloud 콘솔에서 Spanner 인스턴스 페이지로 이동합니다.

Spanner 인스턴스로 이동
자신이 만든 인스턴스(예: test-instance)를 클릭합니다.
개요의 인스턴스 이름 아래에서 데이터베이스 만들기를 클릭합니다.
데이터베이스 이름에 데이터베이스 이름을 입력합니다. 예를 들면 example-db입니다.
데이터베이스 언어 선택에서 Google 표준 SQL을 선택합니다.

Spanner 벡터 검색은 PostgreSQL 언어로 사용할 수 없습니다.

다음 스키마를 복사하여 DDL 템플릿 편집기 탭에 붙여넣습니다. 스키마는 Products 테이블을 정의합니다.

  CREATE TABLE products (
    categoryId INT64 NOT NULL,
    productId INT64 NOT NULL,
    productName STRING(MAX) NOT NULL,
    productDescription STRING(MAX) NOT NULL,
    productDescriptionEmbedding ARRAY<FLOAT32>,
    createTime TIMESTAMP NOT NULL OPTIONS (
    allow_commit_timestamp = true
    ), inventoryCount INT64 NOT NULL,
    priceInCents INT64,
  ) PRIMARY KEY(categoryId, productId);

암호화 옵션 표시에서 아무 것도 변경하지 마세요.
만들기를 클릭합니다. Google Cloud 콘솔에 생성된 데이터베이스의 개요 페이지가 표시됩니다.

임베딩 모델 만들기

Spanner에서 CREATE MODEL DDL 문을 사용하면 데이터베이스에서 Vertex AI 모델의 엔드포인트에 대한 참조가 등록됩니다. 모델을 등록한 후 ML.PREDICT 함수를 사용하여 쿼리에서 모델에 액세스할 수 있습니다.

다음 예에서는 Vertex AI 텍스트 임베딩 모델을 등록하는 방법을 보여줍니다. 이 모델은 데이터베이스에서 유사한 제품을 찾는 유사성 검색을 실행하는 데 사용됩니다.

데이터베이스 개요 페이지에서 Spanner 스튜디오를 클릭합니다.
Spanner 스튜디오 페이지에서 새 탭을 클릭하거나 빈 편집기 탭을 사용합니다.

다음을 입력합니다.

CREATE MODEL EmbeddingsModel INPUT(
content STRING(MAX),
) OUTPUT(
embeddings STRUCT<values ARRAY<FLOAT32>>,
) REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/PROJECT_ID/locations/us-central1/publishers/google/models/TEXT_EMBEDDING_MODEL'
);

다음을 바꿉니다.

PROJECT_ID:Google Cloud 프로젝트에 고유한 영구 식별자입니다.
TEXT_EMBEDDING_MODEL: 텍스트 임베딩 모델의 이름입니다. Vertex AI 텍스트 임베딩 모델 목록은 지원되는 모델을 참고하세요.

실행을 클릭하여 모델을 만듭니다.

모델이 성공적으로 추가되면 탐색기 창에 표시됩니다.

데이터 로드

products 테이블에 Cymbal 샘플 데이터를 로드하려면 다음을 실행하세요.

Spanner 스튜디오의 새 탭에서 다음 삽입 문을 복사하여 붙여넣습니다.

INSERT INTO products (categoryId, productId, productName, productDescription, createTime, inventoryCount, priceInCents)
VALUES (1, 1, "Cymbal Helios Helmet", "Safety meets style with the Cymbal children's bike helmet. Its lightweight design, superior ventilation, and adjustable fit ensure comfort and protection on every ride. Stay bright and keep your child safe under the sun with Cymbal Helios!", PENDING_COMMIT_TIMESTAMP(), 100, 10999),
      (1, 2, "Cymbal Sprout", "Let their cycling journey begin with the Cymbal Sprout, the ideal balance bike for beginning riders ages 2-4 years. Its lightweight frame, low seat height, and puncture-proof tires promote stability and confidence as little ones learn to balance and steer. Watch them sprout into cycling enthusiasts with Cymbal Sprout!", PENDING_COMMIT_TIMESTAMP(), 10, 13999),
      (1, 3, "Cymbal Spark Jr.", "Light, vibrant, and ready for adventure, the Spark Jr. is the perfect first bike for young riders (ages 5-8). Its sturdy frame, easy-to-use brakes, and puncture-resistant tires inspire confidence and endless playtime. Let the spark of cycling ignite with Cymbal!", PENDING_COMMIT_TIMESTAMP(), 34, 13900),
      (1, 4, "Cymbal Summit", "Conquering trails is a breeze with the Summit mountain bike. Its lightweight aluminum frame, responsive suspension, and powerful disc brakes provide exceptional control and comfort for experienced bikers navigating rocky climbs or shredding downhill. Reach new heights with Cymbal Summit!", PENDING_COMMIT_TIMESTAMP(), 0, 79999),
      (1, 5, "Cymbal Breeze", "Cruise in style and embrace effortless pedaling with the Breeze electric bike. Its whisper-quiet motor and long-lasting battery let you conquer hills and distances with ease. Enjoy scenic rides, commutes, or errands with a boost of confidence from Cymbal Breeze!", PENDING_COMMIT_TIMESTAMP(), 72, 129999),
      (1, 6, "Cymbal Trailblazer Backpack", "Carry all your essentials in style with the Trailblazer backpack. Its water-resistant material, multiple compartments, and comfortable straps keep your gear organized and accessible, allowing you to focus on the adventure. Blaze new trails with Cymbal Trailblazer!", PENDING_COMMIT_TIMESTAMP(), 24, 7999),
      (1, 7, "Cymbal Phoenix Lights", "See and be seen with the Phoenix bike lights. Powerful LEDs and multiple light modes ensure superior visibility, enhancing your safety and enjoyment during day or night rides. Light up your journey with Cymbal Phoenix!", PENDING_COMMIT_TIMESTAMP(), 87, 3999),
      (1, 8, "Cymbal Windstar Pump", "Flat tires are no match for the Windstar pump. Its compact design, lightweight construction, and high-pressure capacity make inflating tires quick and effortless. Get back on the road in no time with Cymbal Windstar!", PENDING_COMMIT_TIMESTAMP(), 36, 24999),
      (1, 9,"Cymbal Odyssey Multi-Tool","Be prepared for anything with the Odyssey multi-tool. This handy gadget features essential tools like screwdrivers, hex wrenches, and tire levers, keeping you ready for minor repairs and adjustments on the go. Conquer your journey with Cymbal Odyssey!", PENDING_COMMIT_TIMESTAMP(), 52, 999),
      (1, 10,"Cymbal Nomad Water Bottle","Stay hydrated on every ride with the Nomad water bottle. Its sleek design, BPA-free construction, and secure lock lid make it the perfect companion for staying refreshed and motivated throughout your adventures. Hydrate and explore with Cymbal Nomad!", PENDING_COMMIT_TIMESTAMP(), 42, 1299);

실행을 클릭하여 데이터를 삽입합니다.

벡터 임베딩 생성

모델을 등록하고 Spanner에 데이터를 로드한 후 데이터의 제품 설명으로 벡터 임베딩을 생성할 수 있습니다. 벡터 임베딩은 텍스트 데이터를 단어의 의미와 컨텍스트를 포착하는 수치 값으로 변환합니다. 이 변환은 시맨틱 검색을 실행하는 데 중요합니다.

이 단계에서는 ML.PREDICT를 사용하여 productDescription 열에서 임베딩을 생성하여 productDescriptionEmbedding 열을 채웁니다. 이렇게 하면 다음 단계에서 벡터 유사성 검색을 실행할 수 있습니다.

Spanner 스튜디오의 새 탭에서 다음 업데이트 문을 복사하여 붙여넣습니다.

UPDATE products p1
SET productDescriptionEmbedding =
  (SELECT embeddings.values
    FROM ML.PREDICT(MODEL EmbeddingsModel,
      (SELECT p1.productDescription as content)
    )
  )
WHERE categoryId=1;

실행을 클릭하여 임베딩을 생성합니다.

벡터 유사성 검색 수행

다음 예에서는 SQL 쿼리를 사용하여 자연어 검색 요청을 제공합니다. SQL 쿼리는 이전에 생성한 벡터 임베딩을 사용하여 벡터 유사성 검색을 실행합니다. 쿼리는 다음을 실행하여 검색을 수행합니다.

ML.PREDICT를 사용하여 주어진 검색어 ('3세 자녀를 위한 입문용 자전거를 사고 싶어')의 임베딩을 생성합니다.
이 쿼리 삽입과 제품 테이블에 있는 각 제품의 productDescriptionEmbedding 간의 COSINE_DISTANCE를 계산하여 Cymbal 스토어에서 유사한 결과를 찾습니다.
inventoryCount이 0보다 큰 제품만 포함하도록 결과를 필터링합니다.
계산된 거리로 결과를 정렬하고 productName, productDescription, inventoryCount와 함께 가장 가까운 상위 5개 일치 항목을 반환합니다.

Spanner Studio의 새 탭에서 다음 쿼리를 복사하여 붙여넣습니다.

SELECT productName, productDescription, inventoryCount,
  COSINE_DISTANCE(
    productDescriptionEmbedding,
    (
      SELECT embeddings.values
      FROM
        ML.PREDICT(
          MODEL EmbeddingsModel,
          (SELECT "I'd like to buy a starter bike for my 3 year old child" AS content))
    )) AS distance
FROM products
WHERE inventoryCount > 0
ORDER BY distance
LIMIT 5;

실행을 클릭하여 검색 텍스트와 가장 일치하는 제품을 반환합니다.

출력 예시:

/*-----------------+--------------------+----------------+--------------------*
| productName      | productDescription | inventoryCount | distance           |
+------------------+--------------------+----------------+--------------------+
| Cymbal Sprout    | Let their cycling  | 10             | 0.3094387191860244 |
|                  | journey begin with |                |                    |
|                  | the Cymbal Sprout, |                |                    |
|                  | the ideal balance  |                |                    |
|                  | bike for beginning |                |                    |
|                  | riders ages 2-4    |                |                    |
|                  | years...           |                |                    |
| Cymbal Spark Jr  | Light, vibrant,    | 34             | 0.3412342902117166 |
|                  | and ready for      |                |                    |
|                  | adventure, the     |                |                    |
|                  | Spark Jr. is the   |                |                    |
|                  | perfect first bike |                |                    |
|                  | for young riders   |                |                    |
|                  | (ages 5-8)...      |                |                    |
| Cymbal Helios    | Safety meets style | 100            | 0.4197863319656684 |
| Helmet           | with the Cymbal    |                |                    |
|                  | children's bike    |                |                    |
|                  | helmet...          |                |                    |
| Cymbal Breeze    | Cruise in style and| 72             | 0.485231776523978  |
|                  | embrace effortless |                |                    |
|                  | pedaling with the  |                |                    |
|                  | Breeze electric    |                |                    |
|                  | bike...            |                |                    |
| Cymbal Phoenix   | See and be seen    | 87             | 0.525101413779242  |
| Lights           | with the Phoenix   |                |                    |
|                  | bike lights...     |                |                    |
*------------------+--------------------+----------------+--------------------*/

근사 최근접 이웃을 사용하도록 벡터 검색 확장

이전 벡터 검색 예에서는 정확한 K-최근접 이웃 (KNN) 벡터 검색을 사용합니다. KNN 벡터 거리 함수 (코사인 거리, 유클리드 거리, 내적)는 Spanner 데이터의 특정 하위 집합을 쿼리할 수 있는 경우에 유용합니다. KNN 검색은 쿼리 벡터와 데이터베이스의 모든 벡터 간의 정확한 거리를 계산하므로 데이터를 파티셔닝할 수 있는 경우 효율적입니다. 쿼리에서 특정 필터 없이 데이터베이스의 모든 벡터를 쿼리 벡터와 비교해야 하고 쿼리를 독립적인 하위 쿼리로 나눌 수 없는 경우 KNN을 사용하면 성능 병목 현상이 발생할 수 있습니다. 이러한 상황에서는 근사 최근접 이웃 (ANN) 벡터 검색이 유용합니다. 자세한 내용은 근사 최근접 이웃 찾기를 참고하세요.

워크로드를 파티셔닝할 수 없고 데이터가 많은 경우 ANN 벡터 검색을 사용하여 대규모 데이터 세트의 쿼리 성능을 높일 수 있습니다.

Spanner에서 ANN 벡터 검색을 확장하고 사용하려면 다음 단계를 따르세요.

벡터 색인 만들기
ANN 거리 함수를 사용하도록 쿼리 수정

벡터 색인 만들기

Spanner는 Google Research의 확장 가능한 최근접 이웃 (ScaNN)을 활용하는 특수한 벡터 색인을 사용하여 ANN 벡터 검색 시간을 단축합니다.

데이터 세트에서 벡터 색인을 만들려면 productDescriptionEmbeddings 열을 수정하여 vector_length 주석을 정의해야 합니다. vector_length 주석은 각 벡터의 차원을 나타냅니다. 다음 DDL 문은 productDescriptionEmbedding 열을 삭제하고 vector_length로 다시 만듭니다. 벡터의 최대 길이 (차원)는 선택한 임베딩 모델에 따라 달라집니다.

Spanner Studio의 새 탭에서 다음 DDL 문을 복사하여 붙여넣어 productDescriptionEmbedding 열을 다시 만듭니다.
```
ALTER TABLE products DROP COLUMN productDescriptionEmbedding;
ALTER TABLE products
  ADD COLUMN productDescriptionEmbedding ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH_VALUE);
```
VECTOR_LENGTH_VALUE을 선택한 삽입 모델의 최대 출력 차원으로 바꿉니다.
실행을 클릭합니다.

다음 삽입 문을 복사하여 붙여넣어 벡터 삽입을 다시 생성합니다.

UPDATE products p1
SET productDescriptionEmbedding =
(SELECT embeddings.values from ML.PREDICT(MODEL EmbeddingsModel,
(SELECT p1.productDescription as content)))
WHERE categoryId=1;

실행을 클릭합니다.

다음 DDL 문을 복사하여 붙여넣어 벡터 색인을 만듭니다.

CREATE VECTOR INDEX ProductDescriptionEmbeddingIndex
    ON products(productDescriptionEmbedding)
    WHERE productDescriptionEmbedding IS NOT NULL
OPTIONS (
distance_type = 'COSINE'
);

실행을 클릭합니다.

ANN 벡터 거리 함수 사용

Spanner에서 ANN 벡터 검색을 사용하려면 SQL 쿼리에서 다음을 수정하세요.

SQL 쿼리 내에서가 아닌 별도로 프롬프트 임베딩을 생성합니다.
삽입 결과를 쿼리에 복사합니다.
FORCE_INDEX 힌트를 사용하여 새 벡터 색인을 참조합니다. @{force_index=ProductDescriptionEmbeddingIndex}
COSINE_DISTANCE 대신 APPROX_COSINE_DISTANCE 벡터 거리 함수를 사용합니다. JSON '{"num_leaves_to_search": num_leaves}' 옵션은 필수입니다.

Spanner Studio의 새 탭에서 다음 쿼리를 복사하여 붙여넣어 프롬프트 삽입을 생성합니다.

-- Generate the prompt embedding
SELECT embeddings.values
FROM ML.PREDICT(
  MODEL EmbeddingsModel,
  (SELECT "I'd like to buy a starter bike for my 3 year old child" as content)
  );

실행을 클릭합니다.
embeddings.values 결과를 복사합니다.

다음 쿼리에서 embedding을 이전 단계에서 복사한 삽입 결과로 바꿉니다.

-- Update embedding query using the vector index
SELECT productName, productDescription, inventoryCount,
  (APPROX_COSINE_DISTANCE(productDescriptionEmbedding,
  array<float32>[embedding],
  options => JSON '{\"num_leaves_to_search\": 10}')) as distance
FROM products @{force_index=ProductDescriptionEmbeddingIndex}
WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0
ORDER BY distance
LIMIT 5;

새 SQL 쿼리는 다음과 유사합니다.

SELECT productName, productDescription, count,
  (APPROX_COSINE_DISTANCE(productDescriptionEmbedding,
    array<float32>[-0.00457216799,-0.0771846101,-0.0319350846,0.0352052487,-0.0457422845,0.0183265656...],
    options => JSON '{\"num_leaves_to_search\": 10}')) as distance
FROM products @{force_index=ProductDescriptionEmbeddingIndex}
WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0
ORDER BY distance
LIMIT 5;