基于易百纳玄武S3（RK3588+RK182X平台）部署llama-rknn3-server示例

硬件平台：易百纳玄武S3

简介

本文主要介绍llama-rknn3-server示例在Ebaina玄S3边缘计算AI终端上的交叉编译、板端部署与运行验证方法。该示例基于llama.cpp Web UI和OpenAI兼容接口提供统一入口，实际推理由板端rkllm3-server完成，面向RK3588+RK182平台，可在完全离线的端侧运行大模型对话。

服务启动后包含两个进程：

• llama-server：对外提供 Web UI、健康检查及 OpenAI 兼容接口，默认监听 0.0.0.0:18080；
• rkllm3-server：本机后端模型服务，默认监听127.0.0.1:8082，由llama_server_startup启动、停止和切换模型。

说明：deb包只包含应用二进制、运行脚本、动态库和systemd服务文件，不包含模型文件，也不包含rkllm3-server本体，需板端提前安装 rkllm3-server。

示例功能：

• 提供Web UI对话界面（默认监听0.0.0.0:18080），支持文本与图片多轮对话；
• 模型下拉框位于输入框右下角，可在多个模型之间切换；切换时llama-server调用llama_server_startup switch <model>重启后端rkllm3-server；
• 自动识别视觉模型（模型目录中含*vision*/*vl*的.rknn），选择视觉模型后可在Web UI上传图片问答；
• 支持多卡分段级联模型（xxx_seg0.rknn/xxx_seg1.rknn…），分段数与NPU卡数一一对应，可体验更大参数量模型。

整体流程分为三步：

1. 在x86编译服务器上准备llama.cpp源码、交叉编译并打包生成arm64 deb包；
2. 将deb包推送到板端安装，将模型推送到板端/userdata/models目录；
3. 启动llama-rknn3-server服务，通过Web UI与OpenAI兼容接口验证对话与推理效果。

环境准备

1. 准备 llama.cpp 源码

将llama.cpp.tar.gz（网盘资料获取）放到<SDK>/applications/llama-rknn3-server/ 目录下解压，再执行准备脚本：

cd applications/llama-rknn3-server
tar -xvf llama.cpp.tar.gz
# 执行准备脚本：应用本地补丁、校验版本
bash scripts/prepare-llama-cpp.sh

2. 编译

设置交叉编译工具链后执行编译脚本：

cd <SDK>/applications/llama-rknn3-server
# 工具链路径以本机实际位置为准
export AARCH64_TOOLCHAIN=/<toolchain实际路径>/toolchain/aarch64-none-linux-gnu
bash scripts/build-linux.sh -DGGML_CCACHE=OFF

编译输出

编译完成后，运行产物会暂存到：

install/llama-rknn3-server/

暂存目录中的主要文件包括：

• usr/bin/llama-server
• usr/bin/llama_rkllm3_server_run
• usr/bin/llama_server_startup
• usr/lib/lib*.so.0
• usr/lib/libllama-server-impl.so

3. 打包

执行打包脚本生成 arm64 deb 包：

cd <SDK>/applications/llama-rknn3-server
bash scripts/package-deb.sh

默认生成： out/llama-rknn3-server_1.0.0_arm64.deb，out/llama-rknn3-server_1.0.0_arm64.deb.sha256。

deb 安装后的系统路径如下：

4. 板端安装

以下命令使用通用 ADB 写法，适用于已连接的 ADB 设备（也可在板端 shell 中直接执行对应命令）：

# PC端推送deb包到板端任意目录
adb push <\out\llama-rknn3-server_1.0.0_arm64.deb> /userdata
cd userdata/
# 板端安装
dpkg -i llama-rknn3-server_1.0.0_arm64.deb

5. 板端模型部署

将模型目录推送到板端/userdata/models下（本例以Qwen3.5-4B为例，亦支持Qwen2.5-3B等其他RKLLM模型）：

# 将模型目录推送到板端/userdata/models目录下
adb push <Qwen3.5-4B> /userdata/models

6. 运行

# 运行
systemctl start llama-rknn3-server
# 停止
systemctl stop llama-rknn3-server
# 重启
systemctl restart llama-rknn3-server

查看服务状态：

systemctl status llama-rknn3-server --no-pager
/usr/bin/llama_server_startup status
 /usr/bin/llama_server_startup pid

查看日志：

journalctl -u llama-rknn3-server -n 100 --no-pager
cat /run/llama-rknn3-server/rkllm3.log

7. Web访问对话

服务启动后，在PC浏览器访问：

http://<board-ip>:18080

本例为：http://192.168.1.168:18080/（请替换为你板端的实际IP地址）。

如图所示可以进行对话，对话框右下角可以选择模型：

8. 测试

基础接口测试

curl -sS http://<board-ip>:18080/health
curl -sS http://<board-ip>:18080/v1/models

Web UI静态资源默认使用压缩响应，命令行测试首页时建议加--compressed：

curl --compressed -sS -o /tmp/llama-rknn3-ui.html -w '%{http_code}\n' http://<board-ip>:18080/

文本问答测试

curl -sS http://<board-ip>:18080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model-id-from-v1-models>",
    "messages": [
      {
        "role": "user",
        "content": "你好，请用一句话介绍你自己。"
      }
    ],
    "stream": false
  }'

图片问答测试建议直接使用Web UI：选择视觉模型后，在输入框区域上传图片并提问。

常见问题

1. 服务启动失败：先检查rkllm3-server是否可执行：adb shell which rkllm3-server；
2. Web UI 无法访问：检查llama-rknn3-server.service是否处于active，并确认板端18080端口未被其他服务占用（ss -ltnp | grep 18080）。
3. 后端异常退出：systemd 会将服务判定为失败并按 Restart=on-failure 自动重启。可通过journalctl -u llama-rknn3-server -n 100 --no-pager和/run/llama-rknn3-server/rkllm3.log查看具体原因。
4. 编译时报 llama.cpp has local changes：说明 llama.cpp 工作区有未提交改动，先恢复干净再编译：git -C llama.cpp reset --hard HEAD git -C llama.cpp clean -fd git -C llama.cpp status --short 或将llama.cpp目录备份移走后重新执行bash scripts/prepare-llama-cpp.sh --force。