要点
- Context windows combine prompt and completion, so long histories drain limits faster than expected.
- 流式传输需要谨慎处理 SSE 事件，以避免 JSON 损坏或 token 丢失。
- JSON mode demands strict schema adherence; malformed responses cause silent parsing failures.
- 预付加密货币计费意味着错误是免费的，但令牌计数必须精确，以避免意外。
为什么你的 API 密钥可能被拒绝
当客户端发送格式错误的标头或请求体超出限制时，API 密钥会被拒绝。服务器在处理任何逻辑之前会验证认证标头。如果标头缺失或包含多余的空格，请求将立即失败。
另一个常见原因是发送的负载超过了 8 MB 的 body 大小限制。具有大量消息的大型 context window 很容易超过此阈值。在发送前，请检查您的 message array 长度和 token 计数。
- 确保 Authorization 标头正确使用 'Bearer' 前缀。
- Verify the request body size stays under 8 MB.
- 检查 API 密钥是否有效且未过期。
理解上下文窗口限制
上下文窗口包含输入提示和生成的补全。我们的 API 支持 100,000 token 的窗口，但你必须同时考虑两端。如果你发送 80,000 token 的上下文，那么只剩下 20,000 用于响应。
如果您未指定 max_tokens，大多数模型会默认使用较小的输出限制。这可能会导致长回答被意外截断。仅当您希望设置上限时，才将 max_tokens 设置为所需的长度。请记住，该限制适用于整个请求，而不仅仅是提示词。
正确处理流式传输中断
通过服务器发送事件（SSE）进行流式传输需要强大的错误处理机制。如果连接断开，您可能会丢失最后一个 token 或使用量元数据。始终对传入的块进行缓冲，并在客户端重建完整响应。
Token 使用数据通常在流的最后一个 chunk 中发送。如果提前关闭连接，可能会错过确切的 token 计数。这会影响预付费系统的计费准确性。实现带有指数退避的重试机制，以处理临时网络问题。
使用专用的流式客户端，自动处理 SSE 解析。这可以降低解析错误的风险，并确保捕获所有数据。
JSON 模式解析错误
使用 response_format: {"type": "json_object"} 时，模型必须返回有效的 JSON。任何偏差都会导致应用程序出现解析错误。请确保您的提示词明确指示模型仅输出 JSON。
有时模型会在 JSON 周围包含 Markdown 代码块，这会破坏严格解析器。在解析之前移除 包装器。此外，在使用数据之前，请在客户端验证 JSON 结构。
使用模式验证库尽早捕获错误。这可以防止模型返回意外键或类型时发生崩溃。
令牌计数和计费意外
预付费仅按实际使用的 token 计费。错误和拒绝请求免费，这比订阅模式具有显著优势。然而，如果不考虑完整的上下文，token 计数可能会很棘手。
对话历史中的每条消息都会计入输入令牌限制。长对话会比你预期的更快地消耗你的预付费额度。请定期监控使用情况，以免在会话中途额度耗尽。
设置低余额提醒。这可以确保在请求失败前及时充值。请注意，余额不会过期，因此您可以随时方便时进行充值。
避免在 NSFW 提示词中出现软拒绝
当模型犹豫不决或提供部分答案而非直接回应时，就会发生软拒绝。这通常出现在争议性或成人话题中。即使在无审查的模型中，某些触发因素也可能导致犹豫。
调整 temperature 参数以减少随机性。较低的温度使模型更具确定性，且更不易含糊其辞。此外，确保提示词清晰直接。避免使用可能使模型困惑的模糊语言。
如果您遇到频繁的软拒绝，请尝试稍微调整提示词。细微的措辞变化通常可以绕过犹豫，获得直接的回答。
速率限制峰值与退避策略
API 每分钟允许 300 次请求，每个密钥允许 8 个并发请求。流量激增会迅速触及这些限制。实现指数退避以优雅地处理速率限制错误。
当收到 429 状态码时，请在重试前等待。从较短的延迟开始，并在每次重试时增加延迟。这可以防止在高峰时段使服务器过载。
监控您的请求速率并相应地调整并发级别。如果您正在发出许多并发请求，请考虑将它们分散到一段时间内。这可以确保稳定的吞吐量，而不会触及限制。
函数调用负载结构
函数调用需要特定的负载结构。在 tools 参数中定义你的函数，并指定 tool_choice。如果模型判断这是合适的响应，它将返回一个函数调用。
确保您的函数定义准确且完整。缺少参数或类型不正确可能导致模型生成无效调用。在执行之前，始终验证函数调用参数。
使用 tool_choice 参数来控制模型何时调用函数。您可以强制调用函数、让模型自行决定，或完全禁用函数调用。这使您能够对模型的行为进行细粒度控制。
调试 400 与 500 错误
400 错误表示客户端问题，例如 JSON 无效或缺少参数。500 错误表示服务器端问题，例如内部错误或超时。区分两者有助于更快地进行调试。
对于 400 错误，请检查响应中提供的错误消息。它通常直接指向问题所在。对于 500 错误，请稍作延迟后重试请求。如果错误仍然存在，请携带请求 ID 联系支持团队。
记录每次错误的请求和响应详情。这有助于识别模式和重复出现的问题。使用日志服务来跟踪随时间变化的错误，从而改进你的 API 集成。
