在 AlloyDB Omni 中注册和调用远程 AI 模型

预览 — Model endpoint management

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

如需使用模型调用预测或生成嵌入，请向模型端点管理注册模型端点。

如需详细了解 google_ml.create_model() 函数，请参阅模型端点管理参考文档。

在向模型端点管理服务注册模型端点之前，如果您的模型端点需要身份验证，您必须启用 google_ml_integration 扩展程序并根据模型提供程序设置身份验证。

确保您使用 postgres 默认用户名访问数据库。

启用扩展程序

您必须先添加并启用 google_ml_integration 扩展程序，然后才能开始使用关联的函数。若要进行模型端点管理，您需要安装 google_ml_integration 扩展程序。

1. 使用 psql 连接到数据库。

2. 可选：如果已安装 google_ml_integration 扩展程序，请对其进行更改以更新到最新版本：

       ALTER EXTENSION google_ml_integration UPDATE;
   

3. 使用 psql 添加 google_ml_integration 扩展程序：

     CREATE EXTENSION google_ml_integration;
   

4. 可选：向非超级 PostgreSQL 用户授予管理模型元数据的权限：

     GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;
   

   将 NON_SUPER_USER 替换为非超级 PostgreSQL 用户名。

5. 在数据库上启用模型端点管理：

     ALTER SYSTEM SET google_ml_integration.enable_model_support=on;
     SELECT pg_reload_conf();
   

设置身份验证

以下部分介绍了如何在添加 Vertex AI 模型端点或其他提供商的模型端点之前设置身份验证。

设置 Vertex AI 身份验证

如需使用 Google Vertex AI 模型端点，您必须向安装 AlloyDB Omni 时使用的服务账号添加 Vertex AI 权限。如需了解详情，请参阅配置 AlloyDB Omni 安装以查询基于云的模型。

为其他模型提供方设置身份验证

对于 Vertex AI 模型以外的所有模型，您都可以将 API 密钥或 Bearer 令牌存储在 Secret Manager 中。如果您的模型端点不通过 Secret Manager 处理身份验证（例如，如果您的模型端点使用 HTTP 标头传递身份验证信息或根本不使用身份验证），则此步骤是可选的。

本部分介绍了如果您使用的是 Secret Manager，如何设置身份验证。

如需创建和使用 API 密钥或 Bearer 令牌，请完成以下步骤：

1. 在 Secret Manager 中创建 Secret。如需了解详情，请参阅创建 Secret 并访问 Secret 版本。

   Secret 名称和 Secret 路径用于 google_ml.create_sm_secret() SQL 函数。

2. 向 AlloyDB 集群授予访问该 Secret 的权限。

     gcloud secrets add-iam-policy-binding 'SECRET_ID' \
         --member="serviceAccount:SERVICE_ACCOUNT_ID" \
         --role="roles/secretmanager.secretAccessor"
   

   替换以下内容：

   • SECRET_ID：Secret Manager 中的 Secret ID。

   • SERVICE_ACCOUNT_ID：您在上一步中创建的服务账号的 ID。确保此账号与您在安装 AlloyDB Omni 时使用的账号相同。其中包括完整的 PROJECT_ID.iam.gserviceaccount.com 后缀。例如：[e-mail]

     您还可以在项目级别向服务账号授予此角色。如需了解详情，请参阅添加 Identity and Access Management 政策绑定

内置支持的文本嵌入模型

本部分介绍了如何注册模型端点管理提供内置支持的模型端点。

Vertex AI 嵌入模型

模型端点管理功能为 Vertex AI 的所有 text-embedding-gecko 模型版本提供内置支持。使用限定名称将模型版本设为 textembedding-gecko@001 或 textembedding-gecko@002。

由于 textembedding-gecko 和 textembedding-gecko@001 模型端点 ID 已预先注册到模型端点管理，因此您可以直接将它们用作模型 ID。对于这些模型，该扩展程序会自动设置默认的转换函数。

如需注册 textembedding-gecko@002 模型端点版本，请完成以下步骤：

对于 AlloyDB Omni，请确保您已设置 AlloyDB Omni 以查询基于云的 Vertex AI 模型。

