이 페이지에서는 Cloud SQL을 Vertex AI와 통합하는 방법을 설명합니다. 이 통합을 통해 Vertex AI에서 호스팅되는 대규모 언어 모델(LLM)을 PostgreSQL용 Cloud SQL 데이터베이스 버전 12 이상에 적용할 수 있습니다.
Cloud SQL을 Vertex AI와 통합하면 머신러닝(ML) 모델의 시맨틱 및 예측 성능을 데이터에 적용할 수 있습니다. 이 통합은 모델 쿼리를 위한 두 가지 함수를 사용하여 PostgreSQL 구문을 확장합니다.
- 트랜잭션 내에서 SQL을 사용하여 모델을 호출하려면 예측을 호출합니다.
- 임베딩 모델이 텍스트 프롬프트를 숫자 벡터로 변환하도록 임베딩을 생성합니다. 그런 다음 이러한 벡터 임베딩을
pgvector
함수의 입력으로 적용할 수 있습니다. 여기에는 상대적 시맨틱 거리에 따라 텍스트 샘플을 비교하고 정렬하는 메서드가 포함됩니다.
따라서 실시간 예측을 수행하고 데이터베이스 내에서 직접 유용한 정보를 얻을 수 있으므로 워크플로를 간소화하고 의사 결정 능력을 향상시킬 수 있습니다.
Vertex AI에 대한 자세한 내용은 Vertex AI 소개를 참조하세요.
시작하기 전에
- Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
- 필요한 Google Cloud API를 사용 설정합니다.
Console
- API 및 서비스 페이지로 이동합니다.
- 프로젝트 목록에서 프로젝트를 선택합니다.
- API 라이브러리가 열려 있지 않으면 탐색 메뉴에서 라이브러리를 선택합니다.
사용 설정할 API를 클릭합니다. 이 절차에서는 Cloud SQL Admin API 및 Vertex AI API를 사용 설정합니다.
- 각 API를 선택한 후 사용 설정을 클릭합니다.
gcloud
- Cloud Shell을 열면 브라우저에서 직접 명령줄을 통해 Google Cloud 리소스에 액세스할 수 있습니다.
- 필요한 API를 사용 설정하려면
gcloud services enable
명령어를 사용합니다.gcloud services enable sqladmin.googleapis.com \ enable aiplatform.googleapis.com
이 명령어는 다음 API를 사용 설정합니다.
- Cloud SQL Admin API
- Vertex AI API
- 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와 데이터베이스 통합을 사용 설정하려면 다음 단계를 완료하세요.
- 인스턴스를 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": "user@example.com", "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": "user@example.com", "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": "user@example.com", "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": "user@example.com", "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" }
- 기본 Cloud SQL 인스턴스의 데이터베이스에
google_ml_integration
확장 프로그램을 설치합니다. 이 데이터베이스에는 예측을 실행할 데이터가 포함됩니다.- psql 클라이언트를 사용하여 연결에 설명된 대로
psql
클라이언트를 기본 인스턴스에 연결합니다. psql
명령 프롬프트에서 데이터베이스에 연결합니다.\c DB_NAME
DB_NAME
을 확장 프로그램을 설치할 데이터베이스의 이름으로 바꿉니다.- 확장 프로그램을 설치합니다.
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
- psql 클라이언트를 사용하여 연결에 설명된 대로
문제 해결
이 섹션에는 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 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개를 초과합니다. |