← Frontend / AI

AI 模型本地部署

AI 模型本地部署指南,涵盖模型选型、硬件估算、量化、Ollama、llama.cpp、vLLM、LoRA 与 RAG

目录


0. 先记住这 8 句话

  1. 本地部署的主要价值是数据边界、可控性、离线能力和稳定成本,不等于“永远比云 API 便宜”。
  2. 模型能否运行,先看权重内存;能否跑长上下文和高并发,还要看KV Cache与运行时开销。
  3. 参数量相同,不同架构、精度、量化格式和上下文长度的资源需求仍可能差很多。
  4. 蒸馏是重新训练一个更小的学生模型;量化是用更低精度表示同一模型的权重。两者不是一回事。
  5. 量化通常显著省内存,但不保证在每种硬件和后端上都更快。
  6. 个人聊天、学习和轻量应用优先考虑 Ollama;高吞吐 API、多 GPU 和生产服务优先考虑 vLLM。
  7. 本地运行只代表推理发生在本机;若客户端、插件、日志或遥测仍向外传输数据,就不能声称“数据绝不出网”。
  8. 先用真实任务做小规模评测,再决定是否升级模型;参数更大不等于对我的任务一定更好。
我的记忆主线:场景 → 模型 → 内存 → 上下文 → 引擎 → 接口 → 评测 → 安全。

1. 我为什么要本地部署

1.1 适合本地部署的场景

核心价值:

  • 数据边界可控:适合内部代码、合同、病历等敏感数据,但仍需做好权限、日志和网络隔离。
  • 离线可用:弱网、断网或内网环境仍可推理。
  • 延迟更稳定:少了公网往返,但最终速度仍由本机算力、模型大小和上下文长度决定。
  • 可深度定制:可以更换模型、控制采样参数、挂载 LoRA、构建私有 RAG,或提供内部 API。
  • 边际调用成本低:硬件购置后,频繁推理不再逐 token 付费,但电费、折旧、运维和人力并不为零。

1.2 不一定适合本地部署的场景

场景 更合适的选择 原因
偶尔使用,调用量很小 云 API 无需承担硬件和维护成本
需要最强闭源模型能力 云 API 本地开源模型未必达到同等效果
流量波动极大 云服务或混合部署 弹性扩缩容更容易
严格内网、稳定高频调用 本地或私有云 数据和资源边界更容易控制
个人学习、开发、离线助手 Ollama / llama.cpp 上手快,资源要求相对可控
易错点:“本地部署后不限次数”只表示没有云端按 token 账单,不代表没有吞吐上限。GPU、内存带宽、并发和散热仍会限制服务能力。

1.3 成本要看总拥有成本

总拥有成本(TCO)至少包括:硬件采购、折旧、电费、机房或散热、维护、监控、升级和工程人力。

我的判断方式:

本地月均成本 ≈(硬件价格 ÷ 预计使用月数)+ 电费 + 运维成本
云端月均成本 ≈ 输入 token 费用 + 输出 token 费用 + 其他服务费

不要把某个时间点的 API 单价写死在长期笔记里;实际决策时查看供应商最新价格页。


2. 如何读懂模型名称

2.1 通用拆解方法

Qwen3-14B-Instruct-AWQ
│     │    │        └─ 量化方法:AWQ
│     │    └────────── 指令微调版
│     └─────────────── 参数规模:约 140 亿
└───────────────────── 模型家族与代际

阅读顺序:先看家族与版本,再看参数量,然后看任务类型,最后看量化/精度与上下文说明。

2.2 常见任务后缀

标识 含义 我的使用判断
Base 预训练基础模型 适合继续训练或研究,通常不直接聊天
Instruct 指令微调模型 通用问答首选
Chat 对话微调模型 常见于较早命名体系;实际能力仍看模型卡
Coder 代码专项 代码生成、补全、解释和修复
Math 数学专项 数学推理、证明和公式任务
VL / Vision 视觉语言模型 图像理解;还要确认推理框架是否支持视觉组件
Audio 音频相关 可能是 ASR、音频理解或语音对话,必须看模型卡
Embedding 向量模型 用于检索与 RAG,不是聊天模型
Reranker 重排序模型 对检索结果再次打分,提高 RAG 召回质量

