Welcome to Firefly
中文
中文

ClawChips RK3588+RK1828: Compute Decoupling & Edge-Cloud Architecture

Keeper

ClawChips 介绍与部署指南

ClawChips 是什么

ClawChips 是瑞芯微开源的端侧 Agent 部署参考方案（仓库：github.com/airockchip/clawchips），核心是在 RK3588+RK1828 双芯边缘设备上提供一个端侧 LLM 网关（RKClawServer）——以标准 OpenAI 兼容接口对外提供服务，各类 Agent 框架均可将其作为标准 LLM provider 接入。

与纯云端方案的区别在于：系统根据任务复杂度对请求进行本地/云端分流。高频、轻量、实时性要求高的任务优先在本地 RK1828 完成（本地推理零 Token 成本）；长上下文深度思考与复杂任务规划则交由云端处理。由此云端资源可集中于复杂理解与高质量生成，整体交互成本显著下降。

架构：主控 + 协处理器

RK3588 虽集成 6 TOPS NPU，但大语言模型推理属于典型的**内存带宽受限（memory wall）**负载：自回归解码阶段每生成一个 token 均需完整遍历模型权重，推理耗时主要集中于内存访问而非算术运算——公开分析口径下，该比例可达 80% 以上。RK3588 的模型权重存放于外置 LPDDR4/4X，其带宽与 7B 级模型流畅推理所需相差一个数量级。

RK1828 的解决方案是采用 3D 堆叠封装，将高带宽内存直接集成于芯片封装内部：

对比项RK3588（主控）RK1828（协处理器）
定位通用 SoC：系统、Agent 运行环境、感知输入/执行输出、外设专职 AI 推理加速外设
NPU 算力6 TOPS INT8（通用视觉/检测为主）20 TOPS INT8（Transformer 原生优化，INT4 可达 40 TOPS）
内存外置 LPDDR4/4X片内 5GB 3D 堆叠 LPDDR4X（与兆易创新定制）
内存带宽—理论 1024 GB/s，约为 RK3588 外置内存带宽的 20 倍（官方对比口径）
调度核心4×A76 + 4×A553×64 位独立 RISC-V（NPU 任务调度/预处理，不占主控 CPU）
功耗—典型满载推理约 5W，无源散热可稳定运行
接口/形态—PCIe 2.0 x1 ×2、USB 3.0；M.2 2280 / SO-DIMM
支持模型上限传统小模型0.5B~7B LLM/VLM（Qwen、LLaMA、Gemma、DeepSeek 等）

该架构对存量设备升级尤为友好：主控 SoC、操作系统与外设均无需改动，插入一块 M.2 算力卡即可补足大模型推理能力；且 RK1828 具备独立内存与供电域，推理过程不占用主控内存带宽。其本质是经由专用数据通路实现的算力解耦，而非共享总线意义上的算力叠加。

三大核心模块与数据流转

整套架构由三大模块构成：RK1828（端侧推理）、RK3588（Agent 运行环境与数据底座）、云端大模型（Token 套餐），数据流转如下：

                  ┌──────────────────── RK3588 Main SoC ─────────────────────┐
                  │  Agent Harness (Nanobot) · Skills · Perception I/O ·     │
                  │  Private Data Storage                                    │
                  └─────────┬────────────────────────────────────┬───────────┘
       Lightweight / high-frequency /                   Complex / long-context
       latency-sensitive tasks                                    tasks
                            ▼                                      ▼
           RKClawServer (OpenAI-compatible gateway, :8081)       Cloud LLM
                            │
                            ▼
                     RK1828 Co-processor
                (RKNN3 Toolkit Lite · 20 TOPS NPU)
  1. 轻量化任务：主控下发至 RKClawServer，由 RK1828 本地完成推理，不产生云端调用；
  2. 高复杂度任务：经智能路由上传云端服务器，由云端大模型完成深度运算；
  3. 记忆路由：请求优先复用本地记忆库命中结果，命中即不产生新的推理调用；
  4. 通过双向任务调度形成端云一体协同，全链路支持带隐私计算能力的端云协同 AI 推理。

RKClawServer：面向 Agent 的完整推理运行时

RKClawServer（v0.7.0）是方案的核心枢纽：向上对 Agent Harness 暴露标准 OpenAI 兼容接口，向下管理 RKNN3 推理后端。能力构成如下：

接口层（OpenAI 兼容）

端点用途
POST /v1/chat/completions多轮对话，同步 JSON 与 SSE 流式输出
GET /v1/models查询当前已加载模型
GET /healthzHTTP 进程存活检查
GET /readyzTokenizer / 模型 / RKNN Session 初始化就绪检查

面向 Agent 负载的专项优化（以下能力为通用推理服务所不具备）：

  • 支持 thinking 输出与 tool results 回传；
  • 支持并行 tool calls，内置 ToolCall 纠错机制——模型输出的畸形工具调用将被自动修正而非直接报错，该机制对 Agent 多轮循环的鲁棒性至关重要；
  • 可选 XGrammar 约束生成，保证 JSON 类结构化输出合法；
  • KV-Cache 持久化：自动保存/加载 KV cache 以降低首会话时延（前提为 system marker 与当前系统提示词一致）；
  • 另提供请求排队、健康检查、日志与会话管理、配置管理及内置 WebUI 等完整运行时能力。

