OpenAI与Anthropic API实战：从基础调用到工具调用完整指南

最近在对接 OpenAI 和 Anthropic 的 API 时，不少开发者反馈遇到了各种网络连接、配置兼容和模型调用的问题，从基础的“无法连接到服务”到复杂的工具调用（Tool Calling）协议适配，每一步都可能踩坑。本文将系统梳理这两个主流大模型 API 的实战接入流程，涵盖从环境准备、密钥配置、基础调用到高级功能（如函数调用）的完整代码示例，并针对高频错误提供详细的排查思路。无论你是想快速集成 ChatGPT 能力，还是需要将现有应用迁移到兼容 OpenAI 格式的国产模型，都能在这里找到可复用的解决方案。

1. 核心概念与生态现状

在开始写代码之前，有必要理清当前大模型 API 服务的基本格局和关键术语，这能帮助我们更好地理解后续的配置和排错。

1.1 OpenAI 与 Anthropic：协议与定位

OpenAI 的 ChatGPT API（通常指gpt-3.5-turbo,gpt-4等模型）已成为事实上的行业标准。其 API 采用基于 HTTP 的 RESTful 接口，请求和响应格式（特别是 Chat Completions 格式）清晰、文档完善，因此被众多后续的模型服务提供商所兼容。

Anthropic 的 Claude 系列模型（如claude-3-opus-20240229）是另一个重要的竞争者。其 API 协议在设计上与 OpenAI 有相似之处，但并非完全兼容。两者在请求体字段、身份验证方式（如x-api-key头）、以及一些高级功能（如流式响应、工具调用）的实现细节上存在差异。这意味着直接使用为 OpenAI 编写的客户端库去调用 Claude API 很可能失败。

1.2 “OpenAI-Compatible” 生态

由于 OpenAI API 格式的广泛流行，一个庞大的“OpenAI-Compatible”生态已经形成。这包括：

1. 国产大模型平台：如阿里云百炼、百度文心、智谱AI、月之暗面（Kimi）等，许多都提供了兼容 OpenAI API 格式的接口。这意味着开发者可以使用openai这个官方 Python 库，通过修改base_url和api_key，来调用这些国产模型。
2. 本地部署模型：许多开源模型（如 Llama 系列、Qwen 系列）的推理框架（如 vLLM, Ollama, LM Studio）也提供了 OpenAI 兼容的 API 端点。
3. 代理与中转服务：一些服务商提供了将 Anthropic、Cohere 等非 OpenAI 协议转换为 OpenAI 协议的中转层，以简化开发。

核心价值：对于开发者而言，“OpenAI-Compatible” 的最大好处是代码无需大幅重写。一套基于openai库的代码，通过更换配置，就能灵活切换后端模型供应商，极大地降低了集成和迁移成本。

1.3 关键术语解析

• API Key: 访问模型的凭证，相当于密码。OpenAI 的 Key 通常以sk-开头，Anthropic 的以sk-ant-开头。务必妥善保管，不要在客户端代码中硬编码。
• Base URL: API 服务的端点地址。OpenAI 官方是https://api.openai.com/v1，兼容服务则需要替换为对应的地址，如https://dashscope.aliyuncs.com/compatible-mode/v1（阿里云百炼）。
• Model Name: 指定要使用的具体模型，如gpt-4o,claude-3-5-sonnet-20241022,qwen-max。
• Chat Completions: OpenAI 定义的一种对话补全接口格式，也是兼容性标准的核心。它使用messages数组来组织对话历史，每条消息包含role(system, user, assistant) 和content。
• Tool Calling / Function Calling: 模型根据对话内容，决定调用开发者预定义的工具（函数）的能力。这是构建智能 Agent 的关键。OpenAI 和 Anthropic 都支持此功能，但请求和响应的 JSON 结构有细微差别。

2. 环境准备与基础配置

我们将以 Python 环境为例，演示如何配置和调用 OpenAI 官方 API 及兼容 API。

2.1 Python 环境与依赖安装

确保你已安装 Python (推荐 3.8+)。然后使用 pip 安装必要的库。最核心的是openai库，用于调用 OpenAI 及兼容服务。为了演示对比和错误处理，我们也会安装anthropic库。

