ML.GENERATE_EMBEDDING 함수를 사용하여 텍스트 임베딩 생성

이 문서에서는 Vertex AI 임베딩 모델을 참조하는 BigQuery ML 원격 모델을 만드는 방법을 설명합니다. 그런 다음 이 모델을 ML.GENERATE_EMBEDDING 함수와 함께 사용하여 BigQuery 표준 테이블의 데이터를 사용해서 텍스트 임베딩을 만듭니다.

필요한 역할

• 연결을 만들려면 다음 Identity and Access Management(IAM) 역할에 멤버십이 필요합니다.

  • roles/bigquery.connectionAdmin

• 연결의 서비스 계정에 권한을 부여하려면 다음 권한이 필요합니다.

  • resourcemanager.projects.setIamPolicy

• BigQuery ML을 사용하여 모델을 만들려면 다음 IAM 권한이 필요합니다.

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

• 추론을 실행하려면 다음 권한이 필요합니다.

  • 테이블에 대한 bigquery.tables.getData
  • 모델에 대한 bigquery.models.getData
  • bigquery.jobs.create

시작하기 전에

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Make sure that billing is enabled for your Google Cloud project.

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

데이터 세트 생성

ML 모델을 저장할 BigQuery 데이터 세트를 만듭니다.

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

   BigQuery 페이지로 이동

2. 탐색기 창에서 프로젝트 이름을 클릭합니다.

3. 작업 보기 > 데이터 세트 만들기를 클릭합니다.

   

4. 데이터 세트 만들기 페이지에서 다음을 수행합니다.

   • 데이터 세트 ID에 bqml_tutorial를 입력합니다.

   • 위치 유형에 대해 멀티 리전을 선택한 다음 US(미국 내 여러 리전)를 선택합니다.

     공개 데이터 세트는 US 멀티 리전에 저장됩니다. 편의상 같은 위치에 데이터 세트를 저장합니다.

   • 나머지 기본 설정은 그대로 두고 데이터 세트 만들기를 클릭합니다.

     

연결 만들기

클라우드 리소스 연결을 만들고 연결의 서비스 계정을 가져옵니다. 이전 단계에서 만든 데이터 세트와 동일한 위치에 연결을 만듭니다.

다음 옵션 중 하나를 선택합니다.

콘솔

1. BigQuery 페이지로 이동합니다.

   BigQuery로 이동

2. 연결을 만들려면 추가를 클릭한 다음 외부 데이터 소스에 연결을 클릭합니다.

3. 연결 유형 목록에서 Vertex AI 원격 모델, 원격 함수, BigLake(Cloud 리소스)를 선택합니다.

4. 연결 ID 필드에 연결 이름을 입력합니다.

5. 연결 만들기를 클릭합니다.

6. 연결로 이동을 클릭합니다.

7. 연결 정보 창에서 나중의 단계에 사용할 서비스 계정 ID를 복사합니다.

bq

1. 명령줄 환경에서 연결을 만듭니다.

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   --project_id 매개변수는 기본 프로젝트를 재정의합니다.

   다음을 바꿉니다.

   • REGION: 연결 리전
   • PROJECT_ID: Google Cloud 프로젝트 ID
   • CONNECTION_ID: 연결의 ID

   연결 리소스를 만들면 BigQuery가 고유한 시스템 서비스 계정을 만들고 이를 연결에 연계합니다.

   문제 해결: 다음 연결 오류가 발생하면 Google Cloud SDK를 업데이트하세요.

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. 이후 단계에서 사용할 수 있도록 서비스 계정 ID를 가져와 복사합니다.

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   출력은 다음과 비슷합니다.

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

main.tf 파일에 다음 섹션을 추가합니다.

 ## This creates a cloud resource connection.
 ## Note: The cloud resource nested object has only one output only field - serviceAccountId.
 resource "google_bigquery_connection" "connection" {
    connection_id = "CONNECTION_ID"
    project = "PROJECT_ID"
    location = "REGION"
    cloud_resource {}
}        

다음을 바꿉니다.

• CONNECTION_ID: 연결의 ID
• PROJECT_ID: Google Cloud 프로젝트 ID
• REGION: 연결 리전

서비스 계정에 액세스 권한 부여

