利用 AI 函数提升查询性能

借助 AI 函数的智能批处理功能，您可以在 AlloyDB for PostgreSQL 中运行使用 AI 函数的查询时优化性能。它提供与基于数组的函数相同或更好的性能，而无需您将查询重写为复杂的数组结构。如需详细了解 AI 函数，请参阅 AI 函数概览。

在标准 PostgreSQL 中，逐行评估 AI 函数会导致每行都产生网络延迟。借助 AlloyDB 中的智能批处理功能，符合条件的 AI 操作会自动进行批处理并分流以进行异步评估，从而让您能够编写标准、易于阅读的 SQL 查询。标准关系过滤条件会在 AI 函数之前进行评估，以确保最佳性能和模型使用。

支持的 AI 函数

AlloyDB 智能批处理支持以下 AI 函数，这些函数在 ai 和 google_ml 架构中均可用：

函数 说明 扩展程序版本
ai.if(prompt text, ...)/google_ml.if(...) 对自然语言布尔值提示进行求值，返回 true 或 false。支持 SELECT 投影、WHERE 过滤条件和 JOIN 子句。 全部
ai.rank(prompt text, ...)/google_ml.rank(...) 计算数值相关性得分 (float)，以指示输入与给定条件的匹配程度。支持 WHERE 过滤条件、ORDER BY、SELECT 和 JOIN 子句。 全部
ai.generate(prompt text, ...)/google_ml.generate(...) 使用基础模型生成自然语言回答或结构化文本。支持 SELECT 投影、WHERE 过滤条件和 JOIN 子句。 全部
ai.analyze_sentiment(input text, ...)/google_ml.analyze_sentiment(...) 分析输入文本的情感，并返回 'positive'、'negative' 或 'neutral'。支持 SELECT 投影、WHERE 过滤条件和 JOIN 子句。 1.6.3
ai.summarize(input text, ...)/google_ml.summarize(...) 总结输入文本。支持 SELECT 投影、WHERE 过滤条件和 JOIN 子句。 1.6.4
ai.agg_summarize(column_name text, ...)/google_ml.agg_summarize(...) 将多行中的文本值汇总成一个摘要。 1.6.4
ai.extract(input text, output_schema text, ...)/google_ml.extract(...)

（预览版；需要设置 google_ml_integration.enable_preview_ai_functions=on）		 从文本中提取结构化实体或键值对属性。支持 SELECT 投影、WHERE 过滤条件和 JOIN 子句。 1.6.1
ai.classify(input text, categories text[][], ...)/google_ml.classify(...)

（预览版；需要设置 google_ml_integration.enable_preview_ai_functions=on）		 将文本归入指定的类别标签。支持 SELECT 投影、WHERE 过滤条件和 JOIN 子句。 1.6.1

如需详细了解 AI 函数的语法和参数，请参阅模型端点管理参考文档。

支持的子句

AI 函数加速功能适用于主要 SQL 子句，无论是单独使用还是组合使用：

  • WHERE 子句：在对选择性非 AI 关系谓词求值后，使用布尔 AI 评估 (ai.if) 过滤行。
  • ORDER BY 子句：在执行排序或限制操作之前，批量计算 AI 相关性分数 (ai.rank)。
  • SELECT 投影：跨结果行对标量 AI 函数（ai.if、ai.rank、ai.generate、ai.analyze_sentiment、ai.summarize、ai.extract 和 ai.classify）进行批处理，并使用 ai.agg_summarize 跨行聚合和汇总文本。
  • JOIN ... ON 条件：使用智能批处理评估 INNER JOIN 操作中的跨表 AI 条件。
  • DML 语句：在 UPDATE、DELETE 和 INSERT ... SELECT 操作（例如 INSERT INTO ... SELECT ai.generate(...) 和 UPDATE ... SET col = ai.generate(...)）中，加速 WHERE 谓词、目标列表和 SET 表达式中的 AI 函数。

支持的参数表达式

