Vertex AI와 Cloud SQL 통합

이 페이지에서는 Cloud SQL을 Vertex AI와 통합하는 방법을 설명합니다. 이 통합을 통해 Vertex AI에서 호스팅되는 대규모 언어 모델(LLM)을 PostgreSQL용 Cloud SQL 데이터베이스 버전 12 이상에 적용할 수 있습니다.

Cloud SQL을 Vertex AI와 통합하면 머신러닝(ML) 모델의 시맨틱 및 예측 성능을 데이터에 적용할 수 있습니다. 이 통합은 모델 쿼리를 위한 두 가지 함수를 사용하여 PostgreSQL 구문을 확장합니다.

  • 트랜잭션 내에서 SQL을 사용하여 모델을 호출하려면 예측을 호출합니다.
  • LLM이 텍스트 프롬프트를 숫자 벡터로 변환하도록 임베딩을 생성합니다. 그런 다음 이러한 벡터 임베딩을 pgvector 함수의 입력으로 적용할 수 있습니다. 여기에는 상대적 시맨틱 거리에 따라 텍스트 샘플을 비교하고 정렬하는 메서드가 포함됩니다.

따라서 실시간 예측을 수행하고 데이터베이스 내에서 직접 유용한 정보를 얻을 수 있으므로 워크플로를 간소화하고 의사 결정 능력을 향상시킬 수 있습니다.

Vertex AI에 대한 자세한 내용은 Vertex AI 소개를 참조하세요.

시작하기 전에

  1. Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

  2. Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기로 이동

  3. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  4. Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기로 이동

  5. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  6. 필요한 Google Cloud API를 사용 설정합니다.

    Console

    1. API 및 서비스 페이지로 이동합니다.
    2. 프로젝트 목록에서 프로젝트를 선택합니다.
    3. API 라이브러리가 열려 있지 않으면 탐색 메뉴에서 라이브러리를 선택합니다.

    4. 사용 설정할 API를 클릭합니다. 이 절차에서는 Cloud SQL Admin API 및 Vertex AI API를 사용 설정합니다.

    5. 각 API를 선택한 후 사용 설정을 클릭합니다.

    gcloud

    1. Cloud Shell을 열면 브라우저에서 직접 명령줄을 통해 Google Cloud 리소스에 액세스할 수 있습니다.
    2. 필요한 API를 사용 설정하려면 gcloud services enable 명령어를 사용합니다. 
      gcloud services enable sqladmin.googleapis.com \
enable aiplatform.googleapis.com
      3. 이 명령어는 다음 API를 사용 설정합니다.
      • Cloud SQL Admin API
      • Vertex AI API

  7. Cloud SQL 서비스 계정에 Vertex AI에 액세스할 수 있는 Identity and Access Management(IAM) 권한을 부여합니다.

    gcloud

    Cloud SQL 인스턴스가 있는 프로젝트의 Cloud SQL 서비스 계정에 Vertex AI 권한을 추가하려면 gcloud projects add-iam-policy-binding 명령어를 사용합니다. 

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/aiplatform.user"

    다음을 바꿉니다.
    • PROJECT_ID: Vertex AI 엔드포인트가 있는 프로젝트의 ID입니다. Cloud SQL은 이 엔드포인트를 사용하여 Vertex AI에 호스팅되는 LLM에 액세스합니다.

    • SERVICE_ACCOUNT_EMAIL: Cloud SQL 서비스 계정의 이메일 주소입니다.

      이 이메일 주소를 찾으려면 gcloud sql instances describe INSTANCE_NAME 명령어를 사용하고 INSTANCE_NAME을 Cloud SQL 인스턴스의 이름으로 바꿉니다. serviceAccountEmailAddress 매개변수 옆에 표시되는 값은 이메일 주소입니다.

Vertex AI와 데이터베이스 통합 사용 설정

Vertex AI와 데이터베이스 통합을 사용 설정하려면 다음 단계를 완료하세요.

  1. 인스턴스를 Vertex AI와 통합할 수 있도록 Cloud SQL 인스턴스를 만들거나 업데이트합니다.

    gcloud

    인스턴스 만들기

    Cloud SQL 인스턴스를 만들려면 gcloud sql instances create 명령어를 사용합니다.

    gcloud sql instances create INSTANCE_NAME \
