Llama 安装与部署

安装与部署

第一步：拿到权重与 Hugging Face 登录

Llama 权重托管在 Hugging Face 上，但多数官方仓库是 gated（需申请）的。流程是：注册 Hugging Face 账号 → 打开对应模型页（例如 meta-llama/Llama-3.1-8B-Instruct）→ 填写用途表单提交 → 等待通过 → 生成一个 read 权限的 access token。之后在机器上登录：

pip install -U "huggingface_hub[cli]"

# 旧版 CLI 写法
huggingface-cli login
# 新版 CLI 已合并到 hf 子命令，行为一致
hf auth login

# 非交互场景（CI / 容器）直接用环境变量，不要写死进代码
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
export HF_HOME=/data/hf_cache

登录后验证能否访问：

hf download meta-llama/Llama-3.1-8B-Instruct --include "config.json" --local-dir ./probe

国内网络下载大文件经常断，建议先装 hf_transfer 并开启，它用 Rust 实现多线程传输并支持断点续传：

pip install hf_transfer
export HF_HUB_ENABLE_HF_TRANSFER=1
# 只下需要的文件，避免把整个仓库（含多种精度副本）全拖下来
hf download meta-llama/Llama-3.1-8B-Instruct --local-dir ./llama-8b

第二步：Ollama（最快跑通）

如果只想先看到模型说话，用 Ollama 最快，它把权重下载、量化选择、模板配置全包了。

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# 启动服务（默认监听 127.0.0.1:11434）
ollama serve

# 拉取并交互式运行
ollama pull llama3.1:8b
ollama run llama3.1:8b

# 查看当前加载的模型与占用
ollama ps
ollama list

第三步：llama.cpp（可控性最强）

llama.cpp 支持纯 CPU、CUDA、Metal、Vulkan 等多种后端，是本地部署里控制粒度最细的选择。从源码编译：

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# NVIDIA 显卡开启 CUDA 后端；纯 CPU 则去掉 -DGGML_CUDA=ON
cmake -B build -DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j $(nproc)

编译产物里几个关键可执行文件：llama-cli（命令行对话）、llama-server（OpenAI 兼容 HTTP 服务）、llama-quantize（量化）、llama-bench（性能基准）。启动服务：

./build/bin/llama-server \
  -m ./models/llama-3.1-8b-instruct-Q4_K_M.gguf \
  -c 8192 \
  -ngl 99 \
  --host 0.0.0.0 --port 8080 \
  --parallel 4

参数含义：-m 指定 GGUF 文件路径；-c 是上下文长度（num_ctx）；-ngl 99 表示把 99 层全部卸载到 GPU（层数不够时按实际层数生效，等价于「全部上 GPU」）；--parallel 是并发槽位，每个槽位独立占用一份 KV cache，调大前先算显存。

第四步：vLLM（高吞吐生产推理）

vLLM 的核心优势是 PagedAttention 与连续批处理（continuous batching），单卡并发吞吐明显高于前两者，适合做后端服务。它直接吃 Hugging Face 原始权重，不需要先转 GGUF。

pip install vllm

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --dtype auto \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.90 \
  --served-model-name llama-local \
  --port 8000

容器化部署时注意要共享内存，否则多进程会报错：

docker run --gpus all --ipc=host \
  -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -e HF_TOKEN=$HF_TOKEN \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --max-model-len 8192

依赖与环境变量清单

export HF_TOKEN=hf_xxx            # Hugging Face 访问令牌
export HF_HOME=/data/hf_cache     # 权重与数据集缓存根目录
export CUDA_VISIBLE_DEVICES=0,1   # 只暴露指定 GPU，多卡/多任务隔离必用
export HF_HUB_ENABLE_HF_TRANSFER=1

常见报错与排查

• CUDA out of memory：先降 --max-model-len 或 -c，再降 --gpu-memory-utilization / --parallel，最后换更低量化档位。用 nvidia-smi 确认是不是别的进程占着显存。
• 下载中断 / 卡在 0%：开启 HF_HUB_ENABLE_HF_TRANSFER=1；确认 HF_HOME 所在磁盘有空间；gated 仓库报 401/403 说明申请未通过或 token 无 read 权限。
• 输出乱码、复读、答非所问：九成是 chat template 不匹配。llama.cpp 用 --chat-template 或模型自带模板；Ollama 用 Modelfile 的 TEMPLATE 段覆盖；vLLM 用 --chat-template 指定。拿原始权重自带的 tokenizer_config.json 里 chat_template 字段作基准最稳。
• 模型加载后仍走 CPU：-ngl 没给，或编译时未开 CUDA 后端。用 llama-bench 或启动日志确认层是否 offload。
• 输出一直不停止：缺少正确的 stop token。检查模板里是否带 <|eot_id|> 这类结束符，并在推理参数里显式设置 stop。