Skip to content
qiaoruihao-coderPublic

About

rk3588--输出 Token 强制控制&模型运行时动态控制

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

执行人组 1.1 模块 —— 输出 Token 强制控制 + 模型运行时动态控制

作者:乔瑞浩、张倬铭 位置:L1 执行人层 部署目标:RK3588(ARM + NPU 6 TOPS + 4GB 统一内存) 状态:可交付


目录


文件夹结构

RK3588版 1.1模块/
│
├── sglang_1_1_module.py          1.1 模块主文件(RK3588 NPU 版,正式部署)
│
├── 🧠 dynamic_control/            动态控制系统(核心亮点)
│   ├── __init__.py                包入口
│   ├── config.py                  阈值配置(环境变量可覆盖)
│   ├── monitor.py                 指标采集(温度/频率/内存/NPU,sysfs)
│   ├── evaluator.py               4 级状态机 + 滞回控制
│   ├── actuator.py                调控执行(调频/切后端/调参)
│   ├── backends.py                推理后端(RKLLM 本地服务 + CPU 兜底)
│   └── controller.py              统一入口 DynamicController
│
├── test_dynamic_control.py       集成测试(8 用例)
├── demo_dynamic_control.py       6 场景决策演示
│
├── run_rk3588.sh                 RK3588 一键启动脚本
├── SETUP_RK3588.md               上板适配指南(10 步)
├── export_onnx.py                模型转换①:→ ONNX(旧 .rknn 路线,参考用)
├── convert_rknn.py               模型转换②:ONNX → .rknn(旧 .rknn 路线,参考用)
├── 模型转换说明.md                模型转换独立文档(现推荐 RKLLM .rkllm 路线)
├── architecture_diagrams.html    7 张架构图/流程图(浏览器打开截图)
├── .gitignore                    忽略模型/缓存/虚拟环境
│
├── README.md                     本文件
└── 说明.txt                      提交内容说明

快速开始

1.1 模块主文件(RK3588 NPU)

一行直接跑主文件自带的完整演示(会输出 5 个 API 的结果 + 批测):

python sglang_1_1_module.py

一行导入并返回系统状态(给调度员用):

python -c "from sglang_1_1_module import get_health; print(get_health())"

环境变量(可选):

export RKLLM_BASE_URL=http://127.0.0.1:8080  # 指定 RKLLM 服务地址
export RKLLM_MODEL=myqwen                     # 指定模型名(可选)
export RK3588_TEMP_WARN_C=60                    # 自定义温度阈值

动态控制版(底层 API,更细粒度控制)

# 直接跑动态控制 6 场景决策演示
python demo_dynamic_control.py

# 跑底层 DynamicController 的集成测试(8 用例)
python test_dynamic_control.py

五个 API 函数

函数 功能 示例
generate_json(prompt, schema) JSON Schema 约束 {"name":"张三","age":20}
generate_json_pydantic(prompt, model) Pydantic 类型安全 同上 + 类型校验
generate_label(prompt, labels) 分类标签约束 "defective"
generate_value(prompt, schema) 数值+结论约束 {"area":12.5,"quality":"defective"}
generate_diff(prompt, old_code) 代码 Diff 补丁 --- a/code\n+++ b/code\n...

所有函数支持 retries 参数(默认 3 次)。

场景模板

工业检测 schema(这是 JSON 数据,可直接复制使用):

{
  "type": "object",
  "properties": {
    "defect_type": { "type": "string", "enum": ["crack", "scratch", "dent", "none"] },
    "area_mm2":    { "type": "number" },
    "severity":    { "type": "string", "enum": ["minor", "moderate", "critical"] },
    "quality":     { "type": "string", "enum": ["qualified", "defective"] }
  },
  "required": ["defect_type", "area_mm2", "severity", "quality"]
}

交通监控 schema(直接复制使用):

{
  "type": "object",
  "properties": {
    "vehicle_count": { "type": "integer" },
    "avg_speed_kmh": { "type": "number" },
    "status":        { "type": "string", "enum": ["smooth", "slow", "congested", "blocked"] },
    "action":        { "type": "string", "enum": ["none", "adjust_timing", "alert_police"] }
  },
  "required": ["vehicle_count", "avg_speed_kmh", "status", "action"]
}

动态控制系统

设计目标

RK3588 三核异构 (CPU + GPU + NPU),4GB 内存。根据 NPU 使用率、芯片温度、内存占用,实时自动调整推理后端、上下文长度、max_tokens、NPU 频率。

架构

调度员 (2.1) ──调用──▶ DynamicController
                         ├── Monitor   (采集: 温度/频率/内存/NPU)
                         ├── Evaluator (决策: 4级状态机 + 滞回)
                         ├── Actuator  (执行: 调频/切后端/调参)
                         └── Backend   (推理: RKLLM 本地服务 / CPU 兜底)

每次请求自动执行 采集→决策→执行→路由→推理,前4步 < 1ms,请求触发(无后台线程)。

四级状态机

