Prefill 废弃迁移 + Effort 参数：Claude 4.x 升级的两大必知变化

第十四章：OpenAI 兼容端点：迁移指南与差异处理

14.1 为什么需要 OpenAI 兼容端点

Anthropic 提供了一个与 OpenAI Chat Completions API 高度兼容的端点，允许开发者使用为 OpenAI 设计的客户端库（openai Python 库、LangChain、LiteLLM 等）直接调用 Claude 模型，只需修改 base_url 和 API Key。

这一设计的主要价值：

1. 零代码迁移：现有 OpenAI 项目只需改两行配置即可接入 Claude
2. 生态系统兼容：使用依赖 OpenAI SDK 的第三方工具（如 LangChain、各种 Agent 框架）
3. A/B 测试：在同一代码库中轻松切换不同提供商的模型
4. 统一接口层：当上层使用 LiteLLM 等路由工具时，Claude 作为其中一个后端选项

重要提示：OpenAI 兼容端点是一个"最大公约数"接口，它不支持 Claude 专有的特性（如 Extended Thinking、Prompt Caching 控制、工具 betas 参数）。若需使用这些能力，必须使用原生 Anthropic SDK。

14.2 基础配置

使用 OpenAI Python 库调用 Claude

import openai

# 只需修改 base_url 和 api_key
client = openai.OpenAI(
    base_url="https://api.anthropic.com/v1/",
    api_key="your-anthropic-api-key"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",  # 使用 Claude 模型名
    max_tokens=1024,
    messages=[
        {"role": "system", "content": "你是一个专业的技术顾问。"},
        {"role": "user", "content": "解释什么是微服务架构"}
    ]
)

print(response.choices[0].message.content)

流式输出

# 流式调用与 OpenAI 完全一致的接口
stream = client.chat.completions.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    stream=True,
    messages=[
        {"role": "user", "content": "写一首关于代码的诗"}
    ]
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

环境变量配置

import os
import openai

# 方式一：直接在代码中配置
client = openai.OpenAI(
    base_url="https://api.anthropic.com/v1/",
    api_key=os.environ["ANTHROPIC_API_KEY"]
)

# 方式二：通过环境变量（需要设置 OPENAI_BASE_URL 和 OPENAI_API_KEY）
# export OPENAI_BASE_URL=https://api.anthropic.com/v1/
# export OPENAI_API_KEY=your-anthropic-api-key
# 然后直接使用默认客户端：
# client = openai.OpenAI()

14.3 模型名称映射

使用兼容端点时，模型名称使用 Anthropic 的模型 ID，而非 OpenAI 的模型名：

# 模型路由示例：根据任务复杂度选择模型
def create_completion(task_complexity: str, messages: list) -> str:
    model_map = {
        "simple": "claude-haiku-4-5-20251001",    # 简单任务
        "standard": "claude-sonnet-4-6",           # 标准任务
        "complex": "claude-opus-4-6"               # 复杂推理
    }
    
    model = model_map.get(task_complexity, "claude-sonnet-4-6")
    
    response = client.chat.completions.create(
        model=model,
        max_tokens=1024,
        messages=messages
    )
    
    return response.choices[0].message.content

14.4 工具调用（Function Calling）兼容

Claude 通过兼容端点也支持工具调用，接口与 OpenAI 的 Function Calling 相同：

import json
import openai

client = openai.OpenAI(
    base_url="https://api.anthropic.com/v1/",
    api_key="your-anthropic-api-key"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_stock_price",
            "description": "获取指定股票的当前价格",
            "parameters": {
                "type": "object",
                "properties": {
                    "symbol": {
                        "type": "string",
                        "description": "股票代码，如 AAPL、GOOGL"
                    },
                    "currency": {
                        "type": "string",
                        "enum": ["USD", "CNY"],
                        "description": "价格货币"
                    }
                },
                "required": ["symbol"]
            }
        }
    }
]

