MedInsight Agent

基于 Nexent 与 DataMate 的医疗数据治理、知识图谱构建与智能洞察平台

MedInsight Agent 面向医疗数据治理与知识工程场景，围绕 DataMate 与 Nexent 构建数据处理、知识图谱生成和图谱驱动分析三类智能体，形成可复现、可追溯的“数据 -> 知识 -> 洞察”工程链路。

原始医疗文本 / 医疗表格
        |
        v
任务一 Data Processing Agent
清洗、去重、分段、结构化、质量门控
        |
        v
任务二 Medical KG Agent
实体抽取、关系抽取、三元组校验、知识图谱生成、图谱问答
        |
        v
任务三 Graph-grounded Insight Agent
图谱结构理解、NL2SQL、统计分析、BI 可视化、洞察报告

运行效果

Task1 数据处理智能体

Task1 CLI 提供医疗文本、结构化表格、处理规划和异常恢复四类入口：

任务通过 Nexent OpenAPI Tool 执行，输出任务理解、规划器、算子链、质量门控、性能指标及 DataMate 接入状态：

Task2 医疗知识图谱智能体

Task2 CLI 提供医疗文本图谱构建、图谱问答和图谱库管理入口：

知识图谱生成过程展示 Nexent 工具调用、实体与关系抽取、三元组校验、质量门控、知识缺口和算子性能：

生成结果在保存前提供实体节点、图谱关系和待确认图谱预览：

Task3 图谱驱动分析智能体

Task3 CLI 提供图谱洞察分析、自然语言分析、配置化分析和 NL2SQL 评测入口：

分析任务经 Nexent Agent 编排后生成图谱指标、NL2SQL 评测结果、洞察报告和 BI 看板：

自然语言分析同步展示查询结果与可执行 SQL，覆盖实体分布、疾病关系、治疗覆盖和图谱质量等分析场景：

Streamlit 工作台

任务一数据质量与处理结果：

任务二知识图谱质量、实体关系分布与三元组结果：

任务三图谱洞察、BI 看板与评测结果：

项目代码位于：

MedInsightAgent_项目代码/

功能概览

模块	智能体	核心能力	主要入口
任务一	medinsight_data_processing_agent	医疗文本/表格处理、流程规划、质量门控、异常处理、DataMate 接入	scripts/task1/task1_cli_menu.sh
任务二	medinsight_medical_kg_qa_agent	通用医疗文本抽取、三元组校验、知识图谱生成、图谱合并、证据问答	scripts/task2/task2_cli_menu.sh
任务三	medinsight_graph_insight_agent	图谱感知、Graph-aware NL2SQL、统计分析、BI 看板、洞察报告	scripts/task3/task3_cli_menu.sh

三个任务均通过 OpenAPI Tool 接入 Nexent。CLI 负责提供可演示的终端交互，API 负责暴露算子与智能体能力，artifacts/ 目录保存运行报告和评测产物。

核心创新点

1. 任务一：可解释数据处理规划

任务一不是固定脚本清洗数据，而是先对输入数据做画像，再根据自然语言任务生成可解释的处理计划。报告中记录任务理解、算子选择理由、执行事件、异常记录、质量门控和 DataMate 接入状态。

任务一同时保留流程规划小模型能力，包含流程规划数据集、轻量 planner、Qwen2.5-0.5B LoRA adapter 产物和推理入口。

2. 任务二：自校验医疗知识图谱生成

任务二采用 Schema-Guided Self-Verified Medical KG Agent 设计：

医疗文本
  -> 实体抽取
  -> 关系抽取
  -> 三元组生成
  -> Schema 校验
  -> 自动修复
  -> 冲突检测
  -> 图谱质量门控
  -> 知识图谱生成
  -> 证据路径问答

每条知识边保留来源文本和置信度。图谱问答只基于已确认保存的知识图谱库返回答案，输出关系路径和证据文本。

3. 任务二：增量图谱合并

用户可以多次输入医疗文本构建图谱。保存时系统会把新图谱合并进同一个主知识图谱库：

• 同名同类型实体对齐为同一节点；
• 相同 主体-关系-客体 边自动去重；
• 多次输入的证据文本追加到同一条边；
• 主知识图谱库供任务二问答和任务三分析复用。

4. 任务三：图谱驱动洞察智能体

任务三读取任务一处理结果和任务二知识图谱，构建 SQLite 分析库，再通过 Graph-aware NL2SQL、图谱路径查询和统计分析算子生成洞察。

任务三输出：

