Haystack 中的 RagasEvaluator使用 Ragas 框架评估 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/haystackRagasEvaluator 是 Haystack 对 Ragas 评估框架的原生集成组件用于以 LLM 驱动的指标如忠实度、答案相关性、上下文精确率等对检索增强生成RAG管线进行端到端评估。本文基于 Haystack 2.22 版本的相关文档完整讲解该组件的安装、初始化、序列化、同步/异步运行以及将其接入评估管线的实战方案并辅以仓库源码与配套文档佐证帮助你用可复现的方式度量 RAG 系统的质量。Ragas 与 Haystack 集成概览Ragas 是一个提供多种基于 LLM 的评估指标的评估框架。你可以使用RagasEvaluator组件评估一条 Haystack 管线例如检索增强生成管线在 Ragas 提供的某一项或多项指标上的表现。该组件位于独立的集成包ragas-haystack中导入路径为haystack_integrations.components.evaluators.ragas.evaluator从文档定位看它在管线中最常见的位置是独立运行或位于一条专门的评估管线中通常放在另一条管线生成评估输入之后使用参见 docs-website/versioned_docs/version-2.22/pipeline-components/evaluators/ragasevaluator.mdx。Haystack 官方的评估指南中也将其与 DeepEval 一起列为两大评估框架集成之一。组件在 Haystack 评估体系中的定位Haystack 的评估体系分为两条路线详见 model-based-evaluation.mdx基于模型的评估Model-based Evaluation用 LLM 或小型微调模型对管线输出打分通常不需要标签。RagasEvaluator属于这一类。统计评估Statistical Evaluation基于地面真值标签计算精确率、召回率等指标例如 Haystack 自带的 DocumentRecallEvaluator、DocumentMRREvaluator 等详见 statistical-evaluation.mdx。Haystack 核心库自带的 Evaluator 组件见 haystack/components/evaluators/init.py包括AnswerExactMatchEvaluator、ContextRelevanceEvaluator、FaithfulnessEvaluator、LLMEvaluator、SASEvaluator等而 Ragas 与 DeepEval 属于外部框架集成。在 v2.22 版本的评估对比表中见 model-based-evaluation.mdxRagasEvaluator 的定位如下支持的评估模型OpenAI 全系 GPT 模型、Google VertexAI 模型、Azure OpenAI 模型、Amazon Bedrock 模型支持的指标ANSWER_CORRECTNESS、FAITHFULNESS、ANSWER_SIMILARITY、CONTEXT_PRECISION、CONTEXT_UTILIZATION、CONTEXT_RECALL、ASPECT_CRITIQUE、CONTEXT_RELEVANCY、ANSWER_RELEVANCY自定义提示词支持可通过ASPECT_CRITIQUE指标实现自定义评估维度。安装与前置条件pip install ragas-haystack使用前请注意以下前提Ragas 的多数指标依赖 OpenAI 模型需要设置环境变量OPENAI_API_KEY指标对象在构造时就必须完整配置好其 LLM以及按需的 embedding 模型该组件支持 Ragas 的现代指标 APIragas.metrics.collections每个指标必须是SimpleBaseMetric实例。初始化 RagasEvaluator构造函数签名__init__( ragas_metrics: list[SimpleBaseMetric], concurrency_limit: int 4 ) - None参数说明ragas_metricslist[SimpleBaseMetric]来自ragas.metrics.collections的现代 Ragas 指标列表。每个指标必须在构造时完成完整配置包括其 LLM。可用指标的完整清单见 Ragas 官方文档的 available metrics 页面。concurrency_limitint默认4允许并发运行的指标评估任务的最大数量。该参数仅在run_async方法中生效。快速开始示例参考 API 参考文档ragas.md中的用法示例一个最小可用的忠实度评估如下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, clientclient) evaluator RagasEvaluator( ragas_metrics[Faithfulness(llmllm)], ) output evaluator.run( queryWhich is the most popular global sport?, documents[ Football is undoubtedly the worlds 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. ], referenceFootball is the most popular sport with around 4 billion followers worldwide, ) output[result]这个示例揭示了两个关键点LLM 通过llm_factory创建Ragas 的llm_factory负责根据模型名和客户端构造 LLM 实例这里使用了AsyncOpenAI客户端说明评估过程走的是异步 OpenAI 接口指标在构造时绑定 LLMFaithfulness(llmllm)在构造时即完成配置组件不再负责创建或替换指标内部的 LLM。需要 embedding 的指标部分指标如AnswerRelevancy除了 LLM 之外还需要 embedding 模型。参考当前版本文档docs/pipeline-components/evaluators/ragasevaluator.mdx中的示例需要额外通过embedding_factory配置from ragas.embeddings import embedding_factory from ragas.metrics.collections import AnswerRelevancy embeddings embedding_factory(openai, modeltext-embedding-3-small, clientclient) metric AnswerRelevancy(llmllm, embeddingsembeddings)因此在初始化之前务必确认所选指标需要哪些依赖LLM 与/或 embedding并将其一次性配置完整。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]]run_async的签名与run完全一致区别在于以异步方式执行评估并通过concurrency_limit控制指标评估的并发度。输入参数详解参数类型说明querystr \| None用户输入的问题responselist[ChatMessage] \| str \| None模型或 Agent 生成的回答ChatMessage 列表或字符串documentslist[Document \| str] \| None为查询检索到的 Haystack Document 或字符串列表reference_contextslist[str] \| None本应被检索到的参考上下文列表multi_responseslist[str] \| None为查询生成的多个回答referencestr \| None查询的参考标准答案rubricsdict[str, str] \| None评估评分标准字典键为分数值为对应的评估准则并非所有参数都会被每个指标用到——不同指标只消费其中一部分输入。例如Faithfulness忠实度主要使用query、documents、response判断回答是否可依据检索文档得出AnswerRelevancy答案相关性主要使用query与responseContextPrecision / ContextRecall还需要reference或reference_contexts作为对照AspectCritique方面评判可接受自定义rubrics来定义评估维度与打分标准。返回值方法返回dict[str, dict[str, MetricResult]]字典键为result其值是一个将指标名称映射到MetricResult的字典。每个MetricResult携带指标名与分数供你在评估报告中直接读取。同步 vs 异步的选择需要将评估结果接入既有同步管线时使用run需要高吞吐批量评估、或希望并发执行多个指标评估时使用run_async并结合concurrency_limit控制并发上限避免一次性打满模型服务的速率限制。to_dict 与 from_dict序列化与反序列化与 Haystack 的标准组件一样RagasEvaluator实现了to_dict/from_dict以支持管线的保存与加载。to_dictto_dict() - dict[str, Any]将组件序列化为字典返回包含序列化数据的dict[str, Any]。序列化后的字典可以在后续通过from_dict或Pipeline.load恢复组件。from_dictfrom_dict(data: dict[str, Any]) - RagasEvaluator从字典反序列化组件。指标会依据其存储的类路径以及 LLM/embedding 配置被重建。反序列化的自动支持目前仅限openaiproviderAPI 密钥在加载时从OPENAI_API_KEY环境变量读取。反序列化白名单haystack-ai 3.0当haystack-ai版本 3.0 时指标类所在的模块必须位于反序列化白名单上Ragas 自带的指标自动受信任自定义指标类例如来自你自己的包需要显式信任例如Pipeline.load(..., allowed_modules[mypackage.*])若指标类不在白名单中from_dict会抛出DeserializationError。在管线中使用 RagasEvaluator完整实战参考 v2.22 文档ragasevaluator.mdx中的示例RagasEvaluator 可以像普通组件一样被加入Pipeline。示例一单指标评估答案相关性v2.22 文档中的上下文相关性示例采用RagasMetric.ANSWER_RELEVANCY枚举写法旧版 API而当前版本则推荐直接传入配置好的指标实例。以下是 v2.22 文档中的管线搭建方式from haystack import Pipeline from haystack_integrations.components.evaluators.ragas import ( RagasEvaluator, RagasMetric, ) pipeline Pipeline() evaluator RagasEvaluator( metricRagasMetric.ANSWER_RELEVANCY, ) pipeline.add_component(evaluator, evaluator)运行评估管线时需要准备好该指标所期望的输入来自被评估管线的运行结果results pipeline.run( { evaluator: { questions: [ When was the Rhodes Statue built?, Where is the Pyramid of Giza?, ], contexts: [[Context for question 1], [Context for question 2]], }, }, )注意v2.22 版本的文档与 API 参考文档存在 API 差异——前者仍展示基于RagasMetric枚举 metric_params的旧式接口后者则展示基于ragas.metrics.collectionsSimpleBaseMetric的新式接口。实际使用时应以你安装的ragas-haystack版本对应的 API 为准。示例二多指标联合评估上下文精确率 方面评判v2.22 文档展示了同时评估上下文精确率Context Precision与自定义方面评判Aspect Critique的管线。方面评判支持通过metric_params自定义名称、定义与严格度from haystack import Pipeline from haystack_integrations.components.evaluators.ragas import ( RagasEvaluator, RagasMetric, ) pipeline Pipeline() evaluator_context RagasEvaluator( metricRagasMetric.CONTEXT_PRECISION, ) evaluator_aspect RagasEvaluator( metricRagasMetric.ASPECT_CRITIQUE, metric_params{ name: custom, definition: Is this answer problematic for children?, strictness: 3, }, ) pipeline.add_component(evaluator_context, evaluator_context) pipeline.add_component(evaluator_aspect, evaluator_aspect)运行两条评估分支时为每个组件分别提供其所需输入QUESTIONS [ Which is the most popular global sport?, Who created the Python language?, ] CONTEXTS [ [ 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 worlds 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., ], [ Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming language. Its design philosophy emphasizes code readability, and its language constructs aim to help programmers write clear, logical code for both small and large-scale software projects., ], ] RESPONSES [ Football is the most popular sport with around 4 billion followers worldwide, Python language was created by Guido van Rossum., ] GROUND_TRUTHS [ Football is the most popular sport, Python language was created by Guido van Rossum., ] results pipeline.run( { evaluator_context: { questions: QUESTIONS, contexts: CONTEXTS, ground_truths: GROUND_TRUTHS, }, evaluator_aspect: { questions: QUESTIONS, contexts: CONTEXTS, responses: RESPONSES, }, }, )示例三新式 API 的多指标管线上下文精确率 忠实度若你使用的是支持现代 Ragas 指标 API 的版本推荐直接传入配置完整的指标实例一次评估多个指标参见 docs/pipeline-components/evaluators/ragasevaluator.mdxfrom 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, clientclient) pipeline Pipeline() evaluator RagasEvaluator( ragas_metrics[ContextPrecision(llmllm), Faithfulness(llmllm)], ) pipeline.add_component(evaluator, evaluator)运行并传入所有指标所需的组合输入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 worlds 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, }, }, )与 Haystack 内置评估器的对比与选型Haystack 核心库自带基于 LLM 的FaithfulnessEvaluator与SASEvaluator见 haystack/components/evaluators/faithfulness.py 与 haystack/components/evaluators/sas_evaluator.py它们与 Ragas 集成各有适用场景FaithfulnessEvaluator内置将回答拆分为多条陈述逐条判断能否从上下文中推出最终分数为 0.01.0 的陈述可推断比例见 faithfulness.py。适合只需要忠实度单一指标的轻量场景无需引入额外框架。SASEvaluator内置基于 transformer 交叉编码器计算两个回答的语义相似度不依赖外部模型提供方 API key更快更便宜但只能评估训练过的维度见 model-based-evaluation.mdx。RagasEvaluator集成覆盖指标面最广忠实度、答案相关性、上下文精确率/召回率/利用率、答案正确性、答案相似度、自定义方面评判等支持 OpenAI、VertexAI、Azure OpenAI、Bedrock 等多家模型提供方且ASPECT_CRITIQUE支持自定义评估提示词。代价是需要安装独立包、配置指标内的 LLM/embedding并注意反序列化白名单等约束。选型建议需要单一忠实度指标且希望轻量实现时用内置FaithfulnessEvaluator需要快速廉价地衡量语义相似度时用SASEvaluator需要多维度、多提供方、可自定义提示词的全面评估时选择RagasEvaluator。常见问题与注意事项指标未配置 LLM 会怎样组件的核心约束是“每个指标必须在构造时完整配置 LLM”直接传入未配置的指标实例会导致评估无法进行。务必通过llm_factory必要时再加embedding_factory先构造好依赖再传给RagasEvaluator。OPENAI_API_KEY何时需要多数指标使用 OpenAI 模型且from_dict反序列化时也会从OPENAI_API_KEY读取 API 密钥。运行与加载前都要确保该变量已设置。concurrency_limit为什么只在run_async生效并发控制针对异步调度场景同步run不涉及并发调度因此该参数不影响同步执行。反序列化报DeserializationError检查你的自定义指标类模块是否在反序列化白名单中并通过Pipeline.load(..., allowed_modules[mypackage.*])显式放行。Ragas 自带的指标类自动受信任。输入与指标不匹配不同指标消费不同的输入字段请根据指标需求提供query、response、documents、reference、reference_contexts、rubrics等字段的组合多余字段会被忽略。小结RagasEvaluator让 Haystack 用户以极小的接入成本获得 Ragas 全套 LLM 评估指标构造时配置好指标的 LLM与 embedding即可在独立评估管线或主管线末端对 RAG 输出进行同步或异步评估。配合to_dict/from_dict的序列化能力与concurrency_limit的并发控制它既能融入标准 Haystack 开发流程也能支撑批量、并发的评估任务。相关 API 细节可继续查阅 version-2.22 的 API 参考 与组件使用指南以及基于模型的评估总览。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考