Ollama API：常见错误排除

了解 100k 上下文窗口

每个章节的第一句话都回答了标题中的问题。

100,000 token 的上下文窗口听起来很庞大，但它平均分配给输入提示和输出补全。当您发送长系统提示以及冗长的对话历史时，您消耗该预算的速度可能比预期的要快。许多开发人员认为该限制仅适用于输入，这会导致响应被截断或当模型达到上限时出现静默失败。

考虑一个将 50,000 token 的文档作为上下文传递的场景。您只剩下 50,000 个 token 用于实际生成。如果您不仔细管理这种平衡，模型将在句子中间截断。始终监控每次请求发送的总 token 数量，以避免意外的截断。

最大 Token 数与默认输出长度

每个部分必须回答标题中的问题。

除非你指定限制，否则大多数 API 默认输出长度适中，通常约为 2,048 个 token。这个默认值对于短查询很有用，但对于代码生成或长篇写作来说则是一场灾难。如果你需要模型生成完整的脚本或详细的分析，你必须明确设置 max_tokens 参数。

将此值设置过高也会影响延迟和成本。您为生成的每个 token 付费，无论其是否有用。务实的做法是设置一个与您的用例相匹配的合理上限，而不是将其保留为默认值或任意无穷大。

正确处理流式 SSE 块

流式传输需要仔细处理 Server-Sent Events 以避免数据丢失。

启用流式传输后，API 返回一系列小数据块，而非单个完整响应。每个数据块包含文本增量，但关键细节（如 token 使用统计信息）通常仅出现在最后一个数据块中。如果过早停止解析，您将错过用于计费或速率限制跟踪的使用数据。

此外，流式传输在错误处理方面引入了复杂性。网络中断可能会使您留下部分文本。您需要一个强大的解析器，能够从这些片段中重建完整消息。这在将文本实时渲染到 UI 组件时尤其重要。

函数调用工具定义错误

当工具模式与模型的预期不匹配时，函数调用会失败。

模型期望工具定义具有特定的 JSON 结构。如果您省略必填字段或使用错误的类型，模型可能会完全忽略该工具或返回格式错误的响应。这是构建需要与外部 API 交互的代理的开发人员常见的痛点。

在发送请求之前，始终根据您的 API 文档验证工具模式。即使是小的偏差，例如使用整数而不是字符串作为参数，也可能会破坏函数调用。调试此问题需要检查原始 JSON 响应，以查看模型是否尝试调用工具。

JSON 模式响应格式问题

JSON 模式强制模型输出有效的 JSON，但它仍然可能会产生幻觉。

当您将 response_format 设置为 json_object 时，模型被限制仅输出 JSON。然而，这并不能保证内容语义正确。模型可能会生成有效的 JSON 语法，但键错误或字段缺失。您仍然需要解析器在将数据用于之前验证结构。

此外，JSON 模式有时会降低模型的创造力或灵活性。如果您的提示词过于复杂，模型可能难以将叙事内容适应到严格的 JSON 结构中。此模式主要用于结构化数据提取或函数参数，在这些场景中一致性比细微差别更重要。

速率限制与并发请求

速率限制针对每个 API 密钥强制执行，而不是针对用户或 IP 地址。

大多数 API 对每分钟请求数和并发连接数施加限制。如果你超过这些限制，你将收到 429 Too Many Requests 错误。这对于生成多个线程或进程来处理用户请求的应用程序至关重要。单个密钥只能处理有限数量的并行请求。

要管理此问题，请在客户端代码中实现指数退避。当收到 429 错误时，等待一小段时间后再重试。这可以防止服务器过载，并确保更流畅的用户体验。始终检查响应标头中的 retry-after 值以优化等待时间。

API 密钥替换行为

重新生成 API 密钥会立即使前一个密钥失效。

部分平台每个账户只允许一个活动密钥。如果您生成新密钥，旧密钥会立即失效。如果您有多个服务或脚本使用旧密钥，这可能导致服务中断。在轮换密钥之前，请始终更新所有密钥实例。

此行为旨在确保安全，确保泄露的密钥无法无限期使用。然而，这在分布式系统中需要仔细管理。使用环境变量或密钥管理器存储您的密钥，使更新更容易且不易出错。

请求体大小限制

大型负载可能超过 8 MB 的请求体限制。

当发送以 base64 编码的长文档或图片时，请求体可能会迅速增大。如果超出大小限制，服务器将拒绝请求并返回 413 Payload Too Large 错误。这是一个硬性限制，在许多情况下，即使升级计划也无法增加。

为避免此问题，请压缩输入或将大型文档拆分为较小的块。您也可以对图像使用更高效的编码方法。始终监控请求的大小，尤其是在处理媒体丰富内容时。