本页面显示了 AlloyDB Omni 版本 15.7.0 的文档。
前往 AlloyDB Omni 文档版本，选择其他版本。

此页面由 Cloud Translation API 翻译。

模型端点管理参考文档

本页列出了 google_ml_integration 扩展程序提供的用于注册和管理模型端点以及使用模型端点管理功能的不同函数的参数。

您必须先将 google_ml_integration.enable_model_support 数据库标志设置为 on，然后才能开始使用该扩展程序。

如需了解详情，请参阅将 AlloyDB Omni 与 AI 模型搭配使用，实现模型端点管理。

模型

请参阅此参考文档，了解用于管理模型端点的函数的参数。

`google_ml.create_model()` 函数

以下示例展示了如何调用用于注册模型端点元数据的 google_ml.create_model() SQL 函数：

  CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

参数	必填	说明
`MODEL_ID`	所有模型端点都需要	您定义的模型端点的唯一 ID。
`REQUEST_URL`	对于其他内置支持的文本嵌入模型端点，此参数为可选	添加其他文本嵌入和通用模型端点时，使用的特定于模型的端点。对于 AlloyDB for PostgreSQL，请提供 `https` 网址。该函数为内置模型端点生成的请求网址会引用集群的项目和区域或位置。如果您要引用其他项目，请务必明确指定 `model_request_url`。如需查看 Vertex AI 模型端点的请求网址列表，请参阅 Vertex AI 模型端点请求网址。对于自定义托管的模型端点，请确保可以从 AlloyDB 所在的网络访问该模型端点。
`PROVIDER_ID`	内置支持的文本嵌入模型端点必需	模型端点的提供方。默认值为 `custom`。设置为以下某个值： `google`（适用于 Vertex AI 模型端点） `open_ai`（适用于 OpenAI 模型端点） `hugging_face`（适用于 Hugging Face 模型端点） `anthropic`（适用于 Anthropic 模型端点） `custom`（对于其他提供商）
`MODEL_TYPE`	对于通用模型端点，此参数为可选参数	模型类型。设置为以下其中一项： `text_embedding`（适用于文本嵌入模型端点） `generic`（适用于所有其他模型端点）
`MODEL_QUALIFIED_NAME`	对于内置支持的文本嵌入模型，此参数为必需参数；对于其他模型端点，此参数为可选参数	内置支持的文本嵌入模型的完全限定名称。如需了解必须为预注册模型使用的 Vertex AI 合格名称，请参阅预注册的 Vertex AI 模型。如需了解必须为内置支持的 OpenAI 模型使用的合格名称，请参阅内置支持的模型
`AUTH_TYPE`	可选，除非模型端点有特定的身份验证要求	模型端点使用的身份验证类型。对于 Vertex AI 模型，您可以将其设置为 `alloydb_service_agent_iam`；对于其他提供商（如果它们使用 Secret Manager 进行身份验证），则可以将其设置为 `secret_manager`。如果您使用的是身份验证标头，则无需设置此值。
`AUTH_ID`	不针对 Vertex AI 模型端点进行设置；对于在 Secret Manager 中存储 Secret 的所有其他模型端点，此属性为必需属性	您设置的 Secret ID，之后会在注册模型端点时使用。
`GENERATE_HEADER_FUNCTION`	可选	用于生成自定义标头的函数的名称。对于 Anthropic 模型，模型端点管理提供了一个 `google_ml.anthropic_claude_header_gen_fn` 函数，您可以将其用于默认版本。此函数的签名取决于您使用的预测函数。请参阅头文件生成函数。
`INPUT_TRANSFORM_FUNCTION`	对于内置支持的文本嵌入模型端点，此参数为可选参数；对于通用模型端点，请勿设置此参数	用于将相应预测函数的输入转换为特定于模型的输入的函数。请参阅转换函数。
`OUTPUT_TRANSFORM_FUNCTION`	对于内置支持的文本嵌入模型端点，此参数为可选参数；对于通用模型端点，请勿设置此参数	用于将模型专用输出转换为预测函数输出的函数。请参阅转换函数。

`google_ml.alter_model()`

以下示例展示了如何调用用于更新模型端点元数据的 google_ml.alter_model() SQL 函数：

    CALL
    google_ml.alter_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

如需了解您必须为每个参数设置的值，请参阅创建模型。

`google_ml.drop_model()` 函数

