ModelEngineBySoldierBoy

基于 ModelEngine 生态 DataMate 与 Nexent 的“数据-知识-洞察”医疗智能体参赛项目。

目标

• 构建数据处理智能体：医疗文本/结构化数据清洗、抽取、转换与流水线执行。
• 构建医疗知识图谱生成与问答智能体：实体抽取、关系抽取、三元组生成、图谱问答。
• 构建数据分析智能体：基于图谱做统计分析、NL2SQL 查询与可视化展示。

当前状态

• 官方源码已在 WSL 工作区准备：
  • ../upstream/DataMate
  • ../upstream/nexent
• 本仓库作为参赛交付主仓库，后续代码、Demo、文档和评测结果放在这里。
• 当前仓库已具备可运行的医疗智能体链路。这里的 CLI/API 是参赛 Demo 和 Nexent OpenAPI/MCP 工具服务入口；任务一真实执行链路通过 DataMate API 完成数据集创建、文件上传、算子市场查询、清洗任务创建、状态轮询和结果采集，不用本地 Python 假装 DataMate 处理结果：
  • 正式验收：bash scripts/prepare_submission.sh --knowledge-base-id d769e9b3-2348-46d1-b0ab-bbaf499d748d --cblue-source data/external/cblue --cblue-limit 300 --no-screenshots
  • 数据处理：python3 -m demo.run_medical_demo process --output-root . --input data/raw/medical_demo.jsonl --task "清洗医疗文本并抽取字段，标准化为图谱输入"
  • 数据分析：python3 -m demo.run_medical_demo analyze --output-root .
  • NL2SQL 评测：python3 -m demo.run_medical_demo nl2sql-eval --output-root .
  • CLI：python3 -m demo.run_medical_demo build --output-root .
  • HTTP API：python3 -m demo.app_server --port 8088
  • 平台集成证据：python3 -m demo.run_medical_demo integrate --output-root .
  • CPU benchmark：python3 -m benchmarks.kg_operator_benchmark --output benchmarks/results/entity_extract_cpu.json
• 任务三的分析输出已包含分析报告、查询摘要、NL2SQL 评测报告、图表数据和子图数据。
• 任务一已补强自然语言任务输入、动态执行计划、状态跟踪、质量告警、异常恢复动作和处理报告。
• 任务一报告：demo/task1_processing_report.md；异常恢复报告：demo/task1_invalid_processing_report.md。
• 任务二已新增图谱质量报告：demo/kg_quality_report.md；CBLUE CMeIE/CMeEE 转换脚本：scripts/convert_cblue_to_medical_kg.py。
• 当前严格链路接入官方 CBLUE 本地数据源，最近一次记录为 320 docs、4468 entities、3403 triples、15 类关系、0 rejected。
• 当前 NL2SQL 评测集 70/70 通过，准确率 100.00%，高于赛题 85% 要求。
• 当前 DataMate/Nexent 已在本机 Docker/WSL 中真实启动并完成集成证据刷新：DataMate UI http://localhost:30000，DataMate Gateway http://localhost:8080，Nexent UI http://localhost:3000，Nexent Config API http://localhost:5010。
• 当前平台链路已完成 DataMate 模型配置、数据集文件上传、DOCUMENT 知识库创建、Nexent tenant DataMate URL 持久化、Nexent 知识库同步和 datamate_search 检索；最新 trace 为 HTTP 200，结果数 5。
• 任务一可选小模型增强已完成标准 Transformer LoRA 训练：Qwen3-0.6B + LoRA，56,000 条编排数据，远端 Ascend NPU 训练完成；holdout/OOD operator_micro_f1=0.9943，独立 manual blind v2 operator_micro_f1=0.9553。
• NPU 加分项已接入三处真实算子层：任务一新增 DataMate operator market 候选排序/DAG 规划输入的 tensor ranker，用于智能体侧多算子组合与调度；任务二新增 tensor KG 后端，将实体候选召回、关系意图排序和三元组生成支撑层改为 CPU/Ascend NPU 可运行的张量化候选排序算子，其中核心 candidate scoring + top-k kernel 已达到 15.3177x，4x 更大 score count 复测仍达到 14.0649x；任务三新增图谱多关系相似度 tensor 算子，用于图谱驱动分析和 BI 可视化。总报告见 docs/npu_optimization_summary.md；远程 Ascend 910B2C 证据见 docs/task1_tensor_ranker_cpu_npu_comparison.json、docs/task2_tensor_kernel_1_5x_npu_comparison.json、docs/task2_tensor_kernel_large_batch_npu_comparison.json、docs/task2_tensor_pipeline_cpu_npu_evidence.json、docs/task2_task3_tensor_npu_chain_evidence.json，算子级 CPU/NPU 性能报告见 docs/task1_tensor_ranker_npu_optimization_report.md、docs/task2_tensor_kernel_1_5x_npu_report.md、docs/tensor_kg_npu_optimization_report.md、docs/task3_tensor_npu_optimization_report.md。

