常见问题

硬件相关

PCIe 设备未识别

现象：lspci | grep Rockchip 无输出

排查步骤：

  1. 确认金手指是否插紧

  2. 确认 RK1828 供电线缆已连接（必须独立供电，不能从 PCIe 槽取电）

  3. 确认 PCIe 插槽模式配置是否正确（Gen2/Gen3）

  4. 查看系统日志：

    sudo dmesg | grep -E "pci|pcie"

正常时 lspci 应能看到 RK1828 NPU，PCIe 地址 0004:41:00.0，Device ID 182a：

实际验证（当前 RK3588 系统）：

lspci | grep -i rockchip

输出：

0002:20:00.0 PCI bridge: Rockchip Electronics Co., Ltd RK3588 (rev 01)
0004:40:00.0 PCI bridge: Rockchip Electronics Co., Ltd RK3588 (rev 01)
0004:41:00.0 Processing accelerators: Rockchip Electronics Co., Ltd Device 182a (rev 01)

实测只有 2 个 PCI bridge（0002:20:00.0 + 0004:40:00.0），没有 0003:30:00.0。BDF 因主板 PCIe 拓扑而异，以本机 lspci 实际输出为准。

lspci -s 0004:41:00.0

输出：

0004:41:00.0 Processing accelerators: Rockchip Electronics Co., Ltd Device 182a (rev 01)
dmesg | grep -E "pci|pcie" | head -10

输出：

（无输出，内核 ring buffer 已滚出）

实测 dmesg | grep -E "pci|pcie" 完全为空，ring buffer 已被后续日志覆盖。重启后能看一次，之后会被覆盖。要保留 PCIe 启动信息可在 dmesg --follow 模式 + 抓取启动窗口。

NPU 温度过高

现象：rknn-smi info 显示温度 > 70°C

建议：

  • 检查散热片、风扇是否正常

  • 确认环境通风

  • 降低推理频率或减少并发：

    sudo rknn-smi set -t npu_freq   # 查看 / 设置 NPU 频率档位

若 rknn-smi info 表格为空，多为 rknn3_transfer_proxy 异常，需先恢复代理服务：

sudo systemctl restart rknn3
sudo rknn-smi info

验证 rknn-smi 路径：

which rknn-smi

输出：

/usr/bin/rknn-smi

rknn-smi 工具可用，位于 /usr/bin/rknn-smi

实际运行 rknn-smi info 输出：

Failed to initialize rknnsmi
rknn-smi set -t npu_freq 2>&1

输出：

Failed to initialize rknnsmi

当前系统上 rknn-smi info / rknn-smi set 返回 Failed to initialize rknnsmi 错误：尽管 rknn3.service 是 active 状态，但 rknn-smi CLI 工具无法访问 RK1828 PCIe 设备（不识别 RK1828）。这不影响实际推理服务——rkllm3-server 等正常用，详见 RKLLM 设备端 LLM 推理。

systemctl status rknn3

输出（部分）：

