diff --git a/ai-service/README.md b/ai-service/README.md
new file mode 100644
index 0000000..837293c
--- /dev/null
+++ b/ai-service/README.md
@@ -0,0 +1,33 @@
+# 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","detections":[{"bbox":{x,y,w,h},"class":"healthy|sick","confidence":0.95}]}`
+
+## 本地运行
+
+```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
+```
+
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `MODEL_MODE` | `mock` | `mock` / `onnx` |
+| `MODEL_PATH` | `models/best.onnx` | ONNX 模型路径 |
+| `MODEL_LABELS` | `healthy,sick` | 类别列表（逗号分隔） |
+| `MOCK_CLASS` | `healthy` | mock 返回类别 |
+| `MOCK_CONFIDENCE` | `0.95` | mock 返回置信度 |
+
+## 说明
+
+- 只做检测，风险评分在 Go 后端计算（#9：0.5×AI 置信度 + 0.2×环境 + 0.15×阶段 + 0.15×整齐度）。
+- ONNX 后处理按 YOLOv8 常见输出格式实现（含 letterbox 与 NMS），训练产物出来后需用真实模型校准验证。
diff --git a/ai-service/requirements.txt b/ai-service/requirements.txt
new file mode 100644
index 0000000..c396cdf
--- /dev/null
+++ b/ai-service/requirements.txt
@@ -0,0 +1,9 @@
+fastapi>=0.110,<1.0
+uvicorn[standard]>=0.29,<1.0
+onnxruntime>=1.17
+numpy>=1.26
+Pillow>=10.0
+pydantic>=2.5
+python-multipart>=0.0.9
+pytest>=8.0
+httpx>=0.27