让每一个 AI 结论，都能回到图像证据。
Evidence-first multimodal fire-safety inspection
VLM · YOLO · Specialist Review · Deterministic Harness · Human Feedback
XFDemo 不是又一个 VLM Prompt Wrapper。
它是一条面向真实视觉巡检的证据链：模型负责观察，YOLO 负责定位，专项复核负责质疑，确定性规则负责守住边界，人工复核负责持续纠错。
| 01 · SEE | 02 · LOCATE | 03 · VERIFY | 04 · GUARD | 05 · TRACE |
| VLM 理解全图语义 | YOLO 定位可见组件 | 专项模型复核争议项 | 规则阻止无证据结论 | 保存链路并支持人工纠错 |
一张巡检图
│
├── VLM：看到了什么？整体是否异常？
├── YOLO：哪些组件真的可见？分别在哪里？
├── Specialist Review：缺失、方向、折弯是否成立？
├── Harness：标签和证据是否一致？范围有没有串用？
└── Report：只输出最终成立的异常与对应证据
单次 VLM 输出在真实巡检中很容易遇到这些问题：
| 常见问题 | XFDemo 的处理方式 |
|---|---|
| 首轮识别到了异常，后续复核却把它覆盖 | 专项复核只拥有自己负责的标签，不允许清空其他证据 |
| YOLO 没检出组件，系统就断言“组件缺失” | YOLO 只提供辅助候选框，未检出不能单独证明缺失 |
| 透明箱门同时显示外观和内部，模型范围串用 | 先做检查范围对齐，再调用对应检测链路 |
| 自然弧度被误判为软管严重折弯 | 使用折弯专项证据门槛和反例约束 |
| 报告结论与正文证据互相矛盾 | 按“最终标签 → 对应证据”重新构建报告 |
| 线上误判无法定位是哪个环节造成的 | 保存阶段耗时、状态、模型摘要和 YOLO 可视化 |
 组件级定位 YOLO 检测框与 VLM 语义互相校验 |
 缺失类专项复核 水枪、水带等高误判标签独立验证 |
 外观与标识识别 内部组件和箱体外观使用独立范围 |
