内容
<div align="center">
# 开放门户
### 开放式 grounded AI 测试与评估
**不要仅信任 AI。验证它。基于证据的 AI 验证 —— 没有 LLM 裁判。**
[](https://github.com/nickjlamb/opengate/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@pharmatools/opengate)
[](https://pypi.org/project/opengate-grounding/)
[](https://hub.docker.com/r/pharmatools/opengate)
[](https://nodejs.org)
[](LICENSE)
[](CONTRIBUTING.md)
[快速开始](#快速开始-60秒) · [架构](#架构) · [多面评估](#一键评估-多面) · [示例](examples/) · [路线图](docs/ROADMAP.md) · [贡献](CONTRIBUTING.md) · [更新日志](CHANGELOG.md)
</div>
---
**证据优于合理性。** 开放门户验证 AI 系统，确保其根据提供的证据为每个答案提供依据 —— RAG 管道、文档-QA 工具、法律和科学助手。它回答一个关键问题：**系统能否从给定的证据中证明其答案？**
检查是**确定性**的 —— 没有 LLM 作为裁判，没有评分模型，也没有六点评判标准。所需的事实必须存在，每个数字必须追溯到源头，当上下文无法回答时，系统必须放弃而不是捏造。因为它纯粹是逻辑，所以它是可重复的、免费的，并且足够快，可以在每次回答或每次提交时运行。
> 随着 AI 进入高风险领域，评估变得与传统软件中的自动化测试一样重要。开放门户将基础故障转化为可跟踪的数字，并针对基线检查每个提示、模型或工作流更改，以确保可靠性不会悄悄下降。
## 快速开始（60 秒）
无需 API 密钥 —— 离线套件运行确定性评分器与捆绑的黄金数据集：
```bash
npx @pharmatools/opengate # 运行离线评估套件
npx @pharmatools/opengate init # 搭建黄金案例 + HTTP 配置 + GitHub Actions
```
```
开放门户 — 39 个案例，线上=false，适配器=refcheckr
✓ 引用检测 PASS
perClaim_exactSetRate 100.0%
perClaim_jaccardMean 100.0%
supportedStyle_accuracy 100.0%
⊘ 基础验证 跳过 — 线上评分器（传递 --online）
```
将 `opengate.http.json` 指向您的端点，并添加 `--online --ci` 以验证您自己的系统。完整教程： **[入门指南](docs/GETTING-STARTED.md)**。
## 一键评估，多面
相同的确定性基础验证逻辑适用于您的堆栈：
| 表面 | 安装 | 用途 |
|---|---|---|
| **CLI + 框架** | `npx @pharmatools/opengate` | 完整评估套件、适配器、回归门控 |
| **GitHub Actions** | `uses: nickjlamb/opengate@v0` | 任意仓库中的一键 CI 门控 |
| **Python 包** | `pip install opengate-grounding` | `check_grounding()`、pytest 门控、 [DeepEval](https://deepeval.com) 指标 |
| **MCP 服务器** | `npx @pharmatools/opengate-mcp` | 验证其自身答案的代理 |
| **Docker 镜像** | `docker run pharmatools/opengate` | CPU 独占、容器化管道 |
## 架构
```mermaid
flowchart TB
subgraph CORE["开放门户核心"]
direction TB
G["黄金数据集 — 手动标记案例"]
S["评分器 — 每个指标家族一个"]
R["记分卡 — 版本化 JSON + HTML"]
C["回归门控 — 基线差异，CI"]
G --> S --> R
S --> C
end
CORE -->|"适配器（一个文件）"| SUT
subgraph SUT["被测试系统"]
direction TB
A["RefCheckr — QA / 引用"]
B["Redacta — 删减"]
D["Patiently AI — 简化"]
E["PubCrawl — 检索"]
Y["您的系统 — 编写一个适配器"]
end
```
评分器从不直接与系统通信 —— 它们通过一个小型**适配器**与系统交互，因此方法论得以传承，而只有黄金数据集发生变化。在开发循环中，它位于哪里：
```mermaid
flowchart LR
CH["更改提示、模型或管道"] --> RUN["运行开放门户"]
RUN --> Q{"指标 vs 基线？"}
Q -->|"改进 / 保持"| DEP["部署"]
Q -->|"退化"| INV["构建失败 — 调查"]
```
## 为什么不使用 DeepEval？
两者结合使用 — **评估衡量，开放门户验证**。像 DeepEval 和 OpenAI Evals 这样的通用框架广泛评估 AI 系统，通常使用 LLM 来评估输出。开放门户验证一个更狭窄、更重要的承诺：每个答案都**基于证据**：
- **出处是首要的** — 引用的段落是否实际存在于源中？
- **没有 LLM 裁判** — 分数是确定性检查与手动标记的黄金数据集，因此可重复且免费运行在 CI 中；您的判断存在于黄金数据集中，而不是评分模型中。
- **回归检测是首要的** — 每次运行都与每个适配器的基线进行差异比较；如果分数下降，则构建失败。
将通用框架用于广泛的质量指标与开放门户结合使用，以验证基础。
## 核心概念
**黄金案例** — 手动标记的基准案例（`datasets/cases/`）：源文本、应提取的声明、不应提取的句子，以及具有已知正确判决的参考片段。复制 `_template.json` 以添加一个；格式参见 [`datasets/SCHEMA.md`](datasets/SCHEMA.md)，标记规则参见 [`datasets/LABELING-GUIDE.md`](datasets/LABELING-GUIDE.md)。
**评分器** — 每个指标家族一个模块（`src/scorers/`）：
| 评分器 | 模式 | 衡量指标 |
|---|---|---|
| `citation-detection` | 离线 | 每个声明的引用集精确匹配和 Jaccard 指数；支持样式准确性 |
| `claim-extraction` | 在线 | 精确度 / 召回率 / F1 与黄金数据集；非声明泄漏； **保真度**（声明是否逐字来自源头） |
| `verdict-accuracy` | 在线 | 六点量表的精确度和邻接准确性； **幻觉率**；一致性；延迟和令牌成本 |
| `redaction` | 在线 | 黄金标识符召回率与 **泄漏作为命名失败**；过度删减；已知间隙跟踪 |
| `simplification` | 在线 | 改写的忠实度： **锚点召回率**（关键事实存活率）， **捏造数字**，长度门控 |
| `retrieval` | 在线 | 检索记录与权威的忠实度： **锚点字段** + 结构不变性 |
| `grounding` | 在线 | 通用 RAG： **答案锚点召回率**， **捏造** 与上下文，和 **放弃**。一键路径 |
离线评分器在无 API 密钥的情况下运行 — 足够快以适应每次提交。线上评分器通过适配器与实时系统交互。
**记分卡** — 每次运行写入 `results/<timestamp>.json`，带有 git SHA，因此任何结果都是可重复和可审计的。按模型运行的记录带有 `run_model` 标签，将结果目录变成一个有测量值的比较（准确性 × 幻觉 × 延迟 × 成本）。
**回归门控** — `--baseline` 保存一个参考；后续运行打印每个指标的差异（▲/▼ 百分比）并且 `--ci` 在任何下降时都会失败基线。基线是**每个适配器**，因此一个系统的记分卡不会覆盖另一个系统的记分卡。
**HTML 报告** — 添加 `--report`（或 `opengate report`）以获取一个自包含的仪表板：每个评分器的通过/失败、与基线的差异、每个命名失败。 一个文件，无需服务器，无需依赖。
## 评估您自己的系统
适配器是一个文件：两个基本导出 — `onlineAvailable()`、`onlineConfigHint()` — 加上至少一个完整的**功能**（例如 `grounding` → `answer()`）。评分器检查 `adapter.capabilities` 并在边界处干净地跳过；适配器在加载时通过消息验证每个缺失的导出。
```bash
OPENGATE_ADAPTER=./adapters/my-system.mjs npm run eval:online
```
对于基于 REST 的系统，有一个**无需编码的路径**：捆绑的通用 HTTP 适配器从 `opengate.http.json` 读取端点路径和头部（`${ENV}` 插值，内置延迟/令牌捕获）。完整合同和最小骨架： **[ADAPTERS.md](ADAPTERS.md)**。
## 示例
- [**评估 NIM 驱动的 RAG 代理**](examples/nim-rag) — 在 [NVIDIA NIM](https://build.nvidia.com) 模型上构建 RAG 代理，并使用开放门户确定性地验证其答案的依据，无需 LLM 裁判。包括可运行的 Python 笔记本（`opengate-grounding`）和用于 CI 门控的 Node 适配器。
## 已在生产中证明
四个 PharmaTools 产品在 CI 中运行开放门户 —— 四种不同的功能形状，一个评估标准。对 RefCheckr 的黄金数据集进行测试，开放门户：
- 发现了一个影响约 50% 的多声明判决的**静默解析失败模式**，通过强制结构化输出消除（→ 0）；
- **减少了幻觉率**（5.8% → 2.4%）通过驱动一个有测量的生产模型更改 —— 根据数字而不是声誉做出的决定；
- 在 **~0.95 F1** 下保持声明提取，具有近乎完全的召回率。
<details>
<summary><b>Redacta</b> — 删减功能（证明方法不是 QA 形状）</summary>
[Redacta](https://www.pharmatools.ai/redacta) 封装了 `@pharmatools/redacta` 引擎，与合成的英国临床笔记黄金标签标识符进行对比。 在其首次运行时，评估发现了引擎的两个真实错误（关系短语吞噬嵌套名称；撇号姓氏丢失）—— 两者都被修复和确认（`knownGap_closed: 2`），然后提升到黄金。 当前记分卡： **25 个黄金标识符的 100% 召回率，0 个泄漏，0 个开放间隙**。
```bash
npm install --no-save @pharmatools/redacta
node src/runner.mjs --online --adapter ./src/adapters/redacta.mjs
```
</details>
<details>
<summary><b>Patiently AI</b> — 简化功能（改写的忠实度）</summary>
[Patiently AI](https://www.pharmatools.ai/patiently-ai) 锻炼了设计为改写的文本的忠实度评分。 评估发现简化器 **丢弃了安全关键细节** — 一种抗生素剂量从出院总结中消失了（锚点召回率 86%）。 保存在下一个运行到 **100% 锚点召回率，0 个丢弃的事实，0 个捏造的数字**。
```bash
node src/runner.mjs --online --adapter ./src/adapters/patiently.mjs
```
</details>
<details>
<summary><b>PubCrawl</b> — 检索功能（一切的基础）</summary>
[PubCrawl](https://www.pharmatools.ai/pubcrawl) **没有模型** — 它在手动验证的锚点和结构不变性方面锻炼检索忠实度，捕获解析器回归（崩溃的作者数组， `[object Object]` 泄漏），这些将会毒害后续的引用。 开放门户评估一个非 AI 系统的事实是重点：基于证据的 AI 的可靠性与下面的检索一样。
```bash
node src/runner.mjs --online --adapter ./src/adapters/pubcrawl.mjs
```
</details>
完整的 方法论 和 模型比较： [RefCheckr 如何评估](https://www.pharmatools.ai/refcheckr-eval)。
## 项目布局
```
opengate/
├── src/
│ ├── lib/ 指标 + 共享基础验证核心（单一真相源）
│ ├── scorers/ 每个指标家族一个文件（7 个评分器）
│ ├── adapters/ 被测试系统边界（refcheckr.mjs 是参考）
│ └── runner.mjs CLI：发现案例 → 评分 → 报告 → 快照 → 门控
├── datasets/ 黄金标签案例（39）+ 固定数据集 + 模式
├── examples/ 已完成的示例（NVIDIA NIM RAG）
├── mcp/ MCP 服务器（@pharmatools/opengate-mcp）
├── python/ opengate-grounding（PyPI）+ DeepEval 指标
├── Dockerfile CPU 独占镜像（pharmatools/opengate）
└── action.yml GitHub Actions
```
## 文档
| 文档 | 内容 |
|---|---|
| [入门指南](docs/GETTING-STARTED.md) | 零到 CI 门控，用于通用 RAG 系统 |
| [ADAPTERS.md](ADAPTERS.md) | 适配器合约 + 最小骨架 |
| [datasets/SCHEMA.md](datasets/SCHEMA.md) | 黄金案例格式 |
| [路线图](docs/ROADMAP.md) | 下一步是什么，以及通往 1.0 的道路 |
| [贡献](CONTRIBUTING.md) | 开发设置、添加案例/适配器/评分器、PR 流 |
| [更新日志](CHANGELOG.md) | 发布历史 |
## 贡献
欢迎贡献 —— 尤其是 **黄金案例**（新领域、引用样式）、**适配器**（连接您的系统）和 **评分器**（新的指标家族）。参见 **[CONTRIBUTING.md](CONTRIBUTING.md)** — 包括其支持和治理期望以及 AI 辅助开发披露；开启一个问题来讨论大型更改。 接口可能会在 1.0 之前发生变化，并且 semver 将发出破坏性更改的信号。
## 引用开放门户
如果您在研究中使用开放门户，请引用它 —— 引用元数据位于 [`CITATION.cff`](CITATION.cff)（GitHub 的“引用此仓库”按钮使用它）。
## 许可证
[MIT](LICENSE) — 因为评估框架不应该是黑盒。 如果评估影响部署决策，工程师应该能够检查每个评分器、指标和基准。
<div align="center">
<sub>由 <a href="https://www.pharmatools.ai">PharmaTools.AI</a> 构建 · <a href="https://www.pharmatools.ai/opengate">开放门户概述</a></sub>
</div>
