这份清单面向「第一次把 AI 接口接进生产系统」的团队。顺序按真实推进节奏排,每一条都写清了「不做会怎样」。
用环境变量或密钥管理服务。提交记录里出现过的 key,一律当作已泄露,立即轮换。不做会怎样:仓库一旦被公开或前员工带走,账单由你付。
用一条最小请求确认网络、鉴权、模型名三件事都对。SDK 报错时你才知道是代码问题还是环境问题。
curl https://api.deepseek.com/v1/chat/completions \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-chat","messages":[{"role":"user","content":"ping"}]}'连接超时 5 秒,读超时按你的最长生成时间给(比如 60 秒)。SDK 的默认值通常太长或太短,都会出事。
不做会怎样:个别请求生成到上下文上限才停,一次调用烧掉几十块钱,而你毫无察觉。
每次都把 prompt_tokens / completion_tokens 落库,按业务维度(用户、功能、模型)聚合。没有这个,你无法回答「钱花在哪」。
| 状态码 | 含义 | 该怎么做 |
|---|---|---|
| 400 | 请求格式/参数错 | 不要重试,记日志修代码 |
| 401/403 | key 无效或无权限 | 不要重试,告警 |
| 404 | 模型名或路径错 | 不要重试,检查配置 |
| 413 | 请求体过大 | 切分输入,不要重试原请求 |
| 429 | 限流 | 指数退避重试,并降低并发 |
| 500/502/503 | 服务端故障 | 退避重试,多次失败切备用 |
| 超时/连接重置 | 网络或服务卡住 | 有限重试,注意流式半截断 |
流式响应收到若干块后连接断开,且没有结束标记——这不是「部分成功」,是失败。要丢弃已收到的内容并重试,否则用户会看到一段被截断的话。
接口全挂时,页面上应显示「当前咨询量较大,请稍后再试」,而不是一个 500 错误页或永久转圈。
用真实请求打 50 并发,持续 5 分钟,看 P95 延迟、429 比例、错误率。你会发现「官方标称的 RPM」和「实际能跑到的 RPM」经常差 2~5 倍。