BigQuery AI.GENERATE_TABLE 实战指南：用表值函数在 SQL 中批量做 Gemini 结构化抽取（Google Agent Skills bigquery-ai-ml）

BigQuery AI.GENERATE_TABLE 实战指南用表值函数在 SQL 中批量做 Gemini 结构化抽取Google Agent Skills bigquery-ai-ml【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文基于 Google Agent Skills 仓库中bigquery-ai-ml技能的参考文档完整讲解 BigQuery 的AI.GENERATE_TABLE函数它是一个表值函数TVF将 Gemini 远程模型按预定义的 SQL Schema 把原始文本批量抽取为结构化列且完整保留输入列以便溯源。读完本文你将掌握它的完整语法、全部输入参数取值范围、多模态 prompt 构造方式、输出 Schema 结构以及如何创建配套远程模型并写出可运行的批量抽取查询。一、AI.GENERATE_TABLE 是什么把 LLM 输出变成表AI.GENERATE_TABLE使用 Gemini 模型把信息抽取到预先定义的 SQL Schema中。它的核心定位是一个Table-Valued Function表值函数因此必须写在FROM子句中而不是SELECT列表里SELECT * FROM AI.GENERATE_TABLE( MODEL project.dataset.model, { TABLE project.dataset.table | (QUERY_STATEMENT) }, STRUCT( OUTPUT_SCHEMA AS output_schema [, MAX_OUTPUT_TOKENS AS max_output_tokens] [, TOP_P AS top_p] [, TEMPERATURE AS temperature] [, STOP_SEQUENCES AS stop_sequences] [, SAFETY_SETTINGS AS safety_settings] [, REQUEST_TYPE AS request_type]) )这个定位与同技能中的标量函数AI.GENERATE形成对照。AI.GENERATE 参考文档显示AI.GENERATE返回一个STRUCT含result、status、full_response字段适合对单行做即席生成而AI.GENERATE_TABLE把每一行输入对应一行结构化输出这件事封装成了表操作天然适合对整张表或整段查询结果做批处理并且输出直接是带类型的列而不是需要自己解析的 STRUCT。bigquery-ai-ml 技能主文件对它的定位也印证了这一点Table-valued AI generation。二、输入参数逐项详解AI.GENERATE_TABLE接收三组参数模型、输入数据、以及一个用STRUCT承载的模型行为配置。逐项说明如下完整表格与原始文档一致参数是否必填类型说明model必填—远程模型资源形如project.dataset.model。input_data必填—源表或SELECT语句。必须包含一个名为prompt或以prompt为别名的列。output_schema必填String一个STRUCT内含 SQL 风格的列定义例如name STRING, qty INT64。max_output_tokens可选Int64取值范围[1, 8192]限制响应长度。temperature可选Float64取值范围[0.0, 2.0]随机性程度文档建议抽取类任务使用0.0以获得确定性响应。top_p可选Float64取值范围[0.0, 1.0]改变模型选择输出 token 的方式。stop_sequences可选ArrayString匹配到时立即停止模型生成的字符串列表。safety_settings可选ArrayStruct用于过滤仇恨言论、骚扰内容的阈值设置。request_type可选StringSHARED、DEDICATED或UNSPECIFIED默认UNSPECIFIED。几个使用上的关键点prompt列是硬性约定。无论输入是TABLE还是(QUERY_STATEMENT)都必须存在名为prompt或别名为prompt的列模型就是逐行读取该列内容做生成。这意味着你通常需要在子查询里完成列改名例如SELECT ticket_id, body AS prompt FROM ...。output_schema决定输出列类型。它是一段 SQL 风格的 DDL 字符串函数会按它把模型返回的 JSON 解析为强类型列。抽取数字、日期、枚举等字段时这里写对类型INT64、DATE、ARRAYSTRING等直接决定了下游能不能免解析地使用结果。temperature为 0.0 的建议来自原始文档结构化抽取是确定性任务随机采样只会引入解析失败率所以做信息抽取时应优先取0.0。Prompt 构造STRING 与多模态引用当输入使用(QUERY_STATEMENT)时可以通过组合不同类型来构造多模态 prompt原始文档Prompt Construction小节STRING/ARRAYSTRING字面量文本或列名用于拼接指令与源文本ObjectRefRuntime对图片、PDF 等对象引用列使用OBJ.GET_ACCESS_URL(col, r)生成可访问的签名 URL 作为模型输入。这与 AI.GENERATE 文档中的图片处理示例 使用同一套OBJ.GET_ACCESS_URL机制该示例针对 Cloud Storage 外部表中的 PNG 图片生成描述与实体数组说明两种函数共享同一种对象引用 → 签名 URL → 模型输入的多模态接入模式。三、输出 Schema保留输入列 生成列 诊断列AI.GENERATE_TABLE的输出表是输入数据与模型生成内容的联接它会保留全部原始输入列以维持可追溯性traceability再追加模型生成的列和两列诊断信息列类型说明[Input Columns]与输入一致你的输入TABLE或QUERY_STATEMENT中包含的每一列。[Schema Columns]按定义你在OUTPUT_SCHEMA参数中指定的带类型列。full_responseJSON底层 Gemini 模型返回的原始、未解析的 JSON 响应。statusSTRING执行状态若某一行抽取失败错误信息包含在其中。从这张表可以读出三个实战设计输入列全量保留意味着结果可以直接与业务主键联表不需要额外维护哪一行生成自哪一行源数据的映射full_response保留原始 JSON为排查解析结果不对劲提供了原始凭证——当某个字段值不符合预期时可以直接查看模型到底返回了什么status是行级错误通道。批量抽取不会因单行失败而整体报错失败行的错误信息落在status里因此生产查询中应对status做非空过滤或条件分支这是与标量AI.GENERATE同样以status表示 API 响应状态一致的错误处理约定。四、前置条件先创建指向 Gemini 的远程模型AI.GENERATE_TABLE的第一个参数是MODELproject.dataset.model这个模型实体需要通过 Vertex AI 连接创建。同技能的 Creating Remote Models 文档给出了标准流程CREATE [OR REPLACE] MODEL project.dataset.model_name REMOTE WITH CONNECTION { DEFAULT | project.region.connection_id } OPTIONS (ENDPOINT endpoint_name);生成类端点gemini-2.5-pro、gemini-2.5-flashAI.GENERATE_TABLE使用的就是这一类端点嵌入类端点text-embedding-005、text-multilingual-embedding-002、gemini-embedding-001对应AI.GENERATE_EMBEDDING与本文函数无关。连接方面使用REMOTE WITH CONNECTION DEFAULT时BigQuery 会尝试使用模型所在区域的默认连接否则必须给出完整的连接 ID例如my-project.us.my-connection。也就是说跑通AI.GENERATE_TABLE的完整依赖链是Vertex AI 连接 →CREATE MODEL REMOTE ...创建模型 → 在FROM子句中调用 TVF。五、完整示例LLM 摘要时保留业务主键下面是原始文档给出的示例Preserving Keys During LLM Summarization展示了对支持工单表做批量优先级判定与摘要同时保留ticket_id-- The output includes ticket_id from the input and priority and issue_summary from the AI schema SELECT ticket_id, priority, issue_summary FROM AI.GENERATE_TABLE( MODEL prod.models.gemini_flash, (SELECT ticket_id, body AS prompt FROM support.tickets), STRUCT(priority STRING, issue_summary STRING AS output_schema) )逐行拆解这段查询可以看到AI.GENERATE_TABLE三个参数的典型写法MODELprod.models.gemini_flash引用第四节创建好的远程模型资源子查询作为input_data(SELECT ticket_id, body AS prompt FROMsupport.tickets)——body被别名为prompt满足必填约定同时ticket_id作为普通输入列进入输出表STRUCT(priority STRING, issue_summary STRING AS output_schema)只定义了两个输出列priority和issue_summary因此最终输出为 3 列ticket_id 2 个生成列外加full_response与status。外层SELECT显式挑列把诊断列排除在结果之外。如果要在生产环境增强这段查询可以基于文档中已定义的参数做三件事均为文档支持的行为加入确定性参数STRUCT(priority STRING, issue_summary STRING AS output_schema, 0.0 AS temperature)按文档建议在抽取/摘要类任务中固定随机性限制输出长度对issue_summary这类短字段加... , 512 AS max_output_tokens须落在[1, 8192]内失败行兜底在外层查询中用WHERE status IS NULL或检查status非空行隔离失败数据利用行级status错误信息进行重跑或告警。六、与技能库其他 AI 函数的关系bigquery-ai-ml技能SKILL.md将 BigQuery 与 Vertex AI 集成提供一族可直接在 SQL 中调用的 AI/ML 函数。其中与AI.GENERATE_TABLE定位最接近的两类是同为 TVF 的函数如 AI.KEY_DRIVERS、AI.FORECAST同样是FROM子句中的表值函数但输入是结构化表数据而非prompt文本输出是分析结论列AI.GENERATE_TABLE则专门处理文本/多模态输入 → 模型生成结构化列这一场景标量生成函数AI.GENERATE 适合逐行即席生成返回 STRUCT当需要对整表批量抽取、且希望输出直接是强类型列并能保留输入列时AI.GENERATE_TABLE是更贴合的选择。此外BigQuery Basics 技能 覆盖了数据集、表和作业管理等基础运维内容——bigquery-ai-ml技能文档明确说明 AI/ML 查询之外的通用 BigQuery 管理需求应走该技能两者分工清晰。七、适用前提与限制小结调用位置只能出现在FROM子句表值函数语义不能像AI.GENERATE那样直接放在SELECT列表中模型依赖必须先存在通过CREATE MODEL ... REMOTE WITH CONNECTION ...创建的远程模型且连接对 Vertex AI 有访问权限参数取值范围max_output_tokens为[1, 8192]temperature为[0.0, 2.0]top_p为[0.0, 1.0]request_type取值SHARED/DEDICATED/UNSPECIFIED默认输入契约输入表或查询必须含prompt列可用AS prompt别名满足错误语义行级失败不使整条查询失败错误落在status列full_response保留原始 JSON 供排查文档依据本文全部语法与参数说明源自 ai_generate_table.md远程模型创建部分源自 remote_models.md端点清单以仓库当前版本所列gemini-2.5-pro、gemini-2.5-flash等为准实际可用端点可能随 BigQuery/Vertex AI 服务更新而变化。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考