AI部署接口连通与流式自检

完成下面的 AI部署接口连通与流式自检后，你将有一套可重复执行的请求检查方法，能区分单次 JSON、流式 NDJSON 和异常对象。开始前需要能访问 Ollama API 文档 所列本地服务，并准备一个可供调用的模型；原生请求基址为 http://localhost:11434/api，OpenAI-compatible 基址为 http://localhost:11434/v1，以下命令默认在服务所在机器执行。

准备条件

准备一个可以发送 HTTP 请求的终端和 curl。根据 Ollama 身份验证文档，本地 API 不要求身份验证，只有云端请求需要 API key；本教程只访问本地服务，不应把云端密钥直接写进命令或配置，后续需要时应通过环境变量提供。

以下步骤假定 Ollama 服务已经启动，并且本地已有可调用模型。如果服务尚未运行或模型未准备好，先按当前官方文档完成安装、启动和模型准备，不要直接跳到生成请求。

AI部署：操作步骤

1. 确认服务、版本和模型

下面的端点、字段和成功标志按 Ollama API 文档 核对。model 使用 model:tag 格式；如果省略 tag，默认使用 latest。本文命令使用 llama3.2，执行前先确认模型列表中存在它。

curl http://localhost:11434/api/version

这条请求读取 Ollama 版本；服务可达时，响应中应包含版本信息。

curl http://localhost:11434/api/tags

这条请求返回本地可用模型列表；如果列表中没有 llama3.2，先完成模型准备，不要继续执行生成测试。

2. 验证非流式请求

按照 Ollama 流式接口文档，支持流式的端点在 stream 设为 false 时，会返回一个 application/json 对象，而不是连续响应。先保持模型、提示词和参数不变，只关闭流式输出。

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Why is the sky blue?",
  "stream": false,
  "options": {
    "num_ctx": 4096
  }
}'

这条请求显式关闭流式，正确结果应是一个完整的 JSON 对象。

如果输出被拆成多行，先检查 stream 是否为布尔值 false，以及请求体是否仍是有效 JSON；不要把非流式响应交给逐行解析器。

3. 验证流式请求

流式命令沿用 Ollama FAQ 中的请求形式；options.num_ctx 是按请求传入的模型参数。请求中不设置 stream，让端点采用默认流式行为。

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Why is the sky blue?",
  "options": {
    "num_ctx": 4096
  }
}'

正确结果是连续收到多个 NDJSON 对象，最终对象还包含本次请求的统计信息。

解析时应逐行读取 JSON，不要把整个响应一次性交给普通 JSON 解析器，也不要只凭终端文字出现的速度判断流式是否成功；对象边界和最终响应才是可靠的检查对象。

怎么确认成功

依次运行上面的四个请求并保留原始输出，同时满足以下条件，才算完成接口连通与流式自检：

• /api/version 返回版本信息，说明版本端点可达。
• /api/tags 返回包含 llama3.2 的本地模型列表。
• 设置 stream 为 false 后，只得到一个 application/json 对象。
• 省略 stream 后，得到多个 NDJSON 对象，最终对象包含统计信息。

前两项只完成了服务连通和模型检查；第三项验证非流式分支，第四项才验证默认流式分支。不要用其中一项的结果代替另一项。

常见出错点

按 Ollama 错误文档，普通错误以 application/json 返回，并放在 error 属性中：400 表示缺少参数或 JSON 无效，404 表示模型不存在，429 表示超过速率限制，500 表示内部错误，502 表示网关错误，例如无法访问某个云端模型。如果错误发生在流式响应开始之后，错误会作为含 error 的 NDJSON 对象到达，已经建立的 HTTP 状态码不会再改变。

请求体无效或模型不存在

可以故意发送一次无效 JSON，确认客户端能够识别错误分支：

curl http://localhost:11434/api/generate -d '{'

这次探针应得到 400，并从响应的 error 属性读取错误信息。

看到 400 时，检查 JSON 引号、逗号以及 model、prompt 等参数；看到 404 时，重新执行 /api/tags，并使用列表中实际存在的模型名，不要继续重复请求不存在的名称。

流已经开始后才出现错误

客户端必须检查每一个 NDJSON 对象中的 error，不能只检查首个对象或 HTTP 状态。修复方式是让解析器逐行处理响应，即使已经收到部分内容，也要在发现 error 后立即停止等待并记录该对象。

429、500 和 502

429 明确对应请求速率超限，应先降低调用端的并发和发送速率再重试。500 与 502 不等同于流式解析错误；先保留完整 error 内容，再按当前官方文档核对服务状态或上游模型是否可达，不要未经判断地反复重试。

本文步骤依据正文所链接的官方文档整理，未在本站机器上运行或测量；执行前请按当前版本核对。

资料来源

• Ollama API 介绍
• Ollama 身份验证
• Ollama API
• Ollama 流式响应
• Ollama FAQ
• Ollama 错误处理