常见误区
新用户最常踩的 10 个坑。看一眼能省几小时排障。
1. base_url 末尾漏了 /v1
OpenAI SDK 会自动拼
正确：
/chat/completions。如果 base_url 是http://router.swarmixtoken.com（漏了 v1），SDK 会去请求 http://router.swarmixtoken.com/chat/completions → 404。正确：
http://router.swarmixtoken.com/v12. 把 OpenAI 和 Swarmix 的 Key 搞混
我们的 Key 以 sk-swx- 开头，不是 sk-。如果你不小心把 OpenAI 的sk-xxx 填进来，会 401 Invalid API Key。
3. 在浏览器里直接调用 API
永远不要把
正确做法：前端 → 你的后端服务器 → Swarmix。后端代理转发时校验用户身份。
sk-swx-* 放进前端 JS 代码。任何访问你网页的人都能 F12 看到它，然后全球薅你余额。正确做法：前端 → 你的后端服务器 → Swarmix。后端代理转发时校验用户身份。
4. 一把 Key 走天下
生产 / 测试 / 本地开发各用一把独立 Key：
- 泄露时可以精准吊销受影响的
- 用量统计能按 Key 拆分（看清是哪个业务在花钱）
- 可以给不同 Key 设不同的模型权限 / RPM 上限
5. 不处理 429 直接重试
RPM 触发时无脑循环重试只会让所有请求一起等。必须：
python
# 错误
while True:
try:
resp = client.chat.completions.create(...)
break
except RateLimitError:
continue # ❌ 马上再试，还是 429
# 正确
import time, random
for attempt in range(4):
try:
resp = client.chat.completions.create(...)
break
except RateLimitError as e:
retry = int(e.response.headers.get("retry-after", 1))
time.sleep(retry + random.uniform(0, 0.5)) # ✓ 退避6. max_tokens 设得太大 → 预扣"冻"掉所有余额
Swarmix 按 max_tokens 做最坏情况预扣。如果你 max_tokens=100000， 就算实际只用 500 token，也会在请求进行中把高额冻结掉，并行的其他请求可能余额"不够"被拒。
建议：max_tokens 按业务实际上限设（比如"一段摘要"设 500 够了）。
7. 以为 stream=true 就一定实时
流式只是渐进式返回，**不是**秒级响应。TTFT（首 token 时间）取决于上游：
- aliyun/qwen-turbo / aliyun/deepseek-r1：200-500ms
- aliyun/qwen-max：500ms - 2s
- deepseek-reasoner：5-15s（先思考后输出）
8. tools / function_call 用老版本语法
Qwen / DeepSeek / Hunyuan 都走 OpenAI 的**新版** tools 格式，不是老版的functions。如果你用了老版代码：
python
# ❌ 老版（OpenAI 2023 前）
response = client.chat.completions.create(
functions=[...],
function_call="auto",
)
# ✓ 新版
response = client.chat.completions.create(
tools=[{"type": "function", "function": {...}}],
tool_choice="auto",
)9. stream 响应不读 usage chunk
默认流式响应不包含 usage。需要显式开启：
python
stream = client.chat.completions.create(
...
stream=True,
stream_options={"include_usage": True}, # ← 加这行
)
# 循环到最后一个 chunk，choices 为空，usage 字段有值10. 以为 OpenAI / Claude 模型名一定可用
Swarmix 的公开调用以 GET /v1/models 返回的模型 ID 为准。gpt-4o、claude-3-5-sonnet 这类名称只有在当前部署显式配置了 public alias 时才可用，不应假设一定会自动映射到某个国产模型。
如果你需要确定性路由：直接传模型列表里展示的原生模型名 （例如 aliyun/qwen-max / aliyun/deepseek-r1 等）。