工具调用 on 姚玉亮的网络日志

Function Calling 在企业工具调用场景的工程化

Sun, 06 Apr 2025 10:30:00 +0800

拼 prompt 的 JSON 靠不住

知识库问答服务最早的工具调用，是把工具列表拼进 system prompt，让模型自己输出 JSON。结果经常漏字段、枚举值写错，甚至回一段自然语言而不是 JSON。

后来 OpenAI 兼容协议支持了 Function Calling，我们切到原生 tool_calls，日子好过了一点。但生产环境又冒出新问题：模型选错工具、参数不合法、工具执行超时、多轮调用陷入死循环。

这篇讲我们怎么把它从"能跑通"做成"生产可用"。

一个 Tool 接口，一个注册表

我们抽象了一个 Tool 接口，所有工具实现它，框架负责注册、schema 生成、参数校验、执行和结果回填：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


type Tool interface {
 Name() string
 Description() string
 Schema() *jsonschema.Schema // 入参 JSON Schema
 Invoke(ctx context.Context, args json.RawMessage) (any, error)
}

type Registry struct {
 tools map[string]Tool
}

func (r *Registry) Definitions() []openai.Tool {
 defs := make([]openai.Tool, 0, len(r.tools))
 for _, t := range r.tools {
 defs = append(defs, openai.Tool{
 Type: "function",
 Function: openai.FunctionDefinition{
 Name: t.Name(),
 Description: t.Description(),
 Parameters: t.Schema(),
 },
 })
 }
 return defs
}

每个工具自己声明入参 struct，用 tag 生成 JSON Schema，避免手写 schema 跟代码脱节：

1
2
3
4
5
6
7
8
9


type SearchDatasetArgs struct {
 DatasetID string `json:"dataset_id" jsonschema:"required,description=数据集ID"`
 Query string `json:"query" jsonschema:"required,description=检索关键词"`
 TopK int `json:"top_k" jsonschema:"description=返回条数,default=5"`
}

func (s *SearchDatasetTool) Schema() *jsonschema.Schema {
 return jsonschema.Reflect(&SearchDatasetArgs{})
}

执行循环才是核心

一次用户请求内维护一个 maxIterations（默认 5），每次拿到模型响应后：

如果没有 tool_calls，把内容作为最终回答返回；
如果有，逐个执行工具，把结果以 role=tool 消息追加到对话历史；
再次请求模型，直到模型不再调用工具或达到迭代上限。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


for iter := 0; iter < maxIter; iter++ {
 resp, err := s.llm.Chat(ctx, msgs, tools)
 if err != nil {
 return nil, err
 }
 if len(resp.ToolCalls) == 0 {
 return resp.Content, nil
 }
 for _, call := range resp.ToolCalls {
 tool, ok := reg.Get(call.Function.Name)
 if !ok {
 msgs = append(msgs, toolErrMsg(call.ID, "tool not found"))
 continue
 }
 if err := validateArgs(tool.Schema(), call.Function.Arguments); err != nil {
 msgs = append(msgs, toolErrMsg(call.ID, err.Error()))
 continue
 }
 result, err := invokeWithTimeout(ctx, tool, call.Function.Arguments)
 if err != nil {
 msgs = append(msgs, toolErrMsg(call.ID, err.Error()))
 continue
 }
 msgs = append(msgs, openai.ToolMessage(call.ID, result))
 }
}

五个坑

参数校验必须做。就算有 schema，模型照样会输出类型错误或枚举外的值。我们在执行前用 JSON Schema 校验一遍，失败不直接报错给用户，而是把错误信息作为 tool result 回给模型，让它自我修正。通常一两轮就能改对。

工具数量和描述质量要严控。工具一多，模型选错的概率直线上升。我们的经验是单次对话注入的工具不超过 15 个；工具名用动宾结构（search_dataset、export_order），description 写清"什么时候用、什么时候不要用"。这比罗列参数说明更能降低误调用。

执行要隔离，超时要兜底。工具可能查数据库、调第三方接口，不能让一个慢工具拖垮整个会话。每个工具执行都包一层带超时的 context，用带缓冲的 channel 接结果，超时就返回错误，让模型自己决定要不要重试。

死循环要防。除了 maxIterations，我们还记录每次调用的"工具名+参数"hash，连续两次完全相同的调用直接中断，免得模型用同样的参数反复撞同一个错误。

结果要裁剪。有些工具（SQL 查询、文献检索）返回的数据量很大，直接塞回上下文会爆 token。我们在工具层统一做裁剪和结构化摘要，只给模型相关的前 N 条和总命中数，完整结果通过引用 ID 让前端按需拉取。

后来

Function Calling 的工程化，难点是围绕模型的不确定性做防御：schema 校验、执行隔离、迭代上限、结果裁剪。知识库问答服务用统一的 Tool 接口和执行循环，把这些横切逻辑收敛到框架里。新增业务工具只要实现接口、把描述写好，就能安全地交给模型调用。

