使用经过优化的 AI 函数加速查询

您可以在 AlloyDB for PostgreSQL 中使用经过优化的 AI 函数，从而降低运营成本并提高查询响应速度。优化后的 AI 函数会使用更小、更快的代理模型处理大多数查询，并且仅在必要时才回退到更大的 LLM，从而最大限度地减少对大语言模型 (LLM) 的使用，以执行逐行分类或过滤任务。

注意：经过优化的 AI 函数支持在单个查询中使用多个 ai.if() 子句，前提是每个 ai.if() 函数的所有实参都引用单个表别名。默认情况下，用于控制远程 LLM 回退的 google_ml_integration.proxy_models_enable_llm_fallback 标志处于启用状态 (on)。

由于对 LLM 的远程调用，ai.if() 等 AlloyDB AI 函数可能会出现高延迟。优化后的函数通过使用较小的本地训练代理模型（例如逻辑回归模型）来处理查询，从而解决此延迟问题。这些模型使用 LLM 的输出作为真实来源，基于您的数据样本进行训练。

您可以使用 google_ml_integration.proxy_models_enable_accuracy_check 标志（默认设置为 off）配置在运行时执行的准确性检查。准确率检查会使用基准 LLM 评估查询中的行样本，以确保准确率达到 google_ml_integration.proxy_models_f1_score_threshold 标志定义的阈值。如果准确率检查失败，查询会回退到使用 LLM（如果停用了回退，则会抛出错误）。

优化后的 AI 函数工作流

当您使用经过优化的 AI 函数并将 google_ml_integration.proxy_models_enable_accuracy_check 标志设置为 true 时，AlloyDB 会执行以下操作。

注意：如果 google_ml_integration.proxy_models_enable_llm_fallback 标志设置为 off，则当代理模型未经训练或未通过准确率检查时，查询会返回错误，而不是调用远程 LLM。

1. 安排训练：当您对表执行包含 ai.if() 函数的查询时，AlloyDB 会自动安排在后台训练轻量级代理模型。

2. 回退到 LLM：在代理模型训练期间，或者如果代理模型不可用，AlloyDB 会回退到使用远程 LLM 来评估查询（除非停用了回退）。

3. 执行优化后的查询：模型训练完成后，AlloyDB 会使用经过训练的代理模型在本地处理后续查询，从而提升性能。

下图展示了使用优化后的 AI 函数处理查询的逻辑流程：

准备工作

在使用经过优化的 AI 函数之前，请执行以下操作：

• 使用 psql 连接到数据库。您还可以使用 AlloyDB Studio 以 postgres 用户身份或有权访问数据所在表的用户身份进行连接。

• 验证是否已安装 google_ml_integration 扩展程序 1.6.3 版或更高版本。

  SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
  

  输出类似于以下内容：

   extversion 
  ------------
   1.6.3
  (1 row)
  

  如果未安装该扩展程序，或者安装的版本低于 1.6.3，请更新该扩展程序：

  CREATE EXTENSION IF NOT EXISTS google_ml_integration;
  ALTER EXTENSION google_ml_integration UPDATE;
  

• 将 AlloyDB 配置为与 Gemini Enterprise Agent Platform 搭配使用。如需了解详情，请参阅与代理平台集成。

• 验证以下实例级数据库标志是否已启用。如需了解详情，请参阅支持的数据库标志、用于优化 AI 函数的数据库标志和配置实例的数据库标志。

  • google_ml_integration.enable_model_support
  • google_ml_integration.enable_ai_query_engine
  • google_ml_integration.enable_ai_function_acceleration
  • google_ml_integration.enable_cost_optimized_ai_functions

• 查看后备和准确性验证数据库标志，您可以使用 SQL（SET 或 ALTER DATABASE）在会话或数据库级别配置这些标志：

  • google_ml_integration.proxy_models_enable_llm_fallback：控制在代理模型不可用时，查询是否回退到远程 LLM。此标志默认设置为 on。如果设置为 off，则数据库会抛出错误，而不是回退到远程 LLM。
  • google_ml_integration.proxy_models_enable_accuracy_check：启用针对基准 LLM 的运行时准确率检查。此标志默认设置为 off。

• 查看定期重新训练数据库标志：

  • google_ml_integration.proxy_models_retraining_interval_minutes：控制后台重新训练作业的频率（以分钟为单位）。默认值为 1440（24 小时）。将其设置为 0 会停用定期重新训练。
  • google_ml_integration.proxy_models_retraining_batch_size：控制在单次迭代中重新训练的 模型数量（默认值为 1）。

