Function Calling Schema 演进：新增参数时别让旧调用全部失效

Function Calling Schema 演进：新增参数时别让旧调用全部失效

一、今天的上线让三个月前写的所有 Agent 都报错了

给工具加一个新参数，看起来是很小的改动。
在 JSON Schema 里加一行"new_param": {"type": "string"}。
部署后，旧版本 Prompt 发出的调用全部失败。
因为旧 Prompt 不知道这个新参数，导致 Schema 校验不通过。

更糟的是，有些 Prompt 是硬编码在数据库里的。
你需要找到所有引用这个工具的地方逐一修改。
这就是 Schema 演进缺乏向后兼容的代价。

Function Calling 的 Schema 本质是 API 契约。
模型根据这个契约决定传什么参数。
一旦契约变更，所有消费者都可能受影响。

这个问题的根源在于我们对 Function Calling 的认知偏差。
传统 API 的消费者是程序员，API 变更时你可以发邮件通知、更新文档、甚至强制升级 SDK。
但 Function Calling 的消费者是大模型——它不会读你的 Release Notes，也不会理解你标注的deprecated。
模型只会按照 Prompt 里的 Schema 描述来调用工具。

我在实际项目中踩过一个典型的坑。
一个订单查询工具最初只有一个参数order_id。
三个月后业务需要支持按用户 ID 批量查询，我新增了user_id参数。
部署后，所有使用旧版 Prompt 的 Agent（约 12 个，分布在 4 个不同团队维护的代码仓库中）发出的调用全部校验失败。
因为这些 Agent 的 System Prompt 里描述的工具仍然是旧版 Schema，模型不知道要传user_id，但它又看到了 Schema 里有这个参数定义，于是传了个空字符串——这在某些场景下触发了错误的业务逻辑。

二、Schema 演进的兼容性策略

Schema 的变更有三种破坏级别。
字符串类型的默认值变更：非破坏性。
新增可选参数：理论上非破坏性，但有坑。
参数改名或删除：破坏性，必须做版本迁移。

为什么"新增可选参数"也有坑？
因为虽然 Schema 层面标记了required: false，但 Prompt 中的工具描述没有同步更新。
模型可能理解到有一个可选参数，但不知道什么情况下该传、什么情况下不该传。
结果模型要么忽略新参数（功能降级），要么瞎传（产生副作用）。

所以我们需要一套正式的 Schema 版本管理策略。
核心思路是：让旧 Prompt 还能工作，给新 Prompt 充裕的迁移窗口。

flowchart TB A[工具 Schema 需要变更] --> B{变更类型} B -->|新增可选参数| C[追加 Schema，标记 required: false] B -->|参数改名| D[添加新参数 + 保留旧参数（标记 deprecated）] B -->|修改参数类型| E[创建新版本 Schema v2] B -->|删除参数| E C --> F[模型自动适配新参数] D --> G[同时支持新旧参数] G --> H[监控旧参数使用率] H --> I{旧参数使用率为 0?} I -->|是| J[安全删除旧参数] I -->|否| K[继续等待] E --> L[注册新版本 Schema] L --> M[通知 Agent 升级] M --> N[Agent 切换到新版本] N --> O[取消旧版本注册]

这里的关键节点在"监控旧参数使用率"。
你不能靠"我觉得没人用了"来判断，必须有数据支撑。
在我们的实践中，我们给每个 deprecated 参数加了使用量打点，在 Grafana 上挂了监控面板。
连续两周旧参数调用量为 0，才进入删除流程。
同时保留一个"冷静期"——在日志中打印 deprecated 警告，给那些低频调用（比如周报级别的定时任务）额外的发现机会。

三、Schema 版本管理实现

下面的代码实现了一个完整的 Schema 注册中心。
通过SchemaRegistry管理工具的版本历史，evolve方法支持三种变更策略，validate_params在参数校验时自动做兼容转换。

