chenlin
f3a8a38acd
web-platform-ci / Standalone decision service (no cloud credentials) (push) Has been cancelled
web-platform-ci / TypeScript, lint, unit, build (push) Has been cancelled
web-platform-ci / Playwright E2E (push) Has been cancelled
lekiwi-compatibility / cpu-compatibility (push) Has been cancelled
web-platform-ci / Standalone decision service (no cloud credentials) (pull_request) Has been cancelled
web-platform-ci / TypeScript, lint, unit, build (pull_request) Has been cancelled
web-platform-ci / Playwright E2E (pull_request) Has been cancelled
lekiwi-compatibility / cpu-compatibility (pull_request) Has been cancelled
集成同源 BYOK 会话隔离、精简模型设置、官方订阅入口和 HTTPS 发布运维；保留本地训练/调参与控制能力。同步 npm 版本及 CHANGELOG，记录公网真实 API 验收仍待用户凭据。
139 lines
13 KiB
Markdown
139 lines
13 KiB
Markdown
# 本地强化学习训练服务
|
||
|
||
该服务把 Web 平台发出的受限训练请求转换为本机训练子进程，并提供状态轮询、停止任务和 `policy.onnx` 下载接口。它还提供 `Unitree-Go2-Flat` 奖励函数自调参：DeepSeek Agent 根据训练曲线与固定评估指标提出受限参数 patch，系统支持全自动或逐轮审批、successive-halving、TensorBoard scalar 查询、最佳 preset 与 ONNX 导出。服务只绑定 `127.0.0.1`，不执行前端传入的任意命令或 Agent 生成的代码。
|
||
|
||
仓库已在 [`rl/`](rl/) 内置 `Unitree-Go2-Flat` 所需的 PPO 训练代码、Go2 模型资产和 ONNX 导出逻辑，不再要求另外克隆 `unitree_rl_mjlab`。`mjlab`、PyTorch 等大型运行依赖仍需安装在本机训练环境中。
|
||
|
||
## LeKiwi 一键训练（与 Go2 共用控制台）
|
||
|
||
注册任务 `MobileManipulator-LeKiwi-v1`、`MobileManipulator-LeKiwi-Bundle`，使用 SB3 PPO + 原生 MuJoCo，沿用同一作业状态机、资源锁、取消和日志轮询。MuJoCo 必须与浏览器一致（3.11.0），**不要升级现有 Go2 环境**；首次配置独立解释器：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
python -m venv build/venvs/mobile
|
||
build/venvs/mobile/bin/python -m pip install -r training_server/mobile_manipulator/requirements.txt
|
||
python training_server/server.py --mobile-python "$PWD/build/venvs/mobile/bin/python"
|
||
```
|
||
|
||
主工作台导入对应 ZIP，在 URDF 选项选择「LeKiwi v1 / Bundle · 移动操作训练场景」；旧 `lekiwi-v1` profile 也能从训练面板开始，届时自动组合任务场景。进入「控制台 → 强化学习任务」，连接服务、配置迭代/环境数/设备/种子/每环境采样步数/物体和目标坐标，点击「发起本地训练」。无需下载训练包或手动执行训练脚本。加载场景会暂停仿真并切换到移动操作任务（不启用外部控制桥、Go2 地图或相机配置）。
|
||
|
||
- 浏览器自动上传组合后的 MJCF 与资产快照。认证 ZIP 上传限 128 MiB、展开 512 MiB/10000 文件；拒绝路径越界、符号链接、include/plugin、非注册机器人契约和包外资产引用。最多保留 20 份去重快照，满额后需停止服务再清理 `logs/mobile_packages/`。
|
||
- `POST /jobs` 仅接收服务器内容 ID `mobilePackageId`，不接受本机路径。`mobileParams` 包括 `stage`（默认 `navigate`）、`sourceJobId`、`navigationBootstrapSteps`（0–10000，默认4096）、`positionJitter`（0–0.3 m，默认0.1）、`evaluationEpisodes`（2–64，默认10）、`rolloutSteps`（8–4096，默认128）、`objectPosition`、`goalPosition`。环境数1–64，默认1；总采样步数为 `maxIterations × numEnvs × rolloutSteps`。CPU 物理向量环境顺序采样，设备选择只控制 PPO 网络；GPU 仅支持单卡，不会静默回退 CPU。
|
||
- actor/critic/entropy 损失、每采样步平均 reward 和已完成回合长度使用共享 `Learning iteration / Mean ...` 日志协议。没有额外 VecNormalize。
|
||
- 自动生成 `logs/rsl_rl/web_jobs/{id}/policy.onnx`、`deployment.json`、PPO checkpoint 与训练配置。元数据包含任务/变体、固定 float32 `[1,92] → [1,12]`、v2 限速动作语义、训练阶段、独立评估、50Hz、权重/机器人配置/场景 SHA-256 和初始目标坐标。
|
||
- 点击「导入策略」自动下载两份成果物，经校验后通过主仿真会话的 `ONNXPolicyRunner` 执行单飞锁步推断。暂停、重载和控制权切换使在途结果失效；回合终止/超时暂停，需重置后继续。改动资产/动力学后应重新训练，哈希不是跨机器人泛化证明。
|
||
- `health.taskMetadata` 按任务报告 `ready/error`，移动依赖缺失不阻断 Go2，反之亦然。短程冒烟只验证链路，不保证抓取成功率；尚未验证长程收敛、GPU 性能或实机迁移。
|
||
|
||
阶段按底盘接近→末端接近→抓取放置推进；服务验证上一阶段至少10回合、≥80%成功率且无安全终止。同阶段可继续训练；接续只能引用同一服务会话中已完成的同场景作业。完整设计、限速说明和实际导航结果见 [分阶段训练](../docs/mobile-training-curriculum.md)。旧68维策略必须重新训练。
|
||
|
||
真实浏览器端到端（需两个本地模型 ZIP 和上述独立环境）：
|
||
|
||
```bash
|
||
npx playwright test -c web_platform/playwright.lekiwi.config.ts lekiwi.training.spec.ts
|
||
```
|
||
|
||
## 自定义任务与地形
|
||
|
||
内置新增 `Unitree-Go2-ObstacleAvoidance`（81维前视射线导航），并放行 `Unitree-Go2-Rough` 训练。健康接口提供可配置参数元数据，job 的 `deployment` 返回精确地图布局、传感器及策略契约。首版支持 `plane/discrete_obstacles/rough/pyramid_stairs/wave` 的训练专用box布局；不是任意场景导入，也不实现真实深度相机。旧 Rough 的234维actor不能在当前浏览器一键部署。完整字段、坐标系、观测动作及复现方式见 [避障部署契约](OBSTACLE_AVOIDANCE.md)。
|
||
|
||
## 准备训练环境
|
||
|
||
使用仓库已有的 `.venv` 项目虚拟环境：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
python -m pip install -r training_server/rl/requirements.txt
|
||
python -m pip install -r training_server/requirements.txt
|
||
```
|
||
|
||
## 启动
|
||
|
||
使用已安装训练依赖的 Python 解释器启动服务：
|
||
|
||
```bash
|
||
.venv/bin/python training_server/server.py
|
||
```
|
||
|
||
服务启动时会在终端显示一个随机访问令牌。将该令牌填入前端“访问令牌”字段后再连接。令牌只保存在当前浏览器标签页的 `sessionStorage` 中。自动化启动时可固定令牌：
|
||
|
||
```bash
|
||
MUJOCO_TRAINING_TOKEN='至少十六个字符的随机令牌' npm run training-server -- \
|
||
--trainer-python /path/to/training-env/bin/python
|
||
```
|
||
|
||
启用云端自调参 Agent 时，在**服务端环境变量**中配置 DeepSeek；不要把 key 填到浏览器、URL 或命令行参数：
|
||
|
||
```bash
|
||
export DEEPSEEK_API_KEY='你的 DeepSeek API key'
|
||
export MUJOCO_TUNING_AGENT_BASE_URL='https://api.deepseek.com' # 可省略
|
||
export MUJOCO_TUNING_AGENT_MODEL='deepseek-v4-flash' # 可省略
|
||
npm run training-server -- --trainer-python "$PWD/.venv/bin/python"
|
||
```
|
||
|
||
普通训练与基础策略上传不要求 DeepSeek key。未配置时健康接口会把 tuning 标记为不可用；只有创建 session 时明确勾选 fallback，才允许使用 Optuna 候选，不会静默降级。
|
||
|
||
### 从浏览器选择已有策略（推荐）
|
||
|
||
普通训练和自调参均可在“基础策略”直接选择单个`.pt`或`.onnx`文件：连接默认服务 → 勾选Go2 legacy47观测/关节语义确认 → 点击“选择基础策略文件” → 等待验证成功后自动选择内容ID并检查文件名/格式/原文件SHA → 发起训练或自调参。不需要`--pretrained-sources`、管理员JSON、服务器路径或sidecars；旧管理员注册是可选高级功能。
|
||
|
||
上传期间禁止启动；取消、验证失败、任务/连接改变会保留旧选择，旧请求结果不会污染新连接。相同文件可重选重试，失效来源不会静默退回随机；从头训练须明确选择“不选择（随机初始化）”。支持47维Go2 actor扩展到81/97新输入，不接受未知机器人/任意ONNX/97维源checkpoint。
|
||
|
||
**只继承actor，不是完整PPO resume**：两格式critic/optimizer全新、iteration0。`.pt`保留原normalizer count和探索std；ONNX仅继承确定性网络，count合成1,000,000、std/var按受限模板推导、探索std使用目标默认1.0，源迭代未知。详细上限、安全边界及点击步骤见[基础策略上传与迁移](PRETRAINED.md)。
|
||
|
||
默认训练工程是仓库内的 `training_server/rl`。如需使用包含其他已注册任务的外部训练工程，仍可通过 `--trainer-root /path/to/trainer` 或 `UNITREE_RL_MJLAB_ROOT` 覆盖。默认端口是 `8765`。如果前端不是从 `localhost` 或 `127.0.0.1` 提供，可显式添加来源：
|
||
|
||
```bash
|
||
python training_server/server.py \
|
||
--trainer-python /path/to/training-env/bin/python \
|
||
--allow-origin http://192.168.1.10:5173
|
||
```
|
||
|
||
普通训练与自调参共享同一个计算资源锁，任何时刻只允许一个训练/评估子进程占用 GPU。普通任务最多保留 20 个内存状态和每个任务 200 行最近日志；调参 session、trial、proposal、审计和 scalar 写入 SQLite/WAL，默认保存在 `training_server/rl/logs/auto_tuning/`。服务重启后等待审批/暂停状态可恢复，正在训练或评估的 trial 标记为 interrupted，只能从已完整保存的 checkpoint 显式恢复。停止服务或点击“停止”会终止整个进程组。
|
||
|
||
普通训练的 W&B 模式默认为 `offline`；调参 trial 强制使用本地 TensorBoard writer，DeepSeek 只接收最多 12 个 trial 的脱敏数值摘要和降采样曲线，不接收源代码、机器人资产、checkpoint、服务 token 或本地路径。所有 HTTP API 请求都必须携带启动时生成的 Bearer Token。
|
||
|
||
## 自调参流程
|
||
|
||
在主工作台连接训练服务后，点击“打开自调参 Agent 工作台”。默认预算为 12 个唯一配置：所有配置先训练 300 iterations，前 4 名续训到 900，前 2 名续训到 2000；默认使用 GPU 0 和 4096 个并行环境。首次使用建议先降低为 256–512 environments 做 smoke test。
|
||
|
||
固定评估使用站立、前进/侧移、转向和组合命令以及 3 个固定 seed。最终分数不直接使用可被权重放大的总 reward，而由速度跟踪 35%、动作平滑 20%、姿态稳定 15%、减少跌倒 15%、足端滑移 10%、能耗 5% 的权重无关指标组成。跌倒率高于基线 2% 或速度误差恶化超过 5% 的 trial 不晋级。逐轮审批模式会自动运行基线，之后每条 Agent 建议都等待批准、修改后批准或拒绝反馈；运行中的 session 也可在逐轮审批和全自动之间切换，切到全自动时会批准当前待处理建议。
|
||
|
||
最佳结果保存为不可变 preset，可在普通训练面板的“奖励配置”中选择，也可导出 JSON；不会覆盖仓库里的 Python 默认奖励配置。
|
||
|
||
## 接口
|
||
|
||
- `GET /api/training/health`：运行环境、允许的任务和活动任务；
|
||
- `POST /api/training/pretrained-sources/upload?format=pt|onnx&template=go2-legacy47-v1&name=显示名`：认证有界二进制单文件上传，返回持久化内容ID；
|
||
- `POST /api/training/mobile-packages`：认证场景快照上传（`application/zip`），返回64位内容ID；
|
||
- `POST /api/training/jobs`：发起训练；
|
||
- `GET /api/training/jobs/{id}`：状态、迭代进度和最近日志；
|
||
- `DELETE /api/training/jobs/{id}`：停止训练；
|
||
- `GET /api/training/jobs/{id}/artifacts/policy.onnx`：下载本次生成的策略；
|
||
- `GET /api/training/jobs/{id}/artifacts/deployment.json`：下载移动操作部署元数据；
|
||
- `GET /api/tuning/capabilities`、`POST /api/tuning/agent/test`：检查/测试 Agent；
|
||
- `GET|POST /api/tuning/sessions`、`GET|DELETE /api/tuning/sessions/{id}`：列出、创建、查询、停止 session；
|
||
- `POST /api/tuning/sessions/{id}/pause|resume`：暂停后续调度或恢复；
|
||
- `POST /api/tuning/sessions/{id}/mode`：运行时切换 `automatic`/`approval` 模式；
|
||
- `PUT /api/tuning/sessions/{id}/constraints`：以 revision CAS 保存参数固定值/工程上下限，服务端在 Agent、fallback 与人工修改三条路径统一强制；
|
||
- `POST /api/tuning/sessions/{id}/step`：发放且只消费一个 Trial 调度令牌，完成训练与固定评估后重新暂停；
|
||
- `POST /api/tuning/sessions/{id}/rollback`：把同 Session 内已完成且通过安全门槛的 Trial 设为非破坏性后续基准，可同时验证其 checkpoint；
|
||
- `POST /api/tuning/sessions/{id}/proposals/{proposalId}/approve|reject`：审批、修改或拒绝建议；
|
||
- `GET /api/tuning/sessions/{id}/trials/{trialId}/metrics?afterStep=N`：查询降采样或增量 scalar；
|
||
- `GET /api/tuning/sessions/{id}/artifacts/best/policy.onnx`：下载最佳策略；
|
||
- `GET /api/tuning/presets`：列出可供普通训练复用的最佳奖励 preset。
|
||
|
||
普通任务状态在服务重启后丢失，但日志、checkpoint 和 ONNX 保留在 `training_server/rl/logs/rsl_rl/`；调参状态、调度令牌、参数护栏、回滚基准及产物持久化在 `logs/auto_tuning/`。候选配置数可在 1–100 间设置（包含基线配置，仍受连续无提升早停约束）。作业/session API 接收32位资源ID，基础策略选择使用64位内容ID；上传仅接收文件字节，不接收客户端服务器文件路径；奖励 patch 受到名称、符号、上下界、Session 护栏、每轮最多 4 项及 `0.5×–2×` 变化率校验。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
python -m pip install -r requirements-dev.txt
|
||
npm run lint:python
|
||
npm run test:training-server
|
||
```
|
||
|
||
## 使用已训练基础策略
|
||
|
||
普通训练与自调参面板均提供“基础策略”选择。管理员通过 `--pretrained-sources` 注册只读本地ONNX及数值匹配的.pt；服务创建SHA绑定快照，浏览器只能选择内容ID，不能提交文件路径。完整可直接运行的注册/启动命令、兼容47/81/97范围、重启恢复规则与验证方法见 [基础策略迁移](PRETRAINED.md)。缺.pt、Rough不匹配或快照失效均明确拒绝，绝不静默随机初始化。
|