面向 LLM 的程序设计 11：多语言与多模态下的工具描述
问题：当用户用中文问"查一下我的订单"，而你的工具名叫search_orders、参数键是order_id时，模型会不会搞混？当用户上传一张发票照片，模型"看到"的是图像像素，但你的查单工具只接受字符串order_id，这个gap怎么补上？
总结：工具的技术标识（名字、参数键）保持英文稳定，让模型在任何语言环境下都认得；自然语言描述用用户母语，让模型理解何时该用；多模态输入先经过结构化转换（OCR/提取），再进工具调用，别让工具直接"看像素"。
关键词：多语言；多模态；工具元数据；稳定标识符；MCP；Token 预算
0 系列回顾
- 面向 LLM 的程序设计 1：API 契约设计：从 REST 到「能力端点」。能力化端点：为具体业务动作各自暴露的专用接口，例如
/summarize-document、/list-orders-by-user；不要把所有需求都丢进一个万能/ask接口。 - 面向 LLM 的程序设计 2：确定性契约：为什么 LLM 调用的 API 需要严格 JSON Schema。用 JSON Schema 钉死类型、枚举与必填，对冲模型输出的随机性，减少歧义与解析失败。
- 面向 LLM 的程序设计 3：LLM-Friendly 的响应结构：扁平键、稳定字段与类型标注。键名稳定、结构尽量扁平、语义一眼可读，方便模型与下游工具链消费。
- 面向 LLM 的程序设计 4：API 版本化与演进——在「模型会记忆旧文档」前提下的兼容策略。显式版本、可渐进扩展与废弃公告，避免模型仍按旧文档调用已变更接口。
- 面向 LLM 的程序设计 6：Tool Calling 的完整生命周期——从定义、决策、执行到观测回注。从工具定义到回注再推理串成闭环，每步可校验、可观测、失败可处理。
- 面向 LLM 的程序设计 7：工具描述的工程化——name、description、parameters 怎么写才少误用。稳定 name、写清何时用与边界、Schema 与文案一致，降低选错工具与填错参的概率。
- 面向 LLM 的程序设计 8：「少而宽」还是「多而窄」——工具粒度与 Token 预算的权衡。在工具个数、单工具覆盖面与上下文占用之间做工程权衡，平衡误触率与 Token 成本。
- 面向 LLM 的程序设计 9：系统提示中的「能力边界」——减少越权与幻觉调用。在系统提示里划清能做与不能做，减少越权操作与「假装能调」的幻觉调用。
- 面向 LLM 的程序设计 10：链式任务中的中间输出格式——如何写提示才能稳定得到可解析结构。探讨在多步推理、Prompt 链、LangGraph 节点之间，如何将中间输出约定为稳定的结构化格式：定义字段、类型、缺值处理方式，在提示词中给出正反示例，并与解析、校验、重试机制配合。
1 多语言：一套接口，多语用户
1.1 什么必须固定不变？
无论用户说中文、英文还是日文，以下这些技术标识必须全球统一：
| 要素 | 正确做法 | 错误做法 |
|---|---|---|
| 工具名 | search_orders | search_orders_cn、查询订单 |
| 参数键 | order_id、start_date | 订单号、开始日期 |
| 枚举值 | pending、paid、shipped | 待付款、已支付、已发货 |
原因：模型可能在思维链里中英混杂，但最终生成的 JSON 必须能被程序正确路由。如果工具名随语言变，同样的功能就要维护多套定义，迟早会出现"中文用户调不到英文工具"的 bug。
1.2 什么可以本地化？
只有给人读的自然语言可以本地化：
- 工具描述（description）：告诉模型"这个工具什么时候用、输入什么、返回什么"。用户说中文，你就给中文描述。
- 参数说明：每个字段的含义解释，用用户能懂的语言写。
- 示例（few-shot）：放几条用户语言的调用示例在 prompt 里。
1.3 推荐的描述格式：双语块
与其维护两套独立的工具定义（中英文各一份），不如在一个描述里并列双语，维护成本低，模型也能对照理解：
[工具] search_orders [参数] keyword (string), status (enum: pending|paid|shipped) [中文] 按关键词搜索订单列表，只读操作。当用户问"我的订单在哪"但没说具体订单号时使用。 [EN] Search orders by keyword. Read-only. Use when user asks about orders but doesn't provide a specific order_id. [注意] 不要与 find_shipment 混淆：本工具查订单主数据，物流追踪请用 find_shipment。这样同一套search_orders定义，中英文界面都能用，只是系统 prompt 里的描述段切换或双语并列。
1.4 跨语言误选：一个真实问题
场景：用户用中文问"我订单到哪了"，你的工具库里有两个：
search_orders（查订单列表）find_shipment（查物流轨迹）
如果search_orders的描述只有英文，模型可能误判用户想问物流，从而选错工具。
解决：
- 至少给每个工具一行用户语言的摘要
- 在描述里写清边界：“本工具只查订单列表，不查物流。物流请用 find_shipment”
2 多模态：图像/文档怎么进工具？
2.1 别让工具"直接看像素"
除非你的工具后端真的接了一个视觉模型，否则工具参数应该是引用，而不是原始图像。
| 用户上传 | 上游处理 | 工具接收 |
|---|---|---|
| 发票照片 | OCR 提取 →{"order_id": "ORD-12345", "amount": 299} | query_order(order_id="ORD-12345") |
| 商品截图 | 物体识别 →{"product_id": "SKU-67890"} | get_product_info(product_id="SKU-67890") |
| PDF 合同 | 版面分析 →{"contract_id": "CTR-001", "parties": [...]} | review_contract(contract_id="CTR-001") |
原则：把"看懂图像"和"执行业务"拆成两道工序——
- 多模态理解节点：用视觉模型把图/文档转成结构化数据
- 工具调用节点：用确定性参数调用业务工具
2.2 只传"最小必要信息"
视觉模型往往输出一堆字段：订单号、金额、日期、商户名、商品列表……但你的查单工具可能只需要order_id。不要把整张 OCR 结果塞进工具参数，既浪费 Token 又稀释模型注意力。
做法：在视觉节点和工具节点之间加一道"字段映射"，只挑工具真正需要的字段传递。
2.3 生成任务 vs 工具调用要分开
用户上传照片后，模型可能想干两件事：
- 描述图片内容给用户听（生成任务）
- 调用工具处理图片里的信息（工具调用）
这两件事在架构上要拆成两个节点：
- Caption 节点：给模型看图片，让它生成自然语言描述（用户可见）
- Tool Planner 节点：基于结构化数据决定调用什么工具（程序消费）
不要让"描述图片"和"执行操作"在同一个 LLM 调用里混着做，容易出错且难调试。
3 Token 控制：双语描述的取舍
中英双语描述会让工具说明体积翻倍。根据场景选择策略：
| 场景 | 策略 |
|---|---|
| 高频工具 | 双语全量注入，确保准确率 |
| 低频/内部工具 | 默认语言全量 + 其他语言一行摘要 |
| 多语言应用 | 按locale动态组装，只注入当前语言版本（参考第 8 篇动态注入） |
| 从不触发的域 | 不要因为"翻译完整"就提前注入，浪费 Token |
4 与 MCP / 开放生态衔接
MCP (Model Context Protocol) 等开放协议中，建议对外注册工具时提供：
{"name":"search_orders","title_zh":"搜索订单","title_en":"Search Orders","description":"...","tags":["order","read-only","e-commerce"]}name：永远稳定、语言无关title_*：可选的本地化显示名tags：语言无关的主题标签，便于检索和过滤
5 小结
| 维度 | 原则 |
|---|---|
| 多语言 | 技术标识（name、参数键）用英文统一；描述和示例用用户母语；双语并列优于维护两套定义 |
| 多模态 | 图像/文档先结构化再进工具；工具参数只接引用（ID/URI），不接原始像素或全文 OCR |
| Token | 按频率和语言动态裁剪，低频工具不必全量翻译 |
实践建议：建立一张tool_i18n表，记录每个工具在各语言的描述摘要和"易混淆工具"对照。在 CI 里检查"每个工具至少有一种用户语言的摘要"，避免上线后某语言用户集体误选。
参考资源
以下是关于多语言与多模态工具设计的权威资料，可帮助你深入理解相关实践：
官方文档
OpenAI Function Calling Guide
- 函数定义的基础规范，包括名称、描述、参数 Schema 的最佳实践
- 支持工具搜索（tool search）以优化大规模工具集场景
Anthropic Tool Use Documentation
- Claude 的工具使用机制详解
- 提供
strict: true选项确保输出严格匹配 Schema - 强调工具描述应至少 3-4 句话，越详细越好
Google Vertex AI Multimodal Function Calling
- Gemini 模型的多模态函数调用实现
- 支持函数返回图像/PDF 等多模态内容
- 最多支持 512 个 FunctionDeclarations
社区实践
Writing Tools for AI Agents - Anthropic Engineering Blog
- 如何编写有效的工具描述
- 工具命名空间（namespacing）与功能边界划分
- Token 效率优化建议
Designing Tool Schemas for AI Agents - CallSphere
- JSON Schema 设计最佳实践
- 适用于多语言场景的 Agent 架构设计
Multimodal Function Calling with Gemini - Philipp Schmid
- Gemini 3 多模态函数调用的实战示例
- 如何处理函数返回的图像数据
延伸阅读
MCP Model Context Protocol
- 标准化的工具注册与发现协议
- 支持元数据本地化（title、description 的多语言版本）
LLM Function Calling Implementation Guide - PremAI
- 完整的函数调用实现指南（2026 版）
- Schema 合规性保证机制