本地部署Llama 3的Python环境搭建全指南

1. 为什么现在还要亲手搭一个本地 Llama 3 的 Python 环境？这真不是在重复造轮子

“本地部署 Llama 3 的 Python 环境搭建”——光看这个标题，你脑子里可能已经浮现出两种人：一种是刚在 Hugging Face 上点开meta-llama/Meta-Llama-3-8B-Instruct页面、手指悬在“Download”按钮上却迟迟不敢点的新人；另一种是刚被公司运维通知“生产环境禁止拉取外部模型权重”，转身就打开 VS Code 开始删.gitignore里venv/那一行的老手。我试过这两种状态，也踩过所有你能想到的坑：从 pip install torch 报错ERROR: Could not find a version that satisfies the requirement torch，到OSError: libcuda.so.1: cannot open shared object file卡在模型加载第一行，再到用llama-cpp-python跑通了但发现 token 生成速度比煮一壶咖啡还慢……这些都不是玄学，全是可定位、可复现、可解决的工程细节。

核心关键词“本地”“Llama”“Python”“环境搭建”背后，藏着三个真实需求：第一是可控性——你得知道模型权重存在哪块硬盘、推理时内存怎么分配、日志往哪个文件写；第二是可调试性——当 prompt 没有按预期触发 function calling，你能直接import pdb; pdb.set_trace()进transformers的generate()方法里看 attention mask 是怎么算歪的；第三是可迁移性——今天在你那台 32G 内存的 MacBook Pro 上跑通的环境，明天换到实验室那台带 A100 的 Ubuntu 服务器上，改三行配置就能复用，而不是重头再来一遍“pip install 全家桶”。这不是为了炫技，而是当你需要把 Llama 3 接进一个老旧的 ERP 系统做智能工单分类，或者给内部知识库加个 RAG 模块时，唯一能让你不被“API 调用超时”和“月度额度用完”卡脖子的底层能力。零基础的朋友别慌，Python 安装、CUDA 驱动、模型量化格式这些概念，我会用“装打印机驱动”的逻辑来类比——你不需要懂 USB 协议栈，但得知道驱动装错版本会导致打印出来全是乱码，而我们接下来要做的，就是帮你把每一步的“驱动版本号”都标清楚。

2. 整体设计思路：为什么放弃一键脚本，坚持手动分层搭建？

很多人看到“本地部署 Llama 3”第一反应是去搜ollama run llama3或者dify local deploy，这没错，但它们像预装好所有 App 的 iPhone——你用得很爽，可一旦某个 App 崩溃，你连进程 ID 都看不到。我们的方案是回归 Linux 哲学：“每个程序只做好一件事”，把整个环境拆成四个严格解耦的层次：运行时层（Python 解释器）→ 计算层（CUDA/cuDNN 或 CPU 加速库）→ 框架层（PyTorch / llama-cpp-python）→ 模型层（GGUF 量化权重 + tokenizer）。这种分层不是为了显摆技术深度，而是为了解决三个高频痛点：

第一，版本冲突的精准隔离。比如你系统里已有 Python 3.9 用于数据分析，但 Llama 3 的某些 tokenizer 依赖 Python 3.11 的新语法；又比如你的 PyTorch 2.0.1 是用 CUDA 11.8 编译的，但新显卡驱动只支持 CUDA 12.1。一键脚本会强行覆盖全局环境，而分层方案让你用pyenv创建独立 Python 版本，用conda创建隔离的 CUDA 环境，互不干扰。

第二，资源消耗的透明可控。transformers默认加载模型到 GPU 显存，但如果你只有 6GB 显存的 RTX 3060，它会直接 OOM；而llama-cpp-python允许你用n_gpu_layers=35精确指定多少层放 GPU、多少层放 CPU 内存。这种控制权，只有手动配置才能拿到。

第三，故障排查的路径清晰。当推理卡住时，你能快速判断：是 Python 层的import torch失败（运行时层问题），还是torch.cuda.is_available()返回 False（计算层问题），或是Llama.from_pretrained()报KeyError: 'model.layers.0'（模型层格式错误）。每一层都有明确的验证命令，失败即止，不浪费一秒钟在无效尝试上。

所以，我们不推荐pip install llama这种模糊包（它实际是 llama-index 的缩写，和 Llama 3 毫无关系），也不用docker run -p 11434:11434 --gpus all ollama/ollama这种黑盒容器。我们要的是每个pip install命令后都能python -c "import xxx; print(xxx.__version__)"验证成功，每个nvidia-smi输出都能对应到具体的 GPU 内存分配。这就像修车——你得先分清是火花塞问题还是油路堵塞，而不是直接把整台发动机换掉。