def run_tool_call_loop(user_message: str) -> str:
    """运行完整的工具调用循环"""
    
    messages = [{"role": "user", "content": user_message}]
    
    while True:
        response = client.chat.completions.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            tools=tools,
            messages=messages
        )
        
        choice = response.choices[0]
        
        if choice.finish_reason == "stop":
            return choice.message.content
        
        elif choice.finish_reason == "tool_calls":
            # 将助手消息（含工具调用）添加到历史
            messages.append({
                "role": "assistant",
                "content": choice.message.content,
                "tool_calls": [
                    {
                        "id": tc.id,
                        "type": "function",
                        "function": {
                            "name": tc.function.name,
                            "arguments": tc.function.arguments
                        }
                    }
                    for tc in choice.message.tool_calls
                ]
            })
            
            # 执行工具并收集结果
            for tool_call in choice.message.tool_calls:
                func_name = tool_call.function.name
                func_args = json.loads(tool_call.function.arguments)
                
                # 模拟工具执行
                if func_name == "get_stock_price":
                    result = {"symbol": func_args["symbol"], "price": 150.23, "currency": "USD"}
                else:
                    result = {"error": "Unknown function"}
                
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": json.dumps(result)
                })
        else:
            break
    
    return "无法获取回复"

# 测试
print(run_tool_call_loop("苹果公司股价是多少？"))

14.5 LangChain 集成

from langchain_openai import ChatOpenAI
from langchain.schema import HumanMessage, SystemMessage

# LangChain 通过 OpenAI 兼容接口使用 Claude
llm = ChatOpenAI(
    model="claude-sonnet-4-6",
    openai_api_key="your-anthropic-api-key",
    openai_api_base="https://api.anthropic.com/v1/",
    max_tokens=1024
)

# 基础调用
messages = [
    SystemMessage(content="你是一个专业的代码审查员。"),
    HumanMessage(content="审查以下 Python 代码的潜在问题：\n\ndef divide(a, b):\n    return a / b")
]

response = llm.invoke(messages)
print(response.content)

# 在 LangChain Chain 中使用
from langchain.prompts import ChatPromptTemplate
from langchain.chains import LLMChain

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是{role}，用简洁的语言回答问题。"),
    ("human", "{question}")
])

chain = LLMChain(llm=llm, prompt=prompt)
result = chain.run(role="Python 专家", question="什么是装饰器？")
print(result)

LangChain LCEL（新式链）

from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.schema.output_parser import StrOutputParser

llm = ChatOpenAI(
    model="claude-haiku-4-5-20251001",
    openai_api_key="your-anthropic-api-key",
    openai_api_base="https://api.anthropic.com/v1/"
)

prompt = ChatPromptTemplate.from_template("用一句话解释：{concept}")
chain = prompt | llm | StrOutputParser()

# 批量处理
concepts = ["量子计算", "区块链", "联邦学习"]
results = chain.batch([{"concept": c} for c in concepts])
for concept, result in zip(concepts, results):
    print(f"{concept}: {result}")

14.6 LiteLLM 统一路由

LiteLLM 是一个多 LLM 提供商路由库，可以统一 OpenAI、Claude、Gemini 等的调用接口：

import litellm

# 方式一：前缀路由到 Claude
response = litellm.completion(
    model="anthropic/claude-sonnet-4-6",  # 使用 anthropic/ 前缀
    messages=[{"role": "user", "content": "你好！"}]
)
print(response.choices[0].message.content)

# 方式二：使用 OpenAI 兼容端点
response = litellm.completion(
    model="openai/claude-sonnet-4-6",
    api_base="https://api.anthropic.com/v1/",
    api_key="your-anthropic-api-key",
    messages=[{"role": "user", "content": "你好！"}]
)

# 方式三：模型负载均衡（混合使用多个模型）
litellm.set_verbose = False

responses = litellm.batch_completion(
    models=["anthropic/claude-haiku-4-5-20251001", "gpt-4o-mini"],
    messages=[{"role": "user", "content": "简单回答：2+2=？"}]
)

for model, resp in zip(["claude", "gpt4o-mini"], responses):
    print(f"{model}: {resp.choices[0].message.content}")

使用 LiteLLM 进行成本路由

import litellm
from litellm import Router

