Firebase JS SDK AI 包中 GroundingMetadata 接口详解：解析 Gemini Grounding 响应元数据-北京尧图网络

开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载在 Firebase JS SDK 的firebase/ai包中当你为模型启用 Grounding接地/依据检索工具后generateContent返回的候选结果里会携带一个GroundingMetadata对象用于描述模型依据了哪些检索内容来生成回答。本文基于 docs-devsite/ai.groundingmetadata.md 这份接口参考文档结合 packages/ai 包的源码与集成测试完整讲解该接口五个属性的含义、类型结构与典型用法读完你可以正确读取groundingChunks、groundingSupports、searchEntryPoint等字段并在 Web 应用中正确渲染 Google Search 入口点与引用溯源信息。GroundingMetadata 是什么、在哪里出现GroundingMetadata是启用 grounding 后返回的元数据Metadata returned when grounding is enabled。从源码结构看它挂载在GenerateContentCandidate上定义于 packages/ai/src/types/responses.ts#L241-L269export interface GenerateContentCandidate { index: number; content: Content; finishReason?: FinishReason; finishMessage?: string; safetyRatings?: SafetyRating[]; citationMetadata?: CitationMetadata; groundingMetadata?: GroundingMetadata; // -- 挂载点 urlContextMetadata?: URLContextMetadata; }因此访问路径统一为response.candidates[0].groundingMetadata。当前支持范围目前仅支持 Grounding with Google Search 和 Grounding with Google Maps 两种场景分别由GoogleSearchTool和GoogleMapsTool触发接口定义见 packages/ai/src/types/requests.ts#L568-L630。合规要求原文档明确要求务必遵守使用 Grounding with Google Search 时必须遵守你所选 API 提供方Gemini Developer API 或 Agent Platform Gemini API中关于 Grounding with Google Search 的使用条款使用 Grounding with Google Maps 时同样必须遵守对应的 Grounding with Google Maps 使用条款。源码中在GoogleSearchTool、GoogleMapsTool、GroundingMetadata的 TSDoc 注释里都重复强调了这一合规约束见 packages/ai/src/types/responses.ts#L223-L240 与 packages/ai/src/types/requests.ts#L557-L602。接口签名与属性总览export interface GroundingMetadata { searchEntryPoint?: SearchEntrypoint; groundingChunks?: GroundingChunk[]; groundingSupports?: GroundingSupport[]; webSearchQueries?: string[]; googleMapsWidgetContextToken?: string; }属性类型说明googleMapsWidgetContextTokenstringGoogle Maps widget context token 的资源名可配合PlacesContextElementwidget 渲染上下文数据。仅在启用 Google Maps grounding 时填充groundingChunksGroundingChunk[]GroundingChunk对象列表。每个 chunk 代表模型用来接地其回答的一段检索内容例如来自某个网页groundingSupportsGroundingSupport[]GroundingSupport对象列表。每个对象说明模型回答中的某一段内容如何被groundingChunks中的内容所支撑searchEntryPointSearchEntrypointGoogle Search 网页搜索入口点。包含一段必须嵌入到应用中的 HTML/CSS 片段用于针对模型的 Grounded Response 展示后续网页搜索入口webSearchQueriesstring[]模型为收集 grounding 信息而执行的网页搜索查询列表可用于让用户自行探索搜索结果属性一searchEntryPoint 与 Google Search 入口点渲染searchEntryPoint的类型是SearchEntrypoint定义见 packages/ai/src/types/responses.ts#L276-L293只有一个可选属性renderedContent?: string——一段必须嵌入 Web 页面的 HTML/CSS 片段其设计目标是避免与页面其余 CSS 产生意外交互。源码注释明确建议为确保正确渲染并防止 CSS 冲突推荐将renderedContent封装在 shadow DOM 中再嵌入网页const container document.createElement(div); document.body.appendChild(container); container.attachShadow({ mode: open }).innerHTML renderedContent;仓库的集成测试对这一字段有真实断言在启用tools: [{ googleSearch: {} }]后断言searchEntryPoint?.renderedContent内容包含div见 packages/ai/integration/generate-content.test.ts#L109-L148可以印证 Google Search grounding 场景下该字段确实会由后端返回。属性二groundingChunks 检索内容块groundingChunks是GroundingChunk[]。每个GroundingChunk有两个互斥可选字段标识该 chunk 的来源类型export interface GroundingChunk { web?: WebGroundingChunk; // 来自 Web 源的细节 maps?: GoogleMapsGroundingChunk; // 来自 Google Maps 源的细节 }WebGroundingChunkGoogle Search 场景字段类型说明uristring被检索网页的 URItitlestring被检索网页的标题domainstring原始 URI 的域名。仅在 Agent Platform Gemini APIAgentPlatformBackend下支持使用 Gemini Developer APIGoogleAIBackend时该字段为undefinedGoogleMapsGroundingChunkGoogle Maps 场景字段类型说明uristring该地点place的 URItitlestring该地点的标题textstring该地点答案的文本placeIdstring该地点的资源名格式为places/{place_id}可用于在 Google Maps API 中查询该地点两者均定义在 packages/ai/src/types/responses.ts#L301-L366。集成测试也验证了两种场景的 chunk 形态差异Google Search 场景断言每个 chunk 的web.uri存在Google Maps 场景则断言maps.uri、maps.title、maps.placeId均存在packages/ai/integration/generate-content.test.ts#L131-L172。属性三groundingSupports 回答片段与引用溯源groundingSupports中的每个GroundingSupport对象描述回答中的哪一段话由哪些 chunk 支撑包含两个字段export interface GroundingSupport { segment?: Segment; // 模型回答中被支撑的片段 groundingChunkIndices?: number[]; // 支撑该片段在 groundingChunks 中的下标列表 }groundingChunkIndices是指向GroundingMetadata.groundingChunks数组的下标列表。例如[1, 3, 4]表示groundingChunks[1]、groundingChunks[3]、groundingChunks[4]是支撑该片段回答内容的来源。segment是Segment接口定义见 packages/ai/src/types/responses.ts#L395-L418用于精确定位片段在响应Content中的位置字段类型说明partIndexnumber父Content的parts数组中该Part的零基下标startIndexnumber片段在指定Part内的零基起始下标以 UTF-8 字节计含起点从 0 开始endIndexnumber片段在指定Part内的零基结束下标以 UTF-8 字节计不含终点textstring响应中与该片段对应的文本注意一个源码测试中揭示的细节partIndex和startIndex由于常为 0而 protobuf 可能省略默认值 0因此这两个字段在响应中可能缺失测试注释见 packages/ai/integration/generate-content.test.ts#L145。属性四webSearchQueries 与属性五googleMapsWidgetContextTokenwebSearchQueries?: string[]模型为收集 grounding 信息而实际执行的网页搜索查询列表可用于向用户展示、让用户自行查看搜索结果。googleMapsWidgetContextToken?: stringGoogle Maps widget context token 的资源名可配合PlacesContextElementwidget 渲染上下文数据。文档明确说明仅在启用 Google Maps grounding 时才会填充。集成测试中反复断言 Google Search 与 Maps 基础场景下googleMapsWidgetContextToken为undefinedpackages/ai/integration/generate-content.test.ts#L147与该按需填充语义一致。实战如何在 firebase/ai 中启用 Grounding 并消费元数据以下示例与仓库集成测试的用法packages/ai/integration/generate-content.test.ts#L109-L119保持一致通过getGenerativeModel的tools参数启用工具import { getAI, getGenerativeModel } from firebase/ai; const ai getAI(app); // 方式一Google Search grounding const model getGenerativeModel(ai, { model: gemini-2.5-flash, tools: [{ googleSearch: {} }] }); // 方式二Google Maps grounding可附加 RetrievalConfig 指定检索位置 const mapsModel getGenerativeModel(ai, { model: gemini-2.5-flash, tools: [{ googleMaps: {} }], toolConfig: { retrievalConfig: { latLng: { latitude: 42.4154, longitude: -71.1565 } } } });RetrievalConfig/LatLng类型定义见 packages/ai/src/types/requests.ts#L677 与 #L794。集成测试验证了带retrievalConfig.latLng的 Maps grounding 提问如 Where is a good place to grab a coffee near here?同样会返回完整的groundingMetadatapackages/ai/integration/generate-content.test.ts#L187-L230。拿到结果后的典型消费逻辑const result await model.generateContent( What is the speed of light in a vacuum in meters per second? ); const groundingMetadata result.response.candidates?.[0].groundingMetadata; // 1. 展示引用来源列表 groundingMetadata?.groundingChunks?.forEach((chunk) { if (chunk.web) console.log(chunk.web.uri, chunk.web.title); if (chunk.maps) console.log(chunk.maps.placeId, chunk.maps.title); }); // 2. 为回答片段渲染脚注segment.text 由 groundingChunkIndices 指向的 chunks 支撑 groundingMetadata?.groundingSupports?.forEach((support) { const sources support.groundingChunkIndices ?.map((i) groundingMetadata.groundingChunks?.[i]); console.log(support.segment?.text, -, sources); }); // 3. 展示模型实际执行的搜索查询 console.log(groundingMetadata?.webSearchQueries); // 4. Google Search 场景用 shadow DOM 嵌入搜索入口点 if (groundingMetadata?.searchEntryPoint?.renderedContent) { const container document.createElement(div); document.body.appendChild(container); container.attachShadow({ mode: open }).innerHTML groundingMetadata.searchEntryPoint.renderedContent; }底层实现groundingMetadata 在 SDK 内部如何流转结合源码可以确认groundingMetadata的完整链路请求/响应类型Gemini Developer API 后端的内部候选类型GoogleAIGenerateContentCandidate同样携带groundingMetadata字段packages/ai/src/types/googleai.ts#L56-L65。后端差异映射googleai后端的响应在 packages/ai/src/googleai-mappers.ts#L188-L197 中被映射为统一的公共候选结构groundingMetadata是原样透传的groundingMetadata: candidate.groundingMetadata。同一映射函数还处理了citationMetadata.citationSources到citations的转换体现了 Gemini Developer API 与 Agent Platform 后端在字段命名上的差异而 grounding 元数据则两端结构一致。流式聚合generateContentStream场景下各 SSE 分片响应由aggregateResponses聚合。从源码结构看packages/ai/src/requests/stream-reader.ts#L256-L265聚合逻辑对groundingMetadata采用以最新分片为准的覆盖策略——后到的分片若携带groundingMetadata会覆盖聚合结果中的旧值这与同函数中urlContextMetadata需保留首个非空值的特殊处理形成对比。因此在流式消费时最终应从result.response聚合 Promise而非单个流分片中读取完整的 grounding 元数据。两个后端下的字段差异小结从源码注释可归纳出GroundingMetadata相关字段在两种后端下的行为差异使用时需要留意字段Gemini Developer APIGoogleAIBackendAgent Platform Gemini APIAgentPlatformBackendgroundingChunks[].web.domain不支持为undefined支持其余属性在两个后端下结构一致。此外groundingMetadata本身是可选字段只有请求中实际配置了对应 grounding 工具且后端返回了依据信息时才会出现消费代码应对undefined情况做防御性处理集成测试全部通过candidates?.[0].groundingMetadata安全访问。参考路径接口参考文档docs-devsite/ai.groundingmetadata.md、docs-devsite/ai.groundingchunk.md、docs-devsite/ai.groundingsupport.md、docs-devsite/ai.searchentrypoint.md、docs-devsite/ai.segment.md核心类型定义packages/ai/src/types/responses.ts工具请求类型GoogleSearchTool / GoogleMapsTool / RetrievalConfigpackages/ai/src/types/requests.ts后端响应映射packages/ai/src/googleai-mappers.ts流式聚合实现packages/ai/src/requests/stream-reader.ts集成测试Google Search / Maps grounding 真实断言packages/ai/integration/generate-content.test.ts赞分享开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载相关推荐Firebase JS SDKfirebase/aiGoogleMapsGroundingChunk 接口详解Google Maps 接地Grounding响应数据解析Firebase JS SDKfirebase/aiGoogleMapsGroundingChunk 接口详解Google Maps 接地Ground开发工具后端Firebase AI SDK WebAttribution 接口详解理解 Gemini 网页归因与 Grounding 元数据Firebase AI SDK WebAttribution 接口详解理解 Gemini 网页归因与 Grounding 元数据 WebAttribution开发工具后端Firebase JS SDKfirebase/ai中 GoogleMapsTool 详解让 Gemini 模型接入 Google Maps 位置信息落地GroundingFirebase JS SDKfirebase/ai中 GoogleMapsTool 详解让 Gemini 模型接入 Google Maps 位置信息落开发工具后端上一篇ML-For-Beginners 9-Real-WorldML Scavenger Hunt 作业实战指南——设计一份黑客松级的经典机器学习行业方案下一篇网页一键变知识库MaxKB 网页抓取功能快速上手指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Firebase JS SDK AI 包中 GroundingMetadata 接口详解：解析 Gemini Grounding 响应元数据

相关推荐

OpenProse 的 Arabian Nights 寄存器：用《一千零一夜》叙事语法编排多智能体工作流

markdownlint 链接文本空格规则 MD039 实战：剖析 links-with-markup 测试用例与自动修复原理

Delphi TStringGrid数据导出Excel：SpreadsheetML方案与OLE对比实战

更多资讯

GitHub Actions上跑AI Agent：事件驱动自动化实战与避坑指南

家校沟通高情商话术：化解家长矛盾与冲突的实用指南

博世如何用MEMS传感器筑起手机、汽车与工业的感知帝国

海康安防证书是否安装的检查：Windows/Linux全流程指南

vLLM高并发本地推理部署实战：从原理到压测调优

技能包+任务图：三小时上线邮件自动分类与回复服务

今日更新

Cephadm实战指南：Linux系统工程师的生产级Ceph集群部署与排障

不想再被 Token 额度卡脖子？把免费 API 接入 WorkBuddy 的完整教程

ITK中SpatialObject几何体系解析：坐标系、变换与管道集成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？