DeepInfra 报错调不通？地址鉴权模型 ID 三层排查法

代码从别的平台复制过来，改了两行配置，一跑就红。控制台里只有一行 Error code: 404 或者 401，没有更多线索——这是接 DeepInfra 时最常见的开局。

这种时候最浪费时间的做法是猜：怀疑网络、怀疑账号没开通、怀疑模型下架了，然后把三件事同时改一遍，跑通了也不知道是哪一步起的作用。更省事的做法是按固定顺序查三层：地址 → 鉴权 → 模型 ID。这三层是有先后依赖的，地址不对，鉴权根本没机会被验证；鉴权不过，模型 ID 写没写对服务端也不会告诉你。顺序反了，你会拿着一个下游的报错去改上游的配置。

而且这三层都是可以离线确认的事实，不需要看运行时日志，不需要压测，对着官方接入文档逐字比对就能定位。下面按这个顺序展开，最后再讲不属于这三层的那部分该怎么办。

三层的典型症状先对一遍

先给一张速查表，把症状和层次对上，再往下看细节。

症状	最可能的层	判断依据
返回 404，或者返回的根本不是 JSON（是 HTML 页面）	地址层	请求打到了不存在的路径，服务端按普通网页 404 处理
返回 401	鉴权层	凭据缺失或无效，路径本身是通的
返回 403	鉴权层	凭据被识别了，但这个凭据不被允许做这件事
返回结构化的 JSON 错误，内容指向模型不存在	模型 ID 层	地址和凭据都过了，服务端已经在处理业务参数
请求超时、连接被重置	都不是	网络或代理问题，先解决连通性再谈接口

这张表最有用的一条是 404 与 401 的先后关系。如果你拿到的是 404，先别去翻 key，key 再对也救不了一个不存在的路径。反过来，能拿到 401 其实是个好消息——说明地址层已经通了，服务端确实在这个路径上等着验凭据。

第一层：base_url 的路径顺序是最大的坑

DeepInfra 的 OpenAI 兼容 base_url 是：

https://api.deepinfra.com/v1/openai

请把这个地址多读两遍，重点看结尾：是 /v1/openai，不是 /openai/v1。

这一处顺序为什么值得单独开一节？因为它跟大多数人的肌肉记忆是反的。OpenAI 官方的地址结尾是 /v1，很多兼容平台也把版本号放在最后，接过几家之后手就习惯了先写服务名再写版本号。等你接 DeepInfra 的时候，眼睛看到的是文档里的正确地址，手打出来的是 /openai/v1，而且回头检查时大脑还会把它自动”读对”——因为你潜意识里认为它就该长这样。我见过不少人在这一行上卡半小时，最后是同事扫了一眼才发现的。

打错的后果很干脆：请求打到一个不存在的路径上，拿到 404。而 404 在报错信息里往往长得像”模型不存在”或者干脆是一段 HTML，于是排查方向立刻被带偏到模型 ID 上去，越查越远。

用 curl 打完整地址，再倒推 SDK 配置

不要在 SDK 层调试地址。SDK 会替你拼路径，你写的 base_url 和最终发出去的 URL 之间隔了一层拼接逻辑，出了问题你分不清是自己写错了还是拼错了。

正确的做法是先绕开 SDK，用 curl 把完整的最终地址打一遍：

curl -i https://api.deepinfra.com/v1/openai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPINFRA_TOKEN" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V3",
    "messages": [{"role": "user", "content": "hi"}]
  }'

-i 参数很关键，它会把响应头一起打出来，你能直接看到状态码，而不是只看到一段被截断的 body。

这一步跑通之后，你手里就有了一个已确认可用的完整 URL。接下来配 SDK 的时候是倒推：SDK 的 base_url 应该填到 /openai 为止，后面的 /chat/completions 由客户端库自己补。

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPINFRA_TOKEN"],
    base_url="https://api.deepinfra.com/v1/openai",
)

如果 curl 通了、SDK 不通，那问题一定在拼接方式上——常见的是 base_url 结尾多写了一个斜杠，或者把 /chat/completions 也写进了 base_url 里，导致最终地址出现重复段。把 SDK 的调试日志打开看一眼实际请求 URL，比对 curl 里那一行，差异会立刻显形。

这一层的排查成本极低，却能挡掉最多的无效时间——地址不对，后面所有的检查都是在做无用功。

第二层：鉴权，环境变量名不叫 API_KEY

地址通了之后再看鉴权。DeepInfra 的鉴权 header 是标准形式：

Authorization: Bearer $DEEPINFRA_TOKEN

注意官方文档里用的环境变量名是 DEEPINFRA_TOKEN，不是 DEEPINFRA_API_KEY。

这个细节单看无关紧要，你爱叫什么叫什么，只要值传对了就行。但它在一种场景下会集中爆发：批量迁移配置的时候。

