Skip to main content
Glama
io.github.hzy9981/aviation-accident-analysis

io.github.hzy9981/aviation-accident-analysis

航空事故致因抽取与知识图谱项目 (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 配置文件。

Related MCP server: docsearch

环境要求

  • 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 实例,确保能够正常连接。

Available Tools

3 tools
list_available_reportsB

List all available reports in a specified directory.

Inputs: directory. Returns: result

list_available_templatesA

List all available prompt templates in the prompts/ directory.

Inputs: no named parameters. Returns: result

upload_and_generate_promptA

Upload an aviation accident report (PDF, DOCX, TXT), parse it, and wrap it in a specified prompt template.

Inputs: file_path (required), template_name. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: uploading and generating a prompt, listing templates, and listing reports. There is no overlap or ambiguity between them.

    Naming Consistency4/5

    All tool names use snake_case and follow a verb-first pattern. The first tool uses a compound verb 'upload_and_generate' while the others use 'list_available', which is a minor deviation but still predictable and readable.

    Tool Count4/5

    Three tools is a slightly thin but reasonable set for the narrow scope of uploading reports and managing available templates/reports. It is within the acceptable range and does not feel excessive.

    Completeness2/5

    The tool surface is incomplete for a server named 'aviation-accident-analysis'. It only supports uploading a report and listing templates/reports, with no tools to actually perform analysis, manage templates (create/update/delete), or retrieve detailed content. This leaves significant gaps that would require external actions.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for exporting PDF to markdown, optimized for LLM consumption.
      698 PyPI
      73
      AGPL 3.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that enables searching and reading binary document files (PDF, DOCX, PPTX, XLSX, ODT, ODS, ODP, RTF, EPUB) using regex patterns and retrieving content by sections.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that extracts clean text, tables, and structured data from documents, images, code, and audio files, supporting 97 formats with OCR, transcription, and code intelligence.
      MIT