一、文档定位

汇总 Ollama 工具使用、LLaMA 系列模型本地运行、模型拉取 / 自定义构建、量化配置、显存调度、API 调用、Docker 部署、参数调优、QLoRA 微调与 Ollama 衔接、多模型管理等实操内容，偏向工程落地手册。

说明：文中模型 tag 尽量贴近 Ollama Library 常见写法（如 llama3.1:8b-instruct-q4_K_M）。库会随版本增减 tag，拉取前可用 ollama pull / 官网页面再确认一次。

二、Ollama 基础介绍

定义：轻量化开源大模型本地运行工具，统一完成下载、量化权重管理、加载与推理，覆盖 LLaMA、Qwen、Mistral 等开源模型，屏蔽 CUDA、依赖安装、显存分配等底层细节。

核心优势

• 跨平台：Windows / macOS / Linux；支持 NVIDIA、AMD（视平台与后端）、以及 CPU 推理
• 内置 GGUF 量化生态：常见档位包括 FP16、Q8_0、Q6_K、Q5_K_M、Q4_K_M、Q3_K 等
• 自带 RESTful API：提供 OpenAI 兼容接口，可对接 LangChain、FastAPI 等
• Modelfile 自定义：可固化系统提示词、上下文窗口、温度、最大生成长度等默认参数

三、Ollama 基础命令全集（LLaMA 模型运维）

3.1 模型拉取与运行

# 拉取 LLaMA 3.1 8B Instruct（库内常用默认/别名写法）
ollama pull llama3.1:8b

# 直接启动对话
ollama run llama3.1:8b

# 指定量化精度（更贴近库内完整 tag）
ollama pull llama3.1:8b-instruct-q4_K_M
ollama pull llama3.1:8b-instruct-q5_K_M
ollama pull llama3.1:8b-instruct-q8_0

3.2 常用运维命令

ollama list                              # 查看本地已下载模型
ollama stop llama3.1:8b                  # 停止运行中的模型，释放显存
ollama rm llama3.1:8b                    # 删除本地模型
ollama ps                                # 查看当前已加载模型
ollama show llama3.1:8b                  # 查看模型详情（参数、量化、模板等）
ollama show llama3.1:8b --modelfile      # 导出/查看对应 Modelfile

注意：没有 ollama info，查看模型信息请用 ollama show。

四、GGUF 量化格式与 LLaMA 精度选型（显存适配核心）

Ollama 本地跑 LLaMA 时，权重以 GGUF 形式管理。下表为 LLaMA 3.1 8B 量级 的权重显存/内存粗算（不含长上下文 KV Cache，实际占用会更高）：

量化档位	权重占用粗算（8B）	适用场景	优缺点
FP16	约 16GB+	高端显卡、追求尽量保真	精度最高，显存压力最大
Q8_0	约 9～10GB	中高端 N 卡	损耗很小，占用仍偏高
Q5_K_M	约 6～7GB	性价比常用档	精度 / 体积较均衡
Q4_K_M	约 5～6GB	8GB 显卡常见选择	日常对话够用，细节略损
Q3_K	约 3.5～4.5GB	低显存 / 偏 CPU 场景	更省资源，长文本与复杂推理掉点更明显

补充要点：

1. 上表主要是权重体积；真正跑起来还要加 KV Cache，随 num_ctx、batch、并发近似线性增长。
2. 「4GB 显存可跑 Q3」通常默认 短上下文 + 部分层卸载 / CPU 协作，不是任意 num_ctx 都稳。
3. 经验参考：8B 模型在 16GB 显存 上跑 Q5_K_M + 中等上下文 通常较从容；8GB 更常见 Q4_K_M + 控制 num_ctx。

五、Modelfile 自定义 LLaMA 模型（个性化定制）

通过 Modelfile 可封装专属实例：固定角色人设、上下文窗口、生成参数、系统 Prompt。

编写 Modelfile

# 基础模型来源（可用本地已有模型名，或 GGUF 文件路径）
FROM llama3.1:8b-instruct-q4_K_M

# 固定系统提示词
SYSTEM 你是专业大模型技术助手，回答简洁严谨。

# 全局生成参数
PARAMETER temperature 0.7
PARAMETER num_ctx 8192      # 上下文窗口（token）
PARAMETER num_predict 1024  # 单次最大生成 token 数

构建并运行

ollama create my-llama31 -f Modelfile
ollama run my-llama31

六、Ollama OpenAI 兼容 API 调用（程序对接）

6.1 接口基础地址

• OpenAI 兼容：http://localhost:11434/v1/chat/completions
• 原生接口（可选）：http://localhost:11434/api/chat

请求体与 OpenAI Chat Completions 基本对齐，Python 示例：

import requests

url = "http://localhost:11434/v1/chat/completions"
data = {
    "model": "llama3.1:8b-instruct-q4_K_M",
    "messages": [{"role": "user", "content": "讲解 FFN 原理"}],
    "temperature": 0.6,
}
res = requests.post(url, json=data, timeout=120)
res.raise_for_status()
print(res.json()["choices"][0]["message"]["content"])

适用场景：RAG、FastAPI 后端、LangGraph / Agent 项目本地接模型。

七、Docker 部署 Ollama（服务端离线部署方案）

7.1 容器启动（GPU 直通）

# 挂载模型目录，开启 NVIDIA GPU，并允许非本机访问
docker run -d \
  --name ollama \
  --gpus all \
  -v ollama_data:/root/.ollama \
  -p 11434:11434 \
  -e OLLAMA_HOST=0.0.0.0 \
  ollama/ollama

容器内拉模型示例：

docker exec -it ollama ollama pull llama3.1:8b-instruct-q4_K_M

