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

3.4 KiB

Research bundle schema v1

An export is an immutable directory:

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:

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.