# 安装 OpenAI 官方库 (版本需 >= 1.0.0，新版本接口变化较大) pip install openai # 安装 Anthropic 官方库 pip install anthropic # 可选：安装用于处理环境变量的库 pip install python-dotenv

版本注意：OpenAI Python 库在 1.0.0 版本进行了重大更新，模块导入和客户端初始化方式与旧版 (openai<1.0.0) 完全不同。本文所有示例均基于新版 (openai>=1.0.0) 语法。如果你遇到AttributeError: module ‘openai’ has no attribute ‘ChatCompletion’错误，说明你正在使用旧版，请升级。

2.2 安全地管理 API 密钥

绝对不要将 API Key 直接写在源代码中并提交到版本控制系统（如 Git）。推荐使用环境变量管理。

方法一：使用.env文件（推荐用于开发）

1. 在项目根目录创建.env文件。
2. 在文件中添加你的密钥：

   # .env OPENAI_API_KEY=sk-your-openai-key-here ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here # 兼容服务示例 ALIYUN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 ALIYUN_API_KEY=sk-your-aliyun-key-here

3. 在 Python 代码中使用python-dotenv加载：

   # config.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY") ALIYUN_BASE_URL = os.getenv("ALIYUN_BASE_URL") ALIYUN_API_KEY = os.getenv("ALIYUN_API_KEY")

4. 确保将.env添加到.gitignore文件中，避免泄露。

方法二：系统环境变量（推荐用于生产/服务器）在部署应用的服务器上，通过命令行或配置管理工具设置环境变量。

# Linux/macOS export OPENAI_API_KEY='sk-your-key-here' # Windows (PowerShell) [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-key-here", "User")

然后在代码中通过os.getenv(“OPENAI_API_KEY”)读取。

3. 基础 API 调用实战

接下来，我们分别实现 OpenAI、Anthropic 和一个兼容服务（以阿里云百炼为例）的基础聊天调用。

3.1 调用 OpenAI 官方 API

# openai_demo.py import os from openai import OpenAI from config import OPENAI_API_KEY # 假设从上面的config.py导入 # 初始化客户端 client = OpenAI(api_key=OPENAI_API_KEY) # 默认base_url为 OpenAI 官方 def chat_with_openai(): try: response = client.chat.completions.create( model="gpt-3.5-turbo", # 指定模型 messages=[ {"role": "system", "content": "你是一个有帮助的助手。"}, {"role": "user", "content": "用Python写一个简单的Hello World程序。"} ], max_tokens=500, temperature=0.7, ) # 新版响应对象，通过属性访问 answer = response.choices[0].message.content print(f"OpenAI 回复: {answer}") return answer except Exception as e: print(f"调用 OpenAI API 时出错: {e}") return None if __name__ == "__main__": chat_with_openai()

3.2 调用 Anthropic Claude API

注意 Anthropic 的请求格式与 OpenAI 不同，需要使用其官方库。

# anthropic_demo.py import os import anthropic from config import ANTHROPIC_API_KEY # 初始化客户端 client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY) def chat_with_claude(): try: # Anthropic 使用 messages.create 方法，且 system 角色是单独参数 message = client.messages.create( model="claude-3-5-sonnet-20241022", max_tokens=500, temperature=0.7, system="你是一个有帮助的助手。", messages=[ {"role": "user", "content": "用Python写一个简单的Hello World程序。"} ] ) # 响应内容在 content 列表中 answer = message.content[0].text print(f"Claude 回复: {answer}") return answer except anthropic.APIConnectionError as e: print(f"网络连接失败: {e.__cause__}") except anthropic.APIStatusError as e: print(f"API 返回错误状态码: {e.status_code}") print(f"错误详情: {e.response.text}") except Exception as e: print(f"其他错误: {e}") return None if __name__ == "__main__": chat_with_claude()

3.3 调用兼容 OpenAI 格式的国产模型（阿里云百炼示例）

这是“OpenAI-Compatible”优势的体现：代码结构与调用 OpenAI 几乎一致，只需修改客户端配置。