多数团队的配置模板是按 *_API_KEY 的命名规律长起来的——OPENAI_API_KEY、GROQ_API_KEY，一路排下去。新增一家平台时，人的习惯动作是照着上一行的样式复制，于是 .env 里写了 DEEPINFRA_API_KEY，而代码里照抄官方示例读的是 DEEPINFRA_TOKEN。结果是：环境变量明明设了，程序读到的却是空值，请求带着一个空 token 发出去，服务端返回 401，你却对着 .env 文件反复确认”我明明配了”。

排查这一类问题只需要一行代码——不要打印 key 本身，打印它的长度：

import os
tok = os.environ.get("DEEPINFRA_TOKEN")
print("key present:", tok is not None, "| length:", len(tok) if tok else 0)

长度是 0 或者变量是 None，说明是命名对不上，跟 key 本身好不好使一点关系都没有。这一步能筛掉很大一批”401 疑难杂症”。

401 和 403 是两码事

按通用 HTTP 语义（这是 HTTP 协议层的约定，不是 DeepInfra 的专有定义）：

• 401 的语义是没通过身份验证——凭据缺失、格式不对、已失效。服务端不认识你是谁。
• 403 的语义是身份认了但权限不够——服务端知道你是谁，但不允许你做这件事。

方向完全不同。401 该去查 key 本身怎么传的；403 该去查这个账号/凭据的权限范围和账户状态。拿 403 去反复换 key，通常换不出结果。401 的通用排查思路更细的展开可以看 401 鉴权失败排查指南。

key 带了首尾空白，是最常见的低级原因

如果命名对得上、长度也不是 0，还是 401，下一个要怀疑的就是 key 的值本身被污染了。最高频的两种：

1. 复制时多选了一个空格或换行。从控制台拖蓝复制，尾部很容易带上一个不可见字符；粘进 .env 或者 CI 的 secret 输入框里，肉眼完全看不出来。
2. 用 shell 重定向写 .env 时带进了换行。这类 key 拼进 Authorization header 后，header 值就不合法了。

判断方法还是打印长度，跟控制台里那串的实际长度比对；或者干脆在读取时兜一道底：

tok = os.environ["DEEPINFRA_TOKEN"].strip()

生产代码里加这一行 .strip() 不算不优雅，它能省掉未来某个凌晨的一小时。同理，往 CI 的 secret 里粘贴时也建议粘完再手动确认一次尾部有没有多出来的字符。

第三层：模型 ID 是两段式，而且大小写敏感

地址和鉴权都过了之后，剩下的报错基本都落在业务参数上，其中模型 ID 出问题的比例最高。

DeepInfra 的模型 ID 是 HuggingFace 风格的 组织/模型名 两段式，官方示例是：

deepseek-ai/DeepSeek-V3

这个格式有三个独立的坑，很多人一次踩两个。

第一，组织前缀不能省。 从别的平台迁过来的代码，model 字段里可能只写了模型名那一段，没有前缀。少了前缀，服务端就找不到对应的条目。两段式命名与扁平式命名之间的差异和坑，模型 ID 命名规则 里讲得更全。

第二，大小写敏感。 DeepSeek-V3 里的大写字母不是排版风格，是标识符的一部分。写成 deepseek-v3 就是另一个字符串，不是同一个东西。这一点在两类地方最容易翻车：

• 代码里有人顺手加了 .lower()。比如为了做缓存 key 或者日志归一化，随手把模型名转成小写，然后不小心把转换后的值也传给了 API。
• 从表格、文档、聊天记录里手抄模型名。人抄写时会不自觉地把大小写”规整”成自己习惯的样子。

第三，配置框架的规范化处理。 一些配置加载库和网关中间件会对字符串做”善意”的处理——去空格、转小写、把斜杠当作路径分隔符再切一刀。前两种会破坏大小写，第三种更麻烦：deepseek-ai/DeepSeek-V3 里的那个斜杠可能被误认为路径层级，模型名被截断成一段。如果你的模型 ID 是从 YAML/JSON 配置里读出来的，打印一次实际传给 SDK 的值，别相信配置文件里写的那个。

print(repr(model_id))   # 用 repr，能一眼看出空白字符和大小写

repr() 比 print() 好用，因为它会把引号和转义字符都显示出来，尾部空格、换行一目了然。

顺带说一句好消息：从标准 OpenAI 配置切到 DeepInfra，官方口径是只需要三处改动——改 base URL、换 token、把模型改成其模型目录里的模型，现有 OpenAI 客户端库改动极小即可工作。也就是说，如果你改动的地方超过了这三处，多半是改多了。完整的接入步骤在 DeepInfra 接入怎么配 里。

三层之外：通用 HTTP 语义怎么判断”该改代码还是该重试”

三层都排完还在报错，那就进入了运行时问题的范畴。这里要先声明一句：**下面这部分讲的是 HTTP 层面的通用约定，不是 DeepInfra 官方文档的内容。**具体到该平台会返回哪些状态码、错误响应体是什么结构，请以官方文档和你实际收到的响应为准，我不替它做断言。

通用的判断轴只有一条：这个错误重试有没有意义。