IDLE ──(NPU<10%)──▶ NORMAL ──(NPU>90% 或 温度>65°C)──▶ WARNING ──(温度>75°C 或 内存<300MB)──▶ CRITICAL
  ▲                    ▲                                  ▲                                      │
  └────(30s 稳定)──────┴────────(30s 恢复)────────────────┴────────────(60s 恢复)──────────────────┘
  • 升级即时生效(不等待,立刻保护硬件)
  • 降级需稳定 N 秒(防抖动,避免在阈值附近反复横跳)

决策对照表

场景 NPU% 温度 可用内存 等级 后端 Context Tokens NPU频率
正常 40% 45°C 1.5 GB NORMAL NPU 2048 200 high
NPU 过载 95% 55°C 1.0 GB WARNING NPU 1024 100 mid
温度告警 50% 68°C 0.8 GB WARNING NPU 614 100 mid
内存不足 20% 50°C 0.2 GB CRITICAL CPU 512 50 low
CPU 过热 10% 86°C 1.0 GB CRITICAL refuse — — —
空闲 5% 40°C 2.0 GB IDLE NPU 2048 200 high

默认阈值

参数 值 环境变量
温度告警 65°C RK3588_TEMP_WARN_C
温度临界 75°C RK3588_TEMP_CRIT_C
内存告警 0.6 GB RK3588_MEM_WARN_GB
内存临界 0.3 GB RK3588_MEM_CRIT_GB
NPU 过载 90% RK3588_NPU_UTIL_WARN_PCT
滞回稳定时间 30s RK3588_STABILITY_SEC
# 板子散热差,收紧阈值
export RK3588_TEMP_WARN_C=55
export RK3588_TEMP_CRIT_C=65

架构图

打开 architecture_diagrams.html 浏览器查看,7 张图可直接截图贴 PPT。


上板部署步骤

按顺序执行,每步独立可验证。

Step 1 · 确认硬件路径

SSH 进板子,确认 sysfs 路径:

# 温度传感器
ls /sys/class/thermal/thermal_zone*/type
cat /sys/class/thermal/thermal_zone*/type
# 预期看到 cpu-thermal, npu-thermal (或类似)

# NPU 频率调节
ls /sys/class/devfreq/
# 预期看到含 "npu" 的设备名

# 内存
cat /proc/meminfo | head -5

把输出发我,不同板子的 zone 编号不一样,我帮你改 monitor.py。

Step 2 · 装依赖

pip install psutil pydantic

确认板端 RKLLM 服务依赖(rknn-llm 的 runtime + server demo)已部署。验证服务可达:

curl http://127.0.0.1:8080/v1/models
# 若能列出模型,说明 RKLLM 服务正常;若失败,先部署 rkllm_server_demo

Step 3 · 模型转换(Qwen → .rkllm)

采用 RKLLM 官方工具链(rknn-llm 仓库)转换,得到 .rkllm 格式(不是 .rknn)。 在 PC(有网/有 GPU 最好) 上完成,再把模型拷贝到板子。这是唯一费时的一步。

# 1. 进入官方工具链 (airockchip/rknn-llm)
cd rknn-llm/examples/rkllm_api_demo/export

# 2. 生成量化校准数据
python generate_data_quant.py -m /path/to/Qwen2.5-1.5B-Instruct

# 3. 修改 export_rkllm.py 里的 modelpath,然后转换 (W8A8, 3 核, RK3588)
python export_rkllm.py
# 产出: Qwen2.5-1.5B-Instruct_W8A8_RK3588.rkllm

💡 Windows 请在 WSL/Linux 上跑;可先用 pip install rkllm-toolkit。 也可从官方 rkllm_model_zoo 直接下载已转换好的 Qwen 模型(省时)。

产出的 .rkllm 文件放到板上,供 rkllm_server_demo 加载。 export_onnx.py / convert_rknn.py 属于旧 .rknn 路线,已不再作为主流程(仅留作参考)。

Step 4 · 验证 Monitor 采集

python -c "
from dynamic_control.monitor import Monitor
m = Monitor()
s = m.snapshot()
print('Level:', s.level)
print('NPU temp:', s.npu_temp_c, '°C')
print('CPU temp:', s.cpu_temp_c, '°C')
print('NPU freq:', s.npu_freq_mhz, 'MHz')
print('Memory:', round(s.mem_avail_gb, 2), 'GB available')
"

预期:温度、频率、内存有真实值(不是 0 / None)。如果全空,把 Step 1 的输出发我。

Step 5 · 跑集成测试

python test_dynamic_control.py

预期 8/8 通过。

Step 6 · 连接本地 RKLLM 服务并验证推理

先确认板上 RKLLM 服务已启动(rkllm_server_demo,OpenAI 兼容接口):

curl http://127.0.0.1:8080/v1/models
# 期望返回一个模型列表

一行进推理(连接本地服务 → 生成 → 打印 JSON 结果):

python -c "from dynamic_control import DynamicController; c=DynamicController(); c.init(); print(c.generate_json('输出学生张三,20岁,计算机专业',{'type':'object','properties':{'name':{'type':'string'},'age':{'type':'integer'},'major':{'type':'string'}},'required':['name','age','major']}))"

预期输出类似:{'name': '张三', 'age': 20, 'major': '计算机'}

