ADK 中 BigQuery AI.GENERATE 函数完全指南：语法、参数与 Agent 集成实战-平芜编程栈

ADK 中 BigQuery AI.GENERATE 函数完全指南：语法、参数与 Agent 集成实战

【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python

本篇技术指南聚焦 ADK（adk-python）预置的bigquery-ai-mlSkill 中最核心的通用内容生成函数AI.GENERATE，系统讲解其 SQL 语法、输入参数、输出 STRUCT 结构，以及四个可直接运行的实战示例（文本生成、结构化输出、GCS 图片处理、Grounding 联网搜索）。读完本文，你将掌握在 ADK Agent 中通过execute_sql()使用AI.GENERATE的完整方法，并能结合BigQueryToolset与SkillToolset快速搭建数据洞察 Agent。

一、背景：`bigquery-ai-ml`Skill 与 AI.GENERATE 的定位

在 ADK 的 BigQuery 集成中，官方推荐优先使用 SQL Skill 而非专用高层工具来处理 AI/ML 类功能（如预测、异常检测）。这一约定明确写在预置 Skill 的说明文件 SKILL.md 中：

Agents should prefer using the Skill (SQL viaexecute_sql()) over dedicated BigQuery tools for functionalities like Forecasting and Anomaly Detection.

bigquery-ai-mlSkill 覆盖了 11 个AI.*系列函数，其中AI.GENERATE是通用目的（general-purpose）的文本与内容生成函数，负责调用 Gemini 等模型完成摘要、抽取、问答、多模态理解等任务。其余函数各有分工：

函数	用途	参考文档
`AI.FORECAST`	基于预训练 TimesFM 模型做时序预测	bigquery_ai_forecast.md
`AI.CLASSIFY`	将非结构化数据分类到预定义标签	bigquery_ai_classify.md
`AI.DETECT_ANOMALIES`	基于 TimesFM 识别时序异常	bigquery_ai_detect_anomalies.md
`AI.GENERATE`	通用文本与内容生成	bigquery_ai_generate.md
`AI.GENERATE_BOOL`	依据 prompt 生成布尔值（TRUE/FALSE）	bigquery_ai_generate_bool.md
`AI.GENERATE_DOUBLE`	依据 prompt 生成浮点数	bigquery_ai_generate_double.md
`AI.GENERATE_INT`	依据 prompt 生成整数	bigquery_ai_generate_int.md
`AI.IF`	求值自然语言布尔条件	bigquery_ai_if.md
`AI.SCORE`	按语义相关性排序（配合`ORDER BY`）	bigquery_ai_score.md
`AI.SIMILARITY`	计算两个输入的余弦相似度	bigquery_ai_similarity.md
`AI.SEARCH`	在表上做语义搜索，自动生成 embedding	bigquery_ai_search.md

关键路由规则：SKILL.md明确要求 Agent 在生成 SQL之前必须读取对应的参考文档，且严禁猜测文件名，只能使用表中给出的精确路径。本文所讲的AI.GENERATE完整语法即来自 bigquery_ai_generate.md。

二、AI.GENERATE 语法参考

AI.GENERATE的完整函数签名如下：

AI.GENERATE( [ prompt => ] 'PROMPT', [, endpoint => 'ENDPOINT'] [, model_params => 'MODEL_PARAMS'] [, output_schema => 'OUTPUT_SCHEMA'] [, connection_id => 'CONNECTION_ID'] [, request_type => 'REQUEST_TYPE'] )

参数全部采用**命名参数（named argument）**形式，通过=>传值；
除prompt外，其余参数均为可选项，可按需组合；
prompt可以是一个字符串字面量，也可以是由列名、字符串拼接（||）、元组（(...)）构成的表达式——下文示例会展示这三种用法。

三、输入参数详解

参数	必填	类型	说明
`prompt`	必填	String	传给模型的提示词文本或指令。可拼接列值、可传多模态内容（如图片引用）
`connection_id`	可选	String	BigQuery 连接 ID，格式形如`my-project.us.my-connection`。若通过其他方式配置（如默认连接）或仅做测试时可不填
`endpoint`	可选	String	模型名称，例如`'gemini-2.5-flash'`。不指定时使用默认模型
`output_schema`	可选	String	结构化输出的 Schema 定义，例如`'answer BOOL, reason STRING'`，使模型返回符合该结构的字段而非自由文本
`request_type`	可选	String	取值为`'DEDICATED'`或`'SHARED'`，控制请求使用专用还是共享的资源通道
`model_params`	可选	JSON	JSON 对象形式的模型参数，例如`temperature`、`max_output_tokens`，以及 Grounding 工具配置（见下文）

各参数要点：

