Claude + GPT API 实战手册（2026 版）

应用市场2026-05-15 23:49

title: Claude + GPT API 实战手册（2026 版）：从基础调用到 Agent / 缓存 / Claude Code 全覆盖

date: 2026-05-14
categories: [AI编程, 大模型, API开发]
tags: [Claude, GPT, Claude Code, Codex, Function Calling, Prompt Caching, Anthropic, OpenAI]

Claude + GPT API 实战手册（2026 版）

上一篇文章 [《AI 编程助手三强争霸（2026 版）》] 写完后，不少同行私信问"光知道哪家强不够，能不能给一份能直接上手的 API 实战手册？"

那就来了。这一篇用 Python 为主、Node.js/cURL 为辅，把 Claude 和 GPT 两家 API 的核心用法系统讲透。

全文按"基础 → 工具调用 → 长上下文 → 成本优化 → 命令行实战"五个模块展开，所有代码都基于 2026 年 5 月最新模型（Claude Opus 4.7 / GPT-5.5），可直接复制粘贴运行。

目录

  • 一、准备工作（账号、Key、SDK、国内访问）
  • [二、基础调用：Messages / Responses 双家对比](#二、基础调用：Messages / Responses 双家对比)
  • [三、流式输出 + 多轮对话](#三、流式输出 + 多轮对话)
  • [四、Function Calling / Tool Use / Agent 循环](#四、Function Calling / Tool Use / Agent 循环)
  • [五、长上下文 + 文件 + 图像处理](#五、长上下文 + 文件 + 图像处理)
  • [六、成本优化：Prompt Caching + Batch API + 模型路由](#六、成本优化：Prompt Caching + Batch API + 模型路由)
  • [七、Claude Code / Codex CLI 实战](#七、Claude Code / Codex CLI 实战)
  • 八、生产环境避坑清单

一、准备工作

1.1 申请 API Key

提供商 注册入口 备注
Anthropic（Claude） https://console.anthropic.com 新账号送 $5 试用额度，无需信用卡
OpenAI（GPT） https://platform.openai.com 需要绑定信用卡（境外卡）或 Plus 订阅

⚠️ 国内同学注意：两家官网目前都需要科学上网或 IP 不能是大陆。Anthropic 对支付方式更宽松一些（支持 Stripe），OpenAI 严格按 IP 地区识别。

1.2 安装 SDK

Python（推荐）：

bash 复制代码 
# Claude
pip install anthropic

# OpenAI（GPT）
pip install openai

# 我们后面所有示例还会用到
pip install httpx python-dotenv pillow

Node.js / TypeScript：

bash 复制代码 
npm install @anthropic-ai/sdk openai

1.3 配置环境变量

新建 .env 文件（千万别 commit 到 Git）：

bash 复制代码 
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxx
OPENAI_API_KEY=sk-proj-xxxxxxxxxx

Python 代码里这样加载：

python 复制代码 
from dotenv import load_dotenv
load_dotenv()

# SDK 会自动读取对应的环境变量
import anthropic
import openai

claude = anthropic.Anthropic()      # 读 ANTHROPIC_API_KEY
gpt = openai.OpenAI()               # 读 OPENAI_API_KEY

1.4 国内访问的三种典型方案

方案 说明 适合谁
官方 API + 代理 设置 HTTPS_PROXY 走自己的代理服务器 个人开发，需要"原版体验"
第三方中转 API 通过 OpenRouter / AIMLAPI 等代理网关，国内可直连 团队 / 公司，无法翻墙
国内合规模型 DeepSeek / GLM / 通义 等，多数兼容 OpenAI / Anthropic 协议 需要数据合规、稳定可用

代理方式示例：

python 复制代码 
import os
os.environ["HTTPS_PROXY"] = "http://127.0.0.1:7890"

# 之后正常使用 SDK 即可
client = anthropic.Anthropic()

第三方中转网关示例（以 OpenAI 兼容协议接 Claude 为例）：

python 复制代码 
client = openai.OpenAI(
    api_key="<你的中转 Key>",
    base_url="https://api.aimlapi.com/v1"  # 第三方中转
)

response = client.chat.completions.create(
    model="anthropic/claude-opus-4-7",
    messages=[{"role": "user", "content": "Hello"}]
)

二、基础调用

两家在 2026 年的"推荐方式"已经分化：

  • Claude ：统一用 client.messages.create()
  • OpenAI ：GPT-5.5 系列强烈推荐 用新的 Responses API （client.responses.create()），旧的 chat.completions.create() 也兼容但功能受限

2.1 Claude：Messages API

最小可用示例：

python 复制代码 
import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用一句话解释什么是 DVL（多普勒测速仪）"}
    ]
)

print(message.content[0].text)
print(f"输入 tokens: {message.usage.input_tokens}")
print(f"输出 tokens: {message.usage.output_tokens}")

加 system prompt：

python 复制代码 
message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    system="你是一位资深的水下机器人嵌入式工程师，回答简洁、贴近工程实践。",
    messages=[
        {"role": "user", "content": "Nucleus1000 DVL 的 lever arm 补偿应该在哪一层做？"}
    ]
)
print(message.content[0].text)

🔥 重要变更（Opus 4.7） ：

从 Opus 4.7 开始，temperature / top_p / top_k 三个采样参数被移除，传了会报 400 错误。如果你需要"更确定"的输出，请在 prompt 里直接说明（比如 "Return only the JSON, no explanation"）。

同样的，扩展思考（extended thinking）也从"budget_tokens"改成了 adaptive thinking，由模型自己决定要不要多想。

2.2 GPT：Responses API（推荐）

python 复制代码 
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    input="用一句话解释什么是 DVL（多普勒测速仪）"
)

# 新版 SDK 提供 output_text 快捷字段
print(response.output_text)
print(f"输入 tokens: {response.usage.input_tokens}")
print(f"输出 tokens: {response.usage.output_tokens}")

加 system instruction（Responses API 里叫 instructions）：

python 复制代码 
response = client.responses.create(
    model="gpt-5.5",
    instructions="你是一位资深的水下机器人嵌入式工程师，回答简洁、贴近工程实践。",
    input="Nucleus1000 DVL 的 lever arm 补偿应该在哪一层做？",
    reasoning={"effort": "medium"},   # minimal/low/medium/high/xhigh
    text={"verbosity": "low"}         # low/medium/high
)
print(response.output_text)

🔥 GPT-5.5 几个关键参数：

  • reasoning.effort：思考深度（默认 medium）。复杂 agent 任务用 high/xhigh，简单分类用 low。
  • text.verbosity：输出的"啰嗦程度"。代码生成场景用 low 能省不少 token。
  • GPT-5.5 在 Chat Completions API 里不再支持 reasoning: none + 工具调用，必须用 Responses API。

2.3 兼容旧代码：Chat Completions

如果你的项目还在用旧的 chat.completions，下面是对比写法：

python 复制代码 
# 旧风格（仍可用）
response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "你是工程师..."},
        {"role": "user", "content": "Hello"}
    ]
)
print(response.choices[0].message.content)

