silk/ai-service/README.md

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

本地运行

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 -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），训练产物出来后需用真实模型校准验证。