1. 创建并启用 google_ml_integration 扩展程序。

2. 使用 psql 连接到数据库。

3. 创建并启用 google_ml_integration 扩展程序。

4. 调用 create model 函数以添加 textembedding-gecko@002 模型端点：

   CALL
     google_ml.create_model(
       model_id => 'textembedding-gecko@002',
       model_provider => 'google',
       model_qualified_name => 'textembedding-gecko@002',
       model_type => 'text_embedding',
       model_auth_type => 'alloydb_service_agent_iam');
   
     The request URL that the function generates refers to the project associated with the AlloyDB Omni service account. If you want to refer to another project, then ensure that you specify the `model_request_url` explicitly.
   

Open AI 文本嵌入模型

模型端点管理为 OpenAI 的 text-embedding-ada-002 模型提供了内置支持。google_ml_integration 扩展程序会自动设置默认转换函数，并调用对远程模型的调用。

以下示例添加了 text-embedding-ada-002 OpenAI 模型端点。

1. 使用 psql 连接到数据库。
2. 创建并启用 google_ml_integration 扩展程序。
3. 将 OpenAI API 密钥添加为 Secret Manager 中的 Secret 以进行身份验证。

4. 调用存储在 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 Manager 中创建 Secret 时设置的 Secret ID。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • VERSION_NUMBER：密文 ID 的版本号。

5. 调用 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 标头或定义端点。

自定义托管的文本嵌入模型

本部分介绍了如何注册自托管模型端点，以及如何创建转换函数和（可选）自定义 HTTP 标头。AlloyDB Omni 支持所有自定义托管的模型端点，无论其托管位置如何。

以下示例添加了由 Cymbal 托管的 custom-embedding-model 自定义模型端点。cymbal_text_input_transform 和 cymbal_text_output_transform 转换函数用于将模型的输入和输出格式转换为预测函数的输入和输出格式。

如需注册自托管文本嵌入模型端点，请完成以下步骤：

1. 使用 psql 连接到数据库。

2. 创建并启用 google_ml_integration 扩展程序。

3. 可选：将 API 密钥添加为 Secret Manager 中的 Secret 以进行身份验证。

4. 调用存储在 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 Manager 中创建 Secret 时设置的 Secret ID。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • VERSION_NUMBER：密文 ID 的版本号。
   注意： Secret Manager 默认会为身份验证生成 Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER 标头。如果此格式与模型端点的授权 Bearer 令牌格式匹配，则您无需使用标头生成函数生成授权标头。

5. 根据文本嵌入模型端点的预测函数的以下签名，创建输入和输出转换函数。如需详细了解如何创建转换函数，请参阅转换函数示例。

   以下是特定于 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;
   $$;
   

6. 调用 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。
   • MODEL_QUALIFIED_NAME：如果您的模型端点使用限定名称，则必填。完全限定名称（如果模型端点有多个版本）。
   • SECRET_ID：您之前在 google_ml.create_sm_secret() 过程中使用的 Secret ID。

OpenAI Text Embedding 3 小型和大型模型

您可以使用特定于模型端点的嵌入预测函数和转换函数注册 OpenAI text-embedding-3-small 和 text-embedding-3-large 模型端点。以下示例展示了如何注册 OpenAI text-embedding-3-small 模型端点。

如需注册 text-embedding-3-small 嵌入模型端点，请执行以下操作：

1. 使用 psql 连接到数据库。
2. 创建并启用 google_ml_integration 扩展程序。
3. 将 OpenAI API 密钥添加为 Secret Manager 中的 Secret 以进行身份验证。如果您已为任何其他 OpenAI 模型创建 Secret，则可以重复使用同一 Secret。

4. 调用存储在 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：您设置的密钥 ID，之后会在注册模型端点时使用。
   • SECRET_MANAGER_SECRET_ID：您在 Secret Manager 中创建 Secret 时设置的 Secret ID。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • VERSION_NUMBER：密文 ID 的版本号。