7.2 远端访问配置

默认监听本机回环地址。若需局域网 / 跨机调用：

1. 设置 OLLAMA_HOST=0.0.0.0（Docker 里用 -e 注入，如上例）
2. 放行宿主机 11434 端口
3. 生产环境务必叠加鉴权 / 反向代理 / 防火墙，不要裸奔公网

八、LLaMA 配套进阶实操知识点

自定义 GGUF 导入 Ollama

本地用 llama.cpp 等工具，把私有权重或 LoRA 合并后的全量权重 转成 GGUF，再在 Modelfile 里：

FROM ./my-model-q4_k_m.gguf

适配「QLoRA 微调 → 合并 → 转 GGUF → Ollama 部署」链路。

显存 / 性能相关参数

参数	含义（易混点已纠正）
num_gpu	卸载到 GPU 的层数（对应 llama.cpp 的 n_gpu_layers 语义），不是「用几张 GPU」
num_ctx	上下文窗口长度；越大，KV Cache 越吃显存
num_thread	CPU 侧推理线程数
numa	多路 CPU / NUMA 场景下的内存访问优化开关

上下文窗口拓展

增大 num_ctx 可支持更长上下文，但会同步抬高 KV Cache 占用。模型本身若支持 RoPE 外推 / 缩放，才能更好做超长上下文；只改 num_ctx 不等于质量无损拉长。

多模型管理

可同时下载多个规格（如 8B / 70B）与多个量化档位，按需 run / stop 加载释放；同一模型不同 tag 对应不同量化或模板，不会自动互相替代。

九、QLoRA 量化与 GGUF 量化核心区别（微调 + 部署）

在 LLaMA 本地化落地中，QLoRA 与 GGUF 属于不同阶段、不同用途的技术：前者服务微调训练，后者服务推理部署，不可混为一谈。

9.1 核心定位与适用阶段

1. QLoRA 量化（训练微调阶段）

QLoRA 是基于 bitsandbytes 等实现的训练期量化方案，典型做法是将基座权重以 4bit（如 NF4）+ 双重量化 加载，冻结主干，只训练少量 LoRA 适配器，从而在消费级显卡上微调 7B/8B/13B 乃至更大模型。
产出通常是 LoRA 适配器（体积小），一般需要与基座合并（或按推理框架支持的方式加载适配器）后，再进入部署流程。
说明：工程上也会见到 8bit 加载 + LoRA，但那更常称为 8bit LoRA，严格意义上的 QLoRA 主打 4bit 路线。

2. GGUF 量化（推理部署阶段）

GGUF 是 llama.cpp 生态的权重封装与推理格式（替代早期 GGML），用于离线推理，不承担反向训练。
支持 Q2_K、Q3_K、Q4_K_M、Q5_K_M、Q8_0、FP16 等多档压缩。Ollama、llama.cpp 等工具原生适配。
需要强调：GGUF 是 Ollama / llama.cpp 路线的主流格式，但不是「LLaMA 本地部署的唯一格式」；还有 safetensors（Transformers / vLLM 等）、GPTQ、AWQ、EXL2 等部署形态。

9.2 核心特性对比

对比维度	QLoRA 量化	GGUF 量化
使用阶段	微调 / 参数高效训练	推理 / 本地或服务部署
核心作用	降低微调显存门槛	压缩体积、降低推理显存/内存
输出产物	LoRA 适配器（通常几十～几百 MB）	完整可推理权重（.gguf）
是否支持训练	支持（训练适配器）	不支持训练更新
与 Ollama 关系	不能直接当最终模型用；需合并/转换后再导入	Ollama 原生支持拉取与加载
精度特点	训练期低比特加载；效果取决于数据、超参与是否充分训练	静态量化，档位选定后推理侧基本定型
硬件倾向	训练侧通常依赖 CUDA 等加速环境	推理可 N 卡 / A 卡 / CPU（能力与速度差异大）

9.3 完整工程链路（二者衔接）

常见落地流程：

原始基座 → QLoRA 微调 → 合并 LoRA 与基座 → 转为 GGUF → Ollama / llama.cpp 部署推理

二者是前后衔接，不是互相替代：QLoRA 负责「低成本调教」，GGUF 负责「在 Ollama 生态里高效跑起来」。

9.4 选型避坑

1. 只做对话 / RAG 本地推理：不必上 QLoRA，直接用 Ollama 库内 GGUF 量化模型即可。
2. 要基于私有数据定制能力：用 QLoRA（或同类 PEFT）微调，再合并并转 GGUF 后导入 Ollama。
3. 不要拿 GGUF 当训练集做反向传播；它不是为训练图设计的格式，强行「当可训练权重」会踩梯度 / 工具链不匹配等问题。

十、常见问题优化总结

现象	优先处理
生成卡顿 / 吞吐低	换更低量化档、减小 num_ctx、提高 num_gpu（GPU 层数）、检查是否落 CPU
显存溢出 OOM	换 Q4_K_M 及以下、减小 num_ctx、ollama stop 释放闲置模型、降低并发
外网/局域网访问不到容器 Ollama	容器内设置 OLLAMA_HOST=0.0.0.0，并检查端口映射与防火墙
微调模型进不了 Ollama	LoRA 合并基座 → 导出 GGUF → Modelfile FROM 本地文件 → ollama create
ollama info 报错	改用 ollama show <model>

十一、文档收尾

Ollama 是 LLaMA 系列在个人学习、离线 RAG、私有化小服务场景下很省事的本地推理方案，能较好衔接「HuggingFace / PEFT 微调 → GGUF → API / Agent」链路。
命令、tag、默认量化会随官方版本变化，以当前 ollama CLI 与模型库页面为准。