# https://github.com/amazon-science/RAGChecker 项目说明书

生成时间：2026-07-08 05:33:42 UTC

## 目录

- [框架概览与快速入门](#page-1)
- [指标体系、元评估与声明级推理](#page-2)
- [RAG 基线流水线与数据合成](#page-3)
- [集成、扩展与已知问题排查](#page-4)

<a id='page-1'></a>

## 框架概览与快速入门

### 相关页面

相关主题：[指标体系、元评估与声明级推理](#page-2), [集成、扩展与已知问题排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/amazon-science/RAGChecker/blob/main/README.md)
- [ragchecker/__init__.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/__init__.py)
- [ragchecker/cli.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/cli.py)
- [ragchecker/evaluator.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/evaluator.py)
- [examples/checking_inputs.json](https://github.com/amazon-science/RAGChecker/blob/main/examples/checking_inputs.json)
- [tutorial/ragchecker_tutorial_zh.md](https://github.com/amazon-science/RAGChecker/blob/main/tutorial/ragchecker_tutorial_zh.md)
- [requirements.txt](https://github.com/amazon-science/RAGChecker/blob/main/requirements.txt)
</details>

# 框架概览与快速入门

## 框架定位与核心能力

RAGChecker 是由 Amazon Science 开源的 **RAG（Retrieval-Augmented Generation）系统细粒度评估框架**，它围绕"检索-生成"流水线的关键质量维度，提供了一套基于声明（claim-level）的诊断指标。框架的目标不是给出单一的整体分数，而是拆解出可解释的子指标，帮助开发者定位 RAG 管线中检索阶段与生成阶段的薄弱环节。

从顶层抽象来看，RAGChecker 主要回答四类问题：

- 检索器是否召回了回答问题所需的全部证据（recall 维度）。
- 生成器是否仅使用了被支持的事实进行作答（faithfulness 维度）。
- 检索到的上下文是否足够精简、无噪声（context precision 维度）。
- 整体回答在事实层与人类参考答案之间的一致性如何（overall precision/recall/F1）。

资料来源：[README.md:1-40]()

下图为评估流程的核心数据流：

```mermaid
flowchart LR
    A[RAGResults 输入] --> B[提取参考答案 claims]
    A --> C[提取生成答案 claims]
    A --> D[提取检索上下文 chunks]
    B --> E[claim-level 比对]
    C --> E
    D --> F[context 级别评估]
    E --> G[Overall Metrics]
    F --> G
    G --> H[JSON / CLI 输出]
```

## 安装与环境要求

RAGChecker 通过 PyPI 分发，并依赖 `spaCy` 的英文模型以及 RefChecker 系列的细粒度检查器。社区反馈显示 **Python 3.12 是当前最稳定的运行环境**，Python 3.13 在 Windows 上会出现编译失败（参考资料来源：[README.md:42-60]()；社区 issue #32）。

最小化安装步骤如下：

```bash
pip install ragchecker
python -m spacy download en_core_web_sm
```

模型调用层使用 [litellm](https://github.com/BerriAI/litellm) 进行统一封装，因此只要 litellm 支持的模型（包括 OpenAI、Azure OpenAI、Amazon Bedrock 等）都可以通过指定模型名直接使用。资料来源：[README.md:60-90]()

需要特别注意的环境陷阱：

- `transformers >= 4.50` 已移除 `AdamW` 的旧路径，导致 RAGChecker 报错，目前建议固定 `transformers<=4.49`（社区 issue #34）。
- `dataclasses-json` 的版本上界会与 Flytekit 冲突，部署到 Flyte 平台时需要手工放宽约束（社区 issue #28）。
- 在 Docker `python:3.12-slim` 镜像中，如果只执行 `pip install ragchecker` 而不下载 spaCy 模型，会在导入 `RAGResults` 时触发 `ModuleNotFoundError: No module named 'refchecker.checker.alignscore'`（社区 issue #35）。

## 核心数据结构与评估入口

框架对外暴露的最主要类型是 `RAGResults` 与 `RAGChecker`，前者是带 schema 的数据容器，后者负责驱动指标计算。资料来源：[ragchecker/__init__.py:1-30]()

一个标准的 `RAGResults` 输入通常包含以下字段（与 `examples/checking_inputs.json` 一致）：

| 字段 | 含义 | 评估中的作用 |
|------|------|--------------|
| `query` | 用户原始问题 | 计算上下文相关性的锚点 |
| `gt_answer` | 人类参考答案 | 抽取 gt claims 并计算 overall recall |
| `response` | RAG 系统生成的回答 | 抽取 response claims 并计算 faithfulness |
| `retrieved_contexts` | 检索器返回的 chunk 列表 | 计算 context precision / noise |
| `response_chunks` | 回答中实际引用到的 chunk | 用于 claim-level 来源归属 |

资料来源：[examples/checking_inputs.json:1-50]() 与 [tutorial/ragchecker_tutorial_zh.md:30-80]()

通过 CLI 运行时，可直接传入输入文件与模型配置：

```bash
ragchecker.cli \
  --input_path examples/checking_inputs.json \
  --extractor_name gpt-4o-mini \
  --checker_name gpt-4o-mini \
  --output_path results.json
```

CLI 在调用 Bedrock 模型时存在已知问题：若运行环境未正确注入 AWS 凭据，会进入每 10 秒一次的无限重试循环（社区 issue #37）。资料来源：[ragchecker/cli.py:1-80]()

## 快速上手：5 行代码完成一次评估

下面示例演示了从读取输入到输出整体指标的最小闭环，源自教程文件的精简版本。资料来源：[tutorial/ragchecker_tutorial_zh.md:80-140]()

```python
from ragchecker import RAGResults, RAGChecker

with open("examples/checking_inputs.json", "r") as fp:
    rag_results = RAGResults.from_json(fp.read())

checker = RAGChecker(extractor_name="gpt-4o-mini", checker_name="gpt-4o-mini")
results = checker.evaluate(rag_results, ["overall_metrics", "retrieval_metrics"])
print(results)
```

首次运行时会触发声明抽取与细粒度校验，因此耗时与样本量近似线性。社区中常见的一个困惑是 **同一份输入多次运行结果不一致**，其根源在于 LLM 在 temperature=0 时仍存在非零的随机性（社区 issue #24）。在需要可复现的实验场景中，建议同时固定 litellm 的 `seed` 参数与模型版本号。

## 输出指标速查

评估结果会被聚合成若干簇，每一簇对应 RAG 流水线的一个阶段。RAGChecker 官方元评估使用 **Overall-Precision 衡量 Correctness、Overall-Recall 衡量 Completeness**（社区 issue #20 中作者给出的对应关系）。资料来源：[README.md:90-150]() 与 [ragchecker/evaluator.py:1-60]()

主要指标簇包括：

- `overall_metrics`：precision / recall / F1，综合事实层一致性。
- `retrieval_metrics`：context_precision、context_recall、claim_recall。
- `generation_metrics`：faithfulness、hallucination rate、噪声 chunk 比例。

如果仅希望计算部分指标，可以在 `checker.evaluate()` 的第二个参数显式列出指标簇，以减少 token 消耗。资料来源：[tutorial/ragchecker_tutorial_zh.md:140-200]()

---

<a id='page-2'></a>

## 指标体系、元评估与声明级推理

### 相关页面

相关主题：[框架概览与快速入门](#page-1)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ragchecker/metrics.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/metrics.py)
- [ragchecker/computation.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/computation.py)
- [data/meta_evaluation/README.md](https://github.com/amazon-science/RAGChecker/blob/main/data/meta_evaluation/README.md)
- [data/meta_evaluation/meta_eval.py](https://github.com/amazon-science/RAGChecker/blob/main/data/meta_evaluation/meta_eval.py)
- [data/meta_evaluation/baseline_ragchecker.json](https://github.com/amazon-science/RAGChecker/blob/main/data/meta_evaluation/baseline_ragchecker.json)
- [data/meta_evaluation/human_labeled_data.json](https://github.com/amazon-science/RAGChecker/blob/main/data/meta_evaluation/human_labeled_data.json)
</details>

# 指标体系、元评估与声明级推理

RAGChecker 提供一套以"声明 (claim)"为最小评估单元的细粒度指标体系，覆盖 RAG (Retrieval-Augmented Generation) 系统中的检索器、生成器以及端到端三个层次。该体系通过元评估 (meta-evaluation) 与人类标注对齐，验证其相对人工判断的代表性与可信度。下文按"指标分类 → 声明级推理 → 元评估"的顺序展开。

## 指标分类与输入要求

指标按评估对象划分为三类，对应不同的诊断目标与输入依赖。

- **检索器指标**：`context_precision` 与 `context_recall`，分别衡量检索上下文的相关性精确率与黄金证据的覆盖率。`资料来源：[data/meta_evaluation/README.md]()`
- **生成器指标**：`faithfulness`（答案对检索证据的忠实度）、`noise_robustness_in_relevant`、`noise_robustness_in_irrelevant`（对相关 / 不相关噪声的鲁棒性）。`资料来源：[data/meta_evaluation/README.md]()`
- **声明级指标**：`claim_recall`、`claim_precision`、`claim_f1` 等，在"声明集合"上计算集合级 PR/F1。`资料来源：[ragchecker/metrics.py]()`

社区 issue #29 集中讨论了这些指标在 `gt_answer` / `context` / `intermediate` 缺失时的退化行为，例如 `claim_recall` 在缺乏 `gt_answer` 时无法计算而返回 NaN，`faithlessness` 类指标则需要 `intermediate` 中保留每条声明的蕴含判断。`资料来源：[ragchecker/metrics.py]()` 同时 issue #24 指出，由于声明抽取和对齐均由 LLM 完成，相同输入多次运行可能出现轻微分差。`资料来源：[ragchecker/metrics.py]()`

## 总体指标 (Overall Metrics)

总体指标 `Overall-Precision` / `Overall-Recall` / `Overall-F1` 在声明粒度上对齐 answer 与 gt_answer，输出端到端分数：

- **Overall-Precision**：answer 中每条声明是否被检索上下文支持，反映"正确性 (Correctness)"。
- **Overall-Recall**：gt_answer 中的声明是否被 answer 覆盖，反映"完备性 (Completeness)"。
- **Overall-F1**：上述二者的调和平均。

`资料来源：[data/meta_evaluation/meta_eval.py]()` 中通过将 `metric_name` 设为 `overall_precision` / `overall_recall` / `overall_f1` 即可在标注集上复现这些指标。issue #20 中作者也明确将人工标签 `correctness_label` ↔ `Overall-Precision`、`completeness_label` ↔ `Overall-Recall` 进行了对应。`资料来源：[data/meta_evaluation/README.md]()`

## 声明级推理 (Claim-Level Reasoning)

RAGChecker 的核心创新在于将"声明"作为推理基本单位，其流程在 `metrics.py` 与 `computation.py` 中体现：

1. **声明抽取**：调用 LLM 从 answer / gt_answer / context 中拆出原子声明，并保留每条声明的来源 span。
2. **声明对齐与检查**：对 (claim_in_answer, claim_in_gt) 与 (claim_in_answer, claim_in_context) 计算支持 / 矛盾 / 中性三类关系，输出至 `RAGResults` 的 `intermediate` 字段。
3. **集合级聚合**：在声明集合上完成 PR/F1 计算并写回顶层指标。`资料来源：[ragchecker/computation.py]()`

issue #38 进一步追问"真实来源 vs 无依据声明"的支持关系——这正是声明级分类 (claim-level support taxonomy) 在审计工具中的典型延伸。`资料来源：[ragchecker/metrics.py]()`

## 元评估 (Meta-Evaluation)

元评估用于回答"哪个指标最接近人工评价"，由 `data/meta_evaluation/` 下的脚本与数据共同支撑：

- `human_labeled_data.json` 存放专家标注的样本，每条含 `correctness_label`、`completeness_label`、`overall_assessment_label` 三类人工评分。`资料来源：[data/meta_evaluation/human_labeled_data.json]()`
- `baseline_ragchecker.json` 存放 RAGChecker 在该标注集上的预测分数。`资料来源：[data/meta_evaluation/baseline_ragchecker.json]()`
- `meta_eval.py` 加载上述两份 JSON，按 `metric_name` 维度计算各 RAGChecker 指标与对应人工标签的 Kendall 等级相关系数 τ，结果写入 `results.json`。`资料来源：[data/meta_evaluation/meta_eval.py]()`

`README.md` 描述了完整的复现步骤——安装 RefChecker、下载标注与基线数据、运行 `meta_eval.py`，即可得到论文表 7 中的 τ 值。`资料来源：[data/meta_evaluation/README.md]()`

## 小结

RAGChecker 的指标体系在"声明"这一统一抽象下，把检索器诊断、生成器诊断与端到端评估串联起来；元评估则把自动化指标与人类判断绑定到 Kendall 等级相关系数 (τ) 上，从而在调优 RAG 系统时既能获得可解释的细粒度分数，也能对所选指标的代表性与稳健性建立量化信心。

---

<a id='page-3'></a>

## RAG 基线流水线与数据合成

### 相关页面

相关主题：[框架概览与快速入门](#page-1), [集成、扩展与已知问题排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [rag_baselines/chunking.py](https://github.com/amazon-science/RAGChecker/blob/main/rag_baselines/chunking.py)
- [rag_baselines/embedding.py](https://github.com/amazon-science/RAGChecker/blob/main/rag_baselines/embedding.py)
- [rag_baselines/indexing.py](https://github.com/amazon-science/RAGChecker/blob/main/rag_baselines/indexing.py)
- [rag_baselines/retrieval.py](https://github.com/amazon-science/RAGChecker/blob/main/rag_baselines/retrieval.py)
- [rag_baselines/generation.py](https://github.com/amazon-science/RAGChecker/blob/main/rag_baselines/generation.py)
- [rag_baselines/opensearch_client.py](https://github.com/amazon-science/RAGChecker/blob/main/rag_baselines/opensearch_client.py)
</details>

# RAG 基线流水线与数据合成

## 1. 模块定位与整体作用

`rag_baselines/` 目录承载了 RAGChecker 论文中使用的 **端到端 RAG 基线流水线**，负责把原始语料转化为「问题—证据—答案」三元组，再交给 `ragchecker` 核心评估器进行细粒度指标打分。该目录并不直接产出指标，而是为评估阶段提供 **可复现的 RAG 数据合成环境**，使研究者能够在统一基线下对比不同检索器、Embedding 模型或生成器。资料来源：[rag_baselines/chunking.py:1-1]()

流水线总体遵循经典 RAG 架构：分块 → 嵌入 → 索引 → 检索 → 生成。`opensearch_client.py` 提供底层的向量/混合检索客户端封装，被 `indexing.py` 与 `retrieval.py` 共同依赖。资料来源：[rag_baselines/opensearch_client.py:1-1]()

## 2. 数据合成阶段

### 2.1 文档分块（Chunking）

`chunking.py` 提供把长文档切分为定长或语义片段的逻辑，是后续嵌入与索引的最小处理单元。合理的块大小直接决定 recall 指标上界——块过小会切断上下文，过大则会引入噪声上下文，降低上下文精度。资料来源：[rag_baselines/chunking.py:1-1]()

### 2.2 嵌入生成（Embedding）

`embedding.py` 负责调用外部嵌入服务（通过 `litellm` 统一接口，支持 OpenAI、Bedrock 等）将文本块映射为稠密向量。社区中关于「不同模型是否可用作 extractor/checker」的问题（参见 Issue #10）的回答明确指出 RAGChecker 通过 `litellm` 支持多种模型，这同样适用于基线嵌入阶段。资料来源：[rag_baselines/embedding.py:1-1]()、[https://github.com/amazon-science/RAGChecker/issues/10]()

### 2.3 索引构建（Indexing）

`indexing.py` 把向量与原始文本块一起写入 OpenSearch 索引，依赖 `opensearch_client.py` 提供的连接管理、bulk 写入与字段映射能力。索引阶段输出的检索语料库是后续评估的事实基准，决定了所有「未检索到」类指标（context_precision、context_recall）的取值空间。资料来源：[rag_baselines/indexing.py:1-1]()、[rag_baselines/opensearch_client.py:1-1]()

## 3. 在线推理与答案合成

### 3.1 检索（Retrieval）

`retrieval.py` 在评估查询时，根据查询向量执行最近邻搜索，返回 top-k 上下文片段。该模块直接产出 RAGChecker 评估所必需的 `retrieved_contexts` 字段，是 `RAGResults` 数据类的核心输入之一。资料来源：[rag_baselines/retrieval.py:1-1]()

### 3.2 生成（Generation）

`generation.py` 接收检索返回的上下文，拼接 prompt 后调用 LLM 生成最终答案，形成 `response` 字段。该模块的输出连同检索上下文共同构成完整的合成数据样本，可被序列化进 JSON 文件并由 `RAGResults.from_json` 加载（参考 Issue #11 中的用法示例）。资料来源：[rag_baselines/generation.py:1-1]()、[https://github.com/amazon-science/RAGChecker/issues/11]()

## 4. 与评估器的衔接

| 基线阶段 | 产出字段 | 喂入 RAGChecker 的位置 |
|---------|---------|----------------------|
| Chunking | 原始 chunks | 索引语料 |
| Embedding + Indexing | OpenSearch index | 检索源 |
| Retrieval | retrieved_contexts | `RAGResults` 顶层字段 |
| Generation | response | `RAGResults.response` |

资料来源：[rag_baselines/retrieval.py:1-1]()、[rag_baselines/generation.py:1-1]()

需要注意的是，由于生成阶段依赖 LLM，社区反馈多次出现的「同一数据多次运行指标不同」（Issue #24）问题在基线流水线中同样存在——即使 `temperature=0`，底层模型仍可能存在不可复现的随机性，需要在基线实验中固定随机种子或多次取平均。资料来源：[https://github.com/amazon-science/RAGChecker/issues/24]()

## 5. 使用建议与注意事项

- **数据一致性**：基线流水线产出的 `query`、`gt_answer`（来自评测集）和 `response`、`retrieved_contexts` 必须按样本 ID 严格对齐，否则整体/单项指标会因缺失字段而出现 NaN（参考 Issue #29 关于缺失数据行为的讨论）。资料来源：[https://github.com/amazon-science/RAGChecker/issues/29]()
- **模型兼容**：嵌入与生成均通过 `litellm` 调度，因此 Issue #37 报告的 Bedrock 客户端卡死问题在基线阶段也会复现，建议显式重试与超时。资料来源：[https://github.com/amazon-science/RAGChecker/issues/37]()
- **环境依赖**：在精简 Docker 镜像（如 `python:3.12-slim`）上运行基线时，需确保 `spacy` 模型与 `refchecker` 依赖已安装，否则导入 `ragchecker` 会失败（参考 Issue #35）。资料来源：[https://github.com/amazon-science/RAGChecker/issues/35]()

通过上述六个模块的协同，`rag_baselines/` 把「如何得到一份带证据的 RAG 输出」这一前置工程完整封装，与下游 `ragchecker` 评估器解耦，使研究者可以专注于替换任意单环节（分块策略、Embedding 模型、检索器或生成器）来观察指标变化。

---

<a id='page-4'></a>

## 集成、扩展与已知问题排查

### 相关页面

相关主题：[框架概览与快速入门](#page-1), [RAG 基线流水线与数据合成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ragchecker/integrations/llama_index.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/integrations/llama_index.py)
- [ragchecker/cli.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/cli.py)
- [ragchecker/container.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/container.py)
- [ragchecker/_config.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/_config.py)
- [ragchecker/checker.py](https://github.com/amazon-science/RAGChecker/blob/main/ragchecker/checker.py)
- [pyproject.toml](https://github.com/amazon-science/RAGChecker/blob/main/pyproject.toml)
- [examples/run.sh](https://github.com/amazon-science/RAGChecker/blob/main/examples/run.sh)
- [tutorial/ragchecker_tutorial_en.md](https://github.com/amazon-science/RAGChecker/blob/main/tutorial/ragchecker_tutorial_en.md)
</details>

# 集成、扩展与已知问题排查

本页面向希望把 RAGChecker 接入既有 RAG 流水线、替换底层模型或容器化部署的开发者，整理三类内容：可被复用的集成与扩展点、CLI 与依赖容器化方式，以及社区反馈中高频出现的环境与运行错误排查。

## 集成与扩展点

RAGChecker 的外部耦合面集中在「数据接入」「模型调用」「第三方框架适配」三处。

### 模型后端：通过 LiteLLM 解耦

RAGChecker 不直接绑定任何厂商 SDK，而是通过 LiteLLM 统一调度 `extractor` 与 `checker` 使用的 LLM。`pyproject.toml` 中将 `litellm` 列为运行期必需依赖，配合 `_config.py` 中读取的模型名称与环境变量即可访问 OpenAI、Azure OpenAI、Bedrock 等多种后端。官方说明指出："we use litellm for invoking the models, it supports various models including OpenAI models. You can just use the names of OpenAI models"，由此可知切换后端只需修改 `extractor_llm_name` / `checker_llm_name` 字段，无需改动调用代码。`资料来源：[pyproject.toml:1-80]()`

### 第三方框架：LlamaIndex 适配器

`ragchecker/integrations/llama_index.py` 提供 `LlamaIndexRAGChecker` 类，将 LlamaIndex 的 `Response` 对象一键转换为 RAGChecker 内部数据结构，再复用 `RAGChecker.evaluate()` 完成指标计算。该适配器读取 `source_nodes` 中的 `node.text` 与得分作为 `retrieved_contexts`，从 `Response.response` 抽取 `response`，并支持自定义 `user_response_filter` 等钩子，便于在保留 LlamaIndex 查询语义的同时复用 RAGChecker 的细粒度评测能力。`资料来源：[ragchecker/integrations/llama_index.py:1-200]()`

### 配置与依赖注入：Container

`ragchecker/container.py` 采用依赖注入容器统一管理 `extractor`、`checker`、`metric_evaluator` 等组件，外部可通过 `RAGCheckerConfig` 在创建 `RAGChecker` 实例时替换其中的任意服务（例如换成本地 vLLM 端点或自研 NLI 模型）。这一设计也是后续替换 RefChecker 默认 checker（例如 AlignScore、Basilisk）的扩展点。`资料来源：[ragchecker/container.py:1-150]()`

## CLI 与部署形态

`ragchecker/cli.py` 提供 `python -m ragchecker.cli` 形式的命令行入口，可直接传入 `input_path` / `output_path` 跑完一次评估；`examples/run.sh` 给出了带 `extractor_llm_name`、`checker_llm_name`、`metrics` 等参数的可执行范例。`资料来源：[ragchecker/cli.py:1-120]()`、`资料来源：[examples/run.sh:1-60]()`

部署侧，官方推荐的 Python 版本区间与 `pyproject.toml` 中声明的解释器约束一致——pip 安装在 Python 3.13 上会因部分 C 扩展的 metadata-generation-failed 而失败，需回退到 Python 3.12；如果在 Docker `python:3.12-slim` 上安装，还需额外执行 `python -m spacy download en_core_web_sm` 以补齐 RefChecker 的 spaCy 模型，否则会触发 `ModuleNotFoundError: No module named 'refchecker.checker.alignscore'` 类的导入错误。`资料来源：[pyproject.toml:1-80]()`、`资料来源：[tutorial/ragchecker_tutorial_en.md:1-120]()`

下表汇总常见部署变体与其前置动作：

| 部署形态 | Python | 必做动作 | 备注 |
|---|---|---|---|
| 本地 pip | 3.11 / 3.12 | `pip install ragchecker` + `python -m spacy download en_core_web_sm` | Python 3.13 编译失败 |
| Docker slim | 3.12-slim | 同上，并显式安装 spaCy 模型 | 否则缺少 `alignscore` checker |
| EC2 + Bedrock | 3.12 | 配置 AWS 凭证，确认 litellm `bedrock/` 前缀 | 注意 10s 退避循环 |

## 已知问题与排查

社区 issue 中反复出现的问题集中在三类：环境/依赖不兼容、模型调用稳定性、指标随机性。

**环境与依赖**：`transformers ≥ 4.50` 已移除 `AdamW`，导致 `from transformers import AdamW` 在新版下失败；目前已知的兼容上限是 `transformers 4.49`，升级 Hugging Face 库前需先确认是否影响 RefChecker 链路。此外 `dataclasses-json` 的版本上限（`>=0.5.12`）与 `flytekit` 的依赖区间冲突，无法在同一环境同时安装两套依赖，需评估是否真有必要混入 Flyte。`资料来源：[pyproject.toml:1-80]()`

**模型调用稳定性**：在 EC2 上使用 Bedrock 时，`botocore` 抛出的非致命异常会被 LiteLLM 捕获并进入「sleep 10 秒 → 重试」的循环，日志会反复出现 `[sleep 10 seconds] litellm.RateLimitError`。排查时应先开启 `DEBUG` 日志定位真实根因，再调整 `max_retries` 或退避策略；Azure OpenAI 场景下也需要在环境变量中显式声明 `AZURE_API_KEY`、`AZURE_API_BASE`、`AZURE_API_VERSION` 并启用 `RAGCHECKER_VERBOSE`，否则只会看到一行模糊报错。`资料来源：[ragchecker/cli.py:1-120]()`

**指标随机性**：即便把 temperature 设为 0，多次运行仍可能得到不同分数。根因在于 claim-level 抽取和 NLI 判定都依赖 LLM 输出，目前仓库尚无内置的「强制可复现」开关；规避办法包括固定随机种子、固定模型版本、对同一批样本多次评估取中位数，或将抽取/判定改为基于 AlignScore 等非生成式 checker。`资料来源：[ragchecker/checker.py:1-200]()`

## 排查流程速查

```mermaid
flowchart TD
    A[开始] --> B{导入失败?}
    B -- 是 --> C[检查 Python 版本 ≤3.12<br/>+ spaCy 模型]
    B -- 否 --> D{运行报 retry 循环?}
    D -- 是 --> E[检查 litellm 后端凭证<br/>+ 关闭 DEBUG 重试]
    D -- 否 --> F{指标抖动?}
    F -- 是 --> G[固定 seed / 多次取中位<br/>或换非生成式 checker]
    F -- 否 --> H[检查 RAGResults 字段完整性<br/>参考 issue #29]
```

遵循以上顺序，可在大多数情况下把根因定位到「依赖」「凭证」「随机性」三类之一，再结合对应章节进一步收敛。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：amazon-science/RAGChecker

摘要：发现 15 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：Deprecation issue with the latest Transformers。

## 1. 安装坑 · 来源证据：Deprecation issue with the latest Transformers

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Deprecation issue with the latest Transformers
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/amazon-science/RAGChecker/issues/34 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：RAGChecker Metric Input Requirements and Missing Data Handling

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：RAGChecker Metric Input Requirements and Missing Data Handling
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/amazon-science/RAGChecker/issues/29 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：Taxonomy question: real source vs unsupported claim support

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Taxonomy question: real source vs unsupported claim support
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/amazon-science/RAGChecker/issues/38 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安装坑 · 来源证据：pip install ragchecker fails with Python 3.13 – works with Python 3.12

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：pip install ragchecker fails with Python 3.13 – works with Python 3.12
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/amazon-science/RAGChecker/issues/32 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 安全/权限坑 · 来源证据：Error Loading RagChecker

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Error Loading RagChecker
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/amazon-science/RAGChecker/issues/11 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 6. 安全/权限坑 · 来源证据：Which metrics are adopted in meta-evaluation by ragchecker?

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Which metrics are adopted in meta-evaluation by ragchecker?
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/amazon-science/RAGChecker/issues/20 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 安装坑 · 来源证据：import error on a docker python:3.12-slim image

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：import error on a docker python:3.12-slim image
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/amazon-science/RAGChecker/issues/35 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 8. 配置坑 · 来源证据：Dataclasses-json version restrictions leads to Flyte incompatibility

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Dataclasses-json version restrictions leads to Flyte incompatibility
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/amazon-science/RAGChecker/issues/28 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/amazon-science/RAGChecker | README/documentation is current enough for a first validation pass.

## 10. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/amazon-science/RAGChecker | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/amazon-science/RAGChecker | no_demo; severity=medium

## 12. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/amazon-science/RAGChecker | no_demo; severity=medium

## 13. 安全/权限坑 · 来源证据：CLI fails with Bedrock models unless

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CLI fails with Bedrock models unless
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/amazon-science/RAGChecker/issues/37 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 14. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/amazon-science/RAGChecker | issue_or_pr_quality=unknown

## 15. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/amazon-science/RAGChecker | release_recency=unknown

<!-- canonical_name: amazon-science/RAGChecker; human_manual_source: deepwiki_human_wiki -->