更新日志

v0.8.1 (2026-10-15)

改进

  • register_model() 相关测试改为以 model_type 注册检测模型，与运行时后处理链接行为对齐

文档

  • 新增中英双语「学习路径」页：按首跑、看活的、拿来用、交付、查阅五阶段组织入门路径，逐阶段指向 quickstart、教学 demo、examples 阶梯与应用镜像指南

  • README 补齐 Overlay / StreamPipeline / Audio / DSP 四节 API 速览与教学 demo 章节，与 0.8.0 门面逐符号对账

  • 学习路径阶段 3 与 apps 仓 examples/ 的编号阶梯（01–07）互链；阶梯 05 即教学 demo 站 1 的独立 app 版

  • 新增「设备开通」页（中英双语）：从购买 NE503 到首次登录——首连静态地址 10.0.0.1/24、出厂凭据、SSH 与网页终端、组播发现；作为学习路径的阶段 0 反向互链

v0.8.0 (2026-09-16)

新增功能

  • 客户端推理管线：新增 Preprocessor / PreprocessMeta、YoloV5Postprocessor / YoloV8Postprocessor、InferencePipeline 与 PipelineRunner，支持从模型规格派生预处理、结果坐标映射、可替换后处理、异步执行，以及带最新帧优先背压和统计信息的长驻运行器

  • 平台调度管线：新增 StreamPipeline / StreamPipelineStatus，组合 InferenceClient.subscribe() 与 OverlayClient，在像素不进入应用进程的情况下完成推理、过滤、硬件叠加和应用侧结果消费，并提供丢帧、延迟、时序偏差和错误观测

  • 帧注入输出路径：新增 FramePublisher 及 CameraClient.push_frame() / injection_status() / stop_injection()，支持 replace / overlay、NV12 / RGB 发布、EOS 恢复与会话标记；写租约感知的缓冲池只复用 daemon 已释放的槽位，兼容旧版 daemon 的深度轮转模式

  • 叠加层帧同步与观测：OverlayClient 支持严格对帧模式，以及 frame_sequence / stream_epoch / session_id 绑定；StreamStatus 新增编码发布、叠加烘焙、严格锁帧、迟到命令和代数拒绝计数

  • 部署诊断：新增永不抛错的 diagnostics() 快照、可按应用要求验收并抛出汇总错误的 diagnostics.check()，以及应用级 set_route_policy() 加速策略入口

  • 推理模型信息：register_model() 支持 batch_size，ModelInfo 透传服务端批大小；InferenceResult 新增服务端计算的 skew_us

  • 端到端设备驻留数据链：DSP 路由器复用进程级客户端；resize_hw / convert_hw 支持 out="ref" 返回 DspBufferRef，推理可直接消费设备侧引用，NV12 预处理可直通，BLEND 可直接写入 FramePublisher 池槽，避免中间读回与重复导入

  • 区域化叠加渲染：新增 render_overlay_fragments()，把描边拆成受 DSP batch 上限约束的偶数尺寸条带，减少全幅 ARGB 覆盖层的带宽和内存开销

改进

  • Frame 的裁剪 / 缩放链保留组合几何变换元数据；keep-fd 帧在预处理、推理、混合和发布路径中保持设备侧数据，媒体与编码客户端补充丢帧和连接观测

  • 新增完整的设备接口与性能测试套件，以及 perf_demo 的 subscribe / keep-fd 对照链、部署脚本和运行期指标采集工具

修复

  • 修复设备实测发现的三个接口问题：DSP import id 按有符号 64 位解析导致高位 id 失效；get_device_status() 读取不存在的 ir_led_on 字段；AppClient.list_apps() 构造了错误的 Empty 消息类型

  • 修复注入退出未发送 EOS、回调内停止引发线程自连接，以及部分叠加发布路径遗漏 ttl_ms 校验

  • 修复 DSP 客户端关闭后池与引用仍可误用、路由器更换进程级客户端时过早关闭在用资源，以及 passthrough 推理完成后输入引用未释放的问题

  • 收紧区域化叠加条带的偶数尺寸和 batch 上限处理，修复边缘平移前高度取整不足导致的无效几何

弃用

  • 插件系统 API (PluginDiscovery / PluginServer / PluginEndpoint) 已弃用。当前平台未部署 /run/aipc/plugins 插件发现机制；v0.8.0 仍保留导入兼容并发出 DeprecationWarning，文档页已下线。如有使用需求请提前反馈。

