一、部署前准备

1. 硬件要求

• 树莓派型号：树莓派 4B（4GB/8GB）或树莓派 5（4GB/8GB）（2GB 内存仅能跑 1B 级超小模型，不推荐）
• 存储：建议用 32GB+ Class 10 TF 卡（模型文件+系统需占用 10-20GB）
• 散热：树莓派运行大模型会持续高负载，必须配散热片/小风扇（否则会因过热降频，推理速度骤降）
• 电源：用 5V 3A 及以上电源（避免供电不足导致崩溃）

2. 系统要求

• 操作系统：Raspberry Pi OS（64 位，推荐 Bookworm 版本），32 位系统不支持大模型量化格式，直接淘汰！
• 提前更新系统：

  sudo apt update && sudo apt upgrade -y
  

二、分步部署教程

第一步：安装依赖工具

树莓派编译 llama.cpp 需要编译器、Git 等基础工具，执行以下命令安装：

# 安装编译依赖（gcc、cmake 等）
sudo apt install -y build-essential git cmake libopenblas-dev libgfortran5

# 安装 Python 依赖（用于模型转换，可选）
sudo apt install -y python3-pip python3-dev
pip3 install --upgrade pip
pip3 install numpy sentencepiece

第二步：克隆并编译 llama.cpp（关键优化）

树莓派 CPU 是 ARM 架构，编译时需开启针对性优化，才能最大化性能：

# 克隆 llama.cpp 仓库
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# 编译（针对树莓派 CPU 优化，启用 OpenBLAS 加速）
# 树莓派 4B：用 -mcpu=cortex-a72 优化
# 树莓派 5：用 -mcpu=cortex-a76 优化
cmake -S . -B build -DLLAMA_OPENBLAS=ON -DCMAKE_CXX_FLAGS="-mcpu=cortex-a72"  # 4B 用这个
# cmake -S . -B build -DLLAMA_OPENBLAS=ON -DCMAKE_CXX_FLAGS="-mcpu=cortex-a76"  # 5 代用这个

# 开始编译（-j4 表示用 4 线程，树莓派 4B 最大支持 4 线程，5 代可改 -j8）
cmake --build build -j4

• 编译成功后，会在 build/bin 目录下生成 llama-cli（推理工具）、llama-server（API 服务）等可执行文件。
• 若编译报错“内存不足”，先关闭其他程序，或临时增大交换分区（不推荐长期用，伤 TF 卡）。

第三步：下载/转换 GGUF 格式模型（核心！树莓派专用）

树莓派性能有限，必须选择 2B-7B 参数的量化模型（推荐 Q4_K_M 格式，平衡速度和效果），无需自己转换，直接下载现成的 GGUF 模型（避免占用树莓派资源）：

1. 推荐模型（树莓派适配优先级）：

   • Phi-3-mini-4K-Instruct-Q4_K_M.gguf（1.3B 参数，仅需 2-3GB 内存，速度快）
   • TinyLlama-1.1B-Chat-v1.0-Q4_K_M.gguf（1.1B 参数，适合纯文本任务）
   • Llama-3-8B-Instruct-Q4_K_M.gguf（8B 参数，效果更好，但需 4GB+ 内存，速度较慢）

2. 下载方式（用 wget 直接在树莓派下载，或电脑下载后传到树莓派）：
   访问 Hugging Face 模型库（如 https://huggingface.co/TheBloke），搜索模型名+Q4_K_M+gguf，复制下载链接，示例：

   # 下载 Phi-3-mini 1.3B Q4_K_M 模型（推荐首选）
   wget https://huggingface.co/TheBloke/Phi-3-Mini-4K-Instruct-GGUF/resolve/main/phi-3-mini-4k-instruct.Q4_K_M.gguf -P ./models/
   

第四步：运行模型测试推理

用 llama-cli 工具启动模型，测试是否能正常运行，参数要适配树莓派资源：

# 进入编译后的 bin 目录
cd build/bin

# 运行模型（核心参数说明）
./llama-cli -m ../../models/phi-3-mini-4k-instruct.Q4_K_M.gguf \
  -p "请用简单的语言解释什么是人工智能？" \
  --n_ctx 1024 \  # 上下文长度（树莓派建议 512-1024，太大占用内存）
  --n_threads 4 \  # 线程数（和 CPU 核心数一致，4B 用 4，5 代用 8）
  --n_gpu_layers 0  # 树莓派无 NVIDIA GPU，设为 0（仅用 CPU）

• 正常情况下，会看到模型开始生成文本，树莓派 4B 运行 Phi-3-mini 速度约 3-8 tokens/秒（能满足简单问答），5 代速度可提升 50% 左右。
• 若运行卡顿/崩溃：① 换更小参数模型（如 TinyLlama）；② 降低 n_ctx（如 512）；③ 检查散热是否正常。

第五步：（可选）启动 API 服务，供其他设备调用

如果想让树莓派作为本地 API 服务器，让电脑/手机通过网络调用模型，用 llama-server：

# 启动 API 服务，端口 8080
./llama-server -m ../../models/phi-3-mini-4k-instruct.Q4_K_M.gguf \
  --n_ctx 1024 \
  --n_threads 4 \
  --host 0.0.0.0  # 允许局域网内其他设备访问

• 启动后，在电脑浏览器访问 http://树莓派IP:8080，可看到 Web 交互界面；也能通过 HTTP 请求调用 API（类似 OpenAI）。

