# 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` 退出。