2.3 常见结构与优化标识

  • MoE:Mixture of Experts,混合专家。每个 token 只激活部分专家,但完整权重通常仍需存储或分布到设备上。
  • Distill:蒸馏模型。名称中通常同时出现老师模型家族和学生基座。
  • AWQ / GPTQ:常见的权重量化方法,通常面向 GPU 推理。
  • GGUF、Q4_K_M、Q8_0:llama.cpp 生态常见文件/量化标识,适合 CPU、Apple Silicon 和多种本地后端。
  • FP16 / BF16 / FP8 / INT8 / INT4:权重或计算所采用的数值精度;不能仅凭名字推断所有算子都用同一种精度。

2.4 名字不能告诉我的信息

模型名通常不会完整告诉我:

  • 最大上下文是否为原生长度,还是通过 RoPE 扩展;
  • Chat Template(对话模板)是什么;
  • 是否允许商用、再分发或提供托管服务;
  • 工具调用、结构化输出、多模态是否被当前后端完整支持;
  • 真实显存、吞吐和准确率。
Tip:下载前至少读三处:模型卡、许可证、推理框架兼容性说明。

3. 选模型前先估算硬件

3.1 权重内存的粗略公式

理论权重大小 ≈ 参数量 × 每参数位数 ÷ 8

以 7B 稠密模型为例:

精度 理论权重大小 实际说明
FP32 约 28 GB 几乎不用于个人推理
FP16 / BF16 约 14 GB 还未计算 KV Cache 与框架开销
INT8 约 7 GB 还会有 scale、元数据等额外开销
4-bit 约 3.5 GB 实际文件和运行占用通常略高

3.2 为什么“模型文件能放进显存”仍可能 OOM

运行时内存通常由以下部分组成:

总占用 ≈ 模型权重 + KV Cache + 临时张量/工作区 + 运行时开销

其中,KV Cache保存注意力层历史键值,通常随以下因素增加:

  • 上下文长度;
  • 并发序列数;
  • 层数、隐藏维度和 KV Head 数;
  • KV Cache 的数据类型。
易错点:上下文窗口从 8K 调到 32K,不只是“允许输入更多文字”,也可能明显增加 KV Cache;高并发时影响更大。

3.3 GPU、CPU 与 Apple Silicon

硬件 优点 限制 适合我在什么时候用
NVIDIA GPU 生态成熟、吞吐高 显存价格高,依赖 CUDA 训练、vLLM、批量推理
CPU 通用、无需独显 生成速度通常较慢 小模型、低频、离线实验
Apple Silicon 统一内存,可容纳较大模型 内存被系统与 GPU 共用;生产生态不同 Mac 个人本地推理

经验原则:不要把“统一内存容量”全部算给模型;给操作系统、客户端和上下文缓存留出余量。

3.4 真正应该测的 4 个指标

  1. TTFT(Time to First Token):首 token 延迟,决定“多久开始回答”。
  2. 输出速度:通常用 tokens/s 表示,决定回答生成速度。
  3. 吞吐:单位时间处理的总 token 或请求量,生产服务尤其重要。
  4. 峰值内存:在目标上下文和并发下是否稳定、不 OOM。

4. 满血、MoE、蒸馏与量化

4.1 四个概念放在一起比较

概念 改变了什么 主要收益 主要代价
稠密模型 每层大部分参数都参与计算 架构直接、部署成熟 大模型计算量高
MoE 每个 token 路由到部分专家 总参数大、单 token 激活较少 权重存储、通信和路由更复杂
蒸馏 训练一个更小的学生模型 模型本身变小 能力不会完整继承
量化 降低权重/激活的表示精度 内存与文件体积下降 可能损失质量,速度依赖硬件与内核

4.2 DeepSeek-R1 案例