2.4 两家参数对照表

概念 Claude (Messages) OpenAI (Responses)
系统提示 system="..." instructions="..."
用户输入 messages=[{"role":"user", "content":"..."}] input="..." 或 input=[...]
最大输出 max_tokens=4096 隐式（按需自动）
思考深度 adaptive（自动） reasoning={"effort": "..."}
输出简洁度 通过 prompt 控制 text={"verbosity": "..."}
取消采样参数 ✅ 已移除（4.7） 仍支持 temperature
主流模型 ID claude-opus-4-7 claude-sonnet-4-6 claude-haiku-4-5-20251001 gpt-5.5 gpt-5.5-pro gpt-5.4

三、流式输出 + 多轮对话

3.1 Claude 流式

python 复制代码 
import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[{"role": "user", "content": "用 Python 写一个 CSV 解析函数，带异常处理"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print()  # 末尾换行

# 流结束后还能拿到完整的 message 对象
final = stream.get_final_message()
print(f"\n总耗 tokens：{final.usage.output_tokens}")

3.2 GPT 流式（Responses API）

python 复制代码 
from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="gpt-5.5",
    input="用 Python 写一个 CSV 解析函数，带异常处理",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print(f"\n\n总耗 tokens：{event.response.usage.output_tokens}")

3.3 多轮对话：把历史当作"接力棒"

核心原则 ：API 本身是无状态的，每次请求都要把完整的历史传进去。

Claude 写法：

python 复制代码 
import anthropic

client = anthropic.Anthropic()
history = []

def chat(user_msg: str) -> str:
    history.append({"role": "user", "content": user_msg})
    
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system="你是一位水下机器人嵌入式工程师。",
        messages=history
    )
    
    reply = resp.content[0].text
    history.append({"role": "assistant", "content": reply})
    return reply

print(chat("我在做 ROV 项目，传感器用的是 BWsensing AH100c"))
print(chat("帮我设计一下姿态数据采集的数据结构"))
print(chat("如果还要同时接 DMC610 做对比，结构怎么扩展？"))

GPT 用 Responses API 还有一个新机制 ：可以用 previous_response_id 让服务端帮你维护上下文：

python 复制代码 
from openai import OpenAI

client = OpenAI()

# 第一轮
r1 = client.responses.create(
    model="gpt-5.5",
    input="我在做 ROV 项目，传感器用的是 BWsensing AH100c"
)

# 第二轮：传 previous_response_id，省得自己拼历史
r2 = client.responses.create(
    model="gpt-5.5",
    previous_response_id=r1.id,
    input="帮我设计一下姿态数据采集的数据结构"
)

print(r2.output_text)

💡 小技巧 ：长对话场景下，每过 N 轮自动摘要压缩前文，能显著降低 token 消耗。我自己的做法是每 20 轮跑一次"总结当前会话要点"，然后用摘要替换前面所有原文。

四、Function Calling / Tool Use / Agent 循环

这是 API 使用的"分水岭"------会用工具调用 = 能做 Agent，不会用 = 只能做聊天机器人。

4.1 Claude Tool Use

Step 1：定义工具
python 复制代码 
tools = [
    {
        "name": "get_dvl_status",
        "description": "查询指定 DVL 设备的当前工作状态，包括速度、底跟踪、温度、电压等。",
        "input_schema": {
            "type": "object",
            "properties": {
                "device_id": {
                    "type": "string",
                    "description": "DVL 设备 ID，例如 'nucleus1000-01'"
                },
                "fields": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "要返回的字段，可选: velocity, bottom_track, temperature, voltage"
                }
            },
            "required": ["device_id"]
        }
    },
    {
        "name": "send_thruster_command",
        "description": "向 ROV 推进器发送 PWM 控制指令。",
        "input_schema": {
            "type": "object",
            "properties": {
                "thruster_id": {"type": "integer", "minimum": 0, "maximum": 5},
                "pwm": {"type": "integer", "minimum": 1100, "maximum": 1900}
            },
            "required": ["thruster_id", "pwm"]
        }
    }
]
Step 2：让 Claude 决定调哪个工具
python 复制代码 
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    tools=tools,
    messages=[
        {"role": "user", "content": "查一下 nucleus1000-01 的速度和温度。"}
    ]
)

