Files
UniversalHumanoid/docs/DEPLOYMENT.md
T
2026-11-03 19:46:08 +08:00

62 lines
3.4 KiB
Markdown

# Research bundle schema v1
An export is an immutable directory:
```text
policy.onnx deterministic actor, with trained observation normalization
contract.json observation/action ordering, affine transforms, simulation PD settings
reference.json one raw observation and its expected unclipped policy action
evaluation.json fixed-protocol rollout evidence bound to the checkpoint/source hashes
experiment.json original experiment
agent.json runner architecture/configuration
provenance.json source/assets/runtime versions and hashes
manifest.json SHA-256 of every payload file, checkpoint hash, ONNX parity results
```
The bundle contains no robot meshes, checkpoint pickle, board executable or motor transport.
It is portable for **CPU ONNX inference**, not a self-contained simulation environment. Replay
still needs the recorded task code, asset checkout and compatible mjlab environment.
## Consumer contract
`PolicyRuntime(Path(bundle)).predict(observation)` accepts a finite float32 `[1, observation_size]`
array. Observation terms must be concatenated in the exact `start:stop` order. Read each term's
function identity in `contract.json`; implementation semantics are in the recorded sources.
For current flat tasks, terms are base linear/angular velocity from the configured IMU sensors,
projected gravity, joint position relative to default, joint velocity relative to default,
previous clipped raw action, and `(vx, vy, yaw_rate)` commands. Sensor frame/site and filtering
matter; a base estimator cannot be substituted without validating parity. Joint observation
ordering is explicitly separate from action ordering. Units are SI; angles in radians.
Normalization is inside ONNX. Do **not** normalize twice. On reset, previous action is zero.
During inference:
```text
raw_action = policy(observation)
clipped_action = clip(raw_action, -raw_clip, raw_clip)
joint_target_rad = offset + scale * clipped_action
```
The consumer returns all three arrays and does not send them anywhere. Host PD/control frequency
must match the recorded policy/physics timestep semantics. Simulation gain and torque data are
metadata, not a certified motor configuration. Joint-limit clamping is not silently added to
inference because it would change training semantics; a physical safety controller must be
separately designed, validated and may refuse the policy.
## Export checks and limits
Export requires a completed local run and matching evaluation report. It tests ONNX checker
validity and action parity at 16 actual rollout observations (`atol=1e-5`, `rtol=1e-4`), then
writes file hashes. `verify-bundle --inference` checks integrity and one saved reference.
This detects common swapped-joint/normalizer/version mistakes, but is not a complete behavioral
proof. The current exporter requires MLP, one joint-position action group, no per-joint action
clip, one position actuator per joint and batch size one. It does not generate a robot driver.
A report can show poor tracking and many falls and still be packaged for research. All bundles
are `hardware_approved: false`. There is no release-quality gate or hardware approval command.
Before physical deployment, implement and validate bus index mapping, estimator/calibration,
IMU frame, latency, torque/position bounds, thermal limits, watchdog, controlled startup/shutdown,
E-stop and supervised sim-to-real tests. Require explicit operator authorization for actual motion.