运维面板：http://<device-ip>:8081/webui/，含 Dashboard（请求/Token/时延统计，1 小时~30 天趋势）、会话日志检索与 JSON 导出、服务器日志过滤、表单/TOML 双模式配置编辑。

Agent Harness 与 Skills 生态

Agent 层采用 Nanobot（组件版本 0.2.2），默认对接本地模型 http://127.0.0.1:8081/v1，WebUI 端口 :8765。v0.7.0 已支持纯 WebUI 完整操作，无需命令行。

端侧 Skills（部署于 /userdata/skills）：

Skill能力关键参数
rk-ocr图像文字提取—
rk-asr语音转写RTF ≈ 0.2，单任务超时 1200 秒，支持约 50 分钟录音
Qwen3-VL图像理解/画面描述OCR 无法提取时自动兜底调用

交互渠道：WebUI 之外原生支持 QQ（开放平台 Bot）、微信（扫码登录）、飞书（扫码建 Bot）三类渠道，配置后重启即可接入。

浏览器能力（实验性）：安装可选浏览器组件后，可将设备端浏览器页面同步至 WebUI，支持 Agent 打开网址、读取页面内容并操作浏览器，相当于在端侧提供一个可被 Agent 驱动的浏览器运行环境。

智能路由与 Token 节省机制

ClawChips 的成本管控由三层机制叠加实现：

  1. 记忆库优先：接收到请求后优先检索本地记忆库，命中则直接复用结果，不触发推理；
  2. 本地分流：轻量任务（代码注释、短文本改写、命名建议等）路由至 RK1828，本地推理零 Token 成本；
  3. 云端按需：仅复杂任务消耗云端 Token。

官方基于 PinchBench 的实测口径：可节省约 40% 云端模型消耗。该数值的适用前提为请求分布中轻量任务占比较高（如编程助手、日常问答类场景）；若业务以长文档深度分析为主，实际节省比例将明显低于该值，选型时建议基于自身真实请求分布进行基准验证。

部署实操

环境要求

项目要求
设备RK3588 + RK1828，aarch64
操作系统Debian 12 或兼容环境
PythonCPython 3.11（/usr/bin/python3）
GLIBC≥ 2.27（推荐 2.36）
基础服务rknn3.service 处于 active 状态

环境自检：

uname -m
cat /etc/os-release
/usr/bin/python3 --version
ldd --version | head -1
systemctl is-active rknn3.service

三种安装方式

方式适用场景
固件烧录首次部署，整镜像刷写（RKDevTool V3.41 / upgrade_tool V2.55，MASKROM 模式）
App Portal已有固件系统：访问 http://<device-ip>:18090，应用列表中一键安装并启动
手动部署开发与定制集成，分别部署 RKClawServer 与 Agent Harness

手动部署 RKClawServer

准备模型（默认 AgentModel-V3.1-4B，四个文件须来自同一导出，不可混用版本）：

sudo mkdir -p /userdata/AgentModel-V3.1-4B-RKNN
sudo cp -a models/AgentModel-V3.1-4B-RKNN/. /userdata/AgentModel-V3.1-4B-RKNN/
cd /userdata/AgentModel-V3.1-4B-RKNN && md5sum -c md5sum.txt

安装并启动（install.sh 会检查架构、Python 版本、rknn3.service 状态，安装 Toolkit Lite 1.1.0 与 RKClawServer，并拉起 rkclaw-server.service）：

cd <release-package-root>/packages/rk-claw-server-0.3.2-linux-aarch64
sha256sum -c SHA256SUMS
sudo cp gateway.toml /clawchips/RKClawServer/gateway.toml
chmod +x install.sh && sudo ./install.sh

验证（部署成功判据：/healthz、/readyz 返回成功，/v1/models 返回配置的模型信息）：

systemctl status rkclaw-server.service --no-pager
curl -sS http://127.0.0.1:8081/healthz
curl -sS http://127.0.0.1:8081/readyz
curl -sS http://127.0.0.1:8081/v1/models

Agent（Nanobot）部署

# 部署端侧 Skills
sudo mkdir -p /userdata/skills
sudo cp -a resources/skills/. /userdata/skills/

# 安装并验证
cd <release-package-root>/packages/nanobot-ai-0.2.2-rk3588-20260815
chmod +x install.sh verify.sh
./install.sh && ./verify.sh --installed

WebUI 初始密码 clawchips（写入 ~/.nanobot/config.json，生产部署务必修改）。端口总览：8081（RKClawServer）→ 18090（App Portal）→ 18790（Nanobot gateway）→ 8765（Nanobot WebUI）。

完整安装、配置、排障步骤见官方 User Guide：docs/Rockchip_RK1820_RK1828_User_Guide_ClawChips_CN.md（仓库 github.com/airockchip/clawchips）。

简体中文