Ollama API 故障排除指南

了解 Ollama API 端点结构

The ollama endpoint 遵循严格的 RESTful 模式，镜像 OpenAI API 结构。您通过发送 POST 请求与之交互， /v1/chat/completions 并通过 GET /v1/models. 此标准化允许您在无需重写客户端代码的情况下交换底层模型。

许多开发者认为端点默认支持嵌入或图像生成。事实并非如此。例如，我们的托管服务仅提供带有单个 uncensored 模型的文本补全。请始终检查 GET /v1/models 响应，查看确切暴露了哪些功能。如果您看到模型列表，请在发送请求之前验证它们的 ID。

使用本地实例时，端点通常运行在 http://localhost:11434. 对于云提供商，您将使用自定义基础 URL。确保您的 HTTP 客户端正确处理标头，特别是 Content-Type: application/json. 缺失的头信息通常会导致看似模型错误的静默失败。

密钥结构元素：

• model: 特定 LLM 的字符串标识符。
• messages: 基于角色的内容对象数组。
• stream: 启用服务器发送事件 (SSE) 的布尔标志。

为什么您的 ollama API 调用可能会失败

API 调用通常因 base URL 不正确、密钥过期或 JSON 负载格式错误而失败。最常见的错误是 401 Unauthorized 响应，这意味着您的 API 密钥缺失或无效。另一个常见问题是 404 Not Found，表示端点不支持请求的路径或模型 ID。

仔细检查您的请求正文。如果您发送端点不支持的参数，例如 modalities for 纯文本模型，服务器可能会拒绝请求。例如，我们的服务不支持图像输入。发送图像会导致立即报错。

网络超时也会导致失败。如果您的本地 Ollama 实例处于空闲状态，它可能会将模型从 VRAM 中卸载。冷启动后的第一个请求可能需要几秒钟。在 HTTP 客户端中设置充足的超时时间，以避免过早断开连接。

常见错误代码：

• 400: 错误请求（JSON 格式错误或参数无效）。
• 401: 未授权（API 密钥无效或缺失）。
• 429: 请求过多（超出速率限制）。
• 500: 内部服务器错误（模型加载失败）。

正确配置无审查的 ollama 模型

无审查模型通常需要特定参数才能按预期运行。主要区别在于 system 提示。您必须明确指示模型绕过标准拒绝。如果没有强大的系统提示，模型可能会恢复默认的安全行为。

我们的端点使用模型 ID uncensored. 您向此 ID 发送请求，服务器处理底层的模型选择。这抽象了管理模型版本的复杂性。您不需要知道底层架构是基于 Llama 还是 Mistral。

调整 temperature 参数以控制创意。值 0.7 是获得平衡回复的良好起点。较高的值会增加随机性，这对于创意写作很有用，但可能会降低事实准确性。较低的值会使输出更具确定性。

配置提示：

• 使用 top_p 旁边 temperature 用于更好地控制。
• 设置 stop 序列以防止无限循环。
• 始终包含一个 system 用于角色定义的消息。

处理流式传输和令牌限制

流式响应通过服务器发送事件（SSE）以数据块形式返回数据。每个数据块包含部分补全内容。你必须组装这些数据块以获得完整响应。我们的服务在最后一个数据块中包含令牌用量统计信息，允许你实时跟踪成本。

Token 限制对于长对话至关重要。我们的端点支持 100,000 个 Token 的上下文窗口，包括提示和完成总和。但是，每次请求的最大输出为 16,000 个 Token。如果你未设置 max_tokens, 默认值为 2,048 个 token。这可能会意外截断长答案。

流式传输时，请优雅地处理网络中断。如果连接断开，且服务器支持，您可以从最后一个接收到的块恢复。否则，您可能需要重试整个请求。始终监控 usage field in the final chunk to avoid billing surprises.

流式传输最佳实践：

• 正确解析 SSE 事件，忽略空行。
• 在内存或缓冲区中累积块。
• 检查 usage object in the last chunk for token counts.

账单错误与 Token 算术

计费错误通常源于对 Token 计数方式的理解偏差。Token 对输入（提示词）和输出（补全）均计费。我们的定价为每 1M 输入 Token $0.15，每 1M 输出 Token $0.50。错误和拒绝请求不收费，从而降低调试成本。

分词器并不总是与字符 1:1 映射。一个词可以是多个 Token。如果您根据字符数估算成本，可能会低估账单。在发送请求之前，请在您的客户端中使用可靠的分词器库以获得准确的计数。

信用余额不会过期。如果您使用加密货币充值，余额将保留直到您使用。这对长期项目非常有用。但是，请注意每次请求都会从您的余额中消耗令牌。如果余额不足，后续请求可能会失败。

计费提示：

• 在每个响应中追踪令牌使用情况。
• 设置低余额阈值警报。
• 使用 max_tokens 以限制潜在成本。

安全和端口扫描问题

本地 Ollama 端点通常默认暴露在网络中。这使得它们容易受到寻找免费计算资源的端口扫描器的攻击。如果您在不进行身份验证的情况下暴露端口 11434，任何人都可以使用您的 GPU 资源。这可能导致高昂的电费账单和性能下降。

通过更改默认端口或使用带身份验证的反向代理来保护你的端点。我们的托管服务为你处理安全性，因此你无需担心端口暴露。你只需保持 API 密钥私密即可。

对于本地部署，使用防火墙将访问限制在受信任的 IP 地址。你还可以在 Ollama 的配置文件中启用基于令牌的认证。这可以防止未经授权的用户发起请求。

安全步骤：

• 如果暴露到互联网，请更改默认端口。
• 使用带有 HTTPS 和身份验证的反向代理。
• 监控您的网络流量以查找异常活动。

本地与云 Ollama API 使用

本地使用让您完全掌控数据隐私和模型选择。您可以同时运行多个模型并即时切换。然而，您需要负责硬件维护、更新和安全。云使用将这些责任外包给提供商。

我们的云服务提供针对无限制内容生成优化的 uncensored 模型。您无需下载大型模型文件即可即时访问。代价是您的数据会经过我们的服务器。对于敏感数据，本地部署可能是更好的选择。

云服务通常因网络往返而具有较高的延迟。如果 GPU 足够快，本地实例的延迟接近零。然而，本地实例需要大量的 VRAM。如果您的 GPU 显存耗尽，模型可能会交换到 CPU，从而显著降低响应速度。

对比：

• 本地： 隐私、控制权、硬件依赖。
• 云： 便利性、可扩展性、数据传输。

常见的客户端错误

开发者常忽略处理速率限制。我们的服务允许每个密钥每分钟 300 次请求。如果超过此限制，你将收到 429 错误。在客户端实现指数退避，以优雅地处理这些错误。

另一个错误是不设置 stream parameter correctly. If you expect streaming but do not set stream: true, 您将等待整个响应完成后才能接收任何数据。这会使您的应用感觉缓慢。

JSON 模式错误也很常见。如果你设置 response_format: {type: "json_object"}, 模型必须返回有效的 JSON。如果未返回，您的解析器将失败。添加错误处理以捕获并重试 JSON 解析错误。

清单：

• 实现速率限制处理。
• 设置 stream: true 用于实时更新。
• 使用 JSON 模式时验证 JSON 输出。