DeepSeek-R1 模型卡给出的规格是:671B 总参数、每 token 约 37B 激活参数、128K 上下文。它是 MoE,不应简单等同于 671B 稠密模型的每-token 计算量;但部署时仍要考虑完整权重的存储和分布。DeepSeek-R1 官方模型卡

蒸馏版包括:

  • Qwen 基座:1.5B、7B、14B、32B;
  • Llama 基座:8B、70B。
DeepSeek-R1-Distill-Qwen-32B
│          │       │    └─ 学生模型参数规模:32B
│          │       └────── 学生基座:Qwen
│          └────────────── 蒸馏路线
└───────────────────────── 老师能力来源:DeepSeek-R1
纠正常见说法:“激活 37B”不等于只需加载 37B 权重;“蒸馏版保留大部分能力”也不是对所有任务都成立,必须看具体基准和真实任务。

4.3 如何选择蒸馏规模

  • 1.5B–8B:快速、轻量,适合摘要、简单问答和低资源设备;复杂推理稳定性有限。
  • 14B:个人设备上的均衡档,质量通常明显好于小模型。
  • 32B:更强推理与代码能力,但 4-bit 权重本身已约 16 GB,运行时还需额外空间。
  • 70B:更高质量,但个人单卡部署门槛高,常需要大内存或多卡。

5. 精度与量化原理

5.1 常见数值格式

类型 每个数的位宽 特点 常见用途
FP32 32 bit 范围和有效精度较高 训练中的部分状态、数值敏感计算
FP16 16 bit 尾数比 BF16 多,指数范围较小 GPU 训练与推理
BF16 16 bit 指数位与 FP32 相同,范围大、尾数较短 现代训练与推理
INT8 8 bit 需要 scale,可能还需要 zero-point 压缩推理
4-bit 4 bit 极省内存,对算法和内核更敏感 本地推理、QLoRA
概念修正:BF16 的名称来自 Brain Floating Point,由 Google Brain 提出;不是因为它“模拟人脑只关心范围”。它的工程价值在于保留了接近 FP32 的指数范围。

5.2 线性量化的核心

量化把浮点值映射到有限的整数格点,再在计算时反量化或由专用内核直接运算。

常见形式:

q = round(x / scale) + zero_point
x̂ = (q - zero_point) × scale
  • x:原始浮点值;
  • q:量化后的整数;
  • x̂:反量化近似值;
  • scale:缩放因子;
  • zero_point:零点,非对称量化中常见。

量化误差来自“连续值被舍入到离散格点”。不同方法会按 tensor、channel 或 group 计算缩放参数,并可能用校准数据减少误差。

5.3 常见量化生态

方法/格式 常见场景 备注
GGUF K-quants llama.cpp / Ollama,本地 CPU、GPU 混合 Q4_K_M 常是体积与质量的折中起点
AWQ GPU 推理 利用激活统计保护重要权重
GPTQ GPU 推理 典型的训练后权重量化,需要校准思路
bitsandbytes 8/4-bit Transformers、QLoRA 易用,但速度取决于设备和实现
FP8 新一代 GPU 推理 依赖硬件、模型与框架支持

Hugging Face 的量化文档明确指出:量化可以降低内存与计算成本,但实际支持范围和加速效果取决于具体算法与后端。Transformers 量化文档

5.4 QLoRA 是什么

QLoRA的基本思路是:

  1. 以 4-bit 形式加载并冻结基础模型;
  2. 插入少量可训练的 LoRA 低秩矩阵;
  3. 梯度只更新 LoRA 参数;
  4. 训练完成后保存适配器,或在兼容条件下合并权重。
易错点:QLoRA 训练后的适配器不能无条件合并到任意量化文件;基座模型、结构、版本和量化流程必须匹配。

6. Ollama、llama.cpp 与 vLLM 怎么选

6.1 三者定位

工具 核心定位 优势 典型场景
Ollama 本地模型运行与管理工具 安装、拉取、运行、API 一体化 个人聊天、开发、原型
llama.cpp 轻量推理引擎与 GGUF 工具链 跨平台、CPU/多后端、可细调 嵌入式、本地应用、格式转换
vLLM 高吞吐模型服务引擎 连续批处理、多 GPU、OpenAI 兼容服务 团队 API、生产推理