3. 核心细节解析：Python 环境、CUDA 驱动、框架选型的硬核取舍

3.1 Python 解释器：为什么必须用 pyenv + virtualenv，而不是系统自带 Python？

Mac 和 Linux 系统自带的 Python（如 macOS 的/usr/bin/python3）是系统级组件，升级或卸载可能破坏 Finder、Spotlight 等原生功能。Windows 的 Python 安装包则常因 PATH 冲突导致pip命令指向错误位置。我见过最惨的案例：某位同事在 Windows 上用官网安装包装了 Python 3.12，结果pip install torch下载的是针对 Python 3.11 编译的 wheel，报错ERROR: xxx.whl is not a supported wheel on this platform，折腾两天才发现python -m pip --version和pip --version显示的 Python 路径完全不同。

正确做法是pyenv 管理 Python 版本 + virtualenv 隔离项目环境。pyenv 不是另一个 Python，而是“Python 的版本管理器”，它通过修改PATH环境变量，让 shell 在执行python命令时优先找到你指定的版本。具体操作：

# macOS 安装 pyenv（需先装 Homebrew） brew update && brew install pyenv # Linux 安装（Ubuntu/Debian） curl https://pyenv.run | bash # 然后将以下三行加入 ~/.bashrc 或 ~/.zshrc export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)" # 重新加载配置 source ~/.zshrc # macOS Catalina 及以后默认 zsh # 查看可用 Python 版本（Llama 3 官方推荐 3.10+） pyenv install --list | grep "3\.[10-12]" # 安装 Python 3.11.9（稳定且兼容性好） pyenv install 3.11.9 # 设为当前目录的局部版本（cd 进项目文件夹后执行） pyenv local 3.11.9 # 验证：此时 python -V 应输出 3.11.9 python -V

提示：pyenv local会在当前目录生成.python-version文件，Git 提交时建议加入.gitignore，避免团队成员强制使用同一版本。如果需要全局默认版本，用pyenv global 3.11.9。

装好 Python 后，必须创建虚拟环境。virtualenv venv或python -m venv venv会复制一份干净的 Python 解释器和pip，所有pip install都只影响这个venv文件夹。激活命令source venv/bin/activate（Linux/macOS）或venv\Scripts\activate.bat（Windows）后，终端提示符前会出现(venv)，这是唯一安全的开发状态。切记：任何pip install前，必须确认(venv)在提示符上，否则就是在污染全局环境。

3.2 CUDA 驱动与工具链：NVIDIA 显卡用户必过的三道关卡

如果你的机器没有 NVIDIA GPU，跳过本节，直接用 CPU 模式（性能会慢 5-10 倍，但绝对稳定）。有 GPU 的同学，请拿出手机拍下nvidia-smi命令的输出，我们来逐行解读：

+-----------------------------------------------------------------------------+ | NVIDIA-SMI 535.104.05 Driver Version: 535.104.05 CUDA Version: 12.2 | |-------------------------------+----------------------+----------------------+ | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. | |===============================+======================+======================| | 0 NVIDIA RTX 4090 Off | 00000000:01:00.0 On | N/A | | 32% 45C P2 98W / 450W | 2852MiB / 24576MiB | 0% Default | +-------------------------------+----------------------+----------------------+

关键信息有三处：Driver Version（535.104.05）→ CUDA Version（12.2）→ GPU 型号（RTX 4090）。这三个数字必须形成闭环：你的 PyTorch wheel 必须匹配 CUDA 12.2，而 CUDA 12.2 又要求驱动版本 ≥ 525（官方文档明确写的最低要求）。如果nvidia-smi显示驱动版本是 470，那pip install torch==2.3.0+cu121一定失败，因为 cu121 表示 CUDA 12.1，需要驱动 ≥ 450，但你的驱动太老，不支持新 CUDA 的 API。

解决方案不是升级驱动（可能破坏现有系统），而是降级 PyTorch 版本以匹配现有驱动。查 NVIDIA 官网的 CUDA Toolkit Archive ，找到你的驱动版本支持的最高 CUDA 版本，再查 PyTorch 官网的 Previous Versions ，选择对应 CUDA 版本的 wheel。例如驱动 470 → 最高支持 CUDA 11.4 → 安装torch==1.12.1+cu113（注意：cu113 是 CUDA 11.3，因为 11.4 的 wheel 在 PyTorch 官网未提供，11.3 是最接近的稳定版）。

