Haystack × Ragas 集成指南：用 RagasEvaluator 构建 LLM 驱动的 RAG 质量评估-平芜编程栈

Haystack × Ragas 集成指南：用 RagasEvaluator 构建 LLM 驱动的 RAG 质量评估

【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack

Ragas 是一个基于 LLM 的 RAG 评估框架，提供 Faithfulness、AnswerRelevancy、ContextPrecision 等一系列开箱即用的生成式评估指标。Haystack 通过ragas-haystack集成包将 Ragas 封装为标准的 Pipeline 组件RagasEvaluator，使你能够直接在 Haystack 的评估 Pipeline 中复用 Ragas 的全部现代指标 API。读完本文，你将掌握该组件的安装配置、全部构造参数与运行参数、同步/异步两种评估调用方式、多指标并行评估的 Pipeline 实战写法，以及组件序列化时的安全反序列化规则。

为什么需要 RagasEvaluator：把 Ragas 指标搬进 Haystack Pipeline

Haystack 将"基于模型评估"（Model-Based Evaluation）分为两类：一类是内置的 LLM 评估器（如 FaithfulnessEvaluator、ContextRelevanceEvaluator），另一类是与第三方评估框架的集成。目前 Haystack 官方集成了 DeepEval 与 Ragas 两大框架，其中 Ragas 的接入组件就是RagasEvaluator（见 Evaluators 总览）。

RagasEvaluator的定位很明确：它不关心你的 RAG Pipeline 内部如何取检索、如何做生成，而是接收 RAG Pipeline 产出的输入（query、documents、response 等），用 Ragas 指标对"检索质量 + 生成质量"做一次整体打分。在 Haystack 中，你既可以把评估 Pipeline 与 RAG Pipeline 分离（先存下 RAG 结果、再反复换指标评估，不必每次重跑 RAG），也可以把评估器挂在 RAG Pipeline 末尾一次pipeline.run()跑完——这两种编排方式在 model-based-evaluation.mdx 中有详细说明，而RagasEvaluator同时适用于这两种形态。

安装与前置准备

RagasEvaluator不是 Haystack 核心库的一部分，需要单独安装集成包：

pip install ragas-haystack

该集成包同时依赖ragas框架本身。使用前还需注意两点环境前提：

OpenAI API Key：Ragas 指标在构造时需要配置 LLM（以及部分指标需要的 embedding 模型）。若使用 OpenAI 作为后端，需先设置OPENAI_API_KEY环境变量，反序列化场景下也会在加载时读取该变量。
Python 异步客户端：Ragas 的llm_factory接受 OpenAI 的AsyncOpenAI客户端，示例代码中统一通过from openai import AsyncOpenAI创建。

核心概念：现代 Ragas 指标 API 与 SimpleBaseMetric

RagasEvaluator只支持 Ragas 的现代指标 API（ragas.metrics.collections）。这意味着：

每个指标必须是SimpleBaseMetric的实例，例如Faithfulness、AnswerRelevancy、ContextPrecision、ContextRecall、AnswerCorrectness、SemanticSimilarity等；
每个指标必须在构造时完成完整配置——尤其是为它绑定 LLM（llm_factory创建），需要 embedding 的指标（如AnswerRelevancy）还要绑定 embedding 模型（embedding_factory创建）。

指标的 LLM/embedding 配置不依赖 Haystack 组件，而是直接走 Ragas 自身的工厂函数：

from openai import AsyncOpenAI from ragas.llms import llm_factory from ragas.embeddings import embedding_factory client = AsyncOpenAI() llm = llm_factory("gpt-4o-mini", client=client) embeddings = embedding_factory("openai", model="text-embedding-3-small", client=client)

RagasEvaluator 构造参数

根据 RagasEvaluator API 参考与使用指南，构造签名如下：

__init__(ragas_metrics: list[SimpleBaseMetric], concurrency_limit: int = 4) -> None

参数	类型	必填	说明
`ragas_metrics`	`list[SimpleBaseMetric]`	是	来自`ragas.metrics.collections`的现代 Ragas 指标列表，每个指标必须在构造时完成完整配置（含其 LLM，必要时含 embeddings）
`concurrency_limit`	`int`	否，默认`4`	允许同时运行的指标评估任务的最大并发数，仅在`run_async`异步方法中生效

在 Pipeline 中的典型位置是"单独运行"或"评估 Pipeline 的末尾"，即先由独立的 RAG Pipeline 生成评估输入，再接评估器打分（组件定位说明见 ragasevaluator.mdx）。

run 与 run_async：输入参数与返回结构

RagasEvaluator提供同步run与异步run_async两个入口，两者签名完全一致：

run( query: str | None = None, response: list[ChatMessage] | str | None = None, documents: list[Document | str] | None = None, reference_contexts: list[str] | None = None, multi_responses: list[str] | None = None, reference: str | None = None, rubrics: dict[str, str] | None = None, ) -> dict[str, dict[str, MetricResult]]

各输入参数的含义与适用指标