# 配置路由规则
router = Router(
    model_list=[
        {
            "model_name": "claude-fast",
            "litellm_params": {
                "model": "anthropic/claude-haiku-4-5-20251001",
                "api_key": "your-anthropic-api-key"
            }
        },
        {
            "model_name": "claude-smart",
            "litellm_params": {
                "model": "anthropic/claude-sonnet-4-6",
                "api_key": "your-anthropic-api-key"
            }
        },
        {
            "model_name": "claude-smart",  # 故障转移到 GPT
            "litellm_params": {
                "model": "gpt-4o-mini",
                "api_key": "your-openai-api-key"
            }
        }
    ],
    routing_strategy="latency-based-routing"
)

response = router.completion(
    model="claude-smart",
    messages=[{"role": "user", "content": "分析这段代码..."}]
)

14.7 关键差异与注意事项

参数映射差异

使用 OpenAI 接口调用 Claude 时，部分参数的行为有所不同：

# 注意：max_tokens 在 Claude 中是必填参数
# 而在 OpenAI 中是可选的

# 错误：缺少 max_tokens 会报错
try:
    response = client.chat.completions.create(
        model="claude-sonnet-4-6",
        messages=[{"role": "user", "content": "你好"}]
        # 缺少 max_tokens！
    )
except Exception as e:
    print(f"错误: {e}")  # max_tokens is required

# 正确
response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,  # 必须提供
    messages=[{"role": "user", "content": "你好"}]
)

System 消息处理差异

OpenAI API 中 system 消息可以出现在对话任何位置；Claude 兼容端点中，system 消息通常只处理第一个，且转换为 Claude 的 system 字段：

# OpenAI 支持多个 system 消息，Claude 只处理第一个
messages = [
    {"role": "system", "content": "你是 Python 专家。"},  # 这个会被使用
    {"role": "user", "content": "解释装饰器"},
    {"role": "system", "content": "改用简洁语言。"},  # 这个可能被忽略
]

# 建议：只使用一个 system 消息，放在最开始
messages_correct = [
    {"role": "system", "content": "你是 Python 专家，用简洁语言解释。"},
    {"role": "user", "content": "解释装饰器"}
]

无法通过兼容端点访问的 Claude 特性

以下 Claude 特性只能通过原生 Anthropic SDK 使用：

import anthropic

client = anthropic.Anthropic()

# 1. Extended Thinking（仅原生 SDK）
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},  # 不可通过 OpenAI 兼容端点使用
    messages=[{"role": "user", "content": "解一道复杂数学题"}]
)

# 2. Prompt Caching 控制（仅原生 SDK）
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "很长的系统提示...",
        "cache_control": {"type": "ephemeral"}  # 不可通过 OpenAI 兼容端点使用
    }],
    messages=[{"role": "user", "content": "问题"}]
)

# 3. 批处理 API（仅原生 SDK）
batch = client.messages.batches.create(requests=[...])  # 无兼容端点版本

# 4. 特定 betas 参数（如 PDF 支持）
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    betas=["pdfs-2024-09-25"],  # 不可通过 OpenAI 兼容端点使用
    messages=[...]
)

14.8 迁移实战：从 OpenAI 迁移到 Claude

评估迁移成本

# 检查代码中使用了哪些 OpenAI 特有功能
def assess_migration_complexity(codebase_path: str) -> dict:
    """扫描代码库，评估迁移到 Claude 的复杂度"""
    
    incompatible_features = {
        "logprobs": [],
        "n_greater_than_1": [],
        "frequency_penalty": [],
        "presence_penalty": [],
        "fine_tuned_model": [],
        "embeddings": [],    # Claude 暂无 embeddings API
        "moderation": [],    # Claude 无专用 moderation API
        "vision_url_openai": []  # OpenAI 特有的 URL 格式
    }
    
    # 实际实现中，扫描代码文件
    # 这里只是示意
    return incompatible_features

# 简单迁移：只需改两行
BEFORE = """
import openai
client = openai.OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-4o",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}]
)
"""

AFTER = """
import openai
client = openai.OpenAI(
    base_url="https://api.anthropic.com/v1/",
    api_key="your-anthropic-api-key"
)
response = client.chat.completions.create(
    model="claude-sonnet-4-6",  # 仅改模型名
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}]
)
"""

渐进式迁移策略

import os
import openai