提示实参支持标准 SQL 表达式，包括：

  • 列引用（例如 r.review）
  • 与列引用串联的字符串字面量（例如 'Is this a positive review? Review: ' || r.review）
  • 多个列的串联（例如 r.name || ' ' || r.review）
  • 标量 SQL 表达式和函数（例如 COALESCE(r.review, '')、LOWER(r.comments)、SUBSTRING(description FROM 1 FOR 500) 和 CASE 语句）

准备工作

如需在 AlloyDB 中对 AI 函数使用智能批处理，请确保满足以下前提条件：

  1. PostgreSQL 版本：使用 PostgreSQL 17 或更高版本。
  2. 与 Gemini Enterprise Agent Platform 集成：完成与 Gemini Enterprise Agent Platform 集成中的步骤。
  3. 区域可用性：智能批处理在支持默认模型 (gemini-2.5-flash-lite) 或使用 google_ml_integration.default_llm_model 配置的模型的区域中可用。如需了解详情，请参阅受支持的国家/地区。

为 AI 函数启用智能批处理

在 PostgreSQL 18 或更高版本中，AI 函数的智能批处理功能默认处于启用状态。在 PostgreSQL 17 中，该功能默认处于停用状态，必须明确启用。您可以通过实例级层的数据库标志全局配置其行为，也可以使用 SQL SET 命令按会话配置其行为。

配置参数

参数名称 类型 默认 范围 说明
google_ml_integration.enable_ai_function_acceleration 布尔值 PostgreSQL 18：on
PostgreSQL 17：off		 会话、用户或实例 控制查询规划器和执行器是否分流符合条件的 AI 操作以进行智能批处理。如果设置为 off，则查询会使用标准 PostgreSQL 逐行执行。

其他设置：

  • 预览版函数：如需为预览版中的 AI 函数（例如 ai.extract 和 ai.classify）启用智能批处理，请将 google_ml_integration.enable_preview_ai_functions 设置为 on。
  • 模型选择：如需指定其他模型（而非默认的 gemini-2.5-flash-lite），请将 google_ml_integration.default_llm_model 设置为目标模型 ID，或在 AI 函数中传递 model_id 参数。

在实例级进行配置

如需在整个 AlloyDB 集群的实例级层配置数据库标志，请使用 gcloud alloydb instances update 命令：

gcloud alloydb instances update INSTANCE_ID \
  --database-flags google_ml_integration.enable_ai_function_acceleration=on \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --project=PROJECT_ID

替换以下内容：

  • INSTANCE_ID：您要更新的实例的 ID。
  • REGION_ID：集群所在区域的 ID。如需了解详情，请参阅支持的区域。
  • CLUSTER_ID：集群的 ID。
  • PROJECT_ID：项目的 ID。

如需了解详情，请参阅配置数据库标志。

在会话级别进行配置

如需为会话调整或切换智能批处理参数，请使用 SET 命令：

-- Disable smart batching for the current session (runs standard row-by-row execution)
SET google_ml_integration.enable_ai_function_acceleration = off;

-- Re-enable smart batching
SET google_ml_integration.enable_ai_function_acceleration = on;

-- Enable preview functions (ai.extract, ai.classify)
SET google_ml_integration.enable_preview_ai_functions = on;

验证 AI 函数的智能批处理功能

如需验证是否已为 AI 函数启用智能批处理，您可以使用 EXPLAIN 语句来分析查询。

启用智能批处理后，执行计划会包含 Custom Scan (AIFunctionApply) 或 Parallel Custom Scan (AIFunctionApply) 节点。此节点的存在表示，符合条件的 AI 函数调用会从标准的逐行执行中提取出来，并以高吞吐量异步批处理方式执行。如果此节点不存在，则使用标准 PostgreSQL 逐行评估来执行查询。

验证 WHERE 子句中的 AI 过滤

在 WHERE 子句中将 AI 布尔值函数（例如 ai.if）与标准关系型 SQL 谓词结合使用时，AlloyDB 会先使用索引扫描或表扫描来评估选择性关系型过滤条件。然后，AlloyDB 仅加速候选行以进行 AI 评估。例如：