6.2 我的快速决策树

主要目标是什么?
├─ 个人聊天 / 学习 / 原型
│  ├─ 想最快上手 ─────────────→ Ollama
│  └─ 想精细控制 GGUF 与参数 ─→ llama.cpp
├─ 给应用或团队提供高并发 API ─→ vLLM
└─ 既要本地体验又要生产服务
   └─ 开发阶段 Ollama,生产阶段再压测 vLLM

6.3 不用记死吞吐倍数

吞吐会被模型、量化方法、GPU、输入/输出长度、并发、批处理策略和软件版本共同影响。正确做法是用同一模型、同一硬件、同一请求分布进行基准测试。


7. Ollama:个人本地部署实战

7.1 安装与验证

从 Ollama 官方下载页安装对应系统版本,然后验证:

ollama --version

Ollama 本地 API 默认地址通常为:

http://localhost:11434

原生 API 以 /api 为前缀;OpenAI 兼容接口使用 /v1。官方说明见 Ollama API Introduction 与 OpenAI compatibility。

7.2 拉取并运行模型

ollama run <模型名:标签>

示例标签会随模型库变化,先到 Ollama 模型库确认名称、大小、上下文和量化版本,再运行实际命令。

常用管理命令:

ollama list                 # 已安装模型
ollama ps                   # 当前加载模型
ollama show <模型名>        # 模型信息
ollama stop <模型名>        # 从运行状态停止
ollama rm <模型名>          # 删除模型(会释放磁盘空间)

7.3 用 API 验证

curl http://localhost:11434/api/chat \
  -d '{
    "model": "<模型名>",
    "messages": [{"role": "user", "content": "你好,请用一句话介绍你自己"}],
    "stream": false
  }'

OpenAI 兼容客户端通常填写:

Base URL: http://localhost:11434/v1
API Key: 由客户端要求决定;本地默认服务通常不据此鉴权
Model: 已安装的 Ollama 模型名
安全提醒:不要为了远程访问而直接把 11434 端口暴露到公网。需要远程访问时,至少加反向代理、TLS、认证、访问控制和防火墙。

7.4 图形客户端与“联网”

Chatbox、Cherry Studio 等客户端可以连接 Ollama 的本地 API。浏览器扩展或客户端的联网搜索,通常是:

客户端搜索网页 → 抽取内容 → 把内容放进提示词 → 本地模型生成回答

这不代表模型自己获得了互联网访问能力。隐私审计时要同时检查搜索服务、浏览器扩展和客户端日志。

7.5 最小排错顺序

  1. ollama --version:确认安装成功;
  2. ollama list:确认模型已下载;
  3. ollama ps:确认是否已加载、占用什么设备;
  4. 直接用终端运行模型,排除 GUI 客户端问题;
  5. 用 /api/chat 测试,排除 OpenAI 兼容层配置问题;
  6. 缩短上下文、降低并发或换小模型,排查内存不足;
  7. 检查模型模板和多模态支持,避免“能加载但回答异常”。

8. 自定义模型:GGUF、Modelfile 与 LoRA

8.1 GGUF 是什么

GGUF是 llama.cpp 生态使用的模型文件格式,可在单个或分片文件中保存张量与模型元数据,支持多种量化类型。

Ollama 的模型库常使用 GGUF,但 Ollama 官方也支持导入部分 Safetensors 模型或适配器;是否兼容取决于模型架构。Ollama 导入模型文档

8.2 从 Hugging Face 格式转换并量化

当前 llama.cpp 常用流程是:先转换为高精度 GGUF,再单独量化。

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
python3 -m pip install -r requirements.txt

# 第一步:Hugging Face / Safetensors → BF16 GGUF
python3 convert_hf_to_gguf.py /path/to/hf-model \
  --outfile /path/to/model-bf16.gguf \
  --outtype bf16

