第一步：安装 Ollama#

macOS 和 Linux 一行搞定：

1
curl -fsSL https://ollama.com/install.sh | sh
2

3
# 验证
4
ollama --version

Windows 用 PowerShell：

1
irm https://ollama.com/install.ps1 | iex

macOS 用户也可以用 Homebrew：brew install ollama。

安装脚本会顺带把 Ollama 注册成后台服务（Linux 上是 systemd，macOS 是 launchd），所以装完之后 API 已经在 http://localhost:11434 监听了。如果 ollama serve 报 address already in use，不用慌——那说明服务本来就在跑。

1
# 拉取并进入交互式 REPL
2
ollama run llama3.1:8b
3

4
# 常用管理命令
5
ollama list          # 已下载的模型
6
ollama ps            # 当前加载进显存/内存的模型
7
ollama show llama3.1:8b
8
ollama stop llama3.1:8b   # 手动卸载，释放显存
9
ollama rm llama3.1:8b

1
export OLLAMA_KEEP_ALIVE=30m

第二步：用 Modelfile 定制自己的模型#

Modelfile 之于模型，就像 Dockerfile 之于容器——把「每次调用都要重复传的参数」固化下来。这是 Ollama 最被低估的功能。

创建一个 Modelfile：

1
FROM qwen2.5:7b
2

3
# 采样参数
4
PARAMETER temperature 0.3
5
PARAMETER num_ctx 8192
6
PARAMETER top_p 0.9
7

8
# 系统提示词，决定模型的默认人格
9
SYSTEM """你是一位严谨的代码审查助手。
10
你会指出问题所在，并给出可直接替换的修改建议。
11
不要赘述显而易见的正确代码。"""

然后构建并运行：

1
ollama create code-reviewer -f ./Modelfile
2
ollama run code-reviewer

想基于已有模型改造？ollama show --modelfile <model> 能打印出它的完整配方，改几行再 create 就行。

关于两个参数值得展开说一下：

• num_ctx：Ollama 的默认上下文窗口相对保守（常见默认 2048），做 RAG 或者丢长文档进去时一定要调大，否则超出部分会被静默截断——这是「明明文档里有这段话，模型却说不知道」的头号原因。代价是显存和速度。
• 量化等级：模型名里的 q4_K_M 是默认推荐的量化档位，相比 FP16 大约小 4 倍，在多数任务上质量损失很小。显存紧张时降到 q4_0，追求质量可以上 q8_0。

第三步：把它当成 OpenAI 用#

除了原生 API（/api/generate、/api/chat），Ollama 还暴露了一套 OpenAI 兼容接口 http://localhost:11434/v1。这意味着 LangChain、LlamaIndex、各种 Agent 框架、IDE 插件，往往只需要改一个 base_url。

1
from openai import OpenAI
2

3
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
4
# api_key 是客户端库强制要求的必填项，但 Ollama 会忽略它的值
5

6
resp = client.chat.completions.create(
7
    model="llama3.1:8b",
8
    messages=[{"role": "user", "content": "用一句话解释什么是量化"}],
9
    temperature=0.3,
10
)
11
print(resp.choices[0].message.content)

不装 SDK 的话，原生接口用 curl 更直接：

1
curl http://localhost:11434/api/chat -d '{
2
  "model": "llama3.1:8b",
3
  "messages": [{"role": "user", "content": "你好"}],
4
  "stream": false
5
}'

把 stream 设为 false 会一次性返回完整结果；流式则是 NDJSON，每行一个 JSON 对象。调试时用非流式，生产里用流式提升体感。

第四步：装上图形界面 Open WebUI#

命令行够用，但一个带聊天记录、多会话、文档上传的界面体验好得多。Open WebUI 是自托管的 ChatGPT 风格前端，数据全在本地。

1
docker run -d -p 3000:8080 \
2
  --add-host=host.docker.internal:host-gateway \
3
  -v open-webui:/app/backend/data \
4
  --name open-webui --restart always \
5
  ghcr.io/open-webui/open-webui:main

几个参数解释一下：

