本地大模型 API 服务搭建：把 Ollama 或 llama.cpp 变成兼容 OpenAI 的接口

在窗口里聊天只是本地模型的起点。编辑器、笔记软件、自动化脚本和你自己写的程序都可以调用它，前提是把它作为一个带 HTTP 接口的服务运行起来。一个 本地大模型 API 服务 能让所有这些工具使用同一个地址，数据留在你自己的机器上，也不用按 token 付费。这篇文章讲怎样把 Ollama 或 llama-server 变成兼容 OpenAI 的接口，怎样测试，怎样让其他设备能访问但又不对所有人敞开，以及多个客户端同时使用时要注意什么。安装的基础步骤请先看 Ollama 安装教程。

核对说明：接口支持情况、默认监听地址和 OLLAMA_HOST 设置来自 Ollama 的 OpenAI 兼容性页面和 FAQ，llama-server 的选项来自 llama.cpp 服务端 README，均在 2026-10-30 读取。不同版本的选项名称和默认值会变，请用 --help 核对你的版本。我们没有测试吞吐量，文中不提供速度数据。

要点速览（更新于 2026-10-30）

• Ollama 默认监听 127.0.0.1 的 11434 端口，支持 OpenAI API 的一个子集，包括 /v1/chat/completions、/v1/models 和 /v1/embeddings；客户端需要填一个 API 密钥，但 Ollama 会忽略它。

• 想让其他设备访问，可以用 OLLAMA_HOST 修改监听地址，但这是一个暴露范围的决定：Ollama 不校验密钥，所以要先配好防火墙或网关。

• llama-server 同样提供兼容 OpenAI 的路由，--host 默认是 127.0.0.1，--parallel 设置服务槽位数以支持多用户。

为什么要搭一个本地大模型 API 服务

有了接口，模型才从玩具变成基础设施。我们的编程助手指南里的编辑器插件向它发请求；Open WebUI 教程里的聊天界面只是另一个客户端；一个总结文档或给笔记打标签的脚本是第三个。它们说的是同一种语言，因为 OpenAI 风格的接口已经成了通用格式，所以从云服务换到自己的服务，往往只需要改一个设置：基础地址。

好处就是人们最初转向本地模型的原因：提示词留在你的硬件上，没有按 token 计费，离线也能用。代价是你成了运维人员：要决定谁能连接，要保证它持续运行，还要处理更新。本地与云端对比可以帮你判断这笔交换是否适合你的项目。

方案一：用 Ollama 作为服务

如果已经装了 Ollama，服务就已经存在。文档说明它在 http://localhost:11434/v1/ 支持 OpenAI API 的一个子集，示例代码里的 API 密钥写成 “ollama”，文档说明客户端要求填写但 Ollama 会忽略。对话接口列出的特性包括流式输出、JSON 模式、可复现输出、视觉、工具调用，以及对思考型模型的推理控制，文档还列出了 /v1/models、/v1/embeddings 等接口。因为只支持子集，你依赖的每个字段都请在兼容性页面上确认。

终端里的第一次测试如下：

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen2.5:14b", "messages": [{"role": "user", "content": "用一句话打个招呼。"}]}'

用官方 OpenAI 客户端的 Python 写法：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1/", api_key="ollama")
reply = client.chat.completions.create(
    model="qwen2.5:14b",
    messages=[{"role": "user", "content": "用一句话打个招呼。"}],
)
print(reply.choices[0].message.content)

如果模型还没下载，请先拉取。请求里的模型名必须和 ollama list 里的名称一致。

方案二：用 llama-server 作为服务

llama.cpp 项目自带服务端。它的 README 描述了一组 REST 接口和网页界面，包含兼容 OpenAI 的 chat completions、responses 和 embeddings 路由，面向多用户的并行解码、连续批处理、函数调用和监控接口。启动时指定模型文件，常用的选项有 --host（默认 127.0.0.1）、--port、--ctx-size、--parallel（服务槽位数，默认自动）和 --alias（给模型起一个接口里使用的名称）。请用 --help 核对，因为新版本会改一些命令名。模型文件从哪里获取，见我们的 GGUF 与 llama.cpp 入门。

