모델을 사용하여 예측을 호출하거나 임베딩을 생성하려면 모델 엔드포인트 관리에 모델 엔드포인트를 등록합니다.
시작하기 전에
모델 엔드포인트 관리에 모델 엔드포인트를 등록하기 전에 google_ml_integration 확장 프로그램을 사용 설정하고 모델 엔드포인트에 인증이 필요한 경우 모델 제공업체를 기반으로 인증을 설정해야 합니다.
postgres 기본 사용자 이름으로 데이터베이스에 액세스해야 합니다.
확장 프로그램 사용 설정
연결된 함수를 사용하려면 먼저 google_ml_integration 확장 프로그램을 추가하고 사용 설정해야 합니다. 모델 엔드포인트 관리를 사용하려면 google_ml_integration 확장 프로그램이 설치되어 있어야 합니다.
인스턴스의
google_ml_integration.enable_model_support데이터베이스 플래그가on로 설정되어 있는지 확인합니다. 데이터베이스 플래그 설정에 관한 자세한 내용은 인스턴스의 데이터베이스 플래그 구성을 참고하세요.psql또는 PostgreSQL용 AlloyDB 스튜디오를 사용하여 데이터베이스에 연결합니다.선택사항:
google_ml_integration확장 프로그램이 이미 설치된 경우 최신 버전으로 업데이트하도록 변경합니다.ALTER EXTENSION google_ml_integration UPDATE;psql을 사용하여
google_ml_integration확장 프로그램을 추가합니다.CREATE EXTENSION IF NOT EXISTS google_ml_integration;선택사항: 모델 메타데이터를 관리할 수 있는 권한을 최고 관리자가 아닌 PostgreSQL 사용자에게 부여합니다.
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;NON_SUPER_USER를 수퍼가 아닌 PostgreSQL 사용자 이름으로 바꿉니다.서드 파티 모델과 같이 VPC 외부에서 호스팅되는 모델에 액세스할 수 있도록 아웃바운드 IP가 사용 설정되어 있는지 확인합니다. 자세한 내용은 아웃바운드 연결 추가를 참고하세요.
인증 설정
다음 섹션에서는 모델 엔드포인트를 등록하기 전에 인증을 설정하는 방법을 보여줍니다.
Vertex AI 인증 설정
Google Vertex AI 모델 엔드포인트를 사용하려면 데이터베이스에 연결하는 데 사용하는 IAM 기반 AlloyDB 서비스 계정에 Vertex AI 권한을 추가해야 합니다. Vertex AI와의 통합에 관한 자세한 내용은 Vertex AI와 통합을 참고하세요.
Secret Manager를 사용하여 인증 설정
이 섹션에서는 Secret Manager를 사용하여 서드 파티 제공업체의 인증 세부정보를 저장하는 경우 인증을 설정하는 방법을 설명합니다.
모델 엔드포인트가 Secret Manager를 통해 인증을 처리하지 않는 경우 이 단계는 선택사항입니다. 예를 들어 모델 엔드포인트가 HTTP 헤더를 사용하여 인증 정보를 전달하거나 인증을 전혀 사용하지 않는 경우입니다.
API 키 또는 보유자 토큰을 만들고 사용하려면 다음 단계를 완료하세요.
Secret Manager에서 보안 비밀을 만듭니다. 자세한 내용은 보안 비밀 만들기 및 보안 비밀 버전 액세스를 참고하세요.
보안 비밀 경로는
google_ml.create_sm_secret()SQL 함수에 사용됩니다.AlloyDB 클러스터에 보안 비밀에 액세스할 권한을 부여합니다.
gcloud secrets add-iam-policy-binding 'SECRET_NAME' \ --member="serviceAccount:SERVICE_ACCOUNT_ID" \ --role="roles/secretmanager.secretAccessor"다음을 바꿉니다.
SECRET_NAME: Secret Manager의 보안 비밀 이름입니다.SERVICE_ACCOUNT_ID:serviceAccount:service-PROJECT_ID@gcp-sa-alloydb.iam.gserviceaccount.com형식의 IAM 기반 서비스 계정의 ID입니다(예:service-212340152456@gcp-sa-alloydb.iam.gserviceaccount.com).프로젝트 수준에서 서비스 계정에 이 역할을 부여할 수도 있습니다. 자세한 내용은 ID 및 액세스 관리 정책 바인딩 추가를 참고하세요.
헤더를 사용하여 인증 설정
다음 예는 함수를 사용하여 인증을 설정하는 방법을 보여줍니다. 이 함수는 임베딩 모델을 요청하는 데 필요한 헤더가 포함된 JSON 객체를 반환합니다.
CREATE OR REPLACE FUNCTION HEADER_GEN_FUNCTION(
model_id VARCHAR(100),
input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
api_key VARCHAR(255) := 'API_KEY';
header_json JSON;
BEGIN
header_json := json_build_object(
'Content-Type', 'application/json',
'Authorization', 'Bearer ' || api_key
);
RETURN header_json;
END;
$$;
다음을 바꿉니다.
HEADER_GEN_FUNCTION: 모델을 등록할 때 사용할 수 있는 헤더 생성 함수의 이름입니다.API_KEY: 모델 제공업체의 API 키입니다.
텍스트 임베딩 모델
이 섹션에서는 모델 엔드포인트 관리에 모델 엔드포인트를 등록하는 방법을 보여줍니다.
모델 엔드포인트 관리는 일부 텍스트 임베딩 및 일반 Vertex AI 모델을 사전 등록된 모델 엔드포인트로 지원합니다. 모델 ID를 직접 사용하여 모델 유형에 따라 임베딩을 생성하거나 예측을 호출할 수 있습니다. 지원되는 사전 등록된 모델에 관한 자세한 내용은 사전 등록된 Vertex AI 모델을 참고하세요.
예를 들어 사전 등록된 textembedding-gecko 모델을 호출하려면 임베딩 함수를 사용하여 모델을 직접 호출하면 됩니다.
SELECT
google_ml.embedding(
model_id => 'textembedding-gecko',
content => 'AlloyDB is a managed, cloud-hosted SQL database service');
마찬가지로 사전 등록된 gemini-1.5-pro:generateContent 모델을 호출하려면 예측 함수를 사용하여 모델을 직접 호출하면 됩니다.
SELECT
json_array_elements(
google_ml.predict_row(
model_id => 'gemini-1.5-pro:generateContent',
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';
임베딩을 생성하려면 사전 등록된 모델 엔드포인트의 임베딩을 생성하는 방법을 참고하세요. 예측을 호출하려면 사전 등록된 모델 엔드포인트의 예측을 호출하는 방법을 참고하세요.
기본 지원되는 텍스트 임베딩 모델
모델 엔드포인트 관리는 Vertex AI 및 OpenAI의 일부 모델을 위한 기본 제공 지원을 제공합니다. 기본 지원이 포함된 모델 목록은 기본 지원이 포함된 모델을 참고하세요.
기본 지원이 있는 모델의 경우 정규화된 이름을 모델 정규화된 이름으로 설정하고 요청 URL을 지정할 수 있습니다. 모델 엔드포인트 관리는 모델을 자동으로 식별하고 기본 변환 함수를 설정합니다.
Vertex AI 임베딩 모델
다음 단계에서는 Vertex AI 모델을 내장 지원으로 등록하는 방법을 보여줍니다. text-embedding-005 및 text-multilingual-embedding-002 모델 엔드포인트가 예로 사용됩니다.
쿼리하는 AlloyDB 클러스터와 Vertex AI 모델이 모두 동일한 리전에 있는지 확인합니다.
create model 함수를 호출하여 모델 엔드포인트를 추가합니다.
text-embedding-005
CALL google_ml.create_model( model_id => 'text-embedding-005', model_request_url => 'publishers/google/models/text-embedding-005', model_provider => 'google', model_qualified_name => 'text-embedding-005', model_type => 'text_embedding', model_auth_type => 'alloydb_service_agent_iam');text-multilingual-embedding-002
CALL google_ml.create_model( model_id => 'text-multilingual-embedding-002', model_request_url => 'publishers/google/models/text-multilingual-embedding-002', model_provider => 'google', model_qualified_name => 'text-multilingual-embedding-002', model_type => 'text_embedding', model_auth_type => 'alloydb_service_agent_iam' model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform', model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');
모델이 AlloyDB 클러스터와 다른 프로젝트 및 리전에 저장된 경우 요청 URL을 projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID로 설정합니다. 여기서 REGION_ID는 모델이 호스팅되는 리전이고 MODEL_ID는 정규화된 모델 이름입니다.
또한 AlloyDB 인스턴스가 있는 프로젝트의 AlloyDB 서비스 계정에 Vertex AI 사용자 (roles/aiplatform.user) 역할을 부여하여 AlloyDB가 다른 프로젝트에 호스팅된 모델에 액세스할 수 있도록 합니다.
Open AI 텍스트 임베딩 모델
google_ml_integration 확장 프로그램은 기본 변환 함수를 자동으로 설정하고 원격 OpenAI 모델 호출을 호출합니다. 기본적으로 지원되는 OpenAI 모델 목록은 기본적으로 지원되는 모델을 참고하세요.
다음 예에서는 text-embedding-ada-002 OpenAI 모델 엔드포인트를 추가합니다.
동일한 단계를 사용하여 OpenAI text-embedding-3-small 및 text-embedding-3-large 모델 엔드포인트를 등록하고 모델별로 모델 한정 이름을 설정할 수 있습니다.
psql를 사용하여 데이터베이스에 연결합니다.google_ml_integration확장 프로그램을 만들고 사용 설정합니다.- 인증을 위해 OpenAI API 키를 Secret Manager에 보안 비밀로 추가합니다.
Secret Manager에 저장된 보안 비밀을 호출합니다.
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입니다(예:key1).SECRET_MANAGER_SECRET_ID: 보안 비밀을 만들 때 Secret Manager에 설정된 보안 비밀 ID입니다.PROJECT_ID: Google Cloud 프로젝트의 ID입니다.VERSION_NUMBER: 보안 비밀 ID의 버전 번호입니다.
모델 만들기 함수를 호출하여
text-embedding-ada-002모델 엔드포인트를 등록합니다.CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'open_ai', model_type => 'text_embedding', model_qualified_name => 'text-embedding-ada-002', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID');다음을 바꿉니다.
MODEL_ID: 정의한 모델 엔드포인트의 고유 ID입니다. 이 모델 ID는 모델 엔드포인트가 임베딩을 생성하거나 예측을 호출하는 데 필요한 메타데이터에 대해 참조됩니다.SECRET_ID: 앞의google_ml.create_sm_secret()절차에서 사용한 보안 비밀 ID입니다.
임베딩을 생성하려면 기본 제공 지원을 통해 모델 엔드포인트의 임베딩을 생성하는 방법을 참고하세요.
커스텀 호스팅 텍스트 임베딩 모델
이 섹션에서는 변환 함수 만들기와 함께 맞춤 호스팅 모델 엔드포인트와 선택적으로 맞춤 HTTP 헤더를 등록하는 방법을 보여줍니다. 모든 맞춤 호스팅 모델 엔드포인트는 호스팅 위치와 관계없이 지원됩니다.
다음 예에서는 Cymbal에서 호스팅하는 custom-embedding-model 맞춤 모델 엔드포인트를 추가합니다. cymbal_text_input_transform 및 cymbal_text_output_transform 변환 함수는 모델의 입력 및 출력 형식을 예측 함수의 입력 및 출력 형식으로 변환하는 데 사용됩니다.
맞춤 호스팅 텍스트 임베딩 모델 엔드포인트를 등록하려면 다음 단계를 완료하세요.
Secret Manager에 저장된 보안 비밀을 호출합니다.
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입니다(예:key1).SECRET_MANAGER_SECRET_ID: 보안 비밀을 만들 때 Secret Manager에 설정된 보안 비밀 ID입니다.PROJECT_ID: Google Cloud 프로젝트의 ID입니다.VERSION_NUMBER: 보안 비밀 ID의 버전 번호입니다.
텍스트 임베딩 모델 엔드포인트의 예측 함수에 관한 다음 서명을 기반으로 입력 및 출력 변환 함수를 만듭니다. 변환 함수를 만드는 방법에 관한 자세한 내용은 변환 함수 예를 참고하세요.
다음은
custom-embedding-model텍스트 임베딩 모델 엔드포인트에만 해당하는 변환 함수의 예입니다.-- Input Transform Function corresponding to the custom model endpoint 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; $$; -- Output Transform Function corresponding to the custom model endpoint 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; $$;create model 함수를 호출하여 맞춤 임베딩 모델 엔드포인트를 등록합니다.
CALL google_ml.create_model( model_id => 'MODEL_ID', model_request_url => 'REQUEST_URL', model_provider => 'custom', model_type => 'text_embedding', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID', model_qualified_name => 'MODEL_QUALIFIED_NAME', model_in_transform_fn => 'cymbal_text_input_transform', model_out_transform_fn => 'cymbal_text_output_transform');다음을 바꿉니다.
MODEL_ID: 필수 항목입니다. 정의한 모델 엔드포인트의 고유 ID입니다(예:custom-embedding-model). 이 모델 ID는 모델 엔드포인트가 임베딩을 생성하거나 예측을 호출하는 데 필요한 메타데이터에 대해 참조됩니다.REQUEST_URL: 필수 항목입니다. 맞춤 텍스트 임베딩 및 일반 모델 엔드포인트를 추가할 때의 모델별 엔드포인트입니다(예:https://cymbal.com/models/text/embeddings/v1). 내부 IP 주소를 통해 모델 엔드포인트에 액세스할 수 있는지 확인합니다. 모델 엔드포인트 관리는 공개 IP 주소를 지원하지 않습니다.MODEL_QUALIFIED_NAME: 모델 엔드포인트에서 정규화된 이름을 사용하는 경우 필요합니다. 모델 엔드포인트에 여러 버전이 있는 경우의 정규화된 이름입니다.SECRET_ID: 앞의google_ml.create_sm_secret()절차에서 사용한 보안 비밀 ID입니다.
일반 모델
이 섹션에서는 Hugging Face, OpenAI, Vertex AI, Anthropic 또는 기타 제공업체와 같이 호스팅된 모델 제공업체에서 사용할 수 있는 일반 모델 엔드포인트를 등록하는 방법을 보여줍니다. 이 섹션에서는 Hugging Face에 호스팅된 일반 모델 엔드포인트, Vertex AI Model Garden의 일반 gemini-pro 모델, claude-haiku 모델 엔드포인트를 등록하는 예를 보여줍니다.
입력과 출력이 JSON 형식인 경우 모든 일반 모델 엔드포인트를 등록할 수 있습니다. 모델 엔드포인트 메타데이터에 따라 HTTP 헤더를 생성하거나 요청 URL을 정의해야 할 수 있습니다.
사전 등록된 일반 모델 및 기본 제공 지원 모델에 관한 자세한 내용은 지원되는 모델을 참고하세요.
Gemini 모델
일부 gemini-pro 모델은 사전 등록되어 있으므로 모델 ID를 직접 호출하여 예측을 호출할 수 있습니다.
다음 예에서는 Vertex AI Model Garden의 gemini-1.5-pro:generateContent 모델 엔드포인트를 사용합니다.
psql를 사용하여 데이터베이스에 연결합니다.google_ml_integration확장 프로그램을 만들고 사용 설정합니다.사전 등록된 모델 ID를 사용하여 예측을 호출합니다.
SELECT json_array_elements( google_ml.predict_row( model_id => 'gemini-1.5-pro:generateContent', 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';
Hugging Face의 일반 모델
다음 예에서는 Hugging Face에 호스팅된 facebook/bart-large-mnli 맞춤 분류 모델 엔드포인트를 추가합니다.
psql를 사용하여 데이터베이스에 연결합니다.google_ml_integration확장 프로그램을 만들고 사용 설정합니다.- 인증을 위해 OpenAI API 키를 Secret Manager에 보안 비밀로 추가합니다. 다른 OpenAI 모델에 대해 이미 보안 비밀을 만든 경우 동일한 보안 비밀을 재사용할 수 있습니다.
Secret Manager에 저장된 보안 비밀을 호출합니다.
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입니다.SECRET_MANAGER_SECRET_ID: 보안 비밀을 만들 때 Secret Manager에 설정된 보안 비밀 ID입니다.PROJECT_ID: Google Cloud 프로젝트의 ID입니다.VERSION_NUMBER: 보안 비밀 ID의 버전 번호입니다.
모델 만들기 함수를 호출하여
facebook/bart-large-mnli모델 엔드포인트를 등록합니다.CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'hugging_face', model_request_url => 'REQUEST_URL', model_qualified_name => 'MODEL_QUALIFIED_NAME', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID');다음을 바꿉니다.
MODEL_ID: 정의한 모델 엔드포인트의 고유 ID입니다(예:custom-classification-model). 이 모델 ID는 모델 엔드포인트가 임베딩을 생성하거나 예측을 호출하는 데 필요한 메타데이터에 대해 참조됩니다.REQUEST_URL: 커스텀 텍스트 임베딩 및 일반 모델 엔드포인트를 추가할 때의 모델별 엔드포인트입니다(예:https://api-inference.huggingface.co/models/facebook/bart-large-mnli).MODEL_QUALIFIED_NAME: 모델 엔드포인트 버전의 정규화된 이름입니다(예:facebook/bart-large-mnli).SECRET_ID: 앞의google_ml.create_sm_secret()절차에서 사용한 보안 비밀 ID입니다.
Anthropic 일반 모델
다음 예에서는 claude-3-opus-20240229 모델 엔드포인트를 추가합니다.
모델 엔드포인트 관리는 인류 모델을 등록하는 데 필요한 헤더 함수를 제공합니다.
psql를 사용하여 데이터베이스에 연결합니다.google_ml_integration확장 프로그램을 만들고 사용 설정합니다.Secret Manager
- 인증을 위해 Secret Manager에 보안 비밀로 bearer 토큰을 추가합니다.
Secret Manager에 저장된 보안 비밀을 호출합니다.
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입니다.SECRET_MANAGER_SECRET_ID: 보안 비밀을 만들 때 Secret Manager에 설정된 보안 비밀 ID입니다.PROJECT_ID: Google Cloud 프로젝트의 ID입니다.VERSION_NUMBER: 보안 비밀 ID의 버전 번호입니다.
모델 만들기 함수를 호출하여
claude-3-opus-20240229모델 엔드포인트를 등록합니다.CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'anthropic', model_request_url => 'REQUEST_URL', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID', generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');다음을 바꿉니다.
MODEL_ID: 정의한 모델 엔드포인트의 고유 ID입니다(예:anthropic-opus). 이 모델 ID는 모델 엔드포인트가 임베딩을 생성하거나 예측을 호출하는 데 필요한 메타데이터에 대해 참조됩니다.REQUEST_URL: 맞춤 텍스트 임베딩 및 일반 모델 엔드포인트를 추가할 때의 모델별 엔드포인트입니다(예:https://api.anthropic.com/v1/messages).
인증 헤더
google_ml.anthropic_claude_header_gen_fn기본 헤더 생성 함수를 사용하거나 헤더 생성 함수를 만듭니다.CREATE OR REPLACE FUNCTION anthropic_sample_header_gen_fn(model_id VARCHAR(100), request_body JSON) RETURNS JSON LANGUAGE plpgsql AS $$ #variable_conflict use_variable BEGIN RETURN json_build_object('x-api-key', 'ANTHROPIC_API_KEY', 'anthropic-version', 'ANTHROPIC_VERSION')::JSON; END; $$;다음을 바꿉니다.
ANTHROPIC_API_KEY: 인류 API 키입니다.ANTHROPIC_VERSION(선택사항): 사용하려는 특정 모델 버전입니다(예:2023-06-01).
모델 만들기 함수를 호출하여
claude-3-opus-20240229모델 엔드포인트를 등록합니다.CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'anthropic', model_request_url => 'REQUEST_URL', generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');다음을 바꿉니다.
MODEL_ID: 정의한 모델 엔드포인트의 고유 ID입니다(예:anthropic-opus). 이 모델 ID는 모델 엔드포인트가 임베딩을 생성하거나 예측을 호출하는 데 필요한 메타데이터에 대해 참조됩니다.REQUEST_URL: 커스텀 텍스트 임베딩 및 일반 모델 엔드포인트를 추가할 때의 모델별 엔드포인트입니다(예:https://api.anthropic.com/v1/messages).
자세한 내용은 일반 모델 엔드포인트의 예측을 호출하는 방법을 참고하세요.
다음 단계
- 모델 엔드포인트 관리 참조에 대해 알아보기
- 모델 엔드포인트 등록을 위한 샘플 템플릿 사용