排查常见 AI 聊天 API 错误

理解上下文窗口

API 失败的最常见原因之一是超出上下文窗口。上下文窗口定义了单个请求中允许的 token 总数，包括输入提示词和生成的补全。当达到此限制时，API 将拒绝请求并报错，通常指示序列过长。

开发人员常误将字符计数当作 token 计数。单个单词可能代表多个 token，具体取决于 tokenizer。例如，100,000 token 的上下文窗口（如我们的 推理 API 提供的那样）允许大量的对话历史或大型文档处理，但它并非无限。

• 监控 token 使用情况： 在发送请求前，使用模型的官方 tokenizer 准确计算 token 数量。
• 智能截断： 如果超出限制，请从对话历史中移除最旧的消息，而不是最新的消息。
• 考虑开销： 为模型响应保留一些 token。如果您的提示词使用了 63,000 个 token，则只剩下 1,000 个 token 用于补全。

未能管理此限制会导致连接断开或响应不完整。在部署到生产环境之前，始终根据模型文档验证您的 token 计数。

处理流式输出错误

通过 SSE 流式输出响应对良好的用户体验至关重要，但它们在错误处理方面引入了复杂性。与标准 JSON 响应不同，流可能会在中间断开。如果发生网络错误，你的客户端可能会收到部分数据，导致流处于未定义状态。

在实现流消费者时，必须仔细处理流的生命周期。在尝试解析流之前检查 HTTP 状态码。如果连接断开，您应该记录错误并决定是重试还是向用户显示消息。

此外，确保您的客户端正确处理流结束标记。某些库期望特定的关闭事件，而其他库则依赖连接关闭。误解这一点可能导致进程挂起或内存泄漏。

始终为流请求实施超时。如果 API 在合理时间内未发送响应，请中止请求以释放资源。这对于在高并发环境中保持稳定至关重要。

Token 计数与限制

Token 计数不仅仅是为了保持在上下文窗口内；它还涉及成本管理。每个 token 都有特定的价格，计算错误的使用量可能导致意外的账单。虽然我们的定价是透明的，具有输入和输出的每 token 费率，但你仍然需要准确跟踪使用情况。

大多数开发人员使用库来计数 token，但使用与您正在使用的模型相对应的正确 tokenizer 至关重要。不同的模型使用不同的 tokenizer，使用错误的 tokenizer 可能导致计数的 token 出现显著差异。例如，针对英文文本训练的 tokenizer 处理标点符号的方式可能与针对代码训练的 tokenizer 不同。

密切关注您的使用限制。我们的 API 允许每个密钥每分钟 300 个请求。如果超出此限制，您将收到 429 Too Many Requests 错误。在应用程序中实现简单的计数器可以帮助您在此限制内并保持服务不中断。

最后，请记住，相同 tokenizer 的不同实现之间的 token 计数可能会有细微差异。始终使用一些已知输入测试您的 token 计数逻辑以确保一致性。

标头配置陷阱

标头是 API 请求的配置层。配置错误是 400 Bad Request 或 401 Unauthorized 错误的常见来源。两个最关键的标头是 Content-Type 和 Authorization。

Content-Type 标头必须设置为 application/json。如果缺少或不正确，API 可能无法正确解析请求体。Authorization 标头必须包含您的 API 密钥，格式为 Bearer YOUR_API_KEY。常见的错误是忘记 Bearer 前缀，这会导致身份验证错误。

• 检查拼写错误： 确保正确复制 API 密钥，包括任何尾随空格或换行符。
• 验证标头： 使用 curl 或 Postman 等工具检查发送的标头。
• 处理大小写敏感性： 某些 API 对标头名称区分大小写，尽管大多数现代 API 不区分。

发送请求前始终验证标头。标头中的小错误可能导致整个请求失败，导致混淆和浪费调试时间。

速率限制管理

设置速率限制是为了确保公平使用并防止滥用。我们的 API 允许每个密钥每分钟 300 个请求。如果超出此限制，您将收到 429 Too Many Requests 错误。此错误包含一个 Retry-After 标头，指示您在发出另一个请求前应等待的时间。

要有效管理速率限制，请实施退避策略。不要立即重试，而是等待一段时间，该时间随每次重试呈指数增长。这可以防止您的应用程序在高峰时段压垮 API。

监控您的使用指标。大多数 API 提供仪表板或 API 端点来跟踪请求量。使用此数据优化应用程序的请求模式。如果您发出太多小请求，请考虑将它们批处理在一起。

请记住，速率限制是针对密钥的，而不是针对账户的。如果您有多个密钥，每个密钥都有自己的限制。相应地规划密钥分发，以避免意外达到限制。

错误代码解读

理解错误代码对于调试至关重要。您将遇到的最常见错误是 400 Bad Request、401 Unauthorized、429 Too Many Requests 和 500 Internal Server Error。

• 400 Bad Request： 这通常表示请求体存在问题，例如缺少字段或 JSON 无效。检查错误消息以获取哪个字段不正确的详细信息。
• 401 Unauthorized： 这表示您的 API 密钥存在问题。验证密钥是否正确且未被撤销。
• 429 Too Many Requests： 这表示您已超出速率限制。实施退避策略以优雅地处理此问题。
• 500 Internal Server Error： 这表示服务器端存在问题。短暂延迟后重试请求。

始终记录错误响应体。它通常包含关于出错的有价值信息，例如导致错误的具体字段。这可以为您节省数小时的调试时间。

优化请求体

请求体是 API 交互的核心。优化它可以提升性能并降低成本。常见的错误是在单个请求中发送过多数据。如果你的提示词过大，可能会超出上下文窗口或产生更高的费用。

仔细构建 JSON。确保所有必填字段都存在，并且仅在需要时包含可选字段。例如，如果你不需要流式输出，请勿包含 stream 参数。这可以减少负载大小并简化响应。

使用 curl 或 Postman 等工具测试你的请求体。这允许你验证 JSON 是否有效，以及 API 是否正确解析它。它还有助于识别正在发送的任何不必要的数据。

最后，考虑对相同请求缓存响应。如果你多次发送相同的提示词，你可以将响应存储在本地，避免再次进行 API 调用。这可以显著降低重复任务的延迟和成本。

调试函数调用

函数调用允许模型根据用户输入执行函数。调试函数调用可能具有挑战性，因为它涉及多个步骤：发送请求、接收函数调用、执行函数，并将结果发送回模型。

确保你的函数定义准确。模式必须与实际函数签名匹配。如果模式不正确，模型可能会生成无效的参数，导致你在尝试执行函数时出错。

记录函数调用参数和函数输出。这允许你验证模型是否生成了正确的参数，以及你的函数是否按预期执行。如果有错误，日志将帮助你识别问题。

优雅地处理错误。如果函数执行失败，将错误消息发送回模型，以便它调整其响应。这提供了更好的用户体验，并允许模型从错误中恢复。