• 对于 AlloyDB Omni，请验证 shared_preload_libraries 中是否加载了以下扩展程序：

  • google_job_scheduler
  • google_ml_integration

• 为要查询的表生成嵌入。如需了解详情，请参阅为大型表生成和管理自动向量嵌入。

• 请考虑以下要求：

  • 源数据列必须是 TEXT 或 VARCHAR 类型。
  • 为优化后的 AI 函数提供输入的嵌入列必须为 REAL[] 或 VECTOR 类型。
  • 优化后的 AI 函数仅在提供 Agent Platform 生成模型的区域可用。如需查看可用区域的列表，请参阅部署和端点。

执行优化后的查询

请按照以下示例使用 ai.if() 函数执行标准 SELECT 语句：

1. 创建 restaurant_reviews 表。保存源数据的 review 列的类型为 TEXT，用于查询的 review_embedding 列的类型为 VECTOR(768)。

   CREATE TABLE restaurant_reviews (
       id SERIAL,
       name VARCHAR(64),
       city VARCHAR(64),
       review TEXT,
       review_embedding VECTOR(768)
   );
   

2. 使用 ai.initialize_embeddings() 过程为源数据生成向量嵌入：

   CALL ai.initialize_embeddings(
       model_id => 'text-embedding-005',
       table_name => 'restaurant_reviews',
       content_column => 'review',
       embedding_column => 'review_embedding'
   );
   

   必须生成嵌入，因为经过优化的 AI 函数依赖于向量嵌入作为特征输入来训练和评估轻量级代理模型。代理模型不会针对每一行将原始文本发送到远程 LLM，而是直接对向量表示法执行快速本地推理。如果未生成嵌入，AlloyDB 将无法训练代理模型，并会回退到使用远程 LLM 评估所有行。

   请注意以下嵌入要求：

   • 如果嵌入列包含 NULL 值，则 ai.if() 输出的计算结果为 NULL。模型训练和推理都需要有效的嵌入。
   • 如果查询嵌入维度与训练的代理模型中存储的维度不匹配，ai.if() 函数会抛出错误。

   如需详细了解嵌入选项和增量刷新，请参阅为大型表生成和管理自动向量嵌入。

3. 使用 ai.if() 函数运行 SELECT 语句。此查询会自动在后台安排代理模型的训练，以优化 AI 函数：

   SELECT r.name, r.city
   FROM restaurant_reviews r
   WHERE ai.if('Is the following a positive review? Review: ' || r.review, r.review_embedding, 'gemini-3.5-flash-lite')
   GROUP BY r.name, r.city
   HAVING COUNT(*) > 500;
   

   首次执行查询会异步触发训练。在代理模型训练期间，如果 google_ml_integration.proxy_models_enable_llm_fallback 标志设置为 on（默认值），AlloyDB 会回退到使用远程 LLM 评估查询，并返回一条警告，指出优化的 AI 函数尚不可用。如果 google_ml_integration.proxy_models_enable_llm_fallback 设置为 off，则查询会返回错误，而不是回退。

   与同一内容表达式 (content_expr)、嵌入列和表匹配的后续查询会使用经过训练的代理模型进行加速。更新行值、删除行或向表中添加数据不会导致 AlloyDB 回退到 LLM。代理模型会继续在本地处理数据，并通过定期后台重新训练来解决数据偏移问题。

   代理模型由函数类型、表 OID、内容表达式和嵌入列（func_type、table_oid、content_expr、embedding_column）唯一标识。借助此架构，只要 ai.if() 的输入保持不变，您就可以在不同的 SQL 查询之间共享模型。

   在以下情况下，AlloyDB 不会使用现有代理模型，而是会启动新代理模型的后台训练，并回退到远程 LLM（受 google_ml_integration.proxy_models_enable_llm_fallback 标志约束）：

   • ai.if() 中的 CONTENT 表达式发生更改（例如，提示字符串或串联列表达式被修改）。
   • ai.if() 中的 EMBEDDING_COLUMN 名称会发生变化。
   • llm_model_id 参数发生变化。
   • 如果启用了运行时准确率检查，并且代理模型在查询开始时未通过准确率检查。

在线训练和阻塞执行

AlloyDB 支持针对优化函数的在线训练工作流，该工作流由 google_ml_integration.proxy_models_enable_online_training 数据库标志控制。默认情况下，此标志会设置为 off。