prompt与列数据的结合：最典型的用法是用||将列值与指令拼接，例如'Summarize this article: ' || article_content，让模型对每一行数据分别生成结果；也可以使用元组形式('指令', 列或表达式)同时传入多个内容片段。
endpoint决定模型能力：选择不同的endpoint会直接影响生成质量、速度与成本，示例中给出的'gemini-2.5-flash'是面向高吞吐、低成本场景的选择，你可以按任务复杂度替换为其他可用模型。
output_schema触发结构化输出：一旦指定，返回结果中原本的result字段将被 Schema 中定义的字段取代，模型输出将严格对齐字段名与类型，便于下游直接做类型化解析。
model_params的 Grounding 扩展：该参数不仅支持temperature、max_output_tokens等常规采样参数，还能通过 JSON 内嵌工具声明启用 Google 搜索 Grounding（见示例四），让模型获得实时外部信息。

四、输出结构（Output Schema）

AI.GENERATE返回一个STRUCT，包含以下字段：

字段	类型	说明
`result`	`STRING`（或自定义类型）	生成的内容。若使用了`output_schema`，该字段被 Schema 中的字段取代
`status`	`STRING`	API 响应状态，成功时为空字符串
`full_response`	`JSON`	模型返回的完整原始 JSON 响应，包含安全评分（safety ratings）、用量元数据（usage metadata）等

理解这个返回结构对编写查询很重要：

直接SELECT AI.GENERATE(...)会得到整个 STRUCT；若要只取文本，通常配合.*展开字段，或访问result字段；
status字段可用于在 SQL 中做错误处理判断——非空即表示本次生成未成功；
full_response保留完整的模型原始输出，便于审计、调试与计量 token 用量，适合在需要追溯生成过程的场景下保留。

五、实战示例

以下四个示例均直接取自参考文档，覆盖了AI.GENERATE最典型的四类使用场景。

5.1 基础文本生成

对dataset.articles表中前 5 篇文章做摘要生成，prompt用||拼接列值，指定 Gemini 模型与连接：

SELECT AI.GENERATE( 'Summarize this article: ' || article_content, connection_id => 'my-project.us.my-connection', endpoint => 'gemini-2.5-flash' ) as summary FROM `dataset.articles` LIMIT 5;

5.2 结构化输出生成

从发票文本中抽取日期与金额，通过output_schema强制模型输出DATE与FLOAT64类型字段，返回结果可直接参与类型化运算：

SELECT AI.GENERATE( 'Extract the date and amount from this invoice: ' || invoice_text, output_schema => 'date DATE, amount FLOAT64' ) as extracted_data FROM `dataset.invoices`;

5.3 处理 Cloud Storage 桶中的图片

这是多模态能力的典型用法：先创建引用 GCS 图片的外部表，再用OBJ.GET_ACCESS_URL为每张图片生成带签名的访问 URL，并把图片与指令以元组形式传入prompt，配合output_schema要求模型返回图片描述与实体数组，最后用.*展开 STRUCT 字段：

CREATE SCHEMA IF NOT EXISTS bqml_tutorial; CREATE OR REPLACE EXTERNAL TABLE bqml_tutorial.product_images WITH CONNECTION DEFAULT OPTIONS ( object_metadata = 'SIMPLE', uris = ['gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/*.png']); SELECT uri, STRING(OBJ.GET_ACCESS_URL(ref,'r').access_urls.read_url) AS signed_url, AI.GENERATE( ("What is this: ", OBJ.GET_ACCESS_URL(ref, 'r')), output_schema => "image_description STRING, entities_in_the_image ARRAY<STRING>").* FROM bqml_tutorial.product_images WHERE uri LIKE "%aquarium%";

要点：

外部表通过WITH CONNECTION DEFAULT OPTIONS声明，object_metadata = 'SIMPLE'只读取对象元数据，uris以通配符形式批量指向桶内图片；
prompt的元组写法("What is this: ", OBJ.GET_ACCESS_URL(ref, 'r'))将指令与图片一并交给多模态模型；
返回的result字段已被output_schema替换为image_description与entities_in_the_image两个字段，.*展开后每行图片直接得到结构化描述。

5.4 使用 Grounding（联网搜索）

通过model_params传入JSON '{"tools": [{"googleSearch": {}}]}'，让模型在生成前借助 Google 搜索获取实时信息，从而回答天气这类依赖时效性数据的问题：

SELECT name, AI.GENERATE( ('Please check the weather of ', name, ' for today.'), model_params => JSON '{"tools": [{"googleSearch": {}}]}' ) FROM UNNEST(['Seattle', 'NYC', 'Austin']) AS name;

UNNEST数组展开后，三座城市各生成一行查询，模型会为每座城市分别进行联网检索并返回当日天气结论。

六、在 ADK Agent 中集成 bigquery-ai-ml Skill