연결의 서비스 계정에 Vertex AI 사용자 역할을 부여합니다.

원격 모델을 만들 때 엔드포인트를 URL(예: endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-004')로 지정할 계획이라면 URL에 지정한 동일한 프로젝트에서 이 역할을 부여합니다.

원격 모델을 만들 때 모델 이름을 사용(예: endpoint = 'text-embedding-004')하여 엔드포인트를 지정할 계획이라면 원격 모델을 만들려는 동일한 프로젝트에서 이 역할을 부여합니다.

다른 프로젝트에서 역할을 부여하면 [e-mail] does not have the permission to access resource 오류가 발생합니다.

역할을 부여하려면 다음 단계를 따르세요.

콘솔

1. IAM 및 관리자 페이지로 이동합니다.

   IAM 및 관리자로 이동

2. 액세스 권한 부여를 클릭합니다.

   주 구성원 추가 대화상자가 열립니다.

3. 새 주 구성원 필드에 앞에서 복사한 서비스 계정 ID를 입력합니다.

4. 역할 선택 필드에서 Vertex AI를 선택한 후 Vertex AI 사용자를 선택합니다.

5. 저장을 클릭합니다.

gcloud

gcloud projects add-iam-policy-binding 명령어를 사용합니다.

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

다음을 바꿉니다.

• PROJECT_NUMBER: 프로젝트 번호
• MEMBER: 이전에 복사한 서비스 계정 ID

모델 만들기

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

   BigQuery로 이동

2. SQL 편집기를 사용하여 원격 모델을 만듭니다.

   CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION `CONNECTION_ID`
   OPTIONS (ENDPOINT = 'ENDPOINT');

   다음을 바꿉니다.

   • PROJECT_ID: 프로젝트 ID입니다.
   • DATASET_ID: 모델을 포함할 데이터 세트의 ID
   • MODEL_NAME: 모델의 이름
   • CONNECTION_ID: BigQuery 연결의 ID

     Google Cloud 콘솔에서 연결 세부정보를 열람할 때 이는 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값입니다(예: projects/myproject/locations/connection_location/connections/myconnection).

   • ENDPOINT: 사용할 임베딩 model입니다.
   중요: textembedding-gecko@002 모델에 대한 BigQuery ML 지원은 단계적으로 중단됩니다. 이 모델을 사용하는 원격 모델이 있는 경우 가능한 한 빨리 text-embedding-004 모델 또는 다른 지원되는 모델 버전으로 마이그레이션하세요.

테이블의 데이터를 사용하여 텍스트 임베딩 생성

테이블 열의 텍스트 데이터를 사용하여 ML.GENERATE_EMBEDDING 함수로 텍스트 임베딩을 생성합니다.

일반적으로 텍스트 전용 사용 사례에는 text-embedding 또는 text-multilingual-embedding 모델을 사용하고 교차 모달 검색 사용 사례에는 multimodalembedding 모델을 사용합니다. 여기서 텍스트 및 시각적 콘텐츠의 임베딩은 동일한 시맨틱 공간에서 생성됩니다.

텍스트 임베딩

임베딩 모델을 통해 원격 모델을 사용하여 텍스트 임베딩을 생성합니다.

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DATASET_ID: 모델이 포함된 데이터 세트의 ID
• MODEL_NAME: 임베딩 모델을 통한 원격 모델의 이름
• TABLE_NAME: 삽입할 텍스트가 포함된 테이블의 이름. 이 테이블에는 이름이 content인 열이 있어야 합니다. 또는 별칭을 사용하여 다른 이름의 열을 사용할 수 있습니다.
• FLATTEN_JSON: 임베딩을 별도의 열로 파싱할지 여부를 나타내는 BOOL 값. 기본값은 TRUE입니다.
• TASK_TYPE: 모델이 더 나은 품질의 임베딩을 생성할 수 있도록 의도된 다운스트림 애플리케이션을 지정하는 STRING 리터럴. TASK_TYPE은 다음 값을 허용합니다.
  • RETRIEVAL_QUERY: 지정된 텍스트가 검색 또는 가져오기 설정의 쿼리임을 지정
  • RETRIEVAL_DOCUMENT: 지정된 텍스트가 검색 또는 가져오기 설정의 문서임을 지정

    이 태스크 유형을 사용할 때 임베딩 품질을 개선하기 위해 쿼리 문에 문서 제목을 포함하면 유용합니다. title 옵션을 사용해 문서 제목이 포함된 열의 이름을 지정할 수 있습니다. 그렇지 않으면 문서 제목은 title 또는 별칭이 title로 지정된 열에 있어야 합니다 예를 들면 다음과 같습니다.

          SELECT *
          FROM
            ML.GENERATE_EMBEDDING(
              MODEL mydataset.embedding_model,
              (SELECT abstract as content, header as title, publication_number
              FROM mydataset.publications),
              STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
          );
          

  • SEMANTIC_SIMILARITY: 지정된 텍스트를 시맨틱 텍스트 유사성(STS)에 사용하도록 지정
  • CLASSIFICATION: 임베딩이 분류에 사용되도록 지정
  • CLUSTERING: 클러스터링에 임베딩을 사용하도록 지정
• OUTPUT_DIMENSIONALITY: 임베딩을 생성할 때 사용할 차원 수를 지정하는 INT64 값입니다. 예를 들어 256 AS output_dimensionality를 지정하면 ml_generate_embedding_result 출력 열에 각 입력 값에 대한 임베딩이 256개 포함됩니다.

  model 인수에 지정하는 원격 모델에서 다음 모델 중 하나를 엔드포인트로 사용하는 경우에만 이 인수를 사용할 수 있습니다.

  • text-embedding-004 이상
  • text-multilingual-embedding-002 이상

멀티모달 임베딩

multimodalembedding 모델을 통해 원격 모델을 사용하여 텍스트 임베딩을 생성합니다.

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output，
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DATASET_ID: 모델이 포함된 데이터 세트의 ID
• MODEL_NAME: multimodalembedding@001 모델에 대한 원격 모델의 이름
• TABLE_NAME: 삽입할 텍스트가 포함된 테이블의 이름. 이 테이블에는 이름이 content인 열이 있어야 합니다. 또는 별칭을 사용하여 다른 이름의 열을 사용할 수 있습니다.
• FLATTEN_JSON: 임베딩을 별도의 열로 파싱할지 여부를 나타내는 BOOL. 기본값은 TRUE입니다.
• OUTPUT_DIMENSIONALITY: 임베딩을 생성할 때 사용할 차원 수를 지정하는 INT64 값입니다. 유효한 값은 128, 256, 512, 1408입니다. 기본값은 1408입니다. 예를 들어 256 AS output_dimensionality를 지정하면 ml_generate_embedding_result 출력 열에 각 입력 값에 대한 임베딩이 256개 포함됩니다.

쿼리의 데이터를 사용하여 텍스트 임베딩 생성

또는 임베딩 모델을 통해 쿼리 및 원격 모델로 제공된 텍스트 데이터를 사용하여 ML.GENERATE_EMBEDDING 함수로 텍스트 임베딩을 생성합니다.

일반적으로 텍스트 전용 사용 사례에는 text-embedding 또는 text-multilingual-embedding 모델을 사용하고 교차 모달 검색 사용 사례에는 multimodalembedding 모델을 사용합니다. 여기서 텍스트 및 시각적 콘텐츠의 임베딩은 동일한 시맨틱 공간에서 생성됩니다.

텍스트 임베딩

또는 임베딩 모델을 통해 원격 모델을 사용하여 텍스트 임베딩을 생성합니다.

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DATASET_ID: 모델이 포함된 데이터 세트의 ID
• MODEL_NAME: 임베딩 모델을 통한 원격 모델의 이름
• CONTENT_QUERY: 결과에 content라는 STRING 열이 포함된 쿼리
• FLATTEN_JSON: 임베딩을 별도의 열로 파싱할지 여부를 나타내는 BOOL 값. 기본값은 TRUE입니다.
• TASK_TYPE: 모델이 더 나은 품질의 임베딩을 생성할 수 있도록 의도된 다운스트림 애플리케이션을 지정하는 STRING 리터럴. TASK_TYPE은 다음 값을 허용합니다.
  • RETRIEVAL_QUERY: 지정된 텍스트가 검색 또는 가져오기 설정의 쿼리임을 지정
  • RETRIEVAL_DOCUMENT: 지정된 텍스트가 검색 또는 가져오기 설정의 문서임을 지정

    이 태스크 유형을 사용할 때 임베딩 품질을 개선하기 위해 쿼리 문에 문서 제목을 포함하면 유용합니다. title 옵션을 사용해 문서 제목이 포함된 열의 이름을 지정할 수 있습니다. 그렇지 않으면 문서 제목은 title 또는 별칭이 title로 지정된 열에 있어야 합니다 예를 들면 다음과 같습니다.

              SELECT *
              FROM
                ML.GENERATE_EMBEDDING(
                  MODEL mydataset.embedding_model,
                  (SELECT abstract as content, header as title, publication_number
                  FROM mydataset.publications),
                  STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
              );
              

  • SEMANTIC_SIMILARITY: 지정된 텍스트를 시맨틱 텍스트 유사성(STS)에 사용하도록 지정
  • CLASSIFICATION: 임베딩이 분류에 사용되도록 지정
  • CLUSTERING: 클러스터링에 임베딩을 사용하도록 지정
• OUTPUT_DIMENSIONALITY: 임베딩을 생성할 때 사용할 차원 수를 지정하는 INT64 값입니다. 예를 들어 256 AS output_dimensionality를 지정하면 ml_generate_embedding_result 출력 열에 각 입력 값에 대한 임베딩이 256개 포함됩니다.

  model 인수에 지정하는 원격 모델에서 다음 모델 중 하나를 엔드포인트로 사용하는 경우에만 이 인수를 사용할 수 있습니다.

  • text-embedding-004 이상
  • text-multilingual-embedding-002 이상

멀티모달 임베딩

multimodalembedding 모델을 통해 원격 모델을 사용하여 텍스트 임베딩을 생성합니다.

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output,
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DATASET_ID: 모델이 포함된 데이터 세트의 ID
• MODEL_NAME: multimodalembedding@001 모델에 대한 원격 모델의 이름
• CONTENT_QUERY: 결과에 content라는 STRING 열이 포함된 쿼리
• FLATTEN_JSON: 임베딩을 별도의 열로 파싱할지 여부를 나타내는 BOOL. 기본값은 TRUE입니다.
• OUTPUT_DIMENSIONALITY: 임베딩을 생성할 때 사용할 차원 수를 지정하는 INT64 값입니다. 유효한 값은 128, 256, 512, 1408입니다. 기본값은 1408입니다. 예를 들어 256 AS output_dimensionality를 지정하면 ml_generate_embedding_result 출력 열에 각 입력 값에 대한 임베딩이 256개 포함됩니다.

예시

다음 예시에서는 테이블 및 쿼리에서 ML.GENERATE_EMBEDDING 함수를 호출하는 방법을 보여줍니다.

테이블에 텍스트 삽입

다음 예시에서는 text_data 테이블의 content 열을 삽입하는 요청을 보여줍니다.

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE mydataset.text_data,
    STRUCT(TRUE AS flatten_json_output, 'CLASSIFICATION' AS task_type)
  );

임베딩을 사용하여 시맨틱 유사성 순위 지정

다음 예시에서는 영화 리뷰 컬렉션을 삽입하고 ML.DISTANCE 함수를 사용하여 '이 영화는 평균입니다'라는 리뷰의 코사인 거리를 기준으로 이를 정렬합니다. 거리가 짧을수록 시맨틱 유사성이 높습니다.

WITH movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "Movie 1" AS title, "This movie was fantastic" AS content
        UNION ALL
        SELECT "Movie 2" AS title, "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "Movie 3" AS title, "This movie was just okay..." AS content
        UNION ALL
        SELECT "Movie 4" AS title, "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
),
average_review_embedding AS (
  SELECT ml_generate_embedding_result
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content),
      STRUCT(TRUE AS flatten_json_output)
    )
)
SELECT
  content,
  ML.DISTANCE(
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    ml_generate_embedding_result,
    'COSINE'
  ) AS distance_to_average_review
FROM
  movie_review_embeddings
ORDER BY distance_to_average_review;

결과는 다음과 같습니다.

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+