# Claude 决定调用工具时，stop_reason 会是 "tool_use"
print("stop_reason:", response.stop_reason)

for block in response.content:
    if block.type == "tool_use":
        print(f"调用工具: {block.name}")
        print(f"参数: {block.input}")

输出大致如下：

复制代码 
stop_reason: tool_use
调用工具: get_dvl_status
参数: {'device_id': 'nucleus1000-01', 'fields': ['velocity', 'temperature']}
Step 3：执行工具，把结果回传给 Claude

完整的 agentic loop（智能体循环）：

python 复制代码 
def run_tool(name: str, input_dict: dict) -> str:
    """模拟工具执行------实际项目里这里就是你真实的业务函数"""
    if name == "get_dvl_status":
        return '{"velocity": [0.12, -0.03, 0.01], "temperature": 24.5}'
    elif name == "send_thruster_command":
        return '{"status": "ok"}'
    return "unknown tool"


def agent_loop(user_msg: str, max_iters: int = 10):
    messages = [{"role": "user", "content": user_msg}]
    
    for i in range(max_iters):
        resp = client.messages.create(
            model="claude-opus-4-7",
            max_tokens=2048,
            tools=tools,
            messages=messages
        )
        
        # 把模型的完整 response 加入 history
        messages.append({"role": "assistant", "content": resp.content})
        
        # 没有工具调用，循环结束
        if resp.stop_reason != "tool_use":
            for block in resp.content:
                if hasattr(block, "text"):
                    print(f"\n[最终回答]\n{block.text}")
            return
        
        # 有工具调用，执行所有工具
        tool_results = []
        for block in resp.content:
            if block.type == "tool_use":
                print(f"[第 {i+1} 轮] 调用 {block.name}({block.input})")
                result = run_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })
        
        messages.append({"role": "user", "content": tool_results})


agent_loop("查一下 1 号 DVL 的速度，如果速度模长超过 0.3，让推进器 0 输出 1500（停止）。")

🔥 关键点 ：tool_result 是以 user 消息的形式回传的，而不是 tool 角色。这是 Claude 和 OpenAI 协议最大的不同之一。

4.2 GPT Function Calling（Responses API）

对应的 GPT 版本：

python 复制代码 
from openai import OpenAI

client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "get_dvl_status",
        "description": "查询 DVL 设备状态",
        "parameters": {
            "type": "object",
            "properties": {
                "device_id": {"type": "string"},
                "fields": {"type": "array", "items": {"type": "string"}}
            },
            "required": ["device_id"]
        }
    }
]