• -p 3000:8080：容器内监听 8080，映射到宿主机的 3000，所以访问 http://localhost:3000。
• -v open-webui:/app/backend/data：把聊天记录、账号、设置持久化到命名卷。不加这个，容器一删数据全没。
• --add-host=host.docker.internal:host-gateway：让容器能访问宿主机上的 Ollama。Ollama 装在宿主机而不是容器里，是因为这样可以复用已有的 GPU 驱动和模型缓存，避免重复下载几十 GB。

有 NVIDIA 显卡就给 docker run 加上 --gpus all，镜像名换成 :cuda 标签。

启动后打开 http://localhost:3000，第一个注册的账号自动成为管理员，然后：

1. 右上角头像 → Admin Panel → Settings → External Connections
2. Ollama API 地址填 http://host.docker.internal:11434
3. 点 Verify Connection，看到绿色对勾就成了

如果连接失败，先确认 curl http://localhost:11434 能返回 “Ollama is running”。若 UI 里列表是空的，通常是还没 pull 任何模型。

第五步：做成私有知识库（RAG）#

Open WebUI 内置了 RAG 引擎，不需要额外写代码。

先装一个嵌入模型，用于把文档切块后转成向量：

1
ollama pull nomic-embed-text
2
# 中文文档效果更好可以选择 bge-m3
3
ollama pull bge-m3

然后在 Admin Panel → Settings → Documents 里，把 Semantic Vector Model Engine 设为 Ollama，Embedding 模型选 bge-m3，保存。

两种用法：

• 临时问文档：在聊天输入框点回形针图标上传 PDF/Word/TXT，之后的问题会自动带上这份文档的上下文。第一次上传会慢一些，因为要现加载嵌入模型。
• 长期知识库：Workspace → Knowledge → + 新建知识库，批量上传文件。之后在聊天里输入 # 就能把整个知识库挂进当前对话。

文档量大了之后，默认的向量存储会成为瓶颈，可以把向量检索迁到 Qdrant 这类专用向量库，Open WebUI 支持通过环境变量切换。

踩坑清单#

几个我在搭建过程中真实撞过的问题：

1. 答非所问 / 说文档里没有的内容。 先查 num_ctx。默认上下文常常装不下 RAG 塞进去的 chunk，超出部分被静默丢弃，症状就是「明明上传了却说不知道」。把它调到 8192 或 16384 再试。

2. 内存爆掉而不是显存爆掉。 显存不够时 Ollama 会自动把部分层放到 CPU 上跑，结果不是报错而是变得极慢。用 ollama ps 看，如果 PROCESSOR 那列是 CPU/GPU 混合，就是这个情况。调小模型或调低量化档位。

3. 模型加载慢。 每次对话前几秒的卡顿是冷启动。设 OLLAMA_KEEP_ALIVE=30m 让常用模型常驻。

4. 只能跑 GGUF。 Ollama 底层是 llama.cpp，只吃 GGUF 格式。HuggingFace 上的 safetensors 模型需要先转换，或者干脆换 vLLM 这类推理框架。

5. 单用户工具，别当生产服务。 Ollama 没有并发调度和队列管理，几个人同时用就会互相排队。真要做多用户的生产级部署，vLLM 或 TGI 是更合适的选择。

结语#

本地大模型的价值不在于「免费替代 GPT-4」——7B 模型的推理能力确实还差得远。它的价值在于可控：数据不出机器、没有网络依赖、没有按量计费、可以随意微调系统提示词、可以在断网的地铁上继续用。对涉及敏感数据的场景，或者只是想低成本理解 LLM 到底是怎么回事，这套组合拳的性价比很高。

从 curl 一行安装到浏览器里聊上第一句，熟练的话十分钟够了。剩下的时间，就花在调 num_ctx 和挑模型上吧——那才是本地部署真正的乐趣所在。

参考来源#

• Ollama 官方文档与 API 参考：https://github.com/ollama/ollama/blob/main/docs/api.md
• Ollama OpenAI 兼容接口说明：https://github.com/ollama/ollama/blob/main/docs/openai.md
• Open WebUI 官方文档：https://docs.openwebui.com/
• Ollama 模型库：https://ollama.com/library
• llama.cpp 项目主页：https://github.com/ggml-org/llama.cpp