本页面介绍了 AlloyDB Omni 版本 15.7.0。选择适用于其他版本的文档。

模型端点管理参考文档

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

您必须先将 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 存储在 Secret Manager 中的其他模型端点，必须设置此属性。	您设置的秘密 ID，随后在注册模型端点时会使用该 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()` 函数

以下示例展示了如何调用 google_ml.create_sm_secret() SQL 函数，该函数用于添加在 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，随后在注册模型端点时会使用该 ID。
`PROJECT_ID`	包含 Secret 的 Google Cloud 项目的 ID。
`SECRET_MANAGER_SECRET_ID`	您创建 Secret 时在 Secret Manager 中设置的 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()` 函数

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

  CALL google_ml.drop_sm_secret('SECRET_ID');

参数	说明
`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 查询示例，请参阅使用通用模型调用预测。

转换函数

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

输入转换函数

下方显示了文本嵌入模型端点的预测函数签名：

  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 输入和输出的自定义托管文本嵌入模型端点。

以下示例 cURL 请求会根据提示和模型端点创建嵌入：

  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 标头）的函数，请考虑使用自定义托管的文本嵌入模型端点。

以下示例 cURL 请求会传递 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()` 函数