一个多余参数就能毁掉 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 列为旧版接口;三家服务商都只是由模型提出调用,函数由你的代码执行
一个参数就足以毁掉一场演示。在较新的 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 个信源
- Using the Messages API
- Streaming messages
- Tool use with Claude
- Streaming API responses
- Function calling
- Why we built the Responses API
- OpenAI API: Responses vs. Chat Completions · 2025-03-11
- Function calling with the Gemini API
- Gemini API | Google AI for Developers
- Text generation | Gemini API | Google AI for Developers