启用此标志并执行未经训练的 ai.if() 函数时，查询会触发训练过程并使用阻塞执行。初始查询会主动阻塞并等待后台代理模型训练完成后再继续。这样可确保查询立即利用经过优化的代理模型，从而避免在初始执行时产生远程 LLM 推理费用。

查询阻塞并等待在线训练完成的最长时长由 google_ml_integration.proxy_models_training_wait_timeout 标志控制（以秒为单位，默认值为 60）。如果训练未在此时间间隔内完成，则查询会超时或根据您的回退设置进行回退。

如需启用在线训练，请执行以下操作：

-- Enable online training (blocking execution)
SET google_ml_integration.proxy_models_enable_online_training = on;

-- Set the maximum wait timeout in seconds (default is 60)
SET google_ml_integration.proxy_models_training_wait_timeout = 30;

配置远程 LLM 回退

默认情况下，系统会启用回退到远程 LLM 的功能。如果代理模型未经训练、正在训练或未通过准确率检查，查询会回退到远程 LLM，并产生标准 Agent Platform API 费用。

您可以使用 google_ml_integration.proxy_models_enable_llm_fallback 数据库标志配置回退行为：

• 启用回退功能后（on，默认）：如果代理模型不可用，AlloyDB 会使用远程 LLM 评估查询，并返回警告：

  WARNING: Optimized AI Function is unavailable. Expect reduced performance.
  

• 停用后备机制 (off) 时：如果代理模型不可用或未通过准确率验证，查询会立即引发错误，而不是调用远程 LLM：

  ERROR: Optimized AI Function: Optimized model fallback to LLM prevented by GUC google_ml_integration.proxy_models_enable_llm_fallback
  

如需为当前会话停用 LLM 后备，请执行以下操作：

SET google_ml_integration.proxy_models_enable_llm_fallback = off;

如需为整个数据库停用 LLM 回退，请执行以下操作：

ALTER DATABASE DATABASE_NAME SET google_ml_integration.proxy_models_enable_llm_fallback = off;

将 DATABASE_NAME 替换为您的数据库名称。

配置运行时准确率检查

运行时准确率检查会使用远程 LLM 评估查询中的样本行，以确保代理模型在执行前满足基准准确率要求。

准确率检查由 google_ml_integration.proxy_models_enable_accuracy_check 数据库标志控制（默认处于停用状态）。

如需为当前会话启用准确性检查，请执行以下操作：

SET google_ml_integration.proxy_models_enable_accuracy_check = on;

如需为当前会话停用准确性检查，请执行以下操作：

SET google_ml_integration.proxy_models_enable_accuracy_check = off;

如需为整个数据库启用准确性检查，请执行以下操作：

ALTER DATABASE DATABASE_NAME SET google_ml_integration.proxy_models_enable_accuracy_check = on;

查看现有代理模型

如需检查现有代理模型、查看其训练状态并查看其模型元数据，请查询 google_ml.optimized_functions_view 视图（或其在 ai 架构中的别名 ai.optimized_functions_view）：

SELECT * FROM ai.optimized_functions_view;

如需了解此视图中的列，请参阅 ai.optimized_functions_view 视图。

您可以按 table_name 或 status 过滤此视图，以验证模型是否已完成训练 (READY)，或确定手动重新训练所需的确切 content_expr 和 embedding_column 值。

重新训练和管理代理模型

代理模型是基于初始训练时表中存在的数据进行训练的。如果向表中添加了较新的数据，或者修改或删除了行，则代理模型可能会随着时间的推移而过时。为了在数据发生变化时保持准确性，代理模型可以在后台定期自动重新训练，也可以根据需要手动重新训练。

定期后台重新训练

在具有 32 个或更多 vCPU 且采用默认配置设置的实例上，AlloyDB 可以在后台定期重新训练代理模型。

定期重新训练由以下数据库标志控制：

• google_ml_integration.proxy_models_retraining_interval_minutes：控制后台重新训练作业的频率（以分钟为单位）。默认值为 1440（24 小时）。将其设置为 0 会停用定期重新训练。
• google_ml_integration.proxy_models_retraining_batch_size：控制在单次迭代中重新训练的 模型数量（默认值为 1）。

注意：vCPU 少于 32 个的数据库实例不支持定期后台自动重新训练。在这些情况下，或者当您需要在重大数据更新后立即重新训练时，请使用手动重新训练。

