DOREMUS音乐知识图谱-MCP服务器
A. 模型上下文协议（MCP） 用于通过基于SPARQL的知识图（默认为DOREMUS）进行代理检索的服务器。服务器暴露了一小部分 本体无关工具 LLM可以调用这些函数来迭代构建有效的SPARQL（实体发现、查询构建、过滤、执行）。
虽然主要使用DOREMUS进行测试(https://data.doremus.org)，此代码库旨在通过更改配置+查询模板来适应任何SPARQL端点。
______________________________________________________________________
目标
1） 基于知识图的代理检索（通过MCP）
提供一个MCP服务器，让LLM：
- 解析实体（例如作曲家、作品），
- 逐步构建SPARQL，
- 稳健地执行查询（超时、重试、安全检查），
- 通过将操作约束到工具/模板来避免模式幻觉。
核心入口点： src.server.main （FastMCP服务器+工具注册）。
2） 模板驱动、本体无关的查询构造
使用可重复使用的 .rq 模板+策略，将用户意图映射到图形模式，并使工具API在本体中保持稳定。
模板引擎： server.template_parser\ 查询状态生成器： server.query_container.QueryContainer
3） 可重复评估+消融
运行评估实验（LangSmith支持）并绘制以下图：
- 精度，
- 成本/延迟权衡，
- 准确性取决于问题的复杂性，
- 错误类型细分，
- 工具配置比较，
- 取样/干运行消融。
评估跑者： evaluators.test_query\ 分析： evaluators.analyze_runs\ 绘图生成： evaluators.create_plots
______________________________________________________________________
项目总体结构
DOREMUS_MCP/
├── src/
│ ├── server/ # MCP server implementation
│ │ ├── config/ # Endpoint + tool + strategy config + templates
│ │ │ ├── templates/ # SPARQL templates (.rq)
│ │ │ ├── server_config.yaml
│ │ │ ├── strategies.yaml
│ │ │ └── tools.yaml
│ │ ├── main.py # FastMCP server + tools (HTTP routes, tool gating)
│ │ ├── tools_internal.py # Tool implementations + query storage
│ │ ├── template_parser.py # Template loading/validation
│ │ ├── query_container.py # QueryContainer state machine + dry-run checks
│ │ ├── graph_schema_explorer.py # Schema exploration helpers
│ │ └── utils.py # SPARQL execution, URI validation, helpers
│ └── rdf_assistant/ # LangChain client/agent (used by evaluators)
│ ├── doremus_assistant.py
│ ├── extended_mcp_client.py
│ ├── prompts.py
│ └── eval/
│ ├── doremus_dataset.py # Loads local .rq dataset files
│ └── split_dataset.py # Computes complexity splits via hop-count heuristic
├── evaluators/ # Evaluation pipeline scripts
│ ├── test_query.py # Main evaluation entry (LangSmith dataset -> runs -> metrics)
│ ├── analyze_runs.py # Extracts traces + metrics into experiments/*.json
│ ├── create_plots.py # Generates plots into data/evaluation/plots/
│ ├── run_tool_study.py # Tool-config sweep (enables/disables tool subsets)
│ ├── run_ablation_study.py # Sampling/dry-run ablation
│ ├── test_gemini_dataset.py # Gemini CLI-based runner (optional)
│ └── export_human_readable.py # Converts analysis JSON to readable .txt
├── eval_dataset/ # Local dataset of .rq files (questions + gold SPARQL + metadata)
├── experiments/ # Output folder for analysis JSON (from analyze_runs.py)
├── data/
│ ├── graph.csv # Graph used by path-finding tooling
│ └── evaluation/plots/ # Generated figures (see "Results" section)
├── docs/ # Documentation & paper PDF
├── tests/ # Unit tests
├── Dockerfile / docker-compose.yml
└── pyproject.toml______________________________________________________________________
它是如何工作的（高级）
MCP服务器+工具门控
工具已在中注册 src.server.main 并且可以通过以下方式启用/禁用 MCP_ENABLED_TOOLS （CSV）。这用于工具研究（消融）。
查询构建是有状态的
每次运行都会操纵存储在中的服务器端查询状态 server.tools_internal.QUERY_STORAGE 使用 server.query_container.QueryContainer.
安全：干运行检查（可选）
在完全执行之前，可以使用以下命令检查查询的健全性 server.query_container.QueryContainer.dry_run_test 可通过以下方式禁用 ENABLE_DRY_RUN=false.
______________________________________________________________________
评估管道
典型的流程是：
- （可选）计算/刷新问题分割 （通过跳数计算复杂性）：\
src.rdf_assistant.eval.split_dataset
- 将数据集上传到LangSmith （删除/重新创建）：\
- 运行评估 （代理调用MCP工具；计算指标）：\
- 分析痕迹 转换为紧凑的JSON用于绘图：\
- 生成绘图 进入
data/evaluation/plots/:\
评估员文件： 评估者/README.md
______________________________________________________________________
结果（来自 data/evaluation/plots/)
该存储库包括一个绘图管道，将实验总结成图表。以下图片是从以下位置加载的 data/evaluation/plots/ 并旨在作为实验的“论文式”总结。
准确性与一致性
该图应理解为 框架约束随机性的证据并非所有模型都“推理得同样好”。
- 本文定义了 一致性分数 作为重复运行（三个独立实验；每个问题三次运行）的剪切反向标准偏差：\
一致性=剪辑（1.0−2.0×σ_问题，0.0，1.0）
- 报告的范围(~82%–93%，基线>80%）被解释为验证 查询容器 方法：语法约束+工具端的“模拟运行”从LLM中卸载结构有效性。
- 因此，当准确性下降时，论文将其主要归因于 复杂问题的推理局限性，而不是随机的语法/工具幻觉。
______________________________________________________________________
准确性与代币成本
此图说明了 代理检索的计算权衡 （准确性不是“免费的”）。
- 高推理多面手模型（示例： gpt-4.1)倾向于更多 工具高效，使用较少的工具调用来隔离正确的模式路径。
- “思维模式”（示例： gpt-5.2)明确贸易 提高精度的令牌效率，增加推理时间计算（从而增加成本/延迟），与“推理量表与推理时间计算”相一致。
- 专业编码器模型可以通过更多地依赖于 迭代反馈回路，但可能会招致 令牌开销.
______________________________________________________________________
准确性与延迟（平均工具调用）
本文将“延迟”视为 迭代/交互代理 而不是挂钟时间。
- 核心要点是 迭代权衡：一些模型通过较少的调用快速收敛，而另一些模型需要更多的迭代（和更多的令牌）才能达到类似的精度。
- 较小敏捷模型中的一个显著行为（例如： 小册子3:14b)是 并行工具调用（“批处理调用”），这通过一次测试多个模式假设来减少顺序探索时间。
- 相比之下，其他架构可能会显示出高资源消耗，因为它们强烈依赖于反馈回路来收敛。
______________________________________________________________________
问题复杂度的准确性
这张热图被用来论证 推理深度决定了硬度，特别是对于聚合和多跳遍历。
- 表现最佳的模型定义了 “可解释性限制” 当前的代理框架（论文提到~85%在易)，这意味着剩余的错误更多地反映了框架的局限性（例如，缺少工具、工具定义模糊、反馈粒度不足），而不是幻觉。
- 该论文强调了 骤降 在硬/非常硬的地层中，激发了对 高推理时间计算 用于分析（聚合）和生成（多跳）查询。
- 在Hard/Vvery Hard中，参数计数与最终精度呈正相关，但专业化很重要：编码器模型可以看起来更多 地层均匀 因为一些“硬”查询在语法上类似于模式（例如GROUP BY），但规模仍然可以提高工具使用精度（更大的编码器>更小的编码器）。
- 据报道，“思维模式”有助于 可变冲突 和 聚合范围，其中标准模型经常将路径或组混淆为错误的实体。
Accuracy Heatmap by Complexity
______________________________________________________________________
按型号划分的故障类型
堆叠的钢筋被框成 语义故障分类，因为语法错误在很大程度上是通过基于执行的验证（“模拟运行”）消除的。
- II型（刀具漂移） 据报道，这是主要的错误模式：模型通常理解意图（低III型）和词汇（低I型），但很难选择最有效/最合适的工具策略。
- I型（图式幻觉） 对于具有推理能力的模型（例如：gpt-5.2、qwen-480b）来说，这是最小的，支持工具定义+约束减少模式发明的说法。
- 第三类（语义漂移） 被描述为跨架构的显著低；当它发生时，它通常是“格式分歧”（例如，URI与标签），而不是误解用户的问题。
- 报纸呼吁 小册子3:14b 由于权衡，I型异常值较高：它通过积极主动的方式弥补了有限的推理 平行勘探，但失去了语义精度（更多的幻觉参数/假设）。
______________________________________________________________________
刀具配置研究（增量刀具贡献）
此图明确用于验证 工具不仅仅是方便，它是必要的 对于DOREMUS级别的本体论。
- 基线“高级工具被拒绝”被视为不受约束的证据 探索性生成工作流程 （本体探索+一次性查询生成）不足；DOREMUS需要一种动态的、多步骤的代理方法。
- 最大的收益来自 构建查询（BQ） 和 添加滤镜（AF）:
- 模板通过编码基本的RDF模式来减少幻觉。 - BQ的内部“轻量级分类器”被认为可以路由到正确的模板策略（例如，艺术家vs表情），提供稳定的骨架。
- 添加 按数量筛选（FBQ） 通过抽象在直接生成中通常会导致语法错误的时间/数字模式（日期范围、ISO-8601持续时间），产生了另一个巨大的收益。
- 添加组件约束（ACC） 被描述为结构关键：它通过递归/寻路逻辑实现“邻域检索”策略，让代理修剪模式并选择相关子图（例如插装）。
- 高级“写访问”工具引入了 推理阈值:
- 对于高推理模型（例如：gpt-4.1）， Groupby拥有（GH） 和 添加三联件（AT） 帮助处理边缘情况并添加~+5% 最终精度。 - 对于较低的推理架构（例如：qwen3编码器30b），启用这些工具可以 降低性能 因为代理的增加会导致误用和语义错误。
______________________________________________________________________
重现情节
假设MCP服务器正在运行并且配置了LangSmith：
# 1) Run evaluation experiments (writes runs to LangSmith)
poetry run python evaluators/test_query.py
# 2) Export a compact JSON into ./experiments/
poetry run python evaluators/analyze_runs.py ""
# 3) Generate plots into data/evaluation/plots/
poetry run python evaluators/create_plots.py工具研究扫描：
取样/干运行消融：
干运行行为： server.query_container.QueryContainer.dry_run_test
______________________________________________________________________
快速开始
使用Docker
docker-compose up --build服务器URL（默认）：
http://localhost:8000/mcp
地方发展（诗歌）
poetry install
poetry run python -m src.server.main评估者/客户依赖关系：
poetry install --with eval
poetry run python evaluators/test_query.py______________________________________________________________________
许可证/支持
此MCP服务器实现按原样提供，用于访问公开可用的DOREMUS知识图。
关于以下问题：
- 此MCP服务器：在存储库中打开问题
- DOREMUS数据/本体：联系DOREMUS项目
- SPARQL端点: https://data.doremus.org/sparql/