opengate-mcp

开放式基于证据的 AI 测试与评估

为基于证据的 AI 提供确定性、以黄金标准为锚点的验证——无需 LLM 评判器。

快速开始 · 架构 · 应用形式 · 示例 · 路线图 · 贡献 · 更新日志

证据胜过似是而非。 OpenGATE 用于验证必须依据源材料为每个回答提供理由的 AI 系统——RAG 流水线、文档问答工具、法律和科学助手。它首先回答一个问题：系统能否根据获得的证据证明自己的回答？

检查是确定性的——没有 LLM 评判器，没有评分模型，也没有六级判定尺度。必须包含所有必需事实，每个数字都必须能追溯到来源；如果上下文无法回答，系统就必须弃答，而不是捏造内容。由于它只依赖纯逻辑，因此可复现、免费，而且速度足够快，可以检查每个回答，或在每次提交时进行门禁检查。

随着 AI 进入高风险领域，评估正变得与传统软件中的自动化测试同样基础。OpenGATE 将依据不足的问题转化为可跟踪的数字，并针对基线检查每次提示词、模型或工作流变更——从而避免可靠性悄然退化。

快速开始（60 秒）

无需 API 密钥——离线测试套件会使用随附的黄金数据集运行确定性评分器：

npx @pharmatools/opengate           # run the offline evaluation suite
npx @pharmatools/opengate init      # scaffold gold cases + HTTP config + a GitHub Action

OpenGATE — 39 case(s), online=false, adapter=refcheckr

  ✓ citation-detection   PASS
      perClaim_exactSetRate      100.0%
      perClaim_jaccardMean       100.0%
      supportedStyle_accuracy    100.0%
  ⊘ grounding            SKIPPED — online scorer (pass --online)

将 opengate.http.json 指向你的端点，并添加 --online --ci，即可对自己的系统进行门禁检查。完整操作指南：入门指南。

一项检查，多种应用形式

同一套确定性的依据验证逻辑可用于技术栈中的各种场景：

架构

评分器不会直接与系统通信，而是通过一个小型适配器与其交互，因此方法可以复用，只有黄金数据集需要更改。在开发循环中，它位于 CI 所在的位置：更改提示词、模型或流水线；回归门禁会将新的评分卡与基线进行比较——得分提升或持平则部署，回归则构建失败。

为什么不用 DeepEval？

两者都用——评估衡量效果，OpenGATE 验证结果。DeepEval 和 OpenAI Evals 这类通用框架会广泛评估 AI 系统，通常由大模型来判断输出。OpenGATE 则验证范围更窄、要求更高的承诺：每个答案都必须有证据作为依据：

• 来源溯源是一等要素——引用的段落是否确实存在于来源中，且与原文完全一致？
• 不使用大模型裁判——分数通过对照人工标注的黄金数据进行确定性检查，因此结果可复现，且可在 CI 中免费运行；判断标准体现在黄金数据中，而不是评分模型中。
• 回归检测是一等要素——每次运行都会与每个适配器各自的基线进行比较；分数下降会导致构建失败。

使用通用框架衡量广泛的质量指标，并搭配 OpenGATE 来把关依据。

核心概念

黄金用例——人工标注的基准用例（datasets/cases/）：源文本、应提取的论点、不应提取的句子，以及带有已知正确判定的参考片段。复制 _template.json 来添加用例；格式说明见 datasets/SCHEMA.md，标注规则见 datasets/LABELING-GUIDE.md。

评分器——每个指标系列对应一个模块（src/scorers/）：

离线评分器无需 API 密钥即可运行，速度足以用于每次提交。在线评分器通过适配器测试实时系统。

评分卡——每次运行都会写入 results/<timestamp>.json，并附上 Git SHA，因此任何结果都可复现、可审计。按模型运行的结果带有 run_model 标签，让结果目录成为一个可衡量的对比（准确率 × 幻觉率 × 延迟 × 成本）。

