大模型部署：用 Ollama 对外提供 API 服务实操

发表于 | 分类于 ，
从安装、拉取模型、启动服务到 REST/OpenAI 兼容 API 调用，说明如何用 Ollama 把本地大模型部署成可供局域网或公网访问的推理服务，并覆盖安全与常见接入方式。

5011.大模型-部署-部署工具-Ollama 侧重 Ollama 是什么、常用命令与 Modelfile 定制。本文接续同一条链路，聚焦一件事：装好之后，如何让其他程序、其他机器通过 HTTP API 调用你本地的模型。

段末注释：Ollama 是基于 llama.cpp 等引擎的本地大模型运行时，内置模型拉取、量化标签管理与 HTTP 服务；默认监听 11434 端口。

整体路径：

1
2
3
安装 Ollama → pull 模型 → serve（自动或手动）→ 本机 API 冒烟
  → 配置 OLLAMA_HOST 开放局域网 → 反向代理 + 鉴权（公网可选）
  → 业务侧用 curl / OpenAI SDK / Open WebUI 接入

一、安装与确认服务已启动

目标

在本机安装 Ollama，并确认后台 HTTP 服务可用。

方法

macOS / Windows：从 Ollama 官网 下载安装包，安装后菜单栏或系统服务会自动拉起 ollama serve。

Linux：

1
2
3
curl -fsSL https://ollama.com/install.sh | sh   # 官方一键安装脚本
sudo systemctl enable ollama                  # 开机自启（多数发行版）
sudo systemctl start ollama

验证服务：

1
2
curl http://127.0.0.1:11434/api/version
# 期望返回 JSON，含 ollama 版本号

结果里盯什么

  • 能访问 http://127.0.0.1:11434 说明 API 服务已起来（与是否在终端里 ollama run 无关）。
  • Linux 上若 curl 失败，查 systemctl status ollama 或手动 ollama serve。

二、拉取并加载模型

目标

把要对外提供的模型权重下载到本机，并确认能正常推理。

方法

Ollama 用 模型名:标签 标识版本（类似 Docker 镜像）：

1
2
3
4
ollama pull qwen2.5:7b          # 拉取 Qwen2.5 7B 量化版（标签省略时多为 latest）
ollama pull llama3.2:3b         # 更小模型，适合资源紧张机器
ollama list                     # 查看本机已有模型
ollama show qwen2.5:7b          # 查看模型详情（参数量、量化、模板等）

首次对话测试（CLI，非必须）：

1
ollama run qwen2.5:7b "用一句话介绍你自己"

模型标签怎么选

标签示例 含义
qwen2.5:7b 7B 参数量默认量化
llama3.2:3b 3B 小模型
qwen2.5:14b 更大参数量，显存/内存需求更高

显存不足时优先换更小标签或更小模型，而不是强行拉 :70b 类大标签。

结果里盯什么

ollama list 中出现目标模型且 ollama run 能正常吐字，再进行 API 层测试。

三、本机 API 冒烟（Ollama 原生接口）

目标

不依赖 CLI 对话，直接用 HTTP 验证「服务 + 模型」可用。

方法

列出模型：

1
curl http://127.0.0.1:11434/api/tags

对话补全（Ollama 原生 /api/chat）：

1
2
3
4
5
6
7
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [
    {"role": "user", "content": "天空为什么是蓝色的？用一句话回答。"}
  ],
  "stream": false
}'

流式输出（stream: true 时返回 NDJSON，逐 chunk 推送）：

1
2
3
4
5
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [{"role": "user", "content": "数到 5"}],
  "stream": true
}'

文本补全（/api/generate，单轮 prompt，无 messages 结构）：

1
2
3
4
5
curl http://127.0.0.1:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "写一首关于春天的五言绝句：",
  "stream": false
}'

常用 API 端点

方法 路径 用途
GET /api/tags 列出本地模型
POST /api/chat 多轮对话（推荐）
POST /api/generate 单轮文本生成
POST /api/embeddings 文本向量（用于 RAG）
GET /api/version 服务版本

完整说明见 Ollama API 文档。

结果里盯什么

响应 JSON 中 message.content（chat）或 response（generate）有合理文本；stream: false 时一次返回完整结果。

四、OpenAI 兼容 API（业务接入首选）

目标

让现有基于 OpenAI SDK 的代码只改 base_url 即可调用本地 Ollama。

方法

Ollama 在 /v1 路径提供 OpenAI 兼容接口，默认地址：

1
http://127.0.0.1:11434/v1

curl 示例：

1
2
3
4
5
6
7
curl http://127.0.0.1:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

Python（openai 库）：

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:11434/v1",
    api_key="ollama",   # Ollama 不校验 key，但 SDK 要求非空，任意字符串即可
)

resp = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "用中文说你好"}],
)
print(resp.choices[0].message.content)

Node.js：

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:11434/v1",
  apiKey: "ollama",
});