EXPLAIN (COSTS OFF)
SELECT r.name, r.review
FROM restaurant_reviews r
WHERE ai.if('Is the following a positive review? Review: ' || r.review)
  AND r.city = 'Los Angeles';

当您使用 EXPLAIN 语句分析查询时，查询计划会显示 Custom Scan (AIFunctionApply) 节点：

                                       QUERY PLAN
----------------------------------------------------------------------------------------
 Custom Scan (AIFunctionApply)
   Filter: ai.if(('Is the following a positive review? Review: '::text || review), NULL::character varying)
   ->  Index Scan using idx_restaurant_reviews_city on restaurant_reviews r
         Index Cond: ((city)::text = 'Los Angeles'::text)

关系型过滤条件 (city = 'Los Angeles') 会先在索引上进行评估，只有匹配的行才会被批量发送到模型进行 ai.if 评估。

通过并行查询执行验证 AI 投影

SELECT 目标列表中的 AI 评分和生成函数会自动加速。当查询扫描大型表时，智能加速功能会与 PostgreSQL 并行查询集成，在并行后台工作器之间分配批量评估：

EXPLAIN (COSTS OFF)
SELECT ai.generate('Summarize the customer sentiment for: ' || r.review) AS review_summary
FROM restaurant_reviews r
WHERE ai.if('Does this review mention food safety concerns? ' || r.review);

查询计划输出示例：

                            QUERY PLAN
------------------------------------------------------------------------------------------------------
 Gather
   Workers Planned: 4
   ->  Custom Scan (AIFunctionApply)
         ->  Parallel Custom Scan (AIFunctionApply)
               Filter: ai.if(('Does this review mention food safety concerns? '::text || r.review), NULL::character varying)
               ->  Parallel Seq Scan on restaurant_reviews r
(6 rows)

备用操作

智能批处理提供安全的后备语义。如果查询包含无法安全加速的构造或模式，则查询不会失败。相反，AlloyDB 会使用标准 PostgreSQL 逐行执行方式安全地执行查询。

使用 DEBUG2 诊断后备广告

如需检查查询使用标准执行而非智能批处理的原因，请将 client_min_messages 设置为 DEBUG2 并执行 EXPLAIN：

SET client_min_messages TO DEBUG2;
EXPLAIN SELECT ...;
RESET client_min_messages;

检查输出中是否有前缀为 AI function acceleration is not applied 的诊断消息。

不受支持的查询句式

以下查询句式无法加速，会自动回退到标准的逐行执行：

  • 嵌套 AI 函数：AI 函数不能将另一个 AI 函数调用作为参数（例如 ai.if(ai.if(...))）。
  • 外联接 ON 子句：放置在 LEFT、RIGHT 或 FULL OUTER JOIN 条件中的 AI 函数。一种权宜解决方法是将 AI 过滤器放在 WHERE 子句或子查询中。
  • 封装 AI 函数的聚合：直接对 AI 函数进行聚合（例如 AVG(ai.rank(...))）。解决方法是先在 CTE 或子查询中计算 AI 函数，然后再进行聚合。
  • 易变函数参数：包含易变函数（例如 random() 或 clock_timestamp()）的参数表达式。
  • 非常量参数：初始文本输入（例如 output_schema、categories 和 model_id）之后的所有参数都必须是常量字面量，而不是列引用或表达式。
  • 相关子查询或外部参数：引用外部查询块中的变量的 AI 表达式。
  • 非基本关系：扫描外部表 (postgres_fdw) 或具体化 CTE (WITH ... AS MATERIALIZED)。
  • 超过 5 个不同的 AI 函数：单次表扫描最多支持 5 个不同的 AI 函数调用。

调优性能

您可以调整 AlloyDB 实例和会话参数，以最大限度地提高吞吐量并最大限度地减少 AI 工作负载的延迟时间。

