weijuesen
49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# ai-service（规划中：AI 推理微服务）
|
||
|
||
FastAPI + ONNX Runtime 的蚕病检测推理服务。YOLO 训练挂起期间以 **mock 模式**跑通链路，训练恢复后放置 `models/best.onnx` 并切换 `MODEL_MODE=onnx`。
|
||
|
||
## 接口
|
||
|
||
- `GET /health` → `{"status":"ok","model":"mock|onnx"}`
|
||
- `POST /detect`（multipart 字段 `file`）→ `{"model":"mock","modelVersion":"...","isMock":true,"status":"healthy|abnormal|unknown","abnormalProbability":0,"detections":[{"bbox":{x,y,w,h},"class":"healthy|sick","confidence":0.95}]}`
|
||
- `POST /internal/stream-tasks`（需 `X-Internal-Key`）→ 创建受限拉流任务，不再接受客户端任意 URL
|
||
|
||
## 本地运行
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
.venv/Scripts/pip install -r requirements.txt # Windows
|
||
# Linux: .venv/bin/pip install -r requirements.txt
|
||
.venv/Scripts/python -m pytest tests -q
|
||
MODEL_MODE=mock .venv/Scripts/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
## 质量检查
|
||
|
||
仓库根目录的 `scripts/verify.ps1` 会使用 `ai-service/.venv/Scripts/python.exe` 运行 pytest；如果该虚拟环境不存在，会回退到 `python`。
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File scripts/verify.ps1
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `MODEL_MODE` | `mock` | `mock` / `onnx` |
|
||
| `MODEL_PATH` | `models/best.onnx` | ONNX 模型路径 |
|
||
| `MODEL_LABELS` | `healthy,sick` | 类别列表（逗号分隔） |
|
||
| `MODEL_VERSION` | `mock-2026.08.14` / `best.onnx` | 模型版本；真实模型上线时必须显式配置 |
|
||
| `MOCK_CLASS` | `healthy` | mock 返回类别 |
|
||
| `MOCK_CONFIDENCE` | `0.95` | mock 返回置信度 |
|
||
| `INTERNAL_API_KEY` | `silk-internal-2026` | 内部接口认证密钥 |
|
||
| `ALLOWED_STREAM_HOSTS` | `localhost,127.0.0.1,100.83.103.1` | 允许拉流的主机白名单 |
|
||
| `STREAM_TASK_MAX_WORKERS` | `2` | 流任务并发 worker 数 |
|
||
| `STREAM_TASK_MAX_FRAMES` | `10` | 单任务最大抽帧数 |
|
||
|
||
## 说明
|
||
|
||
- 只做检测并返回 `abnormalProbability`；风险评分在 Go 后端计算（#9：0.5×AI 异常概率 + 0.2×环境 + 0.15×阶段 + 0.15×整齐度，缺失项归一化）。
|
||
- `healthy` 高置信度不贡献异常概率；空检测或 `unknown` 返回 `unknown`，不自动视为健康。
|
||
- ONNX 后处理按 YOLOv8 常见输出格式实现（含 letterbox 与 NMS），训练产物出来后需用真实模型校准验证。
|