1. 环境搭建与模型下载

任务目标

在边缘设备（以Linux x86_64或树莓派4B为例）上完成llama.cpp的编译安装，下载一个GGUF格式的量化模型，并通过命令行执行一次完整推理，验证环境可用。

环境依赖

• 操作系统：Ubuntu 22.04+ / Debian 12+（树莓派需64位系统）
• 工具链：git、cmake（≥3.14）、g++（≥11，需支持C++17）
• Python 3.10+（仅用于下载脚本，推理本身不依赖Python）
• 磁盘空间：编译约2GB，模型约0.5GB（以Q4_K_M 7B为例）

实现步骤

1. 安装系统依赖并克隆源码

sudo apt update
sudo apt install -y git cmake g++ build-essential
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

2. 编译llama.cpp（Release模式）

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j $(nproc)

编译完成后，可执行文件位于build/bin/目录下。若设备内存小于4GB，编译时建议加-j 2限制并行度。

3. 下载量化模型

使用Hugging Face Hub下载TinyLlama 1.1B的4-bit量化版（约650MB，适合边缘设备验证）：

pip install -U huggingface_hub
huggingface-cli download TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf --local-dir ./models

若网络受限，可手动从 Hugging Face模型页 下载同名文件放入models/目录。

4. 运行推理验证

./build/bin/llama-cli \
  -m ./models/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf \
  -p "Hello, my name is" \
  -n 32 \
  -t 4

参数说明：-m指定模型路径，-p为输入提示词，-n为生成数，-t为线程数（树莓派建议设为4）。

验证方法与通过条件

执行上述推理命令后，观察终端输出。满足以下条件即判定环境搭建成功：

1. 命令正常退出，无报错信息（如模型文件缺失、内存不足等）；
2. 输出文本以Hello, my name is开头，后续生成内容为连贯的英文自然语言（例如Hello, my name is Sarah and I am a...）；
3. 生成速度不低于1 /s（树莓派4B约2-4 /s，x86桌面约10-20 /s），且无卡死或长时间无响应。

若输出为乱码或空白，请检查模型文件是否完整（ls -lh models/确认大小约650MB），并确认编译时CPU架构与设备匹配。

常见问题

• 编译报错“c++: fatal error: killed signal”：内存不足，减少并行度（-j 2）或增加swap空间。
• 运行时提示“failed to load model”：模型路径错误或GGUF文件损坏，重新下载并核对文件名。
• 树莓派编译耗时过长：交叉编译或直接使用预编译release包（llama.cpp/releases），但需确认CPU支持（ARMv8+）。

至此，llama.cpp环境搭建与模型下载验证闭环完成。后续案例将基于此环境进行推理优化与边缘部署调参。