批次组大小

参数 google_ml_integration.ai_function_acceleration_group_size 用于设置批量处理到对 Vertex AI 的单个远程 RPC 调用中的最大行数：

  • 默认值：4000（范围：1 到 20000）
  • 范围：会话、用户或数据库级
SET google_ml_integration.ai_function_acceleration_group_size = 10000;

工作负载规模估算指南：

  • 交互式查询（用于在线事务处理 [OLTP] 或低延迟）：将 group_size 设置为 50 到 100 之间的值。对于具有 LIMIT 子句的查询，较小的批次大小可以更快地返回第一批结果。
  • 批量处理或分析流水线（适用于在线分析处理 (OLAP) 或提取、转换和加载 (ETL) 工作负载）：将 group_size 设置为 5000 到 20000 之间的值。较大的批次可最大限度地提高模型吞吐量，并最大限度地缩短大型数据集的总体查询执行时间。

管理并发和工作器

并行查询执行会将批量评估分配给 Gather 节点下的后台工作器。如需优化并行吞吐量，请考虑以下事项：

  • 对于繁重的分析扫描，请确保 max_parallel_workers_per_gather 和 max_parallel_workers 设置得当，以最大限度地提高并行吞吐量。
  • 对于交互式工作负载或具有严格 Vertex AI 速率限制的环境，减少工作器数量可防止并发查询争用模型配额。

管理内存

智能批处理功能会使用 PostgreSQL 的 work_mem 设置自动限制内存用量，在达到内存阈值时动态分派批处理，以防止资源消耗过多。如果处理非常大的文本提示词或批次，请确保 work_mem 的大小合适。

优化费用

只有通过所有非 AI 关系谓词的行才会发送到模型。 只要查询语义允许，应用选择性关系 SQL 过滤条件（例如日期范围、状态代码或分类过滤条件）即可减少发送到模型的候选行数。这可以降低模型调用费用和执行延迟时间。

问题排查

以下部分介绍了运行加速 AI 查询时的常见问题和修复步骤。

查询未使用加速功能

如果您的查询未使用智能批处理，但您希望它使用，请考虑以下事项：

  • 检查扩展程序标志：验证 SHOW google_ml_integration.enable_ai_function_acceleration; 是否返回 on。
  • 检查不受支持的句式：验证您的查询不包含任何不受支持的查询句式。

  • 运行 DEBUG2 诊断：运行 SET client_min_messages TO DEBUG2;，后跟 EXPLAIN SELECT ...;，以查看跳过 AI 函数加速的具体原因。请务必在运行 EXPLAIN 后立即运行 RESET client_min_messages;，以防止在正常查询操作期间会话中充斥着调试消息。例如：

    SET client_min_messages TO DEBUG2;
EXPLAIN SELECT ...;
RESET client_min_messages;

  • 预准备语句：PostgreSQL 会缓存预准备语句的查询计划。如果您切换了加速标志，请运行 DEALLOCATE ALL; 以重新编译缓存的计划。

处理配额用尽

如果您遇到 HTTP 429 或速率限制错误，这可能是因为智能批处理同时处理过多行，导致 API 消耗量增加。为避免配额用尽，请考虑以下事项：

  • Token 配额 (TPM)：确保您的 Google Cloud 项目在目标区域中为目标模型提供了足够的每分钟 token 数 (TPM) 配额。如需增加 TPM 配额，请参阅申请 TPM 配额调整。
  • Agent Platform API 速率限制：确保您的 Google Cloud 项目有足够的 Agent Platform API 配额。如需为 Agent Platform 模型申请增加配额，请参阅申请增加 API 配额。

  • 并行查询：如果并行工作器耗尽了 Agent Platform 配额，请降低会话的并行度：

    SET max_parallel_workers_per_gather = 0;

  • 非并行查询：对于遇到速率限制的非并行查询，请减小批处理组大小：

    SET google_ml_integration.ai_function_acceleration_group_size = 500;

后续步骤