手动重新训练

您可以使用 ai 架构中的函数（或 google_ml 架构中的等效函数）手动重新训练代理模型。

重新训练表的所有模型

如需重新训练与特定表关联的所有代理模型，或重新训练表的经过过滤的模型子集，请调用 ai.retrain_optimized_models()：

SELECT ai.retrain_optimized_models(
  table_name => 'restaurant_reviews',
  embedding_column => 'review_embedding', -- Optional
  content_expr => '(''Is the following a positive review? Review: ''::text || review)', -- Optional
  llm_model_id => 'LLM_MODEL_ID' -- Optional
);

如需查看参数说明，请参阅 ai.retrain_optimized_models() 函数。

按模型 ID 重新训练特定模型

如需使用特定代理模型的唯一模型标识符重新训练该模型，请调用 ai.retrain_optimized_model() 并传入 model_id 参数：

SELECT ai.retrain_optimized_model(model_id => 'MODEL_ID');

如需查看参数说明，请参阅 ai.retrain_optimized_model() 函数。

按模型训练参数重新训练特定模型

如需使用特定代理模型的表名称、内容表达式和嵌入列重新训练该模型，请调用 ai.retrain_optimized_model()：

SELECT ai.retrain_optimized_model(
  table_name => 'restaurant_reviews',
  embedding_column => 'review_embedding',
  content_expr => '(''Is the following a positive review? Review: ''::text || review)',
  llm_model_id => 'LLM_MODEL_ID' -- Optional
);

如需查看参数说明，请参阅 ai.retrain_optimized_model() 函数。

删除代理模型

您可以使用以下函数删除单个代理模型或所有模型。这些操作必须由具有 alloydbsuperuser 权限或管理员授予的权限的用户执行。

如需查找删除特定代理模型所需的内部 model_id，请查询 google_ml.proxy_models_expr_mapping 表：

SELECT model_id, table_oid::regclass, content_expr
FROM google_ml.proxy_models_expr_mapping;

-- Delete a specific proxy model
SELECT ai.delete_optimized_model('com_if_12345_67890');

-- Delete all proxy models and stop the background automated retraining job
CALL ai.delete_all_optimized_models();

监控

您可以监控后台工作器训练作业，并查看模型运行状态。

查看模型训练状态和历史记录

如需验证代理模型是已完成训练、失败还是正在重新训练，请查询 ai.optimized_functions_view：

SELECT table_name, content_expr, status, last_trained_at, training_duration
FROM ai.optimized_functions_view;

status 列指示模型的当前运行状态，并提供以下值：

• READY：代理模型已成功完成训练，可以加速传入的查询。
• UNTRAINED：模型已注册或已安排，但后台训练尚未完成。如果初始后台训练失败，模型将保持 UNTRAINED 状态，查询将回退到远程 LLM（如果停用回退，则会出错）。
• RETRAINING_IN_PROGRESS：正在进行后台重新训练。
• RETRAINING_FAILED：最近一次后台或手动重新训练运行失败。在大多数情况下，如果存在重新训练前的模型权重，AlloyDB 会继续使用这些现有模型权重进行推理。如果现有模型权重不可用（或运行时准确率检查失败），AlloyDB 会回退到使用远程 LLM 评估查询（受 google_ml_integration.proxy_models_enable_llm_fallback 限制），直到模型成功重新训练。

如需详细了解此视图中提供的所有列，请参阅查看现有代理模型。

限制

• 优化后的 AI 函数仅支持 ai.if() 函数。
• 在 vCPU 少于 32 个的数据库实例上，不支持定期在后台自动重新训练代理模型。
• 行级安全性 (RLS)：在对使用行级安全性 (RLS) 政策的表进行训练的模型中，可能会在特定发起用户的权限下进行训练，从而泄露安全信息。已停用在具有 RLS 政策的表上训练代理模型。
• 输入修改：如果您修改了提供给 ai.if() 的来源内容列、嵌入列、提示字符串或基本 LLM 模型 ID，则系统会绕过现有代理模型，并针对该组合发起新的后台训练请求。
• SQL 限制：
  • 查询必须包含有效的 FROM 子句。
  • AI 函数的所有参数都必须来自同一个表别名。
  • 在 ai.if() 表达式中添加列作为嵌入的源列。
  • 请勿将 ai.if() 函数放在子查询或通用表表达式 (CTE) 中。

后续步骤

• 排查优化后的 AI 函数问题。