response = client.responses.create(
    model="gpt-5.5",
    input="查一下 nucleus1000-01 的速度和温度",
    tools=tools
)

# 遍历 output items 找工具调用
for item in response.output:
    if item.type == "function_call":
        print(f"调用 {item.name}({item.arguments})")
        # item.call_id 是后续回传结果时要用的 ID

回传工具结果：

python 复制代码 
import json

# 假设我们执行了工具，得到结果
tool_output = json.dumps({"velocity": [0.12, -0.03, 0.01], "temperature": 24.5})

response2 = client.responses.create(
    model="gpt-5.5",
    previous_response_id=response.id,
    input=[{
        "type": "function_call_output",
        "call_id": "<上一步的 call_id>",
        "output": tool_output
    }],
    tools=tools
)

print(response2.output_text)

4.3 并行工具调用

两家都支持一次调用多个工具并行执行，这是 agent 提效的关键：

python 复制代码 
# Claude：默认就支持并行，模型可能在一个 response 里返回多个 tool_use block
# 在 agent_loop 里你看到的 `for block in resp.content` 已经能处理多个

# OpenAI：默认 parallel_tool_calls=True
response = client.responses.create(
    model="gpt-5.5",
    input="同时查询设备 A、B、C 的状态",
    tools=tools,
    parallel_tool_calls=True  # 默认 True
)

4.4 实战建议

我自己在 ROV 控制软件里跑 agent 的几个经验：

  1. 工具描述要写"使用场景" ，不要只写"做什么"。比如 "当用户询问任何 DVL 数据时调用" 比 "查询 DVL" 准确率高得多。
  2. 必须给模型一个 STOP 工具 （比如 task_complete），否则在简单任务上它会一直"想多步"。
  3. 设置 max_iters：永远不要相信模型不会无限循环。
  4. 失败重试要带 backoff：API 偶尔 529 / 503，要带指数退避。

五、长上下文 + 文件 + 图像处理

5.1 1M 上下文：什么时候真的需要？

模型 上下文窗口 备注
Claude Sonnet 4.6 / Opus 4.7 1M（beta header 启用） 默认 200K，需要时再开
Claude Haiku 4.5 200K
GPT-5.5 1M 超过 272K 后输入按 2x、输出按 1.5x 计费

启用 Claude 的 1M 上下文（需要 beta header）：

python 复制代码 
client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    messages=[{"role": "user", "content": large_codebase}],
    extra_headers={"anthropic-beta": "context-1m-2025-08-07"}
)

💡 真实经验：1M 上下文≠1M 上下文都好用。两家在前 300K 范围内的"召回精度"都很高，超过 500K 后开始出现"中段遗忘"。关键信息放在 prompt 的开头或结尾是黄金法则。

5.2 图像输入

Claude 支持 base64 / URL 两种方式：

python 复制代码 
import anthropic, base64, httpx

client = anthropic.Anthropic()

# 方法1：URL
message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {"type": "url", "url": "https://example.com/circuit.png"}
            },
            {"type": "text", "text": "这块电路板上的主控芯片型号是什么？"}
        ]
    }]
)

# 方法2：base64 本地图片
with open("rov_status.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {"type": "base64", "media_type": "image/png", "data": image_data}
            },
            {"type": "text", "text": "从这张 ROV 状态截图，判断哪些传感器是异常的？"}
        ]
    }]
)
print(message.content[0].text)

🔥 Opus 4.7 视觉升级 ：图像分辨率上限从 2 MP 提升到 3.75 MP ，在 XBOW 的视觉精度 benchmark 上从 54.5% 跃升到 98.5%。screenshot-to-code、PDF 表格识别这类任务变得非常稳定。

GPT 用图像输入：

python 复制代码 
response = client.responses.create(
    model="gpt-5.5",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "这张 ROV 状态截图有什么异常？"},
            {"type": "input_image", "image_url": "https://example.com/status.png"}
        ]
    }]
)
print(response.output_text)

5.3 PDF / 文件处理

Claude 直接支持 PDF 输入：

python 复制代码 
import base64

with open("Nucleus1000_Manual.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                }
            },
            {"type": "text", "text": "总结这份手册里关于 lever arm 补偿的所有要点。"}
        ]
    }]
)
print(message.content[0].text)

OpenAI 走 Files API（先上传再引用）：

python 复制代码 
# 1. 上传文件
file = client.files.create(
    file=open("Nucleus1000_Manual.pdf", "rb"),
    purpose="user_data"
)