以下示例展示了如何调用用于删除模型端点的 google_ml.drop_model() SQL 函数：

  CALL google_ml.drop_model('MODEL_ID');

参数	说明
`MODEL_ID`	您定义的模型端点的唯一 ID。

`google_ml.list_model()` 函数

以下示例展示了如何调用用于列出模型端点信息的 google_ml.list_model() SQL 函数：

  SELECT google_ml.list_model('MODEL_ID');

参数	说明
`MODEL_ID`	您定义的模型端点的唯一 ID。

`google_ml.model_info_view` 个视图

以下代码展示了如何调用用于列出所有模型端点的模型端点信息的 google_ml.model_info_view 视图：

  SELECT * FROM google_ml.model_info_view;

Secret

请参阅此参考文档，了解用于管理 Secret 的函数的参数。

`google_ml.create_sm_secret()` 函数

以下示例展示了如何调用用于添加在 Secret Manager 中创建的密钥的 google_ml.create_sm_secret() SQL 函数：

    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，之后会在注册模型端点时使用。
`PROJECT_ID`	包含该密钥的 Google Cloud 项目的 ID。
`SECRET_MANAGER_SECRET_ID`	您在 Secret Manager 中创建 Secret 时设置的 Secret ID。
`VERSION_NUMBER`	Secret ID 的版本号。

`google_ml.alter_sm_secret()` 函数

以下示例展示了如何调用用于更新 Secret 信息的 google_ml.alter_sm_secret() SQL 函数：

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

如需了解您必须为每个参数设置的值，请参阅创建 Secret。

`google_ml.drop_sm_secret()` 函数

以下示例展示了如何调用用于删除密钥的 google_ml.drop_sm_secret() SQL 函数：

  CALL google_ml.drop_sm_secret('SECRET_ID');

参数	说明
`SECRET_ID`	您设置的密钥 ID，之后在注册模型端点时使用。

预测函数

请参阅此参考文档，了解用于生成嵌入或调用预测的函数的参数。

`google_ml.embedding()` 函数

以下展示了如何生成嵌入：

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');

参数	说明
`MODEL_ID`	您定义的模型端点的唯一 ID。
`CONTENT`	要转换为向量嵌入的文本。

如需查看用于生成文本嵌入的 SQL 查询示例，请参阅 AlloyDB Omni 的转换函数示例。

`google_ml.predict_row()` 函数

以下代码展示了如何调用预测：

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

参数	说明
`MODEL_ID`	您定义的模型端点的唯一 ID。
`REQUEST_BODY`	预测函数的参数，采用 JSON 格式。

如需查看用于调用预测的 SQL 查询示例，请参阅 AlloyDB Omni 示例。

转换函数

请参阅此参考文档，了解输入和输出转换函数的参数。

输入转换函数

以下是文本嵌入模型端点的预测函数签名：

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

参数	说明
`INPUT_TRANSFORM_FUNCTION`	用于将相应预测函数的输入转换为特定于模型端点的输入的函数。

输出转换函数

以下是文本嵌入模型端点的预测函数签名：

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];

参数	说明
`OUTPUT_TRANSFORM_FUNCTION`	用于将特定于模型端点的输出转换为预测函数输出的函数。

转换函数示例

如需更好地了解如何为模型端点创建转换函数，请考虑一个需要 JSON 输入和输出的自托管文本嵌入模型端点。

以下 c网址请求示例会根据问题和模型端点创建嵌入：

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json" 
    -d '{"prompt": ["AlloyDB Embeddings"]}'

系统会返回以下示例响应：

[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]

根据此输入和响应，我们可以推断出以下内容：

该模型需要通过 prompt 字段接收 JSON 输入。此字段接受输入数组。由于 google_ml.embedding() 函数是行级函数，因此它一次只能接受一个文本输入。因此，您需要创建一个输入转换函数，用于构建包含单个元素的数组。
模型的回答是一个嵌入数组，每个输入提示对应一个嵌入。由于 google_ml.embedding() 函数是行级函数，因此它一次只能返回单个输入。因此，您需要创建一个输出转换函数，以便从数组中提取嵌入。

以下示例展示了在模型端点注册到模型端点管理时，用于此模型端点的输入和输出转换函数：

输入转换函数

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;
$$;

输出转换函数

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;
$$;

HTTP 标头生成函数

