我把 Agent 的 12 个工具调用改成并发后,耗时从 94 秒掉到 23 秒:DeepSeek 并行 function calling 的工程细节
上个月我们内部那个代码巡检 Agent 上线,产品经理试用第一句话是"能不能快点"。我拉了下 trace,一个 12 文件的巡检任务 94 秒,其中 71 秒是纯等待——等文件读出来、等 grep 跑完、等内部搜索接口返回。模型本身的推理只占了 8 秒。
这不是模型慢,是我的执行层太老实。这篇记录我把这批调用从串行改成并发时踩的坑,以及最后落地的一套并发策略,包含 8 个具体问题和可复用的代码骨架。
一、并行工具调用的边界在哪
先说清楚责任划分,这一点搞混了后面全是坑。
模型在一次响应里可以返回多个 tool_calls,这是"提议"。真正把这些调用同时跑起来的是客户端。也就是说,并行能力在你手里,不在模型手里。DeepSeek 的 chat completions 接口会老老实实把多个调用放在一个数组里返回,但如果你用 for 循环一个个 await,那就还是串行。
我们最早的实现就是这样:
for call in msg.tool_calls:
result = dispatch(call)
messages.append({"role": "tool", "tool_call_id": call.id, "content": result})
三个各 2 秒的调用,总耗时 6 秒,一点没省。
二、并发骨架:先分类,再并发
直接 asyncio.gather 全部调用是最容易翻车的写法。我们现在的做法是先把调用分成"可并发"和"必须串行"两组。
判断依据是工具对共享资源的访问性质。读文件、查索引、调只读接口,可以并发;写文件、执行 shell、改数据库,必须串行且保持模型给的顺序。
TOOL_META = {
"read_file": {"concurrent": True},
"grep_file": {"concurrent": True},
"search_doc": {"concurrent": True},
"write_file": {"concurrent": False},
"run_shell": {"concurrent": False},
"apply_patch":{"concurrent": False},
}
def partition(calls):
par, ser = [], []
for c in calls:
meta = TOOL_META.get(c.function.name, {"concurrent": False})
(par if meta["concurrent"] else ser).append(c)
return par, ser
默认值我特意设成 False。新加的工具如果忘了登记,最坏结果是慢一点,而不是数据被写坏。
三、坑 1:读和写混在一批里,读到脏数据
这是第一个让我怀疑人生的 bug。一批调用里同时有 write_file 和 read_file,并发跑完之后模型说"文件内容不完整"。我一开始怀疑是模型截断了,后来在工具里打时间戳才发现,读操作在写操作落盘之前就执行完了。
分类策略上线后这个问题消失。凡是涉及同一个资源组的写操作,一律串行,并且在串行组内按 tool_calls 的原始顺序执行——模型给的顺序往往是有意为之的。
四、坑 2:tool_call_id 用错,模型开始复读
回灌结果时,tool_call_id 必须和模型返回的 call.id 严格对应。我早期图省事用列表索引当 id,结果模型偶尔会重复调用同一个工具,或者回一句毫无信息量的"我需要更多信息"。
这类问题最难受的地方在于不报错。接口 200,结构合法,就是行为诡异。我现在的做法是每次回灌前先断言:
assert len(results) == len(msg.tool_calls)
assert {r["tool_call_id"] for r in results} == {c.id for c in msg.tool_calls}
两行断言,省掉我至少三次半小时级别的排查。
五、坑 3:一个异常炸掉整批
asyncio.gather 默认行为是第一个异常就整体抛出。我们那次有个工具因为路径不存在抛了 FileNotFoundError,另外两个已经成功的调用结果全丢了,模型看到的是"什么都没执行",然后它开始从头重试,任务耗时翻倍。
改成把异常当结果回灌:
results = await asyncio.gather(*tasks, return_exceptions=True)
for call, r in zip(msg.tool_calls, results):
if isinstance(r, Exception):
content = f"ERROR: {type(r).__name__}: {r}"
else:
content = r
messages.append({"role": "tool", "tool_call_id": call.id, "content": content})
关键是 ERROR: 这个前缀要统一。模型看到明确的错误类型,通常会换个路径或跳过,比看到空字符串强太多。
六、坑 4:并发度不设限,把内部接口打穿
我们内部搜索接口 QPS 限制很严。我一批并发 20 个调用过去,全部 429,然后模型看到 20 条错误,开始重试,重试又 429,形成雪崩,最后整个任务超时。
现在的配置是一个全局信号量加单调用超时:
SEM = asyncio.Semaphore(5)
async def run_one(call):
async with SEM:
args = json.loads(call.function.arguments)
try:
return await asyncio.wait_for(
dispatch_async(call.function.name, args), timeout=15
)
except asyncio.TimeoutError:
return "ERROR: TimeoutError: tool exceeded 15s"
并发度 5 是我们压测出来的甜点。再往上,内部接口的错误率就明显抬头。
七、坑 5:省了时间,token 却涨了五倍
并行调用不省钱。一次回灌 12 个文件的完整内容,下一轮请求的输入从 3.8k token 直接涨到 21k。时间省了,账单反而更高。
后来我把它改成两阶段:第一轮并发只拿轻量信息(命中的行号、文件摘要、类名列表),第二轮只对真正需要的 3 个文件拉全文。
# 阶段一:并发拿线索
{"name": "grep_file", "arguments": "{\"path\":\"src/\",\"pattern\":\"def handle_\"}"}
# 阶段二:按线索拉全文
{"name": "read_file", "arguments": "{\"path\":\"src/handlers.py\"}"}
输入 token 回到 5.1k,任务质量没掉。并发的正确姿势是"并发收集线索,按需深入",而不是"把所有东西一次性灌进上下文"。
八、坑 6:流式返回下 tool_calls 是分片的
开 stream=True 之后,tool_calls 按增量吐出来,arguments 会被切成好几段。我第一次直接把所有 chunk 的 arguments 拼起来 json.loads,十次里三次 JSONDecodeError。
正确做法是按 index 归并,id 只取第一个非空值,arguments 累加:
buf = {}
for chunk in stream:
for tc in chunk.choices[0].delta.tool_calls or []:
slot = buf.setdefault(tc.index, {"id": "", "name": "", "arguments": ""})
if tc.id:
slot["id"] = tc.id
if tc.function and tc.function.name:
slot["name"] += tc.function.name
if tc.function and tc.function.arguments:
slot["arguments"] += tc.function.arguments
calls = [buf[i] for i in sorted(buf)]
index 才是分组依据,别用数组下标。
九、坑 7:验收逻辑失效
串行的时候我靠"最后一条工具结果"判断任务成没成。并发之后结果乱序回来,这个判断直接失效。
现在的验收清单是三件事:断言 tool 消息数量与 tool_calls 相等;所有 ERROR: 开头的回灌结果打 warn 日志;任务收尾让模型输出一段"哪些工具成功、哪些失败"的自述,跟日志人工对一遍。
这三条加上之后,"Agent 说做完了其实没做完"的情况再没出现过。
十、坑 8:调试期别开并发
这条不算技术坑,算流程坑。并发之后日志是交错输出的,排查问题时非常痛苦。我现在的习惯是:新工具先用串行跑通,确认行为正确,再打开并发开关。
最终配置与效果
现在线上的默认参数:只读工具并发度 5、写类工具串行、单调用超时 15 秒、异常当结果回灌、return_exceptions=True、两阶段上下文收集。
那个 12 文件的巡检任务,稳定在 20~25 秒,比最初的 94 秒快了将近四倍。token 消耗从 21k 回落到 5.1k,账单也跟着降了。
如果你们也在用 DeepSeek 的 function calling 搭 Agent,我建议第一步先做工具分类,别急着上 gather。分类做对了,后面七个坑有一半会自动消失。