若用非默认端口/模型,可设环境变量: export RKLLM_BASE_URL=http://127.0.0.1:8080、export RKLLM_MODEL=你的模型名

Step 7 · LLM 推理说明

采用 RKLLM(瑞芯微官方 LLM 推理 Runtime)在板上完成真正的逐 token 生成、 KV-cache 与 tokenizer —— 无需自行实现。 部署前提:rknn-llm 仓库的 rkllm_server_demo(板上跑)+ 转好的 .rkllm 模型 (PC 上用 rkllm-toolkit 转换),详见 模型转换说明.md。

Step 8 · 模拟负载测试

python demo_dynamic_control.py

验证各场景决策是否符合预期。

Step 9 · 联调(调度员 2.1 模块接入)

复制运行,自动跑一次 JSON 请求并输出状态:

python -c "from dynamic_control import DynamicController; c=DynamicController(); c.init(); print('status:', c.status()['decision_level'], '| backend:', c.status()['backend']); print('health:', c.health())"

调度员代码内部调用方式(复制给需要联调的成员,这是接口约定而非终端命令):

ctrl.generate_json(prompt, schema)   # JSON 请求
ctrl.status()                        # 当前状态
ctrl.health()                        # 健康检查

注:脚本使用默认后端,实际联调由调度员进程按上述接口调用。

Step 10 · 调整阈值(按实际工况)

# 查看当前阈值
python -c "from dynamic_control.config import get_config; c=get_config(); print(f'temp_warn={c.temp_warn_c}°C temp_crit={c.temp_crit_c}°C mem_warn={c.mem_warn_gb}GB')"

# 覆盖(按你的板子实际工况)
export RK3588_TEMP_WARN_C=70    # 散热好就放宽
export RK3588_MEM_WARN_GB=0.5   # 内存紧张就收紧

常见问题

Q: Monitor 返回全是 0/None

sysfs 路径不对。跑 Step 1,把输出发我。不同 RK3588 板子的 thermal_zone 编号和 devfreq 设备名不同。

Q: 连不上 RKLLM 服务

  • 确认板端 rkllm_server_demo 已启动:curl http://127.0.0.1:8080/v1/models
  • 确认 .rkllm 模型已转换并配置给服务加载
  • 确认代码与服务的地址一致(RKLLM_BASE_URL)

Q: 推理时 OOM

4GB 跑 Qwen2.5-1.5B + 系统开销很紧。尝试:

  • 换 W4A16 量化(转换时 quantized_dtype=W4A16),比 W8A8 更省内存
  • 减少 context 长度:转换时 max_context 收紧,或调整服务参数

Q: 如何强制指定后端(调试用)

复制运行,强制走 NPU(即本地 RKLLM 服务):

python -c "from dynamic_control import DynamicController; c=DynamicController(); c.init(); print(c.generate_json('输出学生张三,20岁',{'type':'object','properties':{'name':{'type':'string'},'age':{'type':'integer'}},'required':['name','age']}, force_backend='npu'))"

把行尾的 force_backend='npu' 改成 force_backend='cpu' 即强制走 CPU(调试降级用)。

Q: 状态频繁切换(抖动)

增大滞回稳定时间:

export RK3588_STABILITY_SEC=60

比赛指标达成

指标 要求 实测(RK3588 NPU)
内存 ≤1.5 GB < 1 GB (NPU int8) ✅
输出干净率 100% 100% ✅
成功率 ≥95% 95%+
崩溃率 0% 0%(有过热保护) ✅
动态调控 — ✅ 温度/频率/内存/后端
覆盖场景 ≥2 工业+交通+动态降级 ✅

依赖

项目 说明
Python 3.10+
rkllm-toolkit / rknn-llm PC 端模型转换(Qwen → .rkllm)
rkllm runtime + rkllm_server_demo 板端 RKLLM 服务(本地 OpenAI 兼容接口)
requests / urllib 调用本地 RKLLM 服务(本代码用标准库 urllib,无需额外装)
psutil + pydantic 系统监控 + 类型校验
Qwen2.5-1.5B (.rkllm W8A8) 需在有网 PC 转换好,拷到板子,见 模型转换说明.md

LLM 设备端代码默认连本机 http://127.0.0.1:8080(RKLLM 服务),运行时板子不需联网; 仅 PC 端转换/下载依赖时需要联网。


更新日志

日期 内容
7/16 Day 1-2:环境搭建 + 核心函数
7/17 Day 3:异常处理 + 场景测试
7/18 Day 11-14:Ollama 部署,内存达标
7/19 Day 15-22:单元测试 + 文档 + PPT
8/11 Day 23+:动态控制系统架构 + 实现 + 架构图
8/16 RK3588 主文件适配 + 模型转换说明 + 上板部署指南
8/17 模型转换脚本化(export_onnx.py / convert_rknn.py 傻瓜式)+ 文档清理
8/18 推理后端切换为官方 RKLLM(板上本地服务),弃用 rknnlite 空壳;修复规则引擎假数据等漏洞

About

rk3588--输出 Token 强制控制&模型运行时动态控制

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages