Margrop
Articles317
Tags814
Categories6

Categories

1password 24GB VRAM 2K 3-SAT 3.6 Flash 30B dense 4-bit 量化 6-DoF SLAM AC ACP AI & Economy ATLAS AI Agent AI Coding Assistant AI Tech AI Workflow AI tutor AI 基础设施 AI 安全 AI 工程 AI 应用 AI 日记 AI 生产力 AI编程助手 ALTK-Evolve AMIE AP API API 定价 API 稳定性 API 设计 API 降价 ARC-AGI-3 ASR ATEM chat 模板 AUTOMATIC1111 Agent Agent Harness Agent Memory Agent 入侵 Agent 可靠性 Agent 工程 Agent 推理 Agent 架构 Agent 检索 Agent 沙箱 Agent 系统 Agent 训练 Agent 记忆 Agent 评测 Agent 路由 Agentic AI Agentic SOC Agentic tools Ai2 Alertmanager AllenAI Android 17 Antigravity Apertus 1.5 AppDaemon AppWorld Apple Silicon Aqara Astra Async GRPO Attention AutoSynthData Baseten Benchmark CC-Switch CI/CD CLI Tools CLI工具 COBOL CPU 推理 Cache Hit Rate Caddy ChatGPT Claude Code Claude Sonnet ClawLoader Code Interpreter CodeMender Codex Coding Agent ComfyUI Computer Use Cookie 认证 Cosmos DB Cosmos-H-Dreams Cost Optimization Cron Cybersecurity DFIR DSpark Date DeepSeek DeepSeek V4 Flash Diagrams.net Diary Diffusers Diffusion Docker Efficiency Tools Embedding English Evaluation Cards FSDP2 Fable 5 Falcon ASR Fireworks AI FlashAttention FlashDreams Frontier AI Function Calling Funes GGUF GLM 5.2 GLM-5.2 GPT-4.1 GPT-5.6 GPT-5.6 Sol GPT-6 GPT-6 Astra GPT-6.2 GPT-Live GPT-Live-1 GPT-Red GPU 云 GPU 加速 GPU 性能分析 GPU 集群 GRPO Gated DeltaNet Gateway Gemini Gemini 3.5 Flash Gemini 3.7 Flash Gemini 3.8 Gemini 4 Argon Gemini API Gemini CLI Gemini Omni Flash Gemma 4 12B Gemma Translator Gemma4 GitHub Actions Google Google AI Google Beam Google Data Commons Google DeepMind Google Research Google Sheets Grabette Gradio Gradio Workflow Granite Gripette HA HADashboard HF Security Incident Hailuo Hermes Hexo Holo4 HomeAssistant Hugging Face IBM Granite IBM Research In-context Learning Inference Providers Inkling Isaac Lab Isaac Sim JSON Output JSON Schema Java KV cache KV 缓存 Kimi K3 Kubernetes LFM2.5 LFM2.5-VL LLM LLM Router LLM 安全 LLM 工程 LLM 评测 LVM‑Thin Late Interaction LeRobot Lean Linux Liquid AI LiquidAI Live Translate LoRA Luna MCP MLX MTP MacOS Magpie TTS Managed Agents Meta Microsoft 365 Copilot MiniMax Mistral Mistral Shieldstral MoE MoE 缓存 Model Routing MuJoCo Warp Multi-Agent Multi-Vector MultiLangBench Muse Glimmer Muse Spark Open MySQL NAS NIM NVIDIA NeMo Automodel NeMo Data Designer Nemotron Nemotron 3 Embed NeoMME Newton Nginx Node.js Nunchaku OCR OOM OlmoEarth On-device AI Open Source OpenAI OpenAI Codex OpenAI 兼容 OpenClaw OpenCode OpenResty OpenRouter OpenUSD OpenWrt PII 检测 Physical AI Pollen Robotics Portainer PostgreSQL ProcessOn Project Astra Prometheus Prompt Caching Prompt Injection Prompt 缓存 Proxmox VE PyTorch Qwen Qwen3 Qwen3-VL Qwen3.6 RAG RPC RTEB Real-Time Inference Red Teaming Reflection Beam Responses API SNAP SOCKS5 SPED SVDQuant SWE-Bench Schema Scientific Computing Self-Forcing Distillation Sentence Transformers Session Sheets canvas Shell Sol Speech-to-Text StateBench Storage Buckets Strands Agents Subagent Surgical Robotics TRL TTS Tabular Terra Think button TimeMachine Tokenizer ToyBlocks Transformers TutorMoments UML Uptime Kuma V4-Pro VLA VPS Voice Agent VoiceEQ WARP WebRTC WebSocket Windows World Foundation Model XY问题 agent agentic aligenie aliyun allenai annotation aop autofs backup bash bitwarden boot brew browser budget control centos cert certbot charles chat chrome classloader client clone closures cloudflare command commit commoditization container crontab cyber capability demo dependency deploy developer devtools dll dns docker domain download drafter draw drawio dsm dump dylib environment hooks exception fail-closed fail2ban feign firewall-cmd flow flow matching free tier frontier hosted model frp frpc frps fuckgfw full-duplex function gfw git github gperftools gridea grub guardrail lockout gvt-g hacs havcs heap hello hexo hibernate hidpi hoisting homeassistant hosts html htmlparser https huggingface_hub iKuai iMessage image img img2kvm immortalwrt import index inference cost install intel io ios ip iptables iso java javascript jni jnilib jpa js json jsonb jupter jupyterlab jvm k8s kernel key kvm lastpass launchctl learning letsencrypt linux llama.cpp low-code lvm mac mariadb markdown maven md5 microcode mirror modules monitor mount mstsc multimodal mysql n5105 network nfs node node-red nodejs nohup notepad++ npm nssm ntp oop open d1 open weights openfeign openssl os ovz packet capture pdf pem perf pip plugin png powerbutton print pro productive struggle pve pvekclean python qcow2 qemu qemu-guest-agent rar reasoning control reasoning slider reboot reflog remote remote desktop renew repo resize retina router runtime safari sata scaffolding scheduled triggers scipy-notebook scoping scp self-play server serverless inference silent test simulated student so speculative decoding spk spring springboot springfox ssh ssl stash string support svg svn swagger sync synology systemctl systemd template terminal token 效率 txt ubuntu ui undertow unlocker upgrade vLLM vhd vim vm vmdk web windows with worker xml yum zai-org/GLM-5.2 zip 一致性评测 上下文压缩 上下文工程 上下文管理 上下文结构 专家剪枝 世界模型 事件响应 交换机 人才争夺 人机协作 代理 代码生成 代码迁移 仿真基准 企业 AI 企业自动化 优化 低延迟 低资源编程语言 供应链 健康检查 光猫 免费层 具身智能 内存 内存优化 内网渗透 决策模型 分布式存储 分布式推理 分布式训练 医疗 AI 升级 卫星影像 反向代理 反诉 可复现性 合成数据 后训练配方 向量检索 启动 告警 告警优化 图像生成 地球观测 地理空间推理 基准评测 基础设施 复盘评测 夏令时 多 token 预测 多向量检索 多智能体 多模型编排 多模态 多模态 AI 多模态 API 多模态 Agent 多模态交互 多模态检索 多模态模型 多语言 多语言 AI 大厂人才战 大模型评测 天猫精灵 安全 安全事件 安全基础设施 安全对齐 安全评测 安全运营 安装 定时任务 实时协作 实时语音 客户端 SDK 容器 对齐 导入 小模型 小米 屏幕理解 工作流编排 工具审计 工具调用 工具调用拦截 工程团队 工程实践 工程笔记 常用软件 应用市场 延迟优化 开权重 开源权重 开源模型 异常 异步任务 异步委派 强化学习 形式化验证 微信 心跳 性能优化 性能捕捉 成本优化 成本控制 扩散模型 技术 抓包 拒答校准 持续预训练 指令数据分离 按 provider 优先级 授权链 排查 推测解码 推理加速 推理引擎 推理成本 推理服务 推理模型 推理速度 推理预算 描述文件 提示注入 提示词敏感性 搜索 API 故障排查 效率工具 教育数据开源 教育评测 数学推理 数据工作流 数据治理 数据流 数据管线 数据集偏差 文本编码器 文档解析 旁路由 日志分析 日记 时区 显卡虚拟化 显存优化 智能家居 智能音箱 服务管理 本地 Agent 本地 agent 本地推理 本地模型 机器人仿真 机器人学习 机器人数据采集 架构 标记语言 模块 模型压缩 模型发布 模型微调 模型快照 模型推理 模型评测 模型路由 模型适配 残存访问 流式推理 流程 流程图 浏览器 混合专家 漫游 火绒 状态追踪 生成式影像 电信 画图 监控 监控系统 监管 知识蒸馏 磁盘 科研 Agent 科研自动化 稀疏注意力 立体声 端侧 AI 端侧推理 端口 端口冲突 端口扫描 结构化抽取 结构化输出 续期 网关 网络 网络安全 网络风暴 置信度 群晖 脚本 脚本优化 腾讯 自动化 自动恢复 自动攻击 自部署 苹果 虚拟机 表格基础模型 视觉语言模型 视频生成 视频问诊 计算复杂性 认证 训练基础设施 证书 评测 评测基准 评测方法学 诉讼 语义化版本 语用学 语音 AI 语音 Agent 语音识别 资产验证 资源调度 超时 路由 路由器 软件工程 软件测试 软件管家 软路由 边缘 AI 运维 运维监控 连接保活 连接问题 通信机制 通知 邮件漏发 部署 配置 量化 量子计算 钉钉 镜像 镜像源 长上下文 长任务编排 长连接 门窗传感器 问题排查 防火墙 阿里云 阿里源 集客 非人类身份 飞书

Hitokoto

Archive

Gemini Tool Retrieval 拆解:Agent 有上百个工具时,怎么少发 schema 还不选错?

Gemini Tool Retrieval 拆解:Agent 有上百个工具时,怎么少发 schema 还不选错?

Gemini Tool Retrieval:让 Agent 按需加载工具 schema

先说结论

Google 在 2026 年 11 月 19 日把 Tool Retrieval 放进 Gemini Interactions API 预览。它解决的不是“模型不会调用工具”,而是另一个随着 Agent 规模增长才会暴露的问题:当工具从十几个变成上百个时,每次请求都把全部参数 schema 塞进上下文,会同时增加输入 token、延迟和选错工具的机会。

官方方案是把工具拆成两层:模型始终看到每个工具的名称和描述,但把较长的参数 schema 标记为 defer_loading: true;请求里增加一个 tool_search,模型需要某个工具时先搜索,API 在同一次交互里加载匹配工具的完整 schema,再继续生成工具调用。

我的判断是:这是一项很适合 Agent 平台直接采用的“上下文控制面”能力,但不要把它误读成免费的向量数据库或自动可靠性证明。它能减少未使用工具的重复传输;它不能替你修复含糊的工具名、重叠的描述、危险的权限边界,也不能保证模型永远挑中正确工具。工程上应该保留高频工具常驻,把长尾工具延迟加载,并用真实任务统计每次搜索带来的 token、延迟和误选变化。

发生了什么

主来源是 Google 官方博客《Introducing Tool Retrieval in the Gemini API》,发布日期为 2026 年 11 月 19 日:

官方事实是:Tool Retrieval 适用于 Gemini 3.6 及更新模型,并支持全部 Gemini 4 模型;不另收 Tool Retrieval 服务费,仍按所调用模型的标准输入与输出 token 计费。启用 tool_search 会增加一小段固定输入 token;模型实际加载的每个 schema,会像预先声明的工具一样计入后续对话输入。我的判断是:成本是否下降取决于“从未被调用的 schema”是否明显多于“实际被加载的 schema”,不能只看产品名称就假设每个请求都会更便宜。

技术细节

1. 工具描述可见,参数结构延迟加载

传统的工具调用请求通常把工具数组完整放进去:名称、用途描述、参数类型、必填字段、枚举值和嵌套对象全部随请求发送。当 Agent 有 50 个甚至更多函数时,真正与当前任务相关的可能只有一两个,但其余 schema 仍然占据上下文。

Tool Retrieval 的切分很实用。调用方在工具列表中加入一个 tool_search,对长尾函数设置 defer_loading: true。模型仍然能看到这些函数的名称和 description,因此知道“工具库里有哪些能力”;完整参数定义暂时不进入上下文。模型判断需要退款工具时,可以先按名称请求搜索,平台返回 issue_refund 的完整参数结构,随后模型在同一交互中发出普通的 function call。

