作者:乔瑞浩、张倬铭 位置: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 提交内容说明
一行直接跑主文件自带的完整演示(会输出 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 # 自定义温度阈值# 直接跑动态控制 6 场景决策演示
python demo_dynamic_control.py
# 跑底层 DynamicController 的集成测试(8 用例)
python test_dynamic_control.py| 函数 | 功能 | 示例 |
|---|---|---|
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。
按顺序执行,每步独立可验证。
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。
pip install psutil pydantic确认板端 RKLLM 服务依赖(rknn-llm 的 runtime + server demo)已部署。验证服务可达:
curl http://127.0.0.1:8080/v1/models
# 若能列出模型,说明 RKLLM 服务正常;若失败,先部署 rkllm_server_demo采用 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 路线,已不再作为主流程(仅留作参考)。
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 的输出发我。
python test_dynamic_control.py预期 8/8 通过。
先确认板上 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=你的模型名
采用 RKLLM(瑞芯微官方 LLM 推理 Runtime)在板上完成真正的逐 token 生成、 KV-cache 与 tokenizer —— 无需自行实现。 部署前提:
rknn-llm仓库的rkllm_server_demo(板上跑)+ 转好的.rkllm模型 (PC 上用rkllm-toolkit转换),详见模型转换说明.md。
python demo_dynamic_control.py验证各场景决策是否符合预期。
复制运行,自动跑一次 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() # 健康检查
注:脚本使用默认后端,实际联调由调度员进程按上述接口调用。
# 查看当前阈值
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 # 内存紧张就收紧sysfs 路径不对。跑 Step 1,把输出发我。不同 RK3588 板子的 thermal_zone 编号和 devfreq 设备名不同。
- 确认板端
rkllm_server_demo已启动:curl http://127.0.0.1:8080/v1/models - 确认
.rkllm模型已转换并配置给服务加载 - 确认代码与服务的地址一致(
RKLLM_BASE_URL)
4GB 跑 Qwen2.5-1.5B + 系统开销很紧。尝试:
- 换 W4A16 量化(转换时
quantized_dtype=W4A16),比 W8A8 更省内存 - 减少 context 长度:转换时
max_context收紧,或调整服务参数
复制运行,强制走 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(调试降级用)。
增大滞回稳定时间:
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 空壳;修复规则引擎假数据等漏洞 |