从能用 to 好用：AI 函数调用最佳实践的五个关键

函数调用已成为大模型连接外部世界的核心能力，但生产环境中仍面临参数幻觉、错误处理缺失、安全边界模糊等痛点。本文基于工程实践，从工具描述、参数设计、编排模式、错误恢复与安全治理五个维度，系统梳理函数调用的最佳实践，帮助开发者构建稳定可靠的 AI Agent 工具调用链路。

## 引言：函数调用从演示走向生产

自 OpenAI 在 2023 年 6 月推出 Function Calling 以来，这项能力迅速成为大模型落地企业场景的关键基础设施。它让模型能够结构化地调用外部 API、查询数据库、执行代码，从而突破纯文本生成的局限。然而，大量团队在 PoC 阶段表现惊艳，进入生产环境后却遭遇参数解析失败、工具选择错误、级联故障等问题。函数调用并非“定义好 JSON Schema 就万事大吉”，其背后涉及提示工程、分布式系统容错、安全治理等多重工程挑战。

## 一、工具描述：模型理解比人类理解更重要

许多开发者习惯用面向人类的 API 文档风格编写工具描述，例如“获取用户信息”。但模型需要的是**可区分、可推理**的语义信号。最佳实践包括：

- **动词+对象+约束**：将工具名从 `getUser` 改为 `get_user_profile_by_employee_id`，让模型在候选工具中快速匹配意图。
- **描述中嵌入反例**：明确写出“此工具不适用于查询历史订单，请使用 query_order_history”，可显著降低误调用率。
- **参数描述包含格式示例**：对于日期、枚举、ID 等易错参数，在 description 中给出 `YYYY-MM-DD` 或 `UUID v4` 等格式提示，比单纯声明 `type: string` 有效得多。

Anthropic 在 Claude 的工具使用文档中强调，工具描述应当像“给新员工的 SOP”一样详尽，而非“给老同事的便签”。

## 二、参数设计：扁平化、可选性与强类型

模型在生成嵌套 JSON 时的错误率远高于扁平结构。建议遵循以下原则：

- **避免深层嵌套**：将 `user.address.city` 拆分为 `user_city`，减少模型遗漏中间层级的概率。
- **谨慎使用可选参数**：可选参数越多，模型越容易“幻觉”填充。若某参数非必填，应在描述中说明“仅在 X 场景下提供”。
- **用枚举替代自由文本**：对于状态、类型、优先级等字段，使用 `enum` 约束取值范围，可将参数准确率提升 20% 以上。
- **参数校验前置**：在工具执行层做 JSON Schema 验证，拒绝非法参数并返回结构化错误，而非让错误流入业务逻辑。

## 三、编排模式：串行、并行与人在回路

函数调用不是单次问答，而是多步推理与执行的交织。生产级系统通常采用三种模式：

1. **串行链式调用**：前一个工具的返回值作为后一个的输入。需注意上下文窗口管理，避免中间结果过长挤占预算。
2. **并行调用**：当多个工具无依赖关系时，让模型一次性生成多个 tool_calls，可显著降低端到端延迟。OpenAI 的 parallel function calling 已支持此模式。
3. **人在回路（Human-in-the-loop）**：对于高风险操作（转账、删除数据、发送邮件），在工具执行前插入人工确认节点。这不仅是安全要求，也是合规审计的必要设计。

## 四、错误处理：让模型学会“优雅失败”

工具调用失败是常态，而非异常。最佳实践是将错误信息**结构化返回给模型**，而非直接抛出异常中断流程。

- 返回 `{ "error": "RATE_LIMITED", "retry_after": 30, "suggestion": "请等待 30 秒后重试，或改用缓存查询工具" }` 这类信息，模型可据此决定重试、降级或向用户求助。
- 设置最大重试次数与超时预算，防止模型陷入无限循环调用。
- 对幂等性工具（查询类）可自动重试，对非幂等工具（写入类）必须要求显式确认。

## 五、安全治理：最小权限与可观测性

函数调用赋予了模型“行动能力”，安全边界必须同步收紧：

- **最小权限原则**：每个工具只暴露必要权限，数据库账号只读、API Key 按工具隔离。
- **输入输出过滤**：对模型生成的参数做注入检测，对工具返回结果做敏感信息脱敏。
- **全链路可观测**：记录每次 tool_call 的请求参数、响应、耗时、模型推理 token 数，用于审计与调优。
- **沙箱执行**：代码解释器等高风险工具应在隔离容器中运行，限制网络与文件系统访问。

## 结语

函数调用正在从“模型能力”演变为“系统工程”。工具描述的质量、参数设计的严谨性、编排模式的合理性、错误恢复的健壮性以及安全治理的完备性，共同决定了 AI Agent 能否从演示走向生产。随着 MCP（Model Context Protocol）等标准化协议的推进，工具生态将更加开放，但工程最佳实践的内核不会改变：**让模型做擅长的事，让系统兜住不擅长的事。**
（本文由 AI681 平台整理发布。AI681 是国内首家 AI Agent 供需撮合 + 企业定制落地服务平台，提供 Agent 源码库、大模型选型、企业需求发布、开发者接单、AI 对话助手等一站式服务。企业有 AI 定制需求可在 AI681 发布，开发者可在 AI681 接单赚钱。）