本页列出了 google_ml_integration 扩展程序提供的用于注册和管理模型端点的不同函数的参数。该页面还列出了您可以使用模型端点管理功能管理的 Secret。如需在生产环境中使用 AI 模型，请参阅使用 Cloud SQL 构建生成式 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 |
对于内置支持的文本嵌入模型端点，此参数为可选 |
添加其他文本嵌入和通用模型端点时，使用的特定于模型的端点。 该函数为内置模型端点生成的请求网址会引用集群的项目和区域或位置。如果您要引用其他项目，请务必明确指定 对于自定义托管的模型端点，请确保可以通过互联网访问模型端点。 |
PROVIDER_ID |
内置支持的文本嵌入模型端点必需 | 模型端点的提供方。默认值为 custom。对于 Cloud SQL，如果是 Vertex AI 模型端点，请将提供程序设置为 google；如果是 OpenAI 模型端点，请将提供程序设置为 open_ai；如果是 Anthropic 模型端点，请将提供程序设置为 anthropic；如果是 Hugging Face 模型端点，请将提供程序设置为 hugging_face；如果是自定义托管的模型端点，请将提供程序设置为 custom。 |
MODEL_TYPE |
对于通用模型端点，此参数为可选参数 | 模型类型。对于文本嵌入模型端点，您可以将此值设置为 text_embedding；对于所有其他模型端点，您可以将此值设置为 generic。 |
MODEL_QUALIFIED_NAME |
对于 OpenAI 模型端点，此属性为必需属性；对于其他模型端点，此属性为可选属性 | 如果模型端点有多个版本，或者模型端点定义了该名称，则为完全限定名称，例如 textembedding-gecko@001 或 textembedding-gecko@002。由于 textembedding-gecko@001 模型已预先注册到模型端点管理，因此您可以使用 textembedding-gecko@001 作为模型 ID 生成嵌入。 |
AUTH_TYPE |
可选，除非模型端点有特定的身份验证要求 | 模型端点使用的身份验证类型。对于 Vertex AI 模型，您可以将其设置为 cloudsql_service_agent_iam；对于其他提供商，则可以将其设置为 secret_manager。 |
AUTH_ID |
不针对 Vertex AI 模型端点进行设置；对于在 Secret Manager 中存储 Secret 的所有其他模型端点，此属性为必需属性 | 您设置的 Secret ID，之后会在注册模型端点时使用。 |
GENERATE_HEADER_FUNCTION |
可选 | 您设置用于生成自定义标头的函数名称。此函数的签名取决于 google_ml.predict_row() 函数。请参阅 HTTP 标头生成函数。 |
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 包含 Secret 的项目的 ID。此项目可以与包含您的 Cloud SQL 实例的项目不同。 |
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_ID |
您设置的 Secret ID，之后会在注册模型端点时使用。 |
PROJECT_ID |
Google Cloud 包含 Secret 的项目的 ID。此项目可以与包含您的 Cloud SQL 实例的项目不同。 |
SECRET_MANAGER_SECRET_ID |
您在 Secret Manager 中创建 Secret 时设置的 Secret ID。 |
VERSION_NUMBER |
Secret ID 的版本号。 |
google_ml.drop_sm_secret()
以下示例展示了如何调用用于删除密钥的 google_ml.drop_sm_secret() SQL 函数：
CALL google_ml.drop_sm_secret('SECRET_ID');
| 参数 | 说明 |
|---|---|
SECRET_ID |
您设置的 Secret ID，之后会在注册模型端点时使用。 |
预测函数
请参阅此参考文档，了解用于生成嵌入或调用预测的函数的参数。
google_ml.embedding()
以下展示了如何生成嵌入：
SELECT
google_ml.embedding(
model_id => 'MODEL_ID',
contents => 'CONTENT');
| 参数 | 说明 |
|---|---|
MODEL_ID |
您定义的模型端点的唯一 ID。 |
CONTENT |
要转换为向量嵌入的文本。 |
如需查看用于生成文本嵌入的 SQL 查询示例，请参阅示例。
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 输入和输出的自托管文本嵌入模型端点。
以下 c网址 请求示例会根据问题和模型端点创建嵌入：
curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
-H "Content-Type: application/json"
-d '{"prompt": ["Cloud SQL 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": ["Cloud SQL 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;
$$;
请求网址生成
使用请求网址生成函数推断内置支持的模型端点的请求网址。以下是此函数的签名：
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 |
用于为内置支持的模型端点生成由扩展程序生成的请求网址的函数。 |