""" schema_evolution.py - Function Calling Schema 演进管理 """ import hashlib import json import logging from datetime import datetime, timedelta from typing import Any, Dict, List, Optional from dataclasses import dataclass, field logger = logging.getLogger(__name__) @dataclass class ToolSchema: """工具 Schema 定义""" name: str description: str parameters: Dict[str, Any] version: str # 语义化版本 required: List[str] = field(default_factory=list) deprecated_params: List[str] = field(default_factory=list) created_at: Optional[datetime] = None def to_openai_format(self) -> Dict[str, Any]: """转换为 OpenAI Function Calling 格式""" return { "type": "function", "function": { "name": self.name, "description": self.description, "parameters": { "type": "object", "properties": self.parameters, "required": self.required, }, }, } def fingerprint(self) -> str: """计算 Schema 指纹，用于变更检测""" content = json.dumps({ "name": self.name, "params": self.parameters, "required": self.required, }, sort_keys=True) return hashlib.sha256(content.encode()).hexdigest()[:16] class SchemaRegistry: """Schema 注册与版本管理中心""" def __init__(self): self.schemas: Dict[str, List[ToolSchema]] = {} # 工具名 -> 版本列表 def register(self, schema: ToolSchema) -> str: """注册新版本 Schema""" name = schema.name schema.created_at = datetime.now() # 检查版本冲突 existing = self.schemas.get(name, []) for s in existing: if s.version == schema.version: raise ValueError( f"工具 {name} 版本 {schema.version} 已存在" ) self.schemas.setdefault(name, []).append(schema) logger.info( f"注册 Schema: {name} v{schema.version} " f"(指纹: {schema.fingerprint()})" ) return schema.version def get_latest(self, name: str) -> Optional[ToolSchema]: """获取最新版本""" versions = self.schemas.get(name) if not versions: return None return versions[-1] def get_version(self, name: str, version: str) -> Optional[ToolSchema]: """获取指定版本""" for s in self.schemas.get(name, []): if s.version == version: return s return None def evolve( self, name: str, changes: Dict[str, Any], strategy: str = "additive", ) -> ToolSchema: """ Schema 演进入口 strategy: - "additive": 新增参数，版本号 1.1.0 -> 1.2.0 - "compatible": 不破坏兼容性的修改 - "breaking": 破坏性修改，版本号 1.x -> 2.0.0 """ current = self.get_latest(name) if current is None: raise ValueError(f"工具 {name} 未注册") # 深拷贝当前 Schema new_params = json.loads(json.dumps(current.parameters)) new_required = list(current.required) deprecated = list(current.deprecated_params) for param_name, param_def in changes.items(): action = param_def.get("action", "add") if action == "add": # 新增参数：默认非必填 new_params[param_name] = { "type": param_def["type"], "description": param_def.get("description", ""), } if param_def.get("required", False): new_required.append(param_name) elif action == "rename": # 参数改名：同时保留新旧参数 old_name = param_def["old_name"] if old_name in new_params: new_params[param_name] = new_params.pop(old_name) deprecated.append(old_name) logger.warning( f"{name}: {old_name} -> {param_name} (旧参数标记 deprecated)" ) elif action == "remove": if param_name in new_params: del new_params[param_name] if param_name in new_required: new_required.remove(param_name) # 版本号递增 new_version = self._bump_version(current.version, strategy) new_schema = ToolSchema( name=name, description=current.description, parameters=new_params, required=new_required, version=new_version, deprecated_params=deprecated, ) self.register(new_schema) return new_schema def _bump_version(self, current: str, strategy: str) -> str: """语义化版本递增""" parts = current.split(".") major, minor, patch = int(parts[0]), int(parts[1]), int(parts[2]) if strategy == "additive": return f"{major}.{minor}.{patch + 1}" elif strategy == "compatible": return f"{major}.{minor + 1}.0" elif strategy == "breaking": return f"{major + 1}.0.0" return current def validate_params( self, name: str, provided_params: Dict[str, Any] ) -> Dict[str, Any]: """ 参数校验与兼容转换 将旧参数名映射到新参数名 """ current = self.get_latest(name) if current is None: raise ValueError(f"工具 {name} 未注册") validated = {} for key, value in provided_params.items(): # 跳过已废弃的参数（兼容处理） if key in current.deprecated_params: logger.info(f"忽略已废弃参数: {name}.{key}") continue validated[key] = value # 校验必填参数 for req_param in current.required: if req_param not in validated: raise ValueError( f"工具 {name} 缺少必填参数: {req_param}" ) return validated # ---- 使用示例 ---- def demo_schema_evolution(): registry = SchemaRegistry() # 1. 注册初始版本 search_v1 = ToolSchema( name="web_search", description="搜索互联网信息", parameters={ "query": { "type": "string", "description": "搜索关键词", }, }, required=["query"], version="1.0.0", ) registry.register(search_v1) print(f"初始 Schema: {search_v1.fingerprint()}") # 2. 新增可选参数（非破坏性） registry.evolve("web_search", { "max_results": { "action": "add", "type": "integer", "description": "最大返回数", "required": False, }, }, strategy="additive") # 3. 参数改名（兼容处理） registry.evolve("web_search", { "search_text": { "action": "rename", "old_name": "query", "type": "string", "description": "搜索文本", }, }, strategy="compatible") # 4. 使用旧参数名调用（自动兼容） try: # 旧代码仍使用 "query" result = registry.validate_params("web_search", { "query": "AI Agent 架构", }) print(f"校验通过: {result}") except ValueError as e: print(f"校验失败: {e}") # 5. 一段时间后，删除旧参数 registry.evolve("web_search", { "query": {"action": "remove"}, }, strategy="breaking") # 现在用旧参数会失败 try: registry.validate_params("web_search", {"query": "AI Agent 架构"}) except ValueError as e: print(f"旧参数已移除: {e}")

