openpi 最小推理客户端实战指南：使用 examples/simple_client 连接远端策略服务器并测速-北京尧图网络

openpi 最小推理客户端实战指南使用 examples/simple_client 连接远端策略服务器并测速【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpi导读examples/simple_client是 openpi 仓库中一个依赖极简、开箱即用的最小客户端示例它通过 WebSocket 向远端策略服务器发送随机观测observation循环调用策略推理并输出详细的推理速率与延迟统计。本文将以该示例为核心完整讲解其命令行参数、Docker / 无 Docker 两种启动方式、各机器人环境的观测字典结构、客户端与服务端的通信协议原理以及如何把测得的时序数据导出为 Parquet 供离线分析并补充源码级的实现佐证帮助你快速理解并复用 openpi 的远端推理链路。一、simple_client 是什么位置与定位在 openpi 仓库中远端推理的完整链路由三部分组成策略服务器scripts/serve_policy.py 负责加载预训练 checkpoint 并通过 WebSocket 对外提供服务默认端口 8000。客户端策略库packages/openpi-client 提供WebsocketClientPolicy实现了与服务端一致的infer(obs)接口可被嵌入任意机器人代码库。最小示例examples/simple_client/main.py 即本文主角——它不连接真实机器人而是用随机生成的观测持续向服务器发请求重点测量端到端推理时延与吞吐用于验证部署环境、排查瓶颈。正如 examples/simple_client/README.md 所述A minimal client that sends observations to the server and prints the inference rate它的价值在于在没有机器人硬件的情况下即可验证策略服务器的可用性与性能。与之配套的远端推理完整说明见 docs/remote_inference.md本文聚焦于 simple_client 本身的全部细节。二、快速开始两种启动方式2.1 先看帮助所有可选环境运行下面的命令即可查看支持的环境选项--envuv run examples/simple_client/main.py --help从 main.py 的EnvMode枚举可以看到支持四种环境枚举值内部标识对应策略 checkpoint见 serve_policy.pyALOHAalohapi05_aloha/gs://openpi-assets/checkpoints/pi05_baseALOHA_SIMaloha_simpi0_aloha_sim/gs://openpi-assets/checkpoints/pi0_aloha_simDROIDdroidpi05_droid/gs://openpi-assets/checkpoints/pi05_droidLIBEROliberopi05_libero/gs://openpi-assets/checkpoints/pi05_libero2.2 方式一Docker推荐自动拉起服务器与客户端仓库提供了 examples/simple_client/compose.yml一条命令即可同时构建并启动策略服务器openpi_server服务与客户端runtime服务export SERVER_ARGS--env ALOHA_SIM docker compose -f examples/simple_client/compose.yml up --build关键点解读SERVER_ARGS环境变量同时注入两个容器客户端启动命令实际为python examples/simple_client/main.py $SERVER_ARGS见 Dockerfile。也就是说这个参数会同时传给客户端因此务必保证它与你想要测试的环境一致。两个服务均使用network_mode: host客户端与服务器通过宿主机回环端口通信无需额外配置端口映射。openpi_server容器将${OPENPI_DATA_HOME:-~/.cache/openpi}挂载到/openpi_assets用于缓存下载的 checkpointcompose.yml。GPU 支持compose 文件末尾的deploy.resources.reservations段为服务器预留了 1 块 NVIDIA GPU在无 GPU 的机器上运行时应注释掉该块compose.yml。Docker 镜像的构建方式也值得注意examples/simple_client/Dockerfile基于python:3.7-slim并内嵌uv0.5.1通过UV_PROJECT_ENVIRONMENT/.venv把虚拟环境写到项目目录之外避免挂载卷时污染宿主机目录只COPY依赖清单requirements.txt与openpi-client/pyproject.toml项目代码通过 volume 挂载因此修改代码无需重建镜像非常适合开发期反复调试。2.3 方式二无 Docker两个终端窗口不依赖 Docker 时需要手动启动两端终端窗口 1 —— 启动客户端uv run examples/simple_client/main.py --env DROID终端窗口 2 —— 启动策略服务器uv run scripts/serve_policy.py --env DROID注意--env值在两端必须一致因为客户端生成的观测结构要与服务端加载的策略输入规格匹配详见下文第四节。scripts/serve_policy.py的--env只决定加载哪个默认 checkpoint如果你有自己的训练产物可改用policy:checkpoint子参数显式指定例如参考 docs/remote_inference.mduv run scripts/serve_policy.py policy:checkpoint --policy.configpi0_fast_droid --policy.dirgs://openpi-assets/checkpoints/pi0_fast_droid三、客户端命令行参数全解main.py 使用tyro解析Argsdataclass全部参数如下参数类型默认值含义--hoststr0.0.0.0要连接的策略服务器地址--portint | None8000服务器端口与服务器默认端口一致--api-keystr | NoneNone访问服务器的 API Key服务端启用鉴权时必填--num-stepsint20循环推理的步数即发送多少次观测请求--timing-filepathlib.Path | NoneNone指定后把时序数据写入 Parquet 文件如timing.parquet--envEnvModeALOHA_SIM要测试的环境决定观测字典的构造方式一个带鉴权、100 步、导出时序文件的完整示例uv run examples/simple_client/main.py --env LIBERO --host 192.168.1.50 --port 8000 --api-key YOUR_KEY --num-steps 100 --timing-file timing.parquet参数背后的实现细节host/port 的拼接逻辑在 websocket_client_policy.py 中WebsocketClientPolicy会判断 host 是否以ws开头若以ws开头则直接作为 URI此时可传入ws://或wss://完整地址否则拼接为ws://{host}:{port}。API Key 的传递方式如果提供了api_key客户端在建立连接时会附加 HTTP 头Authorization: Api-Key keywebsocket_client_policy.py。自动重连等待客户端构造时即尝试连接若目标未就绪ConnectionRefusedError会每 5 秒重试并打印 Still waiting for server...websocket_client_policy.py。因此即使先启动客户端、后启动服务器也能正常工作这也是 Docker compose 中depends_on之外的另一层兜底。四、观测字典四种环境的输入规格simple_client 的核心思路是用随机数据模拟真实传感器输入因此每种环境都定义了一个_random_observation_*工厂函数main.py并在main中按--env映射选择main.pyALOHA / ALOHA_SIM_random_observation_aloha{ state: np.ones((14,)), # 14 维关节/本体状态 images: { cam_high: np.random.randint(256, size(3, 224, 224), dtypenp.uint8), # CHW uint8 cam_low: np.random.randint(256, size(3, 224, 224), dtypenp.uint8), cam_left_wrist: np.random.randint(256, size(3, 224, 224), dtypenp.uint8), cam_right_wrist:np.random.randint(256, size(3, 224, 224), dtypenp.uint8), }, prompt: do something, }DROID_random_observation_droid{ observation/exterior_image_1_left: np.random.randint(256, size(224, 224, 3), dtypenp.uint8), # HWC uint8 observation/wrist_image_left: np.random.randint(256, size(224, 224, 3), dtypenp.uint8), observation/joint_position: np.random.rand(7), observation/gripper_position: np.random.rand(1), prompt: do something, }LIBERO_random_observation_libero{ observation/state: np.random.rand(8), observation/image: np.random.randint(256, size(224, 224, 3), dtypenp.uint8), observation/wrist_image:np.random.randint(256, size(224, 224, 3), dtypenp.uint8), prompt: do something, }三种规格的共性规律键名与真实环境策略的输入完全一致——ALOHA 用嵌套images字典命名键cam_high等DROID/LIBERO 用扁平化命名observation/...这与各环境策略实现如 aloha_policy.py、droid_policy.py、libero_policy.py的观测规格一一对应。图像统一为 uint8尺寸 224×224这是预训练 pi0 模型的典型resize_sizedocs/remote_inference.md 明确指出典型值为 224。prompt为任务指令字符串服务端策略执行时使用若数据中缺失且模型无默认 prompt可由服务器端--default-prompt兜底serve_policy.py。归一化normalization由服务端处理如 docs/remote_inference.md 所强调proprioceptive 的state可以直接传未归一化值。五、一次推理循环客户端如何工作main.py 的main函数流程如下构造WebsocketClientPolicy(host, port, api_key)打印policy.get_server_metadata()获取的服务器元信息模型名、输入规格等预热先发送 2 次推理policy.infer(obs_fn())确保模型权重已加载到显存/内存避免把首次加载耗时计入统计用tqdm进度条循环num_steps次推理每次记录client_infer_ms客户端视角的端到端耗时含网络往返从响应字典中取server_timing服务端infer_ms、prev_total_ms与policy_timing策略内部各阶段耗时逐项记录打印统计表若指定--timing-file则写 Parquet。底层通信协议msgpack numpy 扩展客户端与服务端的协议实现位于 websocket_client_policy.py 与 websocket_policy_server.py客户端用msgpack_numpy.Packer序列化观测并send服务端recv后unpackb还原websocket_policy_server.py服务端调用self._policy.infer(obs)得到动作注入server_timing字段后回传websocket_policy_server.py握手阶段服务端先发送一条元数据消息packer.pack(self._metadata)客户端据此得到server_metadatawebsocket_policy_server.py若服务端推理抛出异常会先发送 traceback 字符串再以INTERNAL_ERROR关闭连接客户端收到字符串类型响应时直接抛出RuntimeError展示服务端报错websocket_client_policy.py——这是一个非常实用的排障特性服务端额外提供/healthz健康检查端点返回200 OKwebsocket_policy_server.py。关于推理速率的量化方式main中的client_infer_ms是同步阻塞测量的一次infer从发请求到收到动作的完整时间。真实的推理速率每秒可执行的策略步数可由1000 / mean(client_infer_ms)估算。若配合 action_chunk_broker.py 中的ActionChunkBroker思路一次推理产出action_horizon步动作、逐步消费实际控制频率可进一步降低对推理时延的依赖。六、时序统计TimingRecorder 的统计口径TimingRecorder 负责聚合所有计时数据输出两类结果6.1 终端表格print_all_stats()用rich渲染一张Timing Statistics表格每个指标如client_infer_ms、server_infer_ms、policy_*一行列出 8 个统计量列计算方式get_statsMean / Std平均值与标准差P25 / P50 / P7525/50/75 分位数毫秒P90 / P95 / P9990/95/99 分位数用于观察长尾延迟分位数的价值在于均值可能被个别慢请求拉高而P99 能反映真实部署中最差情况的时延体验对机器人实时控制尤为重要。6.2 Parquet 导出若传入--timing-file timing.parquet则用polars把所有时序写入 Parquetwrite_parquetframe pl.DataFrame(self._timings) # 每列是一个计时指标每行是一步 frame.write_parquet(path)导出的 Parquet 可用任意支持列式数据的工具pandas、polars、DuckDB 等离线分析例如绘制延迟分布直方图或按策略阶段拆分耗时。依赖项见 examples/simple_client/requirements.txtnumpy、rich、tqdm、tyro、polars。七、从随机观测到真实机器人如何迁移到自己的代码simple_client 的价值不止于测速——把_random_observation_*替换为真实传感器数据就构成了完整的机器人控制回路。完整的迁移范例在 docs/remote_inference.md在机器人环境安装客户端库仓库内使用uv独立部署时可参考cd packages/openpi-client pip install -e .在机器人代码中初始化客户端并构造观测docs/remote_inference.mdfrom openpi_client import image_tools from openpi_client import websocket_client_policy # 指向策略服务器的 host 与 port默认 localhost:8000 client websocket_client_policy.WebsocketClientPolicy(hostlocalhost, port8000) observation { observation/image: image_tools.convert_to_uint8( image_tools.resize_with_pad(img, 224, 224) # 客户端侧缩放降低带宽/时延 ), observation/wrist_image: image_tools.convert_to_uint8( image_tools.resize_with_pad(wrist_img, 224, 224) ), observation/state: state, # 可传未归一化值服务端负责归一化 prompt: task_instruction, } # 返回形状为 (action_horizon, action_dim) 的动作块 action_chunk client.infer(observation)[actions] # 实际执行时通常每 N 步调用一次策略其余步按动作块开环执行不同环境的观测字典构造范例正是 examples/simple_client/main.py 中_random_observation_*函数所演示的docs/remote_inference.md 原文亦指向该文件。八、常见问题与调优建议两端--env不一致观测结构键名、图像布局 CHW vs HWC、维度对不上服务端会报错。Docker 方式下注意SERVER_ARGS同时影响两个容器。首次推理特别慢这是权重加载预热导致的simple_client 已内置 2 次预热推理统计不会计入首次加载时间。无 GPU 环境运行 Docker 前注释掉compose.yml的deploy块CPU 推理时延会显著上升测得的速率仅代表环境验证而非真实性能。图像传输带宽真实场景建议像 docs/remote_inference.md 那样在客户端侧用resize_with_padconvert_to_uint8压缩图像再上传224×224 是预训练 pi0 的典型尺寸。鉴权场景服务器若启用 API Key客户端必须传--api-key否则连接会被拒绝。网络部署客户端与服务端跨机时把--host指向服务器 IP并确保服务器0.0.0.0监听与防火墙端口放行。结语examples/simple_client以不到 200 行的代码完整展示了 openpi 远端推理的客户端侧全部要素环境感知的观测构造、WebSocket msgpack 序列化协议、服务端时序回传与分位数统计、Parquet 离线分析。它既是部署验证工具也是把 openpi 策略接入真实机器人代码库的最小模板——结合 scripts/serve_policy.py、websocket_policy_server.py 与 docs/remote_inference.md 阅读即可完整打通训练 → 服务化 → 远端调用 → 性能评估的整条链路。【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

openpi 最小推理客户端实战指南：使用 examples/simple_client 连接远端策略服务器并测速

相关推荐

vue-neo4j实战：从Cypher查询到D3力导向图的可视化

OpenMetadata 实时摄取日志流（SSE）：从轮询到推送的读路径设计与实现

Envoy xDS API 端点全解析：gRPC 流式、REST、ADS 聚合、Delta 增量与资源 TTL

更多资讯

身份证翻译件去哪里弄？手把手教你3步搞定盖章翻译件

OpenClaw部署腾讯云：广告营销Agent基础设施实战指南

Spring Boot缓存机制：原理、优化与实战

申请季急用！留学生成绩单翻译认证怎么办？加急多久能出件？一文说清

Java Swing+MySQL学生选课及成绩管理系统实战：从建表到答辩

Telegraf Lustre2 输入插件实战指南：采集 Lustre 并行文件系统的 OST/MDS 运行指标

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？