# 模型注册的工具列表
available_tools = ["search_database", "send_email", "create_report"]

# 模型实际输出（幻觉）
{
  "tool_calls": [{
    "function": {
      "name": "delete_database_records",  # ← 不存在的工具
      "arguments": '{"table": "users", "condition": "inactive"}'
    }
  }]
}

# 模型调用存在的工具，但参数完全编造
{
  "tool_calls": [{
    "function": {
      "name": "send_email",  # 工具存在
      "arguments": '{"to": "[email protected]", "subject": "URGENT: System Shutdown", "body": "..."}'  # 参数幻觉
    }
  }]
}

flowchart TD
    A[用户请求] --> B[LLM生成工具调用]
    B --> C{工具名在白名单?}
    C -->|否| D[拦截 + 返回错误]
    C -->|是| E{参数Schema校验}
    E -->|失败| F[拒绝执行 + 日志告警]
    E -->|通过| G{参数值合理性检查}
    G -->|可疑| H[人工确认 / 二次验证]
    G -->|安全| I[执行工具调用]
    D --> J[将错误反馈回LLM重试]
    F --> J
    style D fill:#ff6b6b
    style F fill:#ff6b6b
    style H fill:#ffd93d

# 嵌套Schema定义
tools = [{
    "name": "book_flight",
    "parameters": {
        "type": "object",
        "properties": {
            "passenger": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "loyalty": {
                        "type": "object",           # 第3层嵌套
                        "properties": {
                            "tier": {"type": "string", "enum": ["silver", "gold", "platinum"]},
                            "points": {"type": "number"}   # 第4层！
                        }
                    }
                }
            },
            "legs": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "from": {"type": "string"},
                        "to": {"type": "string"}
                    }
                }
            }
        }
    }
}]

# 模型实际输出 — Schema违规典型表现
{
    "passenger": {
        "name": "John",
        "loyalty": "gold"          # 应为object，输出为string
    },
    "legs": "SFO-JFK"             # 应为array，输出为string
}

任务：将自然语言转换为数据库查询工具调用

自由文本输出（约45 tokens）：
"Search the users table where age > 25 and status is active, return name and email"

结构化JSON输出（约78 tokens，+73%）：
{
  "tool": "search_database",
  "parameters": {
    "table": "users",
    "filters": [{"field": "age", "operator": ">", "value": 25}, ...],
    "select": ["name", "email"]
  }
}

graph LR
    subgraph 输入端开销
        A[工具Schema定义] -->|500-2000 tokens| B[System Prompt]
        C[工具描述文本] -->|200-800 tokens| B
    end
    subgraph 输出端开销
        D[自由文本] -->|基准| E[~100 tokens]
        F[结构化JSON] -->|+31%~+47%| G[~138 tokens]
    end
    subgraph 推理端开销
        H[Constrained Decoding] -->|+120~210ms| I[延迟惩罚]
    end
    B --> J[总成本 = 输入 + 输出 + 延迟]
    E --> J
    G --> J
    I --> J
    style J fill:#ff9f43,color:#000

// SSE流式传输的逐块输出（模拟）
// Chunk 1: {"tool_calls":[{"function":{"name":"se
// Chunk 2: arch_database","arguments":"{\"tab
// Chunk 3: le\":\"users\",\"filte
// Chunk 4: rs\":[{\"field\":\"age\",\
// Chunk 5: "op\":\">\",\"val
// Chunk 6: ue\":25}]}"}}]}

// 问题：每个Chunk都不是合法的JSON！
// 必须累积拼接后才能解析

# 模型单次返回两个并行调用
tool_calls = [
    {"name": "withdraw_money", "arguments": '{"account": "A", "amount": 1000}'},
    {"name": "transfer_money",  "arguments": '{"from": "A", "to": "B", "amount": 1000}'}
]

# 如果第一个成功、第二个失败 → 账户A被扣款但未转账
# 如果两个都成功但顺序反了 → 余额不足报错
# 没有内置的事务回滚机制！

# 生产级工具调用评估套件
class ToolCallEvaluator:
    def evaluate(self, model, test_cases):
        results = {
            "schema_compliance": self.test_schema(model, test_cases),
            "hallucination_rate": self.test_phantom_calls(model, test_cases),
            "latency_p95": self.test_latency(model, test_cases, percentile=95),
            "error_recovery": self.test_error_handling(model, test_cases),
            "parallel_atomicity": self.test_parallel(model, test_cases),
        }
        # 综合评分 — Schema遵守只占40%
        results["overall"] = (
            results["schema_compliance"] * 0.25 +
            (1 - results["hallucination_rate"]) * 0.25 +
            results["error_recovery"] * 0.20 +
            results["parallel_atomicity"] * 0.15 +
            (1 - normalize(results["latency_p95"])) * 0.15
        )
        return results

quadrantChart
    title 工具调用模型选择矩阵
    x-axis Schema遵守率低 --> Schema遵守率高
    y-axis 延迟高 --> 延迟低
    quadrant-1 快速可靠
    quadrant-2 精确但慢
    quadrant-3 慢且不可靠
    quadrant-4 快但粗糙
    GPT-4o: [0.85, 0.65]
    Claude Sonnet 4: [0.90, 0.70]
    Gemini 2.5 Pro: [0.80, 0.55]
    DeepSeek V3: [0.70, 0.75]
    Llama 4: [0.60, 0.80]