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

google_bigquery_connection 리소스를 사용합니다.

참고: Terraform을 사용해서 BigQuery 객체를 만들려면 Cloud Resource Manager API를 사용 설정해야 합니다.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

다음 예에서는 US 리전에 my_cloud_resource_connection라는 Cloud 리소스 연결을 만듭니다.

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Google Cloud 프로젝트에 Terraform 구성을 적용하려면 다음 섹션의 단계를 완료하세요.

Cloud Shell 준비

1. Cloud Shell을 실행합니다.

2. Terraform 구성을 적용할 기본 Google Cloud 프로젝트를 설정합니다.

   이 명령어는 프로젝트당 한 번만 실행하면 되며 어떤 디렉터리에서도 실행할 수 있습니다.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Terraform 구성 파일에서 명시적 값을 설정하면 환경 변수가 재정의됩니다.

디렉터리 준비

각 Terraform 구성 파일에는 자체 디렉터리(루트 모듈이라고도 함)가 있어야 합니다.

1. Cloud Shell에서 디렉터리를 만들고 해당 디렉터리 내에 새 파일을 만드세요. 파일 이름에는 .tf 확장자가 있어야 합니다(예: main.tf). 이 튜토리얼에서는 파일을 main.tf라고 합니다.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 튜토리얼을 따라 하는 경우 각 섹션이나 단계에서 샘플 코드를 복사할 수 있습니다.

   샘플 코드를 새로 만든 main.tf에 복사합니다.

   필요한 경우 GitHub에서 코드를 복사합니다. 이는 Terraform 스니펫이 엔드 투 엔드 솔루션의 일부인 경우에 권장됩니다.

3. 환경에 적용할 샘플 매개변수를 검토하고 수정합니다.
4. 변경사항을 저장합니다.
5. Terraform을 초기화합니다. 이 작업은 디렉터리당 한 번만 수행하면 됩니다.

   terraform init

   원하는 경우 최신 Google 공급업체 버전을 사용하려면 -upgrade 옵션을 포함합니다.

   terraform init -upgrade

변경사항 적용

1. 구성을 검토하고 Terraform에서 만들거나 업데이트할 리소스가 예상과 일치하는지 확인합니다.

   terraform plan

   필요에 따라 구성을 수정합니다.

2. 다음 명령어를 실행하고 프롬프트에 yes를 입력하여 Terraform 구성을 적용합니다.

   terraform apply

   Terraform에 '적용 완료' 메시지가 표시될 때까지 기다립니다.

3. 결과를 보려면 Google Cloud 프로젝트를 엽니다. Google Cloud 콘솔에서 UI의 리소스로 이동하여 Terraform이 리소스를 만들었거나 업데이트했는지 확인합니다.

참고: Terraform 샘플은 일반적으로 필요한 API가 Google Cloud 프로젝트에서 사용 설정되었다고 가정합니다.

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

연결의 서비스 계정에 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: 사용할 임베딩 모델의 이름입니다. text-embedding, text-multilingual-embedding 또는 multimodalembedding 모델이어야 합니다. 지원되는 모델 버전 및 별칭에 관한 자세한 내용은 ENDPOINT를 참고하세요.
   중요: 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       |
+------------------------------------------+----------------------------+