本页介绍了如何通过向模型端点管理注册模型端点，使用模型调用预测或生成嵌入。
准备工作
在使用模型端点管理注册模型端点之前，如果您的模型端点需要身份验证，您必须启用 google_ml_integration 扩展程序，并根据模型提供方设置身份验证。
请务必使用 postgres 默认用户名访问您的数据库。
启用扩展程序
您必须先添加并启用 google_ml_integration 扩展程序，然后才能开始使用关联的函数。若要管理模型端点，您需要安装 google_ml_integration 扩展程序。
验证实例的
google_ml_integration.enable_model_support数据库标志是否设置为on。如需详细了解如何设置数据库标志，请参阅配置实例的数据库标志。使用
psql或 AlloyDB for PostgreSQL Studio 连接到数据库。使用 psql 添加
google_ml_integration扩展程序：CREATE EXTENSION IF NOT EXISTS google_ml_integration;可选：如果已安装
google_ml_integration扩展程序，请对其进行更改以更新到最新版本：ALTER EXTENSION google_ml_integration UPDATE;可选：请求使用 AlloyDB for PostgreSQL AI 查询引擎（预览版）功能的权限，包括支持多模态模型、排名模型和运算符函数。
可选：向 PostgreSQL 非超级用户授予管理模型元数据的权限：
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;将
NON_SUPER_USER替换为 PostgreSQL 非超级用户名。确保已启用出站 IP 访问在 VPC 外部托管的模型（例如第三方模型）。如需了解详情，请参阅添加出站连接。
设置身份验证
以下部分介绍了如何在注册模型端点之前设置身份验证。
设置 Vertex AI 身份验证
如需使用 Google Vertex AI 模型端点，您必须向用于连接到数据库的基于 IAM 的 AlloyDB 服务账号添加 Vertex AI 权限。如需详细了解如何与 Vertex AI 集成，请参阅与 Vertex AI 集成。
使用 Secret Manager 设置身份验证
本部分介绍了如何在使用 Secret Manager 存储第三方提供商的身份验证详细信息时设置身份验证。
如果您的模型端点不通过 Secret Manager 处理身份验证（例如，如果您的模型端点使用 HTTP 标头来传递身份验证信息，或者根本不使用身份验证），则此步骤是可选的。
如需创建和使用 API 密钥或不记名令牌，请完成以下步骤：
在 Secret Manager 中创建 Secret。如需了解详情，请参阅创建 Secret 并访问 Secret 版本。
Secret 路径会在
google_ml.create_sm_secret()SQL 函数中使用。向 AlloyDB 集群授予访问 Secret 的权限。
gcloud secrets add-iam-policy-binding 'SECRET_NAME' \ --member="serviceAccount:SERVICE_ACCOUNT_ID" \ --role="roles/secretmanager.secretAccessor"替换以下内容：
SECRET_NAME：Secret Manager 中的 Secret 名称。SERVICE_ACCOUNT_ID：基于 IAM 的服务账号的 ID，格式为serviceAccount:service-PROJECT_ID@gcp-sa-alloydb.iam.gserviceaccount.com，例如service-212340152456@gcp-sa-alloydb.iam.gserviceaccount.com。您还可以在项目级向服务账号授予此角色。如需了解详情，请参阅添加 Identity and Access Management 政策绑定
使用标头设置身份验证
以下示例展示了如何使用函数设置身份验证。该函数会返回一个 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 模型。
text-embedding-large-exp-03-07 模型仅在 us-central1 区域提供。
例如，如需调用预注册的 text-embedding-large-exp-03-07 模型，您可以直接使用嵌入函数调用该模型：
SELECT
embedding(
model_id => 'text-embedding-large-exp-03-07',
content => 'AlloyDB is a managed, cloud-hosted SQL database service');
同样，如需调用预先注册的 gemini-1.5-pro:generateContent 模型，您可以直接使用预测函数调用该模型：
SELECT 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. Only provide SQL query with no explanation."
}
]
}
]
}')-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';
如需生成嵌入，请参阅如何为预先注册的模型端点生成嵌入。如需调用预测，请参阅如何为预先注册的模型端点调用预测。
具有内置支持的文本嵌入模型
模型端点管理针对 Vertex AI 和 OpenAI 的部分模型提供内置支持。如需查看内置支持的模型列表，请参阅内置支持的模型。
对于内置支持的模型，您可以将限定名称设置为模型限定名称，并指定请求网址。模型端点管理会自动识别模型并设置默认转换函数。
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 集群不同的项目和区域中，请将请求网址设置为 projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID，其中 REGION_ID 是模型的托管区域，MODEL_ID 是经过限定的模型名称。
此外，请向 AlloyDB 实例所在项目的 AlloyDB 服务账号授予 Vertex AI User (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 以进行身份验证。
调用存储在 Secret Manager 中的 Secret：
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：您设置的 Secret ID，随后在注册模型端点时会用到，例如key1。SECRET_MANAGER_SECRET_ID：您创建 Secret 时在 Secret Manager 中设置的 Secret ID。PROJECT_ID：您的 Google Cloud 项目的 ID。VERSION_NUMBER：Secret ID 的版本号。
调用 create model 函数以注册
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()过程中使用的 Secret ID。
如需生成嵌入，请参阅如何为内置支持的模型端点生成嵌入。
自定义托管文本嵌入模型
本部分介绍了如何注册自定义托管模型端点，以及如何创建转换函数和视情况创建自定义 HTTP 标头。无论托管在何处，所有自定义托管的模型端点均受支持。
以下示例添加了由 Cymbal 托管的 custom-embedding-model 自定义模型端点。cymbal_text_input_transform 和 cymbal_text_output_transform 转换函数用于将模型的输入和输出格式转换为预测函数的输入和输出格式。
如需注册自定义托管文本嵌入模型端点，请完成以下步骤：
调用存储在 Secret Manager 中的 Secret：
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：您设置的 Secret ID，随后在注册模型端点时会用到，例如key1。SECRET_MANAGER_SECRET_ID：您创建 Secret 时在 Secret Manager 中设置的 Secret ID。PROJECT_ID：您的 Google Cloud 项目的 ID。VERSION_NUMBER：Secret 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()过程中使用的 Secret ID。
具有内置支持的多模态模型
由于模型端点管理针对 Vertex AI 的 multimodalembedding@001 模型提供内置支持，因此您可以直接调用模型 ID 来生成多模态嵌入。
以下示例使用 multimodalembedding@001 限定的模型名称作为模型 ID 来生成多模态图片嵌入：
- 使用
psql连接到数据库。 - 创建并启用
google_ml_integration扩展程序。 生成多模态图片嵌入：
SELECT ai.image_embedding( model_id => 'multimodalembedding@001', image => 'IMAGE_PATH_OR_TEXT', mimetype => 'MIMETYPE');
替换以下内容：
- IMAGE_PATH_OR_TEXT 和图片的 Cloud Storage 路径，例如
gs://cymbal_user_data/image-85097193-cd9788aacebb.jpeg，以转换为图片的矢量嵌入或 base64 字符串。 - 将 MIMETYPE 替换为图片的 MIME 类型。
排名模型
本部分介绍了如何注册内置支持的 semantic-ranker-512-002 Vertex AI 排名模型。semantic-ranker-512-002 和 semantic-ranker-512-003 模型都内置了此功能。
Vertex AI 排名模型
本部分介绍了如何使用模型端点管理注册排名端点。
如需注册 semantic-ranker-512-002 模型端点，请完成以下步骤：
创建一个与 AlloyDB 服务账号不同的服务账号。
在您要注册排名模型端点的项目中启用 Discovery Engine API。
向服务账号授予以下角色：
Discovery Engine Admin (roles/discoveryengine.admin)Vertex AI Administrator (roles/aiplatform.admin)
向服务账号授予以下服务账号角色：
Service Account Token Creator role (roles/iam.serviceAccountTokenCreator)Service Account User role (roles/iam.serviceAccountUser)
为服务账号生成有效期更长的访问令牌。
gcloud auth print-access-token \ --impersonate-service-account="service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \ --lifetime=43200创建存储在 Secret Manager 中的 Secret：
CALL google_ml.create_sm_secret( secret_id => 'SECRET_ID', secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/latest;替换以下内容：
SECRET_ID：您设置的 Secret ID，随后在注册模型端点时会用到，例如key1。SECRET_MANAGER_SECRET_ID：您创建 Secret 时在 Secret Manager 中设置的 Secret ID。PROJECT_ID：您的 Google Cloud 项目的 ID。VERSION_NUMBER：Secret ID 的版本号。由于系统会使用最新的 Secret 版本，因此当您的 Secret 令牌过期且您在 Secret Manager 中更新该令牌时，您无需再次在 AlloyDB 中更新版本。
调用 create model 函数以添加模型端点：
CALL google_ml.create_model( model_id => 'semantic-ranker-512-002', model_type => 'reranking', model_provider => 'custom', model_request_url => 'https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/rankingConfigs/default_ranking_config:rank', model_qualified_name => 'semantic-ranker-512@002', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID', model_in_transform_fn => 'google_ml.vertexai_reranking_input_transform', model_out_transform_fn => 'google_ml.vertexai_reranking_output_transform', generate_headers_fn => 'google_ml.vertexai_reranking_header_gen_fn');将 PROJECT_ID 替换为您的项目 ID。
通用模型
本部分介绍了如何注册托管式模型提供程序（例如 Hugging Face、OpenAI、Vertex AI、Anthropic 或任何其他提供程序）上提供的任何通用模型端点。本部分提供了一些示例，展示了如何注册托管在 Hugging Face 上的通用模型端点、Vertex AI Model Garden 中的通用 gemini-pro 模型以及 claude-haiku 模型端点。
只要输入和输出采用 JSON 格式，您就可以注册任何通用模型端点。根据模型端点元数据，您可能需要生成 HTTP 标头或定义请求网址。
如需详细了解预注册的通用模型和内置支持的模型，请参阅支持的模型。
通用 Gemini 模型
本部分介绍了如何注册通用 Gemini 模型。
gemini-1.5-pro 型号
由于某些 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 中的 Secret 以进行身份验证。如果您已为任何其他 OpenAI 模型创建 Secret，则可以重复使用相同的 Secret。
调用存储在 Secret Manager 中的 Secret：
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：您设置的 Secret ID，随后在注册模型端点时会用到。SECRET_MANAGER_SECRET_ID：您创建 Secret 时在 Secret Manager 中设置的 Secret ID。PROJECT_ID：您的 Google Cloud 项目的 ID。VERSION_NUMBER：Secret ID 的版本号。
调用 create model 函数以注册
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()过程中使用的 Secret ID。
Anthropic 通用模型
以下示例会添加 claude-3-opus-20240229 模型端点。模型端点管理功能提供了注册 Anthropoic 模型所需的标头函数。
- 使用
psql连接到数据库。 创建并启用
google_ml_integration扩展程序。Secret Manager
- 将 Bearer 令牌作为 Secret 添加到 Secret Manager 以进行身份验证。
调用存储在 Secret Manager 中的 Secret：
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：您设置的 Secret ID，随后在注册模型端点时会用到。SECRET_MANAGER_SECRET_ID：您创建 Secret 时在 Secret Manager 中设置的 Secret ID。PROJECT_ID：您的 Google Cloud 项目的 ID。VERSION_NUMBER：Secret ID 的版本号。
调用 create model 函数以注册
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：Anthropic API 密钥。ANTHROPIC_VERSION（可选）：您要使用的特定模型版本，例如2023-06-01。
调用 create model 函数以注册
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。
如需了解详情，请参阅如何为通用模型端点调用预测。