FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

一个多余参数就能毁掉 Claude 演示,先学会原生 API

在 Claude 和 OpenAI 上手写工具调用循环,再对比 Gemini,学会看懂框架掩盖的底层故障。

分享微博

要点速览

  • Claude Messages API 是无状态的:每一轮都要重发完整历史,并记得带上 tool_use_id 返回 tool_result
  • OpenAI Responses API 在 output 数组中返回带 call_id 的 function_call,结果以 function_call_output 的形式发回
  • Gemini 建议新项目使用 Interactions API,并把 generateContent 列为旧版接口;三家服务商都只是由模型提出调用,函数由你的代码执行
工具调用循环示意图,分为两条泳道。上方泳道是模型(API):只返回提议,从不运行函数。下方泳道是你的代码。第 1 步:代码发送包含历史和工具的请求。第 2 步:模型提议一次带 id 的工具调用。第 3 步(橙色高亮):代码运行 get_order_status 函数。第 4 步:代码带上对应的调用 id 发回结果。一条虚线箭头回到第 2 步,注明只要模型继续提议调用,循环就会重复,并设有迭代上限。旁注写道:工具调用循环出问题时,先查自己的代码。下方三栏列出命名方式:Claude Messages 使用 stop_reason "tool_use"、tool_result 和 tool_use_id;OpenAI Responses 使用 function_call 条目、function_call_output 和 call_id;Gemini 由模型提议函数调用、应用返回结果,id 匹配方式需查文档,新项目应使用 Interactions API。
三家服务商都只由模型提议函数调用,真正运行函数的是你的代码,区别只在字段名以及结果与调用的匹配方式。

一个参数就足以毁掉一场演示。在较新的 Claude 模型上,只要把 temperature、top_p 或 top_k 设成非默认值,API 就会返回 400 错误。从 4.6 系列开始,预填充(prefill)也会被拒绝,所以从旧博客里复制来的代码,可能当着客户的面直接崩掉。

框架会把这些细节藏起来,但藏不了一辈子。作为前线部署工程师(FDE),你会发现客户系统往往坏在最底层:header 写错、id 对不上、某一轮对话丢了。要学会读懂这类故障,最快的办法是至少亲手调用一次原生 API。

本指南围绕一个小脚本展开,脚本里只有一个工具 get_order_status(order_id),它通过模拟函数查询订单状态。你会在 Claude 和 OpenAI 上走完请求、流式输出和工具调用的完整流程,再对比 Gemini 如何处理同样的问题。你需要准备 Python、写入环境变量的 API key,以及 anthropic 和 openai 两个 SDK。

为便于阅读,下面的代码做了精简,没有错误处理和重试。模型名放在 MODEL 和 OA_MODEL 两个变量里,请按各家文档填入当前的模型名。

第 1 步:为什么从 curl 开始?

在让 SDK 封装请求之前,你需要先看清原始请求。Claude Messages API 接收 POST /v1/messages,用 x-api-key header 认证,还需要一个 anthropic-version header。在 Anthropic 的示例中,max_tokens 和 messages 数组是两个必填字段。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "'"$CLAUDE_MODEL"'", "max_tokens": 512,
       "messages": [{"role": "user", "content": "你好"}]}'

**检查:**你应该收到一段包含回复的 JSON。接着发送第二轮,只带上新问题。模型不会记得第一轮的任何内容,因为 Messages API 是无状态的:每一轮都必须重发完整的对话历史。

所以,当客户抱怨模型“忘了”上一轮时,首先要查的就是这里。

第 2 步:流式输出应当逐步显示文本

用户盯着空白屏幕等上十秒,就会以为系统卡死了。在 Claude 上,设置 "stream": true,即可通过服务器发送事件(SSE)分段接收响应。Python SDK 自带 text_stream 辅助方法,不必自己解析事件。

import anthropic
client = anthropic.Anthropic()
history = [{"role": "user", "content": "用 3 句话解释 SSE"}]

with client.messages.stream(model=MODEL, max_tokens=512,
                            messages=history) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

**检查:**文本应当在终端里逐步出现。如果整段文字一次性出现,就要排查你的机器和 API 之间是否有代理或网关先缓冲了响应再转发。在客户的内网环境里,这个问题值得尽早提出。

第 3 步:模型提出调用,你的代码执行函数

这是本指南最重要的概念。当 Claude 想使用客户端工具时,它会返回 stop_reason: "tool_use",并附带一个或多个 tool_use 块。你的代码执行函数,再把结果放进 tool_result 块发回。服务端工具则不同,它们运行在 Anthropic 的基础设施上。

先写一个返回字符串的模拟函数,声明工具,再写一个调用 API 的公共函数:

def get_order_status(order_id): return f"订单 {order_id}:派送中"  # 模拟数据

tools = [{"name": "get_order_status",
          "description": "根据订单 ID 查询订单状态",
          "input_schema": {"type": "object",
              "properties": {"order_id": {"type": "string"}},
              "required": ["order_id"]}}]

def ask():
    return client.messages.create(model=MODEL, max_tokens=512,
                                  tools=tools, messages=history)

然后把问题放进 history,编写循环,并限制轮数,防止无限循环:

history = [{"role": "user", "content": "订单 A123 现在在哪?"}]
resp = ask()
for _ in range(5):
    if resp.stop_reason != "tool_use":
        break
    history.append({"role": "assistant", "content": resp.content})
    results = [{"type": "tool_result", "tool_use_id": b.id,
                "content": get_order_status(**b.input)}
               for b in resp.content if b.type == "tool_use"]
    history.append({"role": "user", "content": results})
    resp = ask()

