指南

作者： Matt Connor 2026-11-02 · 更新于 2026-11-09

Ollama 11434端口与API接口详解

Q: 11434 端口用于什么？

11434 是 Ollama HTTP API 的默认 TCP 端口。标准安装后，服务器绑定在 127.0.0.1:11434，ollama 命令行工具和所有 HTTP 客户端都通过该端口与其通信。原生 API 位于 /api，兼容 OpenAI 的 API 位于同一端口的 /v1。curl http://localhost:11434/api/tags 是检查服务是否响应的最快方法。

Q: 为什么对 11434 端口执行 curl 会显示 Connection refused？

您请求的地址上没有进程监听。运行 systemctl status ollama 确认服务正在运行，然后运行 ss -ltnp | grep 11434 查看绑定地址。如果服务器本机检查正常，但从笔记本电脑访问失败，原因通常是默认绑定地址：Ollama 仅监听 127.0.0.1，因此从公网接口到达的连接会被拒绝。您可以设置 OLLAMA_HOST 并添加访问控制，或者使用 ssh -N -L 11434:127.0.0.1:11434 user@your-server 转发端口。

Q: 如何让另一台机器访问 Ollama API？

运行 sudo systemctl edit ollama.service，并在 [Service] 行下添加 Environment="OLLAMA_HOST=0.0.0.0:11434"，然后运行 sudo systemctl daemon-reload 和 sudo systemctl restart ollama。使用 ss -ltnp | grep 11434 确认新的绑定地址。必须编辑该单元，因为服务器在 systemd 下以 ollama 用户身份运行，所以在 shell 中导出的变量不会传递给服务。本地 API 不要求客户端进行身份验证，因此在端口可从互联网访问前，应先配置防火墙规则或受密码保护的代理。

Q: 如何更改 Ollama 端口？

在 OLLAMA_HOST 中设置端口，因为该变量同时包含地址和端口。将 Environment="OLLAMA_HOST=127.0.0.1:11500" 写入 systemd 覆盖配置，然后重新加载并重启服务。还要更新所有客户端：如果某个客户端仍指向 11434，而该端口没有进程监听，就会收到连接拒绝；如果该端口仍由其他服务占用，则会连接到该服务。如果 ollama serve 以 bind: address already in use 退出，先运行 sudo ss -ltnp | grep 11434：该端口通常已被正在运行的 Ollama 服务占用。

Q: /api/generate 和 /api/chat 有什么区别？

/api/generate 接收一个 prompt 字符串，并返回一次补全结果。/api/chat 接收一个 messages 数组，每个元素包含一个 role；该端点支持工具调用。两者都不会在服务器上保存会话状态，因此客户端必须在每轮请求中发送完整的对话历史。对话类任务使用 /api/chat，分类等一次性文本处理使用 /api/generate。

了解如何用 curl 测试 Ollama 的 11434 端口，准确解读“连接被拒绝”，查看 API 端点，并安全设置 OLLAMA_HOST，避免暴露服务器。

11434 端口的用途

Ollama API 监听 TCP（传输控制协议）端口 11434。对 /api/tags 执行一次 curl 请求，即可确认它是否在响应。先在服务器本机执行，再从其他计算机进行测试。

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

有两种结果需要关注。如果返回 JSON，说明服务器进程已运行，并且 API 正在该端口响应。如果 curl 输出 Connection refused，说明该地址上没有进程监听。拒绝连接发生在应用层以下：TCP 层报告没有进程占用该端口，因此此时还与身份验证和模型名称无关。

/api/tags 是正确的首个请求，因为它不需要请求正文，也不会加载模型。它会列出您已经拉取的模型。

响应是一个包含 models 数组的 JSON 对象。下面是经过简化的结构，便于阅读。请将其视为示例，而不是固定格式：您使用的模型名称和大小会不同，不同版本之间也可能新增字段。

{
  "models": [
    {
      "name": "llama3.2:latest",
      "model": "llama3.2:latest",
      "size": 2019393189,
      "details": {
        "format": "gguf",
        "family": "llama",
        "parameter_size": "3.2B",
        "quantization_level": "Q4_K_M"
      }
    }
  ]
}