注意：不要用conda install pytorch自动选 CUDA 版本！conda 有时会选错，必须用pip install指定完整 URL。例如：

pip install torch==2.3.0+cu121 torchvision==0.18.0+cu121 --index-url https://download.pytorch.org/whl/cu121

这个 URL 中的cu121是硬编码，确保 wheel 包含正确的 CUDA 二进制。

验证 CUDA 是否真正可用：

import torch print(torch.__version__) # 应输出 2.3.0+cu121 print(torch.cuda.is_available()) # 必须是 True print(torch.cuda.device_count()) # 应 ≥ 1 print(torch.cuda.get_device_name(0)) # 应输出你的 GPU 型号，如 'NVIDIA RTX 4090'

如果is_available()是 False，90% 是驱动/CUDA/PyTorch 版本不匹配，剩下 10% 是权限问题（Linux 下需将用户加入video组：sudo usermod -aG video $USER，然后重启）。

3.3 框架选型：PyTorch vs llama-cpp-python，到底该用哪个？

这是新手最容易纠结的问题。简单说：想快速验证模型效果，用 PyTorch；想长期部署、节省显存、跨平台运行，用 llama-cpp-python。

• PyTorch 方案（transformers + accelerate）
  优势：API 最标准，Hugging Face 生态无缝对接，支持 LoRA 微调、Flash Attention 加速、多卡并行。适合需要修改模型结构、做研究实验的场景。
  劣势：显存占用大。Llama 3-8B FP16 模型需约 16GB 显存，30B 模型需 60GB，远超消费级显卡。即使启用device_map="auto"，accelerate也会把部分层放到 CPU，导致推理速度暴跌。

• llama-cpp-python 方案
  优势：基于 C++ 的 llama.cpp 移植，支持 GGUF 量化格式（如Q4_K_M），8B 模型可压缩到 4.5GB，30B 模型压到 18GB，RTX 3090（24GB）就能跑 30B。CPU 模式下也能跑（慢但稳），Mac M 系列芯片原生支持 Metal 加速。
  劣势：API 较底层，不支持 Hugging Face 的pipeline，需手动处理 tokenizer、prompt template。

我的实操建议是：起步用 llama-cpp-python，因为它能让你在 5 分钟内看到第一个 token 输出；等模型逻辑跑通后，再用 PyTorch 做精度对比或微调。安装命令：

# 必须指定 --no-deps，否则会自动装 torch（可能冲突） pip install --no-deps llama-cpp-python # 然后手动装兼容的 torch（如果已装好，跳过） pip install torch==2.3.0+cu121 --index-url https://download.pytorch.org/whl/cu121 # 验证 python -c "from llama_cpp import Llama; print('OK')"

实测心得：llama-cpp-python 的n_gpu_layers参数是灵魂。RTX 4090（24GB）跑 8B 模型，设n_gpu_layers=45（总层数 32，45 表示全部放 GPU）；RTX 3060（12GB）跑 8B，设n_gpu_layers=25（留 7 层在 CPU 内存），速度损失不到 15%，但显存占用从 12GB 降到 8GB，系统不卡顿。这个值不是拍脑袋，而是llama.cpp源码里llama_model_loader.cpp的n_layer字段决定的，不同模型层数不同，8B 是 32，70B 是 80，必须查模型 config.json。

4. 实操过程：从零开始搭建可运行的 Llama 3 环境（含完整命令与参数说明）

4.1 环境初始化：创建项目目录与 Python 环境

我们从一个干净的项目目录开始，避免路径混乱。假设项目名为llama3-local：

# 创建项目目录 mkdir llama3-local && cd llama3-local # 初始化 git（方便后续版本管理） git init echo "venv/" > .gitignore echo "__pycache__/" >> .gitignore echo "*.log" >> .gitignore # 用 pyenv 设置 Python 版本（确保已按 3.1 节装好 pyenv） pyenv local 3.11.9 # 创建虚拟环境 python -m venv venv # 激活虚拟环境（Linux/macOS） source venv/bin/activate # 验证 Python 版本 python -V # 应输出 Python 3.11.9 # 升级 pip 到最新版（避免旧 pip 无法识别新 wheel 格式） pip install --upgrade pip # 安装基础工具（setuptools, wheel 是构建包必需） pip install setuptools wheel