- 智能检测：上传图片，生成带证据的结构化检测报告。
- 检测历史：查看原图、YOLO 可视化、最终标签和完整推理链路。
- 人工复核：确认或修正模型结论，记录问题来源和复核依据。
- 数据集看板：浏览严格清洗版本、标签、Prompt 版本和数据拆分。
- 多模态检索演示：展示以图搜图、以文搜图和以图搜文的交互链路。
- 法规库与知识图谱演示：为后续可验证法规引用和关系检索预留产品形态。
- 型材计数：独立 YOLO 服务演示多任务接入方式。
flowchart LR
UI["Vue 3"] --> API["Flask API"]
API --> SCOPE{"检查范围"}
SCOPE -->|内部组件| VLM["VLM 初检"]
SCOPE -->|箱体外观| VLM
SCOPE -->|可定位目标| YOLO["YOLO 辅助检测"]
VLM --> JUDGE["二次复核"]
YOLO --> JUDGE
JUDGE --> MISSING["缺失专项"]
JUDGE --> DIRECTION["栓口方向专项"]
JUDGE --> BEND["软管折弯专项"]
MISSING --> MERGE["标签与证据合并"]
DIRECTION --> MERGE
BEND --> MERGE
MERGE --> HARNESS["确定性 Harness"]
HARNESS --> REPORT["最终报告"]
HARNESS --> TRACE["推理链路"]
REPORT --> HISTORY["历史与人工复核"]
TRACE --> HISTORY
classDef primary fill:#E53935,color:#fff,stroke:#C62828;
classDef evidence fill:#FDECEC,color:#8E1B18,stroke:#E57373;
classDef output fill:#202124,color:#fff,stroke:#111;
class VLM,YOLO,JUDGE primary;
class MISSING,DIRECTION,BEND,MERGE,HARNESS evidence;
class REPORT,TRACE,HISTORY output;
-
检查范围对齐 区分内部组件、箱体外观和双范围可见，避免内部模型与外观模型串用。
-
标签别名归一化 将模型产生的同义表达映射到标准标签，减少 Prompt 变化造成的标签漂移。
-
证据门控 缺失、方向、折弯等高风险标签必须满足各自的可见证据条件。
-
专项结果隔离 每个专项只能修改自己负责的标签，不能覆盖其他阶段已经成立的异常。
-
冲突消解 组件明确可见时阻止“未检出即缺失”；视角或证据不足时返回无法判断。
-
报告重建 最终报告按照“最终标签 → 对应证据”生成，确保结论、标签和正文一致。
| Layer | Stack |
|---|---|
| Web | Vue 3 · Vite · Vue Router · Lucide |
| API | Flask · Python |
| Vision | OpenAI-compatible / Anthropic-compatible VLM API |
| Detection | Ultralytics YOLO |
| Orchestration | Staged Pipeline · Specialist Review · Rule Harness |
| Observability | JSONL History · Stage Trace · YOLO Visualization |
| Deployment | Docker · Nginx · Gunicorn |
git clone https://github.com/Chan-Developer/XFDemo.git
cd XFDemo推荐使用 Python 3.11。
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-backend.txt在项目根目录创建 .env，至少配置一个兼容 OpenAI API 的视觉模型：
FIRST_VL_PROVIDER=openai
FIRST_VL_API_BASE=https://your-vlm-endpoint.example/v1
FIRST_VL_API_KEY=your-api-key
FIRST_VL_MODEL=your-vision-language-model
JUDGE_VL_PROVIDER=openai
JUDGE_VL_API_BASE=https://your-vlm-endpoint.example/v1
JUDGE_VL_API_KEY=your-api-key
JUDGE_VL_MODEL=your-judge-model尚未准备 YOLO 权重时，可以先使用纯 VLM 模式：
YOLO_ENABLED=0python -m backend.app
curl http://127.0.0.1:5000/health推荐使用 Node.js 18 或更高版本。
cd frontend
npm ci
npm run dev访问 http://127.0.0.1:3000。Vite 会把 /api 请求代理到 http://127.0.0.1:5000。
启用 YOLO 辅助检测
仓库不包含模型权重。准备内部组件和外观模型后，在 .env 中配置：
YOLO_ENABLED=1
YOLO_PYTHON=/path/to/yolo/python
YOLO_INTERNAL_WEIGHTS=/path/to/fire_hydrant_internal.pt
YOLO_APPEARANCE_WEIGHTS=/path/to/fire_hydrant_appearance.pt
YOLO_CLASSES_FILE=/path/to/classes.json
YOLO_DEVICE=0
YOLO_CONF=0.20YOLO 是辅助证据源，检测框不会直接决定最终合规结论。
XFDemo/
├── backend/
│ ├── api/ # Flask 路由
│ ├── config/ # 环境与路径配置
│ ├── infrastructure/ # VLM、YOLO、型材计数客户端
│ └── modules/
│ ├── inspection/ # Prompt、复核、规则与报告生成
│ ├── history/ # 检测历史与人工复核
│ └── dataset/ # 数据集查询服务
├── frontend/ # Vue 3 + Vite
├── services/pipes_counting/ # 型材计数推理服务
├── tools/
│ ├── data_pipeline/ # 数据处理与统计
│ ├── training/qwen25vl/ # 多模态微调数据构建
│ └── research/vision_attention/ # 离线研究工具
├── resources/ # 参考图与演示样例
├── scripts/ # 启动、推理和部署脚本
├── deploy/ # Docker 与 Nginx 配置
├── archive/legacy/ # 历史实现，仅供追溯
├── artifacts/ # 模型与导出物，不提交 Git
├── output/ # 离线任务产物，不提交 Git
└── runtime/ # 在线运行产物，不提交 Git
模型权重、训练数据、API Key、检测历史、日志和运行产物不会提交到仓库。你需要使用自己的模型服务、权重和数据完成部署。
法规库、多模态检索和知识图谱当前包含演示能力，不应直接用于真实执法、正式合规认定或其他高风险决策。
- 固定人工标注回归集与端到端评测脚本
- 检测历史迁移到结构化数据库
- 组件级置信度校准和跨模型冲突统计
- 法规知识库的可验证引用与版本管理
- 可复现的 Docker Compose 开发环境
- 英文界面与英文文档
欢迎通过 Issues 分享误判样例、Prompt 设计、YOLO 数据集、评测方法或工程建议。
提交问题时，请尽量包含：
- 脱敏后的原始图片
- 期望结论和可见证据
- 实际输出与推理链路
- 使用的模型、配置和复现步骤
Built for traceable multimodal inspection.