以下是标头生成函数的签名，可在注册其他文本嵌入模型端点时与 google_ml.embedding() 预测函数搭配使用。

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

对于 google_ml.predict_row() 预测函数，签名如下：

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;

参数	说明
`GENERATE_HEADERS`	用于生成自定义标头的函数。您还可以在注册模型端点时传递标头生成函数生成的授权标头。

标头生成函数示例

如需更好地了解如何创建一个函数，以便以 JSON 键值对的形式生成用作 HTTP 标头的输出，请考虑使用自托管文本嵌入模型端点。

以下 c网址请求示例会传递模型端点使用的 version HTTP 标头：

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["AlloyDB Embeddings"]}'

该模型需要通过 version 字段输入文本，并以 JSON 格式返回版本值。以下示例展示了在向模型端点管理注册此文本嵌入模型端点时，用于该端点的标头生成函数：

CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN json_build_object('version', '2024-01-01')::JSON;
END;
$$;

使用 API 密钥的标头生成函数

以下示例展示了如何使用 API 密钥设置身份验证。

嵌入模型

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

将 API_KEY 替换为模型提供方的 API 密钥。

通用模型

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'anthropic-version', '2023-06-01')::JSON;
END;
$$;

将 API_KEY 替换为模型提供方的 API 密钥。

请求网址生成

使用请求网址生成函数推断内置支持的模型端点的请求网址。以下是此函数的签名：

CREATE OR REPLACE FUNCTION GENERATE_REQUEST_URL(provider google_ml.model_provider, model_type google_ml.MODEL_TYPE, model_qualified_name VARCHAR(100), model_region VARCHAR(100) DEFAULT NULL)

参数	说明
`GENERATE_REQUEST_URL`	用于为内置支持的模型端点生成由扩展程序生成的请求网址的函数。

支持的模型

您可以使用模型端点管理功能注册任何文本嵌入或通用模型端点。模型端点管理还包括预注册的 Vertex AI 模型和内置支持的模型。如需详细了解不同的模型类型，请参阅模型类型。

预注册的 Vertex AI 模型

模型类型	模型 ID	扩展程序版本
`generic`	`gemini-1.5-pro:streamGenerateContent` `gemini-1.5-pro:generateContent` `gemini-1.0-pro:generateContent`	1.4.2 版及更高版本
`text_embedding`	`textembedding-gecko` `text-embedding-gecko@001`	1.3 版及更高版本

内置支持的模型

Vertex AI

限定的模型名称	模型类型
`text-embedding-gecko@001`	`text-embedding`
`text-embedding-gecko@003`	`text-embedding`
`text-embedding-004`	`text-embedding`
`text-embedding-005`	`text-embedding`
`text-embedding-preview-0815`	`text-embedding`
`text-multilingual-embedding-002`	`text-embedding`

OpenAI

限定的模型名称	模型类型
`text-embedding-ada-002`	`text-embedding`
`text-embedding-3-small`	`text-embedding`
`text-embedding-3-large`	`text-embedding`

Anthropic

限定的模型名称	模型类型
`claude-3-opus-20240229`	`generic`
`claude-3-sonnet-20240229`	`generic`
`claude-3-haiku-20240307`	`generic`

模型端点管理参考文档

模型

google_ml.create_model() 函数

google_ml.alter_model()

google_ml.drop_model() 函数

google_ml.list_model() 函数

google_ml.model_info_view 个视图

Secret

google_ml.create_sm_secret() 函数

google_ml.alter_sm_secret() 函数

google_ml.drop_sm_secret() 函数

预测函数

google_ml.embedding() 函数

google_ml.predict_row() 函数

转换函数

输入转换函数

输出转换函数

转换函数示例

输入转换函数

输出转换函数

HTTP 标头生成函数

标头生成函数示例

使用 API 密钥的标头生成函数

嵌入模型

通用模型

请求网址生成

支持的模型

预注册的 Vertex AI 模型

内置支持的模型

Vertex AI

OpenAI

Anthropic

`google_ml.create_model()` 函数

`google_ml.alter_model()`

`google_ml.drop_model()` 函数

`google_ml.list_model()` 函数

`google_ml.model_info_view` 个视图

`google_ml.create_sm_secret()` 函数

`google_ml.alter_sm_secret()` 函数

`google_ml.drop_sm_secret()` 函数

`google_ml.embedding()` 函数

`google_ml.predict_row()` 函数