过去一年，开源大模型的参数规模从 7B 一路推进到 70B、110B 乃至 MoE 架构的数百 B 级别，量化技术把 70B 模型压缩到单张 24GB 显卡可运行的范围，推理框架的迭代周期以周为单位。对开发者而言，"本地部署"已经从极客玩具变成了可落地的工程选项：数据不出内网、推理成本可控、可以自由微调和改造。但真正动手时会发现，从 Hugging Face 下载权重到稳定跑起一个能用的服务，中间横亘着显存规划、量化格式选择、推理框架适配、并发吞吐调优等一系列具体问题。本文按工程流程梳理这条链路，并给出可直接复用的配置与代码。

一、先想清楚：本地部署的边界在哪里

在动手之前需要明确本地部署的能力边界，避免选型阶段的反复。

适合本地的场景：敏感数据推理（合同审阅、代码库问答）、离线环境、需要频繁调用且调用量稳定的批处理任务、模型微调与蒸馏实验、教学与研究。

不适合的场景：需要 GPT-4 级别复杂推理的高难度任务、超长上下文（128K 以上）的高并发服务、对首 token 延迟极度敏感的交互产品。消费级硬件上，7B-14B 模型在量化后可以做到可用的交互体验，70B 模型在单张 24GB 卡上只能以较低速度运行，不适合多用户并发。

硬件方面，经验值是：FP16 精度下每 10 亿参数约需 2GB 显存，4-bit 量化后约需 0.6-0.7GB。也就是说 7B 模型 4-bit 量化约占 5GB，14B 约占 9GB，32B 约占 20GB，70B 则需要 40GB 以上，单卡 24GB 必须依赖 CPU 卸载或双卡。内存（RAM）同样重要，模型加载时的权重转换会占用大量系统内存，建议不低于显存的两倍。

二、模型与量化格式的选择

模型来源

主流权重托管在 Hugging Face 与 ModelScope。国内网络环境下 ModelScope 的下载体验更稳定，且提供 modelscope CLI 工具：

pip install modelscope
modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./models/qwen2.5-7b-instruct

Hugging Face 侧可使用 huggingface-cli download，配合 HF_ENDPOINT=https://hf-mirror.com 环境变量走镜像。注意校验下载完整性，大文件断点续传失败是常见问题，建议用 --resume-download 并核对 *.safetensors 的 sha256。

量化格式

当前生态里主要有三条路线：

GGUF（llama.cpp 生态）：CPU/GPU 混合推理友好，量化粒度细（Q2_K 到 Q8_0），单文件分发方便，适合个人设备和 CPU 推理。缺点是 GPU 上的吞吐不如专用框架。

AWQ / GPTQ：GPU 推理专用，4-bit 量化后精度损失较小，需要 vLLM、AutoAWQ 等框架配合。AWQ 对激活值做保护，通常比 GPTQ 更稳。

bitsandbytes（NF4）：transformers 原生支持，加载最省事，但推理速度不如前两者，适合实验阶段。

一个实用建议：先用 GGUF 的 Q4_K_M 版本快速验证模型能力是否满足需求，确认后再针对生产环境选择 AWQ + vLLM 或 GGUF + llama.cpp 的正式方案。

三、三条部署路径与可运行代码

路径一：Ollama——最快跑通

Ollama 把模型下载、量化、服务化封装成一条命令，适合快速验证和本地开发：

# 安装后直接拉取并运行
ollama run qwen2.5:7b

# 作为服务常驻，暴露 OpenAI 兼容接口
OLLAMA_HOST=0.0.0.0:11434 ollama serve

调用侧完全兼容 OpenAI SDK：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "用 Python 写一个带重试的 HTTP 客户端"}],
    temperature=0.3,
)
print(resp.choices[0].message.content)

自定义模型可以通过 Modelfile 固化系统提示词和参数：

FROM ./models/qwen2.5-7b-instruct.Q4_K_M.gguf
PARAMETER temperature 0.2
PARAMETER num_ctx 8192
SYSTEM 你是一名严谨的代码审查助手，只输出可执行的建议。

ollama create my-reviewer -f Modelfile 之后即可用 my-reviewer 作为模型名调用。Ollama 的局限在于并发调度能力弱，适合单人或小团队使用，不适合作为生产网关。

路径二：llama.cpp——最可控的 GGUF 推理

需要精细控制上下文长度、批大小、GPU 层数时，直接使用 llama.cpp：

# 编译（CUDA 版）
git clone https://github.com/ggerganov/llama.cpp && cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j

# 启动 OpenAI 兼容服务
./build/bin/llama-server \
  -m ./models/qwen2.5-7b-instruct.Q4_K_M.gguf \
  -c 8192 -ngl 99 -np 4 --host 0.0.0.0 --port 8080

关键参数：-ngl 控制卸载到 GPU 的层数，设为 99 表示尽量全部卸载；-np 是并行槽位数，影响并发；-c 是总上下文，注意 -c 会被 -np 分摊，多并发时需要相应放大。启动后访问 http://localhost:8080 有内置的 Web UI，接口路径为 /v1/chat/completions。

llama.cpp 的优势是内存管理透明、支持 CPU+GPU 混合、量化选择丰富。在只有 CPU 的机器上，Q4_K_M 的 7B 模型在 16 核服务器上大约能跑到 8-15 token/s，作为内部工具完全够用。

路径三：vLLM——面向吞吐的生产方案

需要服务多用户、追求吞吐时，vLLM 的 PagedAttention 和连续批处理是当前事实标准：

pip install vllm
vllm serve ./models/qwen2.5-7b-instruct-awq \
  --quantization awq \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.9 \
  --max-num-seqs 32 \
  --port 8000

--gpu-memory-utilization 控制 KV Cache 的预留比例，0.9 是常见起点，显存紧张时下调到 0.8。--max-num-seqs 决定并发批大小，与显存和延迟目标相关。vLLM 同样暴露 OpenAI 兼容接口，切换成本低。

一个容易踩的坑：AWQ 权重需要与模型架构匹配，部分新模型发布后要等 vLLM 版本更新才支持，部署前务必核对 vLLM release notes 中的支持列表。

四、几个值得动手的源码级玩法

改造采样逻辑。llama.cpp 的 examples/main 和 common/sampling.cpp 结构清晰，可以加入自定义的 logit 处理器，比如强制 JSON 输出、屏蔽特定 token、按语法约束生成。这比在应用层做后处理可靠得多。

给 Ollama 加自定义后端。Ollama 的 llm/server.go 中定义了推理后端的接口，社区已有接入 TensorRT-LLM 的尝试。阅读这部分代码是理解"推理服务化"分层设计的好材料。

用 llama.cpp 的 grammar 做结构化输出。它支持 GBNF 语法约束，可以直接约束模型输出为合法 JSON：

root   ::= object
object ::= "{" ws (string ":" ws value ("," ws string ":" ws value)*)? ws "}"
value  ::= object | array | string | number | ("true" | "false" | "null")

配合 --grammar-file 参数，模型输出会被硬约束在语法内，对需要稳定解析的自动化流程非常实用。

投机解码（speculative decoding）。llama.cpp 支持用一个小模型做 draft、大模型做 verify：-md draft.gguf --draft-max 8。在代码补全这类高可预测场景下，实测能有 1.5-2