注意：Windows 用户请用venv\Scripts\activate.bat激活，且后续所有source命令替换为对应 bat 文件。PowerShell 用户需先执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser允许脚本运行。

4.2 安装核心框架：PyTorch 与 llama-cpp-python 的双轨策略

我们采用“双轨安装”：先装 llama-cpp-python（主推），再装 PyTorch（备用）。这样即使 PyTorch 安装失败，也不影响主流程。

# 安装 llama-cpp-python（重点：必须加 --no-deps） pip install --no-deps llama-cpp-python # 如果你有 NVIDIA GPU，安装匹配的 PyTorch（按 3.2 节确定版本） # 示例：CUDA 12.1 驱动 535.x pip install torch==2.3.0+cu121 torchvision==0.18.0+cu121 --index-url https://download.pytorch.org/whl/cu121 # 如果你用 Apple Silicon Mac（M1/M2/M3），装 Metal 版本 # pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/apple # 如果你只有 CPU，装 CPU 版本（最稳） # pip install torch==2.3.0+cpu torchvision==0.18.0+cpu --index-url https://download.pytorch.org/whl/cpu # 验证两个框架 python -c " from llama_cpp import Llama import torch print('llama-cpp-python OK') print(f'PyTorch version: {torch.__version__}') print(f'CUDA available: {torch.cuda.is_available()}') "

如果最后两行输出CUDA available: True，恭喜，计算层打通。如果为 False，回到 3.2 节检查驱动/CUDA/PyTorch 版本链。

4.3 下载并验证 Llama 3 模型：GGUF 格式是本地部署的生命线

Llama 3 官方只发布 Hugging Face 格式（.safetensors），但本地部署强烈推荐GGUF 格式，因为它是 llama.cpp 专用的、支持量化和流式加载的二进制格式。Hugging Face 上搜索llama-3，找TheBloke组织发布的量化模型，例如：

• TheBloke/Llama-3-8B-Instruct-GGUF（8B 指令微调版）
• TheBloke/Llama-3-70B-Instruct-GGUF（70B 指令微调版）

进入模型页面，点击Files and versions，你会看到一堆文件名如llama-3-8b-instruct.Q4_K_M.gguf、llama-3-8b-instruct.Q5_K_M.gguf。后缀含义：

• Q4_K_M：4-bit 量化，K 分组，M 精度（平衡速度与质量，推荐新手）
• Q5_K_M：5-bit，质量更好，体积稍大（12GB vs 8B 的 5.2GB）
• Q8_0：8-bit，几乎无损，但体积大（15GB）

下载命令（用wget或浏览器）：

# 创建 models 目录存放模型 mkdir models # 下载 8B Q4_K_M 版本（约 4.5GB，适合入门） cd models wget https://huggingface.co/TheBloke/Llama-3-8B-Instruct-GGUF/resolve/main/llama-3-8b-instruct.Q4_K_M.gguf # 回到项目根目录 cd ..

提示：国内下载慢？用hf-mirror.com镜像站。把 URL 中的huggingface.co替换为hf-mirror.com，例如：https://hf-mirror.com/TheBloke/Llama-3-8B-Instruct-GGUF/resolve/main/llama-3-8b-instruct.Q4_K_M.gguf

验证模型完整性（防止下载中断）：

# 检查文件大小（Q4_K_M 应为 ~4.5GB） ls -lh models/llama-3-8b-instruct.Q4_K_M.gguf # 用 llama.cpp 自带的工具检查 header（需先装 llama.cpp） # git clone https://github.com/ggerganov/llama.cpp && cd llama.cpp && make # ./llama-cli -m models/llama-3-8b-instruct.Q4_K_M.gguf -p "Hello" -n 1 # 如果输出 token，说明模型可读。

4.4 编写第一个推理脚本：用 llama-cpp-python 跑通 Hello World

创建inference.py，这是你和 Llama 3 的第一次对话：

