diff --git a/README.md b/README.md index a8f4db5..a8e4bef 100755 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ | [aibox](aibox/) | Python | 8765 | 独立 AI 智能体系统（DeepSeek + WebSocket），自带技能系统/记忆/任务调度，由 core 拉起但与主干微服务无调用关系 | | [BotOps](BotOps/) | Python | — | aibox 智能体 TUI 前端（Textual），WebSocket 连接 aibox，支持 Markdown 增量流式渲染、思考模式展示、任务独立侧栏、自动重连 | | [bot4cj](bot4cj/) | 仓颉(Cangjie) | — | 机器人硬件脚本解析器，解析 .mt 矩阵脚本通过 I2C 驱动 PCA9685 舵机 / MPU6050 陀螺仪，面向树莓派 Dashun 蜘蛛机器人平台（独立硬件项目） | -| [pybot](pybot/) | Python | — | bot4cj 的 Python 迁移版：.mt 动作脚本解析器（零第三方依赖，与仓颉版逐语义对齐）；支持执行 / `--dry-run` / `--record` 录制 actpred episode（含 imu.npy）/ `--loop` 实时预测闭环 | +| [pybot](pybot/) | Python | — | bot4cj 的 Python 迁移版：.mt 动作脚本解析器（零第三方依赖，与仓颉版逐语义对齐）；支持执行 / `--dry-run` / `--record` 录制 actpred episode（含 imu.npy）/ `--loop` 实时预测闭环（HEF 后端自动异步，推理与执行并行） | | [mtc](mtc/) | Python | — | 命令式动作脚本（Python DSL）→ .mt 编译器：非阻塞时间轴 + 10ms 栅格展开，输出可由 pybot/bot4cj 直接执行；零第三方依赖 | | [actpred](actpred/) | Python(PyTorch) | — | 动作预测模型（图像 + 动作历史 → 下一动作），bot4cj/pybot 的「大脑」配套；两阶段训练（.mt 预训练 → episode 微调），ONNX/Hailo HEF 部署（实验） | | [lci](lci/) | C++ | — | 嵌入式帧缓冲图形界面（LCI），基于 `/dev/fb0` 直接操作显存，无需 X11/Wayland，矢量字体、图片渲染、实时数据可视化，面向树莓派等嵌入式环境 | @@ -256,7 +256,7 @@ ### pybot（机器人动作脚本解析器 · Python 迁移版） - [bot4cj](#bot4cj机器人硬件脚本解析器) 的 Python 迁移版，零第三方依赖（纯标准库），与仓颉版逐语义对齐（含占位符 `-` 递归继承、微步分解、块序依赖）。 -- 三种运行模式：脚本执行 `run()`、`--record` 录制 actpred episode（images + actions.npy + imu.npy，≤4 个 MPU6050 按块行序拼接）、`--loop` 实时预测闭环（daemon 线程队列非阻塞取帧，overrun 告警）。 +- 三种运行模式：脚本执行 `run()`、`--record` 录制 actpred episode（images + actions.npy + imu.npy，≤4 个 MPU6050 按块行序拼接）、`--loop` 实时预测闭环（daemon 线程队列非阻塞取帧，overrun 告警；HEF 后端自动走异步推理——执行上一步动作与 NPU 推理并行，滞后一拍）。 - 扬声器静音语义：`frequency <= 0` 不出声仅保持节拍（对齐仓颉版 sleep 占位语义）。 - Windows 开发机可跑测试（fcntl mock + 符号链接 fallback）；详见 [pybot/README.md](pybot/README.md)。 diff --git a/actpred/README.md b/actpred/README.md index 9726df6..3e3a32a 100644 --- a/actpred/README.md +++ b/actpred/README.md @@ -311,3 +311,17 @@ python3 dfc_compile.py # 产物 checkpoints/actpred_pretrain.hef `--pred-token` 喂入学习值、`--stats` 喂入归一化统计、`--imu` 喂入姿态。 环境调研与 API 踩坑记录见 [docs/reports/actpred_hailo_hat2_inference_research_20260813.md](../docs/reports/actpred_hailo_hat2_inference_research_20260813.md)。 + +### 异步推理（`predict_async`，run_async 流水线） + +`HailoPredictor.predict_async(images, action_history, pred_token=None, imu=None)` +提交异步推理并立即返回 `_AsyncJob`，需要结果时 `job.result(timeout)` 阻塞获取： + +- 与同步 `predict` 语义/输出完全一致（公共 `_prepare_inputs/_fill_bindings/_postprocess`） +- 内部维护 4 个绑定缓冲池 + 完成回调；在途任务超过缓冲数时提交会阻塞等待 + 空闲缓冲，`job.result` 超时**不会**释放缓冲（缓冲由完成回调释放） +- 连续提交（≥2 个在途）时 NPU 保持满负荷：实测连续吞吐 6.0ms vs 同步 + 15.5ms（约 2.6×）；扩展测试覆盖乱序取结果/混合调用/缓冲压力/300 次 + 稳定性/4 线程并发，输出与同步 0 差异 +- pybot `--loop` 检测到 `predict_async` 即自动走异步闭环（推理期间并行 + 执行上一步动作），见 [pybot/README.md](../pybot/README.md) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 002f24a..5d639e1 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,7 +2,7 @@ > 权威架构参考。本文以 `core/services.yaml`（实际运行清单）与 `git HEAD` 为事实来源。 > 与根目录 `README.md` 的偏差见文末「§10 与 README 的偏差」。 -> 最后核对于：2026-08-15。 +> 最后核对于：2026-08-17。 --- @@ -148,7 +148,7 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe | **aibox** | Python | 8765 | 127.0.0.1 | 独立 AI 智能体（WebSocket） | 独立产品 | | **BotOps** | Python | — | — | aibox 的 TUI 前端 | 独立 | | **bot4cj** | Cangjie | — | 树莓派 I2C | 机器人脚本解析器 | 独立硬件 | -| **pybot** | Python | — | 树莓派 | bot4cj 的 Python 迁移版（.mt 解析、actpred episode 录制、--loop 实时预测闭环） | 独立硬件 | +| **pybot** | Python | — | 树莓派 | bot4cj 的 Python 迁移版（.mt 解析、actpred episode 录制、--loop 实时预测闭环；HEF 后端自动异步，推理与执行上一步动作并行） | 独立硬件 | | **mtc** | Python | — | — | 命令式动作脚本（Python DSL）→ .mt 编译器（非阻塞时间轴 IR + 10ms 栅格化），pybot/bot4cj 的脚本 authoring 工具 | 开发期工具 | | **lci** | C++ | — | /dev/fb0 | 嵌入式帧缓冲 GUI | 独立硬件 | | **actpred** | Python | — | — | 动作预测（图像+动作历史→下一动作），bot4cj/pybot 的「大脑」配套 | 实验 | @@ -236,6 +236,7 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe - **smtp3 待上线**：C++ 重写已完成并通过安全审计，但 services.yaml 仍指向 Python `smtp`，建议择机平替以消除最后一块 Python 有状态服务。 - **可观测性缺口**：缺 tracing/metrics/告警，建议后续引入轻量方案（或复用 db2 Logs + 定时聚合）。 - **水平扩展限制**：smtp/captcha 内存态为单点，若需多实例需引入 Redis 等共享存储。 +- **panel 面板微服务（规划中）**：设计稿见 [docs/panel_service.md](panel_service.md)——背景视图 + 各服务自持控件片段（iframe 沙箱 + BFF 转发），解决整页应用互相改前端代码的耦合问题；落地后需三处同步（本文件 / MODULES.md / 根 README）。 --- diff --git a/docs/MODULES.md b/docs/MODULES.md index d2d5806..4888b79 100644 --- a/docs/MODULES.md +++ b/docs/MODULES.md @@ -53,7 +53,7 @@ | 模块 | 语言 | 端口 | 职责 | |------|------|------|------| | bot4cj | 仓颉/Cangjie | — (树莓派 I2C) | 机器人硬件脚本解析器，解析 `.mt` 驱动 PCA9685 舵机 / MPU6050 陀螺仪 / 扬声器，面向 Dashun 蜘蛛机器人 | -| pybot | Python | — (树莓派) | bot4cj 的 Python 迁移版：`.mt` 动作脚本解析器（零第三方依赖，与仓颉版逐语义对齐）；支持执行 / `--dry-run` / `--record` 录制 actpred episode（含 imu.npy）/ `--loop` 实时预测闭环 | +| pybot | Python | — (树莓派) | bot4cj 的 Python 迁移版：`.mt` 动作脚本解析器（零第三方依赖，与仓颉版逐语义对齐）；支持执行 / `--dry-run` / `--record` 录制 actpred episode（含 imu.npy）/ `--loop` 实时预测闭环（HEF 后端自动异步：推理与执行上一步动作并行） | | mtc | Python | — | 命令式动作脚本（Python DSL）→ `.mt` 编译器：`exec` 注入命名空间 → 时间轴 IR（非阻塞语义、重叠截断）→ 10ms 栅格化；产物可由 pybot/bot4cj 直接执行，零第三方依赖 | | lci | C++ | — (/dev/fb0) | 嵌入式帧缓冲图形界面（无需 X11/Wayland），矢量 GB2312 中文字库、图片渲染、实时数据可视化 | | 3d | — (资产) | — | 机器人 / 机械臂 CAD 模型（STEP/STL/SLDPRT），bot4cj 配套硬件资产 | @@ -77,7 +77,7 @@ | 模块 | 说明 | |------|------| | tests | 黑盒测试套件（`test_db.py`/`test_gateway.py`/`test_waf.py`/`test_dnfs.py`/`test_captcha.py`/`test_smtp.py`/`test_ai_review.py`/`test_static.py`/`test_core_confs.py`），纯标准库 HTTP/TCP 用户旅程模拟，经 `test_runner.py` 统一调度（详见 [tests/blackbox/README.md](../tests/blackbox/README.md)） | -| docs | 文档聚合（security/ 审计、reviews/ 审查、reports/ 分析），70 篇 md | +| docs | 文档聚合（security/ 审计、reviews/ 审查、reports/ 分析），76 篇 md | ## 九、根级构建与部署脚本 @@ -92,5 +92,5 @@ - **日志链路**：各服务 `log_client.py`（异步批量）→ `db2:8005` Logs 表（fail-safe，db2 不可用时静默丢弃） - **配置链路**：`gateway` → `core` 内嵌 confs:8010（内存缓存 + mtime 重载，仅 gateway.ini）；其余服务配置纯 CLI 传递 - **数据/审核/邮件/缓存**：`dnfs2` → `db2:8005`（pymsg 持久化）；`dnfs2` → `ai_review:8007`（审核）；注册邮件 `ca` → `smtp:8008`；登录验证码 `ca` → `captcha2:8009`；`memdb:8011`（内存缓存，libmsg RPC，暂无业务调用方，预留热点数据/会话缓存） -- **机器人数据链**：`mtc` 编译 Python DSL → `.mt`（或手写 `.mt`）→ `pybot` 执行 / `--record` 录制 episode（images + actions.npy + imu.npy）→ `actpred` 两阶段训练 → ONNX/Hailo HEF 部署 → `pybot --loop` 实时预测闭环（bot4cj 语义对齐） +- **机器人数据链**：`mtc` 编译 Python DSL → `.mt`（或手写 `.mt`）→ `pybot` 执行 / `--record` 录制 episode（images + actions.npy + imu.npy）→ `actpred` 两阶段训练 → ONNX/Hailo HEF 部署（`predict_async` 异步流水线）→ `pybot --loop` 实时预测闭环（bot4cj 语义对齐，HEF 后端推理与执行并行） - **端口一览**：80 redirect80 · 443 waf · 8443 ca · 8445 gateway · 5200/8010 core · 9200 fsys · 8006 dnfs2 · 8005 db2 · 8007 ai_review · 8009 captcha2 · 8008 smtp · 8011 memdb · 8765 aibox diff --git a/pybot/README.md b/pybot/README.md index 916c50c..faffbd1 100644 --- a/pybot/README.md +++ b/pybot/README.md @@ -50,6 +50,11 @@ cat scripts/std.mt | ./_run.sh # 与 bot4cj 相同的管道用法 - checkpoint 后缀 `.hef` → Hailo NPU 后端，否则 → PyTorch 后端 - `hz` 须 ≥ 推理 + 执行耗时（ONNX ~11ms / Hailo ~12ms，hz ≤ 50 安全） +- **异步推理路径**：predictor 提供 `predict_async`（Hailo NPU 后端，见 + actpred `hailo_infer.py`）时自动启用——提交推理后**并行执行上一步动作** + （滞后一拍执行，动作与状态错位一拍，10Hz 下 = 100ms，对微动作步态影响 + 可忽略），隐藏真实 I2C 执行耗时（实测 HEF 步耗时 ~16ms → ~12ms）； + PyTorch/ONNX 同步路径不变 - `@Action` 表头列数须 ≤ `action_dim`（默认 18），闭环中跳过 `spk.delay` 阻塞 - **帧源**：闭环从 camera 守护线程队列取最近 F 帧（无阻塞），`@Camera` 的 `framerate` 建议 ≥ 2×`hz` 以保证帧新鲜度；`capacity` 应 ≥ F（帧窗长度）。