信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。
读前提醒：先看 本地部署值不值：硬件、显存、电费与时间。本篇假设你已经接受"本地模型主要用于隐私/离线/学习，而非替代顶级云端模型"。
1. Ollama 是什么？
【有据可查】Ollama 是一个在本机运行大模型的工具，提供命令行、桌面应用和本地 REST API；本地 API 默认地址 http://localhost:11434，同时提供 OpenAI 兼容接口 http://localhost:11434/v1 与 Anthropic 兼容入口。来源：Ollama GitHub、API 介绍、OpenAI 兼容
【待核实】原稿写“截至 2026-10，最新稳定版为 v0.40.x”，本次未核对该版本结论。安装后用 ollama --version 查看自己的版本，再到 官方 Releases 核对；本文不把示例版本视为已确认的最新稳定版。
2. 安装【有据可查】
| 系统 | 方式 |
|---|---|
| macOS / Windows | 官网下载桌面应用：https://ollama.com/download |
| Linux | curl -fsSL https://ollama.com/install.sh | sh |
| Docker | 官方镜像 ollama/ollama |
首次运行 ollama 会出现引导，可选择登录或"仅本地使用"。【有据可查：Release 说明】
3. 常用命令
| 命令 | 作用 |
|---|---|
ollama run <模型> |
下载（若无）并进入对话，如 ollama run gemma4 |
ollama pull <模型> |
只下载 |
ollama list |
已下载的模型 |
ollama ps |
当前加载在内存/显存中的模型 |
ollama show <模型> |
查看模型信息（参数、模板、上下文、思考能力等） |
ollama rm <模型> |
删除 |
ollama cp <源> <新名> |
复制/改名（给只认固定模型名的工具用） |
ollama create <名> -f Modelfile |
用 Modelfile 自定义模型 |
ollama serve |
仅启动服务 |
ollama launch <工具> |
把 Ollama 接到 Claude Code、Codex、DeepSeek Harness 等工具（README 列出的集成） |
模型名与标签（如
:8b、:q4_K_M）以 ollama.com/library 为准；本文示例中的模型名只是示意。
4. 用 API 调用
# 原生 API
curl http://localhost:11434/api/chat -d '{
"model": "gemma4",
"messages": [{"role": "user", "content": "用一句话解释量化"}],
"stream": false
}'
# 本机 OpenAI 兼容 HTTP API：curl 不必填 Key；OpenAI SDK 需要占位 api_key，Ollama 本机服务会忽略它
curl http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"gemma4","messages":[{"role":"user","content":"Hello"}]}'
【有据可查：OpenAI 兼容文档】
接入 Agent：在 dsh、Codex 等工具里添加一个 OpenAI 兼容 provider，Base URL 填 http://localhost:11434/v1、Key 随便填（如 ollama）。（方法见DSH 添加模型：协议、地址、密钥与模型 ID、DSH 日常工作流、profile 与进阶用法/Codex 本地使用：安装、权限、项目规则与排错。）
5. Modelfile：定制你的模型
FROM gemma4
PARAMETER temperature 0.3
PARAMETER num_ctx 16384
SYSTEM """你是一个只用简体中文回答的技术助手，回答要简短。"""
ollama create my-assistant -f Modelfile
ollama run my-assistant
【有据可查】官方文档建议通过 ollama create 创建新模型来调整上下文长度等参数。【社区共识】num_ctx 设得越大越吃显存。
6. 安全设置
| 设置 | 说明 | 层级 |
|---|---|---|
| 默认只监听本机 | 不要随意改成 0.0.0.0 |
社区共识 |
OLLAMA_HOST |
改监听地址的环境变量；若要局域网访问，务必配合防火墙，不要暴露公网（本地 API 无鉴权） | 社区共识 |
| 云模型 | xxx:cloud 模型在 Ollama 云端运行，数据会离开本机；需要隐私时只用本地模型 |
有据可查（文档区分 Cloud 与 Local） |
7. 常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 速度极慢 | 显存不够，模型部分跑在 CPU | 换更小模型或更低量化；ollama ps 查看 GPU/CPU 占比 |
| 回答被截断/忘记前文 | 上下文长度太小 | 用 Modelfile 调大 num_ctx |
| Docker 里的 Open WebUI 连不上 | 容器内 127.0.0.1 不是宿主机；宿主 Ollama 也可能只监听回环 | 先核对 Docker 网络模式、宿主监听与容器可达性；host.docker.internal:11434 需满足这些条件（见 Open WebUI 入门：安装、模型连接与知识库） |
| Agent 工具调用失败 | 小模型工具调用能力弱 | 换支持工具调用、体量更大的模型 |
某工具只认 gpt-4o 这类名字 |
工具写死模型名 | ollama cp 改名 |
8. 本篇无法核实/需谨慎的点
- 模型库中具体模型的可用标签与效果。
ollama launch支持的工具列表随版本变化。- 各操作系统上 GPU 加速支持的细节（AMD、Intel、Apple Silicon 的 MLX 后端等）。
图解与代码示例中的相关教程：Open WebUI 入门：安装、模型连接与知识库；SillyTavern 酒馆图解：连接、角色卡、世界书与提示词。
小白练习：把本文流程逐项走通
练习目标：下载一个合适的本地模型，并确认它真的在本机运行。
上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。
-
从官网安装后重新打开终端，运行 ollama --version。版本与原稿示例可能不同，模型标签以当前模型库为准。
-
打开官方模型库，选择与电脑资源相符的本地标签，记录完整名字；不要选带 cloud 的标签做离线测试。
-
先运行 ollama pull 加完整标签，等待下载结束；再运行 ollama list 确认模型已经在本地。
-
运行 ollama run 加同一标签，发送一个简单问题，等输出结束。
-
在另一个终端运行 ollama ps 查看加载状态。退出对话按当前 CLI 帮助中的方式操作，Ctrl+C 可以中断正在生成的输出。
-
接 API 前先核对原生接口与兼容接口路径。Modelfile 保存为准确文件名，创建新模型后再单独测试。
本机 HTTP、SDK 和云凭据分开看
【有据可查】官方 OpenAI compatibility 的本机示例中，Python/JavaScript 客户端填写 api_key='ollama' 或 apiKey: 'ollama'，因为客户端要求一个值；同页 HTTP curl 示例没有认证头。Ollama Authentication 也说明本机 API 不需要认证。
【有据可查】这一结论只适用于本机 Ollama 接口；直接请求 https://ollama.com 的云 API 需要真实密钥。在本机服务中选择云模型也会把推理交给云端，不能因为 Base URL 是 localhost 就认定内容从未离开本机。
【有据可查】Ollama 默认绑定 127.0.0.1:11434。Docker 容器访问要再检查宿主监听和网络模式；不要为了排错把无鉴权的本机 API 直接公开到公网。
核对来源：Ollama 官方：OpenAI compatibility；Ollama 官方：Authentication；Ollama 官方：FAQ。