from llama_cpp import Llama import time # 初始化模型（路径、参数详解见下表） llm = Llama( model_path="./models/llama-3-8b-instruct.Q4_K_M.gguf", # 模型文件路径 n_ctx=4096, # 上下文长度，Llama 3 支持 8K，但 4K 更稳 n_threads=8, # CPU 线程数，设为物理核心数 n_gpu_layers=45, # GPU 层数，RTX 4090 设 45，3060 设 25 verbose=True, # 打印详细日志，调试必备 ) # 构造 Llama 3 的标准 prompt template（必须！否则效果差） # 参考官方文档：https://llama.meta.com/docs/model-cards-and-prompt-formats/meta-llama-3/ prompt = """<|begin_of_text|><|start_header_id|>system<|end_header_id|> You are a helpful AI assistant.<|eot_id|><|start_header_id|>user<|end_header_id|> Hello, who are you?<|eot_id|><|start_header_id|>assistant<|end_header_id|> """ # 开始推理 start_time = time.time() output = llm( prompt, max_tokens=256, # 最大生成 token 数 stop=["<|eot_id|>"], # 遇到此字符串停止，Llama 3 的 EOS token echo=False, # 不回显输入 prompt temperature=0.7, # 创造性控制，0.7 是平衡值 ) end_time = time.time() # 打印结果 print("Generated text:") print(output['choices'][0]['text']) print(f"\nTime taken: {end_time - start_time:.2f} seconds")

运行它：

python inference.py

如果看到类似输出：

Generated text: I am an AI assistant created by Meta, designed to help with a wide range of tasks including answering questions, writing stories, coding, logical reasoning, and more. Time taken: 2.34 seconds

恭喜！你已成功本地部署 Llama 3。注意Time taken这个数字：RTX 4090 应 ≤ 3 秒，RTX 3060 应 ≤ 8 秒，Mac M2 Max 应 ≤ 12 秒。如果超过 30 秒，检查n_gpu_layers是否设得太低（导致大量计算在 CPU），或n_ctx是否过大（4096 是安全值，8192 可能爆显存）。

4.5 进阶：用 PyTorch 加载 Hugging Face 原生模型（当你要微调时）

虽然 GGUF 是部署首选，但如果你想用 LoRA 微调、或测试原始精度，就得走 PyTorch 路线。创建hf_inference.py：

from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline import torch # 加载 tokenizer（必须和模型配套） tokenizer = AutoTokenizer.from_pretrained( "meta-llama/Meta-Llama-3-8B-Instruct", use_fast=True, trust_remote_code=True ) # 加载模型（关键：device_map="auto" 自动分配 GPU/CPU） model = AutoModelForCausalLM.from_pretrained( "meta-llama/Meta-Llama-3-8B-Instruct", torch_dtype=torch.bfloat16, # Llama 3 官方推荐 bfloat16 device_map="auto", # 自动分配，无需指定 cuda:0 trust_remote_code=True ) # 创建 pipeline（简化接口） pipe = pipeline( "text-generation", model=model, tokenizer=tokenizer, max_new_tokens=256, do_sample=True, temperature=0.7, top_k=50, top_p=0.95, ) # 构造 prompt（Hugging Face 格式） messages = [ {"role": "system", "content": "You are a helpful AI assistant."}, {"role": "user", "content": "Hello, who are you?"}, ] # 用 tokenizer.apply_chat_template 格式化（Llama 3 必须！） prompt = tokenizer.apply_chat_template( messages, tokenize=False, add_generation_prompt=True # 自动加 <|start_header_id|>assistant<|end_header_id|> ) # 生成 outputs = pipe(prompt) print("HF Generated text:") print(outputs[0]['generated_text'][len(prompt):])

运行前，需先pip install transformers accelerate bitsandbytes，并确保HF_HOME环境变量指向缓存目录（避免下载到 C 盘）：

export HF_HOME="/path/to/your/cache" # Linux/macOS # Windows: set HF_HOME=C:\path\to\cache

注意：首次运行会自动下载 15GB 的safetensors权重，耐心等待。如果device_map="auto"报错，手动指定device_map={"": "cuda:0"}。

5. 常见问题与排查技巧实录：那些让我熬夜到凌晨三点的坑

5.1 “ImportError: libcudnn.so.8: cannot open shared object file” —— CUDA 库找不到

现象：import torch成功，但torch.cuda.is_available()返回 False，nvidia-smi正常显示 GPU，错误日志里反复出现libcudnn.so.8找不到。

原因：PyTorch 依赖 cuDNN（CUDA Deep Neural Network library），而pip install torch下载的 wheel 只包含 CUDA runtime，不包含 cuDNN。系统级 cuDNN 未安装，或版本不匹配。

排查步骤：

1. 查 PyTorch 版本对应的 cuDNN 要求：PyTorch 2.3.0+cu121 要求 cuDNN 8.9.2（ 官方文档 ）。
2. 检查系统是否安装 cuDNN：

   ls /usr/lib/x86_64-linux-gnu/ | grep cudnn # 应看到 libcudnn.so.8 或 libcudnn.so.8.9.2