# compatible_demo.py import os from openai import OpenAI from config import ALIYUN_API_KEY, ALIYUN_BASE_URL # 初始化客户端，指向兼容服务的端点 client = OpenAI( api_key=ALIYUN_API_KEY, base_url=ALIYUN_BASE_URL, # 关键：替换 base_url ) def chat_with_compatible(): try: # 注意：模型名称需要替换为兼容服务支持的模型，例如阿里的 qwen-max response = client.chat.completions.create( model="qwen-max", # 此处使用阿里云百炼的模型名 messages=[ {"role": "system", "content": "你是一个有帮助的助手。"}, {"role": "user", "content": "用Python写一个简单的Hello World程序。"} ], max_tokens=500, temperature=0.7, ) answer = response.choices[0].message.content print(f"兼容服务回复: {answer}") return answer except Exception as e: print(f"调用兼容服务 API 时出错: {e}") # 详细检查错误信息 if hasattr(e, ‘response‘): print(f"错误响应: {e.response.text}") return None if __name__ == "__main__": chat_with_compatible()

关键点：

1. base_url: 必须替换为目标兼容服务的端点。
2. model: 必须使用目标服务支持的模型名称列表中的名称，不能使用gpt-3.5-turbo。
3. API Key: 使用目标服务提供的 Key。

4. 高级功能：工具调用 (Tool Calling) 实战

工具调用允许大模型根据对话内容，决定调用开发者提供的函数。这是构建智能应用的核心。OpenAI 和 Anthropic 都支持，但格式有差异。

4.1 OpenAI 工具调用示例

首先，定义工具（函数）列表。然后，在对话中让模型决定是否以及如何调用它们。

# openai_toolcall.py import json from openai import OpenAI from config import OPENAI_API_KEY client = OpenAI(api_key=OPENAI_API_KEY) # 1. 定义工具（函数）的 schema tools = [ { "type": "function", "function": { "name": "get_current_weather", "description": "获取指定城市的当前天气", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "城市名称，例如：北京，上海", }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "温度单位", }, }, "required": ["location"], }, }, } ] # 2. 模拟的工具执行函数 def execute_tool(tool_call): """根据模型返回的工具调用信息，执行本地函数""" function_name = tool_call.function.name arguments = json.loads(tool_call.function.arguments) if function_name == "get_current_weather": location = arguments.get("location", "未知") unit = arguments.get("unit", "celsius") # 这里模拟返回天气数据，真实场景应调用外部API return f"{location}的天气是晴朗，温度25{unit}。" else: return f"未知工具: {function_name}" def chat_with_tools(): messages = [ {"role": "user", "content": "北京现在天气怎么样？"} ] # 3. 第一次调用，让模型决定是否使用工具 response = client.chat.completions.create( model="gpt-3.5-turbo", messages=messages, tools=tools, tool_choice="auto", # 让模型自动决定 ) response_message = response.choices[0].message tool_calls = response_message.tool_calls # 4. 将模型的响应（包含工具调用请求）添加到对话历史 messages.append(response_message) # 5. 如果模型要求调用工具，则执行并返回结果 if tool_calls: for tool_call in tool_calls: # 执行工具 tool_result = execute_tool(tool_call) # 将工具执行结果作为一条新消息追加 messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": tool_result, }) # 6. 第二次调用，将工具执行结果返回给模型，让它生成最终回答 second_response = client.chat.completions.create( model="gpt-3.5-turbo", messages=messages, ) final_answer = second_response.choices[0].message.content print(f"最终回答: {final_answer}") return final_answer else: # 模型没有调用工具，直接返回回答 print(f"直接回答: {response_message.content}") return response_message.content if __name__ == "__main__": chat_with_tools()

4.2 Claude (Anthropic) 工具调用示例

Anthropic 的工具调用（称为 Tool Use）概念类似，但 API 参数名称和结构不同。