两者的选择主要看习惯。Ollama 按名称管理模型，是日常更简单的选择；llama-server 可以直接控制每个参数。三者对比里有详细讨论，下表总结与 API 相关的差异。

让其他设备也能访问

默认情况下两种服务都只监听本机，这很安全，但对手机或第二台电脑没用。Ollama 的 FAQ 写明它绑定 127.0.0.1 的 11434 端口，可以通过 OLLAMA_HOST 环境变量修改监听地址。在使用 systemd 的 Linux 上，用 systemctl edit ollama.service 加入 Environment="OLLAMA_HOST=0.0.0.0:11434"，然后重新加载并重启；macOS 用 launchctl setenv；Windows 则设置用户环境变量并重启应用。

请先停一下，想想这个改动意味着什么。OpenAI 风格的接口接受任何密钥，所以绑定到所有网卡之后，能访问该端口的人都可以使用你的显卡和上面的模型。在可信的家庭网络里也许没问题，但在共享的办公网络、租用的服务器或有公网地址的机器上就不行。系统侧的做法见远程部署指南，下面的阶梯则说明如何一步一步扩大访问范围。

1. 只限本机。 保持默认，同一台电脑上的应用用 localhost。
2. 局域网加防火墙白名单。 绑定到网络，只放行需要访问的设备。
3. 反向代理加 API 密钥和 TLS。 在前面放一个 nginx 或 Caddy 这类网关，要求密钥并加密传输，模型服务只监听本机。
4. VPN 或零信任通道。 通过私有网络访问机器，而不是开放端口。

对大多数家庭来说，第 2 步或第 4 步就够了。团队使用时，第 3 步能提供按用户区分的密钥和日志，我们在团队共享服务器指南里会展开。千万不要在路由器上把这个端口转发到公网。

多个客户端同时使用

本地模型用有限的内存响应请求，所以并发是有代价的。在 Ollama 里，并发请求由 OLLAMA_NUM_PARALLEL 和 OLLAMA_MAX_QUEUE 等环境变量控制，每个并行请求都需要上下文内存，这就是上下文长度指南在这里很重要的原因。在 llama-server 里，--parallel 设置槽位数，上下文大小由各槽位共享，槽位越多，每个用户分到的上下文越少。先从一两个并行请求开始，用真实的工作负载测试，内存允许时再往上加。

如果要做繁重的多用户服务，专门的推理引擎就是为批处理设计的，参见vLLM 与 SGLang 入门。它们配置更复杂，但在大量请求同时到达时能更好地利用显卡。我们不在这里给出速度结论，因为结果完全取决于你的模型、显卡和请求组合。

按使用场景选择方案

合适的暴露程度取决于谁在使用，而不是技术上能做到什么。下表把常见情况对应到一个起点，请按你自己的网络和风险承受能力调整。

让模型保持就绪

如果服务每次调用都要重新加载模型，使用起来会觉得很慢。Ollama 会在空闲一段时间后卸载模型，OLLAMA_KEEP_ALIVE 变量控制它在内存里保留多久；如果你的工具只是偶尔调用，而且显存放得下，就把时间设长一点。反过来也一样：如果服务器和游戏或其他工作共用一块显卡，较短的保留时间能更快释放显存。使用 llama-server 时，只要进程在运行，模型就一直在内存里，问题就变成要不要开机自启，可以用 systemd 单元或 Windows 服务封装来实现。

请记住，重启之后的第一次请求会比较慢，因为要从磁盘加载模型。如果客户端在第一次调用时超时，可以在启动脚本里先发一个简短请求来预热模型。

配置常见客户端

