目录

在 SpacemiT K1 开发板上烧录、安装与运行 Gemma 4 QAT 大模型

本指南总结了在进进时空（SpacemiT）K1 架构 RISC-V 芯片板卡（以 Milk-V Jupiter 16GB 版本为例）上，从系统烧录、硬件级加速交叉编译、网络优化，到最终跑通 Google Gemma 4 QAT 模型的完整全栈实战步骤。

目录

  1. 系统烧录 (Flashing OS)
  2. 环境准备与交叉编译 (Cross-Compilation)
  3. 硬件级加速与系统优化 (Optimization)
  4. 网络代理与模型下载 (Model Download)
  5. 模型运行与参数调优 (Execution)
  6. 参考链接 (References)

1. 系统烧录 (Flashing OS)

为了使 K1 芯片的向量（RVV 1.0）及矩阵扩展指令（IME）发挥最大功效，我们需要使用 Bianbu OS 官方提供的最新 minimal 镜像。

  1. 下载官方系统包： 手动下载极简系统压缩包（例如 milkv-jupiter-bianbu-24.04-minimal-k1-v2.1.1-release-2025-0305.zip）。
  2. 连接开发板： 使用 USB 转串口线或 DFU 连接电脑，使开发板进入刷机状态。
  3. 启动烧录服务并写入镜像： 在 host 主机端运行官方刷机脚本 ./flashserver：
    qtopierw@kylaptop:foo$ ./flashserver 
# 系统会列出当前可用的烧录端口：
--- Available ports:
---  1: 3-8                  'fastboot VID:PID=0x361c:0x1001 SER=dfu-device'
--- Enter port index or full name: 1
    输入端口索引并确认，刷机程序会自动将 minimal bianbu 镜像烧录至开发板。完成后拔线重启，使用 ssh root@spacemit-k1 连接至开发板（默认系统密码一般为 gushijie 或配置项指定值）。

2. 环境准备与交叉编译 (Cross-Compilation)

由于开发板本地的 GCC 编译器可能缺乏对 zvfh（半精度浮点向量扩展）的完整编译支持，直接本地编译会导致硬件加速指令集丢失。因此，我们需要在 x86_64 主机 上进行交叉编译。

  1. 准备 host 工具链： 在 x86_64 host 主机上下载进迭时空官方交叉编译工具链 v1.2.4 以及便携式 cmake 3.29.3。
  2. 下载 llama.cpp 源码：
    git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
  3. 执行交叉编译（启用 SpacemiT 专属优化）： 使用交叉编译链运行 cmake。这里至关重要的是要开启 -DGGML_CPU_RISCV64_SPACEMIT=ON 芯片定制选项，同时启用 GGML_RVV 向量和 GGML_RV_ZVFH 指令集：
    cmake -B build \
  -DCMAKE_TOOLCHAIN_FILE=path/to/spacemit-toolchain.cmake \
  -DGGML_CPU_RISCV64_SPACEMIT=ON \
  -DGGML_RVV=ON \
  -DGGML_RV_ZVFH=ON \
  -DBUILD_SHARED_LIBS=ON
cmake --build build --config Release -j$(nproc)
  4. 同步到开发板： 编译完成后，将生成的二进制程序及动态库（libggml.so、libllama.so等）拷贝到 K1 开发板的指定目录下（建议存放为 /root/llama-installed/bin/ 和 /root/llama-installed/lib/）。

3. 硬件级加速与系统优化 (Optimization)

在开发板端，我们需要解锁 K1 SoC 独有的 TCM（紧耦合内存，Tightly Coupled Memory）同步驱动，否则 llama.cpp 将因为无法加载 barrier 分配而回退到普通的 heap 堆分配，导致严重掉速。

  1. 建立 TCM 设备文件软链接： 在开发板内，SpacemiT 的硬件同步设备可能映射在 /dev/tcm 下。而 llama.cpp 编译好的底层调用默认指向 /dev/tcm_sync_mem。我们需要执行：
    ln -sf /dev/tcm /dev/tcm_sync_mem
  2. 解决开机失效问题： 由于 /dev 是一个临时 RAM 磁盘（tmpfs），开发板关机或重启后该软链接会消失。为避免回退掉速，必须将此挂载脚本加入系统的开机自启配置文件 /etc/rc.local 中：
    # 编辑 /etc/rc.local 并写入：
