工具调用中的 JSON 崩溃链：从解析到容错的系统工程实践

当 Agent 需要调用外部 API 时，80% 的故障始于工具参数的 JSON 解析错误。DeepSeek 在实际企业工单处理场景中观测到：即便 LLM 生成看似合规的 JSON，仍可能因以下原因导致后续管线崩溃：

故障根因深度解析

1. 类型系统不匹配

• 典型场景：
• 要求 {"timeout": 60} 但输出 {"timeout": "60"}
• 预期布尔值却收到 "true" 字符串
• 底层原因：
• LLM 对类型系统的理解基于文本模式而非编程约束
• 训练数据中存在混合类型的样本干扰
• 修复方案：
• 在 Schema 中明确标注 "type": "integer" 等类型声明
• 添加类型转换中间层（如 int(value) if str(value).isdigit()）

2. 嵌套结构逃逸

• 典型案例：

  {
    "config": "{\"retry\": 3}"  // 未转义的双层 JSON
  }

• 危害链：
• 初级解析器将内层 JSON 识别为字符串
• 业务逻辑尝试二次解析时触发语法错误
• 错误处理层无法区分结构错误与内容错误
• 防御措施：
• 使用 JSON Schema 的 "contentSchema" 校验字符串内容
• 在 prompt 示例中展示正确的转义写法

3. 键名规范冲突

• 常见变异形式：

ALIAS_MAP = {
    "userId": "user_id",
    "active": "is_active"
}

4. 容器边界失控

• 边界条件：
• 约定返回 3 个结果但实际返回空数组
• 分页参数 page_size=100 但返回 101 条记录
• 验证策略：

  from pydantic import conlist
  class ResponseModel(BaseModel):
      items: conlist(str, min_items=1, max_items=3)

5. 编码污染问题

• 典型表现：
• UTF-8 BOM 头导致首字符解析失败
• 混合使用 Unicode 编码（如 \u4e00 与中文汉字混排）
• 清洗方案：

  def clean_json(raw: str) -> str:
      return raw.lstrip('\ufeff').encode('utf-8').decode('unicode_escape')

强制结构化输出工程指南

1. 模式验证最佳实践

# 进阶验证示例：带业务逻辑的校验
from pydantic import validator

class PaymentParams(BaseModel):
    amount: float
    currency: str

    @validator('amount')
    def check_amount(cls, v):
        if v <= 0:
            raise ValueError("金额必须大于0")
        return round(v, 2)  # 自动修正小数位

    @validator('currency')
    def check_currency(cls, v):
        if v.upper() not in ['CNY', 'USD']:
            raise ValueError("仅支持CNY/USD")
        return v.upper()

2. 动态约束调整策略

• 上下文感知约束：
• 根据用户权限动态调整 max_items 上限
• 在非生产环境放宽必填字段要求
• 渐进式严格化：
• 首次失败：仅提示缺少字段
• 二次失败：提供字段示例
• 三次失败：切换为表单输入

3. 容错架构设计模式

graph TD
    A[原始输出] --> B{语法校验}
    B -->|通过| C[语义校验]
    B -->|失败| D[语法修复]
    C -->|通过| E[业务校验]
    C -->|失败| F[语义修正]
    E -->|通过| G[执行]
    E -->|失败| H[业务补偿]

    D --> B
    F --> C
    H --> I[人工回滚]

生产环境分级处理方案

1. 实时拦截策略矩阵

2. 错误归因分析方法

1. 特征提取：
2. 统计高频错误字段 TOP5
3. 分析时间相关性（如特定时段故障激增）
4. 根因定位：
5. 对比错误请求与成功请求的 prompt 差异
6. 检查模型版本更新与错误率变化关联
7. 闭环处理：
8. 将确认的 bug 转化为微调数据
9. 更新 schema 的字段说明文档

关键决策检查清单

1. 事前预防：
2. [ ] 是否在接口文档标注所有边界条件？

3. [ ] 是否提供可执行的 curl 示例？

4. 事中控制：

5. [ ] 是否设置合理的默认值和 fallback 逻辑？

6. [ ] 是否有字段级别的修改历史追踪？

7. 事后改进：

8. [ ] 是否建立错误案例知识库？
9. [ ] 是否定期评审自动化率指标？

演进路线图

1. 短期（1个月）：
2. 实现基础校验框架

3. 建立错误监控看板

4. 中期（3个月）：

5. 引入自动修复能力

6. 完成 80% 接口的容错测试

7. 长期（6个月）：

8. 实现动态约束调整
9. 达到 95% 的自动化处理率

通过系统化的校验策略和渐进式的容错设计，可在保证可靠性的前提下稳步提升自动化处理效率。建议从关键业务接口开始试点，逐步扩大验证范围，最终形成覆盖全场景的智能校验体系。