封面图：M McBey / Flickr · CC BY 2.0

MCP 协议接入实践：让大模型调用多源工具

Thu, 06 Mar 2025 10:30:00 +0800

每接一个工具，就得改一轮

知识库问答服务上线后，陆陆续续接了不少工具：知识库检索、订单查询、数据集导出、学术文献检索（OpenAlex）。每个工具都是自定义的 HTTP 接口，工具描述、入参、错误返回各写各的。更要命的是，每接一个，适配代码要改一轮，Prompt 里的工具清单也得跟着改一轮，工具越多维护越累。

2024 年底 Model Context Protocol（MCP）开始流行。它定义了一套 client/server 之间发现工具、调用工具的标准 JSON-RPC 协议，把"模型怎么发现和调用工具"这件事标准化了。我们决定把知识库问答服务的工具层改造成 MCP client：内部工具和第三方工具都以 MCP server 的形式接入，业务层只面向一套接口编程。

三层：Transport、Session、工具适配

Transport 层：支持 stdio（本地子进程）和 SSE（远程 server）两种传输，对接不同来源的工具；
Session 层：封装 MCP 的 initialize、tools/list、tools/call，维护会话状态，做超时与重试；
工具适配层：把 MCP 返回的 tool schema 转成统一 LLM 适配层里的 ToolDef，调用结果再回填给模型。

服务里维护一个 MCPRegistry，启动时按配置拉起或连接多个 server，把每个 server 暴露的工具注册进工具表。

注册表与会话

配置结构和工具定义长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


type MCPServerConfig struct {
 Name string `json:"name" yaml:"name"`
 Transport string `json:"transport" yaml:"transport"` // stdio | sse
 Command string `json:"command" yaml:"command"` // stdio
 Args []string `json:"args" yaml:"args"`
 URL string `json:"url" yaml:"url"` // sse
}

type ToolDef struct {
 Name string
 Description string
 Parameters map[string]any
 Server string // 来自哪个 MCP server
}

type MCPRegistry struct {
 mu sync.RWMutex
 sessions map[string]MCPSession
 tools map[string]ToolDef // key: server.tool
}

初始化时遍历配置：stdio 类型用 exec.Command 拉起进程，通过 stdin/stdout 交换 JSON-RPC 消息；SSE 类型发起长连接。握手成功后调 tools/list 拉取工具清单并缓存。

工具调用时，先从模型返回的 tool_calls 里解析出工具名（带 server 前缀），再路由到对应 session：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


func (r *MCPRegistry) Call(ctx context.Context, server, tool string, args map[string]any) (string, error) {
 r.mu.RLock()
 sess, ok := r.sessions[server]
 r.mu.RUnlock()
 if !ok {
 return "", fmt.Errorf("mcp server %s not found", server)
 }
 req := map[string]any{
 "jsonrpc": "2.0",
 "id": snowflake.NextID(),
 "method": "tools/call",
 "params": map[string]any{
 "name": tool,
 "arguments": args,
 },
 }
 return sess.Request(ctx, req)
}

工具定义在统一 LLM 适配层里只有一份 ToolDef 切片，底下是 OpenAI、Azure 还是 VLLM 都无所谓。模型选完工具后分两类：内置函数走本地函数表，MCP 工具走 Registry.Call，结果统一塞回 role=tool 的消息。

四个坑

第一个坑是 stdio 子进程变僵尸。早期没给子进程设置进程组，主服务重启后旧的 MCP server 进程还挂着，时间一长服务器上堆了一堆 node、python 进程。后来用 SysProcAttr{Setpgid: true} 建独立进程组，关 session 时给整个组发 SIGTERM，才解决。

第二个坑是工具描述长度。有的 MCP server 把整段文档塞进 description，拼进 Prompt 里 token 直接飙升。现在注册阶段对 description 做截断，也要求内部 server 写工具时遵循"一句话用途加关键字段说明"的格式。

第三个是流式调用和 MCP 的衔接。主对话是 SSE 流式输出，但 MCP 的 tools/call 是请求-响应模型，两边节奏对不上。我们的做法：模型先吐出 tool_calls 增量，聚合成完整调用后再请求 MCP server，拿到结果继续生成；前端通过自定义事件 tool_call、tool_result 展示中间状态，用户能看见模型正在调什么。

最后是安全边界。MCP server 能访问文件系统和数据库，不能随便信任远程地址。我们只允许内网 SSE，stdio server 做白名单；工具参数做 schema 校验，防止模型把用户输入直接拼成危险命令。

接入之后

新增工具从改代码变成加一个 server 配置，工具的复用和独立演进都清爽了很多。对我们这种多模型、多工具的企业问答场景，这层抽象的投入产出比目前看是很高的。

封面图：qubodup / Flickr · CC BY 2.0