国内开发者必看：API中转站 / GAC / CC-Switch / Claude & Codex 访问完整指南
·
作者：尘一不染
更新日期：2026年5月
适用人群：需要接入国际大模型API的国内开发者、正在准备AI相关实习/项目的同学
前言
作为一名踏入AI开发领域的大二学生，我深知国内开发者在使用Claude、GPT、Codex等国际大模型时面临的困境：官方API直连困难、网络不稳定、支付门槛高……这些问题在我找实习做Agent开发时简直成了噩梦。
经过两个月的踩坑和研究，我终于整理出了一套完整的解决方案。本文将从原理到实践，手把手教你在国内优雅地接入各种大模型API。
声明：本文所有方案均为技术层面探讨，使用时请遵守各平台的服务条款。
目录
- API中转站原理与使用
- API-Key管理与GAC
- Claude国内使用方案
- CC-Switch深度解析
- Codex国内访问
- 多模型切换架构
- 实战代码示例
- 踩坑记录与最佳实践
1. API中转站原理与使用
1.1 什么是API中转站？
原理图解：
plaintext
┌─────────────────────────────────────────────────────────────────┐
│ 直接调用官方API │
│ ┌──────────┐ ╳ GFW ╳ ┌─────────────────────────┐ │
│ │ 你的代码 │ ──── ╳ ╳ ──── │ api.anthropic.com │ │
│ └──────────┘ ╳ ╳ │ api.openai.com │ │
│ ╳ ╳ │ api.cohere.com │ │
│ 国内开发者 ──┴────────┘ │ │
│ 超时/连接失败 │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 通过API中转站 │
│ ┌──────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ 你的代码 │ ── 稳定连接 ──▶│ 国内中转站 │──────▶│ 官方API │ │
│ └──────────┘ │ (香港/海外节点) │ └──────────┘ │
│ │ │ │
│ │ - 协议转换 │ │
│ │ - 负载均衡 │ │
│ │ - 费用结算 │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
技术定义：API中转站是一个智能代理层，它在用户和各种AI模型提供商之间架起桥梁，提供统一的标准接口。
1.2 为什么需要API中转站？
表格
| 痛点 | 解决方案 |
|---|---|
| 官方API直连超时、不稳定 | 中转站部署优化节点，延迟<200ms |
| 多模型需要管理多个Key | 统一入口，单Key调用所有模型 |
| 官方支付需要信用卡 | 支持支付宝/微信/人民币充值 |
| 模型切换需要改代码 | 统一接口，改个参数就行 |
| 官方限流严格 | 多渠道冗余，智能路由 |
1.3 主流中转站对比
根据2026年5月的综合评测，主流平台对比如下：
表格
| 平台 | 模型覆盖 | OpenAI兼容 | Anthropic原生 | 国内模型 | 协议完整度 |
|---|---|---|---|---|---|
| OpenRouter | 300+ | ✅ | ❌ | 部分 | 中 |
| 非线智能api | 480+ | ✅ | ✅ | ✅ | 高 |
| 147API | 200+ | ✅ | 部分 | ✅ | 高 |
| 硅基流动 | 100+ | ✅ | ❌ | ✅ | 中 |
| tuziapi | 750+ | ✅ | ✅ | ✅ | 高 |
我的推荐：
- 个人开发者/学习：OpenRouter（免费额度多，生态成熟）
- 生产环境/Claude深度用户：非线智能api（协议完整，版本更新快）
- 团队统一管理：147API（企业功能完善）
1.4 OpenRouter详解
OpenRouter是海外生态最成熟的模型聚合平台，特别适合开发者快速上手。
核心特性
markdown
✅ 300+ 模型覆盖：GPT-5、Claude 4.7、Gemini 2.5、Llama 4等
✅ 统一OpenAI兼容接口：改个base_url就能用
✅ 智能路由：自动选择最优模型/最低价格
✅ 免费额度：每日50次请求，多个免费模型
✅ Zero Completion Insurance：调用失败不扣费
注册与配置
bash
# 1. 访问 https://openrouter.ai 注册账号
# 2. 支持 Google/GitHub 快速登录
# 3. 在 API Keys 页面创建新密钥（sk-or-开头）
# 重要：首次使用需要配置隐私设置
# Settings > Privacy > 启用免费模型数据政策
Python调用示例
python
# 安装依赖
pip install openai
# 标准调用方式
from openai import OpenAI
client = OpenAI(
api_key="sk-or-v1-xxxxxxxxxxxxxxxx", # 你的OpenRouter密钥
base_url="https://openrouter.ai/api/v1" # 统一入口
)
# 调用GPT-4o
response = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "用Python实现快速排序"}]
)
print(response.choices[0].message.content)
# 切换到Claude，只需改model参数
response = client.chat.completions.create(
model="anthropic/claude-sonnet-4-20250514", # 注意格式：provider/model-name
messages=[{"role": "user", "content": "解释什么是闭包"}]
)
# 智能路由 - 让平台自动选最优模型
response = client.chat.completions.create(
model="openrouter/auto", # 自动路由
messages=[{"role": "user", "content": "帮我写一个Web服务器"}]
)
路由优化技巧
python
# OpenRouter支持多种路由快捷方式
# :nitro - 最快吞吐量的提供商
# :floor - 最低价格的提供商
# :online - 启用网络搜索
# 示例：使用最低价GPT-4o
response = client.chat.completions.create(
model="openai/gpt-4o:floor",
messages=[...]
)
# 示例：启用搜索增强
response = client.chat.completions.create(
model="openai/gpt-4o:online",
messages=[{"role": "user", "content": "今天有什么科技新闻？"}]
)
1.5 国内中转站：非线智能api
国内平台最大的优势是协议完整度高和人民币结算。
python
from openai import OpenAI
client = OpenAI(
api_key="sk-xxxxxxxxxxxxxxxx", # 国内平台密钥
base_url="https://api.nonelinear.com/v1" # 平台endpoint
)
# 调用Claude（OpenAI兼容格式）
response = client.chat.completions.create(
model="claude-opus-4.7",
messages=[{"role": "user", "content": "什么是RAG？"}]
)
# 如果平台支持Anthropic原生协议，也可以用官方SDK
from anthropic import Anthropic
anthropic_client = Anthropic(
api_key="sk-xxxxxxxxxxxxxxxx",
base_url="https://api.nonelinear.com/anthropic/v1" # 原生协议endpoint
)
response = anthropic_client.messages.create(
model="claude-opus-4.7",
max_tokens=1024,
messages=[{"role": "user", "content": "用Python写一个装饰器"}]
)
2. API-Key管理与GAC
2.1 什么是API-Key？
API-Key是调用大模型服务的"通行证"，类似于密码的作用。每个平台生成的Key格式不同
markdown
OpenAI: sk-proj-xxxxxxxxxxxxxxxx
Anthropic: sk-ant-api03-xxxxxxxxxxxxxxxx
OpenRouter: sk-or-v1-xxxxxxxxxxxxxxxx
国内平台: sk-xxxxxxxxxxxxxxxx
2.2 安全存储最佳实践
❌ 错误做法（血泪教训）
python
# 绝对禁止：把Key直接写在代码里
client = OpenAI(api_key="sk-xxxxxxxxxxxxxxxx") # 会泄露！
# 如果上传到GitHub，几分钟内就会被盗刷
✅ 正确做法一：环境变量
bash
# Linux/macOS 终端
export ANTHROPIC_API_KEY="sk-ant-xxx"
export OPENAI_API_KEY="sk-proj-xxx"
# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-xxx"
# 写入 ~/.bashrc 或 ~/.zshrc 永久生效
echo 'export ANTHROPIC_API_KEY="sk-ant-xxx"' >> ~/.bashrc
python
# Python代码中读取
import os
api_key = os.environ.get("ANTHROPIC_API_KEY")
if not api_key:
raise ValueError("请设置 ANTHROPIC_API_KEY 环境变量")
client = Anthropic(api_key=api_key)
✅ 正确做法二：python-dotenv
bash
# 安装
pip install python-dotenv
# 项目根目录创建 .env 文件
# 注意：.env 一定要加入 .gitignore！
env
# .env 文件内容
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-proj-xxx
OPENROUTER_API_KEY=sk-or-v1-xxx
python
# Python代码
from dotenv import load_dotenv
import os
# 加载 .env 文件
load_dotenv()
# 读取配置
api_key = os.getenv("ANTHROPIC_API_KEY")
git
# .gitignore 文件
.env
.env.local
.env.*.local
✅ 正确做法三：GAC（Git Auto Commit）
GAC是一个智能的Git提交助手，可以安全管理API密钥并自动生成提交信息。
bash
# 安装
uv tool install gac
# 初始化配置
gac init
# 基本使用
git add .
gac # 自动生成提交信息
# 常用命令
gac -y # 自动确认
gac -a -y -p # 暂存所有 + 自动确认 + 推送
gac -v # 详细格式
gac -o # 单行格式
env
# GAC配置文件 ~/.gac.env
GAC_MODEL=anthropic:claude-sonnet-4-20250514
OPENAI_API_KEY=sk-proj-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GAC的安全特性：
bash
# 自动扫描敏感信息
gac --secret-scan # 提交前检查API密钥
gac --skip-secret-scan # 禁用自动扫描（谨慎使用）
# SSL配置（企业代理环境）
GAC_NO_VERIFY_SSL=true # 跳过SSL验证
2.3 团队API-Key管理策略
markdown
## 团队Key管理最佳实践
1. **不要共享Key**
- 每人注册自己的账号
- 各自充值各自的额度
2. **使用统一网关**
- 搭建One-API或LiteLLM统一入口
- 管理员分配虚拟Key给团队成员
- 设置额度限制和用量监控
3. **环境隔离**
- 开发环境 / 测试环境 / 生产环境 分离
- 不同环境使用不同的Key
3. Claude国内使用方案
3.1 Claude官方API访问
Claude官方API支持多种接入方式：
python
# 方式一：官方Python SDK（推荐）
pip install anthropic
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ.get("ANTHROPIC_API_KEY"),
timeout=60.0 # 建议设置，防止长请求超时
)
# 基础调用
message = client.messages.create(
model="claude-sonnet-4-20250514", # 最新Sonnet
max_tokens=1024,
messages=[
{"role": "user", "content": "解释什么是异步编程"}
]
)
print(message.content[0].text)
# 带系统提示
message = client.messages.create(
model="claude-opus-4-20250514", # Opus更强
max_tokens=2048,
system="你是一个Python专家，用简洁清晰的语言解释概念",
messages=[
{"role": "user", "content": "什么是装饰器？"}
]
)
# 流式输出
with client.messages.stream(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[{"role": "user", "content": "讲个笑话"}]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True) # 必须flush=True！
python
# 方式二：原生HTTP请求
import requests
import os
API_URL = "https://api.anthropic.com/v1/messages"
API_KEY = os.environ.get("ANTHROPIC_API_KEY")
headers = {
"x-api-key": API_KEY,
"anthropic-version": "2023-06-01", # 必填
"Content-Type": "application/json"
}
data = {
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "什么是FastAPI？"}
]
}
response = requests.post(API_URL, headers=headers, json=data, timeout=60)
result = response.json()
print(result["content"][0]["text"])
3.2 Claude模型选择指南
表格
| 模型 | 模型ID | 特点 | 适用场景 |
|---|---|---|---|
| Claude Opus 4.7 | claude-opus-4-7 |
最强推理能力 | 复杂分析、代码审查 |
| Claude Sonnet 4.6 | claude-sonnet-4-6 |
均衡之选（推荐） | 日常开发、文档处理 |
| Claude Haiku 4.5 | claude-haiku-4-5-20251001 |
速度快、成本低 | 快速问答、批量处理 |
价格参考（以ClaudeAPI.com为例，2026年5月）：
markdown
| 模型 | 输入价格 | 输出价格 | 推荐场景 |
|------|----------|----------|----------|
| Opus 4.7 | $4.00/1M | $20.00/1M | 复杂推理 |
| Sonnet 4.6 | $2.40/1M | $12.00/1M | 日常开发 |
| Haiku 4.5 | $0.80/1M | $4.00/1M | 快速任务 |
3.3 错误处理与429限流
python
import time
from anthropic import Anthropic, RateLimitError, APIStatusError
client = Anthropic()
def call_with_retry(prompt, max_retries=5):
"""带指数退避的重试机制"""
for i in range(max_retries):
try:
return client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}]
)
except RateLimitError:
# 429限流：指数退避等待
wait = 2 ** i
print(f"触发限流，等待 {wait}s 后重试...")
time.sleep(wait)
except APIStatusError as e:
# 5xx错误：服务端问题，等待后重试
if e.status_code >= 500:
print(f"服务端错误 {e.status_code}，等待 5s 重试...")
time.sleep(5)
continue
raise
raise RuntimeError("重试次数用尽")
# 使用
result = call_with_retry("解释什么是RESTful API")
3.4 常见坑点
python
# 坑1：context too long - 不是只有输入超限
# 输出max_tokens + 输入tokens > 上下文窗口也会报错
# Claude Opus 4.7 上下文窗口200K，注意计算！
# 坑2：messages必须user开头
# ❌ 错误
messages = [{"role": "assistant", "content": "你好"}] # 报错！
# ✅ 正确：system单独传
response = client.messages.create(
model="claude-sonnet-4-6",
system="你是一个有帮助的助手", # system单独传
messages=[
{"role": "user", "content": "你好"}
]
)
# 坑3：tool_use后消息顺序
# 用工具调用时，assistant返回tool_use块后
# 下一条user消息必须包含对应tool_use_id的tool_result
4. CC-Switch深度解析
4.1 什么是CC-Switch？
CC-Switch 是专为 Claude Code 打造的多配置管理工具，让你在不同API配置间一键切换。
plaintext
核心功能：
├── 多Provider管理 - 同时配置官方Key、中转Key、多个渠道
├── 一键切换 - 一条命令切换所有配置
├── Web界面 - 可视化配置管理
├── 智能路由 - 自动选择可用渠道
└── Skills管理 - 一键安装GitHub热门Skills
4.2 安装配置
bash
# npm全局安装（推荐）
npm install -g @hobeeliu/cc-switch
cc-switch --version
# 或下载安装包
# GitHub: https://github.com/farion1231/cc-switch/releases
# 支持 Windows(mac)/macOS(dmg)/Linux(deb/rpm/AppImage)
4.3 ClaudeAPI.com国内直连配置
ClaudeAPI.com是国内直连Claude的优质方案，支持支付宝/微信充值。
bash
# Step 1: 获取API Key
# 访问 https://claudeapi.com 注册
# 控制台 > API Keys > 创建新密钥
# Step 2: 初始化配置
cc-switch init
# Step 3: 添加Provider（Web界面）
cc-switch web
# 自动打开浏览器，界面操作更直观
Web界面配置步骤：
plaintext
1. 点击右上角 "+" 添加供应商
2. 选择 "ClaudeAPI.com" 预设模板
3. 填写配置：
- 供应商名称：ClaudeAPI (可自定义)
- API Key: sk-ant-xxx (从后台复制)
- 请求地址: https://hk.claudeapi.com ⚠️ 不要以斜杠结尾
4. 模型映射：
- 主模型: claude-sonnet-4-6
- Opus模型: claude-opus-4-7
- Sonnet模型: claude-sonnet-4-6
- Haiku模型: claude-haiku-4-5-20251001
5. 勾选 "写入通用配置"
6. 保存并激活
4.4 命令行操作
bash
# 查看所有配置
cc-switch list
# 切换配置
cc-switch use claudeapi # 切换到ClaudeAPI
cc-switch use official # 切换到官方
cc-switch use deepseek # 切换到DeepSeek
# 测试连通性
cc-switch test
# 编辑配置
cc-switch edit default --field env.ANTHROPIC_AUTH_TOKEN
# 输入新Key，自动保存并验证
# 导出/备份配置
cc-switch export > backup.json
# 导入配置
cc-switch import backup.json
4.5 配合Claude Code使用
bash
# 安装Claude Code
npm install -g @anthropic-ai/claude-code
# 切换配置并启动Claude Code
cc-switch use claudeapi && claude
# 或直接运行（使用默认配置）
claude
# 验证Claude Code版本
claude --version
# 输出: 2.1.89 (Claude Code)
5. Codex国内访问
5.1 Codex是什么？
Codex是OpenAI推出的AI编程工具，有多种形态：
plaintext
Codex产品矩阵：
├── Claude Code (Anthropic) - CLI工具，编程助手
├── GitHub Copilot (Microsoft) - IDE插件
├── Cursor - AI代码编辑器
└── Codex CLI (@openai/codex) - OpenAI官方CLI
5.2 Codex CLI安装与配置
bash
# 安装Node.js 22+
# 检查版本
node --version
# 安装Codex CLI
npm install -g @openai/codex
codex --version
5.3 国内中转配置
由于网络限制，需要配置第三方API。
toml
# ~/.codex/config.toml
# 方式一：直接修改base_url
openai_base_url = "https://你的中转地址/v1"
model = "gpt-5.4-codex" # 或其他代码模型
# 方式二：自定义Provider（推荐）
model = "openai/gpt-4o"
model_provider = "myproxy"
[model_providers.myproxy]
name = "国内中转"
base_url = "https://api.中转站.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses" # 必须设为responses！
requires_openai_auth = false
json
// ~/.codex/auth.json
{
"OPENAI_API_KEY": "sk-你的中转站密钥"
}
bash
# 设置环境变量（推荐）
export OPENAI_API_KEY="sk-你的中转站密钥"
5.4 常用配置示例
toml
# 完整配置示例
# ~/.codex/config.toml
# 默认使用GPT-5.4进行代码任务
model = "openai/gpt-5.4-codex"
model_provider = "proxy"
# 推理投入设置
model_reasoning_effort = "high"
[model_providers.proxy]
name = "非线智能api"
base_url = "https://api.nonelinear.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
requires_openai_auth = false
# 重试配置
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000
6. 多模型切换架构
6.1 为什么要统一管理？
plaintext
痛点：
├── 每个模型SDK不同，代码耦合
├── 换模型要改代码，测试成本高
├── 无法灵活切换，成本难控
└── 单点故障，服务不稳定
解决方案：LiteLLM / One-API
6.2 LiteLLM：生产级网关
LiteLLM是一个开源的统一AI网关，支持100+模型。
bash
# 安装
pip install 'litellm[proxy]'
# 或Docker部署
docker run \
-v $(pwd)/litellm_config.yaml:/app/config.yaml \
-e OPENAI_API_KEY=your-key \
-e ANTHROPIC_API_KEY=your-key \
-p 4000:4000 \
ghcr.io/berriai/litellm:main
yaml
# litellm_config.yaml
model_list:
# OpenAI配置
- model_name: gpt-4o
litellm_params:
model: openai/gpt-4o
api_key: os.environ/OPENAI_API_KEY
# Claude配置（通过OpenRouter）
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-sonnet-4-20250514
api_key: os.environ/ANTHROPIC_API_KEY
# DeepSeek（国内模型，直接访问）
- model_name: deepseek-chat
litellm_params:
model: deepseek/deepseek-chat-v3-0324
api_key: os.environ/DEEPSEEK_API_KEY
api_base: https://api.deepseek.com
litellm_settings:
drop_params: true
set_verbose: true
python
# 统一调用 - 不管底层是什么模型
from litellm import completion
# 调用GPT-4o
response = completion(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}]
)
# 切换到Claude，只需改model
response = completion(
model="claude-sonnet",
messages=[{"role": "user", "content": "Hello!"}]
)
# 切换到DeepSeek
response = completion(
model="deepseek-chat",
messages=[{"role": "user", "content": "Hello!"}]
)
6.3 One-API：轻量级中转
One-API适合快速搭建私有API网关。
bash
# Docker一行部署
docker run --name one-api -d \
--restart always \
-p 3000:3000 \
-e TZ=Asia/Shanghai \
-v /data/one-api:/data \
justsong/one-api
# 访问 http://你的服务器IP:3000
# 初始账号: root
# 初始密码: 123456
# ⚠️ 登录后立即修改密码！
配置渠道：
plaintext
1. 登录后台 > 渠道 > 添加渠道
2. 选择类型（OpenAI/Anthropic/DeepSeek等）
3. 填入官方API Key
4. 选择支持的模型
5. 设置权重（负载均衡）
python
# 调用示例
from openai import OpenAI
client = OpenAI(
api_key="sk-你生成的令牌", # One-API生成的令牌
base_url="http://服务器IP:3000/v1" # 改成你的服务器地址
)
# 现在可以调用所有配置的模型
response = client.chat.completions.create(
model="gpt-4o", # OpenAI
messages=[{"role": "user", "content": "你好"}]
)
response = client.chat.completions.create(
model="claude-3-5-sonnet-20241022", # Anthropic
messages=[{"role": "user", "content": "你好"}]
)
response = client.chat.completions.create(
model="deepseek-chat", # DeepSeek
messages=[{"role": "user", "content": "你好"}]
)
6.4 多模型切换架构设计
python
# 多模型统一客户端
from abc import ABC, abstractmethod
from enum import Enum
from typing import Optional
import os
class ModelProvider(Enum):
OPENAI = "openai"
ANTHROPIC = "anthropic"
DEEPSEEK = "deepseek"
LOCAL = "local"
class UnifiedLLMClient(ABC):
"""统一大模型客户端基类"""
@abstractmethod
def complete(self, prompt: str, **kwargs):
pass
@abstractmethod
def chat(self, messages: list, **kwargs):
pass
class OpenAICompatibleClient(UnifiedLLMClient):
"""OpenAI兼容接口客户端"""
def __init__(self, base_url: str, api_key: str, model: str):
from openai import OpenAI
self.client = OpenAI(base_url=base_url, api_key=api_key)
self.model = model
def complete(self, prompt: str, **kwargs):
return self.chat([{"role": "user", "content": prompt}], **kwargs)
def chat(self, messages: list, **kwargs):
return self.client.chat.completions.create(
model=self.model,
messages=messages,
**kwargs
)
class ClaudeClient(UnifiedLLMClient):
"""Claude原生接口客户端"""
def __init__(self, api_key: str, model: str = "claude-sonnet-4-6"):
from anthropic import Anthropic
self.client = Anthropic(api_key=api_key)
self.model = model
def complete(self, prompt: str, **kwargs):
return self.chat([{"role": "user", "content": prompt}], **kwargs)
def chat(self, messages: list, **kwargs):
# 转换消息格式
system = kwargs.pop("system", None)
return self.client.messages.create(
model=self.model,
system=system,
messages=messages,
**kwargs
)
class MultiModelRouter:
"""多模型路由器"""
def __init__(self):
self.clients = {}
self._init_clients()
def _init_clients(self):
"""初始化所有客户端"""
# OpenAI (通过OpenRouter)
self.clients["gpt-4o"] = OpenAICompatibleClient(
base_url=os.environ.get("OPENROUTER_URL", "https://openrouter.ai/api/v1"),
api_key=os.environ.get("OPENROUTER_API_KEY"),
model="openai/gpt-4o"
)
# Claude (通过ClaudeAPI)
self.clients["claude"] = ClaudeClient(
api_key=os.environ.get("ANTHROPIC_API_KEY"),
model="claude-sonnet-4-6"
)
# DeepSeek (直连)
self.clients["deepseek"] = OpenAICompatibleClient(
base_url="https://api.deepseek.com/v1",
api_key=os.environ.get("DEEPSEEK_API_KEY"),
model="deepseek-chat"
)
def complete(self, prompt: str, provider: str = "claude", **kwargs):
"""统一完成接口"""
client = self.clients.get(provider)
if not client:
raise ValueError(f"Unknown provider: {provider}")
return client.complete(prompt, **kwargs)
def chat(self, messages: list, provider: str = "claude", **kwargs):
"""统一对话接口"""
client = self.clients.get(provider)
if not client:
raise ValueError(f"Unknown provider: {provider}")
return client.chat(messages, **kwargs)
def switch_model(self, provider: str, model: str):
"""切换模型"""
if provider in self.clients:
self.clients[provider].model = model
# 使用示例
router = MultiModelRouter()
# 调用Claude
response = router.chat(
messages=[{"role": "user", "content": "解释什么是装饰器"}],
provider="claude"
)
# 切换到GPT-4o
response = router.chat(
messages=[{"role": "user", "content": "解释什么是装饰器"}],
provider="gpt-4o"
)
# 切换到DeepSeek
response = router.chat(
messages=[{"role": "user", "content": "解释什么是装饰器"}],
provider="deepseek"
)
7. 实战代码示例
7.1 Agent开发：带工具调用的Claude
python
import os
from anthropic import Anthropic, HumanStopEvent
from typing import List, Dict, Any
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
# 定义工具
tools = [
{
"name": "get_weather",
"description": "获取指定城市的天气",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"}
},
"required": ["city"]
}
},
{
"name": "calculator",
"description": "执行数学计算",
"input_schema": {
"type": "object",
"properties": {
"expression": {"type": "string", "description": "数学表达式"}
},
"required": ["expression"]
}
}
]
# 工具实现
def execute_tool(name: str, arguments: dict) -> str:
if name == "get_weather":
city = arguments["city"]
# 实际项目中这里调用天气API
return f"{city}今天晴天，25°C"
elif name == "calculator":
expression = arguments["expression"]
# 安全评估后执行
result = eval(expression)
return str(result)
return "未知工具"
# 带工具调用的对话
def chat_with_tools(messages: List[Dict], max_turns: int = 5):
for turn in range(max_turns):
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=messages,
tools=tools
)
# 收集响应
messages.append({"role": "assistant", "content": response.content})
# 检查是否需要工具调用
tool_uses = [block for block in response.content if block.type == "tool_use"]
if not tool_uses:
# 没有工具调用，返回结果
return response.content[0].text
# 执行工具
for tool_use in tool_uses:
tool_name = tool_use.name
tool_args = tool_use.input
result = execute_tool(tool_name, tool_args)
# 添加工具结果
messages.append({
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": tool_use.id,
"content": result
}]
})
return "达到最大对话轮次"
# 使用
messages = [{"role": "user", "content": "北京天气怎么样？帮我算一下 123 * 456"}]
result = chat_with_tools(messages)
print(result)
7.2 RAG系统：多模型检索增强
python
from openai import OpenAI
from typing import List, Tuple
import os
class RAGSystem:
"""简化版RAG系统"""
def __init__(self, llm_client: OpenAI, embedder: OpenAI):
self.llm = llm_client
self.embedder = embedder
# 模拟向量数据库
self.documents = []
self.embeddings = []
def add_documents(self, docs: List[str]):
"""添加文档"""
self.documents.extend(docs)
# 生成embeddings
response = self.embedder.embeddings.create(
model="text-embedding-3-small",
input=docs
)
self.embeddings.extend([item.embedding for item in response.data])
def retrieve(self, query: str, top_k: int = 3) -> List[str]:
"""检索相关文档"""
# 查询embedding
query_embed = self.embedder.embeddings.create(
model="text-embedding-3-small",
input=query
).data[0].embedding
# 简单余弦相似度
similarities = []
for i, doc_emb in enumerate(self.embeddings):
sim = self._cosine_sim(query_emb, doc_emb)
similarities.append((i, sim))
# 返回top_k最相关的
similarities.sort(key=lambda x: x[1], reverse=True)
return [self.documents[i] for i, _ in similarities[:top_k]]
def _cosine_sim(self, a: List[float], b: List[float]) -> float:
"""计算余弦相似度"""
dot = sum(x * y for x, y in zip(a, b))
norm_a = sum(x * x for x in a) ** 0.5
norm_b = sum(x * x for x in b) ** 0.5
return dot / (norm_a * norm_b)
def query(self, question: str, system_prompt: str = None) -> str:
"""RAG查询"""
# 1. 检索相关文档
relevant_docs = self.retrieve(question)
context = "\n\n".join(relevant_docs)
# 2. 构建prompt
if system_prompt:
prompt = f"{system_prompt}\n\n参考信息：\n{context}\n\n问题：{question}"
else:
prompt = f"""基于以下参考信息回答问题。如果信息不足以回答，请说明。
参考信息：
{context}
问题：{question}"""
# 3. 调用LLM
response = self.llm.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
# 使用示例
llm_client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ.get("OPENROUTER_API_KEY")
)
embedder = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ.get("OPENROUTER_API_KEY")
)
rag = RAGSystem(llm_client, embedder)
# 添加知识库
rag.add_documents([
"Python的装饰器是一种高级语法糖，可以在不修改原函数的情况下增加功能。",
"装饰器接收一个函数作为参数，返回一个新的函数。",
"常见的装饰器包括@staticmethod、@classmethod、@property等。"
])
# 问答
answer = rag.query("什么是Python装饰器？")
print(answer)
7.3 流式输出：实时显示响应
python
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
# 方法一：官方SDK流式
print("Claude回复: ", end="", flush=True)
with client.messages.stream(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "写一首关于编程的诗"}]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
print("\n")
# 方法二：流式打字机效果
def typewriter_stream(prompt: str, provider: str = "claude"):
"""模拟打字机效果的流式输出"""
if provider == "claude":
stream = client.messages.stream(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}]
)
full_response = []
with stream as s:
for text in s.text_stream:
print(text, end="", flush=True)
full_response.append(text)
print()
return "".join(full_response)
else:
# OpenAI兼容格式
from openai import OpenAI
openai_client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ.get("OPENROUTER_API_KEY")
)
stream = openai_client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": prompt}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
8. 踩坑记录与最佳实践
8.1 我踩过的坑
markdown
## 血泪教训总结
### 网络问题
1. ❌ 直接调官方API → ✅ 用中转站
2. ❌ timeout=30 → ✅ timeout=60（长prompt需要更长）
3. ❌ 没有重试机制 → ✅ 指数退避重试
### 密钥安全
4. ❌ Key写在代码里 → ✅ 环境变量
5. ❌ .env上传GitHub → ✅ .gitignore
6. ❌ 共享账号Key → ✅ 各自独立
### API使用
7. ❌ 不设max_tokens → ✅ 必须设置，防止无限生成
8. ❌ 忽略429限流 → ✅ 实现退避重试
9. ❌ 不监控用量 → ✅ 设置预算告警
### 代码规范
10. ❌ 硬编码模型名 → ✅ 配置化
11. ❌ 没有异常处理 → ✅ try-catch包裹
12. ❌ 同步调用阻塞 → ✅ 考虑异步/流式
8.2 成本优化策略
python
# 成本优化实践
# 1. 模型选择策略
def select_model(task: str) -> str:
"""根据任务类型选择性价比最高的模型"""
if "分析" in task or "推理" in task:
return "claude-opus-4-7" # 复杂任务用强模型
elif "代码" in task:
return "claude-sonnet-4-6" # 编程用Sonnet
else:
return "claude-haiku-4-5-20251001" # 简单任务用Haiku
# 2. 缓存重复请求
from functools import lru_cache
import hashlib
@lru_cache(maxsize=1000)
def cached_complete(prompt_hash: str):
"""缓存常见问题"""
return None # 实际实现需要配合缓存系统
# 3. 批量处理减少API调用
def batch_process(items: list, batch_size: int = 10):
"""批量处理，减少API调用次数"""
for i in range(0, len(items), batch_size):
batch = items[i:i+batch_size]
# 将batch合并处理
yield batch
8.3 监控与告警
python
# 简单的用量监控
import time
from datetime import datetime
class UsageTracker:
"""简单的API用量追踪"""
def __init__(self):
self.requests = []
self.tokens = {"input": 0, "output": 0}
def record(self, model: str, input_tokens: int, output_tokens: int,
cost: float, success: bool = True):
self.requests.append({
"timestamp": datetime.now().isoformat(),
"model": model,
"input_tokens": input_tokens,
"output_tokens": output_tokens,
"cost": cost,
"success": success
})
self.tokens["input"] += input_tokens
self.tokens["output"] += output_tokens
def report(self):
"""生成报告"""
total_cost = sum(r["cost"] for r in self.requests)
success_rate = sum(1 for r in self.requests if r["success"]) / len(self.requests)
return {
"total_requests": len(self.requests),
"total_input_tokens": self.tokens["input"],
"total_output_tokens": self.tokens["output"],
"total_cost": total_cost,
"success_rate": success_rate
}
# 使用
tracker = UsageTracker()
# 在API调用后记录
tracker.record(
model="claude-sonnet-4-6",
input_tokens=1000,
output_tokens=500,
cost=0.018 # $2.40/1M input + $12.00/1M output
)
print(tracker.report())
8.4 开发环境配置模板
bash
# .env.example - 环境变量模板
# 复制为 .env 后填入实际值
# Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxx
# OpenRouter
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxx
OPENROUTER_URL=https://openrouter.ai/api/v1
# DeepSeek (国产替代)
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx
# 国内中转 (可选)
NONELINEAR_API_KEY=sk-xxxxxxxxxxxxxxxx
NONELINEAR_BASE_URL=https://api.nonelinear.com/v1
# 国内聚合 (可选)
API147_KEY=sk-xxxxxxxxxxxxxxxx
API147_BASE_URL=https://api.147api.com/v1
bash
# .gitignore
.env
.env.local
.env.*.local
__pycache__/
*.pyc
.pytest_cache/
.venv/
venv/
node_modules/
*.log
.DS_Store
总结
本文系统性地介绍了国内开发者访问大模型API的完整方案：
markdown
## 方案选择指南
┌─────────────────────────────────────────────────────────────────┐
│ 快速选择决策树 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 你是个人开发者？ │
│ │ │
│ ├── 学习/尝鲜 ──→ OpenRouter（免费额度） │
│ │ │
│ └── 生产使用 ──→ 非线智能api / ClaudeAPI.com │
│ │ │
│ 你的团队？ │
│ │ │
│ ├── 预算有限 ──→ One-API自建 + 官方Key │
│ │ │
│ └── 企业级 ──→ LiteLLM + 多渠道 + 监控 │
│ │ │
│ 你用Claude Code？ │
│ └── CC-Switch 一键切换 │
│ │
└─────────────────────────────────────────────────────────────────┘
核心要点 ：
- 安全第一 ：永远不要把Key写在代码里，用环境变量
- 稳定性优先 ：通过中转站访问，避免网络问题
- 成本控制 ：根据任务选择合适的模型
- 架构设计 ：从一开始就考虑多模型切换
- 监控告警 ：设置用量预算，防止意外支出
希望这篇指南能帮助到和我一样在AI开发路上摸索的同学们！如果有问题，欢迎交流。
（本文会持续更新，欢迎收藏）
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
9
0- 0
已为社区贡献12条内容
所有评论(0)