# 2. 在 input 里引用
response = client.responses.create(
    model="gpt-5.5",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "总结 lever arm 补偿的所有要点"},
            {"type": "input_file", "file_id": file.id}
        ]
    }]
)
print(response.output_text)

六、成本优化

这一节是真金白银------用得好，月账单能砍掉 70%+。

6.1 模型路由（最简单也最有效）

python 复制代码 
# 把请求按复杂度分到不同模型
def smart_route(prompt: str, task_type: str) -> str:
    if task_type == "classification" or len(prompt) < 200:
        return "claude-haiku-4-5-20251001"  # $0.25/$1.25
    elif task_type == "code_review" or task_type == "complex_reasoning":
        return "claude-opus-4-7"             # $5/$25
    else:
        return "claude-sonnet-4-6"           # $3/$15

我自己一个对 ROV 日志做异常检测的脚本，从全 Opus 改成 Haiku 分类 + Sonnet 分析 + Opus 兜底，月成本从 480 降到 63。

6.2 Prompt Caching（缓存）

核心机制 ：把"重复且巨大"的 prefix（系统提示、工具定义、长文档）标记缓存，之后命中缓存的部分只按 10% 输入价计费。

Claude 缓存示例
python 复制代码 
LONG_SYSTEM_PROMPT = """你是一位资深的水下机器人嵌入式工程师，专精 Qt C++ 开发。
你需要严格遵守以下规范：
... (这里有 5000 字的规范文档，包括 DVL 协议、ROV 控制接口等)
"""

LONG_DOC = open("dvl_full_spec.md").read()  # 假设 30000 tokens

def ask_with_cache(question: str):
    return client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": LONG_SYSTEM_PROMPT,
                "cache_control": {"type": "ephemeral"}   # 标记缓存点
            },
            {
                "type": "text",
                "text": LONG_DOC,
                "cache_control": {"type": "ephemeral"}   # 第二个缓存点
            }
        ],
        messages=[{"role": "user", "content": question}]
    )

# 第一次：写入缓存（写入价 = 输入价 × 1.25）
resp1 = ask_with_cache("DVL 的 PD0 协议帧头是什么？")
print(f"缓存写入 tokens: {resp1.usage.cache_creation_input_tokens}")
print(f"缓存读取 tokens: {resp1.usage.cache_read_input_tokens}")

# 第二次：命中缓存（缓存读 = 输入价 × 0.1）
resp2 = ask_with_cache("PD6 和 PD0 有什么主要区别？")
print(f"缓存读取 tokens: {resp2.usage.cache_read_input_tokens}")
# 应该看到大部分 token 都走了 cache_read
Claude 缓存的"坑"
  1. 5 分钟 TTL（默认） ：2026 年初 Anthropic 把默认 TTL 从 60 分钟改成了 5 分钟。批量任务前预热很重要。
  2. 1 小时 TTL（付费）：写入价 ×2，但保活 12 倍。重型 agent 适合用。
  3. 每次命中都会重置 TTL，所以稳定流量场景下缓存能"长期常驻"。
  4. 最小缓存块：Sonnet 4.6/Opus 4.7 要求 1024 tokens 起，Haiku 4.5 要 2048 起。
  5. 缓存内容必须是 prefix------你只要改 prefix 里任何一个字符，缓存就失效。

预热写法：

python 复制代码 
# 批量任务开始前，发一个 max_tokens=0 的请求"预热"缓存
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1,   # 注：max_tokens=0 在某些 SDK 版本里会被拒，可以用 1
    system=[{"type": "text", "text": LONG_SYSTEM_PROMPT,
             "cache_control": {"type": "ephemeral"}}],
    messages=[{"role": "user", "content": "ok"}]
)
# 之后 5 分钟内的请求都能命中缓存
GPT 的 Prompt Caching

OpenAI 在 GPT-5 系列里默认开启自动 prompt caching------你不用做任何事，系统会自动识别并缓存相同前缀。但有几点要注意：

  • GPT-5.5 只支持 "extended prompt caching"，需要在 prompt 里包含一个稳定的 prefix
  • 缓存命中价格也是 原价 × 10%
  • 没有显式的"打缓存标记"操作，靠服务端自动识别
python 复制代码 
# GPT 自动缓存------只要前缀稳定就行
response = client.responses.create(
    model="gpt-5.5",
    instructions=LONG_SYSTEM_PROMPT,   # 这部分会被自动缓存
    input=question
)

# 看是否命中
print(response.usage.input_tokens_details.cached_tokens)

6.3 Batch API（异步批处理）

如果你能接受最多 24 小时延迟 ，批处理能省 50%。

