常见问题

硬件相关

PCIe 设备未识别

现象：lspci | grep Rockchip 无输出

排查步骤：

  1. 确认金手指是否插紧
  2. 确认 RK1828 供电线缆已连接（需要独立供电）
  3. 确认 PCIe 插槽模式配置是否正确
  4. 查看系统日志：dmesg | grep pci

NPU 温度过高

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

建议：

  1. 检查散热片/风扇是否正常
  2. 确认环境通风
  3. 降低推理频率或减少并发

驱动相关

rknn-smi 命令找不到

现象：rknn-smi: command not found

解决：

# 安装 RKNN3 运行时
sudo dpkg -i rknn3-runtime_*.deb

NPU 显存显示异常

解决：

# 重新加载驱动
sudo rmmod pcie_rkep
sudo modprobe pcie_rkep

模型相关

模型转换失败

常见原因：

  • GPU 显存不足：LLM 模型转换建议 GPU 显存 ≥ 16GB
  • Python 版本不匹配：RKNN3 Toolkit 仅支持 3.10 和 3.12
  • 磁盘空间不足：转换过程需要大量临时空间

推理速度低于预期

排查方向：

  1. 确认 NPU 利用率：rknn-smi info 查看 Npu(%)
  2. 确认上下文长度设置是否合理
  3. 检查是否有多进程抢占 NPU

max_context_len 不够用

说明：max_context_len 在模型转换时确定，运行时无法修改。

解决：重新使用 RKNN3 Toolkit 转换模型，设置更大的 max_context_len：

from rknn3.api import RKNN3

rknn3 = RKNN3()
rknn3.load_huggingface(model="Qwen/Qwen3-1.7B")
rknn3.build(
    target="rk1828",
    quantization="w8a8",
    max_context_len=32768,  # 增大上下文
)
rknn3.export("Qwen3-1.7B.rknn")

rkllm3-server 相关

服务启动失败

常见原因：

  • 模型文件路径错误
  • 端口被占用：更换端口 --port 8081
  • NPU 显存不足：检查 rknn-smi info 的 Memory-Usage

API 响应慢

排查方向：

  1. 确认 NPU 是否被其他进程占用
  2. 检查网络延迟（如果是远程调用）
  3. 减小 max_tokens 参数

ClawChips / Agent 相关

Q: pip install 报错 "externally-managed-environment"

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

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

Q: rknn3-toolkit-lite 安装后 import 失败

确保 Python 版本正确，且 wheel 文件匹配：

python3 --version
pip3 show rknn3-toolkit-lite

Q: VLM 服务启动后健康检查超时

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

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

如果持续超时，检查模型文件是否完整：

ls -lh /userdata/models/Qwen3-VL-2B/*.rknn /userdata/models/Qwen3-VL-2B/*.weight /userdata/models/Qwen3-VL-2B/*.bin

Q: VLM 和本地 LLM 能同时运行吗？

可以。VLM（rk-vl skill）使用 rknn3-toolkit-lite Python API，约占 2GB NPU 内存。剩余 ~3GB 可用于其他用途。

但如果同时运行 rkllm3-server（本地 LLM），两者会争抢 NPU 内存，可能导致不稳定。推荐方案：VLM 走本地 NPU，对话走云端 API。

Q: setup.sh --reconfig 怎么用？

bash setup.sh --reconfig
# 选择：
#   1) 换云端 API Key
#   2) 换 QQ Bot 凭证
#   3) 全部重新配置
#   4) 安装/重装 VLM 图片识别

Q: GitHub 下载很慢怎么办？

脚本内置了 jsdelivr CDN 加速（cdn.jsdelivr.net/gh/...），自动回退到 GitHub raw。如果都很慢：

  1. 在 PC 上下载文件
  2. 通过 scp 传到板子
  3. 手动安装

其他

PowerShell 中 git log 显示乱码

解决：

设置系统环境变量 LESSCHARSET = utf-8

如何提交反馈

如有问题或建议，请通过以下方式联系：

  • 提交 Issue
  • 邮件联系