--database-version=DATABASE_VERSION \
--tier=MACHINE_TYPE \
--region=REGION_NAME \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on

    다음을 바꿉니다.

    • INSTANCE_NAME: 인스턴스 이름
    • DATABASE_VERSION: 인스턴스의 데이터베이스 버전(예: POSTGRES_13)
    • MACHINE_TYPE: 인스턴스의 머신 유형
    • REGION_NAME: 인스턴스의 리전 이름

    인스턴스 업데이트

    인스턴스를 업데이트하려면 gcloud sql instances patch 명령어를 사용합니다.

    gcloud sql instances patch INSTANCE_NAME \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on

    이 업데이트로 인해 재시작이 필요한 값이 수정되면 변경을 진행하거나 취소하라는 메시지가 표시됩니다.

    REST v1

    인스턴스 만들기

    이 예시를 사용하여 인스턴스를 만듭니다. 이 호출의 전체 매개변수 목록은 instances:insert 페이지를 참조하세요. 리전에 따른 유효값을 포함한 인스턴스 설정에 대한 자세한 내용은 인스턴스 설정을 참조하세요.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • PROJECT_ID: 인스턴스가 포함된 Google Cloud 프로젝트의 ID 또는 프로젝트 번호
    • INSTANCE_NAME: 인스턴스 이름
    • REGION_NAME: 인스턴스의 리전 이름
    • DATABASE_VERSION: 데이터베이스 버전의 열거형 문자열(예: POSTGRES_13)
    • PASSWORD: root 사용자의 비밀번호
    • MACHINE_TYPE : db-custom-[CPUS]-[MEMORY_MBS]와 같은 머신(등급) 유형의 열거형 문자열입니다.
    • EDITION_TYPE: Cloud SQL 버전

    또한 요청에 enableGoogleMlIntegration 객체를 포함해야 합니다. 필요에 따라 다음 매개변수를 설정합니다.

    • enableGoogleMlIntegration: 이 매개변수가 true로 설정되면 Cloud SQL 인스턴스가 Vertex AI에 연결하여 실시간 예측 및 통계 요청을 AI에 전달할 수 있습니다.
    • cloudsql.enable_google_ml_integration: 이 매개변수가 on으로 설정되면 Cloud SQL이 Vertex AI와 통합될 수 있습니다.

    HTTP 메서드 및 URL: 

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

    JSON 요청 본문:

    {
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableGoogleMlIntegration": "true" | "false"
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on" | "off"
      }
  }
}

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    다음과 비슷한 JSON 응답이 표시됩니다.

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[email protected]",
  "insertTime": "2019-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    인스턴스 업데이트

    이 예시를 사용하여 인스턴스를 업데이트합니다. 이 호출의 전체 매개변수 목록은 instances.patch 페이지를 참조하세요.

    이 업데이트로 인해 재시작이 필요한 값이 수정되면 변경을 진행하거나 취소하라는 메시지가 표시됩니다.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • PROJECT_ID: 인스턴스가 포함된 Google Cloud 프로젝트의 ID 또는 프로젝트 번호
    • INSTANCE_NAME: 인스턴스 이름

    HTTP 메서드 및 URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    JSON 요청 본문:

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on"
      }
   }
}

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    다음과 비슷한 JSON 응답이 표시됩니다.

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "[email protected]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    REST v1beta4

    인스턴스 만들기

    이 예시를 사용하여 인스턴스를 만듭니다. 이 호출의 전체 매개변수 목록은 instances:insert 페이지를 참조하세요. 리전에 따른 유효값을 포함한 인스턴스 설정에 대한 자세한 내용은 인스턴스 설정을 참조하세요.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • PROJECT_ID: 인스턴스가 포함된 Google Cloud 프로젝트의 ID 또는 프로젝트 번호
    • INSTANCE_NAME: 인스턴스 이름
    • REGION_NAME: 인스턴스의 리전 이름
    • DATABASE_VERSION: 데이터베이스 버전의 열거형 문자열(예: POSTGRES_13)
    • PASSWORD: root 사용자의 비밀번호
    • MACHINE_TYPE : db-custom-[CPUS]-[MEMORY_MBS]와 같은 머신(등급) 유형의 열거형 문자열입니다.
    • EDITION_TYPE: Cloud SQL 버전

    또한 요청에 enableGoogleMlIntegration 객체를 포함해야 합니다. 필요에 따라 다음 매개변수를 설정합니다.

    • enableGoogleMlIntegration: 이 매개변수가 true로 설정되면 Cloud SQL 인스턴스가 Vertex AI에 연결하여 실시간 예측 및 통계 요청을 AI에 전달할 수 있습니다.
    • cloudsql.enable_google_ml_integration: 이 매개변수가 on으로 설정되면 Cloud SQL이 Vertex AI와 통합될 수 있습니다.

    HTTP 메서드 및 URL: 

    POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

    JSON 요청 본문:

    {
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableGoogleMlIntegration": "true" | "false"
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on" | "off"
      }
  }
}

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    다음과 비슷한 JSON 응답이 표시됩니다.

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[email protected]",
  "insertTime": "2019-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    인스턴스 업데이트

    이 예시를 사용하여 인스턴스를 업데이트합니다. 이 호출의 전체 매개변수 목록은 instances.patch 페이지를 참조하세요.

    이 업데이트로 인해 재시작이 필요한 값이 수정되면 변경을 진행하거나 취소하라는 메시지가 표시됩니다.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • PROJECT_ID: 인스턴스가 포함된 Google Cloud 프로젝트의 ID 또는 프로젝트 번호
    • INSTANCE_NAME: 인스턴스 이름

    HTTP 메서드 및 URL: 

    PATCH https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

    JSON 요청 본문:

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on"
      }
   }
}

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    다음과 비슷한 JSON 응답이 표시됩니다.

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "[email protected]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}
  2. 기본 Cloud SQL 인스턴스의 데이터베이스에 google_ml_integration 확장 프로그램을 설치합니다. 이 데이터베이스에는 예측을 실행할 데이터가 포함됩니다.
    1. psql 클라이언트를 사용하여 연결에 설명된 대로 psql 클라이언트를 기본 인스턴스에 연결합니다.
    2. psql 명령 프롬프트에서 데이터베이스에 연결합니다. 
      \c DB_NAME

      DB_NAME을 확장 프로그램을 설치할 데이터베이스의 이름으로 바꿉니다.

    3. 확장 프로그램을 설치합니다. 
      CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;

