用途
该技能指导开发者把 VLA 模型的推理接口转换为符合 CloudRobo 标准的推理服务器接口，从而适配 CloudRobo 客户端库。核心思路是：模型自身的推理接口格式与 CloudRobo 标准通信格式不同，因此不修改模型的推理逻辑，而是新增一层轻量适配器，在扁平线性格式与模型内部格式之间做双向转换。
固定协议约定
- 传输：WSS（WebSocket over TLS）
- 证书：运行时生成自签名证书（cryptography 库，RSA 3072）
- 序列化：msgpack（含 numpy 扩展）
- 观测格式：点号分隔的扁平字典
- 观测键：observation.images.{key}（key 由模型配置推导，不硬编码）、observation.state（固定字段）、task（固定字段）
- 动作响应：{"action": (T, D) float32}，固定字段
- 握手：连接后第一帧发送元数据约定
- 错误：发送 traceback.format_exc() 字符串，并以 INTERNAL_ERROR 关闭
前置条件
- 模型现有推理接口：predict/infer 方法、模型元数据（action_dim、state_dim、image_keys、action_chunk_size）、归一化参数的读取与设置方式
- 训练输出：标准布局的最终权重，以及 dataset_statistics.json（动作反归一化必需）
- Python 包：numpy、msgpack、websockets、cryptography；Pillow 可选（测试客户端从磁盘加载图片时使用）
四组件模式
模型推理逻辑保持不变，所有协议相关逻辑放在新建文件中：
- 入口点（CLI）：解析参数、组装组件
- 传输服务器：WSS + msgpack、握手、请求循环、错误处理
- 协议适配器：观测由扁平格式转模型格式，动作由模型格式转扁平格式
- 模型推理接口（复用现有）：predict/get_action、元数据、归一化
- 模型与权重（保持不变）
其中第 4、5 层已存在，开发者只需创建第 1–3 层。
通用性分层
- 传输服务器（server_template.py）：通用性高，与模型无关，可直接复制使用
- 测试客户端（scripts/test_client.py）：通用性高，从握手元数据自动发现契约，可直接复制使用
- 协议适配器（adapter_template.py）：通用性低，观测格式与动作输出因模型而异，仅作骨架参考，需按模型定制 derive* 方法与转换逻辑
- 适配器验证（verify_adapter.py）：通用性低，依赖模型 API，通过契约注入测试 adapter.infer()
判断原则：若模型推理接口与模板假设差异较大，应重写适配器并自行编写验证，仅复用传输服务器与测试客户端。
使用方式
工作流程分为五步：
- 识别模型推理接口：记录模型内部格式（扁平示例还是嵌套观测、返回形状、期望的图像键），图像键应从模型配置或框架推导，不硬编码。
- 创建协议适配器：包装模型推理接口，暴露 infer(obs) 与 metadata 属性；实现五个 derive* 方法（图像键、状态维度、状态键、动作维度、动作块大小）。观测转换负责提取图像、把 task 转为 lang、把 observation.state 转为 (1, D) 并校验维度；动作转换通常为去除批次维度并校验 batch=1，多动作键按模型顺序拼接。
- 创建传输服务器：启动时生成自签名证书并构建 SSLContext，通信循环为握手、接收观测、推理、附加计时、发送响应；prev_total_time 为连接内局部变量，首请求为 0；错误统一以 traceback 字符串返回。
- 创建入口点：加载模型、用适配器包装、启动时记录契约（图像键、状态维度、动作维度）以便检查训练/测试一致性。
- 创建测试客户端：从握手元数据自动发现契约，验证动作形状为 (T, D)、首个请求 prev_total_ms 为 0、后续大于 0。
模型内部观测有两种形态：扁平示例（{"image": ..., "state": ..., "lang": ...}）与嵌套观测（如 GR00T 的 {"video": {...}, "state": {...}, "language": {...}}）。线上格式（observation.images.{key} / observation.state / task）对两者一致，仅适配器内部转换不同。
核心命令
- python scripts/verify_adapter.py --adapter /path/to/adapter.py --class-name MyAdapter：无服务器适配器单元测试
- python scripts/verify_adapter.py --adapter gr00t_adapter.py --class-name Gr00tProtocolAdapter --stub-module stub_gr00t.py：带模型桩的适配器测试
- python scripts/test_client.py --host 127.0.0.1 --port 8000：随机图像冒烟测试
- python scripts/test_client.py --host 127.0.0.1 --port 8000 --image_dir /path/to/images --num_inferences 5 --verbose：真实图像端到端测试
- python scripts/test_client.py --host 127.0.0.1 --port 8000 --benchmark：性能基准测试
适用场景
适用于需要将现有 VLA 模型（如 GR00T 等机器人策略模型）部署为 CloudRobo 标准推理服务器的场景，尤其是模型推理接口格式与 CloudRobo 通信格式不一致、又不希望改动模型推理代码的情况。
限制
- 适配器层需按具体模型定制，不能直接套用模板
- 各框架配置/统计文件结构随版本变化，推导表仅为示例参考，需以实际模型配置为准
- state_dim/action_dim 应使用统计维度的和，而非模型输入层的填充维度，否则会出现归一化索引错配
- 错误响应格式固定为 traceback 字符串，使用其他格式会导致客户端解析失败
- 文本在参数表处截断，参数说明不完整，暂未提供完整参数列表