EquipDoc-Agent

面向机电设备运维场景的可审核、可降级 Agent。项目将确定性安全策略、LangGraph 人工审核、轴承振动信号诊断工具、可选 RAG 和证据化报告组织为一个可复现的公开工程作品。

当前公开版本默认运行在无模型 Demo 模式：可以完整演示 Agent 工作流，但故障类型是明确标注的固定案例回放，不能作为真实设备诊断结果。Full 模式需要单独配置 Qwen 服务、CNN 权重和可选向量库。

30 秒了解项目

为什么需要这个 Agent

通用大模型无法直接分析振动时序信号，也容易在设备信息不足时生成缺少依据的维修建议。本项目把自然语言交互与专用诊断工具分离，并在高影响工具调用前加入人工审核：

flowchart LR
    A[上传振动信号] --> B[安全校验]
    B --> C[策略判断任务边界]
    C --> D{人工审核}
    D -->|Approve| E[轴承诊断工具]
    D -->|Reject| F[终止工具调用]
    E --> G[检索故障机理与维护依据]
    G --> H[生成带证据与边界的报告]

项目不控制真实设备，不替代工程师作出高风险维修决策，也不根据单段信号预测精确剩余寿命。

核心能力

• 可审核工作流：使用 LangGraph interrupt/resume，在工具执行前展示调用参数并等待审批；
• 确定性安全策略：信号和诊断意图同时满足时才进入诊断分支，关键判断不依赖 LLM 自由发挥；
• 受限信号工具：只接受沙箱内、受限大小、有限数值的 .npy 一维信号；
• 显式降级：缺少 Qwen、CNN 权重或 Chroma 时不静默伪装，Demo 模式和词法检索会明确标注；
• 证据化输出：报告区分输入事实、工具结果、检索依据、建议和适用边界；
• 可复现工程骨架：包含 pyproject.toml、环境变量、Docker、健康检查、Smoke Test 和 CI。

演示结果

诊断工具调用前，系统会暂停工作流并等待人工审核。审核界面只展示工具名称和经过脱敏的文件名，不暴露服务器内部路径。

审批通过后，系统输出带 Demo 标识、检索证据、处理建议和适用边界的报告：

快速运行 Demo

1. 环境要求

• Python 3.10、3.11 或 3.12；
• Demo 模式不需要 GPU、Qwen 模型、CNN 权重或向量库。

2. 创建环境并安装

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[demo]"
Copy-Item .env.example .env

Linux / AutoDL：

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[demo]"
cp .env.example .env

3. 健康检查与测试

python -m equipdoc_agent.health --strict
python scripts/demo_smoke.py
python -m unittest discover -s tests -v

Demo 模式下，bearing_model、bearing_norm 和 rag_vector_db 可以显示为不存在，因为它们不是必需项。

4. 启动页面

python app_gradio.py

打开终端显示的本地地址，默认是：

http://127.0.0.1:7860

若 7860 已被占用，应用会自动尝试 7861、7862 等端口。

5. 体验审核流程

1. 保持“使用仓库内置演示信号”为勾选状态；
2. 使用默认问题“请诊断这段轴承振动信号，并给出判断依据和处理建议”；
3. 点击“提交”，查看待审核的工具名称和参数；
4. 点击 Approve 继续生成报告，或点击 Reject 验证拒绝分支；
5. Demo 报告会明确说明结果是固定案例，不是