架构边界

本仓库不是把智能体逻辑完全写进 Nexent 源码内部，而是按比赛要求“基于 Nexent 构建智能体”：将三个智能体作为 OpenAPI/MCP 工具注册到 Nexent，由 Nexent /agent/run 进行自然语言触发、工具发现、工具绑定和调用验证。

• demo/app_server.py、demo/task*_openapi.py：提供 Nexent 可调用的工具服务和 OpenAPI 描述。
• agents/integration_agent.py：负责 DataMate/Nexent 配置、工具注册、工具可见性和 /agent/run 证据采集。
• agents/datamate_processing_agent.py：任务一智能体编排层，真实调用 DataMate 数据接入、算子市场、清洗任务和状态跟踪 API。
• agents/medical_kg_agent.py：任务二 KG 智能体，编排实体抽取、关系抽取、三元组生成与校验算子。
• agents/analysis_agent.py：任务三分析智能体，复用任务一、二产物，执行图谱理解、NL2SQL、统计/关联/图算法分析和 BI 可视化。

代码中的规则、约束和策略模型用于任务理解、质量门禁、算子选择、DAG 多目标排序、NL2SQL schema linking 和医学三元组校验；DataMate/Nexent 集成情况以 demo/integration/*、docs/capability_matrix_report.* 和 docs/final_acceptance_report.md 中的工具注册、服务探测、DataMate 任务状态、datamate_search 和 /agent/run 记录为准。

文档入口：

• 文档导航
• 初赛项目书终稿 PDF
• 初赛项目书 LaTeX 源文件
• WSL 下 DataMate/Nexent 配置说明
• DataMate/Nexent 集成证据采集说明
• 赛题要求映射
• 比赛提交证据包说明
• 最终提交清单

推荐目录规划

.
├── agents/          # 数据处理、知识图谱、分析智能体
├── benchmarks/      # CPU 性能评测脚本与结果
├── data/            # 样例医疗数据与处理后数据
├── demo/            # CLI/API/Notebook/前端 Demo
├── docs/            # 架构、部署、复现、评测说明
├── graph/           # 图谱 schema、三元组、图数据导出
├── operators/       # KG/分析算子与 DataMate 算子选择辅助
└── scripts/         # 环境检查、数据准备、运行脚本

快速运行

端到端编排三个核心参赛智能体：

python3 -m demo.run_medical_demo orchestrate \
  --output-root . \
  --input data/raw/medical_demo.jsonl

该命令会串联：

DataProcessingAgent -> MedicalKGAgent -> InsightAnalysisAgent

并输出：

demo/orchestration_summary.json
demo/orchestration_trace.jsonl
demo/orchestration_report.md

任务一，数据处理：

python3 -m demo.run_medical_demo process \
  --output-root . \
  --input data/raw/medical_demo.jsonl \
  --task "清洗医疗文本并抽取字段，标准化为图谱输入"

任务一异常恢复样例：

python3 -m demo.run_medical_demo process \
  --output-root . \
  --input data/raw/medical_demo_invalid.jsonl \
  --task "清洗医疗文本并检查异常，恢复重复和空文本问题"

离线构建：

python3 -m demo.run_medical_demo build --output-root .

启动本地 API：

python3 -m demo.app_server --host 127.0.0.1 --port 8088

浏览器仪表盘：

http://127.0.0.1:8088/dashboard

任务三 NL2SQL 评测：

python3 -m demo.run_medical_demo nl2sql-eval --output-root .

可选模型产物

任务一可选小模型产物不放入源码仓库，单独通过网盘提供，避免仓库膨胀。仓库内只保留训练/评估脚本、selector 配置和小体积 JSON 证据；LoRA adapter、joblib 模型和完整训练集作为外部模型包提供。如需验证模型侧增强，可下载并解压到仓库根目录：

• 历史模型包文件名：modelengine_task1_policy_artifacts_20260705.zip
• 最新 v7 LoRA adapter 包：modelengine_task1_lora_qwen06b_v7_targeted.zip
• 网盘文件：ModelEngine初赛模型
• 链接：https://pan.baidu.com/s/1s-2L7JgXvSVuxSVV80hPCQ?pwd=5rxb
• 提取码：5rxb
• 历史模型包 SHA256：6ef6fbd769c6045900d3880c875c7a792ca4fd92406d2a9352f168948489f1a0
• v7 LoRA adapter 包 SHA256：e9c8d7f99c6188112da875f702ae2e296cfdda0495934f188fec1caed39277f9

当前网盘文件夹包含早期可复现模型产物和最新 v7 LoRA adapter 包。如需复现 v7 推理，请下载 modelengine_task1_lora_qwen06b_v7_targeted.zip 并解压到仓库根目录；该包会提供 models/task1_policy/task1_lora_qwen06b_v7_targeted/adapter/ 权重、v7 训练指标和 holdout/OOD、manual blind v2 评估结果。Qwen3-0.6B 基座模型不包含在本仓库或网盘包内，需要按 models/task1_policy/task1_policy_selector_config.v7.json 中的 base_model 配置自行准备。

models/task1_policy/task1_lora_qwen05b_v4/
models/task1_policy/task1_orchestration_policy.joblib
models/task1_policy/task1_orchestration_policy_metrics.json
models/task1_policy/task1_policy_selector_config.json
models/task1_policy/task1_policy_ab_evaluation.json
models/task1_policy/task1_policy_ab_evaluation.md
models/task1_policy/task1_neural_orchestration_policy.joblib
models/task1_policy/task1_neural_orchestration_policy_metrics.json

models/task1_policy/task1_lora_qwen06b_v7_targeted/
models/task1_policy/task1_lora_qwen06b_v7_targeted_holdout_ood/
models/task1_policy/task1_lora_qwen06b_v7_targeted_manual_blind_v2/
models/task1_policy/task1_policy_selector_config.v7.json

本地校验：

sha256sum modelengine_task1_policy_artifacts_20260705.zip
sha256sum modelengine_task1_lora_qwen06b_v7_targeted.zip

解压后可验证：

python3 -m unittest \
  tests.test_datamate_processing_agent.DataMateProcessingAgentTests.test_task1_policy_ab_evaluation_and_selector_config_are_reproducible \
  tests.test_datamate_processing_agent.DataMateProcessingAgentTests.test_task1_transformer_lora_policy_artifacts_are_real_peft_outputs \
  tests.test_datamate_processing_agent.DataMateProcessingAgentTests.test_task1_neural_policy_model_outputs_orchestration_policy

最新 v7 LoRA 证据可直接检查：

python3 scripts/verify_task1_lora_v7_goal.py

已记录的 v7 指标：

holdout/OOD operator_micro_f1: 0.9943
manual blind v2 operator_micro_f1: 0.9553

因此当前可声明“完成小于 1B 的数据处理编排策略模型训练，并通过 holdout/OOD 与独立 manual blind v2 验证”。

主链路使用方式：

v7 LoRA 生成候选编排策略
  -> transformer_lora_guard 校验 workflow、operator_catalog、能力覆盖、低成本/质量约束
  -> 通过：作为 DataMate 算子 DAG 搜索的候选偏置
  -> 不通过：记录 rejected_operator_ids 和原因，回退到规则/约束规划器

因此 v7 LoRA 不会无保护地接管 DataMate 执行链路；稳定性由规则/约束规划器、DataMate operator market 和 DAG 校验共同保证。

任务二 CBLUE 数据转换：

python3 scripts/convert_cblue_to_medical_kg.py \
  --dataset cmeie \
  --input-dir data/external/cblue \
  --output-dir data/external/converted/cblue \
  --limit 300

采集 CBLUE 数据证据：

bash scripts/collect_cblue_evidence.sh --source data/external/cblue

把转换后的 CBLUE 产物并入任务二图谱构建：

python3 -m demo.run_medical_demo build \
  --output-root . \
  --external-documents data/external/converted/cblue/cmeie_documents.jsonl \
  --external-triples data/external/converted/cblue/cmeie_triples.jsonl \
  --external-entities data/external/converted/cblue/cmeee_entities.jsonl

采集 DataMate/Nexent 集成证据：

bash scripts/check_platform_env.sh
bash scripts/collect_integration_evidence.sh --knowledge-base-id d769e9b3-2348-46d1-b0ab-bbaf499d748d --timeout-seconds 12

如果 DataMate 中已创建知识库：

python3 -m demo.run_medical_demo integrate --output-root . --knowledge-base-id <DataMate knowledge base id>

重采集前确保 DataMate Milvus profile 健康，并启动模型代理。当前 DataMate 后端通过 Docker 网络访问 modelengine-model-proxy:18089：

bash scripts/start_model_proxy.sh
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' | rg 'milvus|datamate|nexent-config'

如果使用远程 Ascend/NPU 算力容器，只在远程容器内运行 OpenAI-compatible 模型服务，本地 WSL 继续运行 DataMate、Nexent 和 Demo API。推荐链路：

DataMate/Nexent Docker -> 本地模型代理 :18089 -> SSH 隧道 :18090 -> 远程 NPU 模型服务 :8000

本地启动顺序：

bash scripts/start_remote_npu_tunnel.sh
bash scripts/start_model_proxy.sh
bash scripts/check_remote_npu_model_proxy.sh

该模式默认 MODEL_PROXY_ALLOW_LOCAL_FALLBACK=false。如果远程 NPU 模型服务没有启动，请求会返回 502，不会退回本地规则回复。

运行 CPU benchmark：

python3 -m benchmarks.kg_operator_benchmark --output benchmarks/results/entity_extract_cpu.json

运行任务一规划 ranker tensor/NPU benchmark：

python3 -m benchmarks.task1_tensor_ranker_benchmark --device cpu --output benchmarks/results/task1_tensor_ranker_cpu.json
python3 -m benchmarks.task1_tensor_ranker_benchmark --device npu --output benchmarks/results/task1_tensor_ranker_npu.json

运行任务二 tensor/NPU 后端：

MEDICAL_KG_TENSOR_DEVICE=auto python3 -m demo.run_medical_demo build --kg-backend tensor --output-root .
MEDICAL_KG_TENSOR_DEVICE=npu python3 -m demo.run_medical_demo build --kg-backend tensor --output-root .

运行任务三图谱分析 tensor/NPU 算子：

TASK3_ANALYSIS_TENSOR_DEVICE=auto python3 -m demo.run_medical_demo analyze --output-root .
TASK3_ANALYSIS_TENSOR_DEVICE=npu python3 -m demo.run_medical_demo analyze --output-root .

auto 会在无 torch_npu 的开发机上使用 CPU tensor 后端；显式 npu 时如果 Ascend NPU/torch_npu 不可用会直接失败，不会静默退回规则后端。小 demo 端到端包含 Python 解析、规则候选生成和 NPU 初始化开销，不作为整体加速声明来源；加速声明以同算法 CPU/NPU benchmark 为准。当前可宣称的是任务一智能体规划 tensor ranker、任务二 KG tensor 算子与任务三图谱相似度 tensor 算子已支持 Ascend NPU；不能宣称 DataMate 官方 Docker 内部处理或三任务全流程端到端都被 NPU 加速。

生成比赛提交证据包：

bash scripts/package_competition_evidence.sh

证据包默认写入 dist/competition_evidence，包含最终验收报告、三任务产物、DataMate/Nexent 集成 trace、CPU benchmark、index.html 离线总览页和可选截图状态；详见 比赛提交证据包说明。

提交前推荐顺序：

bash scripts/prepare_submission.sh \
  --knowledge-base-id <DataMate知识库ID> \
  --cblue-source data/external/cblue \
  --cblue-limit 300 \
  --no-screenshots

该脚本会串联最终验收、CBLUE 证据、证据包生成和 manifest 自检。正式链路不再允许 fixture fallback；最终提交材料以 prepare_submission.sh 之后生成的 dist/competition_evidence 为准。

许可证

本项目采用 MIT License。