# anthropic_toolcall.py import json import anthropic from config import ANTHROPIC_API_KEY client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY) # 1. 定义工具 schema (Anthropic 格式) tools = [ { "name": "get_current_weather", "description": "获取指定城市的当前天气", "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "城市名称", }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "温度单位", }, }, "required": ["location"], }, } ] def execute_tool_for_claude(tool_name, input_args): if tool_name == "get_current_weather": location = input_args.get("location", "未知") unit = input_args.get("unit", "celsius") return f"{location}的天气是晴朗，温度25{unit}。" return f"未知工具: {tool_name}" def chat_with_claude_tools(): message = client.messages.create( model="claude-3-5-sonnet-20241022", max_tokens=500, tools=tools, messages=[ {"role": "user", "content": "北京现在天气怎么样？"} ] ) # 2. 解析响应，检查是否有工具调用 final_text = "" tool_results = [] for content_block in message.content: if content_block.type == ‘text‘: final_text += content_block.text elif content_block.type == ‘tool_use‘: # 发现工具调用 tool_name = content_block.name tool_input = content_block.input # 执行工具 tool_result = execute_tool_for_claude(tool_name, tool_input) # 记录结果，用于后续发送 tool_results.append({ "tool_use_id": content_block.id, "tool_name": tool_name, "content": tool_result }) # 3. 如果有工具调用，需要将结果发送回 Claude 进行下一步 if tool_results: # 构建新的消息列表，包含用户问题、Claude的响应（含工具调用）、工具执行结果 next_messages = [ {"role": "user", "content": "北京现在天气怎么样？"} ] # 添加 Claude 的原始响应（包含 tool_use） next_messages.append(message) # 添加工具执行结果（格式为 tool_result） for result in tool_results: next_messages.append({ "role": "user", "content": [ { "type": "tool_result", "tool_use_id": result["tool_use_id"], "content": result["content"] } ] }) # 第二次调用，让 Claude 基于工具结果生成最终回答 second_message = client.messages.create( model="claude-3-5-sonnet-20241022", max_tokens=500, messages=next_messages, ) for block in second_message.content: if block.type == ‘text‘: final_text = block.text break print(f"Claude 最终回答: {final_text}") return final_text if __name__ == "__main__": chat_with_claude_tools()

对比与总结：

• OpenAI: 使用tools和tool_choice参数。模型响应中的工具调用信息在response.choices[0].message.tool_calls中。执行结果需以role: “tool“的消息传回。
• Anthropic: 使用tools参数。模型响应中的工具调用信息是content数组里type为tool_use的块。执行结果需以role: “user“,content类型为tool_result的消息传回。
• 核心流程一致：定义工具 -> 模型请求调用 -> 本地执行 -> 返回结果 -> 模型生成最终回答。

5. 高频错误与深度排查指南

在实际集成中，90%的问题集中在网络、认证和配置上。下面是一个详细的排查清单。

5.1 网络连接类错误

错误现象：APIConnectionError,ConnectionError,Timeout,Unable to connect to Anthropic services,Failed to connect to api.anthropic.com。

代码示例：为 OpenAI 客户端配置代理

import os from openai import OpenAI import httpx # 假设你有一个本地HTTP代理运行在 127.0.0.1:7890 proxy_url = "http://127.0.0.1:7890" http_client = httpx.Client(proxies=proxy_url) client = OpenAI( api_key=os.getenv("OPENAI_API_KEY"), http_client=http_client, # 注入自定义HTTP客户端 ) # 注意：生产环境代理配置应通过环境变量或更安全的方式管理。

5.2 认证与权限类错误

错误现象：AuthenticationError,Invalid API Key,403 Forbidden,401 Unauthorized。

5.3 请求格式与兼容性错误

错误现象：InvalidRequestError,Bad Request, 返回内容异常或为空。

5.4 资源与限额错误

错误现象：RateLimitError,QuotaExceededError,429 Too Many Requests。

6. 工程化最佳实践

将大模型 API 集成到生产项目时，需要考虑稳定性、可维护性和成本。

6.1 配置管理与环境隔离

• 使用配置中心：不要将base_url,api_key,model等硬编码。使用配置文件（如config.yaml）、环境变量或专业的配置中心（如 Apollo, Nacos）进行管理。
• 环境隔离：为开发、测试、预发布、生产环境配置不同的 API Key 和端点（如有）。生产环境使用付费 Key 和稳定端点，开发环境可以使用免费额度或测试端点。
• 密钥轮转：定期更新 API Key，并在服务中实现无缝切换，避免单点故障。

6.2 客户端封装与错误处理

封装一个统一的 LLM 客户端类，内部处理不同供应商的差异。

