모델 엔드포인트 관리 미리보기를 사용하면 모델 엔드포인트를 등록하고, 데이터베이스 클러스터에서 모델 엔드포인트 메타데이터를 관리한 다음, SQL 쿼리를 사용하여 모델과 상호작용할 수 있습니다. 모델과 관련된 모델 엔드포인트 메타데이터를 추가하고 등록한 다음 모델을 사용하여 벡터 임베딩을 생성하거나 예측을 호출하는 함수가 포함된 google_ml_integration 확장 프로그램을 제공합니다.
모델 엔드포인트 관리를 사용하여 등록할 수 있는 모델 유형의 예는 다음과 같습니다.
- Vertex AI 텍스트 임베딩 모델
- 서드 파티 제공업체에서 제공하는 임베딩 모델
- 맞춤 호스팅 텍스트 임베딩 모델
- JSON 기반 API가 있는 일반 모델(예: Vertex AI Model Garden의
gemini-pro모델)
작동 방식
모델 엔드포인트 관리를 사용하여 다음을 준수하는 모델 엔드포인트를 등록할 수 있습니다.
- 모델 입력 및 출력은 JSON 형식을 지원합니다.
- REST 프로토콜을 사용하여 모델을 호출할 수 있습니다.
모델 엔드포인트 관리에 모델 엔드포인트를 등록하면 모델 참조로 제공한 고유한 모델 ID가 각 엔드포인트에 등록됩니다. 이 모델 ID를 사용하여 모델을 쿼리할 수 있습니다.
텍스트 프롬프트를 숫자 벡터로 변환하는 임베딩을 생성합니다. 데이터베이스에서
pgvector확장 프로그램이 사용 설정된 경우 생성된 임베딩을 벡터 데이터로 저장할 수 있습니다.트랜잭션 내에서 SQL을 사용하여 모델을 호출하려면 예측을 호출합니다.
애플리케이션은 google_ml_integration 확장 프로그램을 사용하여 모델 엔드포인트 관리에 액세스할 수 있습니다. 이 확장 프로그램은 다음과 같은 함수를 제공합니다.
- 예측 또는 임베딩 함수에 사용되는 모델 엔드포인트를 등록하는 데 사용되는
google_ml.create_model()SQL 함수. - API 키가 저장된 Google CloudSecret Manager의 보안 비밀을 사용하는
google_ml.create_sm_secret()SQL 함수. - 텍스트 임베딩을 생성하는 예측 함수인
google_ml.embedding()SQL 함수. - JSON 입력 및 출력 형식을 지원하는 일반 모델을 호출할 때 예측을 생성하는
google_ml.predict_row()SQL 함수. - 일반 모델의 맞춤 URL 생성, HTTP 헤더 생성 또는 변환 함수 전달을 처리하는 기타 도우미 함수.
- 등록된 모델 엔드포인트와 비밀을 관리하는 함수.
주요 개념
모델 엔드포인트 관리를 사용하기 전에 모델에 연결하고 이를 사용하는 데 필요한 개념을 파악하세요.
모델 제공업체
모델 제공업체는 지원되는 모델 호스팅 제공업체를 나타냅니다. 다음 표에는 사용하는 모델 제공업체에 따라 설정해야 하는 모델 제공업체 값이 나와 있습니다.
| 모델 제공업체 | 함수에서 다음으로 설정 |
|---|---|
| Vertex AI | google |
| 기타 모델 | custom |
기본 모델 제공업체는 custom입니다.
지원되는 인증 방법은 제공업체 유형에 따라 다릅니다. Vertex AI 모델은 Distributed Cloud 서비스 계정을 사용하여 인증하는 반면, 다른 제공업체는 Secret Manager를 사용하여 인증할 수 있습니다.
모델 유형
모델 유형은 AI 모델의 유형을 나타냅니다. 이 확장 프로그램은 텍스트 임베딩과 모든 일반 모델 유형을 지원합니다. 모델 엔드포인트를 등록할 때 설정할 수 있는 지원되는 모델 유형은 text-embedding 및 generic입니다. 일반 모델 엔드포인트를 등록할 때는 모델 유형을 설정하지 않아도 됩니다. 기본 모델 유형이 generic이기 때문입니다.
- 기본 지원이 있는 텍스트 임베딩 모델
- 모델 엔드포인트 관리는 Vertex AI의
textembedding-gecko모델의 모든 버전을 기본적으로 지원합니다. 이러한 모델 엔드포인트를 등록하려면google_ml.create_model()함수를 사용하세요. Distributed Cloud는 이러한 모델의 기본 변환 함수를 자동으로 설정합니다. - 이러한 모델의 모델 유형은
text-embedding입니다. - 기타 텍스트 임베딩 모델
- 기타 텍스트 임베딩 모델의 경우 모델에서 지원하는 입력 및 출력 형식을 처리하는 변환 함수를 만들어야 합니다. 선택적으로 모델에 필요한 맞춤 헤더를 생성하는 HTTP 헤더 생성 함수를 사용할 수 있습니다.
- 이러한 모델의 모델 유형은
text-embedding입니다. - 일반 모델
- 모델 엔드포인트 관리는 텍스트 임베딩 모델 외에도 다른 모든 모델 유형의 등록도 지원합니다. 일반 모델의 예측을 호출하려면
google_ml.predict_row()함수를 사용하세요. 해당 모델의 특정 요청 엔드포인트 및 HTTP 헤더와 같은 모델 엔드포인트 메타데이터를 설정할 수 있습니다. - 일반 모델 엔드포인트를 등록할 때는 변환 함수를 전달할 수 없습니다. 예측을 호출할 때 함수의 입력이 JSON 형식이고 JSON 출력을 파싱하여 최종 출력을 가져오는지 확인합니다.
- 이러한 모델의 모델 유형은
generic입니다.
인증
인증 유형은 google_ml_integration 확장 프로그램을 사용하여 모델 엔드포인트 관리에 연결하는 데 사용할 수 있는 인증 유형을 나타냅니다. 인증 설정은 선택사항이며 모델에 액세스하기 위해 인증이 필요한 경우에만 필요합니다.
Vertex AI 모델의 경우 Distributed Cloud 서비스 계정이 인증에 사용됩니다. 다른 모델의 경우 Secret Manager에 보안 비밀로 저장된 API 키 또는 Bearer 토큰을 google_ml.create_sm_secret() SQL 함수와 함께 사용할 수 있습니다.
다음 표에는 설정할 수 있는 인증 유형이 나와 있습니다.
| 인증 방법 | 함수에서 다음으로 설정 | 모델 제공업체 |
|---|---|---|
| Distributed Cloud 서비스 에이전트 | alloydb_service_agent_iam |
Vertex AI 제공업체 |
| Secret Manager | secret_manager |
서드 파티 제공업체 |
예측 함수
google_ml_integration 확장 프로그램에는 다음과 같은 예측 함수가 포함되어 있습니다.
google_ml.embedding()- 등록된 텍스트 임베딩 모델 엔드포인트를 호출하여 임베딩을 생성하는 데 사용됩니다. Vertex AI의
textembedding-gecko모델을 기본적으로 지원합니다. - 기본 제공 지원이 없는 텍스트 임베딩 모델의 경우 입력 및 출력 매개변수는 모델에 고유하며 함수에서 모델을 호출하려면 변환이 필요합니다. 예측 함수의 입력을 모델별 입력으로 변환하는 변환 입력 함수와 모델별 출력을 예측 함수 출력으로 변환하는 변환 출력 함수를 만듭니다.
google_ml.predict_row()- 등록된 일반 모델 엔드포인트를 호출하여 예측을 호출하는 데 사용됩니다(JSON 기반 API를 지원하는 경우).
변환 함수
변환 함수는 입력을 모델이 이해하는 형식으로 수정하고 모델 응답을 예측 함수가 예상하는 형식으로 변환합니다. 변환 함수는 기본 제공 지원 없이 text-embedding 모델 엔드포인트를 등록할 때 사용됩니다. 변환 함수의 서명은 모델 유형의 예측 함수에 따라 다릅니다.
generic 모델 엔드포인트를 등록할 때는 변환 함수를 사용할 수 없습니다.
다음은 텍스트 임베딩 모델의 예측 함수 서명을 보여줍니다.
// define custom model specific input/output transform functions.
CREATE OR REPLACE FUNCTION input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
CREATE OR REPLACE FUNCTION output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS real[];
HTTP 헤더 생성 함수
HTTP 헤더 생성 함수는 HTTP 헤더로 사용되는 JSON 키-값 쌍으로 출력을 생성합니다. 예측 함수의 서명은 헤더 생성 함수의 서명을 정의합니다.
다음 예시는 google_ml.embedding() 예측 함수의 서명을 보여줍니다.
CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON;
google_ml.predict_row() 예측 함수의 서명은 다음과 같습니다.
CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON;
모델 등록
모델을 사용하여 예측을 호출하거나 임베딩을 생성하려면 모델 엔드포인트를 모델 엔드포인트 관리에 등록하세요.
google_ml.create_model() 함수에 대한 자세한 내용은 모델 엔드포인트 관리 참조를 확인하세요.
모델 엔드포인트를 모델 엔드포인트 관리에 등록하기 전에 모델 엔드포인트에 인증이 필요한 경우 google_ml_integration 확장 프로그램을 사용 설정하고 모델 제공업체에 따라 인증을 설정해야 합니다.
postgres 기본 사용자 이름으로 데이터베이스에 액세스해야 합니다.
인증 설정
다음 섹션에서는 Vertex AI 모델 엔드포인트 또는 다른 제공업체의 모델 엔드포인트를 추가하기 전에 인증을 설정하는 방법을 보여줍니다.
Vertex AI 인증 설정
Google Vertex AI 모델 엔드포인트를 사용하려면 AlloyDB Omni를 설치할 때 사용한 서비스 계정에 Vertex AI 권한을 추가해야 합니다.
다른 모델 제공업체의 인증 설정
Vertex AI 모델을 제외한 모든 모델의 경우 API 키 또는 Bearer 토큰을 Secret Manager에 저장할 수 있습니다. 모델 엔드포인트가 Secret Manager를 통한 인증을 처리하지 않는 경우(예: 모델 엔드포인트가 HTTP 헤더를 사용하여 인증 정보를 전달하거나 인증을 전혀 사용하지 않는 경우) 이 단계는 선택사항입니다.
이 섹션에서는 Secret Manager를 사용하는 경우 인증을 설정하는 방법을 설명합니다.
API 키 또는 Bearer 토큰을 만들고 사용하려면 다음 단계를 완료하세요.
Secret Manager에서 보안 비밀을 만듭니다.
보안 비밀 이름과 보안 비밀 경로는
google_ml.create_sm_secret()SQL 함수에서 사용됩니다.Distributed Cloud 클러스터가 보안 비밀에 액세스할 수 있도록 권한을 부여합니다.
gcloud secrets add-iam-policy-binding 'SECRET_ID' \ --member="serviceAccount:SERVICE_ACCOUNT_ID" \ --role="roles/secretmanager.secretAccessor"다음을 바꿉니다.
SECRET_ID: Secret Manager의 보안 비밀 IDSERVICE_ACCOUNT_ID: 이전 단계에서 만든 서비스 계정의 ID입니다. AlloyDB Omni 설치 중에 사용한 계정과 동일한 계정인지 확인합니다. 여기에는 전체PROJECT_ID.iam.gserviceaccount.com접미사가 포함됩니다. 예를 들면my-service@my-project.iam.gserviceaccount.com입니다.프로젝트 수준에서 서비스 계정에 이 역할을 부여할 수도 있습니다.
임베딩 생성
이 섹션에서는 AI 모델 엔드포인트 등록 및 모델 엔드포인트 관리로 예측 호출을 실험할 수 있는 미리보기를 설명합니다.
모델 엔드포인트가 추가되고 모델 엔드포인트 관리에 등록된 후에는 모델 ID를 사용해서 이를 참조하여 임베딩을 생성할 수 있습니다.
시작하기 전에
모델 엔드포인트를 모델 엔드포인트 관리에 등록했는지 확인합니다.
임베딩 생성
google_ml.embedding() SQL 함수를 사용하여 텍스트 임베딩 모델 유형으로 등록된 모델 엔드포인트를 호출하여 임베딩을 생성합니다.
모델을 호출하고 임베딩을 생성하려면 다음 SQL 쿼리를 사용하세요.
SELECT
google_ml.embedding(
model_id => 'MODEL_ID',
content => 'CONTENT');
다음을 바꿉니다.
MODEL_ID: 모델 엔드포인트를 등록할 때 정의한 모델 ID.CONTENT: 벡터 임베딩으로 변환할 텍스트.
예시
이 섹션에는 등록된 모델 엔드포인트를 사용하여 임베딩을 생성하는 몇 가지 예시가 나와 있습니다.
기본 지원이 있는 텍스트 임베딩 모델
등록된 textembedding-gecko@002 모델 엔드포인트에 대해 임베딩을 생성하려면 다음 문을 실행합니다.
SELECT
google_ml.embedding(
model_id => 'textembedding-gecko@002',
content => 'AlloyDB is a managed, cloud-hosted SQL database service');
예측 호출
이 섹션에서는 AI 모델 엔드포인트 등록 및 모델 엔드포인트 관리로 예측 호출을 실험할 수 있는 미리보기를 설명합니다.
모델 엔드포인트가 추가되고 모델 엔드포인트 관리에 등록된 후에는 모델 ID를 사용해서 이를 참조하여 예측을 호출할 수 있습니다.
시작하기 전에
모델 엔드포인트를 모델 엔드포인트 관리에 등록했는지 확인합니다.
일반 모델의 예측 호출
google_ml.predict_row() SQL 함수를 사용하여 등록된 일반 모델 엔드포인트를 호출하여 예측을 호출합니다. google_ml.predict_row() 함수는 모든 모델 유형에 사용할 수 있습니다.
SELECT
google_ml.predict_row(
model_id => 'MODEL_ID',
request_body => 'REQUEST_BODY');
다음을 바꿉니다.
MODEL_ID: 모델 엔드포인트를 등록할 때 정의한 모델 ID.REQUEST_BODY: JSON 형식의 예측 함수에 대한 파라미터입니다.
예시
이 섹션에는 등록된 모델 엔드포인트를 사용하여 예측을 호출하는 몇 가지 예시가 나와 있습니다.
등록된 gemini-pro 모델 엔드포인트에 대해 예측을 생성하려면 다음 문을 실행합니다.
SELECT
json_array_elements(
google_ml.predict_row(
model_id => 'gemini-pro',
request_body => '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
}
]
}
]
}'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';
모델 엔드포인트 관리 API 참조
이 섹션에는 google_ml_integration 확장 프로그램에서 모델 엔드포인트 관리로 모델 엔드포인트와 비밀을 등록하고 관리하기 위해 제공하는 다양한 함수의 파라미터가 나와 있습니다.
확장 프로그램을 사용하려면 먼저 google_ml_integration.enable_model_support 데이터베이스 플래그를 on으로 설정해야 합니다.
모델
이 참조를 사용하여 모델 엔드포인트를 관리할 수 있는 함수의 파라미터를 알아봅니다.
google_ml.create_model() 함수
다음은 모델 엔드포인트 메타데이터를 등록하는 데 사용되는 google_ml.create_model() SQL 함수를 호출하는 방법을 보여줍니다.
CALL
google_ml.create_model(
model_id => 'MODEL_ID',
model_request_url => 'REQUEST_URL',
model_provider => 'PROVIDER_ID',
model_type => 'MODEL_TYPE',
model_qualified_name => 'MODEL_QUALIFIED_NAME',
model_auth_type => 'AUTH_TYPE',
model_auth_id => 'AUTH_ID',
generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');
| 매개변수 | 필수 | 설명 |
|---|---|---|
MODEL_ID |
모든 모델 엔드포인트에 필수 | 개발자가 정의한 모델 엔드포인트의 고유 ID입니다. |
REQUEST_URL |
기본 제공 지원이 포함된 기타 텍스트 임베딩 모델 엔드포인트의 경우 선택사항 | 다른 텍스트 임베딩과 일반 모델 엔드포인트를 추가할 때의 모델별 엔드포인트입니다. PostgreSQL용 AlloyDB의 경우 https URL을 제공합니다.함수가 기본 제공 모델 엔드포인트에 생성하는 요청 URL은 클러스터의 프로젝트 및 리전이나 위치를 참조합니다. 다른 프로젝트를 참조하려면 model_request_url을 명시적으로 지정해야 합니다.커스텀 호스팅 모델 엔드포인트의 경우 Distributed Cloud가 있는 네트워크에서 모델 엔드포인트에 액세스할 수 있는지 확인합니다. |
PROVIDER_ID |
기본 제공 지원이 포함된 텍스트 임베딩 모델 엔드포인트에 필수 | 모델 엔드포인트 제공업체입니다. 기본값은 custom입니다.다음 중 하나로 설정합니다.
|
MODEL_TYPE |
일반 모델 엔드포인트의 경우 선택사항 | 모델 유형입니다. 다음 중 하나로 설정합니다.
|
MODEL_QUALIFIED_NAME |
기본 제공 지원이 포함된 텍스트 임베딩 모델에 필수, 다른 모델 엔드포인트의 경우 선택사항 | 기본 지원이 있는 텍스트 임베딩 모델의 정규화된 이름입니다. |
AUTH_TYPE |
모델 엔드포인트에 특정 인증 요구사항이 없는 한 선택사항 | 모델 엔드포인트에서 사용하는 인증 유형입니다. 인증에 Secret Manager를 사용하는 경우 Vertex AI 모델의 경우 alloydb_service_agent_iam으로, 다른 제공업체의 경우 secret_manager로 설정할 수 있습니다. 인증 헤더를 사용하는 경우 이 값을 설정하지 않아도 됩니다. |
AUTH_ID |
Vertex AI 모델 엔드포인트에 설정 금지, Secret Manager에 보안 비밀을 저장하는 다른 모든 모델 엔드포인트에는 필수 | 개발자가 설정하고 이후 모델 엔드포인트를 등록할 때 사용되는 보안 비밀 ID입니다. |
GENERATE_HEADER_FUNCTION |
선택사항 | 맞춤 헤더를 생성하는 함수의 이름입니다. 이 함수의 서명은 사용하는 예측 함수에 따라 다릅니다. |
INPUT_TRANSFORM_FUNCTION |
기본 제공 지원이 있는 텍스트 임베딩 모델 엔드포인트의 경우 선택사항, 일반 모델 엔드포인트에 설정 금지 | 해당 예측 함수의 입력을 모델별 입력으로 변환하는 함수입니다. |
OUTPUT_TRANSFORM_FUNCTION |
기본 제공 지원이 있는 텍스트 임베딩 모델 엔드포인트의 경우 선택사항, 일반 모델 엔드포인트에 설정 금지 | 모델별 출력을 예측 함수 출력으로 변환하는 함수입니다. |
google_ml.alter_model()
다음은 모델 엔드포인트 메타데이터를 업데이트하는 데 사용되는 google_ml.alter_model() SQL 함수를 호출하는 방법을 보여줍니다.
CALL
google_ml.alter_model(
model_id => 'MODEL_ID',
model_request_url => 'REQUEST_URL',
model_provider => 'PROVIDER_ID',
model_type => 'MODEL_TYPE',
model_qualified_name => 'MODEL_QUALIFIED_NAME',
model_auth_type => 'AUTH_TYPE',
model_auth_id => 'AUTH_ID',
generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');
각 매개변수에 설정해야 하는 값에 대한 자세한 내용은 모델 만들기를 참고하세요.
google_ml.drop_model() 함수
다음은 모델 엔드포인트를 삭제하는 데 사용되는 google_ml.drop_model() SQL 함수를 호출하는 방법을 보여줍니다.
CALL google_ml.drop_model('MODEL_ID');
| 매개변수 | 설명 |
|---|---|
MODEL_ID |
개발자가 정의한 모델 엔드포인트의 고유 ID입니다. |
google_ml.list_model() 함수
다음은 모델 엔드포인트 정보를 나열하는 데 사용되는 google_ml.list_model() SQL 함수를 호출하는 방법을 보여줍니다.
SELECT google_ml.list_model('MODEL_ID');
| 매개변수 | 설명 |
|---|---|
MODEL_ID |
개발자가 정의한 모델 엔드포인트의 고유 ID입니다. |
뷰 google_ml.model_info_view개
다음은 모든 모델 엔드포인트의 모델 엔드포인트 정보를 나열하는 데 사용되는 google_ml.model_info_view 뷰를 호출하는 방법을 보여줍니다.
SELECT * FROM google_ml.model_info_view;
보안 비밀
이 참조를 사용하여 보안 비밀을 관리할 수 있는 함수의 파라미터를 알아봅니다.
google_ml.create_sm_secret() 함수
다음은 Secret Manager에서 만든 보안 비밀을 추가하는 데 사용되는 google_ml.create_sm_secret() SQL 함수를 호출하는 방법을 보여줍니다.
CALL
google_ml.create_sm_secret(
secret_id => 'SECRET_ID',
secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
| 매개변수 | 설명 |
|---|---|
SECRET_ID |
개발자가 설정하고 이후 모델 엔드포인트를 등록할 때 사용되는 보안 비밀 ID입니다. |
PROJECT_ID |
보안 비밀이 포함된 Google Cloud 프로젝트의 ID입니다. 이 프로젝트는 PostgreSQL용 AlloyDB 클러스터가 포함된 프로젝트와 다를 수 있습니다. AlloyDB Omni의 경우 보안 비밀이 포함된 Google Cloud 프로젝트의 ID입니다. |
SECRET_MANAGER_SECRET_ID |
보안 비밀을 만들 때 Secret Manager에 설정된 보안 비밀 ID입니다. |
VERSION_NUMBER |
보안 비밀 ID의 버전 번호입니다. |
google_ml.alter_sm_secret() 함수
다음은 보안 비밀 정보를 업데이트하는 데 사용되는 google_ml.alter_sm_secret() SQL 함수를 호출하는 방법을 보여줍니다.
CALL
google_ml.alter_sm_secret(
secret_id => 'SECRET_ID',
secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
각 매개변수에 설정해야 하는 값에 대한 자세한 내용은 보안 비밀 만들기를 참고하세요.
google_ml.drop_sm_secret() 함수
다음은 보안 비밀을 삭제하는 데 사용되는 google_ml.drop_sm_secret() SQL 함수를 호출하는 방법을 보여줍니다.
CALL google_ml.drop_sm_secret('SECRET_ID');
| 매개변수 | 설명 |
|---|---|
SECRET_ID |
개발자가 설정하고 이후 모델 엔드포인트를 등록할 때 사용된 보안 비밀 ID입니다. |
예측 함수
이 참조를 사용하여 임베딩을 생성하거나 예측을 호출할 수 있는 함수의 파라미터를 알아봅니다.
google_ml.embedding() 함수
다음은 임베딩을 생성하는 방법을 보여줍니다.
SELECT
google_ml.embedding(
model_id => 'MODEL_ID',
contents => 'CONTENT');
| 매개변수 | 설명 |
|---|---|
MODEL_ID |
개발자가 정의한 모델 엔드포인트의 고유 ID입니다. |
CONTENT |
벡터 임베딩으로 변환할 텍스트입니다. |
google_ml.predict_row() 함수
다음은 예측을 호출하는 방법을 보여줍니다.
SELECT
google_ml.predict_row(
model_id => 'MODEL_ID',
request_body => 'REQUEST_BODY');
| 매개변수 | 설명 |
|---|---|
MODEL_ID |
개발자가 정의한 모델 엔드포인트의 고유 ID입니다. |
REQUEST_BODY |
JSON 형식의 예측 함수에 대한 파라미터입니다. |
변환 함수
이 참조를 사용하여 입력 및 출력 변환 함수의 파라미터를 알아봅니다.
입력 변환 함수
다음은 텍스트 임베딩 모델 엔드포인트의 예측 함수 서명을 보여줍니다.
CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
| 매개변수 | 설명 |
|---|---|
INPUT_TRANSFORM_FUNCTION |
해당 예측 함수 입력을 모델 엔드포인트별 입력으로 변환하는 함수입니다. |
출력 변환 함수
다음은 텍스트 임베딩 모델 엔드포인트의 예측 함수 서명을 보여줍니다.
CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];
| 매개변수 | 설명 |
|---|---|
OUTPUT_TRANSFORM_FUNCTION |
모델 엔드포인트별 출력을 예측 함수 출력으로 변환하는 함수입니다. |
변환 함수 예시
모델 엔드포인트의 변환 함수를 만드는 방법을 더 잘 이해하려면 JSON 입력과 출력이 필요한 커스텀 호스팅 텍스트 임베딩 모델 엔드포인트를 사용하는 것이 좋습니다.
다음 cURL 요청 예시는 프롬프트와 모델 엔드포인트를 기반으로 임베딩을 만듭니다.
curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
-H "Content-Type: application/json"
-d '{"prompt": ["AlloyDB Embeddings"]}'다음과 같은 응답 예시가 반환됩니다.
[[ 0.3522231 -0.35932037 0.10156056 0.17734447 -0.11606089 -0.17266059
0.02509351 0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
0.06821183 -0.06896557 0.1171584 -0.00931572 0.11875633 -0.00077482
0.25604948 0.0519384 0.2034983 -0.09952664 0.10347155 -0.11935943
-0.17872004 -0.08706985 -0.07056875 -0.05929353 0.4177883 -0.14381726
0.07934926 0.31368294 0.12543282 0.10758053 -0.30210832 -0.02951015
0.3908268 -0.03091059 0.05302926 -0.00114946 -0.16233777 0.1117468
-0.1315904 0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
0.14445548 0.19481727]]
이 입력과 응답을 바탕으로 다음을 추론할 수 있습니다.
모델은
prompt필드를 통해 JSON 입력을 예상합니다. 이 필드는 입력 배열을 허용합니다.google_ml.embedding()함수는 행 수준 함수이므로 한 번에 텍스트 입력 하나를 예상합니다. 따라서 단일 요소로 배열을 빌드하는 입력 변환 함수를 만들어야 합니다.모델의 응답은 모델에 입력된 프롬프트마다 하나씩 있는 임베딩 배열입니다.
google_ml.embedding()함수는 행 수준 함수이므로 한 번에 입력 하나를 반환합니다. 따라서 배열에서 임베딩을 추출하는 데 사용할 수 있는 출력 변환 함수를 만들어야 합니다.
다음 예시에서는 이 모델 엔드포인트가 모델 엔드포인트 관리에 등록될 때 사용되는 입력 및 출력 변환 함수를 보여줍니다.
입력 변환 함수
CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
transformed_input JSON;
model_qualified_name TEXT;
BEGIN
SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
RETURN transformed_input;
END;
$$;
출력 변환 함수
CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
transformed_output REAL[];
BEGIN
SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
RETURN transformed_output;
END;
$$;
HTTP 헤더 생성 함수
다음은 다른 텍스트 임베딩 모델 엔드포인트를 등록할 때 google_ml.embedding() 예측 함수와 함께 사용될 수 있는 헤더 생성 함수의 서명을 보여줍니다.
CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
google_ml.predict_row() 예측 함수의 서명은 다음과 같습니다.
CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;
| 매개변수 | 설명 |
|---|---|
GENERATE_HEADERS |
커스텀 헤더를 생성하는 함수입니다. 모델 엔드포인트를 등록하는 동안 헤더 생성 함수에서 생성된 승인 헤더를 전달할 수도 있습니다. |
헤더 생성 함수 예시
HTTP 헤더로 사용되는 JSON 키-값 쌍으로 출력을 생성하는 함수를 만드는 방법을 더 잘 이해하려면 커스텀 호스팅 텍스트 임베딩 모델 엔드포인트를 사용하는 것이 좋습니다.
다음 cURL 요청 예시에서는 모델 엔드포인트에서 사용하는 version HTTP 헤더를 전달합니다.
curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
-H "Content-Type: application/json" \
-H "version: 2024-01-01" \
-d '{"prompt": ["AlloyDB Embeddings"]}'모델은 version 필드를 통해 텍스트 입력을 예상하고 버전 값을 JSON 형식으로 반환합니다. 다음 예시에서는 이 텍스트 임베딩 모델 엔드포인트가 모델 엔드포인트 관리에 등록될 때 사용되는 헤더 생성 함수를 보여줍니다.
CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
RETURN json_build_object('version', '2024-01-01')::JSON;
END;
$$;
API 키를 사용하는 헤더 생성 함수
다음 예에서는 API 키를 사용하여 인증을 설정하는 방법을 보여줍니다.
임베딩 모델
CREATE OR REPLACE FUNCTION header_gen_func(
model_id VARCHAR(100),
input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;
API_KEY를 모델 제공업체의 API 키로 바꿉니다.
일반 모델
CREATE OR REPLACE FUNCTION header_gen_func(
model_id VARCHAR(100),
response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
-- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'model-version', '2023-06-01')::JSON;
END;
$$;
API_KEY를 모델 제공업체의 API 키로 바꿉니다.
요청 URL 생성
요청 URL 생성 함수를 사용하여 기본 제공 지원이 있는 모델 엔드포인트의 요청 URL을 추론합니다. 다음은 이 함수의 서명을 보여줍니다.
CREATE OR REPLACE FUNCTION GENERATE_REQUEST_URL(provider google_ml.model_provider, model_type google_ml.MODEL_TYPE, model_qualified_name VARCHAR(100), model_region VARCHAR(100) DEFAULT NULL)
| 매개변수 | 설명 |
|---|---|
GENERATE_REQUEST_URL |
기본 제공 지원이 있는 모델 엔드포인트용 확장 프로그램에서 생성된 요청 URL을 생성하는 함수입니다. |
지원되는 모델
모델 엔드포인트 관리를 사용하여 텍스트 임베딩 또는 일반 모델 엔드포인트를 등록할 수 있습니다. 모델 엔드포인트 관리에는 사전 등록된 Vertex AI 모델과 기본 지원 모델도 포함됩니다.
사전 등록된 Vertex AI 모델
| 모델 유형 | 모델 ID | 확장 프로그램 버전 |
|---|---|---|
generic |
|
버전 1.4.2 이상 |
text_embedding |
|
버전 1.3 이상 |
기본 지원이 포함된 모델
Vertex AI
| 정규화된 모델 이름 | 모델 유형 |
|---|---|
text-embedding-gecko@001 |
text-embedding |
text-embedding-gecko@003 |
text-embedding |
text-embedding-004 |
text-embedding |
text-embedding-preview-0815 |
text-embedding |
text-multilingual-embedding-002 |
text-embedding |