validate_params方法的设计有一个重要的工程考量。
它不拒绝使用deprecated_params的调用，而是静默忽略旧参数，转而使用新参数。
这意味着即使某个旧版 Agent 还在发旧参数名，调用也不会失败——只是功能的降级被推迟了。
这是一个折中方案：优先保证可用性，再用监控推动迁移。

四、Schema 演进的权衡

Schema 演进需要额外维护成本。
每个工具的参数变更都要走注册流程。
对于 3-5 个工具的小型 Agent，这套机制过重。

参数兼容的窗口期需要明确。
deprecated 参数保留多久？三个月？半年？
过期未清理的旧参数会污染 Schema。
建议设置强制清理日期，配合告警。

不适合的场景：
原型阶段工具还在快速变化的项目；
内部工具服务，可以同时更新所有消费者；
参数语义完全不同的重构（直接发新工具名更清晰）。

实际上，Schema 演进的成本评估应该考虑工具数量和使用频率的乘积。
在我们的经验中，5 个以下工具的项目用这套机制的投资回报率太低——你花在维护 Schema 版本上的时间可能超过直接改代码的时间。
但当工具数量超过 10 个，且跨团队共享时，这套机制的收益就开始指数级增长。

另一个实用的经验是：在工具注册时自动生成一份"工具使用报告"。
记录哪些 Agent 注册了哪些工具、最近一次调用的时间。
当你要废弃一个参数时，这份报告可以精确告诉你影响范围——而不是靠搜索代码库来猜测。

五、总结

Function Calling Schema 演进需要兼容性策略。
新增可选参数是非破坏性的，可直接追加。
参数改名应同时保留新旧参数，待旧参数调用归零后删除。
Schema 版本管理让每次变更都有追踪记录。
核心原则：模型兼容旧参数，代码校验新 Schema，最终清理旧入口。

把这套思路落地到具体流程上，我建议三个阶段性动作。
第一，Schema 注册标准化：所有工具的 Schema 定义统一存放在一个注册中心，禁止在各 Agent 代码中分散定义。
第二，改动必须走版本号：任何对 Schema 的变更都要新建一个版本，拒绝原地修改。
第三，监控先行：在删除旧参数之前，至少观察两周的数据，确保零调用后再动手。
做到这三点，Function Calling 的 Schema 演进就从"每次改参数都心惊胆战"变成了"可预测、可回滚、可审计"的工程实践。