🎯背景与初衷

在生成式 AI 席卷全球的今天，将大语言模型（LLM）部署在边缘设备上已成为端侧智能的核心趋势。

NVIDIA Jetson Nano (4GB) 虽已是一款发布多年的“算力老兵”——它依然运行着基于 Ubuntu 18.04 的 JetPack 4.6.x 系列固件，其 Maxwell 架构的 GPU 算力仅为 0.5 TOPS（472 GFLOPS FP16）。但在资源受限的边缘计算场景中，它凭借极高的性价比和完善的社区生态，依然是许多开发者进行原型设计和算法验证的首选。

然而，由于其系统环境相对陈旧，Jetson Nano 与当前飞速迭代的 LLM 生态（如 Python 高版本依赖、现代编译器需求）之间存在着巨大的兼容性鸿沟。在尝试部署 Qwen（通义千问）等轻量化模型的过程中，我遭遇了诸如 GCC 版本冲突、Conda 环境干扰以及频繁的 Segmentation fault 等底层噩梦。

这个项目诞生的目的，就是为了打破这些障碍。

我经过无数次“炸机”与重装的尝试，系统性地梳理出了一条可快速复现的技术路径。通过对 llama.cpp 内核参数的微调、编译器路径的深度锁定以及系统资源的极限优化，我成功在 Jetson Nano 上实现了 Qwen 模型的高效运行。希望这份指南能为同样奋斗在边缘计算一线的开发者们提供参考，让我们在这些“陈旧”的硅片上，也能点亮端侧智能的火花。

如果你对这个项目感兴趣欢迎访问Github项目地址：yan-gd/LLM-Jetson-Nano-Qwen-Deployment-Guide: 我记录了在 NVIDIA Jetson Nano (4GB) 硬件环境下，从零开始部署大语言模型（LLM）的完整流程，旨在为边缘计算设备提供端侧的智能语言处理能力

🧭目录

1.系统基础环境搭建

2.核心依赖环境安装 

3.部署流程 

4.运行与交互 

5.踩坑经验 

🧱 1.系统基础环境搭建 (Flashing & Init)

💿 1.1 系统镜像烧录

下载镜像: 从 NVIDIA 官网下载 JetPack 4.6.1 镜像（建议不要用 4.6.3+，兼容性最稳）。https://developer.download.nvidia.cn/embedded/L4T/r32_Release_v7.1/JP_4.6.1_b110_SD_Card/Jeston_Nano/jetson-nano-jp461-sd-card-image.zip?

烧录工具: 使用 BalenaEtcher 或 Raspberry Pi Imager。

硬件建议: 使用至少 64GB 的高速显存卡（推荐 SanDisk High Endurance，防止频繁读写损坏）。

初始配置: 插入 SD 卡开机，完成语言、时区及用户设置（用户名为 `nvidia`）。

🧠 1.2 系统资源极限优化

Jetson Nano 的 4GB 显存是与内存共享的，必须进行以下操作防止 OOM：

创建 4GB Swap:

```bash

sudo fallocate -l 4G /swapfile && sudo chmod 600 /swapfile

sudo mkswap /swapfile && sudo swapon /swapfile

```

开启 Headless 模式: 运行 

sudo init 3

临时关闭图形界面（释放约 800MB 显存）。

🧩 2.核心依赖环境安装 (Dependency Prep)

🛠️ 2.1 升级 CMake (至 3.28+)

Ubuntu 18.04 自带的 CMake 版本太低（3.10），无法支持 llama.cpp 的编译。

```bash

wget https://github.com/Kitware/CMake/releases/download/v3.28.1/cmake-3.28.1-linux-aarch64.tar.gz

tar -zxvf cmake-3.28.1-linux-aarch64.tar.gz

sudo mv cmake-3.28.1-linux-aarch64 /opt/cmake-3.28

# 后续编译时请使用路径：/opt/cmake-3.28/bin/cmake

```

🔒 2.2 编译器路径锁定

建议不要使用 Conda 环境下的 GCC 15，使用系统原生 GCC 8 以匹配 CUDA 10.2。因为conda环境的gcc遇到版本不兼容的问题清理起来非常麻烦。

```bash

sudo apt update && sudo apt install gcc-8 g++-8 -y

```

🧪 3.部署流程 (Installation Steps)

🧷 3.1添加环境变量

```bash

# 修正环境变量 (编辑 ~/.bashrc)

export PATH=/usr/local/cuda/bin:$PATH

export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

```

 📦 3.2获取 llama.cpp 并锁定版本

为了保证编译成功，我们使用了特定的稳定提交版本。

```bash

git clone --recursive https://github.com/ggerganov/llama.cpp

cd llama.cpp

# 锁定到已知稳定版本 (commit: a33e6a0d2)

git checkout a33e6a0d2

```

🧬 3.3调整 ggml-cuda.cu

为了让 llama.cpp 更好地在 Maxwell (Tegra X1) 架构上运行并避免部分计算错误，建议调整以下内核参数：

打开文件（按你的 llama.cpp 版本路径可能略有不同）：

```bash

nano ggml-cuda.cu

```

搜索并启用关键宏（找到后取消注释/启用即可）：

```c

// #define GGML_CUDA_FORCE_MMQ

```

针对计算版本 5.3 的设备，确保 MMVQ (Multi-Message Vectorized Quantization) 相关宏定义与硬件资源匹配。

若遇到半精度 (FP16) 计算冲突，可尝试强制启用 `GGML_CUDA_FORCE_MMQ=1`，以使用更兼容的计算方式。

🧱 3.4针对 Maxwell 架构编译

Jetson Nano 的算力版本为 5.3。

```bash

mkdir build && cd build

/opt/cmake-3.28/bin/cmake .. \

  -DGGML_CUDA=ON \

  -DCMAKE_CUDA_ARCHITECTURES=53 \

  -DCMAKE_C_COMPILER=/usr/bin/gcc-8 \

  -DCMAKE_CXX_COMPILER=/usr/bin/g++-8 \

  -DCMAKE_CUDA_HOST_COMPILER=/usr/bin/gcc-8 \

  -DGGML_NATIVE=OFF



make -j2

```

⬇️ 3.5模型下载 (Qwen 系列)

推荐使用量化后的 GGUF 格式。

```bash

cd ../models

# 建议下载 Qwen2.5-0.5B-Instruct-GGUF (约 468MB) 其他轻量级模型也可以使用.gguf格式。

wget https://hf-mirror.com/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf

```

💬 4.运行与交互 (Usage)

使用以下命令开启交互模式：

```bash

./bin/main -m ../models/qwen2.5-0.5b-instruct-q4_k_m.gguf \

  -ngl 99 -c 512 -i --color -r "User:" \

  --in-prefix "User: " --in-suffix "Assistant: " \

  -p "你是一个聊天助手。"

```

🧯 5.踩坑经验 (Troubleshooting & Pitfalls)

遇到的问题-根本原因-解决方案

Segmentation fault编译器版本冲突：使用了 Conda 带来的 GCC 15，生成了老旧 Nano 芯片无法识别的指令。 彻底删除 Conda 路径，使用系统原生 GCC 8.4 重新编译。

Segmentation fault 模型文件损坏：下载过程中断，导致读取 key-value 对失败。校验模型文件大小（应为 ~400MB+），不要运行只有 1MB 的残缺文件。 

模型自问自答缺少停止符：模型试图续写对话剧本。 | 在启动参数中加入 `-r "User:"` 强制模型在生成该词时停止。

CUDA 初始化失败显存/内存枯竭：图形界面占用了过多资源。执行 `sudo init 3` 关闭桌面，并确保开启了足够的 Swap。