空的 models 数组表示服务器运行正常，但尚未拉取任何模型。要运行本地模型，应执行 pull，而不是重启；云端模型不需要本地下载。

curl 显示“连接被拒绝”的原因

按顺序完成以下 4 项检查。每项检查都用于排除一种不同的原因。

systemctl status ollama 用于确认服务是否正在运行。单元处于 inactive (dead) 状态时，本身就足以解释连接被拒绝。
ss -ltnp | grep 11434 显示监听器绑定的地址。没有任何输出表示没有进程在监听。
journalctl -e -u ollama 显示服务器停止的原因，或启动失败的原因。
curl http://localhost:11434/api/version 请求服务器版本。这是能够证明 API 本身正在响应的最小请求。

最常见的原因不是服务崩溃。Ollama 默认绑定 127.0.0.1 端口 11434，因此它只接受来自服务器本机的连接，其他位置都无法连接。你从笔记本电脑向 http://your-vps-ip:11434/api/tags 发起 curl 请求时会收到连接被拒绝，因为监听器没有绑定到该地址；但通过 SSH 在服务器上执行相同请求却可以正常工作。解决方法是 OLLAMA_HOST，后文会进一步介绍。使用它之前，应先仔细考虑其影响。

服务器上需要关注的端点

原生 API 位于该端口下的 /api。在 VPS 上运行 Ollama，而不是在笔记本电脑上运行时，以下路径值得了解。

GET /api/tags 列出磁盘上的模型。
POST /api/pull 按名称下载模型。
POST /api/generate 使用模型处理单个提示。
POST /api/chat 使用模型处理消息列表。
POST /api/embed 将文本转换为向量。
GET /api/ps 列出当前已加载到内存中的模型。
POST /api/show 返回模型的模板及其参数。
DELETE /api/delete 从磁盘删除模型。
GET /api/version 返回服务器版本。

生成与聊天：选择调用哪个接口

/api/generate 接收一个 prompt 字符串。它应用模型的模板并返回一次补全结果。服务器不会保存会话状态，因此后续问题必须再次发送完整的历史记录。

/api/chat 接收一个 messages 数组。数组中的每个条目都包含一个 role，其值为 system、user、assistant 或 tool，以及对应的 content。这是支持工具调用的端点。Ollama 在这里同样不会保存之前轮次的记忆：客户端每次都必须发送完整数组。

对所有对话式任务以及所有需要调用工具的任务，使用 /api/chat。对于分类或摘要等一次性文本任务，使用 /api/generate；这类任务不需要消息数组。

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

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    {
      "role": "user",
      "content": "why is the sky blue?"
    }
  ],
  "stream": false
}'

将 llama3.2 替换为实际已拉取的模型。请求本地不存在的模型会返回 404。API 不会代您下载模型。已登录的本地服务器也可以运行云模型，而无需下载该模型；请使用带 :cloud 后缀的云模型名称。

流式响应是默认行为，这一点常常令人意外

/api/generate 和 /api/chat默认使用流式响应，/api/pull也是如此。流式响应采用 NDJSON（以换行符分隔的 JSON）：每行一个 JSON 对象，而不是一个 JSON 文档。将整个响应体交给 JSON 解析器会导致解析失败，因为该响应体从未是一个单独的对象。

设置 "stream": false后，模型完成生成时会返回一个对象。对于脚本来说，这种结构更容易处理。代价是延迟更高：直到生成最后一个 token 之前，都不会收到任何内容。

在流式生成响应中，最后一行会携带 "done": true，以及 total_duration 和 eval_count等时间字段。时长单位为纳秒，因此 eval_duration等于 4709213000 时约为 4.7 秒。用 eval_count除以该秒数，才是衡量本地模型每秒生成 token 数的准确方法，因为这个数值来自实际运行的请求。

通过 API 拉取模型

curl http://localhost:11434/api/pull -d '{"model": "llama3.2"}'

连接会在整个下载过程中保持打开，并实时返回进度对象。添加 "stream": false 可静默等待，并在结束时只接收一个状态对象。通过 API 拉取模型时，模型会写入命令行使用的同一模型存储中，因此之后在该服务器上运行 ollama list 即可查看模型。

这对新服务器很重要，因为安装完成后，通常首先需要将模型写入磁盘。如果您现在正在配置服务器，请先从在 VPS 上完成可用的 Ollama 安装开始；等 ollama list 显示内容后，再返回 API。