• 图谱 schema 画像；
• 实体/关系分布；
• 疾病关系结构；
• 药物-疾病关联；
• 中心节点分析；
• 知识缺口检测；
• 任务一数据到任务二知识的转化率；
• BI HTML 看板；
• Markdown 洞察报告；
• NL2SQL 准确率评测。

目录结构

MedInsightAgent_项目代码/
  src/medinsight/
    common/          # 通用 schema、Nexent/DataMate 适配、工具函数
    task1/           # 数据处理智能体、算子、质量门控、planner
    task2/           # 知识图谱生成、图谱问答、图谱库、benchmark
    task3/           # 图谱分析、NL2SQL、BI 看板、洞察报告
  scripts/
    run_pipeline.py  # 一键运行“数据 -> 知识 -> 洞察”完整闭环
    common/          # DataMate/Nexent 启停脚本
    task1/           # 任务一 CLI、API、Nexent 注册、评测脚本
    task2/           # 任务二 CLI、API、Nexent 注册、benchmark
    task3/           # 任务三 CLI、API、Nexent 注册、分析 demo
  config/
    pipeline.json    # 一键闭环 Demo 的输入、输出与任务参数
  data/
    task1/           # 任务一样例数据
    task2/           # 任务二公开医疗数据与样例输入
    task3/           # 任务三配置化分析样例
    shared/          # 任务二图谱库，供任务三复用
  artifacts/
    task1/           # 任务一模型、报告、benchmark 产物
    task2/           # 任务二图谱报告、benchmark 产物
    task3/           # 任务三看板、分析库、洞察报告
    pipeline/        # 一键闭环 Demo 的过程产物
  outputs/           # 一键闭环 Demo 的汇总输出
  docs/
    task1.md
    task2.md
    task3.md
  tests/

外层文档用于提交说明，工程运行以 MedInsightAgent_项目代码/ 为根目录。

环境准备

1. 进入项目目录

git clone https://gitlink.org.cn/Orangeeee/medinsight-agent.git
cd medinsight-agent/MedInsightAgent_项目代码

2. 创建 Python 环境

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

3. 准备 DataMate 与 Nexent

git clone https://www.gitlink.org.cn/modelengine-group/DataMate.git third_party/DataMate
git clone https://www.gitlink.org.cn/foreverGitlink/nexent.git third_party/nexent

4. 启动基础服务

scripts/common/start_datamate.sh
scripts/common/start_nexent.sh

常用页面：

DataMate: http://localhost:30000
Nexent:   http://localhost:3000

Streamlit 可视化界面

项目提供一个轻量 Streamlit 页面，用于查看任务一、任务二、任务三的闭环产物、评测指标、图谱关系分布和 BI 看板。页面只读取已有产物，也可以触发一键闭环脚本重新生成结果。

streamlit run app.py

默认打开地址：

http://localhost:8501

页面包含：

Overview          三任务闭环与关键指标
Task1 Data        数据处理质量与 processed documents
Task2 KG          Agent Plan、实体/关系分布、三元组样例
Task3 Insight     图谱洞察指标与 BI 看板
Evaluation        NL2SQL、质量门控与算子延迟

一键闭环 Demo

首次运行建议先执行完整闭环脚本。该脚本会从公开医疗文本样例开始，依次调用任务一、任务二和任务三能力，生成统一的评测报告和可视化产物。

PYTHONPATH=src python3 scripts/run_pipeline.py --demo

运行完成后会得到：

outputs/evaluation_report.json      # 三任务汇总评测报告
outputs/processed_docs.jsonl        # 任务一处理后的文档
outputs/medical_triples.jsonl       # 任务二生成的三元组
outputs/generated_kg.json           # 任务二合并后的知识图谱
outputs/insight_dashboard.html      # 任务三 BI 看板
outputs/insight_report.md           # 任务三洞察报告

evaluation_report.json 会汇总任务一数据质量、任务二图谱质量、任务三 NL2SQL 与可视化分析指标。运行过程产物保存在 artifacts/pipeline/，不会覆盖各任务的固定样例产物。

运行教程

第一步：运行任务一数据处理智能体

scripts/task1/task1_cli_menu.sh

菜单包含：

处理医疗文本 JSONL
处理结构化医疗 CSV
生成数据处理计划
运行异常处理演示

推荐先选择“处理医疗文本 JSONL”。默认样例为：

data/task1/raw/qamedkg_samples.jsonl

任务一会输出：

data_processing_report.json
events.json
processed_documents.json
segments.json

这些产物记录数据画像、清洗结果、片段结果、质量门控、异常处理和 Nexent 调用信息。

可单独验证 DataMate 的真实数据集上传与清洗任务链路：

PYTHONPATH=src python3 scripts/task1/run_datamate_cleaning_probe.py