**检查:**在 get_order_status 里加一行日志。如果日志出现了,且最终回答包含函数返回的“派送中”字样,说明循环可以正常工作。

还要记住,工具并不免费:API 会悄悄插入一段隐藏的系统提示词来启用工具调用,tools 参数以及 tool_use 和 tool_result 块都会计入 token。

第 4 步:OpenAI Responses 换了名字,逻辑不变

在 Responses API 上,循环是一样的,只是名字变了。函数调用位于 output 数组中,是一个 type 为 function_call 的条目,带有 call_id。你用同一个 call_id,以 function_call_output 条目返回结果。

按 OpenAI 的格式声明工具,复用第 3 步的 schema 和模拟函数:

import json
from openai import OpenAI
oa = OpenAI()
oa_tools = [{"type": "function", "name": "get_order_status",
             "description": "根据订单 ID 查询订单状态",
             "parameters": tools[0]["input_schema"]}]
inputs = [{"role": "user", "content": "订单 A123 现在在哪?"}]

然后执行一轮函数调用,并把结果发回:

resp = oa.responses.create(model=OA_MODEL, input=inputs, tools=oa_tools)
for item in resp.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        inputs.append(item)
        inputs.append({"type": "function_call_output",
                       "call_id": item.call_id,
                       "output": get_order_status(**args)})
resp = oa.responses.create(model=OA_MODEL, input=inputs, tools=oa_tools)

注意,这段代码只处理一轮函数调用,不同于第 3 步中带上限的循环。如果模型收到结果后还会提出新的调用,就用类似的 for 循环包起来,直到 output 中不再出现 function_call 条目为止。

Responses API 同样用 stream=True 开启流式输出,但返回的是一系列语义事件,每个事件都有自己的类型。在编写任何处理逻辑之前,先打印每个 event.type,看看事件流长什么样:

for event in oa.responses.create(model=OA_MODEL, input=inputs,
                                 tools=oa_tools, stream=True):
    print(event.type)

**检查:**你会看到一串事件,每类事件都有不同的名字。找出携带新增文本的那个事件,并对照文档确认它的名字,不要靠猜。

第 5 步:Gemini 正在更换 API,别照抄旧代码

在 Gemini 上,陷阱在于选哪个 API。当前文档建议新项目使用 Interactions API,并把 generateContent 列为旧版接口,因此网上那些使用 generateContent 的教程可能已经过时。通过 REST 调用时,key 放在 x-goog-api-key header 中。

# 精简骨架:endpoint 和 body 请以 Interactions API 文档页为准
curl "$GEMINI_ENDPOINT" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "content-type: application/json" \
  -d @request.json

本指南没有给出现成的 Gemini 工具调用循环,因为 Interactions API 的请求结构应当直接从文档获取。原则不变:Gemini 不会自己执行函数。它提出调用,由你的应用执行函数并发回结果。

默认情况下,模型生成完毕后才会返回响应,所以必须开启流式输出才能分段接收。

**拓展练习:**按照文档,在 Interactions API 上重建 get_order_status 循环,用同样的订单 A123 问题,再对比 Gemini 与另外两家在提出函数调用上的差异。

三个 API,一张对比表

Claude Messages OpenAI Responses Gemini
流式输出 stream: true,SSE stream=True,语义事件 开启流式输出后分段接收
工具调用信号 stop_reason: "tool_use" output 中的 function_call 条目 模型提出函数调用
返回结果 tool_result + tool_use_id function_call_output + call_id 应用发回结果
历史 客户端重发全部内容 可在服务端保存状态 取决于所选 API

真实项目中会遇到的错误

最常见的是过时的采样配置:如果客户的设置里还留着旧模型时代的 temperature: 0.2,较新的 Claude 模型就会返回 400。其次是缺少 id:tool_result 缺了 tool_use_id,或 function_call_output 缺了 call_id,模型就分不清某个结果属于哪次调用。还有一种是每次请求都塞进几十个工具,然后惊讶于 token 账单飙升。

还有一个架构决策需要向客户讲清楚。Anthropic 把 Messages API 定位为面向需要精细控制的手写 Agent 循环;OpenAI 则表示,Responses API 能在多轮之间保留推理内容,这是 Chat Completions 做不到的,并且托管工具在服务端运行。

Simon Willison 也指出,Responses 可以替你在服务端管理对话状态。

作为 FDE,比较稳妥的做法是在第一次会议上问客户两个问题:对话历史允许存放在哪里?工具由谁来执行?

一家希望所有日志都留在自己系统内的银行,更适合无状态模式;而一家需要快速上线的初创公司,可能更愿意把部分状态管理交给服务端。

把练习变成简历上的证据

简历上写一句“有 LLM 经验”,很难证明你理解框架之下的那一层,而当框架在客户现场出故障时,你要调试的恰恰是这一层。把这个脚本推到 GitHub 上,让 Claude 和 OpenAI 两个适配器共用一个 call_tool 接口,再附一份 README,记录你遇到的每个 400 错误以及修复方法。

在简历上具体写明:你在 Claude Messages 和 OpenAI Responses 上手写过工具调用循环;如果完成了拓展练习,再加上 Gemini Interactions API。

阅读岗位描述时,留意“integrate with multiple model providers”或“build agent loops”这类说法。这正是你刚做完的练习,而现在你可以用具体的字段来描述它,而不只是报出框架的名字。

这篇文章对你有帮助吗?

10 个信源
路线图上的下一篇 · 阶段 3: AI 应用提示词要不要加码,让评测分数说了算在笔记本上用 20 条标注工单对比四种技术,只在数据证明不够时才换更重的方案。