Claude Batch
python 复制代码 
from anthropic.types.messages.batch_create_params import Request

requests = [
    Request(
        custom_id=f"task-{i}",
        params={
            "model": "claude-sonnet-4-6",
            "max_tokens": 1024,
            "messages": [{"role": "user", "content": prompt}]
        }
    )
    for i, prompt in enumerate(prompts)   # prompts 是个长 list
]

batch = client.messages.batches.create(requests=requests)
print(f"Batch ID: {batch.id}")
print(f"Status: {batch.processing_status}")

# 轮询直到完成
import time
while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    time.sleep(30)

# 取结果
for result in client.messages.batches.results(batch.id):
    print(f"{result.custom_id}: {result.result}")

一次 batch 可以塞最多 100,000 个请求。

OpenAI Batch
python 复制代码 
# 1. 准备 JSONL 文件
with open("batch_input.jsonl", "w") as f:
    for i, prompt in enumerate(prompts):
        line = {
            "custom_id": f"task-{i}",
            "method": "POST",
            "url": "/v1/responses",
            "body": {
                "model": "gpt-5.5",
                "input": prompt
            }
        }
        f.write(json.dumps(line) + "\n")

# 2. 上传文件
batch_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch"
)

# 3. 创建 batch
batch = client.batches.create(
    input_file_id=batch_file.id,
    endpoint="/v1/responses",
    completion_window="24h"
)

# 4. 轮询 + 取结果
batch = client.batches.retrieve(batch.id)
output = client.files.content(batch.output_file_id)

6.4 成本对比速算表（2026 年 5 月）

模型 输入 ($/1M) 输出 ($/1M) 缓存读 Batch（50% off）
Claude Opus 4.7 $5 $25 $0.50 2.50/12.50
Claude Sonnet 4.6 $3 $15 $0.30 1.50/7.50
Claude Haiku 4.5 $0.25 $1.25 $0.025 0.125/0.625
GPT-5.5 $5 $30 $0.50 2.50/15
GPT-5.5 Pro $30 $180 不支持 15/90
GPT-5.4 $2.50 $15 $0.25 1.25/7.50

💡 典型省钱组合 ：长上下文 + 高频调用场景，用 Sonnet 4.6 + 缓存 + Batch ，能把 Opus 直调的成本压到 1/30。

七、Claude Code / Codex CLI 实战

光会 API 调用还不够。真正在日常开发里"省力"的是把 AI 装进终端，让它直接在你的项目里干活。

7.1 Claude Code 安装

bash 复制代码 
# 前置：Node.js 20+ 必装
node -v   # 确认是 v20 或更新

# 国内用 npm 镜像加速
npm config set registry https://registry.npmmirror.com

# 全局安装
npm install -g @anthropic-ai/claude-code

# 验证
claude --version

第一次启动：

bash 复制代码 
cd ~/my-rov-project
claude
# 按提示登录（OAuth 浏览器跳转）或填 API Key

7.2 Claude Code 的核心文件

文件 作用
CLAUDE.md 项目说明书。Claude 每次启动都会读，里面写"这是什么项目、代码规范、常用命令"
.claude/settings.json 工具权限、自动更新、模型选择等
.mcp.json 项目级 MCP 服务器配置
~/.claude/ 全局配置、历史会话

一份典型的 CLAUDE.md：

markdown 复制代码 
# ROV 控制软件

这是 DEEPINFAR 内部的 ROV 控制软件，基于 Qt 6.5 + C++17 开发。

## 项目结构
- `src/core/` - 核心通讯协议（DVL、USBL、INS）
- `src/ui/` - Qt 界面
- `src/sensors/` - 传感器驱动

## 编译
```bash
cmake -B build && cmake --build build -j8

代码规范

  • 文件用 UTF-8 BOM
  • 缩进 4 空格
  • 类名 PascalCase，函数 camelCase
  • 不要直接捕获 std::exception 基类，要写明具体类型

测试

bash 复制代码 
ctest --test-dir build --output-on-failure
复制代码 
### 7.3 Claude Code 国内"曲线救国"方案

如果你没法直接访问 Anthropic，可以把 Claude Code 接到第三方网关或国内模型上（**官方不推荐，但能用**）：

```bash
# 接 DeepSeek（Anthropic 兼容协议）
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<你的 DeepSeek API Key>
export ANTHROPIC_MODEL=deepseek-v4-pro
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash

# 启动
claude

或者用 cc-switch 这种 GUI 工具一键切换不同后端，对应仓库：

https://github.com/farion1231/cc-switch

7.4 Claude Code 常用命令

