面向智能矿区巡检的多模态 RAG-Agent 系统。项目参考 DriveLM 的“视觉场景理解 + 语言推理 + 行为决策”思想，但将场景迁移到智能矿区巡检：系统能够对矿区道路、皮带机、边坡、积水、落石、人员闯入、车辆占道等风险进行结构化分析，并结合矿区安全规程知识库生成带引用的处置建议和巡检报告。
当前版本定位为：可运行、可演示、可评测，并可扩展到真实多模态模型和无人巡检系统。
在真实无人巡检系统中，大模型不适合直接接管底层车辆控制。本项目将大模型放在更合理的高层认知与决策解释层：
ROS2 / Nav2 / Autoware 负责定位、规划、避障、控制
MinePatrol-Agent 负责场景理解、规程检索、风险判断、报告生成
这个设计适合智能矿区、工业园区、封闭道路巡检等低速无人车场景。
| Version | Status | Key Updates |
|---|---|---|
| v0.1.0 | Offline MVP | 完成离线 RAG-Agent 闭环：场景理解、知识检索、风险评估、报告生成、Streamlit Demo、30 条评测样例。 |
| v0.2.0 | Local VLM | 接入 Ollama + moondream 轻量视觉模型，支持真实图片描述进入 RAG-Agent 流程，并兼容非 JSON 文本解析。 |
| v0.2.1 | GitHub Ready | 增加 README 截图、评测展示和项目展示材料。 |
| v0.3.0 | Vector RAG | 新增 Embedding 向量化、本地向量索引、chunk 检索和可配置 RAG backend，并完成 Ollama nomic-embed-text 真实 Embedding 验证。 |
| v0.3.1 | Release Docs | 补充 Ollama Embedding 验证说明和 GitHub Release 展示。 |
| v0.4.0 | VLM Parsing | 增强视觉模型输出解析，支持 JSON/Markdown JSON/普通文本 fallback，并归一化 scene、objects、hazards。 |
| v0.5.0 | Qwen-VL API | 接入阿里云百炼 Qwen-VL API，完成真实巡检图片场景理解、证据抽取、Vector RAG 和 RiskAgent 闭环实测。 |
| v0.5.1 | Web Demo | Streamlit 页面支持模型提供方切换，并独立展示视觉理解、图像证据和 RAG 检索依据。 |
完整版本记录见 CHANGELOG.md。
- 多模态巡检入口：支持上传巡检图片并输入巡检任务。
- Web 模型切换：Streamlit 页面支持
offline/qwen/ollama/openaiprovider 切换。 - 离线可运行：无 API Key 时使用规则化视觉模拟器，便于展示。
- 本地 VLM 实测：支持 Ollama + moondream 轻量视觉模型，将图片描述接入 RAG-Agent 流程。
- 可扩展 VLM/LLM：支持 Qwen-VL、Ollama、本地模型接口，可替换为更强国内/本地视觉模型。
- 可解释展示：Web 页面单独展示视觉场景摘要、检测对象、隐患候选、图像证据和 RAG 检索来源。
- RAG 增强：检索矿区安全规程、设备巡检规范、应急处置流程。
- Agent 编排：按“场景理解 -> 知识检索 -> 风险评估 -> 报告生成”组织流程。
- 结构化输出：风险等级、隐患类别、处置建议、引用来源、巡检报告。
- 简易评测：内置样例和评测脚本，便于形成可复现实验结果。
巡检任务/图片/备注
-> 多模态场景理解
-> 视觉证据结构化展示
-> 识别隐患候选
-> RAG 检索矿区安全规程
-> Agent 风险评估
-> 结构化 JSON + Markdown 巡检报告
详细架构见 docs/ARCHITECTURE.md。
cd D:\AIproject\MinePatrol-Agent
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python scripts\run_demo.py
streamlit run app.py如果只是先验证核心逻辑，可以不安装 Streamlit，直接运行：
python scripts\run_demo.py
python scripts\run_eval.py默认配置为 offline，即无 API Key 也可以跑完整流程。若要接入真实 VLM，复制 .env.example 为 .env，并设置模型提供方。
# offline | qwen | ollama | openai
MINEPATROL_MODEL_PROVIDER=qwen
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_VLM_MODEL=qwen-vl-plus阿里云百炼 API Key 建议放在系统环境变量中，不要写入 .env 或代码。推荐变量名：
DASHSCOPE_API_KEY=your_key如果本机已经使用 OpenAI-compatible 命名，也兼容：
OPENAI_API_KEY=your_dashscope_keyQwen-VL 真实图片 Demo：
python scripts\run_qwen_vlm_demo.py也可以指定图片：
python scripts\run_qwen_vlm_demo.py --image data\samples\积水.webp已实测输出包括结构化视觉结果、图像证据、向量 RAG 检索来源、风险等级和巡检报告路径。例如 Qwen-VL 可识别“矿区运输道路上有大块落石堵塞，车辆通行受阻”，并输出落石/边坡滚石、车辆占道/会车风险等隐患。
本地轻量 VLM 已使用 moondream 跑通图片描述链路。它适合普通笔记本快速验证：
ollama pull moondream.env 配置：
MINEPATROL_MODEL_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_VLM_MODEL=moondream轻量 VLM 有时只返回普通文本描述而非 JSON。本项目在 provider 层增加了非 JSON 文本兼容解析：如果模型返回类似 rocky hillside, large rocks, car, road 的描述，系统会将其转换为统一的 VisionObservation，再继续执行 RAG 检索、风险评估和报告生成。
如果真实模型调用失败，系统会自动回退到离线分析，并在报告证据中记录失败原因，保证 Demo 不会中断。
MinePatrol-Agent/
app.py # Streamlit Web Demo
src/minepatrol/
config.py # 配置
schemas.py # 数据结构
agent/pipeline.py # Agent 主流程
vision/analyzer.py # 图片/场景理解，可接真实 VLM
rag/retriever.py # 轻量 RAG 检索
report/generator.py # 巡检报告生成
data/knowledge/ # 矿区规程与设备知识库
data/samples/ # 样例任务
eval/cases.json # 评测样例
scripts/run_demo.py # 命令行演示
scripts/run_eval.py # 简易评测
scripts/run_qwen_vlm_demo.py # Qwen-VL 真实图片演示
outputs/ # 运行生成报告
运行：
python scripts\run_eval.py当前 30 条内置样例结果：
risk_level_accuracy: 1.0
hazard_hit_rate: 1.0
citation_rate: 1.0
expected_level_distribution: high=10, medium=17, low=3
评测集覆盖道路积水、车辆占道、边坡落石、皮带机异常、人员闯入、低照度、扬尘、烟雾火情和正常巡检等场景。
{
"scene_summary": "巡检任务指向 haul_road 场景，发现道路积水、车辆占道等风险。",
"risk_level": "medium",
"hazards": ["道路积水", "车辆占道"],
"recommended_action": "降低车速，保持安全距离，必要时绕行并上报调度中心。",
"citations": ["矿区道路巡检规范", "露天矿区车辆会车安全规范"],
"report_path": "outputs/patrol_report_xxx.md"
}offline：规则化场景理解，适合无模型环境稳定演示。qwen：已接入并实测阿里云百炼 Qwen-VL API，适合国内网络环境下调用真实视觉大模型。ollama + moondream：已跑通本地轻量 VLM 图片描述接入流程。openai：保留 OpenAI-compatible 兼容接口，不作为当前主路线。- Provider 可替换：后续可将 moondream 替换为 Qwen2.5-VL、InternVL、LLaVA 等更强国内/本地视觉模型。
项目支持两种知识检索后端：
# keyword | vector
MINEPATROL_RAG_BACKEND=vector
# local | ollama
MINEPATROL_EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
MINEPATROL_VECTOR_STORE_PATH=data/vector_store/knowledge_vectors.jsonkeyword：轻量关键词/统计检索，适合最小依赖稳定演示。vector：将矿区规程 Markdown 切分为 chunk，生成 embedding，写入本地向量索引，再通过余弦相似度召回 Top-K 规程片段。localembedding：无额外模型依赖，适合快速验证“向量化 -> 入库 -> 检索 -> Agent 推理”闭环。ollamaembedding：已接入并验证nomic-embed-text本地 Embedding 模型，可完成真实语义向量生成与 chunk 级检索。
本地 Embedding 模型准备：
ollama pull nomic-embed-text.env 推荐配置：
MINEPATROL_RAG_BACKEND=vector
MINEPATROL_EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-textOllama Embedding 模式下的 30 条内置样例评测结果：
risk_level_accuracy: 1.0
hazard_hit_rate: 1.0
citation_rate: 1.0
- 替换更强 VLM：Qwen2.5-VL、InternVL、LLaVA 或更高精度本地多模态模型。
- 增加图像标注：在巡检图片上标出风险区域，并输出可视化证据。
- 引入 LangGraph：将当前顺序 pipeline 升级为可回溯、有状态 Agent 图。
- 接入 Qdrant/Chroma：将当前本地 JSON 向量索引升级为正式向量数据库，并支持混合检索。
- 扩展评测集：构造 50-100 条矿区图片/文本任务，评估风险识别和引用命中率。
- 加入 ROS2/Nav2 接口：把 Agent 输出映射为停车、绕行、上报、人工接管等高层行为。