大多数支持自定义 OpenAI 接口的工具都要填同样的三个值：基础地址、API 密钥和模型名。对本地的 Ollama，基础地址是 http://localhost:11434/v1/，密钥可以填任意字符串，模型名取自 ollama list。对 llama-server，使用它的主机和端口再加 /v1 路径，模型名用你通过 --alias 设置的别名。如果某个工具只认云服务，可以找“兼容 OpenAI”或“自定义提供商”的选项，许多编辑器和聊天应用都有。当客户端发送服务端不支持的字段时，可能被忽略也可能报错，所以对你依赖的每个功能，比如工具调用或图片输入，都要实际测试，不要想当然。

一个常见的意外是上下文长度。客户端可能以为模型支持很长的窗口，而服务端用的却是较小的默认值，于是长文档被悄悄截断。请在服务端显式设置上下文，并用长提示词测试，方法见上下文长度指南。

简短的加固清单

在别人开始使用之前，把这份清单走一遍。从另一台设备检查监听端口，确认服务到底监听了哪个网卡。添加防火墙规则，只放行需要访问的机器。如果使用网关，测试不带密钥的请求会被拒绝，并且模型服务本身不能从机器外部访问。如果流量经过你无法控制的网络，请开启 TLS，并保持软件更新，因为服务端项目会定期发布修复。最后决定谁能查看日志，因为提示词可能出现在日志里。

测试和监控接口

第一次 curl 成功之后，要测试实际中容易出问题的地方。用 /v1/models 路由列出模型，看客户端看到的名称对不对。发送一个流式请求，确认 token 是逐步到达的。发送一个长提示词，检查有没有被截断；对显存不足 24GiB 的机器，Ollama 默认的上下文窗口较小，需要的话请按文档的设置调大。最后从网络里的另一台设备发同样的请求，证明监听地址和防火墙是对的。

头一个星期请保留日志。在 Linux 上，journalctl -u ollama 能看到服务日志，llama-server 的 README 也介绍了可以启用的监控接口。如果请求变慢，运行 ollama ps 看加载的是哪个模型、有没有完全放在显卡上，因为溢出到 CPU 的模型使用起来就像服务坏了一样。

常见错误

• 绑定到 0.0.0.0 却忘了防火墙。 这样网络里任何人都能使用这个服务。
• 以为 API 密钥能保护 Ollama。 密钥值会被忽略，没有任何安全作用。
• 在容器里使用 localhost。 在 Docker 里，localhost 指的是容器自己。
• 使用没下载过的模型名。 请求会返回找不到模型的错误。
• 没检查内存就提高并行请求数。 每个槽位都要占用上下文内存。
• 把端口转发到公网。 请改用 VPN，或带密钥和 TLS 的网关。

常见问题

Ollama 的 API 真的兼容 OpenAI 客户端吗？

Ollama 支持 OpenAI API 的一个子集，所以常见的对话和嵌入调用可以用，但不是每个字段都支持。请在兼容性页面确认你需要的功能。

API 密钥该填什么？

任何非空字符串都行，比如 “ollama”。客户端库要求有值，Ollama 会忽略它。

怎样让另一台电脑连接？

把 OLLAMA_HOST 设为网络地址并重启 Ollama，然后在防火墙里只对可信设备放行这个端口。

能加上真正的身份验证吗？

可以，在前面放一个 nginx 或 Caddy 这样的反向代理，在那里要求 API 密钥，并让模型服务只监听本机。

Ollama 和 llama-server 选哪个？

想要简单和多个模型就选 Ollama；需要直接控制参数和槽位时选 llama-server。

一块显卡能同时服务多少用户？

这取决于模型、上下文大小和请求组合。我们没有测过，请用自己的工作负载测试，并从一两个并行请求开始。

和我们聊聊

正在为自己的工具搭建 API 服务？欢迎到社区分享，或者发邮件到 admin@microaione.com。

参考资料：Ollama OpenAI 兼容性、Ollama FAQ、llama.cpp 服务端 README。