# 第二步:构建 llama.cpp 后,用量化工具生成 Q4_K_M
./build/bin/llama-quantize \
  /path/to/model-bf16.gguf \
  /path/to/model-q4_k_m.gguf \
  Q4_K_M

工具名称和参数可能随 llama.cpp 更新;执行前以仓库中的 量化说明为准。

8.3 用 Modelfile 注册 GGUF

创建一个名为 Modelfile 的文本文件:

FROM /absolute/path/to/model-q4_k_m.gguf

PARAMETER temperature 0.7
PARAMETER num_ctx 8192

SYSTEM 你是我的本地学习助手。回答简洁、准确,不确定时明确说明。

然后运行:

ollama create my-local-model -f /path/to/Modelfile
ollama run my-local-model

关键理解:Modelfile 是构建说明;GGUF 是模型权重文件。ollama create -f 指向的是 Modelfile,而 FROM 再指向 GGUF。更多字段见 Modelfile Reference。

8.4 导入 LoRA 适配器

示意:

FROM <与训练时完全匹配的基座模型>
ADAPTER /absolute/path/to/adapter

然后:

ollama create my-lora-model -f /path/to/Modelfile
高频故障:基座模型不是训练 LoRA 时使用的同一模型或同一版本,会出现乱码、能力异常或加载失败。对话模板不匹配也会让模型看起来“变笨”。

9. vLLM:生产级 API 服务

9.1 为什么选 vLLM

vLLM 重点解决的是服务效率:连续批处理、KV Cache 管理、多 GPU 并行和 OpenAI 兼容 API。它支持张量并行与流水线并行;多卡部署可使用 --tensor-parallel-size 等参数。vLLM 并行与扩展文档

9.2 直接启动 OpenAI 兼容服务

vllm serve /path/to/model \
  --served-model-name my-model \
  --host 127.0.0.1 \
  --port 6006

多 GPU 示例:

vllm serve /path/to/model \
  --served-model-name my-model \
  --tensor-parallel-size 2 \
  --host 127.0.0.1 \
  --port 6006

客户端配置:

Base URL: http://localhost:6006/v1
Model: my-model

9.3 enforce eager 不是默认必开项

--enforce-eager 会强制 eager 模式,可用于兼容或调试某些场景,但可能放弃 CUDA Graph 等优化。没有明确问题时,不要把它当作所有部署的固定参数。

9.4 上线前的最小生产清单

  • 用真实输入/输出长度压测 TTFT、tokens/s、吞吐和 P95/P99 延迟;
  • 设置最大上下文、最大并发、请求超时和队列上限;
  • 增加鉴权、TLS、访问日志脱敏与限流;
  • 监控 GPU 利用率、显存、KV Cache、请求失败率和 OOM;
  • 固定模型、CUDA、PyTorch、vLLM 与驱动版本;
  • 准备健康检查、优雅重启和回滚方案;
  • 检查模型许可证是否允许目标用途。

10. RAG、微调与提示词的边界

10.1 三种方法分别解决什么问题

方法 最适合解决 不擅长解决
系统提示词 输出格式、角色、流程约束 注入大量新知识、保证事实正确
RAG 私有知识、时效知识、可追溯引用 从根本上改变语言风格和任务能力
LoRA / 微调 风格、固定任务模式、领域行为 自动记住持续变化的知识库

我的选择顺序:先优化提示词;需要外部知识时做 RAG;只有行为模式无法通过提示词稳定获得时,再考虑微调。

10.2 一个最小 RAG 流程

文档 → 清洗/切块 → Embedding → 向量库
用户问题 → Embedding → 召回 → Rerank(可选)
→ 把相关片段放入提示词 → 生成带来源的答案

RAG 的质量瓶颈往往不在生成模型,而在文档解析、切块、召回、重排和引用约束。


11. 安全、评测与常见误区