3. 如果没有，去 NVIDIA 官网下载 cuDNN 8.9.2 for CUDA 12.1，解压后复制文件：

   sudo cp cuda/include/cudnn*.h /usr/local/cuda/include sudo cp cuda/lib/libcudnn* /usr/local/cuda/lib64 sudo chmod a+r /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*

终极方案（推荐）：不用系统 cuDNN，改用conda安装预编译环境：

conda create -n llama3 python=3.11 conda activate llama3 conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

conda 会自动处理 cuDNN 依赖，一劳永逸。

5.2 “OSError: unable to open file” —— GGUF 模型路径或权限错误

现象：Llama(model_path="...")报错OSError: unable to open file，但ls -l确认文件存在。

原因：90% 是路径错误，10% 是文件权限。GGUF 文件必须是可读的，且路径必须是绝对路径或相对于当前工作目录的正确相对路径。

排查清单：

• ✅ 运行pwd确认当前目录，ls models/确认文件在models/下。
• ✅ 在 Python 脚本中用os.path.abspath("./models/xxx.gguf")打印绝对路径，复制到终端ls -l验证。
• ✅ 检查文件权限：ls -l models/xxx.gguf，应有rw-（如-rw-r--r--），如果没有，chmod 644 models/xxx.gguf。
• ✅ Windows 用户注意反斜杠\，Python 中必须用正斜杠/或双反斜杠\\。

实测技巧：在Llama()初始化前加一行 debug：

import os model_path = "./models/llama-3-8b-instruct.Q4_K_M.gguf" print(f"Trying to load: {os.path.abspath(model_path)}") print(f"File exists: {os.path.exists(model_path)}") llm = Llama(model_path=model_path, ...)

5.3 “RuntimeError: Expected all tensors to be on the same device” —— 混合设备错误

现象：用 PyTorch 加载模型后，model.generate()报错Expected all tensors to be on the same device，提示 input_ids 在 cpu，model 在 cuda。

原因：tokenizer.encode()默认返回 CPU tensor，而 model 在 GPU，没做.to("cuda")。

修复代码：

# 错误写法 inputs = tokenizer(prompt, return_tensors="pt") # inputs["input_ids"] 是 cpu tensor # 正确写法 inputs = tokenizer(prompt, return_tensors="pt").to("cuda") # 关键！ outputs = model.generate(**inputs, max_new_tokens=256)

更稳妥方案：用pipeline，它自动处理设备转移：

pipe = pipeline("text-generation", model=model, tokenizer=tokenizer, device="cuda:0") # device 参数指定 GPU，pipeline 内部自动 transfer

5.4 “Token generation stuck at 0%” —— 推理卡死的三大元凶

现象：脚本运行后，光标一直闪烁，无输出，htop显示 Python 进程 CPU 占用 100%，但nvidia-smi显存不动。

元凶 Top 3：

1. Stop tokens 错误：Llama 3 的 EOS token 是<|eot_id|>，不是<|endoftext|>或</s>。如果stop=["<|eot_id|>"]拼错，模型会一直生成直到max_tokens用完，看起来就是卡住。
2. Context overflow：n_ctx=8192但 prompt 已占 7000 tokens，剩余空间不足，模型在 padding 上死循环。用tokenizer.encode(prompt)检查长度。
3. GPU 内存碎片：之前运行崩溃留下内存碎片，nvidia-smi显示显存占用高但torch.cuda.memory_allocated()低。重启 Python 进程或nvidia-smi --gpu-reset（需 root）。

快速诊断脚本：

# 在推理前插入 print(f"Prompt length: {len(tokenizer.encode(prompt))}") print(f"Available context: {llm.n_ctx - len(tokenizer.encode(prompt))}") print(f"Stop tokens: {stop}") # 如果 available context < 100，果断缩减 prompt 或增大 n_ctx

5.5 “Mac M2 跑得比 CPU 还慢” —— Metal 加速未启用

现象：Apple Silicon Mac 上，llama-cpp-python默认用 CPU，速度极慢，nvidia-smi当然没输出（因为没 NVIDIA）。

原因：llama-cpp-python 需要编译时启用 Metal 支持，而pip install默认 wheel 不含 Metal。

解决方案：

# 卸载旧版 pip uninstall llama-cpp-python # 从源码编译