类别	通用语义	该做什么
4xx（除 429）	请求本身有问题	改代码/改配置。重试一万次结果一样
429	请求速率超出了服务端允许的范围	退避后重试，并降低发送速率
5xx	服务端侧的问题	可以重试，但要有上限和退避
超时 / 连接错误	请求可能到了也可能没到	可以重试，但要考虑幂等性

几个容易做错的地方：

4xx 不要重试。 我见过在通用重试装饰器里把所有非 200 都纳入重试的写法，结果一个模型 ID 拼错的请求被重试了五次，日志里刷出五条一模一样的错误，还白白占了五次配额。重试策略应该按状态码分流，4xx 直接抛出去，让它尽早暴露。

429 要退避，不是要立刻重来。 撞到限速后立刻重发，只会让情况更糟——你在服务端已经判定你太快的时候，又发了一次。正确的做法是指数退避加抖动：等待时间逐次翻倍，并加一个随机量，避免多个客户端在同一时刻齐步重试形成新的尖峰。

超时重试要先想清楚幂等性。 超时的可怕之处在于你不知道请求到底有没有被执行。对于纯文本生成这种没有副作用的调用，重试的代价只是多花一次 token；但如果这次调用背后挂着写库、扣费、发消息，重复执行就是事故。退避与重试的具体实现写法，重试与退避 里有可以直接抄的模板。

诚实边界：限速数值和错误码清单，本文不写

有两件事我在这篇里刻意没写，说明一下原因，免得你以为是漏了。

一是该平台的速率限制数值。 写这篇时它的限速文档页取不到，我没有拿到可以确认的 RPM/TPM 数字。凭印象编一个数写进来，比不写更糟——你会照着一个假数字去做容量规划。

二是该平台特有的错误码清单和错误响应体结构。 同理，没有核实过的东西不能当作事实写。上一节的 HTTP 语义是协议层的通用约定，任何按 REST 规范做的服务都适用，但”这个平台在什么情况下返回什么码”是它自己的实现细节，得看它自己的文档。

不知道限速数值的时候，怎么稳妥地把服务跑起来？下面这套做法不依赖任何具体数值：

低并发起步。 从 1 到 2 的并发开始，先把功能跑通，别一上来就把线上流量全切过去。这个阶段的目标不是压出上限，是确认链路是通的。

加压要慢，而且一次只动一个变量。 确认稳定后再往上加并发，每一档跑满一段时间再加下一档。同时改并发数和请求体大小，出了问题你分不清是哪个引起的。

在加压之前先把退避重试准备好。 顺序不能反。没有退避机制就去加压，第一次撞限就会变成一连串失败请求，还可能把情况恶化。先有安全网，再走钢丝。

把撞限的表现记录下来。 这是最有价值的一步，也是最多人跳过的。撞到限制的那一刻，把当时的并发数、每分钟请求数、请求体大致规模、返回的状态码和响应内容全部记下来。跑几次之后，你手里就有了一份你自己场景下的经验值。这份数据比任何文档上的数字都好用，因为它是在你真实的请求形态下测出来的——同样的 RPM 限制，短请求和长上下文请求撞线的时机完全不同。

用监控代替猜测。 把状态码分布做成一个按分钟聚合的指标。哪个码在涨、什么时候开始涨，一眼就能看到。等到用户来报障时才去翻日志，你已经晚了。

留一条降级路径。 不知道上限意味着随时可能撞上。想清楚撞上之后怎么办：排队、降速、还是切到另一家。这个决定最好在出事之前做完，而不是在告警响的时候临时讨论。

排查顺序清单

按这个顺序走，从最省事的排到最费事的：

1. 看状态码，不看报错文案。 先确认到底是 404、401、403 还是别的。文案会误导，状态码不会。
2. curl 打一次完整地址。 确认 base_url 是 /v1/openai 结尾而不是 /openai/v1，带 -i 看响应头。这一步能同时排掉地址和网络问题。
3. 打印 token 的长度和是否为 None。 确认环境变量名是 DEEPINFRA_TOKEN 而不是 *_API_KEY，别打印 key 本身。
4. 给 token 加 .strip()。 排掉复制粘贴带进来的首尾空白，成本一行代码。
5. 用 repr() 打印实际传出去的模型 ID。 检查组织前缀在不在、大小写有没有被改、斜杠有没有被截断。
6. 对着官方模型目录逐字符比对模型 ID。 用编辑器的对比功能，别用眼睛。
7. 确认重试策略按状态码分流。 4xx 不重试，429 和 5xx 走退避重试，超时重试前先确认幂等。
8. 以上都过了还不通，去看官方文档和控制台的当前状态。 到这一步就不是配置问题了，限速、账户状态、模型可用性这些都以官方为准。

前五步加起来不超过十分钟，能覆盖掉绝大多数”调不通”。真正需要往下走到第八步的情况，比你想象的少得多。

相关阅读

• DeepInfra 价格与收费：三档价怎么读，月成本差十几倍
• Fireworks AI 双兼容端点迁移：OpenAI 与 Anthropic 两套代码不用重写
• Groq API 接入指南：拿 key 到 OpenAI 兼容避坑
• LiteLLM 回退/故障转移配置：三种 fallback 分开配才有用