航空事故致因抽取与知识图谱项目 (Aviation Accident Analysis)

<!-- mcp-name: io.github.hzy9981/aviation-accident-analysis -->

本项目基于 Microsoft GraphRAG 框架 ，旨在自动从航空事故报告中抽取实体与因果关系，并构建符合“人-机-环-管”框架的知识图谱。

项目结构

• data/: 原始数据与地标数据。
• input/: GraphRAG 输入目录（清洗后的文本）。
• output/: GraphRAG 输出结果（Parquet, GraphML 等）。
• prompts/: 自定义的 GraphRAG 提取提示词。
• src/:
  • ingest.py: PDF/DOCX 解析与文本清洗。
  • evaluate.py: 提取准确率与 F1 分数评测脚本。
• run.sh: 一键运行脚本。
• settings.yaml: GraphRAG 配置文件。

环境要求

• Python 3.10+
• uv (推荐)

环境配置注意事项

• 若遇到 LLM 连接错误，请检查 settings.yaml 中的 api_base 是否配置正确。在某些 Docker 或受限环境中，建议将 localhost 修改为 127.0.0.1。
• 本项目已对 prompts/extract_graph.txt 中的抽取示例进行了优化，通过引入复杂场景示例，提升了在航空事故报告中的实体抽取表现。

Prompt 优化与评估记录 (2026-07-24)

优化策略

针对航空事故报告的复杂性，对 prompts/extract_graph.txt 进行了多轮手动迭代优化：

1. 实体原子化：强制拆分复杂短语（如“燃油管路破裂”拆分为实体“燃油管路”与关系“破裂导致”），提升知识图谱的结构化程度。
2. 严格去噪：建立了否定约束，排除通用职衔（如单独的“机长”）和指示代词（如“该部件”），提升精确率。
3. 少样本增强：集成了 few_shot_data.csv 中的高质量航空事故致因链示例，引导模型识别长程因果关系。
4. 因果链强制构建：明确 [因素] -> [事件] -> [结果] 的链条要求。

评估结果 (Fuzzy Match)

通过 scripts/run_automated_evaluation.py 运行自动化评估，对比 data/ground_truth.json 得到以下指标：

指标	实体 (Entities)	关系 (Relationships)
精确率 (Precision)	0.4348	0.0556
召回率 (Recall)	0.7143	0.0909
F1 分数 (F1 Score)	0.5405	0.0690

结论：实体抽取的精确率和 F1 分数相比基准版本有显著提升。关系抽取受限于本地模型的指令遵循能力，仍有优化空间。

MCP 服务 (Model Context Protocol)

本项目提供了一个 MCP 服务，方便通过 MCP 客户端（如 Claude Desktop）直接调用文档解析与提示词生成功能。

核心功能

• 文档解析：支持 PDF、DOCX、TXT 格式的自动解析与清洗。
• 提示词注入：将解析出的文档内容自动注入到指定的提示词模板中。

启动方式

uv run mcp_server.py

可用工具

1. upload_and_generate_prompt:
   • 参数 file_path: 文档路径。
   • 参数 template_name: prompts/ 目录下的模板名（默认 extract_entities）。
2. list_available_templates: 列出所有可用的提示词模板。

🐳 一键启动 (Docker)

如果你想快速启动整个分析环境（包含 Neo4j 数据库和 MCP 服务），可以使用 Docker Compose：

docker-compose up -d

启动后：

• Neo4j 控制台: http://localhost:7474 (默认账号: neo4j, 密码: password)
• MCP 服务: 已在容器内运行，并自动连接到容器内的 Neo4j。

运行流程

1. 将事故报告（PDF/DOCX/TXT）放入 data/input_reports。
2. 运行流水线：

   bash run.sh
   

使用 Ollama (本地 LLM)

在 settings.yaml 中修改 completion_models 和 embedding_models：

completion_models:
  default_completion_model:
    model_provider: openai
    api_base: http://localhost:6006/v1
    model: llama3 # 或其他模型
    api_key: ollama # 占位符

注意：GraphRAG 对本地模型的支持取决于模型的遵循指令能力。

提取 Schema (人-机-环-管)

• 实体类型: person (人), equipment (机), environment (环), organization (管), procedure, event, weather, violation.
• 关系类型: leads to, limited by, violates, not executed, belongs to.

Neo4j 知识图谱导入

• 本项目支持将 GraphRAG 提取的实体与关系导入 Neo4j 图数据库。
• 使用 src/export_to_neo4j.py 脚本完成导入。
• 已配置 Docker 容器运行 Neo4j 实例，确保能够正常连接。