5. 根据文本嵌入模型预测函数的以下签名，创建输入和输出转换函数。如需详细了解如何创建转换函数，请参阅转换函数示例。如需了解 OpenAI 模型端点预期的输入和输出格式，请参阅嵌入。

   以下是 text-embedding-ada-002、text-embedding-3-small 和 text-embedding-3-large OpenAI 文本嵌入模型端点的转换函数示例。

   -- Input Transform Function corresponding to openai_text_embedding model endpoint family
   CREATE OR REPLACE FUNCTION openai_text_input_transform(model_id VARCHAR(100), input_text TEXT)
   RETURNS JSON
   LANGUAGE plpgsql
   AS $$
   #variable_conflict use_variable
   DECLARE
     transformed_input JSON;
     model_qualified_name TEXT;
   BEGIN
     SELECT google_ml.model_qualified_name_of(model_id) INTO model_qualified_name;
     SELECT json_build_object('input', input_text, 'model', model_qualified_name)::JSON INTO transformed_input;
     RETURN transformed_input;
   END;
   $$;
   
   -- Output Transform Function corresponding to openai_text_embedding model endpoint family
   CREATE OR REPLACE FUNCTION openai_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->'data'->0->'embedding')) INTO transformed_output;
     RETURN transformed_output;
   END;
   $$;
   

6. 调用 create model 函数以注册 text-embedding-3-small 嵌入模型端点：

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_provider => 'open_ai',
       model_type => 'text_embedding',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID',
       model_qualified_name => 'text-embedding-3-small',
       model_in_transform_fn => 'openai_text_input_transform',
       model_out_transform_fn => 'openai_text_output_transform');
   

   替换以下内容：

   • MODEL_ID：您定义的模型端点的唯一 ID，例如 openai-te-3-small。此模型 ID 用于引用模型端点生成嵌入或调用预测所需的元数据。
   • SECRET_ID：您之前在 google_ml.create_sm_secret() 过程中使用的 Secret ID。

如需了解详情，请参阅如何为其他文本嵌入模型端点生成嵌入。

通用模型

本部分介绍了如何注册托管式模型提供商（例如 Hugging Face、OpenAI、Vertex AI 或任何其他提供商）上提供的任何通用模型端点。本部分展示了注册托管在 Hugging Face 上的通用模型端点以及 Vertex AI Model Garden 中不受内置支持的通用 gemini-pro 模型的示例。

只要输入和输出采用 JSON 格式，您就可以注册任何通用模型端点。根据模型端点元数据，您可能需要生成 HTTP 标头或定义端点。

Hugging Face 上的通用模型

以下示例展示了如何添加托管在 Hugging Face 上的 facebook/bart-large-mnli 自定义分类模型端点。

1. 使用 psql 连接到数据库。
2. 创建并启用 google_ml_integration 扩展程序。
3. 将 Bearer 令牌作为 Secret 添加到 Secret Manager 以进行身份验证。

4. 调用存储在 Secret Manager 中的 Secret：

   CALL
     google_ml.create_sm_secret(
       secret_id => 'SECRET_ID',
       secret_path => 'projects/project-id/secrets/SECRE_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

   替换以下内容：

   • SECRET_ID：您设置的密钥 ID，之后会在注册模型端点时使用。
   • SECRET_MANAGER_SECRET_ID：您在 Secret Manager 中创建 Secret 时设置的 Secret ID。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • VERSION_NUMBER：密文 ID 的版本号。

5. 调用 create model 函数以注册 facebook/bart-large-mnli 模型端点：

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_provider => 'custom',
       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。

Gemini 模型

确保您已设置 AlloyDB Omni 以查询基于云的 Vertex AI 模型。

以下示例会添加 Vertex AI Model Garden 中的 gemini-1.0-pro 模型端点。

1. 使用 psql 连接到数据库。
2. 创建并启用 google_ml_integration 扩展程序。

3. 调用 create model 函数以注册 gemini-1.0-pro 模型：

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.0-pro:streamGenerateContent',
       model_provider => 'google',
       model_auth_type => 'alloydb_service_agent_iam');
   

   替换以下内容：

   • MODEL_ID：您定义的模型端点的唯一 ID，例如 gemini-1。此模型 ID 用于引用模型端点生成嵌入或调用预测所需的元数据。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。

如需了解详情，请参阅如何为通用模型端点调用预测。

后续步骤

• 了解模型端点管理参考文档。