Ollama 本地模型服务指南 · Dylan AI Agent Nexus
Run, Manage and Call Local LLMs via Ollama
定位与价值
Ollama 是一个轻量的本地大模型运行与管理服务，支持在本机/私有服务器上拉取并运行多种开源模型（如 Llama、Qwen、Mistral 等），通过统一的 HTTP API 提供推理能力，契合我们的“本地化部署、安全与数据主权”的总体原则。
运行与模型管理（概念）
- 服务进程：启动后台服务后，默认监听本机端口（可配置），对外暴露 HTTP API。
- 模型仓库：使用命令拉取模型镜像到本地（如 llama3、qwen2、mistral）。
- 生命周期：首次调用会加载模型到内存；空闲可由 keep_alive 控制释放与保活。
- 多平台：支持 CPU/GPU 推理，GPU 可显著提升推理吞吐与延迟表现。
本页不涵盖安装步骤，仅介绍原理、用法与注意事项。安装与环境请参考“部署与配置”相关页面。
API 基础
- 生成接口：
POST /api/generate（单轮、补全式）。 - 聊天接口：
POST /api/chat（多轮、messages 结构）。 - 流式输出：通过
stream: true以逐步返回增量结果；客户端需拼接。 - 选项：
options支持temperature、top_p、num_predict、stop、seed、num_ctx等。 - 结构化输出：可使用
format: "json"（部分模型与版本支持）获得更规整的 JSON 文本。
示例：补全式生成（/api/generate）
curl -X POST http://localhost:11434/api/generate -H "Content-Type: application/json" -d '{"model":"llama3","prompt":"给出3条关于数据治理的金句","stream":false,"options":{"temperature":0.6}}'
请求体关键字段：
- model：模型名称，如
llama3、qwen2。 - prompt：纯文本提示词。
- stream：是否流式返回（
false为整块返回）。 - options：推理参数，如
temperature、num_predict、stop等。
示例：对话式生成（/api/chat）
curl -X POST http://localhost:11434/api/chat -H "Content-Type: application/json" -d '{"model":"qwen2","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"把以下要点整理成政策解读提纲：数据主权、安全合规、本地化部署价值。"}],"stream":true}'
- messages：与主流 Chat API 一致，支持
system/user/assistant角色。 - 流式：
stream=true时，响应为多段增量块；客户端需读取并拼接。 - 多模态：部分多模态模型支持图片输入（需按模型说明提供 image 字段或 base64 数据）。
参考实现：Python requests
import requests
payload = {
"model": "llama3",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "为《隐私合规白皮书》写一个一段式摘要"}
],
"stream": False,
"options": {"temperature": 0.5}
}
res = requests.post("http://localhost:11434/api/chat", json=payload, timeout=120)
res.raise_for_status()
print(res.json())
模型管理（命令概念）
- 拉取模型：
ollama pull llama3、ollama pull qwen2。 - 列出模型：
ollama list。 - 测试运行：
ollama run llama3（交互式）。 - 服务监听：设置
OLLAMA_HOST=0.0.0.0:11434对外提供 API（配合内网/反向代理与访问控制）。
请在受控的私网环境下暴露端口；生产环境建议放置在零信任网段或受反向代理保护，并启用访问鉴权。
自定义 Modelfile（原理）
通过 Modelfile 可以基于已有模型定制系统提示词、参数与模板，生成一个新命名的可复用模型镜像。
# 示例 Modelfile（概念）
FROM llama3
SYSTEM You are a domain expert assistant for enterprise data governance.
PARAMETER temperature 0.6
PARAMETER num_ctx 4096
构建后即可通过 model 指定该自定义模型，统一风格与输出质量。
性能与 GPU 建议
- 上下文窗口：
num_ctx越大越耗显存；根据场景权衡长度与吞吐。 - 推理参数：控制
temperature/top_p/repeat_penalty/stop以稳定输出风格。 - 并发与保活：用
keep_alive保持模型热身，减少冷启动延迟。 - GPU 资源：优先使用 GPU；监控显存占用与负载，必要时分配多卡或降精度权重。
安全与合规注意事项
- 网络边界：仅在可信网络开放；外网访问需网关鉴权与审计。
- 数据最小化：提示词与业务数据避免包含敏感原文；必要时做脱敏/加密。
- 审计与配额：记录调用日志（时间、调用方、耗时、返回大小）；设置并发与速率上限。
与本平台的集成
- 统一配置：在平台的模型配置处填入 Ollama 服务地址（如
http://localhost:11434）。 - API 适配：按
/api/chat或/api/generate的 JSON 结构发起调用，遵循上文参数规范。 - 多模型共存：可同时部署多个本地模型与云端模型，通过配置选择与路由。
故障排查（思路）
- 无法连接：检查服务是否监听、端口与防火墙策略；确认
OLLAMA_HOST设置。 - 加载缓慢：首轮加载模型较慢属正常；开启保活或预热。
- 显存不足：选择更小尺寸权重或降低
num_ctx；必要时升级显存。 - 输出异常：适当降低
temperature，设置stop，或启用format: "json"。