100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
# Detect Server
|
||
|
||
本目录归属“被动调用”的视觉检测 HTTP 服务。服务端负责模型注册、模型生命周期、
|
||
`category -> model` 映射、图像解码和推理资源；调用方只使用稳定的业务
|
||
`category`，不能指定 `model_id`、权重路径或 pipeline。
|
||
|
||
阶段一固定协议入口：
|
||
|
||
- `GET /v1/models`：列出 `active_push` 与 `passive_invoke` 两组能力；
|
||
- `POST /v1/inference`：接收 `InferenceRequest/v1` JSON，返回
|
||
`InferenceResponse/v1`。
|
||
|
||
本顶层目录保存部署边界和可编译示例；HTTP API 与 pipeline 边界组件位于
|
||
`cmvr_edge_ai.server`。公共 wire DTO 以 `cmvr_edge_ai.contracts` 中的版本化类型为准，
|
||
路由层不得复制一套形状相近但不兼容的字典协议。
|
||
|
||
每个被动检测 route 使用一条完整且独立的请求链：
|
||
|
||
```text
|
||
server.request_source@1
|
||
-> media.image_decoder.pillow@1
|
||
-> detection.model@1
|
||
-> server.detection_response@1
|
||
-> server.response_sink@1
|
||
```
|
||
|
||
链路使用 `request/block` QoS，不配置 `max_fps` 或丢帧策略，因此每个进入 broker 的
|
||
请求都会产生一个相关响应或明确失败。Detector 配置 `attach_frame: true`，只有调用方
|
||
在 `requested_artifact_roles` 中请求 `annotated` 或 `original` 时，response 节点才编码
|
||
对应 JPEG artifact。
|
||
|
||
## 配置归属
|
||
|
||
服务端配置拥有：监听地址、category、模型 ID、权重、provider、并发和服务端默认参数。
|
||
客户端配置只拥有服务 URL、认证/超时以及每次调用允许覆盖的业务参数。
|
||
|
||
见 [configs/server_detect.yaml](../../configs/server_detect.yaml)。它沿用根 `AppConfig` 的
|
||
`api_version: cmvr.edge.ai/v1`，并通过 `server.routes` 把公开 category 映射到同一
|
||
文件内声明的 pipelines。
|
||
|
||
示例只做配置加载和 DAG 编译时不会加载模型权重；真正启动 pipeline 时才会初始化
|
||
Pillow、ONNX Runtime、manifest 和静态 ONNX graph。
|
||
|
||
CPU ONNX 服务需要 `server` 与 `onnx-cpu` extras；同一环境还要运行 Detect Client 时加入
|
||
`http`：
|
||
|
||
```bash
|
||
uv sync --locked --extra server --extra http --extra onnx-cpu
|
||
```
|
||
|
||
只校验配置和两条 DAG：
|
||
|
||
```bash
|
||
uv run --no-sync cmvr-edge-ai validate \
|
||
--config configs/server_detect.yaml
|
||
```
|
||
|
||
启动两条被动检测 Pipeline 和 HTTP API：
|
||
|
||
```bash
|
||
uv run --no-sync cmvr-edge-ai serve \
|
||
--config configs/server_detect.yaml \
|
||
--log-level INFO \
|
||
--log-format text
|
||
```
|
||
|
||
`serve` 会启动配置中全部 `enabled: true` 的 Pipeline，不接受 `--pipeline`。启动后可在
|
||
另一终端检查健康状态、能力目录并发起一次检测：
|
||
|
||
```bash
|
||
curl -sS http://127.0.0.1:8081/health/live
|
||
curl -sS http://127.0.0.1:8081/health/ready
|
||
curl -sS http://127.0.0.1:8081/v1/models
|
||
CMVR_DETECT_BASE_URL=http://127.0.0.1:8081 \
|
||
uv run --no-sync python client/detect/example.py \
|
||
/path/to/image.jpg detect.ppe
|
||
```
|
||
|
||
最后一个命令调用 `POST /v1/inference`；也可把 category 改为
|
||
`detect.mobile_phone`。客户端始终不携带 `model_id`、Pipeline ID 或权重路径。
|
||
|
||
若把 `server.http.bind` 改为局域网地址，配置会强制要求 `bearer_token`，并默认要求
|
||
`tls_certfile` 与 `tls_keyfile`。此时调用示例还需设置
|
||
`CMVR_DETECT_BEARER_TOKEN`，base URL 使用 `https://`。只有受信隔离网络才能显式配置
|
||
`allow_insecure_remote: true` 跳过 TLS；存活和就绪探针始终不要求 token。
|
||
|
||
## OpenCV 实时画框 Viewer
|
||
|
||
Viewer 是直接订阅 cmvr-es 相机并同时显示 PPE 与手机检测结果的本地调试入口，不经过
|
||
被动 HTTP API：
|
||
|
||
```bash
|
||
uv run --no-sync python server/detect/show_detections.py \
|
||
--config configs/detection_viewer.yaml \
|
||
--pipeline detection_show \
|
||
--log-level INFO
|
||
```
|
||
|
||
运行前配置远端 endpoint、`device_id` 和两份权重；按 `q` 或 `Esc` 退出。
|