该命令会通过 DataMate API 创建测试数据集、上传 JSONL 文件并创建清洗任务，运行记录保存在 artifacts/task1/datamate_cleaning_probe/report.json。

第二步：生成任务二输入数据

任务二默认使用任务一真实处理后的医疗文本。可手动生成一次：

PYTHONPATH=src python3 scripts/task2/prepare_task2_input_from_task1.py

输出位置：

artifacts/task1/task2_cblue_processed/processed_documents.json
data/task2/samples/medical_text_sample.json

第三步：运行任务二医疗知识图谱智能体

scripts/task2/task2_cli_menu.sh

菜单包含：

输入医疗文本构建知识图谱
根据已构建的知识图谱进行问答
清空所有知识图谱

选择“输入医疗文本构建知识图谱”，输入默认样例路径：

artifacts/task1/task2_cblue_processed/processed_documents.json

生成完成后，终端会展示实体节点、图谱关系、质量门控和算子性能。确认加入主知识图谱库：

y

主知识图谱库位置：

data/shared/knowledge_graph/task2_user_medical_kg_library.json

随后可选择“根据已构建的知识图谱进行问答”，示例问题：

肺炎有什么症状？
肺炎需要做什么检查？
肺炎怎么治疗？
肺炎的症状和治疗方法是什么？

第四步：运行任务三图谱洞察智能体

scripts/task3/task3_cli_menu.sh

菜单包含：

运行图谱洞察分析并生成 BI 看板
自然语言分析（NL2SQL）
按配置文件运行分析任务
评测 NL2SQL 准确率
查看任务三产物路径

推荐先选择“运行图谱洞察分析并生成 BI 看板”。任务三会读取：

artifacts/task1/task2_cblue_processed/data_processing_report.json
data/shared/knowledge_graph/task2_user_medical_kg_library.json

主要输出：

artifacts/task3/demos/nexent_demo/analysis/task3_analysis_report.json
artifacts/task3/demos/nexent_demo/analysis/insight_report.md
artifacts/task3/demos/nexent_demo/analysis/medical_kg_analysis.sqlite
artifacts/task3/demos/nexent_demo/analysis/insight_dashboard.html

自然语言分析示例：

当前医疗知识图谱包含哪些实体类型？
当前图谱中最核心的节点有哪些？
哪些药物关联的疾病数量最多？
哪些疾病节点的知识结构不完整？
任务一数据到任务二知识图谱的转化率怎么样？
分析肺炎的关系结构

一次性验证脚本

完整闭环：

PYTHONPATH=src python3 scripts/run_pipeline.py --demo

任务一：

scripts/task1/run_task1_nexent_demo.sh

任务二：

scripts/task2/run_task2_nexent_demo.sh

任务三：

scripts/task3/run_task3_nexent_demo.sh

评测

单元测试：

PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'

任务一调度与文本处理评测：

PYTHONPATH=src python3 scripts/task1/benchmark_task1_scheduler.py \
  --input data/task1/raw/cblue_task1_1000.jsonl \
  --limit 1000 \
  --output artifacts/task1/benchmarks/cblue_hf_cmeee

任务二算子性能评测：

scripts/task2/run_task2_operator_benchmark.sh

任务三 NL2SQL 评测：

PYTHONPATH=src python3 scripts/task3/run_task3_nexent_tool_cli.py \
  --tool eval \
  --graph-path data/shared/knowledge_graph/task2_user_medical_kg_library.json

提交材料说明

文件/目录	说明
MedInsightAgent_项目代码/README.md	工程运行说明
MedInsightAgent_项目代码/docs/task1.md	任务一专项说明
MedInsightAgent_项目代码/docs/task2.md	任务二专项说明
MedInsightAgent_项目代码/docs/task3.md	任务三专项说明
功能说明文档.md	功能总览
技术文档.md	架构与模块说明
API接口文档.md	API 与 Nexent OpenAPI 工具说明
测试文档.md	测试与评测命令
用户手册.md	面向使用者的运行流程
项目演示说明.md	演示流程
DATA_LICENSES.md	公开数据许可说明
CONTRIBUTING.md	贡献流程、数据规范与提交检查
SECURITY.md	安全报告与医疗数据处理规范
CHANGELOG.md	版本功能与工程变更记录
CITATION.cff	软件引用元数据

数据来源

项目内置样例和评测数据来自公开医疗 NLP 数据集与开源医疗样例数据。CBLUE 相关数据用于样例构建、抽取评测和 benchmark。数据许可说明见：

DATA_LICENSES.md

许可证

本项目采用 Apache License 2.0。