三、关键优化技巧（树莓派必看）

1. 模型选择是核心：优先 1B-3B 参数的 Q4_K_M/Q5_K_M 量化模型，7B 模型仅树莓派 5（8GB）能勉强运行，速度较慢。
2. 线程数匹配 CPU 核心：树莓派 4B 是 4 核，设 --n_threads 4；5 代是 8 核，设 --n_threads 8，过多线程会导致切换开销。
3. 关闭不必要的服务：部署时关闭 VNC、蓝牙、Wi-Fi（若用有线）等无关服务，释放内存和 CPU 资源。
4. 散热！散热！散热：必须配散热风扇，否则树莓派 CPU 温度超过 80℃ 会自动降频，推理速度直接减半。

总结

• 树莓派部署 llama.cpp 的核心是「适配资源」：用 64 位系统+小参数量化模型+针对性编译优化，就能实现本地推理。
• 推荐新手从 Phi-3-mini 1.3B 模型开始，门槛最低、速度最快，适合验证功能；若追求更好效果，再尝试 7B 模型。
• 树莓派的优势是低功耗、全离线，适合做隐私保护的边缘 AI 设备（如本地语音助手、小型问答机器人）。

附录
适合树莓派部署的量化模型，核心要满足参数量1 - 8B、量化后体积小，且适配llama.cpp支持的GGUF格式，同时能适配树莓派4B/5的硬件资源。不同模型在参数量、中文支持、推理速度等方面各有侧重，以下是按“入门轻量→均衡实用→进阶性能”分类推荐：

1. 入门轻量型（适配树莓派4B/5，低内存无压力）
   这类模型参数量多在1 - 2B左右，INT4量化后体积不足1GB，即使树莓派4B（4GB）也能流畅运行，适合简单问答、文本生成等基础任务。
   • TinyLlama - 1.1B：参数量仅1.1B，INT4量化后体积约0.6GB。作为超轻量模型，它对资源需求极低，树莓派4B（4GB）就能稳定运行，且适配GGUF格式，搭配llama.cpp推理时，树莓派5上速度可达5 - 8 tokens/s。缺点是复杂推理能力较弱，适合做入门测试或简单文本生成。
   • DeepSeek - R1 - 1.5B：1.5B参数量，INT4量化后约0.8GB。核心优势是针对中文做了专门优化，同时代码生成能力较强，适合中文场景下的基础问答和简单代码辅助。社区实测在树莓派5（8GB）上运行时，速度约6 tokens/s，内存占用仅3GB，兼容性拉满。
   • GEB - 1.3B：参数量1.3B，经INT4量化后体积小，且采用GQA、FlashAttention - 2等加速机制，CPU推理性能出色。该模型基于550B token训练，中英双语能力均衡，在MMLU、C - Eval等测评中表现优于同量级的TinyLlama，适合对双语交互有需求的轻量场景。
2. 均衡实用型（适配树莓派5，兼顾性能与效果）
   参数量在2 - 4B左右，量化后体积1 - 3GB，推理效果比轻量模型显著提升，适合日常问答、短文本摘要等中度需求，主要适配树莓派5（4GB/8GB）。
   • Phi - 2/Phi - 3 - mini：Phi - 2参数量2.7B，INT4量化后约1.2GB；Phi - 3 - mini参数量3.8B，INT4量化后约3.2GB。两款均由微软优化，推理效率高，其中Phi - 3 - mini支持128K超长上下文窗口，能处理长文本任务。Phi - 3.5 - mini还额外支持图像能力，适合多模态轻量场景，但树莓派5上推理延迟较高，更适合低频交互。
   • Gemma 2 - 2B：谷歌推出的2B参数量模型，适配GGUF格式，Ollama等工具链对其支持完善。该模型性能稳定，在常识推理、日常对话等任务中表现均衡，量化后在树莓派5（4GB）上运行无压力，适合追求稳定体验的场景。
3. 进阶性能型（仅适配树莓派5 8GB，追求强推理能力）
   参数量达7 - 8B，量化后约3 - 4GB，推理能力接近主流中端模型，适合复杂推理、专业领域简单问答等需求，但仅树莓派5（8GB）能勉强支撑，推理速度相对较慢。
   • Mistral - 7B - v0.3：参数量7.3B，INT4量化后约3.5GB，采用Apache - 2.0开源协议。该模型以“性能均衡”著称，在逻辑推理、多轮对话中表现优秀，是7B量级的标杆模型。社区实测树莓派5（8GB）上可运行，速度约2 - 3 tokens/s，适合对推理精度要求高、可接受稍慢响应的场景。
   • LLaMA - 3 - 8B - mini：8B参数量，INT4量化后约4GB，继承了LLaMA - 3系列的强通用能力，在多轮对话、指令理解上表现出色。它适合需要高质量交互的场景，比如专业知识问答、短文本创作，但树莓派5（8GB）运行时需控制上下文长度（建议512 - 1024），避免内存溢出。

此外，选择这些模型的量化版本时，树莓派这类极端轻量设备优先选Q2_K、Q3_K_S格式保证能稳定运行；若想平衡性能和效果，Q4_K_M是性价比最优的选择。这些模型均可在Hugging Face（如TheBloke仓库）下载对应的GGUF量化版本，直接适配llama.cpp运行。