DeepSeek API 返回 401：密钥配置与鉴权排查清单
调用 DeepSeek API 时收到 401，通常不是模型或网络问题，而是鉴权信息在链路的某个环节出了问题。本文按请求从代码到服务端的顺序，整理一份可逐项执行的排查清单，帮助首次集成的开发者快速定位。
说明：本文为通用排查框架，文中出现的环境变量名、请求头格式、endpoint、模型名等均为示例，具体参数请以 DeepSeek 官方文档为准。
一、先确认密钥是否真的被注入
最常见的问题是代码里写了一个占位符，而环境变量从未被设置。例如：
api_key = os.environ.get("DEEPSEEK_API_KEY") # 环境变量名仅为示例
如果该环境变量未定义，get 返回 None，后续拼接请求头时可能变成 Bearer None，服务端自然返回 401。排查时不要只看代码，要在运行环境中打印密钥是否存在、长度是否合理：
key = os.environ.get("DEEPSEEK_API_KEY")
print(bool(key), len(key) if key else 0)
注意不要打印完整密钥，避免泄露到日志。如果长度明显偏短，说明变量被截断或写入了错误值。
二、检查 Authorization 头格式
请先查阅 DeepSeek 官方文档，确认其要求的鉴权头格式。以下以常见的 Bearer 鉴权为例说明排查思路（示例格式，非官方确认）：
Authorization: Bearer
常见错误包括：
- 缺少
Bearer前缀，直接写密钥； Bearer与密钥之间缺少空格，或多了空格；- 大小写不一致，例如
bearer。注意：Bearer 方案的大小写是否敏感需按官方文档确认，不能断言大小写不一致必然导致 401，但建议严格按文档书写； - 在密钥前后混入换行符或引号。
用代码拼接时，建议显式构造并检查：
headers = {
"Authorization": f"Bearer {api_key}", # 格式请以官方文档为准
"Content-Type": "application/json"
}
如果从配置文件读取密钥，注意 YAML 或 .env 文件中的引号、行尾空格可能被一并读入。可以在发送前对密钥做一次 strip()，但更稳妥的做法是从源头保证值干净。
三、确认密钥没有被截断或混入换行
复制密钥时容易带入换行符，尤其是在终端或文档中跨行显示时。一个被截断的密钥在格式上仍然像密钥，但服务端无法识别。排查方法：
- 检查密钥字符串中是否包含
\n、\r或空格； - 确认密钥长度与官方控制台显示的一致；
- 如果通过 CI/CD 变量注入，检查变量值是否被自动换行或转义。
四、多环境配置是否混用
测试环境和生产环境应使用不同的密钥。如果测试代码误用了生产密钥，或生产环境加载了测试配置，可能出现“密钥本身有效但环境不匹配”的情况。需要说明的是，密钥混用可能表现为 401、403 或其他错误码，具体以服务端返回和官方文档为准，不能把环境不匹配直接等同于 401 的确定原因。排查时确认：
- 当前运行环境加载的是哪个配置文件；
- 环境变量是否被更高优先级的配置覆盖；
- 容器或函数计算环境中是否注入了旧密钥。
五、代理或网关是否篡改鉴权头
如果请求经过反向代理、API 网关或企业内网代理，鉴权头可能在转发过程中被丢弃或改写。常见现象是本地直连成功，经过网关后返回 401。排查时：
- 在代理层确认
Authorization头是否被保留； - 检查网关是否配置了额外的鉴权规则，覆盖了原始头；
- 如果使用 HTTP 代理，确认代理没有剥离敏感头。
六、最小可验证请求
在排除代码封装干扰时，可以用最小请求验证密钥本身是否可用。以下 curl 示例中的 endpoint 和模型名仅为示意，请替换为 DeepSeek 官方文档中给出的实际值。命令可直接复制执行，注释已移至代码块外。
curl https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "ping"}]
}'
说明：上述 endpoint、模型名和头格式均为示例，请以 DeepSeek 官方文档为准。
如果该请求成功而业务代码失败，问题就在代码的请求构造或配置加载环节；如果同样返回 401，则重点检查密钥本身和环境变量注入。
七、排查清单汇总
按顺序逐项确认：
- 环境变量是否已设置，值是否非空；
- 密钥长度是否与官方控制台一致，是否含换行或空格；
Authorization头格式是否符合官方文档要求（如 Bearer 前缀、空格、大小写）；- 代码中是否存在硬编码占位符覆盖了环境变量；
- 多环境配置是否混用密钥；
- 代理或网关是否保留并正确转发鉴权头；
- 用最小 curl 请求交叉验证（参数以官方文档为准）。
401 的本质是服务端无法从请求中识别出有效身份。沿着“密钥来源—请求头构造—传输链路”三段排查，绝大多数配置问题都能定位。