此页面由 Cloud Translation API 翻译。

使用模型端点管理功能注册和调用远程 AI 模型

MySQL | PostgreSQL | SQL Server

本页介绍了如何使用模型调用预测或生成嵌入，然后向模型端点管理注册模型端点。

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

准备工作

如果您的模型端点需要身份验证，请启用 google_ml_integration 扩展程序。
根据模型提供程序设置身份验证。
确保您使用 postgres 默认用户名访问数据库。

启用扩展程序

将实例的 google_ml_integration.enable_model_support 数据库标志设置为 on。如需详细了解如何设置数据库标志，请参阅配置数据库标志。
使用 psql 客户端或 Cloud SQL Studio 连接到主实例。
运行以下命令，确保 google_ml_integration 扩展程序已更新到版本 1.4.2：
```
    ALTER EXTENSION google_ml_integration UPDATE TO '1.4.2'
```

使用 psql 添加 google_ml_integration 版本 1.4.2 扩展程序：

  CREATE EXTENSION google_ml_integration VERSION '1.4.2';

可选：向非超级 PostgreSQL 用户授予管理模型元数据的权限：
```
  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;
```
将 NON_SUPER_USER 替换为非超级 PostgreSQL 用户名。

设置身份验证

以下部分介绍了如何在添加托管在 Google Cloud 中的 Vertex AI 模型端点或模型端点之前设置身份验证。

设置 Vertex AI 身份验证

如需使用 Google Vertex AI 模型端点，您必须向用于连接到数据库的基于 IAM 的 Cloud SQL 服务账号添加 Vertex AI 权限。如需详细了解如何与 Vertex AI 集成，请参阅将 Cloud SQL 与 Vertex AI 集成。

为自定义托管的模型设置身份验证

本部分介绍了如果您使用的是 Secret Manager，如何设置身份验证。对于 Vertex AI 模型端点以外的所有模型，您都可以将 API 密钥或 Bearer 令牌存储在 Secret Manager 中。

如果您的模型端点不通过 Secret Manager 处理身份验证，则此部分是可选的。例如，如果您的模型端点使用 HTTP 标头传递身份验证信息或根本不使用身份验证，请勿完成本部分中的步骤。

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

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

Secret 名称和 Secret 路径用于 google_ml.create_sm_secret() SQL 函数。
向 Cloud SQL 实例授予访问该 Secret 的权限。
```
  gcloud secrets add-iam-policy-binding SECRET_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --role="roles/secretmanager.secretAccessor"
```
替换以下内容：
- SECRET_ID：Secret Manager 中的 Secret ID。
- SERVICE_ACCOUNT_EMAIL：基于 IAM 的 Cloud SQL 服务账号的电子邮件地址。如需查找此电子邮件地址，请使用 gcloud sql instances describe INSTANCE_NAME 命令，并将 INSTANCE_NAME 替换为实例的名称。serviceAccountEmailAddress 参数旁边显示的值即电子邮件地址。

内置支持的文本嵌入模型

本部分介绍了如何注册模型端点以进行模型端点管理。

Vertex AI 嵌入模型

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

由于 textembedding-gecko 和 textembedding-gecko@001 模型端点 ID 均已通过模型端点管理功能预注册，因此您可以直接将其中任一 ID 用作模型 ID。对于这些模型，该扩展程序会自动设置默认的转换函数。

确保 Cloud SQL 实例和您要查询的 Vertex AI 模型位于同一区域。

如需注册 textembedding-gecko@002 模型端点，请调用 create_model 函数：

  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 => 'cloudsql_service_agent_iam');

自托管文本嵌入模型

本部分介绍了如何注册托管在 Google Cloud 网络中的自定义模型端点。

添加自托管文本嵌入模型端点需要创建转换函数，还可以选择创建自定义 HTTP 标头。另一方面，添加自定义托管的通用模型端点需要视情况生成自定义 HTTP 标头并设置模型请求网址。

以下示例添加了由 Cymbal 托管的 custom-embedding-model 文本嵌入模型端点，该端点托管在 Google Cloud 中。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 Manager 中创建 Secret 时设置的 Secret ID。
- PROJECT_ID：您的 Google Cloud 项目的 ID。
- VERSION_NUMBER：密文 ID 的版本号。
注意：Secret Manager 默认会生成 Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER 标头以进行身份验证。如果此格式与模型端点的授权令牌格式匹配，则您无需使用标头生成函数生成授权标头。

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

以下是特定于 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 Model Garden 中不受内置支持的通用 gemini-pro 模型端点。您可以注册托管在 Google Cloud 中的任何通用模型端点。

Cloud SQL 仅支持通过 Vertex AI Model Garden 提供的模型端点，以及在 Google Cloud 网络中托管的模型端点。

Gemini 模型

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

如需注册 gemini-1.0-pro 模型端点，请调用 create model 函数：

```sql
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 => 'cloudsql_service_agent_iam');
```

Replace the following:
* <code><var>MODEL_ID</var></code>: a unique ID for the model endpoint that you define (for example,<br> `gemini-1`). This model ID is referenced for metadata that the model endpoint needs to generate embeddings or invoke predictions.
* <code><var>PROJECT_ID</var></code>: the ID of your Google Cloud project.

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

后续步骤

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