← Retour aux guides

LLM API 新手最常犯的 8 个错误：从能调用到可上线的实战排错指南

1. 只测试“能返回”，没有验证输出是否可用

许多新手看到接口返回 200 就认为集成完成，却没有检查内容是否完整、格式是否稳定、是否包含拒答或截断。生产环境应为每个关键任务建立验收样例：固定输入、预期字段、最大响应时间和允许的错误率。若要求模型输出 JSON，不要只在提示词里写“返回 JSON”，还应在客户端执行 JSON 解析、字段校验和失败降级。模型偶尔多输出一句解释，就足以让下游程序报错。

2. 把模型选择当成一次性决定

“最强模型用于所有请求”是最常见的成本陷阱。应按任务路由：分类、摘要、标签提取和简单客服优先使用轻量模型；复杂代码审查、长文推理和高价值决策再升级到能力更强的模型。先记录每类请求的输入 token、输出 token、成功率和人工修正率，再确定默认模型。59API 提供 Claude Opus、Sonnet、Haiku、Fable 及 GPT 模型的按量访问，可让团队用低成本方式做 A/B 测试，而非过早锁定单一模型。

3. 忽略上下文窗口与 token 预算

上下文越长并不必然越准确。无关历史会稀释重点，增加延迟和账单，还可能让关键指令被埋没。实际做法是将系统规则、当前任务、已确认事实和最近对话分层保存；每轮只拼接必要信息。对长文档采用分块检索：先按标题或语义切片，检索少量相关片段，再要求模型引用片段回答。还要为输出预留 token，避免输入接近上下文上限后出现截断。

• 给每类任务设定最大输入和最大输出 token。
• 记录 token 用量，不只记录请求次数。
• 将稳定的系统提示词缓存或复用，避免重复传输大段背景。

4. 没有为超时、限流和瞬时失败设计重试

网络超时、429 限流和 5xx 错误在真实调用中不可避免。错误做法是立即无限重试，这会放大流量并制造重复扣费或重复写入。正确方案是区分错误类型：对连接失败、超时和部分 5xx 使用指数退避加随机抖动；对 429 读取服务端建议的等待时间；对 4xx 参数错误直接记录并停止。涉及创建订单、发送消息等副作用操作时，为每个请求生成幂等键，确保重试不会执行两次。

5. 没有设置成本护栏

成本失控通常来自循环调用、异常长输入和未限制输出。建议在应用层建立三道护栏：单请求 token 上限、单用户日预算、项目级告警阈值。流式输出虽然能改善首字等待时间，但用户中途停止阅读时也应主动取消连接，避免模型继续生成。开发阶段使用小样本回归集评估提示词，避免每次改动都拿全量真实数据反复调用。

6. 将 API 密钥和用户数据直接暴露到前端

浏览器代码、公开仓库和客户端日志都不应保存长期 API 密钥。应由后端代理调用模型，并为不同环境配置独立密钥与额度。日志要脱敏：不要记录 Authorization 请求头、完整身份证号、密码或原始私密对话。对于用户提交的网页、文档或邮件，还要明确它们是不可信输入，禁止其内容覆盖系统指令或触发未授权工具调用。

7. 误以为兼容 SDK 就不需要迁移测试

兼容 OpenAI SDK 能显著降低接入成本，但仍应验证模型名、流式事件、工具调用、JSON 输出和错误对象是否符合现有业务预期。接入 59API 时，将 API Base URL 配置为 https://api.59api.com，并保留原有 OpenAI SDK 调用结构；使用 Claude Code、Codex 的团队也应先在测试环境跑一组真实工作流。重点检查超时配置、环境变量优先级和代理是否正确转发流式响应。

8. 不做可观测性，出了问题只能猜

每次调用至少记录请求 ID、模型、耗时、输入输出 token、状态码、重试次数和任务类型。不要默认记录完整提示词，生产日志应以摘要、哈希或脱敏字段为主。有了这些数据，才能判断问题是提示词退化、模型差异、网络抖动还是预算异常，并持续优化路由策略。需要以更低门槛接入官方质量模型时，可注册 59API，按量使用并通过推荐返利进一步降低长期试验成本。