RAGAS 框架与实现原理写在前面学习 RAG 评测RAGAS 是绝对绕不开的主流框架。它基于LLM-as-a-Judge大模型当裁判的核心范式既解决了人工评测效率低、难规模化的问题又比传统关键词匹配的评测方式更懂语义是目前工业界 RAG 效果评估的标配工具。很多同学入门时会遇到两个痛点一是 RAGAS 版本迭代快网上教程的 API 很容易过时二是只知道指标名字搞不懂分数到底是怎么算出来的。这篇笔记就从整体流程、核心原理、可运行代码三个维度把 RAGAS 最核心的 5 个指标拆解清楚同时标注了新手容易踩的版本、稳定性等坑点跟着步骤就能跑通完整的 RAG 评测。一、RAGAS 整体评估流程RAGAS 的评估逻辑非常清晰是标准的「输入 - 处理 - 输出」三段式结构底层靠「大模型语义判断 向量相似度计算 数学统计」三者配合实现自动化评测。1. 输入数据源Input Data一次完整的评估最多需要 4 个核心元素根据不同指标按需传入Question用户问题用户提出的原始查询是所有评估的基准Context检索上下文RAG 系统从向量库中召回的文档片段对应检索环节的输出Answer生成答案大模型基于检索上下文生成的最终回答对应生成环节的输出Ground Truth标准答案人工标注的参考正确答案部分指标需要用到2. 评估处理引擎Evaluation Engine这是 RAGAS 的核心三个组件协同工作LLM 大模型负责语义层面的判断比如识别内容是否相关、拆解事实声明、检测幻觉Embedding 向量模型负责文本向量化计算语义相似度计算引擎负责执行 Precision、Recall、F1、MAP 等数学统计计算3. 输出评估指标Output Metrics最终输出 0~1 之间的量化分数分数越高代表质量越好。核心覆盖 5 个高频指标分别对应检索、生成、端到端三个环节后面我们会逐个拆解。二、环境准备新手必看・避坑前置重点提示RAGAS 版本差异非常大高版本 API 改动很多网上大部分教程的代码在最新版里都跑不通。教学和学习推荐锁定0.4.3 版本稳定性和资料丰富度都最好。1. 环境搭建步骤# 1. 创建并进入项目目录 mkdir ragas_demo cd ragas_demo # 2. 创建虚拟环境推荐用uvpip也可以 uv venv # 激活虚拟环境 # Linux/macOS source .venv/bin/activate # Windows .venv\Scripts\activate2. 依赖与配置创建requirements.txtragas0.4.3 openai1.0.0 python-dotenv1.0.0安装依赖uv pip install -r requirements.txt创建.env配置文件这里用阿里云通义千问的兼容 OpenAI 接口国内学生不用翻墙就能用OPENAI_API_KEYsk-你的API密钥 OPENAI_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1模型选择建议评估模型推荐用qwen3.6-plus实测比高版本的 qwen3.7-max 打分更稳定波动更小。三、5 个核心指标逐一带练1. Context Precision 上下文精准度是什么衡量检索系统的查准质量 排序质量核心看两件事召回的内容里有多少是真相关的以及相关的内容有没有排在更靠前的位置。它是检索环节的核心指标直接反映 “检索结果的信噪比高不高”。计算原理核心是Precisionk 加权平均公式逻辑对每个位置 k计算Precisionk 前k条中相关内容数 / k用每个位置的相关性标识v_k相关为 1不相关为 0做加权最终得分 所有相关位置的 Precisionk 之和 ÷ 总相关内容数 关键点内容顺序对得分影响极大。相关内容越靠前得分越高哪怕相关内容总数一样排在后面得分也会低很多。代码实战我们用 “北京故宫有哪些著名景点” 做示例故意混入一条无关内容importasyncioimportosfromopenaiimportAsyncOpenAIfromdotenvimportload_dotenvfromragas.llmsimportllm_factoryfromragas.metrics.collectionsimportContextPrecision load_dotenv()# 初始化大模型裁判openai_clientAsyncOpenAI(api_keyos.getenv(OPENAI_API_KEY))llmllm_factory(qwen3.6-plus,clientopenai_client,temperature0.1,# 调低温度让打分更稳定seed42# 固定种子结果可复现)scorerContextPrecision(llmllm)asyncdefmain():print( 上下文精准度评估 )resultawaitscorer.ascore(user_input北京故宫有哪些著名景点,reference北京故宫的著名景点包括太和殿、乾清宫、御花园和角楼。,retrieved_contexts[太和殿是故宫外朝的核心建筑也是中国现存最大的木结构大殿。,乾清宫是明清两代皇帝的寝宫位于故宫内廷。,御花园是故宫的皇家园林位于中轴线北端。,杭州西湖是中国著名的淡水湖有十景之称。# 无关干扰项])print(f得分{result.value:.4f})if__name____main__:asyncio.run(main())手动演算验证上面的例子中前 3 条相关、最后 1 条无关位置 k内容是否相关Precisionk1太和殿是1/1 1.02乾清宫是2/2 1.03御花园是3/3 1.04西湖否3/4 0.75分子加权和 1.0 1.0 1.0 3.0分母总相关数 3最终得分 3.0 / 3 1.0实际运行得分会接近 1LLM 可能会因为语义严苛度有微小扣减。如果把无关内容放到第一位得分会直接降到 0.6 左右这也验证了排序对精准度的巨大影响。2. Context Recall 上下文召回率是什么衡量检索系统的查全能力核心看回答这个问题需要的所有关键信息有没有都被检索出来。它关注的是 “漏不漏”和精准度刚好互补 —— 精准度怕掺假召回率怕遗漏。计算原理采用「声明拆解法」三步计算拆解声明把标准答案拆成若干个独立的、不可拆分的事实陈述句Claims匹配验证拿着每一条声明去检索上下文中找依据判断是否能被支持计算得分得分 能被支持的声明数 ÷ 总声明数代码实战importasyncioimportosfromopenaiimportAsyncOpenAIfromdotenvimportload_dotenvfromragas.llmsimportllm_factoryfromragas.metrics.collectionsimportContextRecall load_dotenv()openai_clientAsyncOpenAI(api_keyos.getenv(OPENAI_API_KEY))llmllm_factory(qwen3.6-plus,clientopenai_client,temperature0.1,seed42)scorerContextRecall(llmllm)asyncdefmain():print( 上下文召回率评估 )resultawaitscorer.ascore(user_input北京故宫有哪些著名景点,reference北京故宫的著名景点包括太和殿、乾清宫、御花园和角楼。,retrieved_contexts[太和殿是故宫外朝的核心建筑。,乾清宫是明清两代皇帝的寝宫。,御花园是故宫的皇家园林。,# 缺少“角楼”相关内容])print(f得分{result.value:.4f})if__name____main__:asyncio.run(main())手动演算验证标准答案可以拆成 4 条独立声明故宫有太和殿 ✅ 有依据故宫有乾清宫 ✅ 有依据故宫有御花园 ✅ 有依据故宫有角楼 ❌ 无依据总声明数 4被支持的 3 个得分 3/4 0.75运行结果会在 0.75 左右浮动和我们的手动计算完全吻合。3. Answer Relevancy 答案相关性是什么衡量生成的答案和用户问题的匹配程度也就是 “有没有答非所问”。这个指标不需要标准答案属于无参考评估非常适合没有标注数据的场景。计算原理采用很巧妙的反向重构法核心逻辑是一个高质量的相关答案一定能反向推导出用户原本的问题。三步计算用 LLM 根据生成答案反向生成 N 个可能的用户问题计算这些反向问题与原始问题的语义向量相似度取所有相似度的平均值作为最终得分代码实战importasyncioimportosfromopenaiimportAsyncOpenAIfromdotenvimportload_dotenvfromragas.llmsimportllm_factoryfromragas.embeddings.baseimportembedding_factoryfromragas.metrics.collectionsimportAnswerRelevancy load_dotenv()openai_clientAsyncOpenAI(api_keyos.getenv(OPENAI_API_KEY))llmllm_factory(qwen3.6-plus,clientopenai_client,temperature0.1,seed42)# 用通义的向量模型计算相似度embeddingsembedding_factory(openai,modeltext-embedding-v4,clientopenai_client)scorerAnswerRelevancy(llmllm,embeddingsembeddings)asyncdefmain():print( 答案相关性评估 )# 相关答案测试result1awaitscorer.ascore(user_inputPython是什么类型的编程语言,responsePython是一种解释型、面向对象的高级编程语言语法简洁易读。)print(f相关答案得分{result1.value:.4f})# 无关答案测试result2awaitscorer.ascore(user_inputPython是什么类型的编程语言,response巴黎是法国的首都位于欧洲西部。)print(f无关答案得分{result2.value:.4f})if__name____main__:asyncio.run(main()) 踩坑提示这个指标的分数会有一定波动因为 LLM 反向生成问题有随机性。解决方法就是调低 temperature、固定随机种子多次评估取平均值。4. Faithfulness 忠实度事实一致性是什么也叫忠诚度、 groundedness专门用来检测幻觉。它衡量生成的答案是不是严格基于检索上下文生成的有没有编造上下文里没有的信息。这是生成环节最重要的指标直接决定 RAG 系统的可信度。计算原理和召回率逻辑相反是从答案出发验证把生成的答案拆解成若干独立的事实声明逐一验证每条声明是否能从检索上下文中推断出来得分 能被上下文支持的声明数 ÷ 答案总声明数代码实战我们故意构造一个有事实错误的答案日期写错importasyncioimportosfromopenaiimportAsyncOpenAIfromdotenvimportload_dotenvfromragas.llmsimportllm_factoryfromragas.metrics.collectionsimportFaithfulness load_dotenv()openai_clientAsyncOpenAI(api_keyos.getenv(OPENAI_API_KEY))llmllm_factory(qwen3.6-plus,clientopenai_client,temperature0.1,seed42)scorerFaithfulness(llmllm)asyncdefmain():print( 忠实度评估 )resultawaitscorer.ascore(user_input图灵是什么时候出生的,response图灵1912年6月23日出生在英国伦敦。,retrieved_contexts[Alan Turing was born on 23 June 1912 in Maida Vale, London, England.])print(f得分{result.value:.4f})if__name____main__:asyncio.run(main())如果把答案里的日期改成错误的 “1915 年”得分会直接降到 0.5 左右因为两条声明出生年份、出生地里有一条不成立。5. Answer Correctness 答案正确性是什么端到端的 “金标准” 指标综合衡量生成答案和人工标准答案的一致程度。它是最接近人工评估结果的指标适合最终的效果验收。计算原理两个维度加权平均语义相似度用向量计算两个答案的语义接近程度事实正确性基于 F1 分数计算事实点的重合度区分 TP都有的事实、FP答案多出来的事实、FN答案漏掉的事实可以通过weights参数调整两个维度的权重默认事实正确性权重更高。代码实战importasyncioimportosfromopenaiimportAsyncOpenAIfromdotenvimportload_dotenvfromragas.llmsimportllm_factoryfromragas.embeddings.baseimportembedding_factoryfromragas.metrics.collectionsimportAnswerCorrectness load_dotenv()openai_clientAsyncOpenAI(api_keyos.getenv(OPENAI_API_KEY))llmllm_factory(qwen3.6-plus,clientopenai_client,temperature0.1,seed42)embeddingsembedding_factory(openai,modeltext-embedding-v4,clientopenai_client)scorerAnswerCorrectness(llmllm,embeddingsembeddings)asyncdefmain():print( 答案正确性评估 )resultawaitscorer.ascore(user_input图灵是什么时候出生的,response图灵1915年出生在英国。,reference图灵1912年出生在英国伦敦。)print(f得分{result.value:.4f})if__name____main__:asyncio.run(main())四、一图速查指标依赖对比不同指标需要的输入不一样适用场景也不同整理成表格方便复习指标用户问题生成答案检索上下文标准答案依赖 LLM依赖 EmbeddingContext Precision 上下文精准度✅-✅✅✅-Context Recall 上下文召回率✅-✅✅✅-Answer Relevancy 答案相关性✅✅--✅✅Faithfulness 忠实度✅✅✅-✅-Answer Correctness 答案正确性✅✅-✅✅✅ 场景选择建议只优化检索模块选 Context Precision Context Recall只优化生成模块选 Faithfulness Answer Relevancy端到端最终验收选 Answer Correctness五、学习总结与避坑指南1. 核心逻辑总结RAGAS 的本质是LLM 语义判断 数学统计计算的结合。大模型负责做语义层面的 “好不好、对不对” 的判断再用经典的信息检索指标Precision、Recall、F1做量化最终输出稳定可对比的分数。2. 新手避坑清单版本锁死学习阶段一定要用 0.4.3 版本新版 API 改动极大很容易跑不通教程结果波动所有基于 LLM 的指标都有随机性调低 temperature、固定 seed、多次取平均可以大幅提升稳定性不要迷信单一指标RAG 质量是多维度的要结合检索、生成多个指标综合判断避免单点优化过度先跑通单条再批量测试先把单个指标的单条用例跑通再接入自己的测试数据集排查问题更高效3. 后续学习方向入门之后可以进一步研究批量测试集的构建与自动评估自定义指标的编写把 RAGAS 集成到 CI/CD 流水线做自动化回归测试结合业务场景做权重调优找到最贴合业务的评估标准
