第一章：硬件环境与模型选型

嵌入式设备（树莓派 4B/5、瑞芯微 RK3588）的特殊限制决定了模型选择至关重要。

硬件配置推荐表

硬件设备	内存限制	推荐模型版本	量化格式	预期性能	部署方式
树莓派 4B	4GB	Qwen3-0.5B	Q4_K_M	~4 t/s (流畅)	纯 CPU (ARM_NEON优化)
树莓派 5	8GB	Qwen3-1.5B	Q4_K_M	~3 t/s (可用)	纯 CPU
RK3588	8GB/16GB	Qwen3-1.5B	Q4_K_M	~20 t/s (启用NPU)	推荐使用 rknn-llm 工具链

重要提示：7B及以上参数模型会导致内存溢出（OOM）或极慢的交换分区读写，请避免使用。

---

第二章：环境准备与模型下载

嵌入式Linux环境下，正确的下载与编译方法尤为关键。

1. 模型下载（替代df命令）

df命令用于查看磁盘空间，实际下载需使用以下方法：

• 方法A(wget)：wget -c <模型直链>（-c参数支持断点续传）
• 方法B(huggingface-cli)：需安装Python环境，使用huggingface-cli download
• 建议：开发板网速较慢时，推荐PC下载后通过scp传输

2. 编译llama.cpp

树莓派编译命令：

cmake -B build -DLLAMA_ARM_NEON=ON
cmake --build build --config Release -j4

RK3588：建议使用瑞芯微官方rknn-llm工具链而非原生llama.cpp以发挥NPU性能。

---

第三章：交互方式与图形化界面

从命令行过渡到"窗口对话"体验的方法。

1. 最佳实践：本地Web界面(llama-server)

实现方式：

• 开发板运行服务端
• 局域网设备通过浏览器访问

启动命令：

./build/bin/llama-server -m ./model.gguf -c 2048 -t 4 --host 0.0.0.0 --port 8080

访问地址：http://<开发板IP>:8080

2. 本地图形界面(GUI)

操作建议：

• 开发板桌面浏览器访问http://localhost:8080
• 注意：桌面环境会占用大量资源，可能影响模型推理速度

---

第四章：模型行为优化与参数调整

解决模型异常输出或参数设置无效问题。

1. 关闭"思考过程"(System Prompt)

Qwen3默认可能输出<thought>标签或推理步骤。

错误排查：若报错invalid argument: --system-prompt，说明版本过旧。

解决方案：

• Web界面设置：在Settings/Configuration面板中找到"System Prompt"输入框
• 内容：You are a direct assistant... Do NOT output any internal reasoning... Provide ONLY the final direct answer.
• 参数调整：设置--temp 0.1和--top-p 0.8减少发散性

2. 上下文大小(Context Size)不生效

原因：模型文件本身有限制（如n_ctx_train=2048），或物理内存不足。

排查方法：查看启动日志中的n_ctx实际值；如需大上下文，需增加物理内存或Swap分区。

---

第五章：Python环境与依赖管理

解决Python包管理冲突问题。

错误：externally-managed-environment

原因：现代Linux(Debian/Ubuntu)系统的保护机制，禁止全局pip安装。

解决方案：

推荐方案(虚拟环境)：

python3 -m venv venv
source venv/bin/activate
pip install llama-cpp-python duckduckgo-search

强制安装(不推荐)：

pip install --break-system-packages ...

---

第六章：进阶功能——赋予模型"联网"能力

在不使用复杂Docker容器的情况下实现自动联网。

1. 方案：Python脚本+Function Calling(函数调用)

实现原理：

1. 编写Python脚本定义"搜索工具"
2. 模型自动判断何时调用

核心库：

• llama-cpp-python（推理）
• duckduckgo-search（免费搜索）

工作流程：

1. 用户提问（如"今天天气如何？"）
2. 模型识别需搜索，输出call_search("查询关键词")
3. 脚本拦截指令，执行搜索并获取网页摘要
4. 脚本将摘要返回模型，生成最终回答

优势：无需Docker，单脚本运行，完全本地化推理，仅搜索时联网

---

第七章：故障排查汇总

常见故障解决方案

故障现象	可能原因	解决方案
速度极慢	未启用GPU/NPU	RK3588尝试开启Vulkan或使用rknn-llm；树莓派确保开启NEON
显存/内存不足	模型过大或上下文过长	换用更小模型（0.5B）；减小-c参数；增加Swap分区
乱码/输出异常	Tokenizer不匹配	确保使用Qwen3专用Chat模板或最新版llama.cpp
安装包报错	缺少编译工具	安装build-essential和python3-dev

---

文档总结

本指南详细介绍了在资源受限的嵌入式设备上部署Qwen3的全流程。从环境搭建到图形界面交互，再到通过Python脚本实现"自动联网"功能，关键在于**模型选型（0.5B/1.5B）与外部工具调用（Function Calling）**的合理结合。