haizhiwei

haizhiwei 是一个面向船舶装备故障诊断场景的知识库问答与图谱检索原型。它把结构化故障案例、本地图谱、可选 Neo4j 图数据库，以及用户上传的运维文档结合起来，输出可追溯的诊断建议、排查步骤、维修动作和风险提示。

介绍

这个项目主要用来做船舶设备故障诊断辅助：

• 输入故障现象、报警描述或设备关键词
• 检索结构化案例和上传文档中的相关知识
• 联动本地图谱或 Neo4j 图谱补充证据
• 输出结构化的诊断建议、排查步骤和风险提示

核心能力

• 结构化案例检索：基于设备、部件、故障现象和关键词做快速召回
• 文档知识库检索：支持上传 pdf、docx、txt、md、json、csv、xlsx
• 图谱联动：本地内存图谱可直接使用，Neo4j 可作为增强检索后端
• 结构化诊断输出：包含故障判断、可能原因、排查步骤、维修建议、风险提示
• 证据可追溯：展示命中的案例、文档片段和图谱节点
• 结果导出：支持导出 Markdown / JSON 诊断结果
• Windows 打包：提供免安装便携包构建脚本

技术路线

用户问题
  -> 术语归一化
  -> 结构化案例检索
  -> 文档知识库检索
  -> 图谱补充检索（本地 / Neo4j）
  -> 模板化结构化回答生成
  -> 图谱可视化与结果导出

快速开始

推荐环境：Python 3.10

python -m pip install -r requirements.txt
streamlit run app.py

默认访问地址：

• http://127.0.0.1:8501

主要目录

• app.py：Streamlit 前端入口
• src/haizhiwei/：检索、图谱、文档知识库、导出等核心模块
• data/knowledge_base.json：结构化船舶故障案例演示数据
• tests/：单元测试
• launch_hzw.py：Windows 便携包启动入口
• HaiZhiWei.spec：PyInstaller 打包配置
• build_windows_package.ps1：Windows 便携包构建脚本

运行配置

Neo4j

Neo4j 是可选增强项；未配置时，系统会自动回退到本地图谱检索。

常用环境变量：

• ENABLE_NEO4J
• NEO4J_URI
• NEO4J_USER
• NEO4J_PASSWORD
• NEO4J_DATABASE

PDF 解析

项目默认使用 PyMuPDF，并支持按需启用 MinerU / RapidOCR 作为增强链路。

常用环境变量：

• PDF_PARSE_STRATEGY
• ENABLE_MINERU
• MINERU_COMMAND
• MINERU_BACKEND
• MINERU_METHOD
• MINERU_LANG
• MINERU_TIMEOUT_S

Windows 免安装打包

项目内置了 PyInstaller 打包脚本，可直接生成便携版目录和压缩包：

.\build_windows_package.ps1

默认产物位置：

• dist/HaiZhiWei/HaiZhiWei.exe
• dist/HaiZhiWei-Windows-Portable.zip

测试

python -m unittest discover -s tests -p "test_*.py"

当前实现边界

• 当前回答主链路为模板化结构化输出，强调可解释和可复现
• Neo4j、MinerU、RapidOCR 都是可选增强，不是启动必需项
• 仓库默认不携带本地上传文档、向量库和导出结果
• 演示案例目前覆盖发动机、液压系统、电气设备三类典型问题

后续可扩展方向

• 接入更完整的真实船舶运维案例库
• 增加更细粒度的设备部件 ontology
• 支持更强的图谱问答和多跳推理
• 引入更稳定的评测集与回归测试