官方示例使用一个退款函数:工具名是 issue_refund,参数包括订单标识和退款金额;另外还有 50 多个延迟加载函数。该示例表达的不是“所有工具都必须延迟”,而是一个混合策略:经常使用的工具保持常驻,长尾工具才放到检索路径。

2. 一次交互里的三步可观测

这个设计的关键不只是少传内容,还把选择过程变成了可检查的步骤。官方示例的 interaction.steps 依次包含:模型发起 tool_search_call,API 返回 tool_search_result,模型再产生 function_call。

这为排障提供了比“最后调用失败”更好的证据链。平台可以记录模型搜索了哪些函数、返回了哪些候选、最终调用了哪一个;开发者可以区分三种问题:模型根本没搜到工具,搜索结果里有正确工具但模型选错,还是选对以后参数校验或执行失败。对于生产 Agent,这三类问题的处理方式完全不同,不能都归因成“模型能力不够”。

Google 还说明,搜索发生在同一次 API 调用中,不需要调用方另建索引或托管检索服务。平台会在服务器侧完成工具搜索;应用代码主要变化是增加 tool_search,再给目标函数加延迟加载标记。

3. 和前缀缓存的关系

官方特别提到 Tool Retrieval 可以配合 prefix caching。延迟加载的 schema 不会出现在提示词开头;模型真正加载的 schema 会在对话后段加入。这样,稳定的系统提示、工具名称和描述仍有机会复用缓存,而当前任务才需要的参数细节在后面补进来。

不过,这不是无条件的性能承诺。缓存命中率取决于请求前缀是否稳定,搜索结果取决于工具命名和描述质量,最终账单还取决于实际加载了多少 schema。部署前至少要测三组流量:少量工具、几十个工具、长尾工具很多的工具库,并分别记录输入 token、首 token 延迟、完整响应延迟、搜索命中率和工具误选率。

对 Agent / 工程的影响

1. 工具注册表应该分层,而不是一股脑塞给模型

以前很多 Agent 框架的工具注册方式是启动时收集全部函数,然后每轮请求原样发送。这种方式在 Demo 阶段简单,但工具规模一大,schema 会成为隐形的固定税。Tool Retrieval 给出的启发是把注册表分成三层:安全且高频的核心工具常驻;低频但描述清晰的工具延迟加载;需要额外授权的高风险工具甚至不要直接暴露给模型,而是先经过确定性的策略检查。

这里的“延迟加载”不是权限控制。一个被检索出来的删除、转账或发布工具,仍然需要服务端做身份、参数、审批和幂等校验。不要因为 schema 没在初始 prompt 里,就把它当成安全隔离。

2. 工具描述要像检索索引,不只是给人看的注释

当模型先依据名称和描述选择候选时,描述质量直接影响召回。工具名应该稳定、具体、可区分;描述要说明什么时候用、什么时候不要用、输入的关键限制是什么。两个工具都写成“处理订单”,即使参数 schema 设计得很严谨,前面的搜索也可能把它们混在一起。