命令 作用
/init 初始化项目，自动生成 CLAUDE.md
/plan 进入"先规划再执行"模式
/ultrareview 最高强度代码审查（Opus 4.7 新增）
/compact 压缩当前会话上下文
/model opus 切换到 Opus 模型
/clear 清空当前会话
/mcp 管理 MCP 服务器
@filename 把指定文件加入上下文
!command 在 bash 里跑命令

一个真实的工作流示例（重构 Qt 模块）：

复制代码 
你：@src/sensors/dvl_driver.cpp 这个驱动太乱了，先 /plan 一下重构方案

Claude：
  [读取文件]
  [生成重构计划，列出 5 个步骤]
  确认要执行吗？

你：执行步骤 1 和 2

Claude：
  [改 dvl_driver.h]
  [改 dvl_driver.cpp]
  [运行 cmake]
  [运行测试]
  完成，3 个测试通过。

你：/ultrareview

Claude：
  [深度审查，按架构/安全/性能/可维护性输出报告]

7.5 Codex CLI 安装与使用

bash 复制代码 
# 安装
npm install -g @openai/codex

# 验证
codex --version

# 启动（先 OAuth 登录或配置 OPENAI_API_KEY）
cd ~/my-project
codex

Codex CLI 的核心配置文件：

toml 复制代码 
# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "on-request"   # 工具执行前是否要求确认
sandbox_mode = "workspace-write"  # 沙箱权限

[mcp_servers.context7]
command = "npx"
args = ["context7-mcp"]
Codex CLI 几个独特能力
  1. Cloud Tasks：你可以"发任务"到云端 sandbox，让 Codex 在远端干完活，回来给你 PR。
  2. AGENTS.md：Codex 项目级配置文件（类似 CLAUDE.md），但语法更宽松，支持声明"工作流"。
  3. /fast 模式：1.5x token 速度，质量不变，适合迭代型修改。

7.6 Claude Code + Codex 双工具协同（强烈推荐）

2026 年最流行的"高产开发"模式：Claude Code 做主力 + Codex 做对抗性审查。

安装方式：

bash 复制代码 
# 在 Claude Code 内安装 Codex 插件
/plugin install codex-review

# 或手动加 MCP
claude mcp add codex -s user -- codex -m gpt-5.5 -c model_reasoning_effort="high"

之后可以这样用：

复制代码 
你：[让 Claude 写了一段身份认证代码]

你：/codex:adversarial-review

Codex：
  我作为对抗性审查者，发现以下设计问题：
  1. JWT 没有验证 exp 字段 ✗
  2. 刷新 token 流程存在 race condition ✗
  3. ...

这种跨厂商交叉验证能发现单一模型的盲点，是目前生产环境最稳的玩法之一。

7.7 实战工作流示例：一次完整的功能开发

复制代码 
1. 启动 → claude-mem 自动恢复上下文
2. /spec        → 生成需求文档（agent-skills 插件）
3. /plan        → 拆任务，生成 task_plan.md
4. /build       → 逐步实现，context7 自动注入文档
5. /review      → Claude 自审
6. /codex:adversarial-review → Codex 对抗性审查
7. /ship        → 生成上线报告
8. 会话结束     → 自动压缩存档

八、生产环境避坑清单

下面是我自己踩过的坑，按"惨烈程度"排序：

8.1 永远 pin 模型版本

python 复制代码 
# ❌ 不要这样
MODEL = os.getenv("MODEL", "claude-opus-4-7")

# ✅ 这样
# 在 prompt 旁边硬编码，因为 prompt 是为特定模型调的
def code_review(diff: str):
    return client.messages.create(
        model="claude-opus-4-7",   # 这个 prompt 是为 4.7 调的
        ...
    )

环境变量改了一行，可能就把你 Haiku 调试的 prompt 跑到 Opus 上，成本瞬间 ×25。

8.2 max_tokens 默认调小

python 复制代码 
# ❌ 不限制
max_tokens=128_000   # Opus 4.7 能这么大

# ✅ 按需开
max_tokens=512       # 默认值
# 只有真的需要长输出的路由才调大

8.3 永远要带超时和重试

python 复制代码 
import time
from anthropic import APIError, APIConnectionError, RateLimitError

def call_with_retry(messages, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1024,
                messages=messages,
                timeout=30.0   # SDK 自带，单位秒
            )
        except RateLimitError:
            time.sleep(2 ** attempt)   # 指数退避
        except (APIError, APIConnectionError) as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

8.4 别把 API Key 硬编码

python 复制代码 
# ❌
client = anthropic.Anthropic(api_key="sk-ant-api03-xxx")