回归门禁——--baseline 用于保存参考基线；后续运行会打印各指标的变化量（以百分点表示的 ▲/▼），而 --ci 会在任何指标下降时令构建失败。基线按适配器分别保存，因此一个系统的评分卡不会覆盖另一个系统的评分卡。

HTML 报告——添加 --report（或运行 opengate report）即可生成独立仪表板：每个评分器的通过 / 失败状态、与基线相比的变化量，以及所有列出的失败项。单个文件，无需服务器或依赖项。

评估你自己的系统

适配器只有一个文件：两个基础导出项——onlineAvailable()、onlineConfigHint()——以及至少一种完整的能力（例如，grounding → answer()）。评分器会检查 adapter.capabilities，并在跨越边界时正常跳过；加载时会验证适配器，并通过消息列出每个缺少的导出项。

OPENGATE_ADAPTER=./adapters/my-system.mjs npm run eval:online

对于由 REST 支持的系统，有一条无代码路径：内置的通用 HTTP 适配器会从 opengate.http.json 读取端点路径和请求头（支持 ${ENV} 插值，并内置延迟和令牌捕获）。完整契约和最小骨架：ADAPTERS.md。

示例

• 评估由 NIM 驱动的 RAG Agent — 基于 NVIDIA NIM 模型构建 RAG Agent，并使用 OpenGATE 确定性地评估答案的依据，无需 LLM 评判器。包含可运行的 Python notebook（opengate-grounding）和用于 CI 门禁的 Node 适配器。

已在生产环境验证

四款 PharmaTools 产品在 CI 中运行于 OpenGATE 上，涵盖四种不同的能力类型，共用一套评估标准。针对 RefCheckr 的黄金集运行时，OpenGATE：

• 发现了一种影响约 50% 多声明判定的静默解析失败模式，通过强制结构化输出将其消除（→ 0）；
• 通过推动一项有数据衡量的生产模型变更，将段落幻觉率减半（5.8% → 2.4%）——这一决策依据的是数据，而非声誉；
• 在已提交的基线上将声明提取保持在 0.91 F1，召回率为 0.93（多次运行的波动范围为 0.86–0.94——拆分器是一个 LLM），目前未通过自身门禁：大多数运行中有 2 个已知的非声明混入提取结果。这是一个尚未解决的拆分器问题，门禁会如实报告，而不是将其四舍五入掩盖。

npm install --no-save @pharmatools/redacta
node src/runner.mjs --online --adapter ./src/adapters/redacta.mjs

node src/runner.mjs --online --adapter ./src/adapters/patiently.mjs

node src/runner.mjs --online --adapter ./src/adapters/pubcrawl.mjs

完整方法和模型比较：RefCheckr 的评估方式。

项目布局

opengate/
├── src/
│   ├── lib/          metrics + shared grounding core (single source of truth)
│   ├── scorers/      one file per metric family (7 scorers)
│   ├── adapters/     system-under-test boundary (refcheckr.mjs is the reference)
│   └── runner.mjs    CLI: discover cases → score → report → snapshot → gate
├── datasets/         gold-labelled cases (39) + fixtures + schema
├── examples/         worked examples (NVIDIA NIM RAG)
├── mcp/              MCP server (@pharmatools/opengate-mcp)
├── python/           opengate-grounding (PyPI) + DeepEval metric
├── Dockerfile        CPU-only image (pharmatools/opengate)
└── action.yml        GitHub Action

文档

贡献

欢迎贡献，尤其是黄金案例（新领域、引用样式）、适配器（接入你的系统）和评分器（新的指标类别）。请参阅 CONTRIBUTING.md，其中包括支持与治理方面的要求，以及 AI 辅助开发披露；如需讨论重大变更，请提交 issue。1.0 发布前，接口仍可能调整，语义化版本将标示不兼容变更。

引用 OpenGATE

如果你在研究中使用 OpenGATE，请引用它——引用元数据位于 CITATION.cff 中（GitHub 的“引用此仓库”按钮会使用该文件）。

许可证

MIT——因为评估框架不应是黑箱。如果评估结果会影响部署决策，工程师就应该能够检查每个评分器、指标和基准。