建议为每个工具补充离线评测集:给定用户目标,检查正确工具是否出现在检索结果中;再检查模型是否能根据完整 schema 生成合法参数。把“检索召回”和“调用成功”分成两个指标,才能知道优化应该落在描述、搜索还是模型推理。

3. 观测系统要把搜索步骤纳入 trace

传统 Agent trace 只记录最终 function call,Tool Retrieval 之后至少要增加三类事件:候选工具数量、搜索请求与返回结果、最终工具及参数校验结果。成本指标也要拆开:初始工具描述 token、搜索固定开销、实际加载 schema token、工具结果 token。

对线上故障来说,这些字段比一条“工具调用失败”有用得多。比如某次延迟升高,可能不是函数执行变慢,而是工具库描述过长;某次误调用,可能不是模型突然退化,而是新工具和旧工具的描述发生语义重叠。把搜索步骤单独记录,才能做回归比较。

4. 跨 Provider 的抽象要谨慎

这项能力目前是 Gemini Interactions API 的预览接口,字段和行为不能直接假定与其他模型平台一致。如果 Agent 框架要同时支持多个 Provider,建议在内部抽象一个“工具目录与加载策略”层,而不是把 defer_loading 写死在业务工具定义中:Provider 支持时映射到原生 Tool Retrieval,不支持时可以退化为本地候选筛选或静态分组。

但退化路径必须明确标记为不同实现。不同 Provider 的检索算法、计费方式、上下文位置和 trace 语义可能不同,不能对外声称“同一套工具路由行为”。

我的判断

第一,工具数量超过几十个、且每轮只会用到少数工具的 Agent,值得优先试 Tool Retrieval;只有几个高频工具的应用,复杂化收益很小。第二,默认采用“核心工具常驻、长尾工具延迟加载、高风险工具确定性审批”的三层策略,不要把所有函数一刀切延迟。第三,把它当成上下文与成本优化,不要当成安全边界或正确率保证;上线门槛应是自己的检索召回、误选率、延迟和账单数据,而不是官方功能名。

Q&A

Q1:来源和发布日期是什么?
A:Google 官方博客《Introducing Tool Retrieval in the Gemini API》,发布日期为 2026-11-19,原始 URL 是 https://blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval/。本文涉及的功能状态、模型范围、计费说明和示例均以该官方页面为准。

Q2:最小接入需要改什么?
A:在 Interactions API 的工具列表中增加 tool_search,把希望按需加载的函数标记 defer_loading: true,保留名称、描述和完整参数定义。先用一个低风险工具做小流量验证,再逐步扩展到长尾工具。

Q3:它是否一定省钱?
A:不一定。Tool Retrieval 本身没有单独服务费,但固定搜索开销和实际加载的 schema 都会计入输入 token。只有未使用的 schema 足够多,节省才会超过新增开销;必须用真实流量测量。

Q4:能否替代权限系统?
A:不能。延迟加载只改变工具 schema 何时进入上下文,不改变工具是否有权执行。删除、付款、发布等操作仍需服务端鉴权、参数验证、审批和幂等控制。

Q5:哪些场景暂时不适合?
A:工具很少、每轮几乎都会调用全部工具,或者 Provider 适配层还没有稳定 trace 的场景,暂时不必引入。先把工具描述、错误处理和执行验证做好,收益通常比增加一层检索更确定。


字数自检:正文超过 1500 个中文字符;来源、发布日期和原始 URL 已列出。
隐私自检:未包含内部网络地址、真实机器名、凭据或用户相关信息。
文件名:2026-11-22-gemini-tool-retrieval-agent-schemas.md
封面尺寸:1600 / 900;categories:ai_tech

本文阅读量 --
Author:Margrop
Link:https://blog.margrop.com/post/2026-11-22-gemini-tool-retrieval-agent-schemas/
版权声明:本文采用 CC BY-NC-SA 3.0 CN 协议进行许可