# llm_client.py import os import json from typing import Optional, List, Dict, Any from openai import OpenAI as OpenAIClient from anthropic import Anthropic as AnthropicClient import httpx from tenacity import retry, stop_after_attempt, wait_exponential class UnifiedLLMClient: def __init__(self, provider: str = “openai“, **kwargs): """ 初始化统一客户端。 :param provider: ‘openai‘, ‘anthropic‘, ‘aliyun‘ 等 :param kwargs: 可传递 api_key, base_url, http_client 等 """ self.provider = provider self.api_key = kwargs.get(‘api_key‘) or os.getenv(f“{provider.upper()}_API_KEY“) self.base_url = kwargs.get(‘base_url‘) self.model = kwargs.get(‘model‘) if provider == “openai“: self.client = OpenAIClient(api_key=self.api_key, base_url=self.base_url) elif provider == “anthropic“: self.client = AnthropicClient(api_key=self.api_key) elif provider == “aliyun“: # 阿里云百炼是 OpenAI 兼容格式 self.client = OpenAIClient(api_key=self.api_key, base_url=self.base_url) else: raise ValueError(f“不支持的提供商: {provider}“) @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) def chat_completion(self, messages: List[Dict[str, str]], **kwargs) -> Optional[str]: """统一的聊天补全接口，自动适配不同提供商""" try: if self.provider in [“openai“, “aliyun“]: # OpenAI 兼容格式 response = self.client.chat.completions.create( model=self.model or kwargs.get(‘model‘, ‘gpt-3.5-turbo‘), messages=messages, **{k: v for k, v in kwargs.items() if k not in [‘model‘]} ) return response.choices[0].message.content elif self.provider == “anthropic“: # Anthropic 格式 # 需要将 messages 中的 system 角色提取出来 system_prompt = ““ new_messages = [] for msg in messages: if msg[‘role‘] == ‘system‘: system_prompt += msg[‘content‘] + “\n“ else: new_messages.append(msg) response = self.client.messages.create( model=self.model or kwargs.get(‘model‘, ‘claude-3-5-sonnet-20241022‘), max_tokens=kwargs.get(‘max_tokens‘, 500), temperature=kwargs.get(‘temperature‘, 0.7), system=system_prompt if system_prompt else None, messages=new_messages, ) return response.content[0].text else: return None except Exception as e: # 这里可以记录日志、发送告警等 print(f“[{self.provider}] API调用失败: {e}“) # 根据错误类型决定是否重试（tenacity 已处理） raise # 重新抛出异常，让 tenacity 进行重试 # 使用示例 if __name__ == “__main__“: # 使用 OpenAI openai_client = UnifiedLLMClient(provider=“openai“, model=“gpt-3.5-turbo“) answer = openai_client.chat_completion([ {“role“: “user“, “content“: “你好“} ]) print(answer) # 使用阿里云百炼 aliyun_client = UnifiedLLMClient( provider=“aliyun“, base_url=“https://dashscope.aliyuncs.com/compatible-mode/v1“, model=“qwen-max“ ) answer2 = aliyun_client.chat_completion([ {“role“: “user“, “content“: “你好“} ]) print(answer2)

封装的好处：

1. 统一接口：业务代码只需调用chat_completion，无需关心底层是 OpenAI 还是 Claude。
2. 错误重试：使用tenacity库实现自动重试，提高稳定性。
3. 易于扩展：新增一个提供商时，只需修改这个类。
4. 集中配置：密钥、模型、端点等配置集中管理。

6.3 日志、监控与成本控制

• 详细日志：记录每次请求的模型、Tokens 消耗、耗时、是否成功。这对于调试和成本分析至关重要。
• 设置预算与告警：在云平台设置每月预算和用量告警，避免意外高额账单。
• Tokens 估算：在发送请求前，可以粗略估算输入 Tokens 数量（例如使用tiktoken库 for OpenAI），对于长文本进行必要截断，控制单次请求成本。
• 缓存策略：对于重复性或确定性较高的查询，可以考虑在应用层增加缓存，减少对 API 的调用。

6.4 安全注意事项

• 输入净化：对用户输入进行必要的检查和过滤，防止 Prompt 注入攻击，避免模型执行意外指令或泄露系统提示词。
• 输出审查：对模型的输出内容进行安全审查，特别是涉及用户生成内容（UGC）或对外展示的场景，防止生成有害、偏见或不实信息。
• 密钥权限：遵循最小权限原则，为不同应用创建不同的 API Key，并设置合理的用量限制。

通过以上从概念到实战，再到排错和工程化的系统梳理，你应该能够顺利地将 OpenAI、Anthropic 或其他兼容的大模型 API 集成到自己的项目中。核心在于理解协议差异、做好配置管理、实现健壮的错误处理，并遵循生产环境的最佳实践。