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

选择文档版本： 15.5.2keyboard_arrow_down

• 15.5.5
• 15.5.4
• 15.5.2

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

如需详细了解 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 密钥或不记名令牌存储在 Secret Manager 中。如果您的模型端点不通过 Secret Manager 处理身份验证，则此步骤是可选的（例如，如果您的模型端点使用 HTTP 标头来传递身份验证信息，或者根本不使用身份验证）。

本部分介绍了如何在使用 Secret Manager 时设置身份验证。

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

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 后缀。例如：my-service@my-project.iam.gserviceaccount.com

     您还可以在项目级层向服务账号授予此角色。如需了解详情，请参阅添加 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.
   

打开 AI 文本嵌入模型

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

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

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

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 时在 Secret Manager 中设置的 Secret ID。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • VERSION_NUMBER：Secret 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 添加到 Secret Manager 以进行身份验证。

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 时在 Secret Manager 中设置的 Secret ID。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • VERSION_NUMBER：Secret ID 的版本号。

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 文本嵌入第 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 添加到 Secret Manager 以进行身份验证。如果您已为任何其他 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：您设置的 Secret ID，随后在注册模型端点时会用到。
   • SECRET_MANAGER_SECRET_ID：您创建 Secret 时在 Secret Manager 中设置的 Secret ID。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • VERSION_NUMBER：Secret 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. 将不记名令牌作为 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：您设置的 Secret ID，随后在注册模型端点时会用到。
   • SECRET_MANAGER_SECRET_ID：您创建 Secret 时在 Secret Manager 中设置的 Secret ID。
   • PROJECT_ID：您的 Google Cloud 项目的 ID。
   • VERSION_NUMBER：Secret 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。

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

后续步骤

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