使用模型端点管理注册和调用远程 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 密钥或不记名令牌存储在 Secret Manager 中。

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

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

在 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。对于这些模型，扩展程序会自动设置默认转换函数。

确保 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 时在 Secret Manager 中设置的 Secret ID。
- PROJECT_ID：您的 Google Cloud 项目的 ID。
- VERSION_NUMBER：Secret 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.

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

后续步骤

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