bigquery-ai-mlSkill 以预打包形式随 ADK 分发，官方加载入口是 bigquery_skill.py 中的get_bigquery_skill()，其内部通过load_skill_from_dir()加载skills/bigquery-ai-ml目录（遵循 agentskills.io 规范）。参考文档中给出的集成骨架如下：

from google.adk.tools.bigquery import BigQueryToolset from google.adk.tools.bigquery.bigquery_skill import get_bigquery_skill from google.adk.tools.skill_toolset import SkillToolset bq_skill = get_bigquery_skill() toolset = SkillToolset(skills=[bq_skill]) bigquery_toolset = BigQueryToolset(...) agent = LlmAgent(tools=[bigquery_toolset, toolset])

这样配置后，Agent 同时获得两类能力：BigQueryToolset提供execute_sql、list_table_ids、get_table_info等查询与元数据工具（当前实现在 src/google/adk/integrations/bigquery 模块下），而SkillToolset让 Agent 能按 SKILL.md 的强制路由规则先读取参考文档、再据此写出正确的AI.GENERATESQL。

更完整的可运行 Agent 示例见 contributing/samples/integrations/bigquery/agent.py，该示例展示了四种凭据模式的配置方式：

ADC（Application Default Credentials）：CREDENTIALS_TYPE = None，适合本地开发，通过google.auth.default()获取凭据；
服务账号：AuthCredentialTypes.SERVICE_ACCOUNT，从service_account_key.json加载并刷新凭据；
交互式 OAuth：AuthCredentialTypes.OAUTH2，依赖OAUTH_CLIENT_ID/OAUTH_CLIENT_SECRET环境变量；
外部 Access Token：AuthCredentialTypes.HTTP，通过external_access_token_key="AUTH_ID"从 tool context 读取 Gemini Enterprise 注入的令牌。

同时可通过BigQueryToolConfig控制写入策略：write_mode的默认值是BLOCKED（只读），演示时可用ALLOWED，会话匿名数据集场景可考虑PROTECTED；max_query_result_rows用于限制返回行数（示例中设为 50）。值得说明的是，bigquery-ai-ml的查询行为本身由 BigQuery 侧模型能力决定，上述工具配置主要影响 SQL 的执行通道与权限边界。

七、工程质量保障：Skill 的测试验证

ADK 为bigquery-ai-mlSkill 提供了专门的单元测试 test_bigquery_skill.py，从多个维度保证该 Skill 与AI.GENERATE参考文档可被 Agent 正常加载使用：

Skill 元数据完整：get_bigquery_skill()返回的 Skill 名称必须为 kebab-case 的bigquery-ai-ml，且与目录名一致，description 与 instructions 非空（test_get_bigquery_skill_returns_valid_skill、test_skill_name_matches_spec）；
参考文档齐全非空：包括bigquery_ai_generate.md在内的全部 11 个参考文件必须存在且内容非空（test_skill_has_expected_references）；
与 SkillToolset 无缝集成：Skill 挂载到SkillToolset后应产出 4 个工具——ListSkillsTool、LoadSkillTool、LoadSkillResourceTool、RunSkillScriptTool（test_skill_works_with_skill_toolset）；
通过内置校验器：Skill 目录必须通过_validate_skill_dir校验，且 frontmatter 中 license 为Apache-2.0、metadata 含 author 与 version 字段（test_skill_passes_validation、test_skill_frontmatter_has_license、test_skill_frontmatter_has_metadata）。

这些测试保证了：只要 Agent 走 Skill 路由，就一定能读取到本文所讲的AI.GENERATE权威语法，而不会出现“猜测文件名导致加载失败”的情况。

八、使用建议与注意事项

遵循强制路由：在 ADK Agent 中使用AI.GENERATE时，应始终先让 Agent 读取 bigquery_ai_generate.md 再生成 SQL，不要凭记忆构造语法。
优先 Skill 而非专用工具：按SKILL.md的约定，AI/ML 类查询统一通过execute_sql()+AI.*函数完成，这比维护专用高层工具更简洁、可控。
结构化输出优先：需要下游程序化消费结果时，务必使用output_schema，让模型输出严格对齐字段类型（如DATE、FLOAT64、ARRAY<STRING>），减少后处理成本。
善用full_response与status：生产环境建议保留full_response用于审计与用量统计，并借助status字段识别失败调用。
凭据与写入安全：生产部署优先使用服务账号或 Gemini Enterprise 托管令牌，write_mode保持默认BLOCKED只读模式，避免 Agent 误写数据。

通过本文，你已掌握AI.GENERATE的完整语法、参数语义、四种实战模式，以及如何在 ADK 中通过get_bigquery_skill()与SkillToolset将其接入 Agent——下一步即可在真实 BigQuery 数据上验证这些 SQL，构建自己的数据智能体。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ADK 中 BigQuery AI.GENERATE 函数完全指南：语法、参数与 Agent 集成实战