嵌入

curl http://localhost:11434/api/embed -d '{
  "model": "all-minilm",
  "input": "Why is the sky blue?"
}'

input 接受字符串或字符串数组，因此可以在一次请求中发送一个批次。响应包含 embeddings 字段，其中每个输入对应一个向量；响应还包含耗时字段。

较旧的 /api/embeddings 端点仍会响应请求。它使用 prompt，而不是 input；返回单个 embedding，而不是 embeddings 数组。新代码应使用 /api/embed。字段名称不同，通常会导致复制的示例返回向量，但您的代码将其读取为 undefined。

/v1 下的 OpenAI 兼容接口

Ollama 还会在同一端口上提供 OpenAI 兼容 API，路径为 /v1。将现有客户端指向 http://localhost:11434/v1，然后确认其功能受支持，并将请求的模型改为 Ollama 模型名称。如果客户端要求使用 OpenAI 模型名称，可以通过 ollama cp 创建本地别名，例如 ollama cp llama3.2 gpt-3.5-turbo。

curl -X POST http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "gpt-oss:20b",
  "messages": [{ "role": "user", "content": "Say this is a test" }]
}'

该兼容接口支持 /v1/chat/completions、/v1/completions、/v1/models、/v1/models/{model}、/v1/embeddings 和 /v1/responses。大多数 SDK（软件开发工具包）需要配置两项：基础 URL http://localhost:11434/v1 和 API 密钥。Ollama 会忽略该密钥，但许多客户端没有密钥就无法启动，因此将其设置为字符串 ollama。

截至 November 2, 2026，该兼容层支持 OpenAI API 的部分功能。它支持 logprobs。图像可以通过 base64 或 URL 发送。它支持 tool_choice，但不支持向 /v1/responses 发送有状态请求。在通过此路径使用某项功能前，请先测试该功能是否满足需求。大多数编辑器插件都会使用此路径；通过它，您可以将编码代理指向自己的 Ollama 服务器，而不是使用付费端点。

OLLAMA_HOST 的作用

OLLAMA_HOST 设置 Ollama 服务器绑定的地址和端口。默认值是 127.0.0.1:11434，仅绑定回环地址。

同一个变量在客户端还有第二个作用。OLLAMA_HOST=http://10.0.0.5:11434 ollama list 会请求远程服务器报告其持有的内容。一个名称有两种含义：在服务器进程中，它决定服务器监听的位置；在命令行中，它决定客户端连接的位置。混淆这两者会导致用户只在 shell 中导出该变量，却不重启任何服务，随后发现监听地址没有变化。

在 Linux 上，服务器以 ollama 用户身份通过 systemd 运行，因此在交互式 shell 中导出的变量不会传递给它。应改为编辑服务单元。

sudo systemctl edit ollama.service

在打开的编辑器中添加以下代码块。

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

然后重新加载并重启服务，再次查看监听器。

sudo systemctl daemon-reload
sudo systemctl restart ollama
ss -ltnp | grep 11434

此时，ss 应显示监听器绑定在 0.0.0.0:11434，而不是 127.0.0.1:11434。如果仍显示回环地址，说明覆盖配置未生效：运行 systemctl show ollama --property=Environment 查看服务实际接收到的内容，并确认文件已写入 /etc/systemd/system/ollama.service.d/ 下。

为何暴露 Ollama API 是一项有意的操作

本地 Ollama API 不要求客户端进行身份验证。本地推理不需要令牌、用户或登录步骤。任何能够访问 11434 端口的人员，都可以列出您的模型、拉取新模型、删除模型，并使用您的硬件运行生成任务，费用也由您承担。

0.0.0.0 表示该计算机所连接的每个网络；对于 VPS，这还包括公网。扫描器很快就能发现开放的 11434 端口，因为这是固定的默认端口。因此，在更改绑定地址前，请先确定哪些人员需要访问，并在 API 前面增加访问控制：可以使用仅允许一个源地址的防火墙规则，也可以使用要求密码的反向代理。这些方案需要的篇幅超出本页范围，加固公开的 Ollama 端点对此有完整说明。

