RK3588RKLLama部署

RKLLama Docker 部署指南 (RK3588/RK3576)

本文档旨在帮助您在 Rockchip RK3588/RK3576 平台上，通过 Docker 快速部署支持 NPU 加速的 LLM 服务。

1. 前置检查

在部署之前，请确保宿主机的 NPU 驱动正常，因为 Docker 容器需要依赖宿主机的内核驱动。

# 检查 NPU 驱动版本
cat /sys/kernel/debug/rknpu/version

  • 要求: 驱动版本建议 >= 0.9.6。如果版本过低，建议升级开发板固件。

2. 部署配置 (Docker Compose)

我们推荐使用 Docker Compose 进行管理，这样可以固化启动参数，避免每次输入长命令。

2.1 创建目录结构

在您的宿主机上创建一个文件夹（例如 ~/rkllama_docker），结构如下：

~/rkllama_docker/
├── docker-compose.yml # 服务配置文件
├── deploy.sh # 一键启动脚本
└── models/ # [自动创建] 存放模型文件的目录

2.2 配置文件 docker-compose.yml

请将以下内容保存为 docker-compose.yml：

version: ‘3.8’

services:
rkllama:
image: ghcr.io/notpunchnox/rkllama:main
container_name: rkllama
restart: unless-stopped

\# \[关键\] 必须开启特权模式，否则容器无法访问 NPU 和 DMA Buffer  
privileged: true  
  
\# 端口映射：API 服务端口 (兼容 Ollama API)  
ports:  
  \- "8080:8080"  
  
\# 目录挂载：  
\# 左边 ./models 是宿主机路径 (您存放 .rkllm 文件的地方)  
\# 右边 /opt/rkllama/models 是容器内固定路径 (不可修改)  
volumes:  
  \- ./models:/opt/rkllama/models  
  
\# 环境变量配置  
environment:  
  \# RKNPU\_VERBOSE=1 可开启 NPU 底层日志，生产环境可注释掉  
  \- RKNPU\_VERBOSE=1  
  \- TZ=Asia/Shanghai  
  
\# 设备节点映射 (开启 privileged 后可选，但显式声明更清晰)  
devices:  
  \- /dev/dri:/dev/dri  
  \- /dev/rga:/dev/rga  
  \- /dev/dma\_heap:/dev/dma\_heap

\# 健康检查  
healthcheck:  
  test: \["CMD", "curl", "-f", "http://localhost:8080/api/version"\]  
  interval: 30s  
  timeout: 10s  
  retries: 3

3. 快速启动

您可以直接运行 docker compose up -d，或者使用下面的脚本来确保目录权限正确。

3.1 一键启动脚本 deploy.sh

#!/bin/bash

# 1. 自动创建模型目录
if [ ! -d “./models” ]; then
echo “📂 正在创建本地模型目录: ./models”
mkdir -p ./models
fi

# 2. 启动服务
echo “🚀 正在启动 rkllama…”
docker compose up -d || docker-compose up -d

# 3. 实时查看日志
echo “📋 服务已启动，正在查看日志 (按 Ctrl+C 退出)…”
sleep 2
docker logs -f rkllama

给脚本执行权限并运行：

chmod +x deploy.sh
./deploy.sh

4. 添加与加载模型

RKLLama 容器启动后，它会自动监视挂载的 ./models 目录。

4.1 手动添加模型 (离线模式)

  1. 创建模型子目录:
    在 ./models 下为每个模型创建一个文件夹。
    mkdir -p models/my-qwen-model

  2. 放入文件:
    将下载好的 .rkllm 文件和分词器配置文件（tokenizer.json 等）放入该文件夹。

    • 如果没有分词器文件，必须确保开发板能联网。

  3. 创建 Modelfile:
    在文件夹内创建 Modelfile 文件：
    FROM=”your-model.rkllm”
    # 联网下载 Tokenizer 配置:
    HUGGINGFACE_PATH=”Qwen/Qwen2.5-3B-Instruct”
    # 或者使用本地 Tokenizer:
    # TOKENIZER=”.”

  4. 加载模型:
    # 在宿主机执行，让容器内的客户端加载模型
    docker exec -it rkllama rkllama load my-qwen-model

4.2 自动下载模型 (在线模式)

进入容器使用交互式命令下载：

docker exec -it rkllama rkllama pull

根据提示输入 HuggingFace 的 Repo ID 和文件名即可。

5. 验证与监控

5.1 验证 NPU 是否工作

在宿主机上使用监控命令：

sudo watch -n 1 “cat /sys/kernel/debug/rknpu/load”

当您与模型对话时，如果 NPU 负载跳动（> 0%），说明 Docker 穿透成功。

5.2 测试 API

默认 API 地址为 http://localhost:8080。

curl -X POST http://localhost:8080/api/chat \
-H “Content-Type: application/json” \
-d ‘{
“model”: “my-qwen-model”,
“messages”: [{“role”: “user”, “content”: “你好”}],
“stream”: false
}’

6. 常见问题

  • Error: Model directory not found:
    • 原因：宿主机的 ./models 目录下没有对应的子文件夹。
    • 解决：确保模型文件放在 ./models/<模型名>/ 里面，而不是直接放在根目录。
  • NPU 占用率为 0%:
    • 原因：Docker 容器没有权限。
    • 解决：确保 docker-compose.yml 中包含 privileged: true。
  • Tokenizer not found:
    • 原因：缺少分词器配置文件且无法联网。
    • 解决：手动下载以下文件放入模型目录，并在 Modelfile 中指定 TOKENIZER=”.”。
      • tokenizer.json (核心文件)
      • tokenizer_config.json (配置参数)
      • special_tokens_map.json (特殊字符映射)
      • config.json (可选，部分模型需要)

7. 常用模型管理命令

在宿主机上，您可以通过 docker exec 执行以下命令来管理容器内的模型：

功能 命令 说明
查看列表 docker exec -it rkllama rkllama list 列出所有已安装的模型
运行对话 docker exec -it rkllama rkllama run <模型名> 启动交互式命令行对话
加载模型 docker exec -it rkllama rkllama load <模型名> 仅将模型加载到 NPU 内存 (不进入对话)
卸载模型 docker exec -it rkllama rkllama unload 卸载当前运行的模型，释放 NPU 内存
查看详情 docker exec -it rkllama rkllama info <模型名> 查看模型的元数据信息
删除模型 docker exec -it rkllama rkllama rm <模型名> 删除指定模型文件
下载模型 docker exec -it rkllama rkllama pull 交互式从 Hugging Face 拉取模型