def create_client(provider: str = "auto") -> openai.OpenAI:
    """
    创建统一接口客户端，支持在 OpenAI 和 Claude 之间切换
    """
    if provider == "auto":
        provider = os.environ.get("LLM_PROVIDER", "anthropic")
    
    if provider == "anthropic":
        return openai.OpenAI(
            base_url="https://api.anthropic.com/v1/",
            api_key=os.environ["ANTHROPIC_API_KEY"]
        )
    elif provider == "openai":
        return openai.OpenAI(
            api_key=os.environ["OPENAI_API_KEY"]
        )
    else:
        raise ValueError(f"未知提供商: {provider}")

def get_model_name(provider: str, tier: str = "standard") -> str:
    """获取各提供商的对应模型"""
    models = {
        "anthropic": {
            "fast": "claude-haiku-4-5-20251001",
            "standard": "claude-sonnet-4-6",
            "powerful": "claude-opus-4-6"
        },
        "openai": {
            "fast": "gpt-4o-mini",
            "standard": "gpt-4o",
            "powerful": "o1"
        }
    }
    return models[provider][tier]

# 使用统一接口
provider = os.environ.get("LLM_PROVIDER", "anthropic")
client = create_client(provider)
model = get_model_name(provider, "standard")

response = client.chat.completions.create(
    model=model,
    max_tokens=1024,
    messages=[{"role": "user", "content": "解释什么是 RAG？"}]
)
print(response.choices[0].message.content)

14.9 调试与故障排查

常见错误及解决方案

import openai
import anthropic

def debug_compatibility_request(messages: list, **kwargs) -> dict:
    """诊断兼容端点请求问题"""
    
    client = openai.OpenAI(
        base_url="https://api.anthropic.com/v1/",
        api_key="your-anthropic-api-key"
    )
    
    # 检查常见问题
    issues = []
    
    # 1. max_tokens 缺失
    if "max_tokens" not in kwargs:
        issues.append("⚠️  max_tokens 未设置（Claude 必填）")
        kwargs["max_tokens"] = 1024  # 自动补充默认值
    
    # 2. 检查不支持的参数
    unsupported = ["n", "logprobs", "top_logprobs"]
    for param in unsupported:
        if param in kwargs and kwargs[param] not in (None, 1):
            issues.append(f"⚠️  {param} 在 Claude 中不支持，将被忽略")
    
    # 3. 检查 temperature 范围
    if "temperature" in kwargs and kwargs["temperature"] > 1:
        issues.append(f"⚠️  temperature={kwargs['temperature']} 超出 Claude 建议范围 [0, 1]")
    
    for issue in issues:
        print(issue)
    
    try:
        response = client.chat.completions.create(
            messages=messages,
            **kwargs
        )
        return {"success": True, "response": response.choices[0].message.content}
    except openai.BadRequestError as e:
        return {"success": False, "error": str(e)}

响应格式差异

Claude 通过兼容端点返回的响应结构与 OpenAI 兼容，但有细微差别：

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=[{"role": "user", "content": "你好"}]
)

# 标准字段（与 OpenAI 兼容）
print(response.model)                           # "claude-sonnet-4-6"
print(response.choices[0].message.content)      # 回复内容
print(response.choices[0].finish_reason)        # "stop" 或 "tool_calls"
print(response.usage.prompt_tokens)             # 输入 tokens
print(response.usage.completion_tokens)         # 输出 tokens

# Claude 特有字段（可能在响应中出现）
# response.model 可能包含完整的模型版本号

小结

OpenAI 兼容端点大大降低了从 OpenAI 生态迁移到 Claude 的门槛：

1. 只需修改 base_url 和 api_key，现有 OpenAI 代码即可调用 Claude
2. 工具调用（Function Calling）、流式输出在兼容端点上完全支持
3. 必须设置 max_tokens，这是 Claude 与 OpenAI 接口最重要的强制差异
4. n、logprobs、presence_penalty、frequency_penalty 在 Claude 中不支持
5. Extended Thinking、Prompt Caching、PDF Beta 等高级特性需使用原生 Anthropic SDK
6. 推荐使用 LiteLLM 进行多提供商统一路由，支持动态切换和故障转移