对于单个用户，更安全的做法是让服务继续绑定 loopback，并通过 SSH 建立隧道。

ssh -N -L 11434:127.0.0.1:11434 user@your-server

该命令运行期间，curl http://localhost:11434/api/tags 您的笔记本电脑会通过 SSH 会话访问服务器的 loopback 接口。任何内容都不会发布到公网，也不需要防火墙规则。

11434 被占用时如何更改 Ollama 端口

端口发生冲突。其他服务或 Ollama 的第二个实例可能已经占用 11434。更改配置前，先确定哪个进程占用了该端口。

sudo ss -ltnp | grep 11434

当 ollama serve 无法占用该端口时，会立即退出。错误消息会列出地址，并以 bind: address already in use 结尾。通常的原因是 systemd 服务已经在运行，而您又手动启动了第二个服务器。使用 sudo systemctl stop ollama 停止其中一个，或直接使用已经运行的服务。

要更改端口，请在同一个变量中设置新值，因为 OLLAMA_HOST 同时包含地址和端口。

[Service]
Environment="OLLAMA_HOST=127.0.0.1:11500"

完成 daemon-reload 和 restart 后，所有客户端都必须使用新配置。命令行需要使用 OLLAMA_HOST=http://127.0.0.1:11500，所有 HTTP 客户端也需要将基本 URL 修改为匹配的地址。如果没有进程监听 11434，仍指向 11434 的客户端会收到 Connection refused；如果其他服务或 Ollama 实例占用该端口，客户端则会连接到该服务或实例。

两个值得了解的变量

OLLAMA_ORIGINS 控制 CORS（跨源资源共享）。默认允许列表比 Ollama FAQ 中描述的范围更宽。源代码中，它在 http:// 和 https:// 上同时涵盖 localhost、127.0.0.1 和 0.0.0.0，无论是否带端口；此外还包括桌面应用和编辑器使用的 app://、file://、tauri://、vscode-webview:// 和 vscode-file:// 协议。因此，来自 http://localhost:3000 的页面或 VS Code webview 可以通过 Ollama 的默认 CORS 检查。本地文件可以发送 Origin: null，但它与 file://* 不匹配，默认会被拒绝。浏览器请求如果携带其他来源，例如您自己的域名或浏览器扩展，Ollama 会返回 403 Forbidden。添加所需来源，例如 Environment="OLLAMA_ORIGINS=chrome-extension://*"；您设置的值会追加到默认值，而不会替换默认值。该检查读取浏览器自动附加的 Origin 请求头，而 curl 不会发送此请求头。因此，它可以阻止网页请求，但完全不会影响 curl。

OLLAMA_KEEP_ALIVE 设置请求完成后模型在内存中的保留时间。默认值为 5 分钟。超时后，模型权重会被卸载，下一次请求需要再次等待加载。每个请求都可以发送 "keep_alive": "30m"，也可以发送 -1，让模型无限期保留在内存中。GET /api/ps 显示当前已加载的内容，并提供 expires_at 时间戳以及每个模型占用的内存。有关内存占用与首个令牌延迟之间的取舍，请参阅让 Ollama 模型保留在内存中。

每个请求的选项

/api/generate 和 /api/chat 都接受一个携带模型参数的 options 对象。

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "summarise this log line"}],
  "stream": false,
  "options": {"temperature": 0, "num_ctx": 8192}
}'

num_ctx 对内存使用量的影响最大，因为 KV cache（键值缓存）会随上下文长度增长。在小型 VPS 上将其设置得过高，模型会超出 RAM，甚至完全无法加载。根据硬件确定 num_ctx 介绍如何选择数值。如果多个客户端会同时调用 API，还需要考虑队列行为；OLLAMA_NUM_PARALLEL 和 OLLAMA_MAX_QUEUE 决定同时运行的请求数，以及需要等待的请求数。

故障模式和您将看到的字符串

Connection refused。该地址和端口上没有进程监听。先检查服务，再使用 ss -ltnp 检查绑定地址。从远程计算机访问时，这几乎总是表示 Ollama 仍绑定在回环地址上。

带有 error 字段的 404。读取错误消息：本地模型缺失和 blob 缺失都会产生此响应。/api/generate 不会按需拉取模型。如果错误指出缺少本地模型，请先执行拉取操作，同时检查标签和名称：llama3.2 与 llama3.2:1b 是不同的模型。云模型不需要下载到本地。

