MedGraph Insight Agent

面向 ModelEngine 开源项目贡献赛初赛的独立 MIT 仓库。项目实现一个离线优先的“数据 -> 知识 -> 洞察”闭环：DataMate 风格数据处理算子、Nexent 可调用的 MCP 工具、医疗知识图谱问答智能体，以及图谱驱动 BI 可视化。

作者团队：队长 李佳斌；队员 李佳禾、姚舒文；单位 武汉大学计算机学院。

Highlights

• 任务一：数据处理智能体：支持 JSONL/CSV/TXT 输入，自动规划清洗、抽取、转换、图谱构建和状态跟踪。
• 任务二：医疗知识图谱问答智能体：实体类型覆盖疾病、症状、药物、检查、治疗、科室、风险因素；关系覆盖症状、治疗、诊断、并发、禁忌、科室归属和风险因素。
• 任务三：数据分析智能体：复用同一图谱做 NL2SQL、统计分析、问答证据链和 Dashboard 可视化。
• 可复现与合规：默认无需外部模型或密钥；NPU 路径提供可检测适配层和基准框架，不伪造硬件结果。
• 展示材料：包含 14 页初赛答辩 PPT 与 173.93 秒 1080p 演示 MP4；内容与仓库中的运行结果、质量报告和官网提交包保持一致。

Quick Start

在 WSL2 Ubuntu 内运行：

git clone https://gitlink.org.cn/Lijiabin1234/medgraph-insight-agent.git
cd medgraph-insight-agent
make install
make constraints-check
make verify
make demo
make test
make benchmark
make quality

启动 API 与 Dashboard：

make api

打开 http://127.0.0.1:8080。

Docker 复现：

docker compose up --build -d
make docker-check

make docker-check 会等待 API 启动，并同时检查 /api/health 与 /api/quality。

CLI

medgraph demo --output-dir outputs/latest
medgraph run --task "清洗医疗文本并生成知识图谱" --source data/sample/medical_cases.jsonl
medgraph qa --question "高血压有哪些症状、治疗和检查证据？"
medgraph analyze --question "统计关系类型分布"
medgraph benchmark
medgraph quality --format json
medgraph quality --format text

API

• POST /api/pipelines/run
• GET /api/runs/{run_id} or GET /api/runs/latest
• GET /api/graph
• POST /api/qa
• POST /api/analyze
• GET /api/benchmarks/latest
• GET /api/quality

Nexent Integration

Nexent 作为智能体编排入口时，可通过 MCP 调用本项目工具。配置见 docs/nexent/agent_tool_config.json，暴露工具：

• run_pipeline
• query_graph
• answer_medical_question
• run_analysis
• get_benchmark
• get_quality_report

DataMate Integration

DataMate 作为数据工程入口时，可将本项目作为自定义算子包调用。算子 manifest 见 docs/datamate/operator_manifest.json，Python 入口为：

medgraph_agent.integrations.datamate_adapter:run_datamate_operator

Scoring Matrix

赛题要求	实现位置
任务理解与自主规划	Planner + PipelineRunner
多算子组合与调度	operators/*，五段流水线
状态跟踪与异常处理	PipelineRun + OperatorResult
实体/关系/三元组算子	medical_extraction.py
医疗问答	qa.py + /api/qa
NL2SQL 85%+	analytics.py + data/sample/nl2sql_eval.json
BI 与图谱可视化	web/static/*
NPU 加分路径	benchmark.py 的 AscendNPUBackend
工程可复现	Makefile、Docker、pytest、docs

Outputs and Review Materials

运行 make demo 后生成：

• outputs/latest/run.json
• outputs/latest/records.json
• outputs/latest/graph.json
• outputs/latest/graph_stats.json
• outputs/latest/qa_sample.json
• outputs/latest/analysis_sample.json
• outputs/latest/benchmark.json
• outputs/latest/quality_report.json
• outputs/latest/nl2sql_eval.json

展示与提交辅助材料：

• docs/presentation/medgraph-insight-agent-preliminary-deck.pptx
• docs/presentation/slide-contact-sheet.png
• docs/video/medgraph-insight-agent-polished-demo.mp4
• docs/video/narration-subtitles.srt
• docs/video/video-contact-sheet.png
• docs/video/video_qa.json
• docs/screenshots/dashboard-live.png
• docs/preliminary_report.md
• docs/scorecard.md
• docs/reproducibility.md

Compliance

本仓库采用 MIT License。仓库不包含账号、密码、访问令牌或外部模型密钥。性能报告只标注本机实际测得结果；没有真实 NPU 硬件时，NPU 部分仅作为适配层和待验证路径。

Packaging

git status --short
make package-submission
make package-check
make archive-replay
make preflight
make package-official

make package-submission 生成完整源码归档，便于离线复现；make package-official 生成官网“文件上传”使用的精简评审包，包含 PPT、演示视频、字幕、报告、集成配置和关键验证证据。make package-check、make archive-replay 与 make preflight 用于确认源码归档、运行结果和提交证据一致。复现细节见 docs/reproducibility.md。

依赖复现使用 pyproject.toml 声明直接依赖，constraints.txt 锁定运行时与测试传递依赖；make constraints-check 会确认当前环境与锁定版本一致。