ln -sf /dev/tcm /dev/tcm_sync_mem

4. 网络代理与模型下载 (Model Download)

在国内由于 DNS 污染，开发板极易将 Hugging Face 解析至被墙的 Meta IP 段（导致 Connection reset 或 SSL Handshake error）。我们需要结合 host 端的代理网络，建立 SSH 反向隧道。

  1. 建立 SSH 反向代理隧道： 在 host 主机端，连接开发板并转发代理端口（假设 host 本地 Privoxy 代理端口为 8118）：
    ssh -R 8118:127.0.0.1:8118 root@spacemit-k1
  2. 在开发板上配置代理：
    export http_proxy=http://127.0.0.1:8118
export https_proxy=http://127.0.0.1:8118
  3. 安装 aria2 并修复 IPv6 解析： 由于 K1 的 IPv6 配置常在解析本地代理时报 Address family not supported 错误，我们将 aria2 的解析配置为只使用 IPv4：
    • 开发板端安装 aria2：apt-get update && apt-get install -y aria2
    • 编写或修改 Hugging Face 下载工具 hfd.sh，在里面的 aria2c 运行命令中加入 --disable-ipv6 参数。
  4. 下载 Unsloth Gemma 4 E4B QAT 模型： 使用带有多线程下载 and 重试保护的脚本，直接拉取 UD-Q4_K_XL (Unsloth 动态 4-bit 量化) 变体：
    until /root/hfd.sh unsloth/gemma-4-E4B-it-qat-GGUF \
  --include '*UD-Q4_K_XL.gguf' \
  --tool aria2c -x 8 -j 5 \
  --local-dir /root/models/gemma-4-E4B-it-qat-GGUF; do
    echo "下载遇到错误，正在 5 秒后自动重连断点续传..."
    sleep 5
done

5. 模型运行与参数调优 (Execution)

Gemma 4 是混合思考模型。为了最大限度挖掘 K1 的推理潜力，运行参数须与 CPU 核心架构深度对齐。

  1. 绑定性能大核 (CPU Core Affinity)： SpacemiT K1 芯片共有 8 个核心，但属于 4 大核 + 4 小核 的非对称架构。如果设置 -t 8 反对会因为小核木桶效应导致性能暴跌。我们必须将线程限制在 -t 4（仅运行在大核心 0-3 上）。
  2. Unsloth 推荐参数集： 根据 Unsloth 对 QAT checkpoints 的模型性能调优，最佳的生成参数为：
    • 运行温度：--temp 1.0
    • Top-P：--top-p 0.95
    • Top-K：--top-k 64
  3. 编写启动脚本： 我们在开发板端创建辅助启动 file /root/run_gemma4.sh：
    #!/bin/bash
export LD_LIBRARY_PATH=/root/llama-installed/lib
MODEL_PATH="/root/models/gemma-4-E4B-it-qat-GGUF/gemma-4-E4B-it-qat-UD-Q4_K_XL.gguf"

if [ ! -f "$MODEL_PATH" ]; then
    echo "错误: 找不到模型文件 $MODEL_PATH"
    exit 1
fi

echo "正在使用优化版 llama.cpp 在 SpacemiT K1 上启动 Gemma-4 E4B QAT 模型..."
/root/llama-installed/bin/llama-cli \
  --model "$MODEL_PATH" \
  --threads 4 \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -cnv \
  --reasoning off \
  --prompt "You are a helpful and precise assistant."
    (注：如果你需要开启思考模式进行深度推理，可将 --reasoning off 改为 --reasoning on，并将 system prompt 修改为引导思考的词) 使该脚本可执行：chmod +x /root/run_gemma4.sh。
  4. 运行测试： 运行 ./run_gemma4.sh 开启本地终端交互：
    • Prompt 推理速度 可达 8.5 tokens/sec
    • 思考链与推理生成速度 可稳定在 1.9 tokens/sec。思考链输出完备，回答质量极高。

6. 参考链接 (References)