理解上下文窗口限制
API 失败最常见的原因之一是超出上下文窗口。上下文窗口定义了模型在单次请求中可以处理的最大 token 数量,包括输入(提示词、历史记录、工具)和输出(补全)。如果你的 token 总数超过此限制,API 通常会返回错误或不可预测地截断你的响应。
例如,如果你使用的是具有 100,000 token 上下文窗口的无审查 Qwen 模型,你必须确保对话历史记录加上新提示词的总和不超过此阈值。许多开发者未能跟踪长会话的累积 token 数量,导致达到限制时集成突然中断。
- 跟踪 token 使用情况: 使用与模型分词器一致的 tokenizer 库来准确计算 token 数量。
- 修剪历史记录: 实现逻辑,当上下文窗口已满时丢弃较旧的消息。
- 监控限制: 如果提供,请检查 API 响应头以获取剩余上下文容量。
忽略这些限制不仅会导致错误;当模型在拥挤的窗口中难以关注相关信息时,还会降低响应质量。
正确处理流式响应
流式输出是现代 LLM API 的标准功能,允许你接收生成的部分响应。然而,许多开发者错误地假设流式输出为每个块返回完整的 JSON 对象。实际上,流式输出返回一系列 Server-Sent Events (SSE),每个事件包含一个部分 JSON 片段。
如果你使用的标准 HTTP 客户端不支持 SSE,你可能需要解析原始文本流,按 data: 行进行分割,并单独解析每个 JSON 对象。如果处理不当,可能会导致 JSON 格式错误或文本截断。
此外,确保你的 UI 或客户端库设计为追加增量文本,而不是替换之前的内容。流式输出也会影响 token 计数;你必须在 token 到达时进行计数,以保持在速率限制和预算限制内。
提示词中的常见格式错误
LLM 对提示词格式敏感。即使是对预期结构的微小偏离,也可能导致性能不佳或解析错误,尤其是在使用函数调用时。例如,如果你使用函数调用,模型期望提示词中包含特定的 JSON 模式。如果提示词包含多余的空格、缺失的逗号或错误的键名,模型可能无法生成有效的函数调用。
- 使用模板: 采用一致的提示词模板库以减少手动格式化错误。
- 验证 JSON: 在处理之前,始终根据预期模式验证输出 JSON。
- 测试边界情况: 使用包含特殊字符、换行符和不同长度的提示词进行测试,以确保健壮性。
当集成无审查 Qwen 模型时,确保你的提示词格式与模型的训练数据结构匹配。格式不匹配可能导致模型忽略指令或生成格式错误的输出。
速率限制与突发流量
API 实施速率限制以防止滥用并确保稳定的性能。一个常见的错误是发送超过每分钟限制的突发请求,导致后续请求以 429 Too Many Requests 错误失败。开发者经常通过低流量测试来忽略这一点,然后在扩大规模部署时未调整其请求策略。
例如,如果 API 允许每分钟 300 次请求,在一分钟内发送 301 次请求将导致最后一次请求失败。为避免这种情况,请在你的客户端库中实现指数退避。此策略在每次失败后增加重试之间的等待时间,从而防止进一步的拥塞。
此外,监控你的请求模式。如果你处理大批量数据,请考虑随时间间隔发送请求,而不是一次性全部发送。这确保了一致的性能并避免触及硬性限制。
Token 计数计算错误
Token 计数经常被低估。开发者经常计算字符或单词而不是 token,导致意外成本或上下文窗口溢出。分词器将文本拆分为子词,这意味着单个单词可能计为多个 token,尤其是对于非英语语言或技术术语。
例如,单词 uncensored 可能会被分词器计为多个 token。始终使用 API 提供商提供的官方 tokenizer 以获得准确的计数。这对于计算成本至关重要,因为定价通常按每 1M token 计算。
- 使用官方分词器: 避免使用每个 token 4 个字符之类的近似值。
- 计算输入和输出: 记住提示词和补全 token 都会计费。
- 监控使用情况: 为高 token 使用情况设置警报,以避免意外费用。
准确的 token 计数确保你保持在预算和上下文限制内,防止关键操作期间的服务中断。
函数调用配置问题
函数调用允许模型调用外部函数,但需要精确配置。一个常见的错误是 API 请求中定义的函数模式与代码中的实际函数实现不匹配。如果模式指定的参数类型与函数的签名不匹配,模型可能会生成无效的参数。
另一个问题是忘记在后续提示词中包含函数调用结果。模型需要工具的输出以生成最终响应。如果省略此步骤,模型可能会产生幻觉或提供不完整的回答。
确保你的工具定义清晰,具有描述性名称和参数。使用各种输入彻底测试函数调用流程,以确保模型正确解释并执行函数。这对于使用开放权重模型(如无审查 Qwen)尤为重要,因为它们可能具有不同的训练数据分布。
认证头错误
身份验证是你访问 API 的第一道防线。一个常见的错误是使用错误的 header 格式。大多数 OpenAI 兼容 API 期望授权 header 格式为Authorization: Bearer YOUR_API_KEY。使用 API-Key 或其他变体可能会导致 401 Unauthorized 错误。另一个问题是将 API 密钥作为查询字符串传递而不是头。虽然某些 API 支持此操作,但安全性较低,且可能不适用于所有客户端。始终优先使用头方法以获得更好的安全性和兼容性。
- 验证头格式: 仔细检查 API 文档中要求的头格式。
- 密钥安全存储: 将 API 密钥存储在环境变量中,而非代码中。
- 轮换密钥: 定期重新生成密钥,如果密钥泄露以最小化风险。
正确的身份验证可确保请求被正确识别和处理,避免不必要的重试和错误。
错误响应解读
API 错误为调试提供了有价值的线索,但经常被误解。400 Bad Request 错误通常表示输入数据有问题,例如无效的 JSON 或缺少必填字段。401 Unauthorized 错误指向认证问题,而 429 Too Many Requests 错误表示速率限制违规。
仔细阅读错误消息。它通常包含导致错误的字段或违反的具体约束等详细信息。例如,错误可能会显示 "Invalid value: 'function'",表明消息中的 role 字段不正确。
一致地记录错误,并包含请求负载和标头等上下文信息。这有助于稍后重现和诊断问题。不要忽略临时错误;实现带有指数退避的重试逻辑,以处理临时网络或服务器问题。
