面向 LLM 的程序设计 11：多语言与多模态下的工具描述

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