摘要
- 流式响应需要健壮的 SSE 解析来处理不完整的数据块和最终的令牌用量数据。
- 当模型在严格的 JSON schema 之外生成尾部文本时，JSON 模式会失败。
- 100k 上下文窗口在提示词和补全之间共享，因此长输出会减少可用的输入空间。
- 成本估算需考虑输出 token 比输入 token 更高的价格。
为什么您的流式响应挂起
当客户端未能读取包含令牌使用数据的最后一个服务器发送事件（SSE）数据块时，流式响应会挂起。我们的 API 随生成流式传输令牌，但连接仅在最后一个数据块到达后才完全关闭。如果你的客户端代码提前断开连接或忽略最后一个数据块，你将失去用于计费验证的确切令牌计数。
读取每一个数据块直到流结束。不要假设最后一个数据块只包含最终 token。我们 SSE 流中的最后一个数据块包含 usage 包含输入和输出令牌总数的字段。如果丢弃此数据，您将无法准确跟踪预付费信用的消耗情况。
常见陷阱
- 忽略最后一个 SSE 事件。
- 为长完成任务设置的超时时间过短。
- 不处理流式模式下的部分 JSON。
始终消耗整个流，以确保服务器知道客户端已接收完整响应。这可以防止我们方面的资源泄漏，并确保您拥有自己的日志所需的数据。
生产环境中处理 JSON 模式错误
JSON 模式错误是因为模型可能在闭合括号后生成文本，违反了严格的 JSON 解析规则。当你设置 response_format 到 {"type": "json_object", 模型会尝试输出有效的 JSON，但通常会在闭合括号后添加类似“这是数据：”的对话式填充内容。您的解析器随后会在额外文本上崩溃。
删除最后一个有效闭合括号后的尾随文本。不要依赖模型恰好在 JSON 结构结束时停止。您必须实施后处理步骤来查找最后一个 '}' 或 ']' 并丢弃其后的所有内容。这在解析数组或嵌套对象时至关重要。
最佳实践
- 使用正则表达式提取最后一个有效的 JSON 块。
- 使用 JSON 解析器验证提取的字符串。
- 如果输出混乱，以较低的温度重试。
这种方法确保即使模型决定变得多话，您的生产管道也能保持稳定。无审查模型约束较少，因此它们的格式可能感觉更具“创造性”。
理解上下文窗口限制
上下文窗口限制为提示词和补全内容的总和 100,000 token。这意味着如果你的输入为 50,000 个 token，你最多只能生成 50,000 个 token 就会达到限制。该限制不仅针对输入，而是整个请求的共享预算。
通过从 100,000 中减去输入 token 数来计算您的可用输出空间。如果您发送大型系统提示或长消息历史，您的可用输出空间将相应减少。这对于维护长对话历史的应用程序至关重要。
计算示例
- 总窗口：100,000 个令牌。
- 输入 Tokens：20,000 个 token。
- 最大输出：80,000 个 Token。
如果您超出此限制，API 将返回错误。请密切监控令牌使用量，以避免模型响应意外截断。模型不会自动截断；如果总量超出窗口，它只会拒绝请求。
Token 计数与成本估算
成本估算需考虑输入和输出 token 的价格差异。输入 token 价格为每 1M 个 $0.15，而输出 token 价格为每 1M 个 $0.50。输出 token 显著更贵，因此生成长回复会比发送长提示词更快地增加成本。
通过计算预期令牌数量乘以相应价格来估算成本。例如，10,000 个输入令牌和 5,000 个输出令牌的成本为：(10,000/1,000,000 * $0.15) + (5,000/1,000,000 * $0.50)。这等于每次请求 $0.0015 + $0.0025 = $0.004。
定价表
| Token 类型 | 每 100 万令牌的单价 |
|---|---|
| 输入 | $0.15 |
| 输出 | $0.50 |
通过最终的 SSE 块或 API 响应跟踪您的使用情况。这确保您可以为高容量应用准确预算。预付费余额永不过期，因此您可以随时间规划支出，无需支付月费。
速率限制：300 RPM 详解
每个 API 密钥每分钟限流 300 次请求。此限制适用于所有请求，与负载大小或 token 数量无关。如果超出此限制，API 将返回 429 错误。您必须实现指数退避算法以优雅地处理这些错误。
监控您的请求速率并相应地调整并发量。如果您使用多个线程或进程，请确保它们共享同一个 API 密钥，并且 collectively 保持在每分钟 300 次请求的限制以下。超出此限制将导致临时错误，直到速率重置。
处理 429 错误
- 实现指数退避。
- 记录失败的请求以供分析。
- 如果限制频繁，请降低并发性。
我们的 API 专为高容量使用设计，但速率限制确保了所有客户端的公平使用。如果您需要更高的限制，可以生成新的 API 密钥，但请注意，每个账户一次只能保留一个活动密钥。
排查函数调用失败
当模型的工具定义与预期模式不匹配，或者模型未能为工具参数输出有效的 JSON 时，就会发生函数调用失败。确保你的工具定义精确并包含所有必需的参数。模糊的模式会导致格式错误的工具调用。
在执行函数之前验证工具参数。模型可能会生成缺少必填字段或包含错误类型的参数。您的客户端代码应通过重试并使用更清晰的提示或调整工具定义来处理这些错误。
调试步骤
- 检查工具定义语法。
- 验证参数类型和值。
- 审查模型输出中缺失的字段。
函数调用是一个强大的功能，但需要仔细的模式设计。无审查模型在工具定义方面可能不如经过过滤的模型一致，因此严格的验证至关重要。
为什么 '无审查' 并非完全无限制
“无审查”标签意味着模型不会拒绝合法的成人、虚构或争议性主题，但它对涉及未成年人的性内容仍有硬性限制。这是唯一始终适用的硬性内容限制。包含此类内容的请求将被拒绝，即使提示的其余部分完全有效。
其他拒绝可能仍会由于技术错误或速率限制而发生。该模型并非无所不能；如果输入过于复杂或超出上下文窗口，它仍然可能无法生成响应。请理解，“uncensored”指的是内容策略，而不是技术可靠性。
内容限制
- 不允许涉及未成年人的性内容。
- 允许合法的成人内容。
- 技术错误仍可能导致拒绝。
这种区别对于需要处理广泛主题的应用程序很重要。了解具体限制有助于你正确设计过滤逻辑。
调试 400 与 429 错误
400 错误表示请求本身存在问题，例如 JSON 无效、缺少必填字段或超过 8 MB 的请求体限制。429 错误表示您已超过每分钟 300 次请求的速率限制。区分这些错误有助于您快速修复正确的问题。
对于 400 错误，请检查请求负载和模式。对于 429 错误，请实现退避机制并降低并发。如果收到关于请求体大小的 400 错误消息，请确保单次请求未发送过多数据。8 MB 的限制是严格的。
错误代码
| 错误代码 | 含义 |
|---|---|
| 400 | 错误请求 |
| 429 | 超出速率限制 |
记录这些错误及其上下文（负载、时间戳）使调试变得更加容易。使用此数据优化您的集成并避免重复失败。
Heretic LLM 优化下一步
优化始于监控您的令牌使用量和错误率。使用最终 SSE 块中的令牌数据来跟踪您的实际消耗量。将其与您的预估成本进行比较，以确保准确性。根据您观察到的使用模式调整并发和速率限制策略。
考虑使用较低的温度以获得更一致的 JSON 输出或函数调用。如果你需要更具创意的响应，请增加温度，但要准备好应对更多的解析错误。尝试不同的参数，为你的用例找到合适的平衡点。
优化建议
- 密切监控令牌用量。
- 调整 temperature 以平衡一致性与创意。
- 实现健壮的错误处理。
以免费试用开始以测试您的集成。这是一种低风险的方式，可在承诺预付费额度之前验证您的客户端代码是否正确处理流式传输、JSON 模式和速率限制。