参数	类型	说明
`query`	`str \\| None`	用户的输入查询，评估 RAG 管线时即原始问题
`response`	`list[ChatMessage] \\| str \\| None`	语言模型或 Agent 生成的回答。可以是字符串，也可以是 Haystack 的`ChatMessage`列表（直接承接生成组件的输出）
`documents`	`list[Document \\| str] \\| None`	针对该查询检索到的文档列表，接受 Haystack`Document`对象或纯字符串
`reference_contexts`	`list[str] \\| None`	本应被检索到的参考上下文列表（评估检索覆盖度时使用）
`multi_responses`	`list[str] \\| None`	针对该查询生成的多个候选回答
`reference`	`str \\| None`	查询的参考答案（ground truth），用于需要参考答案的指标
`rubrics`	`dict[str, str] \\| None`	评估评分细则，键为分值、值为对应的评分标准描述，用于基于 rubric 的指标（如`DomainSpecificRubrics`）

需要特别说明的是：并非所有指标都需要全部参数。具体传入哪些输入，取决于你选择了哪些指标——不同指标对输入的要求不同（这正是"Mandatory run variables"随指标变化的原因）。例如AnswerRelevancy需要query与response，而ContextPrecision/Faithfulness组合需要query、documents、response与reference。

返回值结构

返回值是一个字典，其键固定为result，值为"指标名 →MetricResult"的映射：

{"result": {"Faithfulness": MetricResult, "ContextPrecision": MetricResult, ...}}

同步与异步的选择

run：同步执行所有指标评估；
run_async：异步执行，多个指标的评估任务最多以concurrency_limit（默认 4）并发运行，适合单次评估包含多个指标、希望缩短总耗时的场景。

实战：四个可直接运行的评估示例

以下示例均来自 ragasevaluator.mdx 及 API 参考（OPENAI_API_KEY必须已设置）。

示例 1：直接调用，评估 Faithfulness（忠实度）

from openai import AsyncOpenAI from ragas.llms import llm_factory from ragas.metrics.collections import Faithfulness from haystack_integrations.components.evaluators.ragas import RagasEvaluator client = AsyncOpenAI() llm = llm_factory("gpt-4o-mini", client=client) evaluator = RagasEvaluator( ragas_metrics=[Faithfulness(llm=llm)], ) output = evaluator.run( query="Which is the most popular global sport?", documents=[ "Football is undoubtedly the world's most popular sport with" " major events like the FIFA World Cup and sports personalities" " like Ronaldo and Messi, drawing a followership of more than 4" " billion people." ], reference="Football is the most popular sport with around 4 billion" " followers worldwide", ) output['result']

这是最简单的用法：不搭建 Pipeline，直接实例化RagasEvaluator并调用run，适合快速验证指标配置或做单点评估。

示例 2：Pipeline 化评估 AnswerRelevancy（回答相关性）

AnswerRelevancy需要 LLM + embeddings 双配置，指标构造时通过embedding_factory绑定 embedding 模型：

from haystack import Pipeline from haystack_integrations.components.evaluators.ragas import RagasEvaluator from openai import AsyncOpenAI from ragas.llms import llm_factory from ragas.embeddings import embedding_factory from ragas.metrics.collections import AnswerRelevancy client = AsyncOpenAI() llm = llm_factory("gpt-4o-mini", client=client) embeddings = embedding_factory("openai", model="text-embedding-3-small", client=client) pipeline = Pipeline() evaluator = RagasEvaluator( ragas_metrics=[AnswerRelevancy(llm=llm, embeddings=embeddings)], ) pipeline.add_component("evaluator", evaluator)

该指标期望query与response两个输入，运行时通过 Pipeline 输入字典传入：

results = pipeline.run( { "evaluator": { "query": "Where is the Pyramid of Giza?", "response": "The Pyramid of Giza is located in Egypt.", }, }, )

示例 3：多指标并行评估 ContextPrecision + Faithfulness

多个指标在同一个ragas_metrics列表中一次性传入，Ragas 会分别计算各指标得分：

from haystack import Pipeline from haystack_integrations.components.evaluators.ragas import RagasEvaluator from openai import AsyncOpenAI from ragas.llms import llm_factory from ragas.metrics.collections import ContextPrecision, Faithfulness client = AsyncOpenAI() llm = llm_factory("gpt-4o-mini", client=client) pipeline = Pipeline() evaluator = RagasEvaluator( ragas_metrics=[ContextPrecision(llm=llm), Faithfulness(llm=llm)], ) pipeline.add_component("evaluator", evaluator)

运行时需提供两个指标所需的全部输入（取并集）：query、documents、response、reference：

results = pipeline.run( { "evaluator": { "query": "Which is the most popular global sport?", "documents": [ "The popularity of sports can be measured in various ways, including TV viewership, social media presence, number of participants, and economic impact. Football is undoubtedly the world's most popular sport with major events like the FIFA World Cup and sports personalities like Ronaldo and Messi, drawing a followership of more than 4 billion people." ], "response": "Football is the most popular sport with around 4 billion followers worldwide", "reference": "Football is the most popular sport", }, }, )

