# grounded-rag

**Repository Path**: miniclaw27/grounded-rag

## Basic Information

- **Project Name**: grounded-rag
- **Description**: GroundedRAG——RAG的「校验层」。像数据库有ACID保证，RAG也需要声明级校验门：无证据自动拦截，有证据原样输出，让LLM回答有据可依、无据可拒。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-03
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GroundedRAG

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://gitee.com/miniclaw27/grounded-rag)
[![Tests](https://img.shields.io/badge/tests-247%20passed-brightgreen.svg)](tests/)
[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)](docs/metrics.md)
[![CI](https://github.com/StevenTsai/grounded-rag/actions/workflows/ci.yml/badge.svg)](https://github.com/StevenTsai/grounded-rag/actions)

**轻量开源 RAG 框架** —— 以「声明级校验门（claim-level verifier）」可复现地减少无证据输出，
让 LLM 回答做到「**有据可依，无据可拒**」。

GroundedRAG 面向医疗等高风险领域的检索增强问答设计：回答不是"生成即交付"，而是先拆成
原子主张（`AnswerClaim`），每条绑定可溯源证据（`EvidenceId`）或命中的权威规则
（`RuleDecision`），逐条经过确定性校验门后，才决定**原样输出 / 标注降级 / 拒绝回答**。

> ⚠️ 随仓库分发的 `examples/` 数据（`seed_*`、eval sets）为**自研合成示例**；真实场景评测集（`real_seed_*`）整理自公开临床指南/文献，因第三方版权**不入库、不随仓库分发**（可应评审要求提供）。以上数据均**不构成真实诊疗建议**。
> 请勿用于任何真实医疗决策。

## 为什么是"声明级"

普通 RAG 用"整段相关"打分，模型可以编造一段开头像检索结果的话，段内却混入幻觉。GroundedRAG
把回答降维到 **一条主张 = 一条可核查断言**，校验门逐条判定：

```
AnswerClaim[]  ──引用──▶  EvidenceId[]  /  RuleDecision[]
      │
      ▼  （纯逻辑，零 LLM 依赖）
 引用完整性 → 表面要素一致性 → 规则冲突裁定 → 证据充分性
      │
      ▼
  PASS（原样输出）/ ANNOTATE（附标注）/ REFUSE（拒答/删除）
```

确定性档只做**表面要素一致性**（实体/数值/单位是否真实出现在证据原文），不声称"语义真实支持"；
含否定/比较/因果等关系语义的主张在语义档关闭时统一拒答或标注 —— 详见 [docs/metrics.md](docs/metrics.md)
（指标口径）与各模块 docstring。

## 快速开始

```bash
pip install -e ".[demo]"     # 或最小安装 pip install -e .
```

**方式一：命令行（最简单）**

```bash
groundedrag ask "EGFR突变肺癌一线推荐什么方案？"
groundedrag init --dir my_domain/               # 生成 docs + rules 模板
```

**方式二：Python API**

```python
from groundedrag import Pipeline

pipe = Pipeline.build_from_json(
    "examples/seed_docs.jsonl", "examples/seed_rules.json"
)
result = pipe.ask("EGFR 突变的晚期肺癌一线推荐什么方案？")
print(result.answer_text)
# - 肺癌 一线 EGFR 推荐方案：奥希替尼
```

**方式三：可视化 Demo**

```bash
python examples/demo.py      # CLI 端到端 demo
python examples/app.py       # Gradio 可视化 demo
```

无 API Key 也能跑通全链路：规则命中走"规则直出"（有据可答），未命中则结构化拒答。

启用真实 LLM（OpenAI 兼容端点，如 DeepSeek / 小米 MiMo / 豆包）：

```python
from groundedrag.llm import FailoverLLM, OpenAICompatibleLLM

llm = FailoverLLM([OpenAICompatibleLLM(base_url="https://api.deepseek.com/v1",
                                        api_key="sk-...", model="deepseek-chat")])
pipe = Pipeline.build_from_json("examples/seed_docs.jsonl",
                                "examples/seed_rules.json", llm=llm)
```

也可通过 `.env` 文件配置（支持多 provider 自动 failover）：

```bash
cp .env.example .env
# 编辑 .env —— 填入 LLM_API_KEY 或 provider 专属 key（DEEPSEEK_API_KEY 等）
```

## 集成方式

按需选择三种接入深度，完整指南见 [docs/integration.md](docs/integration.md)：

1. **整条流水线** —— `Pipeline.build_from_json("docs.jsonl", "rules.json").ask(...)`
2. **只挂校验门**（已有 RAG 推荐）—— 校验你自己的检索与生成结果：
   ```python
   from groundedrag.guardrail import EvidenceRegistry, parse_claims, Verifier
   report = Verifier().verify(claims, EvidenceRegistry(evidences))
   ```
   可运行示例：[`examples/integrate_verifier.py`](examples/integrate_verifier.py)
3. **单组件复用** —— `Retriever` / `GuidelineEngine` / `FailoverLLM`

依赖引用（PyPI 尚未发布，请锁 tag、勿引用分支）：
```bash
pip install "groundedrag @ git+https://gitee.com/miniclaw27/grounded-rag.git@v1.0.0"
```

## 评测

### Verify 模式（确定性校验门，无需 LLM）

```bash
python -m groundedrag.eval                  # 读 examples/ 默认三文件
python -m groundedrag.eval --json           # 只输出 JSON 摘要
```

内置可重复评测集 `examples/eval_set.jsonl`（19 组 24 条，含正例、数值幻觉、关系型反例、
证据侧否定翻转、类型自报绕过等），输出：

| 指标 | 口径（README / docs 完整说明） |
|------|------|
| **引用完整性率** | 期望通过的主张中，确实带上了完整可解析引用锚点的占比 |
| **表面一致率** | 期望通过的主张中，最终状态为 pass 的占比（好主张没有被误拒） |
| **拒答正确率** | 期望拒答的主张中，校验门确实给出 refuse 的占比（**防幻觉关键指标**） |

内置评测集期望分布：**24 条主张 = 10 通过 + 12 拒答 + 2 标注**。当前实测三项指标均为 1.0，
即 12 条幻觉高危主张全部拦截、10 条好主张零误伤、2 条标注零误判。

| 对照（同一批幻觉高危题） | 裸 prompt RAG | GroundedRAG |
|------|------|------|
| 拒答正确率（幻觉拦截） | 随模型不可复现（缺据数值 8 采样 3 次直出，见[实录](docs/control_experiment_live.md)） | **1.0**（12/12 全部拦截） |
| 误拒（好主张被拦） | —（无拒答概念） | 0（10/10 通过） |
| 引用锚点 / 可溯源 | 无 | 每条主张 `[证据n]` / `[规则n]` + `EvidenceId` |

> 数值由 `python -m groundedrag.eval --json` 实测生成，随评测集演化同步更新。
> 完整对照方法论、典型案例与诚实边界见 [docs/comparison.md](docs/comparison.md)。

### E2E 端到端模式（完整 RAG 流程 + LLM）

```bash
cp .env.example .env   # 配置 API Key
python -m groundedrag.eval --e2e
```

端到端评测：检索 → LLM 生成 → 声明解析 → 校验门验证。支持多 provider 自动 failover
（xiaomi / deepseek / doubao）。详见 [src/groundedrag/eval/README.md](src/groundedrag/eval/README.md)。

## 架构

![GroundedRAG 三层架构图](docs/architecture.svg)

```
pipeline.py 编排：检索 → 规则匹配 → 受约束生成 → 声明解析 → 校验门 → 降级/拒答
   retriever/            guardrail/ ★              llm/
  BM25 检索             规则引擎 RuleDecision      策略基类 + 多模型降级
  实体增强              证据溯源 EvidenceId       OpenAI 兼容客户端
  查询扩展              声明解析 AnswerClaim      模板回退（无据拒答文案）
  (词典可注入)           ★声明级校验门 verifier
```

- `retriever/`：BM25（jieba 分词；缺失时回退 **CJK char-bigram**，绝不回退 `split()`）+
  实体增强 + 查询扩展，领域同义词词典可注入（业务方可闭源自己的词典）。
- `guardrail/`（★ 核心差异化）：纯 Python 规则引擎（无 ORM，可替换业务侧数据库 Provider）、
  EvidenceId 溯源、AnswerClaim 解析、verifier 校验门（引用完整性 / 表面一致 / 冲突裁定 / 充分性）。
- `llm/`：`LLMService` 策略基类 + OpenAI 兼容原生 HTTP 客户端（零 SDK）+ 模板回退 + 主备降级。
- `eval/`：内置评测集跑分（verify + e2e 两种模式），支持 `.env` 多 provider 配置。
- `pipeline.py`：编排流水线（`Pipeline.build_from_json(...).ask(...)`）。
- `cli.py`：命令行工具（`groundedrag ask / init`）。

## 目录

```
grounded-rag/
├── src/groundedrag/
│   ├── retriever/      # bm25.py + retriever.py
│   ├── guardrail/      # models/engine/provider/evidence/claims/verifier ★
│   ├── llm/            # base/openai_compat/template/failover
│   ├── eval/           # 评测（verify + e2e 两种模式）
│   ├── cli.py          # 命令行工具（groundedrag ask / init）
│   └── pipeline.py     # 可信问答编排
├── examples/           # 种子数据、评测集、demo.py、app.py
├── tests/              # pytest 单测
├── tools/leak_scan.py  # 开源自检工具
├── docs/               # 指标口径 / 对照实验 / 架构设计 / 领域适配指南
└── .env.example        # LLM provider 配置模板
```

## Roadmap

### v1.1（2026 Q4）— 金融/法律领域适配

- [ ] 金融监管规则库接入 + 真实场景评测
- [ ] 法律法规库接入 + 法条引用溯源
- [ ] 领域无关的规则 DSL 设计

### v1.2（2027 Q1）— 企业版

- [ ] 私有规则库托管 + 审计日志
- [ ] 多租户支持
- [ ] SSO 集成

### v1.3（2027 Q2）— 语义增强层（可选）

- [ ] 在确定性校验之上，可选接入 NLI 模型处理关系型主张（否定/比较/因果）
- [ ] NLI 结果仅作参考，不替代确定性校验的最终判定
- [ ] 表面一致率 → 语义支持率指标升级

### v2.0（2027 Q3）— 多领域插件系统

- [ ] 一键切换医疗/金融/法律规则集 + 词典 + 评测集
- [ ] 社区贡献的领域规则库生态
- [ ] 领域无关的规则 DSL

### 长期愿景

成为高风险垂直领域的「**可信 RAG 事实标准**」—— 让 LLM 在医疗/金融/法律等需要可溯源、
可审计的场景下做到「**有据可依，无据可拒**」；沉淀一套"约束生成 + 声明级校验"的工程范式，
推动 RAG 从"检索拼接"向"可信交付"演进。

我们相信：**在高风险场景下，一个诚实拒答的 AI 比一个流畅编造的 AI 更有价值。**

## 参考应用

GroundedRAG 由医疗数据平台 **壹鹿康行** 的生产实践演化而来（47,000+ 条医疗数据 + CSCO 指南规则），
壹鹿康行数据平台网址： https://onco.ylkang.cn
本框架将校验门机制独立开源，附合成示例数据（`examples/`）；真实评测集整理自公开指南、因第三方版权不入库，供任何垂直领域复用。

## 领域适配

GroundedRAG 的校验门是领域无关的——只需准备**证据文档**和**规则库**即可适配新领域：

```bash
groundedrag init --dir my_domain/               # 生成模板
# 编辑 my_domain/my_seed_docs.jsonl             # 填入你的文档
# 编辑 my_domain/my_seed_rules.json             # 填入你的规则
groundedrag ask "你的问题" --docs my_domain/my_seed_docs.jsonl --rules my_domain/my_seed_rules.json
```

完整指南见 [docs/domain_guide.md](docs/domain_guide.md)（含金融/法律示例）。

## 合规与第三方依赖

- 核心运行时仅依赖 **jieba**（MIT）；Gradio 仅存在于 `demo` extra。
- 第三方许可证清单见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
- 贡献指南见 [CONTRIBUTING.md](CONTRIBUTING.md)（含 7 点合规清单 + 红线表）。

## 社区

- **GitHub 镜像**: https://github.com/StevenTsai/grounded-rag
- **Gitee 主仓库**: https://gitee.com/miniclaw27/grounded-rag
- **反馈与讨论**: [GitHub Issues](https://github.com/StevenTsai/grounded-rag/issues) | [Gitee Issues](https://gitee.com/miniclaw27/grounded-rag/issues)
- **技术博客**: 核心设计决策系列 [docs/blog.md](docs/blog.md)
- **贡献者**: 见 [CONTRIBUTING.md](CONTRIBUTING.md)

欢迎贡献代码、规则库、评测用例或新领域适配！特别欢迎：
- 金融/法律领域的规则引擎适配
- 多语言分词器支持（英文/日文/韩文）
- 语义档 NLI 模型集成
- 企业级部署案例

## 引用

如在研究或产品中使用 GroundedRAG，请通过 [`CITATION.cff`](CITATION.cff) 引用。

## License

MIT © 2026 GroundedRAG Contributors。见 [LICENSE](LICENSE)。

**[English Documentation](README.md)**