带有 error 字段的 400。请求正文被拒绝。在 shell 中，这通常是引号问题。直接写入 -d "{"model": "llama3.2"}" 会失败，因为 shell 会在 curl 看到内容之前移除外层双引号。请使用单引号包裹 JSON，或将 JSON 放入文件后发送 -d @request.json。

429，请求过多。这是速率限制导致的。对您自己的服务器看到此错误，说明 base URL 指向托管端点，而不是您服务器上的 11434 端口；也可能是请求指定了 :cloud 模型。您的服务器会将此类模型交给 Ollama 的托管服务处理，其用量会计入该账户。

流传输过程中出现错误。模型发生故障时，流式响应通常已经发送了 HTTP 200，因此状态码仍为 200，故障会以流中包含 error 字段的 JSON 对象形式出现。只检查状态码的客户端会将失败的生成报告为成功。请解析每一行。

第一个请求耗时远超后续请求。模型正在从磁盘加载到内存。调用前后分别执行 GET /api/ps，如果前者返回空列表、后者返回已加载的模型，即可确认这一点。提高 keep_alive 可以避免模型重复加载。

这里的每条命令都会连接您自己的实例，因此输出内容来自您的服务器，而不是我的操作记录。先在服务器上按顺序执行这些命令，再修改绑定地址。这样服务停止响应时，您就能确定发生故障的是哪一层。

FAQ

11434 端口用于什么？

11434 是 Ollama HTTP API 的默认 TCP 端口。标准安装后，服务器绑定在 127.0.0.1:11434，ollama 命令行工具和所有 HTTP 客户端都通过该端口与其通信。原生 API 位于 /api，兼容 OpenAI 的 API 位于同一端口的 /v1。curl http://localhost:11434/api/tags 是检查服务是否响应的最快方法。

为什么对 11434 端口执行 curl 会显示 Connection refused？

您请求的地址上没有进程监听。运行 systemctl status ollama 确认服务正在运行，然后运行 ss -ltnp | grep 11434 查看绑定地址。如果服务器本机检查正常，但从笔记本电脑访问失败，原因通常是默认绑定地址：Ollama 仅监听 127.0.0.1，因此从公网接口到达的连接会被拒绝。您可以设置 OLLAMA_HOST 并添加访问控制，或者使用 ssh -N -L 11434:127.0.0.1:11434 user@your-server 转发端口。

如何让另一台机器访问 Ollama API？

运行 sudo systemctl edit ollama.service，并在 [Service] 行下添加 Environment="OLLAMA_HOST=0.0.0.0:11434"，然后运行 sudo systemctl daemon-reload 和 sudo systemctl restart ollama。使用 ss -ltnp | grep 11434 确认新的绑定地址。必须编辑该单元，因为服务器在 systemd 下以 ollama 用户身份运行，所以在 shell 中导出的变量不会传递给服务。本地 API 不要求客户端进行身份验证，因此在端口可从互联网访问前，应先配置防火墙规则或受密码保护的代理。

如何更改 Ollama 端口？

在 OLLAMA_HOST 中设置端口，因为该变量同时包含地址和端口。将 Environment="OLLAMA_HOST=127.0.0.1:11500" 写入 systemd 覆盖配置，然后重新加载并重启服务。还要更新所有客户端：如果某个客户端仍指向 11434，而该端口没有进程监听，就会收到连接拒绝；如果该端口仍由其他服务占用，则会连接到该服务。如果 ollama serve 以 bind: address already in use 退出，先运行 sudo ss -ltnp | grep 11434：该端口通常已被正在运行的 Ollama 服务占用。

/api/generate 和 /api/chat 有什么区别？

/api/generate 接收一个 prompt 字符串，并返回一次补全结果。/api/chat 接收一个 messages 数组，每个元素包含一个 role；该端点支持工具调用。两者都不会在服务器上保存会话状态，因此客户端必须在每轮请求中发送完整的对话历史。对话类任务使用 /api/chat，分类等一次性文本处理使用 /api/generate。

这篇文章对您有帮助吗？

#ollama #api#curl#self-hosted-llm #网络