# https://github.com/vibrantlabsai/ragas 项目说明书

生成时间：2026-06-25 23:57:58 UTC

## 目录

- [Ragas 项目概述与快速入门](#page-1)
- [评估指标系统（Metrics）](#page-2)
- [测试集生成、数据模式与后端存储](#page-3)
- [LLM 集成、适配器、提示词优化与成本追踪](#page-4)

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

## Ragas 项目概述与快速入门

### 相关页面

相关主题：[评估指标系统（Metrics）](#page-2), [测试集生成、数据模式与后端存储](#page-3), [LLM 集成、适配器、提示词优化与成本追踪](#page-4)

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

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

- [README.md](https://github.com/vibrantlabsai/ragas/blob/main/README.md)
- [examples/README.md](https://github.com/vibrantlabsai/ragas/blob/main/examples/README.md)
- [src/ragas/integrations/__init__.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/integrations/__init__.py)
- [src/ragas/integrations/langchain.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/integrations/langchain.py)
- [src/ragas/integrations/langsmith.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/integrations/langsmith.py)
- [src/ragas/llms/adapters/base.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/adapters/base.py)
- [src/ragas/llms/haystack_wrapper.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/haystack_wrapper.py)
- [src/ragas/testset/graph.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/graph.py)
- [src/ragas/testset/synthesizers/generate.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/synthesizers/generate.py)
- [src/ragas/testset/transforms/base.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/transforms/base.py)
- [src/ragas/testset/transforms/default.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/transforms/default.py)
- [src/ragas/prompt/prompt-formats.md](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/prompt-formats.md)
</details>

# Ragas 项目概述与快速入门

## 一、项目定位与核心能力

Ragas 是一个面向大语言模型（LLM）应用的评估与优化工具集，旨在为 RAG 系统、智能体（agent）、提示词工程以及复杂工作流提供客观、可量化的评估能力，并支持自动化的测试数据生成。根据 `README.md` 中的描述，Ragas 的目标是用"数据驱动"取代"主观、人工"的评估流程，从而帮助开发者在迭代过程中建立可重复、可比较的反馈闭环 资料来源：[README.md:1-15]()。

项目主要提供以下能力：

- **客观评估指标**：同时支持基于 LLM 的语义评估和传统非 LLM 指标（例如字符串相似度、上下文相关性等），便于在不同场景下选择合适的度量方式 资料来源：[README.md:9-15]()。
- **测试数据自动生成**：在没有现成评测集时，可基于知识图谱（KnowledgeGraph）和转换流水线自动生成与生产场景对齐的测试样本 资料来源：[src/ragas/testset/synthesizers/generate.py:48-92]()。
- **框架与可观测性集成**：内置 LangChain、LlamaIndex、LangSmith、Langfuse、MLflow、Helicone、Opik、Haystack 等适配器，覆盖开发、实验追踪和生产观测全链路 资料来源：[src/ragas/integrations/__init__.py:1-25]()。
- **多平台与协议支持**：包括 Amazon Bedrock、R2R、Swarm 多智能体评估以及 AG-UI 事件协议 资料来源：[src/ragas/integrations/__init__.py:11-19]()。

## 二、安装与快速入门

### 2.1 安装方式

Ragas 可通过 PyPI 一键安装，亦可从源码安装以获取最新特性 资料来源：[README.md:27-33]()：

```bash
# PyPI 安装
pip install ragas

# 从源码安装
pip install git+https://github.com/vibrantlabsai/ragas
```

当需要运行官方示例项目时，需要额外安装 `examples` 子包。推荐使用 `uv pip` 进行可编辑安装，便于本地调试 资料来源：[examples/README.md:11-19]()：

```bash
cd /path/to/ragas
uv pip install -e . -e ./examples
```

### 2.2 快速启动模板

`README.md` 提供的 `ragas quickstart` 命令可直接生成可运行的评估项目骨架，目前支持 `rag_eval`（RAG 系统评估），未来将开放 `agent_evals`、`benchmark_llm`、`prompt_evals`、`workflow_eval` 等模板 资料来源：[README.md:37-54]()。

### 2.3 第一个评估示例

下例展示了使用 `DiscreteMetric` 自定义评估维度的最小流程，依赖 `OPENAI_API_KEY` 环境变量，并通过 `llm_factory` 构造 LLM 客户端 资料来源：[README.md:58-87]()：

```python
import asyncio
from openai import AsyncOpenAI
from ragas.metrics import DiscreteMetric
from ragas.llms import llm_factory

client = AsyncOpenAI()
llm = llm_factory("gpt-4o", client=client)

metric = DiscreteMetric(
    name="summary_accuracy",
    allowed_values=["accurate", "inaccurate"],
    prompt="Evaluate if the summary is accurate and captures key information.\n"
           "Response: {response}\nAnswer with only 'accurate' or 'inaccurate'."
)

async def main():
    score = await metric.ascore(llm=llm, response="The summary of the text is...")
    print(f"Score: {score.value}\nReason: {score.reason}")

asyncio.run(main())
```

## 三、核心架构与模块划分

Ragas 的代码组织遵循"核心抽象 + 可插拔适配器"的分层结构。下图展示了主要模块及其依赖关系。

```mermaid
flowchart TB
    A[用户入口<br/>ragas.metrics / ragas.testset] --> B[LLM 适配层<br/>ragas.llms]
    A --> C[嵌入适配层<br/>ragas.embeddings]
    A --> D[测试集合成<br/>ragas.testset]
    B --> E[结构化输出适配<br/>Instructor / LiteLLM]
    B --> F[框架包装<br/>LangChain / LlamaIndex / Haystack]
    D --> G[知识图谱<br/>KnowledgeGraph]
    D --> H[图转换<br/>BaseGraphTransformation]
    A --> I[集成<br/>LangSmith / Langfuse / Opik / Bedrock]
    A --> J[成本与回调<br/>CostCallbackHandler / TokenUsage]
```

关键模块说明：

- **LLM 适配层**：通过 `BaseRagasLLM` 抽象统一同步/异步调用接口，`StructuredOutputAdapter` 抽象类定义结构化输出适配器接口，便于 Instructor、LiteLLM 等后端实现 资料来源：[src/ragas/llms/adapters/base.py:1-29]()。
- **Haystack 包装器**：`HaystackLLMWrapper` 将 Haystack 的 `OpenAIGenerator`/`AzureOpenAIGenerator` 等组件封装为 Ragas 可用的 LLM 资料来源：[src/ragas/llms/haystack_wrapper.py:21-44]()。
- **测试集生成**：核心入口 `generate()` 会构建 `KnowledgeGraph`、应用转换流水线、再分发给不同的合成器（single hop、multi hop 等） 资料来源：[src/ragas/testset/synthesizers/generate.py:48-92]()。
- **图转换基类**：`BaseGraphTransformation` 要求所有转换实现 `transform(kg)`，并保证转换的幂等性，避免重复生成相同结果 资料来源：[src/ragas/testset/transforms/base.py:48-66]()。
- **默认转换集合**：`default_transforms` 会根据文档长度分布动态决定是否启用 HeadlinesExtractor、SummaryExtractor 等步骤 资料来源：[src/ragas/testset/transforms/default.py]()。
- **知识图谱持久化**：`KnowledgeGraph.save()` 以 UTF-8 JSON 写入节点与关系，可跨平台无损加载 资料来源：[src/ragas/testset/graph.py]()。
- **Prompt 持久化格式**：`Prompt` 与 `DynamicFewShotPrompt` 使用 `format_version` 标记的 JSON（含 `.json.gz` 可选压缩）进行序列化，区别在于是否携带嵌入模型与相似度配置 资料来源：[src/ragas/prompt/prompt-formats.md:1-15]()。

## 四、社区关注点与已知注意事项

根据近期的社区讨论，新用户在上手 Ragas 时常关注以下主题和坑点：

- **Token 与成本追踪**：`CostCallbackHandler` 与 `TokenUsage` 是社区高频需求，但 `get_token_usage_for_bedrock` 在 `langchain-aws` 的 `ChatBedrock`/`ChatBedrockConverse` 上读取了错误的 `response_metadata` key，导致始终返回 0 资料来源：[README.md]() 中的反馈引用 issue #2779。
- **多语言测试集生成**：非英语语料（如乌兹别克语）下，`HeadlinesExtractor` 等转换可能因缺少数 `headlines` 属性而报错，需先核对 `default_transforms` 中的语言相关步骤 issue #1775。
- **模型兼容性**：`AspectCritic` 等指标在切换到 `o3` 系列推理模型时容易出现解析错误，需要使用支持结构化输出的适配器 issue #2067。
- **测试集生成模块演进**：v0.4 版本正在征求社区对 `testset` 模块未来形态的意见 issue #2231；最新 v0.4.3 还引入了 `DSPyOptimizer`（基于 MIPROv2）以及 DSPy 缓存能力 资料来源：[v0.4.3 Release Notes]()。
- **可选依赖优化**：`diskcache` 当前以强依赖方式安装，但实际仅在显式调用时才使用，社区建议将其改为可选依赖 issue #2622。
- **安全与流程注入**：项目已修复 `.github/workflows/claude-docs-check.yml` 在 `pull_request_target` 下的潜在提示词注入风险 issue #2692。

## See Also

- 评估指标与 LLM 工厂：`src/ragas/llms/`、`src/ragas/metrics/`
- 测试集合成与知识图谱：`src/ragas/testset/`、`src/ragas/testset/graph.py`
- 集成与可观测性：`src/ragas/integrations/__init__.py`、`src/ragas/integrations/langchain.py`、`src/ragas/integrations/langsmith.py`
- Prompt 持久化规范：`src/ragas/prompt/prompt-formats.md`
- 官方示例集合：`examples/README.md`

---

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

## 评估指标系统（Metrics）

### 相关页面

相关主题：[Ragas 项目概述与快速入门](#page-1), [测试集生成、数据模式与后端存储](#page-3), [LLM 集成、适配器、提示词优化与成本追踪](#page-4)

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

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

- [README.md](https://github.com/vibrantlabsai/ragas/blob/main/README.md)
- [src/ragas/prompt/metrics/__init__.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/metrics/__init__.py)
- [src/ragas/prompt/metrics/base_prompt.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/metrics/base_prompt.py)
- [src/ragas/prompt/metrics/noise_sensitivity.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/metrics/noise_sensitivity.py)
- [src/ragas/prompt/pydantic_prompt.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/pydantic_prompt.py)
- [src/ragas/prompt/prompt-formats.md](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/prompt-formats.md)
- [src/ragas/llms/adapters/base.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/adapters/base.py)
- [src/ragas/integrations/__init__.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/integrations/__init__.py)
</details>

# 评估指标系统（Metrics）

## 一、系统定位与核心目标

Ragas 的评估指标系统（Metrics）是该框架的核心能力之一，用于对大语言模型（LLM）应用进行客观、可量化的评估。指标系统支持基于 LLM 的语义判断（如忠实度、答案相关性）以及传统的非 LLM 数值评估（如上下文召回率），从而覆盖 RAG、Agentic workflow 等多类应用场景。

根据 [README.md](https://github.com/vibrantlabsai/ragas/blob/main/README.md) 的描述，Ragas 通过 `DiscreteMetric` 等预构建指标类，提供面向 RAG 系统的离散评分能力。例如，开发者可以创建一个二元离散指标来判断摘要是否"准确"或"不准确"，并通过 `ascore()` 方法异步调用 LLM 完成评分。资料来源：[README.md:20-50]()

指标系统同时强调"客观评估"与"反馈闭环"——既能为 RAG 流水线生成细粒度诊断结果，也能配合生产数据形成持续优化循环。资料来源：[README.md:18-22]()

## 二、提示词（Prompt）架构

所有指标的核心均为基于 Pydantic 的结构化提示词。`ragas.prompt.metrics` 子包导出了一组面向具体指标语义任务的 Prompt 模板。资料来源：[src/ragas/prompt/metrics/__init__.py:1-14]()

- `answer_relevancy_prompt` —— 用于答案相关性评估
- `correctness_classifier_prompt` —— 用于答案正确性分类
- `nli_statement_prompt` / `statement_generator_prompt` —— 共用子任务（自然语言推理、语句生成）
- `BasePrompt` —— 抽象基类，约束 `instruction`、`input_model`、`output_model` 三要素

每个具体指标的提示词都继承自 `PydanticPrompt[InputModel, OutputModel]`，强制规定输入输出的 Pydantic Schema，确保 LLM 返回的 JSON 可以被自动校验与解析。资料来源：[src/ragas/prompt/metrics/base_prompt.py:7-15]()

下表列出了当前 metrics 子模块导出的关键提示词及其用途：

| 提示词名称 | 适用指标 | 数据流角色 |
|------------|----------|------------|
| `answer_relevancy_prompt` | AnswerRelevance | 生成评估问题与参考答案的候选 |
| `correctness_classifier_prompt` | AnswerCorrectness | 对答案与参考答案的语义一致性做分类 |
| `nli_statement_prompt` | Faithfulness（共用） | 对生成的语句做 NLI 蕴含判断 |
| `statement_generator_prompt` | Faithfulness（共用） | 将长答案拆分为原子语句 |
| `BasePrompt` | 所有指标 | 定义指令、示例、响应模型的统一基类 |

例如，`noise_sensitivity` 指标的提示词使用 `{safe_context}` 与 `{safe_statements}` 占位符，并通过 JSON `verdict` 字段表达逐条语句的相关性判断。资料来源：[src/ragas/prompt/metrics/noise_sensitivity.py:1-40]()

## 三、序列化与适配机制

指标提示词支持 `.json` 与 `.json.gz` 两种持久化格式，`format_version` 字段锁定为 `"1.0"`，便于跨版本兼容。`response_model_info` 字段记录了响应模型的类名、模块路径与 schema，以确保加载时能够反序列化。资料来源：[src/ragas/prompt/prompt-formats.md:7-50]()

在底层，指标与 LLM 的桥接由 `StructuredOutputAdapter` 抽象基类承担，其 `create_llm` 方法负责为不同后端（Instructor、LiteLLM 等）注入结构化输出能力。资料来源：[src/ragas/llms/adapters/base.py:6-25]()

整个评估流程的运行时回放与链路追踪则由集成层负责，Ragas 已对接 Langfuse、MLflow、LangSmith、Opik 等可观测性平台。资料来源：[src/ragas/integrations/__init__.py:1-18]()

## 四、典型工作流与社区反馈

指标的典型工作流可概括为：构造指标实例 → 注入 `llm`（通过 `llm_factory`） → 调用 `ascore()` 或批量评估 → 收集 `value` 与 `reason`。`PydanticPrompt` 内部封装了 `to_string` 与 `generate` 链路，并使用 `PydanticOutputParser` 将 LLM 输出反序列化为 Pydantic 对象。资料来源：[src/ragas/prompt/pydantic_prompt.py:1-50]()

社区中也存在若干与指标系统直接相关的痛点：

- **Evaluator 模型兼容性**：Issue #2067 报告 `AspectCritic` 在切换到 `o3` 推理模型时出现运行时错误，提示结构化输出适配器在新型推理模型上仍需调整。资料来源：community context (issue #2067)
- **Threshold 边界一致性**：Issue #2777 指出 `NonLLMContextRecall` 与 `NonLLMContextPrecisionWithReference` 在分数转二值相关性时使用了不一致的 `>` 与 `>=` 边界。
- **弃用类名错误**：Issue #2748 显示 `LLMContextPrecisionWithoutReference` 的弃用提示指向了不存在的类，可能导致 `ImportError`。
- **结果汇总与阈值闸门**：Issue #2760 提议为 `EvaluationResult` 增加 `summary()` 与 `check_thresholds()` 公共方法，以便在 CI 中使用指标阈值做回归闸门。

为减少类似问题，建议在使用自定义指标时显式声明 `input_model` / `output_model`，并优先通过 `llm_factory` 注入 LLM 而非直接依赖 LangChain 包装器（后者已被标记为弃用）。资料来源：[src/ragas/prompt/pydantic_prompt.py:30-45]()

## See Also

- [测试集生成系统（Testset Generation）](#) —— 依赖 `metrics` 体系进行合成数据的质量评估
- [LLM 工厂与适配器（LLM Factory & Adapters）](#) —— 指标系统与 LLM 后端解耦的关键
- [提示词持久化（Prompt Serialization）](#) —— 指标模板的 `.json/.json.gz` 存储细节

---

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

## 测试集生成、数据模式与后端存储

### 相关页面

相关主题：[Ragas 项目概述与快速入门](#page-1), [评估指标系统（Metrics）](#page-2)

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

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

- [src/ragas/testset/graph.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/graph.py)
- [src/ragas/testset/synthesizers/generate.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/synthesizers/generate.py)
- [src/ragas/testset/synthesizers/single_hop/prompts.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/synthesizers/single_hop/prompts.py)
- [src/ragas/testset/transforms/base.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/transforms/base.py)
- [src/ragas/testset/transforms/default.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/transforms/default.py)
- [src/ragas/testset/transforms/extractors/llm_based.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/transforms/extractors/llm_based.py)
- [src/ragas/testset/transforms/filters.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/transforms/filters.py)
- [src/ragas/prompt/pydantic_prompt.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/pydantic_prompt.py)
- [src/ragas/prompt/prompt-formats.md](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/prompt-formats.md)
- [src/ragas/backends/utils.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/backends/utils.py)
- [src/ragas/llms/adapters/base.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/adapters/base.py)
- [README.md](https://github.com/vibrantlabsai/ragas/blob/main/README.md)
</details>

# 测试集生成、数据模式与后端存储

## 1. 概述

`ragas` 的测试集生成（Testset Generation）模块提供了一套端到端的流水线，用于在没有现成标注数据的情况下，根据用户文档语料自动合成可用于 RAG / LLM 应用评估的数据集。该模块在仓库 README 中被列为四大核心能力之一（"Test Data Generation: Automatically create comprehensive test datasets covering a wide range of scenarios"）。资料来源：[README.md:1-20]()。

其内部核心数据结构是 `KnowledgeGraph`（知识图谱），围绕"节点-关系-变换器-合成器"的层次展开，整体可以拆分为三个相互衔接的子系统：

- **数据模式层**：`KnowledgeGraph` / `Node` / `Relationship` 的内存表示与 JSON 持久化。
- **变换流水线层**：`BaseGraphTransformation` 抽象类及其具体子类（提取器、过滤器、关系构建器）。
- **合成器层**：`generate()` / 单跳（single_hop）提示词驱动的问题-答案对生成。

下图为整体数据流：

```mermaid
flowchart LR
    Docs[LangChain Documents] --> Chunker[Chunker / Default Transforms]
    Chunker --> KG[KnowledgeGraph]
    KG --> Extractors[LLM Extractors<br/>Headlines / Keyphrases / NER / Topic]
    Extractors --> Filters[CustomNodeFilter<br/>QuestionPotential]
    Filters --> RelBuilder[RelationshipBuilder<br/>Similarity]
    RelBuilder --> Synth[Synthesizers<br/>SingleHop / MultiHop]
    Synth --> Testset[Testset]
    KG -.save/load.-> JSON[(JSON file)]
```

## 2. 数据模式：KnowledgeGraph

`KnowledgeGraph` 是测试集生成模块中所有节点和关系的容器，定义了统一的内存模型以及与磁盘之间的序列化约定。资料来源：[src/ragas/testset/graph.py:1-50]()。

关键设计要点：

- **节点类型**：通过 `NodeType` 枚举区分 `DOCUMENT`、`CHUNK` 等不同粒度；每个 `Node` 持有任意键值对形式的 `properties`（例如 `page_content`、`summary`、`document_metadata`）。资料来源：[src/ragas/testset/synthesizers/generate.py:30-50]()。
- **关系类型**：`Relationship` 用于在节点之间建立语义联系（典型用法是基于嵌入相似度）。
- **持久化**：`save(path)` 将 `nodes` 与 `relationships` 通过 `model_dump()` 转储为 JSON，使用 UTF-8 编码写入；对应的 `load(path)` 类方法从同一 JSON 结构中重建图谱。资料来源：[src/ragas/testset/graph.py:60-110]()。

这种"图谱优先"的数据模式让 transforms 既能增量修改节点属性（如抽取摘要），又能构建新关系，最后由合成器基于子图采样生成问答对。

## 3. 变换流水线：Extractors、Filters 与默认编排

### 3.1 抽象基类

所有变换都继承自 `BaseGraphTransformation`，并通过 `generate_execution_plan(kg)` 返回一组协程，由 `Executor` 并行执行。资料来源：[src/ragas/testset/transforms/base.py:1-80]()。这一设计让变换可以独立测试、按需组合。

`NodeSplitter` 负责把父节点拆分为子节点；`RelationshipBuilder` 负责建立新关系；二者的执行计划都通过 `apply_split` / 类似包装函数映射到异步协程序列。

### 3.2 LLM 驱动的 Extractors

`LLMBasedExtractor` 家族包含多种针对 `page_content` 的抽取器，全部基于 `PydanticPrompt` 与 Pydantic 输出模型：

| 抽取器 | property_name | 用途 |
|--------|---------------|------|
| `HeadlinesExtractor` | `headlines` | 抽取 L2/L3 级别标题以切分章节 |
| `KeyphrasesExtractor` | `keyphrases` | 抽取若干关键短语 |
| `TitleExtractorPrompt` | `title` | 抽取文档标题 |
| `NERPrompt` | `entities` | 抽取命名实体 |
| `TopicDescriptionExtractor` | `topic_description` | 抽取主题描述 |

资料来源：[src/ragas/testset/transforms/extractors/llm_based.py:1-200]()。每个抽取器都在 prompt 中给出 few-shot 示例，以保证输出稳定且结构符合 Pydantic schema。

### 3.3 节点过滤

`CustomNodeFilter` 是一个基于 LLM 评分的过滤器，它根据 `QuestionPotentialPrompt` 对节点打分（1–5），默认 `min_score=2`，低于阈值则被剔除，从而避免低信息密度片段进入合成阶段。资料来源：[src/ragas/testset/transforms/filters.py:1-80]()。

### 3.4 默认编排策略

`default_transforms()` 会先对文档做长度分桶统计；若长度超过 500 tokens 的文档占比 ≥ 25%，则启用 `HeadlinesExtractor` 等更重的变换；否则退化为更轻量的链路。资料来源：[src/ragas/testset/transforms/default.py:1-80]()。这一自适应策略可以在长文档与小文档场景之间自动切换，节省 token 成本。

## 4. 合成器与单跳问题生成

`generate()` 是 `TestsetGenerator` 的主入口，负责把文档切片、套用 transforms，再驱动合成器产生最终 `Testset`。其签名支持自定义 `testset_size`、`query_distribution`、`num_personas`、`callbacks`、`token_usage_parser` 等。资料来源：[src/ragas/testset/synthesizers/generate.py:60-180]()。

单跳（single-hop）合成器的 prompt 以 `QueryCondition`（persona、term、query_style、query_length、context）为输入，以 `GeneratedQueryAnswer` 为结构化输出，并要求答案内容**只能来自提供的上下文**。资料来源：[src/ragas/testset/synthesizers/single_hop/prompts.py:1-60]()。

## 5. 提示词与后端存储

### 5.1 Pydantic 提示词序列化

`PydanticPrompt` 是所有 LLM 提示词的基类，支持 JSON（含 `.json.gz`）持久化，便于跨环境复用。基础格式由 `format_version`、`type`、`instruction`、`examples`、`response_model_info` 组成；动态 few-shot 形态（`DynamicFewShotPrompt`）额外保存嵌入模型与相似度阈值。资料来源：[src/ragas/prompt/prompt-formats.md:1-80]()。

### 5.2 实验与数据集命名

后端工具模块提供 `MemorableNames` 类，用于为每次实验 / 数据集生成"Docker 风格"的形容词+名词组合标识（admiring_heisenbug 等），避免在保存测试集时发生命名冲突。资料来源：[src/ragas/backends/utils.py:1-60]()。

### 5.3 LLM 适配器

为支持多种推理后端，Ragas 在 `ragas.llms.adapters.base` 中定义了 `StructuredOutputAdapter` 抽象类，约定所有适配器必须实现 `create_llm(client, model, provider, **kwargs)`，从而把 Instructor / LiteLLM 等后端的差异收敛在统一的工厂方法中。资料来源：[src/ragas/llms/adapters/base.py:1-40]()。

## 6. 常见问题与边界情况

- **缺少 `headlines` 属性的报错**：当文档过短、未触发 `HeadlinesExtractor` 而下游又引用 `headlines` 时会抛出 `'headlines' property not found in this node`。这正是 issue #1775 报告的根因，需保证文档达到 `default_transforms()` 触发抽取的最小长度。资料来源：[src/ragas/testset/transforms/default.py:1-80]()。
- **非英文文本生成异常**：非英文语境下抽取器仍按英文 prompt 工作，可能产生空抽取；建议在合成前显式传入自定义 `transforms_llm` 与多语言 prompt。
- **`StringIO` 缺少 `classifications` 字段**：issue #1688 反映出旧版 prompt schema 兼容问题，建议升级到与最新 `PydanticPrompt` schema 对齐的版本。资料来源：[src/ragas/prompt/pydantic_prompt.py:1-60]()。

## 7. See Also

- 评估指标与数据模式：[`src/ragas/dataset_schema`](https://github.com/vibrantlabsai/ragas/tree/main/src/ragas/dataset_schema)
- LLM 适配与成本追踪：[`src/ragas/llms`](https://github.com/vibrantlabsai/ragas/tree/main/src/ragas/llms)
- LangChain 集成与 LangSmith 评估：[`src/ragas/integrations/langchain.py`](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/integrations/langchain.py)

---

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

## LLM 集成、适配器、提示词优化与成本追踪

### 相关页面

相关主题：[Ragas 项目概述与快速入门](#page-1), [评估指标系统（Metrics）](#page-2), [测试集生成、数据模式与后端存储](#page-3)

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

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

- [src/ragas/llms/__init__.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/__init__.py)
- [src/ragas/llms/base.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/base.py)
- [src/ragas/llms/adapters/base.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/adapters/base.py)
- [src/ragas/llms/adapters/instructor.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/adapters/instructor.py)
- [src/ragas/llms/adapters/litellm.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/adapters/litellm.py)
- [src/ragas/llms/litellm_llm.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/litellm_llm.py)
- [src/ragas/prompt/pydantic_prompt.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/pydantic_prompt.py)
- [src/ragas/prompt/multi_modal_prompt.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/multi_modal_prompt.py)
- [src/ragas/testset/synthesizers/generate.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/testset/synthesizers/generate.py)
- [README.md](https://github.com/vibrantlabsai/ragas/blob/main/README.md)

</details>

# LLM 集成、适配器、提示词优化与成本追踪

## 概述与设计目标

Ragas 在 LLM 集成层面采取「适配器 + 工厂」的模式，使任何兼容 OpenAI 接口、或支持 Instructor/LiteLLM 后端的客户端都能被无缝接入评估与测试集生成流程。根据 [README.md](https://github.com/vibrantlabsai/ragas/blob/main/README.md) 的 Quickstart 示例，标准用法是先构造原生客户端（如 `openai.AsyncOpenAI`），再调用 `ragas.llms.llm_factory("gpt-4o", client=client)` 获得一个 Ragas 兼容的 LLM 对象。`llm_factory` 在 [src/ragas/llms/__init__.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/__init__.py) 中暴露，并负责根据传入的客户端类型选择合适的适配器（Adapter）。

该设计的核心目标有三：

1. **供应商中立**：同一份指标代码（如 `DiscreteMetric.ascore`）可以跑在 OpenAI、Anthropic、Mistral、本地 vLLM 等多种后端之上，无需修改业务代码。
2. **结构化输出可控**：通过 Pydantic 模型驱动 Instructor 后端，保证 LLM 返回符合 JSON Schema 的结果。
3. **可观测性闭环**：内置 `CostCallbackHandler` 与 `TokenUsageParser`，为 CI/CD 中的成本闸门（cost gate）提供数据来源（参见社区讨论 [#540](https://github.com/vibrantlabsai/ragas/issues/540) 关于 token 用量追踪的需求）。

## 适配器体系架构

`src/ragas/llms/adapters/base.py` 定义了所有适配器的抽象基类 `BaseAdapter`，其职责是接收原始 LLM 客户端并生成符合 `BaseRagasLLM` 契约的对象；`src/ragas/llms/base.py` 中的 `BaseRagasLLM` 与 `InstructorBaseRagasLLM` 则负责提供统一的 `generate`、`agenerate`、`generate_text` 接口。两条最常用的实现路径是 Instructor 与 LiteLLM：

| 适配器 | 后端实现 | 典型场景 | 关键源文件 |
|--------|---------|---------|-----------|
| Instructor | `instructor` 库 + Pydantic 解析 | 需要强结构化输出（指标评分、生成样本） | [adapters/instructor.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/adapters/instructor.py) |
| LiteLLM | `litellm` 路由层 | 跨多供应商、需要 OpenAI 兼容代理 | [adapters/litellm.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/adapters/litellm.py), [litellm_llm.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/llms/litellm_llm.py) |
| LangChain Wrapper | 历史兼容层 | 已有 LangChain 应用 | [src/ragas/integrations/langchain.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/integrations/langchain.py) |

```mermaid
flowchart LR
    A[User Code / Metric] --> B[llm_factory]
    B --> C{Adapter Selection}
    C -->|OpenAI client| D[Instructor Adapter]
    C -->|litellm-style| E[LiteLLM Adapter]
    C -->|LangChain| F[LangchainLLMWrapper]
    D --> G[BaseRagasLLM / InstructorBaseRagasLLM]
    E --> G
    F --> G
    G --> H[Structured Generation + CostCallbackHandler]
    H --> I[TokenUsage / EvaluationResult]
```

适配器选择的逻辑在 `llm_factory` 中通过类型嗅探实现；当传入 `mistralai.Mistral` 等未被识别的客户端类型时，会抛出 `ValueError`（参见社区 issue [#2774](https://github.com/vibrantlabsai/ragas/issues/2774)）。在该 issue 被修复前，最稳妥的做法是使用 LiteLLM 适配器作为统一接入点。

## 提示词工程与优化

Ragas 的提示词抽象统一在 `BasePrompt` / `PydanticPrompt` 之下（见 [src/ragas/prompt/pydantic_prompt.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/pydantic_prompt.py)）。每条提示词包含 `instruction`、`examples`、`response_model_info` 三段，并遵循 `prompt-formats.md` 中规定的 v1.0 序列化格式，便于跨版本兼容与磁盘缓存。多模态扩展由 [src/ragas/prompt/multi_modal_prompt.py](https://github.com/vibrantlabsai/ragas/blob/main/src/ragas/prompt/multi_modal_prompt.py) 提供，文件内显式限制了允许的 URL 协议（仅 `http`/`https`）以及最大下载尺寸，作为安全策略的一部分。

在 v0.4.3 版本中，Ragas 引入了 `DSPyOptimizer`（基于 MIPROv2），见 [release notes](https://github.com/vibrantlabsai/ragas/releases/tag/v0.4.3)。该优化器以 DSPy 模块的形式对评估与生成所用的提示词进行自动微调：在小批量验证集上反复采样、评分，再用 MIPROv2 的 Bayesian 优化更新 `instruction` 字段，最终将优化后的提示词热加载回 `BaseRagasLLM`。同时版本还加入了 `dspy caching`，避免重复优化时的开销。用户在迁移时应注意：

- 优化前需准备好带 ground-truth 的小批样本；
- 优化目标与评估指标（如 `faithfulness`）必须一致，否则会出现"提示词变好、指标却下降"的反直觉现象；
- v0.4 仍在收尾阶段，社区正在征集 Testset Generation 的反馈（参见 issue [#2231](https://github.com/vibrantlabsai/ragas/issues/2231)），优化策略可能随之调整。

## 成本追踪、Token 使用与常见故障

`CostCallbackHandler` 借助 `TokenUsageParser` 解析不同供应商的响应元数据，输出统一的 `TokenUsage` 对象。然而，社区已记录多个供应商解析的 Bug，例如 issue [#2779](https://github.com/vibrantlabsai/ragas/issues/2779) 指出 `get_token_usage_for_bedrock` 读取了错误的 `response_metadata` 键，导致 `ChatBedrock`/`ChatBedrockConverse` 始终返回 0。临时绕过方案：自行实现 `TokenUsageParser`，读取 `usage.inputTokens` / `usage.outputTokens` 并包装为回调。其它被频繁报告的问题包括：

- **自定义评估模型兼容性**：`AspectCritic` 在切换到 `o3` 时出现运行时报错（[#2067](https://github.com/vibrantlabsai/ragas/issues/2067)），需要确认目标模型是否支持 `tool_choice` 与 JSON 模式。
- **依赖体积**：`diskcache` 被报告为可内联导入却仍被默认安装（[#2622](https://github.com/vibrantlabsai/ragas/issues/2622)），建议在精简镜像中通过 `pip install ragas --no-deps` 后按需补齐。
- **指标阈值不一致**：`NonLLMContextRecall` 与 `NonLLMContextPrecisionWithReference` 在阈值判定上使用 `>` 与 `>=` 不统一（[#2777](https://github.com/vibrantlabsai/ragas/issues/2777)），CI 场景下应固定到一侧。
- **测试集生成错误**：非英文文档触发 `'headlines' property not found in this node`（[#1775](https://github.com/vibrantlabsai/ragas/issues/1775)），根因通常是 `default_transforms` 中 `HeadlinesExtractor` 未能在小段落上产出标题，可通过自定义 `transforms` 列表或增大 `min_num_tokens` 阈值规避。

## See Also

- 评估指标与 `EvaluationResult` 摘要：社区提议的 `summary()` / `check_thresholds()` 公共方法（[#2760](https://github.com/vibrantlabsai/ragas/issues/2760)）
- 弃用警告修正：`LLMContextPrecisionWithoutReference` 类名错误（[#2748](https://github.com/vibrantlabsai/ragas/issues/2748)）
- 多语言评估数据集贡献：English/Uzbek 双语 RAG 评测（[#2649](https://github.com/vibrantlabsai/ragas/issues/2649)）
- RAG 安全评估：AgentThreatBench 内存投毒任务（[#2732](https://github.com/vibrantlabsai/ragas/issues/2732)）
- 测试集生成模块未来方向：[#2231](https://github.com/vibrantlabsai/ragas/issues/2231)
- OpenAI Batch API 支持请求：[#1521](https://github.com/vibrantlabsai/ragas/issues/1521)

---

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

---

## Doramagic 踩坑日志

项目：vibrantlabsai/ragas

摘要：发现 22 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add EvaluationResult summary and threshold checks。

## 1. 安装坑 · 来源证据：Add EvaluationResult summary and threshold checks

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add EvaluationResult summary and threshold checks
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2760 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：Incorrect class name in deprecation warning for LLMContextPrecisionWithoutReference

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Incorrect class name in deprecation warning for LLMContextPrecisionWithoutReference
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2748 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：No module named 'langchain_community.chat_models.vertexai'

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：No module named 'langchain_community.chat_models.vertexai'
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2741 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：ragas 0.4.3: ChatVertexAI import broken — uses removed langchain_community path

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ragas 0.4.3: ChatVertexAI import broken — uses removed langchain_community path
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2745 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 配置坑 · 来源证据：answer_correctness is not working as expected

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：answer_correctness is not working as expected
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2585 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 6. 配置坑 · 来源证据：faithfulness_score: nan

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

## 7. 配置坑 · 来源证据：llm_factory raises ValueError when using mistralai client

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：llm_factory raises ValueError when using mistralai client
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2774 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 8. 安全/权限坑 · 来源证据：AspectCritic not working with openai o3

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

## 9. 安全/权限坑 · 来源证据：Feature request: Add AgentThreatBench memory poison task as a RAG security evaluation

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature request: Add AgentThreatBench memory poison task as a RAG security evaluation
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2732 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 安全/权限坑 · 来源证据：Make python-diskcache dependency optional

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Make python-diskcache dependency optional
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2622 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 11. 安全/权限坑 · 来源证据：No persona found with name : Documentation example doesn't work with minimal changes

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：No persona found with name : Documentation example doesn't work with minimal changes
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2047 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 12. 安全/权限坑 · 来源证据：Proposal: Contribute English/Uzbek Multilingual RAG Evaluation Dataset to RAGAS

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Proposal: Contribute English/Uzbek Multilingual RAG Evaluation Dataset to RAGAS
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2649 | 来源类型 github_issue 暴露的待验证使用条件。

## 13. 安全/权限坑 · 来源证据：[Security] Agentic Workflow Injection in Claude Docs Check

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Security] Agentic Workflow Injection in Claude Docs Check
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2692 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 14. 安全/权限坑 · 来源证据：get_token_usage_for_bedrock always returns 0 (reads wrong response_metadata keys for langchain-aws ChatBedrock/ChatBedr…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：get_token_usage_for_bedrock always returns 0 (reads wrong response_metadata keys for langchain-aws ChatBedrock/ChatBedrockConverse)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2779 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 15. 配置坑 · 来源证据：EmbeddingUsageEvent telemetry NaNs a metric when embeddings expose a non-string .model (e.g. fastembed)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：EmbeddingUsageEvent telemetry NaNs a metric when embeddings expose a non-string .model (e.g. fastembed)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2783 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

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

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

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

## 20. 安全/权限坑 · 来源证据：TypeError: unsupported operand type(s) for += on dict when using LangchainLLMWrapper with evaluate() in 0.4.3

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TypeError: unsupported operand type(s) for += on dict when using LangchainLLMWrapper with evaluate() in 0.4.3
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/vibrantlabsai/ragas/issues/2790 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

<!-- canonical_name: vibrantlabsai/ragas; human_manual_source: deepwiki_human_wiki -->