const completion = await client.chat.completions.create({
  model: "qwen2.5:7b",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(completion.choices[0].message.content);

与原生 API 的对应关系

OpenAI 端点 Ollama 支持 说明
POST /v1/chat/completions 是 最常用
POST /v1/embeddings 是 RAG 向量化
POST /v1/completions 部分 视版本而定，优先用 chat

结果里盯什么

choices[0].message.content 有内容；业务代码只需把云端 base_url 换成本机 11434/v1 即可做本地联调。

五、对局域网 / 其他容器开放服务

目标

让同一局域网内的其他机器、或 Docker 里的应用（如 Open WebUI、n8n）能访问本机 Ollama。

方法

默认 Ollama 只监听 127.0.0.1。要对外监听需设置环境变量：

1
2
export OLLAMA_HOST=0.0.0.0:11434   # 监听所有网卡，端口 11434
ollama serve

Linux systemd 持久化：

1
2
3
# /etc/systemd/system/ollama.service.d/override.conf
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
1
2
sudo systemctl daemon-reload
sudo systemctl restart ollama

局域网内其他机器测试（将 192.168.1.100 换成宿主机 IP）：

1
curl http://192.168.1.100:11434/api/tags

Docker 中的 Open WebUI 连接宿主机 Ollama：

1
2
3
4
5
6
7
docker run -d \
  --name open-webui \
  -p 3000:8080 \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:main

浏览器访问 http://localhost:3000，即可通过 Web UI 使用本机 Ollama 模型。

安全注意

OLLAMA_HOST=0.0.0.0 后，同一网段内任何设备均可无鉴权调用你的 GPU。仅限受信局域网使用；上公网必须加防火墙或反向代理鉴权（下一节）。

结果里盯什么

  • 局域网他机 curl http://<宿主机IP>:11434/api/tags 成功。
  • Open WebUI 能列出并对话本机模型。

六、公网暴露与安全（可选）

目标

若需从公网访问（VPS、内网穿透），在开放端口的同时避免裸奔 GPU。

原则

Ollama 没有内置 API Key 鉴权。公网方案三选一（可组合）：

方案 做法 适用
防火墙白名单 仅允许固定 IP 访问 11434 固定办公 IP 远程调试用
反向代理 + 鉴权 Nginx/Caddy + TLS + Basic Auth 或 Bearer 小团队共享
VPN WireGuard / Tailscale，Ollama 仍只监听内网 最安全，推荐生产

Nginx 反向代理示意（Ollama 仍只绑 127.0.0.1:11434）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
server {
    listen 443 ssl;
    server_name llm.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    auth_basic "Ollama";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:11434;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;          # 流式响应必须关闭缓冲
        proxy_read_timeout 300s;
    }
}

生成 Basic Auth 密码文件：

1
2
sudo apt install apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd your_username

客户端经 HTTPS 访问 https://llm.example.com/v1/chat/completions，并在请求头或代理层带上认证信息。

结果里盯什么

  • 公网未授权 IP 无法直接打到 Ollama。
  • 流式对话在代理后仍正常逐字输出（proxy_buffering off）。

七、自定义模型与 LoRA adapter 对外服务

目标

不仅使用官方库模型，还把自有 GGUF 或 LoRA 打成 Ollama 模型名，API 层统一用 model 字段调用。

方法

编写 Modelfile（类似 Dockerfile）：

1
2
3
4
5
6
# 从官方模型衍生，改 system prompt
FROM qwen2.5:7b
SYSTEM """
你是一个简洁的技术助手，回答用中文，不超过 200 字。
"""
PARAMETER temperature 0.3
1
2
ollama create my-qwen-assistant -f ./Modelfile
ollama run my-qwen-assistant "什么是 LoRA？"

API 调用时把 model 换成自定义名即可：

1
2
3
4
5
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "my-qwen-assistant",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": false
}'

从本地 GGUF 导入：

1
FROM ./models/my-model.Q4_K_M.gguf

挂载 LoRA adapter（需 Ollama 版本支持 ADAPTER 指令）：

1
2
FROM qwen2.5:7b
ADAPTER ./adapters/my-lora.bin
1
ollama create my-finetuned -f ./Modelfile

Modelfile 全量参数见 官方文档。

结果里盯什么

ollama list 出现自定义模型名；/api/chat 与 /v1/chat/completions 均能用该名称调用。

八、与选型文档的关系

需求 更合适的工具
本机 / 小团队快速起 API、改 base_url 联调 Ollama（本文）
高并发、多卡、生产级吞吐 vLLM 等
仅命令行聊天、不需 HTTP ollama run 即可（见 5011）

横向对比见 本地 LLM 部署框架选型与横向对比。

九、常见问题

现象 原因 对策
connection refused 服务未启动 ollama serve 或检查 systemd
他机访问不了 默认只监听 127.0.0.1 设置 OLLAMA_HOST=0.0.0.0:11434 并放行防火墙
Open WebUI 连不上 Ollama 容器网络隔离 OLLAMA_BASE_URL=http://host.docker.internal:11434 + host-gateway
model not found 未 pull 或名称写错 ollama list 核对，注意大小写与标签
流式响应被代理截断 反向代理开启缓冲 proxy_buffering off
OpenAI SDK 报错 api_key SDK 强制要求 key 填任意非空字符串，如 "ollama"
显存 OOM 模型过大 换更小标签或更小模型

十、小结

用 Ollama 对外提供服务的最小闭环：

  1. 安装 → 确认 11434 端口 API 可用。
  2. ollama pull → 模型落盘。
  3. 本机冒烟 → /api/chat 或 /v1/chat/completions。
  4. 业务接入 → OpenAI SDK 改 base_url 为 http://<host>:11434/v1。
  5. 扩大访问面 → OLLAMA_HOST=0.0.0.0（局域网）；公网必须加 TLS + 鉴权或 VPN。
  6. 定制 → Modelfile create 自定义模型名，API 无感切换。

与 ollama run 的 CLI 对话相比，Serving 的本质是多了一个长期运行的 HTTP 层；掌握 API 与网络暴露方式后，才能把本地模型接进 RAG、Agent、Open WebUI 和现有 OpenAI 业务代码。

-------------本文结束感谢您的阅读-------------