11.1 本地部署安全检查

  • 服务只监听必要网卡,开发时优先 127.0.0.1;
  • 没有把 Ollama/vLLM 端口直接暴露到公网;
  • GUI 客户端、浏览器插件、遥测和日志策略已审计;
  • API 有鉴权、限流、TLS 和访问控制;
  • 提示词、上传文件和模型输出不记录敏感原文,或已脱敏;
  • 模型与依赖来自可信来源,并校验版本/哈希;
  • RAG 文档权限与用户权限一致,避免越权检索;
  • 对工具调用设置白名单、参数校验和人工确认。

11.2 不要只看公开榜单

我应该建立一个小型私有评测集,例如 30–100 条真实任务,覆盖:

  • 正确答案或评分标准;
  • 典型输入长度与输出格式;
  • 中文、代码、表格、长文等真实分布;
  • 容易幻觉、越权或泄露的边界案例;
  • 响应速度和资源占用。

同一模型比较量化版本时,要固定提示词、采样参数、上下文与评测脚本。

11.3 高频误区速查

误区 更准确的理解
本地模型绝不会泄露数据 还取决于客户端、插件、日志、网络和权限
量化后一定更快 内存通常更省;速度由硬件与内核决定
4-bit 模型显存就是参数量 × 0.5 字节 那只是权重下界,还需 KV Cache 和运行时空间
MoE 激活 37B 就只需加载 37B 完整专家权重通常仍需存储或分布
上下文越大越好 更耗内存、可能更慢,也不保证长文利用率
微调可以直接灌入全部知识 动态、可引用知识通常更适合 RAG
参数越大回答一定越好 还取决于训练、任务、量化、模板和推理参数

12. 我的部署决策清单

12.1 需求

  • 是聊天、代码、视觉、Embedding,还是 API 服务?
  • 是否必须离线?是否涉及敏感数据?
  • 平均输入/输出长度是多少?最大上下文需要多大?
  • 同时有多少用户或请求?
  • 对首 token 延迟、生成速度和准确率的最低要求是什么?

12.2 模型

  • 选择 Base 还是 Instruct?
  • 模型架构是否被目标框架支持?
  • Chat Template 是否正确?
  • 量化方法是否匹配硬件与后端?
  • 许可证允许个人、商用、再分发或服务化吗?

12.3 资源

  • 权重大小是否能放入可用内存/显存?
  • 是否给 KV Cache 与运行时留下余量?
  • 是否按目标上下文和并发实测过峰值占用?
  • 多卡时是否评估了通信与拓扑?

12.4 最终路线

个人零代码体验:Ollama → 选 Instruct 模型 → 真实任务评测

私有知识助手:Ollama/vLLM → Embedding → RAG → 权限与引用

定制任务能力:先提示词与 RAG → 再 LoRA/QLoRA → 导出 → 部署评测

生产 API:vLLM → 压测 → 鉴权/限流/监控 → 灰度与回滚

13. 自测题

问题

  1. 为什么 7B 4-bit 模型的实际运行内存通常高于 3.5 GB?
  2. 蒸馏和量化最本质的区别是什么?
  3. 为什么 MoE 的激活参数不能直接当作部署所需权重大小?
  4. 什么场景更适合 Ollama,什么场景更适合 vLLM?
  5. 为什么“本地模型联网”通常不是模型直接访问互联网?
  6. 当模型缺少公司内部最新知识时,应该先考虑 RAG 还是 LoRA?
展开答案
  1. 3.5 GB 只是 7B × 4 bit 的理论权重大小,还要加 scale/元数据、KV Cache、临时张量和框架开销。
  2. 蒸馏会训练出参数更少的学生模型;量化主要改变既有模型权重的数值表示精度。
  3. MoE 每 token 只计算部分专家,但完整专家权重通常仍需加载、存储或分布在多个设备上。
  4. 个人体验、原型和轻量本地 API 选 Ollama;高并发、多 GPU、生产服务优先评估 vLLM。
  5. 通常由客户端或插件搜索并抽取网页,再把内容作为上下文交给本地模型。
  6. 先考虑 RAG,因为知识会变化、需要更新和引用;LoRA 更适合稳定的行为模式或专项任务能力。

参考资料

注:模型、框架、命令行参数和价格都会更新。执行部署前,以对应版本的官方文档和 --help 输出为准。