● rknn3.service - rknn3 runtime service
     Loaded: loaded (/lib/systemd/system/rknn3.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-08-17 14:28:49 CST; 1h 0min ago
   Process: 526 ExecStart=/bin/rknn3_startup start (code=exited, status=0/SUCCESS)
   Main PID: 1790 (rknn3_transfer_)
        CPU: 15min 14.275s
     CGroup: /system.slice/rknn3.service
             ├─1790 /bin/rknn3_transfer_proxy
             └─1803 rknn3_transfer_proxy_c36211b1 -s 0004:41:00.0

rknn3.service 运行中：Active: active (running)，主进程 rknn3_transfer_proxy

驱动相关

rknn-smi 命令找不到

现象：rknn-smi: command not found

解决：

# 安装 RKNN3 运行时
sudo apt-get install -y rknn3-runtime rknn3-toolkit-lite

# 或手动安装 deb
sudo dpkg -i rknn3-runtime_*.deb

NPU 显存显示异常 / 设备无响应

解决：

# 内核模块名为 pcie-rkep（连字符），不是 pcie_rkep
sudo rmmod pcie-rkep
sudo modprobe pcie-rkep

# 若模块已编进内核（不可加载），用 rescan 方式：
echo 1 | sudo tee /sys/bus/pci/rescan
ls /dev/pcie-rkep-*

# 重启代理服务
sudo systemctl restart rknn3_transfer_proxy

验证 pcie-rkep 设备节点：

ls /dev/pcie-rkep-*

输出：

/dev/pcie-rkep-0004:41:00.0

pcie-rkep 设备节点存在：/dev/pcie-rkep-0004:41:00.0

验证 rknn3_transfer_proxy 服务：

systemctl status rknn3_transfer_proxy

输出：

Unit rknn3_transfer_proxy.service could not be found.

rknn3_transfer_proxy 是 rknn3.service 的子进程，应该用：

sudo systemctl restart rknn3   # 重启整个 rknn3 服务

验证：ls /lib/systemd/system/rknn3*（实际只有 rknn3.service）

验证 systemd 服务文件：

cat /lib/systemd/system/rknn3.service

输出：

[Unit]
Description=rknn3 runtime service
DefaultDependencies=no
After=local-fs.target

[Service]
Type=forking
ExecStart=/bin/rknn3_startup start
ExecStop=/bin/rknn3_startup stop

[Install]
WantedBy=sysinit.target

rknn3.service 启动脚本：通过 /bin/rknn3_startup 启动，最终拉起 rknn3_transfer_proxy 子进程

模型相关

RKNN3 Python 包导入

现象：from rknn3.api import RKNN3 报 No module named 'rknn3'

原因：板端安装的是 rknn3-toolkit-lite（推理），不是 rknn3-toolkit（PC 端转换）。两者 Python 模块名不同：

包用途安装位置import
rknn3-toolkitPC 端，HuggingFace / ONNX 转 .rknnx86 PC + GPUfrom rknn.api import RKNN
rknn3-toolkit-lite板端推理板子 (aarch64)from rknn3lite.api import RKNN3Lite

依赖与版本确认：

pip3 show rknn3-toolkit-lite
python3 -c "from rknn3lite.api import RKNN3Lite; print('OK')"

实际验证：

pip3 show rknn3-toolkit-lite

输出：

Name: rknn3-toolkit-lite
Version: 1.0.0
Summary: Rockchip Neural Network RKNN3 Toolkit Lite. (commit: 72e56356)
Home-page:
Author: ai@rock-chips.com
Author-Email: ai@rock-chips.com
License:
Location: /usr/local/lib/python3.11/dist-packages
Requires: numpy, transformers
Required-by:

commit hash 会随 SDK 版本变动（实测从 45eab746 → 72e56356），以版本号 1.0.0 为准即可。

python3 -c "from rknn3lite.api import RKNN3Lite; print('OK')"

输出：

OK

rknn3-toolkit-lite 1.0.0 已安装，Python 导入成功

  • 位置：/usr/local/lib/python3.11/dist-packages
  • 依赖：numpy、transformers
  • Python 版本：3.11.x（与 wheel 文件名 cp311 匹配）

模型转换失败

常见原因：

  • GPU 显存不足：LLM 模型转换建议 GPU 显存 ≥ 16 GB
  • Python 版本不匹配：wheel 文件名 rknn3_toolkit_lite-1.0.4-cp311-cp311-linux_aarch64.whl 仅提供 cp311（Python 3.11）
  • 磁盘空间不足：转换过程需要大量临时空间（建议 ≥ 30 GB）

推理速度低于预期

排查方向：

  1. 确认 NPU 利用率：sudo rknn-smi info 查看 Npu(%)、Memory-Usage(MB)
  2. 确认 NPU core mask 与模型核数匹配（LLM 8 核 → -c 0xff；CNN 1 核 → -c 1）
  3. 检查多进程抢占 NPU：ps aux | grep rknn3

验证 rknn3/rkllm 进程：

ps aux | grep -E "rknn3|rkllm" | grep -v grep

输出：

root        1790  0.2 0.2 194640  3236 ?        Sl   14:28   0:09 /bin/rknn3_transfer_proxy
root        1803 24.8 0.2 390112 23220 ?        Sl   14:28  15:05 rknn3_transfer_proxy_c36211b1 -s 0004:41:00.0

实测当前只有 2 个进程（rknn3_transfer_proxy 主+子），rkllm3-server 和 ocr_server.py 当前未运行（需手动启动）。这是动态信息，跑 rkllm3-server -m ... / bash /userdata/models/Qwen3-VL-2B/vl.sh 后会出现。

max_context_len 不够用

max_context_len 在模型转换时确定，运行时无法修改。需在 PC 上使用 RKNN3 Toolkit 重新转换：

# 这段代码必须运行在安装了 rknn3-toolkit（不是 lite）的 x86 PC 上
from rknn.api import RKNN

rknn = RKNN(verbose=True)
rknn.config(target_platform='rk1820', quantized_dtype='w8a8')
rknn.load_onnx('model.onnx')
rknn.build(do_quantization=True, dataset='./dataset.txt')
rknn.export_rknn('Qwen3-1.7B.rknn')

依赖修正：rknn3-toolkit wheel 是 x86_64 only，只能在 PC 上运行，不能在 RK3588 上转换模型

  • PC 上：from rknn.api import RKNN
  • 板端 lite：from rknn3lite.api import RKNN3Lite

rkllm3-server 相关

服务启动失败

常见原因：

  1. 模型文件路径错误：确认 .rknn / .weight / .tokenizer.gguf / .embed.bin 都存在

  2. 端口被占用：

    sudo ss -tlnp | grep 7878
rkllm3-server --port 8081 ...   # 注意是 --port（双 -），不是 -p

  3. NPU 显存不足：检查 sudo rknn-smi info 的 Memory-Usage

参数可通过 rkllm3-server --help 确认。

验证 rkllm3-server 端口监听：

ss -tlnp 2>&1 | grep 7878
curl --max-time 5 http://127.0.0.1:7878/v1/models

输出：

（无监听 — rkllm3-server 未运行）

curl: (7) Failed to connect to 127.0.0.1 port 7878: Connection refused

实测当前 rkllm3-server 未启动，ss -tlnp | grep 7878 无监听，curl /v1/models 返回 Connection refused。启动后才能看到 OpenAI 兼容 API 响应。手动启动：

rkllm3-server -m /userdata/models/Qwen3-1.7B/Qwen3-1.7B.rknn \
  --weight /userdata/models/Qwen3-1.7B/Qwen3-1.7B.weight \
  --vocab /userdata/models/Qwen3-1.7B/Qwen3-1.7B.tokenizer.gguf \
  --embed /userdata/models/Qwen3-1.7B/Qwen3-1.7B.embed.bin \
  --embed-mmap -a Qwen3-1.7B --host 127.0.0.1 --port 7878 -c 0xff -n 512 &

验证 rkllm3-server 参数（部分）：

rkllm3-server --help 2>&1 | grep -E "port|host|weight|vocab|embed"

输出：

--weight FNAME                          rknn llm model weight path
--weight2 FNAME                         rknn vision model weight path
--weight3 FNAME                         rknn audio model weight path
--vocab FNAME                           vocab path
--embed FNAME                           embed path
--embed-mmap                            Whether to use mmap method to access embed.bin file?
--embedding                             restrict to only support embedding use case; use only with dedicated
                                        embedding models (default: disabled)

rkllm3-server 参数验证：以上输出可见的参数名包括 --weight、--vocab、--embed 等（不含 --port/--host，启动命令中的端口与主机参数以板端实际 --help 为准）

API 响应慢

排查方向：

  1. 确认 NPU 是否被其他进程占用：ps aux | grep -E "rknn3|rkllm"

  2. 检查网络延迟（远程调用时）

  3. 减小 max_tokens 参数（对应 --n-predict / -n）：

    rkllm3-server -m ... --n-predict 256

ClawChips / Agent 相关

pip install 报 externally-managed-environment

Debian 12 启用了 PEP 668，需加 --break-system-packages：

pip3 install --break-system-packages <package>

rknn3-toolkit-lite 安装后 import 失败

确保 Python 版本与 wheel 匹配：

python3 --version            # 需为 Python 3.11.x
pip3 show rknn3-toolkit-lite # 确认包名与版本
python3 -c "from rknn3lite.api import RKNN3Lite; print('OK')"

VLM 服务健康检查

首次加载模型需要约 10 秒，等待后重试：

curl http://127.0.0.1:7879/health
# 返回 {"status":"ok","model":"Qwen3-VL-2B"} 表示就绪

实际验证：

curl --max-time 5 http://127.0.0.1:7879/health

输出：

curl: (7) Failed to connect to 127.0.0.1 port 7879: Connection refused

实测 VLM server 当前未启动。手动启动：

bash /userdata/models/Qwen3-VL-2B/vl.sh

验证 VLM 模型文件：

ls -lh /userdata/models/Qwen3-VL-2B/

输出：

总计 1.9G
-rwxr-xr-x 1 root   root   8.1K  8月10日 14:34 inspect.sh
-rw-r--r-- 1 linaro linaro  20M  8月17日 13:51 llm_Qwen3-VL-2B.rknn
-rw-r--r-- 1 linaro linaro 1.1G  8月17日 13:52 llm_Qwen3-VL-2B.weight
-rw-r--r-- 1 linaro linaro 3.0K  8月11日 22:53 OCRBench.py
-rw-r----- 1 root   root    11K  8月17日 15:24 ocr_server.py
-rwxr-xr-x 1 root   root   1.1K  8月10日 14:34 ocr.sh
drwxr-xr-x 4 linaro linaro 4.0K  8月17日 15:22 PaddleOCR-VL
-rw-r--r-- 1 linaro linaro 594M  8月17日 13:55 Qwen3-VL-2B.embed.bin
-rwxr-xr-x 1 linaro linaro 240K  8月20日 14:00 test.jpg
drwxr-xr-x 2 linaro linaro 4.0K  8月 5日 17:04 tokenizer
-rw-r--r-- 1 linaro linaro 4.2M  8月17日 13:50 vision_Qwen3-VL-2B.rknn
-rw-r--r-- 1 linaro linaro 229M  8月17日 13:54 vision_Qwen3-VL-2B.weight
-rw-r----- 1 root   root    11K  8月17日 14:01 vlm_server.py
-rwxr-xr-x 1 root   root    913  8月10日 14:34 vl.sh

VLM 模型文件已下载：

  • llm_Qwen3-VL-2B.rknn（20 MB）+ .weight（1.1 GB）
  • vision_Qwen3-VL-2B.rknn（4.2 MB）+ .weight（229 MB）
  • Qwen3-VL-2B.embed.bin（594 MB）
  • tokenizer/（词表目录）
  • PaddleOCR-VL/（OCR 模型目录）
  • 服务脚本：vlm_server.py、ocr_server.py
  • test.jpg（240 KB）— 测试图，可用于 VLM 健康检查

VLM 与本地 LLM 共存

VLM（rk-vl skill）使用 rknn3-toolkit-lite Python API，约占 2 GB NPU 内存，剩余约 3 GB 可用于其他用途。若同时运行 rkllm3-server（本地 LLM），两者会争抢 NPU 内存，可能导致不稳定。推荐方案：VLM 走本地 NPU，对话走云端 API。

setup.sh --reconfig 选项

bash setup.sh --reconfig
# 选项：
#   1) 云端模型 API Key
#   2) QQ Bot 凭证
#   3) 全部重新配置（1 + 2）
#   4) 安装 / 重装 VLM 图片识别
#   0) 取消

验证 setup.sh reconfig 选项：

grep -E "echo.*[0-9]\)" ~/lobster-pkg/setup.sh

输出：

    echo "    ${BOLD}1)${NC} DeepSeek（推荐，性价比高）"
    echo "    ${BOLD}2)${NC} 通义千问（阿里云）"
    echo "    ${BOLD}3)${NC} OpenAI"
    echo "    ${BOLD}4)${NC} 自定义（兼容 OpenAI 格式的任意服务）"
    echo "    ${BOLD}5)${NC} MiniMax (MiniMax, Anthropic 兼容)"
    echo "    ${BOLD}1)${NC} 云端模型 API Key"
    echo "    ${BOLD}2)${NC} QQ Bot 凭证"
    echo "    ${BOLD}3)${NC} 全部重新配置"
    echo "    ${BOLD}4)${NC} VLM 图片识别（安装/重装）"
    echo "    ${BOLD}0)${NC} 取消"

setup.sh 选项确认：reconfig 菜单包含 4) VLM 图片识别（安装/重装）

选项 5 实测描述为 "MiniMax (MiniMax, Anthropic 兼容)"，文档示例写"MiniMax（MiniMax-M3）"已过时，以脚本实际输出为准。

GitHub 下载慢

脚本内置 jsdelivr CDN 加速（cdn.jsdelivr.net/gh/...），自动回退到 GitHub raw：

https://cdn.jsdelivr.net/gh/airockchip/rknn3-toolkit@main/rknn3-toolkit-lite/packages/rknn3_toolkit_lite-1.0.4-cp311-cp311-linux_aarch64.whl

若仍慢，可在 PC 上下载后通过 scp 传到板子手动安装：

pip3 install --break-system-packages <wheel 文件>

其他

PowerShell 中 git log 显示乱码

设置系统环境变量：

LESSCHARSET = utf-8

反馈渠道

  • GitHub Issues：https://github.com/airockchip/clawchips/issues
  • 邮箱：support@shimetapi.com