문제 해결

이 섹션에는 Cloud SQL과 Vertex AI의 통합과 관련된 문제에 대한 정보와 문제 해결 단계가 포함되어 있습니다.

문제 문제 해결
오류 메시지: Google ML integration API is supported only on Postgres version 12 or above. Cloud SQL에서 Vertex AI 통합을 사용 설정하려면 PostgreSQL용 Cloud SQL 데이터베이스 버전 12 이상이 필요합니다. 데이터베이스를 이 버전으로 업그레이드하려면 데이터베이스 주 버전 인플레이스 업그레이드를 참조하세요.
오류 메시지: Google ML Integration API is not supported on shared core instance. Please upsize your machine type. 인스턴스의 머신 유형에 공유 코어를 선택한 경우 Cloud SQL에서 Vertex AI 통합을 사용 설정할 수 없습니다. 머신 유형을 전용 코어로 업그레이드합니다. 자세한 내용은 머신 유형을 참조하세요.
오류 메시지: Google ML Integration is unsupported for this maintenance version. Please follow https://cloud.google.com/sql/docs/postgres/self-service-maintenance to update the maintenance version of the instance. Cloud SQL에서 Vertex AI 통합을 사용 설정하려면 인스턴스의 유지보수 버전이 R20240130 이상이어야 합니다. 인스턴스를 이 버전으로 업그레이드하려면 셀프서비스 유지보수를 참조하세요.
오류 메시지: Cannot invoke ml_predict_row if 'cloudsql.enable_google_ml_integration' is off. cloudsql.enable_google_ml_integration 데이터베이스 플래그가 사용 중지됩니다. Cloud SQL은 Vertex AI와 통합할 수 없습니다.

이 플래그를 사용 설정하려면 gcloud sql instances patch 명령어를 사용합니다.

gcloud sql instances patch INSTANCE_NAME --database-flags cloudsql.enable_google_ml_integration=on

INSTANCE_NAME을 기본 Cloud SQL 인스턴스의 이름으로 바꿉니다.
오류 메시지: Failed to connect to remote host: Connection refused. Cloud SQL과 Vertex AI 간의 통합이 사용 설정되지 않습니다. 이 통합을 사용 설정하려면 gcloud sql instances patch 명령어를 사용합니다.

gcloud sql instances patch INSTANCE_NAME
--enable-google-ml-integration

INSTANCE_NAME을 기본 Cloud SQL 인스턴스의 이름으로 바꿉니다.
오류 메시지: Vertex AI API has not been used in project PROJECT_ID before or it is disabled. Enable it by visiting /apis/api/aiplatform.googleapis.com/overview?project=PROJECT_ID then retry. Vertex AI API가 사용 설정되지 않습니다. 이 API 사용 설정에 대한 자세한 내용은 Vertex AI와 데이터베이스 통합 사용 설정을 참조하세요.
오류 메시지: Permission 'aiplatform.endpoints.predict' denied on resource. Vertex AI 권한은 Cloud SQL 인스턴스가 있는 프로젝트의 Cloud SQL 서비스 계정에 추가되지 않습니다. 서비스 계정에 이러한 권한을 추가하는 방법에 대한 자세한 내용은 Vertex AI와 데이터베이스 통합 사용 설정을 참조하세요.
오류 메시지: Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found. Vertex AI에 머신러닝 모델 또는 LLM이 존재하지 않습니다.
오류 메시지: Resource exhausted: grpc: received message larger than max. Cloud SQL이 Vertex AI에 전달하는 요청 크기가 요청당 gRPC 한도인 4MB를 초과합니다.
오류 메시지: Cloud SQL attempts to send a request to Vertex AI. However, the instance is in the %s region, but the Vertex AI endpoint is in the %s region. Make sure the instance and endpoint are in the same region. Cloud SQL이 Vertex AI에 요청을 전송하려고 시도하지만 인스턴스는 한 리전에 있지만 Vertex AI 엔드포인트는 다른 리전에 있습니다. 이 문제를 해결하려면 인스턴스와 엔드포인트가 모두 동일한 리전에 있어야 합니다.
오류 메시지: The Vertex AI endpoint isn't formatted properly. Vertex AI 엔드포인트의 형식이 올바르지 않습니다. 자세한 내용은 온라인 예측에 비공개 엔드포인트 사용을 참조하세요.
오류 메시지: Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model with base model: textembedding-gecko. Cloud SQL이 Vertex AI에 전달하는 요청 수가 프로젝트별 모델당 리전별 분당 요청 한도인 1,500개를 초과합니다.

다음 단계