# ✅
# 用环境变量、密钥管理服务（AWS Secrets Manager / 1Password CLI）
client = anthropic.Anthropic()   # 自动读 ANTHROPIC_API_KEY

8.5 工具调用的输入要"防御性校验"

模型偶尔会传错参数，特别是嵌套 schema：

python 复制代码 
def run_tool(name: str, input_dict: dict):
    if name == "send_thruster_command":
        # 永远要校验
        pwm = input_dict.get("pwm")
        if not isinstance(pwm, int) or not (1100 <= pwm <= 1900):
            return json.dumps({"error": "pwm 必须是 1100-1900 的整数"})
        # ...

把错误信息返回给模型，它一般会自动重试修正。这是 agent 鲁棒性的关键。

8.6 日志要完整

每次调用至少记录：

  • request_id（响应头里有，是出问题时找 Anthropic / OpenAI 报错的关键）
  • model
  • input_tokens / output_tokens / cache_read_input_tokens
  • 耗时
  • stop_reason
python 复制代码 
import logging

def log_response(resp):
    logging.info(
        "model=%s in=%d out=%d cache_read=%d stop=%s",
        resp.model,
        resp.usage.input_tokens,
        resp.usage.output_tokens,
        getattr(resp.usage, "cache_read_input_tokens", 0),
        resp.stop_reason
    )

8.7 流式响应的"半截输出"处理

流式响应中途断开是常事，要能续：

python 复制代码 
collected = ""
try:
    with client.messages.stream(...) as stream:
        for text in stream.text_stream:
            collected += text
            print(text, end="", flush=True)
except Exception as e:
    print(f"\n[流断了，已收集 {len(collected)} 字符]")
    # 把 collected 作为部分输出保存

九、写在最后

API 这件事，真正的难度不是写代码------SDK 都已经做得很好用。难的是：

  1. prompt 工程------同样的 API，不同的 prompt 能差 10 倍质量
  2. 成本控制------缓存、Batch、路由不会用，月账单分分钟翻倍
  3. 错误处理------生产环境 99% 的 bug 都在边界情况和 retry 上
  4. 持续跟进------两家模型迭代极快，4.7 移除采样参数、5.5 改默认 effort，这种 breaking change 经常出

把这篇手册当作起点，配合官方文档：

我自己的习惯是：每两周扫一次两家的 changelog，新出的 beta header / 新参数能不能用得上，往往就是工程效率的下一个台阶。

相关推荐
卷Java5 小时前
2026年4月AI军备竞赛全景：DeepSeek V4 vs GPT-5.5 vs Gemini vs Claude
人工智能·gpt·大模型
Ai马猴子11 小时前
迭代升级再塑旗舰标杆，gpt-5.2入驻 DMXAPI，综合智能表现越级强悍
gpt
dhashdoia13 小时前
2026年GPT-5.5与GPT-Image-2深度解析：国内部署指南
人工智能·python·gpt·ai作画·gpt国内部署
玖日大大14 小时前
GPT-5.5 幻觉率砍半 52.5%、长文本理解翻倍、推理速度 3x 提升 — OpenAI 从「参数内卷」到「可靠性内卷」的实用主义转向
人工智能·gpt·openai·ai可靠性·gpt-5.5·幻觉治理·大模型商业化
AI360labs_atyun14 小时前
ChatGPT更新免费版GPT-5.5 Instant
人工智能·科技·gpt·ai·chatgpt·agi
m0_5358175515 小时前
告别海外账号！Claude Code Windows完整部署指南：从Node.js到api对接（附避坑）
windows·gpt·node.js·api·claude·claudecode·88api
LLM精进之路16 小时前
IEEE 26 | 参数量不是关键：4B模型VeriGround在匿名化电路生成任务上性能超越GPT-5.4
人工智能·gpt·深度学习·机器学习
wa的一声哭了16 小时前
Mit6.s081 Interrupts and device driver（中断和设备驱动）
linux·服务器·arm开发·数据库·python·gpt·算法
Ai马猴子17 小时前
企业定制专属模型，gpt-5.4-cdx高效适配，DMXAPI 安全合规
java·gpt·安全
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03CC-Switch & Claude 基于 Linux 服务器安装使用指南04【AI】2026 年具身智能模型和世界模型总结05零基础教你claude code 接入 deepseek V406AI科技热点日报 | 2026年5月11日07codex app每次打开重连5次Reconnecting问题解决08人工智能最新动态 AI 日报 · 2026年5月10日09Cursor 接入 DeepSeek‑V4‑Pro 完整指南（2026 实测）10Gemini大升级、AI眼镜首发、Android XR亮相，13天后见分晓