示例 4：端到端接入 RAG Pipeline

实际生产中最常见的形态是把RagasEvaluator挂到 RAG Pipeline 末端：让生成器输出的reply作为response、检索器输出的documents作为documents，与原始query一起送入评估器，在一次运行中完成"检索 → 生成 → 评估"的闭环。此时组件间通过 Pipeline 连接自动传递数据，评估输入参数即为各上游组件的对应输出槽位。

序列化与反序列化：to_dict / from_dict 与安全 allowlist

RagasEvaluator实现了 Haystack 的标准序列化协议，支持将组件（含已配置的指标）写入 YAML 字典并重新加载。

to_dict

to_dict() -> dict[str, Any]

将组件序列化为字典，指标以类路径 + LLM/embedding 配置的形式被存储。

from_dict 与反序列化安全机制

from_dict(data: dict[str, Any]) -> RagasEvaluator

反序列化时，指标根据存储的类路径重建，LLM/embedding 配置一并恢复。需要注意：

仅支持 OpenAI provider 的自动反序列化，API key 在加载时从OPENAI_API_KEY环境变量读取；
从haystack-ai >= 3.0开始，指标类所在的模块必须位于反序列化allowlist（白名单）上：Ragas 官方自带的指标会被自动信任，而自定义指标类需要显式放行，例如：

Pipeline.load(..., allowed_modules=["mypackage.*"])

若指标类不在 allowlist 上，from_dict会抛出DeserializationError。

这一机制在 Haystack 核心库的 haystack/core/serialization_security.py 中有完整的源码实现可印证：DEFAULT_ALLOWED_MODULES默认信任haystack、haystack_integrations、haystack_experimental、builtins、typing、collections等模块，而自定义包需通过三种途径之一扩展 allowlist——单次调用参数Pipeline.load(..., allowed_modules=[...])、进程级 APIallow_deserialization_module(...)、或环境变量HAYSTACK_DESERIALIZATION_ALLOWLIST；对完全可信的管线还可以用unsafe=True整体绕过。把自定义 Ragas 指标所在的包名（如mypackage.*）加入上述任一途径，即可安全地反序列化自研指标。

RagasEvaluator 与 DeepEvalEvaluator 选型对比

如果同时在评估两个框架，可以参考 model-based-evaluation.mdx 中的对比表做出选择：

特性	RagasEvaluator	DeepEvalEvaluator
评估模型	Ragas 支持的任何 provider（OpenAI、Anthropic、Google、Groq、Mistral 等），通过`ragas.llms.llm_factory`在每个指标上配置	OpenAI 全系 GPT 模型
支持指标	`ragas.metrics.collections`中的任意指标，如`Faithfulness`、`AnswerRelevancy`、`ContextPrecision`、`ContextRecall`、`AnswerCorrectness`、`SemanticSimilarity`	ANSWER_RELEVANCY、FAITHFULNESS、CONTEXTUAL_PRECISION、CONTEXTUAL_RECALL、CONTEXTUAL_RELEVANCE
响应评估 prompt 可定制	✅，基于 rubric 的指标（如`DomainSpecificRubrics`）支持	❌
分数解释	❌	✅
监控看板	❌	❌

核心差异一目了然：Ragas 的优势在于评估模型的 provider 覆盖面广、指标来自ragas.metrics.collections可自由组合，并支持 rubric 自定义评分细则；DeepEval 的优势在于对每个分数提供解释性输出。如果你的评估需求强依赖特定 LLM provider 或需要自定义评分标准，Ragas 路线更灵活；如果需要开箱即用的分数解释，则 DeepEval 更省事。

最佳实践与注意事项

指标务必在构造时配齐 LLM/embeddings：RagasEvaluator不会替你补配置，遗漏embeddings（如AnswerRelevancy）会在运行时报错。
按指标需求裁剪输入：传入多余参数不影响结果，但缺失某指标必需的参数会导致评估失败。多指标共用时，传入所有指标所需输入的并集（见示例 3）。
评估 Pipeline 与 RAG Pipeline 分离：Haystack 官方推荐先单独跑 RAG Pipeline 并保存结果，再在评估 Pipeline 中反复切换不同指标，避免为尝试新指标而重复执行昂贵的 RAG 流程（见 model-based-evaluation.mdx）。
多指标评估优先用run_async：concurrency_limit（默认 4）只在异步路径生效，指标数量较多时可显著缩短评估耗时。
自定义指标注意反序列化安全：反序列化自有指标类时，务必通过allowed_modules、allow_deserialization_module或HAYSTACK_DESERIALIZATION_ALLOWLIST显式放行其所在包，否则会触发DeserializationError。
环境变量前置：基于 OpenAI 的示例均依赖OPENAI_API_KEY，在脚本或 Notebook 中先完成配置再运行评估，反序列化场景下该变量同样在加载时被读取。