面向 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 推荐的描述格式：双语块

与其维护两套独立的工具定义（中英文各一份），不如在一个描述里并列双语，维护成本低，模型也能对照理解：

text 复制代码

[工具] 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) 等开放协议中，建议对外注册工具时提供：

json 复制代码

{
  "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 多模态函数调用的实战示例
- 如何处理函数返回的图像数据