文档

  • 修正文档与 README 中的视频流示例:移除对从未存在过的 MediaClient 的引用,统一改用 FdMediaClient;流 ID 由 cam0_main / cam0_sub 修正为设备实际暴露的 main / sub;移除不存在的 get_stream_info() / get_raw_stream() 用法;修正 get_encoded_stream() 返回值语义与 frame.data 展平数组误用;补全 EncodedStreamClient / EncodedFrame API 文档

  • 修复应用示例中的缺失导入与误导性导入:多模型融合示例补 import time;英文推理页 GenAI 示例补 import json;错误处理示例移除 from grpc import RpcError (SDK 实际抛出 RuntimeError);清理未使用的 numpy / sys 导入

  • 补译中文推理页缺失章节:自 v0.3.0 起仅存在于英文文档的分割 / OCR / CLIP 图像嵌入 / CLIP 文本编码 / 深度估计 / 运行时更新后处理配置 / GenAI 七个使用小节,以及 SegmentationMask / OcrLine / Embedding / DepthMap 四个数据类型条目,中英文档现已同步

  • 新增管线、帧注入、叠加层与性能说明，补充本地推理应用和 perf_demo 示例

v0.7.4 (2026-09-08)

新增功能

  • 便捷层硬件路由 (sdk-hardware-routing P5): color.rgb_to_nv12 / color.nv12_to_rgb 与 draw.draw_detections``(NV12 数组)默认经 accel 路由器走 DSP 腿,不可用时自动回落软件实现并记账;``Frame.to_jpeg_bytes 对 keep-fd 帧硬件优先(camera-daemon EncodeImage 零拷贝导入),内存帧保持 CPU 编码直达,推流热路径不付额外拷贝与 RPC;软件腿只绑定私有实现,路由公函数不可重入

  • Frame.resize 的 DSP 快路径尊重路由策略: SOFTWARE_ONLY 跳过尝试,``HARDWARE_ONLY`` 失败即抛错(拒绝静默 CPU 回落),``PREFER_HARDWARE`` 经新增的 AccelRouter.note_degradation() 记账(同时新增 policy 属性;外部上报的未注册 op 在 health() 可见,``on_degradation`` 照常触发)

修复

  • _encode_jpeg_hw 硬编码 fmt="rgb24",NV12 keep-fd 帧的提交必被 _resolve_source 以格式不匹配拒绝;帧类源现在随句柄自带格式

  • dsp_format 软件腿经路由公函数重入路由器(跨 op 耦合);改为直接绑定 color 私有实现

  • 色彩转换两腿的 ValueError 契约统一(ndim / 声明尺寸 / 偶数校验先于任何 daemon 提交,调用方错误不再计入降级计数)

v0.7.3 (2026-09-07)

新增功能

  • 硬件优先加速路由器 (accel 模块): AccelRouter / RoutePolicy / health() 降级记账 + on_degradation 钩子 / get_default_router();默认路由注册 resize_nv12 / rgb_to_nv12 / nv12_to_rgb / encode_jpeg / draw_detections 的 DSP 腿与 nms 软件腿

  • DSP 标注合成 (dsp-offload P1): DspClient.blend_hw 把 ARGB32 覆盖层在 DSP 上原位合成回 NV12;``draw.render_overlay_rgba`` 将框+文字渲染为最小 straight-alpha 画布,复现软件光栅输出

  • 异步 DSP 作业 (dsp-offload P2): 全部 *_hw 操作支持 wait=False,``PendingDspJob`` 提供 wait() / done() / release();``blend_hw`` 零拷贝 keep-fd 链(默认拒用——当前固件上为状态依赖的致命路径);``encode_jpeg_hw`` 支持 src_buffer_id 免像素读回;keep-fd 帧源在 resize/convert 腿免 ascontiguousarray 预拷贝;多边形与轨迹形状

  • overlay 标注: annotate() / annotate_result() 经事件总线直推 camera-daemon 渲染器

  • 色彩转换与 NMS: BT.601 limited-range RGB↔NV12(cv2 缺失时的 numpy 路径);跨类感知 postprocess.nms

修复

  • 推理 codec 重构收尾: _tensor_to_numpy / _parse_post_result 遗留 self 致相应解析必失败;删除被薄委托遮蔽的四份完整方法死实现;新增 AST 结构元测试防止同类漂移

v0.7.2 (2026-09-03)

修复

  • _parse_infer_response codec 签名遗留 self: 0.7.0 重构后所有 infer() / infer_batch() 调用抛 TypeError;补充驱动真实 InferResponse 的回归测试

v0.7.1 (2026-09-03)

  • 版本号与 setup.py 对齐,无 API 变化

v0.7.0 (2026-09-02)

新增功能

  • 应用开发工具箱 (原 0.6.0 开发版内容,未单独发布,随 0.7.0 一并发布):

    • Frame.crop() / Frame.resize() / Frame.to_jpeg_bytes() — 帧裁剪、三模式缩放(stretch/letterbox/crop)、JPEG 编码;cv2 缺失时自动降级到 numpy/PIL

    • draw 模块 — 检测结果可视化(draw_boxes / draw_text / draw_detections)

    • recording 模块 — 纯 Python TS 复用打包、HLS 切片、事件预录缓冲(TsWriter / HlsWriter / PrerollBuffer),无需 ffmpeg

    • web 模块 — MJPEG 推流(MjpegServer / MjpegStream / mjpeg_wsgi_app)

    • DeviceClient 原生对焦组 6 个方法(start_oneshot_af / start_zoom_follow / get_autofocus_status / cancel_autofocus / set_af_windows / get_af_measurement)

    • CameraClient 成像/红外/隐私遮挡/OSD/配置组 12 个方法(含红外预设管理、get_osd 与 set_osd 读写对称)

  • 修复 InferenceClient.subscribe() 静默丢弃失败帧的问题

重构

  • 内部架构分层:抽取 _transport 共享传输原语; media 拆分为 frame/encoded/fd_client; dsp 拆分为 dsp_wire/dsp_format; inference 拆分为 types/codec/genai。门面保持全部历史导入路径, 零公共 API 移除

  • DSP CPU 回退从静默日志改为 UserWarning

  • 2D 数组按灰度推理输入触发 DeprecationWarning (请显式传 fmt=)

  • EncodedStreamClient() 默认套接字路径改为 /run/aipc/encoded/{stream}.sock (ENCODED_SOCK_DIR 环境变量可覆盖,显式路径仍优先)

修复

  • 修复 Python 3.8/3.9 下的导入崩溃(全量补齐 from __future__ import annotations)

其他

  • 打包增加 py.typed 类型标记;测试扩充至 270 项全绿

v0.5.0 (2026-08-20)

重构

  • 品牌重构:hailo_ipc_sdk → neoruntime_ipc_sdk (破坏性变更,无兼容层;hailort/ne503/aipc 等功能性名称保留)

修复

  • 修复 audio_capture 流视频布局头的双布局解码

其他

  • CI 建立 TestPyPI/PyPI Trusted Publishing 双发布流程

v0.4.0 (2026-07-14)

新增功能

  • DeviceClient 新增 7 个方法： - set_lens_limits(zoom_limit, focus_limit) — 设置镜头轴限位 - oneshot_autofocus(timeout) — 单次自动对焦（复合操作：开启→等待收敛→关闭） - set_wiegand_out(channel, enable) — 韦根输出控制 - get_wiegand_out(channel) — 韦根输出状态查询 - rs485_init(baudrate, config) — RS-485 串口初始化 - rs485_deinit() — RS-485 串口反初始化 - rs485_tx(data) — RS-485 数据发送

  • AppClient 新增 1 个方法： - restart_app(app_id, timeout_seconds) — 应用重启（停止+启动）

改进

  • 更新 API 文档，补充 DeviceClient 镜头限位、韦根、RS-485 示例

  • 更新 API 文档，补充 AppClient 完整使用示例

  • 同步中英文文档

v0.2.0 (2026-03-02)

新增功能

  • 添加插件系统支持 (PluginDiscovery, PluginServer)

  • 支持插件能力发现和 gRPC 服务调用

  • 新增视频流访问能力（现由 FdMediaClient / EncodedStreamClient 提供）

  • 支持原始视频流和编码视频流获取

改进

  • 优化 InferenceClient 性能

  • 改进事件总线通配符匹配

  • 增强错误处理和日志记录

  • 更新 protobuf 到 4.21.0

修复

  • 修复 EventClient 订阅时的内存泄漏

  • 修复 DeviceClient GPIO 控制问题

  • 修复多线程环境下的连接池问题

v0.1.0 (2025-12-15)

初始版本

  • InferenceClient: AI 推理客户端

  • EventClient: 事件总线客户端

  • DeviceClient: 设备控制客户端

  • Config: 配置管理

  • 支持 Python 3.8+

  • 基于 gRPC 通信