LightRAG 如何用 RAGAS 评估问答质量并解读 Faithfulness、Context Precision 结果【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAGLightRAG 在lightrag/evaluation/目录下内置了一套基于 RAGASRetrieval Augmented Generation Assessment的无参考评估框架它对 LightRAG API 服务发起真实查询用 LLM 对回答质量打分并把结果汇总为 JSON 和 CSV。适合已经有一个索引好文档、正在运行的 LightRAG 实例想要量化回答是否忠实于检索到的上下文、检索结果是否干净的开发者。RAGAS 会计算 Faithfulness、Answer Relevance、Context Recall、Context Precision 四个指标并给出综合 RAGAS 分。评估指标Faithfulness 与 Context Precision 各测什么项目文档lightrag/evaluation/README_EVALUASTION_RAGAS.md对四个核心指标的定义和参考分数如下指标衡量内容参考分数Faithfulness回答基于检索到的上下文是否事实准确 0.80Answer Relevance回答是否切题、回答了用户的问题 0.80Context Recall文档中的相关信息是否都被检索到 0.80Context Precision检索到的上下文是否干净、不含无关噪声 0.80RAGAS Score上述指标的平均值 0.80Faithfulness 关注生成端分数低说明回答里出现了上下文中没有、甚至与上下文矛盾的内容即幻觉。Context Precision 关注检索端分数低说明召回的文档里混入了与问题无关的内容。文档同时给出各分数区间的定性判断0.80–1.00 为 ExcellentProduction-ready0.60–0.80 为 Good仍有改进空间0.40–0.60 为 Poor需要优化0.00–0.40 为 Critical问题严重。准备条件运行评估前需要满足三个条件缺一不可LightRAG API 服务正在运行。评估器默认查询http://localhost:9621文档给出的启动方式是python lightrag/api/lightrag_server.py待评估的文档已索引进 LightRAG 实例。仓库自带一套样例lightrag/evaluation/sample_documents/下的 5 个 Markdown 文件01_lightrag_overview.md到05_evaluation_and_deployment.md与lightrag/evaluation/sample_dataset.json里的 6 条测试问题一一对应。文档建议通过 WebUI 上传这些样例文件完成索引你自己的评估场景则用你自己的语料和对应的问题。评估依赖已安装且需要可用的 API KeyRAGAS 打分本身要调用 LLM 和 Embedding 接口# 直接安装 pip install ragas datasets langfuse # 或使用 pyproject.toml 中已定义的 evaluation 额外依赖 pip install -e .[evaluation]pyproject.toml里evaluation依赖包含lightrag-hku[api]、ragas0.3.7、datasets4.3.0。有一个关键硬性要求评估用的 LLM 和 Embedding 端点必须是 OpenAI 兼容接口。文档明确说明自定义端点必须实现 OpenAI API 格式例如 vLLM、SGLang、LocalAI不兼容的端点会导致评估失败。可选先跑离线检索自检在调用 LightRAG、Embedding、LLM 和 RAGAS 之前可以先用仓库自带的离线检查确认样例问题能否从样例文档中按词法检索到预期文档全程不产生 API/模型调用python lightrag/evaluation/offline_retrieval_check.py --strict配置评估模型与端点评估器通过环境变量读取 RAGAS 打分用的模型配置。所有变量及其默认值来自lightrag/evaluation/README_EVALUASTION_RAGAS.md变量默认值说明EVAL_LLM_MODELgpt-4o-miniRAGAS 评估使用的 LLM 模型EVAL_LLM_BINDING_API_KEY回退到OPENAI_API_KEYLLM 评估的 API KeyEVAL_LLM_BINDING_HOST可选自定义 OpenAI 兼容 LLM 端点 URLEVAL_EMBEDDING_MODELtext-embedding-3-large评估使用的 Embedding 模型EVAL_EMBEDDING_BINDING_API_KEY回退链EVAL_LLM_BINDING_API_KEY→OPENAI_API_KEYEmbedding 的 API KeyEVAL_EMBEDDING_BINDING_HOST回退到EVAL_LLM_BINDING_HOST自定义 OpenAI 兼容 Embedding 端点EVAL_MAX_CONCURRENT2并发评估的测试用例数1串行EVAL_QUERY_TOP_K10每次查询向 LightRAG 请求的实体/关系数EVAL_LLM_MAX_RETRIES5LLM 请求最大重试次数EVAL_LLM_TIMEOUT180LLM 请求超时秒最简用法是只设置 OpenAI KeyLLM 和 Embedding 都走 OpenAI 官方 APIexport OPENAI_API_KEYsk-xxx python lightrag/evaluation/eval_rag_quality.py如果想让 LLM 和 Embedding 共用同一个自定义 OpenAI 兼容端点例如本地服务Embedding 会自动继承 LLM 的端点配置export EVAL_LLM_BINDING_API_KEYyour-custom-key export EVAL_LLM_BINDING_HOSThttp://localhost:8000/v1 export EVAL_LLM_MODELqwen-plus export EVAL_EMBEDDING_MODELBAAI/bge-m3 python lightrag/evaluation/eval_rag_quality.py这些变量也可以写入项目根目录的.env文件脚本会自动加载操作系统环境变量优先于.env。此外评估器访问 LightRAG API 时如果设置了LIGHTRAG_API_KEY环境变量会带上X-API-Key请求头用于认证。运行评估在项目根目录下执行README 的 No sample_dataset.json found 排查条目强调必须在项目根目录运行cd /path/to/Lighrag cd /path/to/LightRAG # 替换为你的 LightRAG 仓库路径 python lightrag/evaluation/eval_rag_quality.py说明/path/to/LightRAG是文档中的占位写法替换为你本地克隆的 LightRAG 仓库目录即可。脚本支持两个命令行参数参数简写默认值说明--dataset-dsample_dataset.json测试数据集 JSON 文件路径--ragendpoint-rhttp://localhost:9621或$LIGHTRAG_API_URLLightRAG API 端点 URL评估自己的语料时把问题写入自己的数据集文件并指向它python lightrag/evaluation/eval_rag_quality.py --dataset my_test.json数据集格式如下question与ground_truth是必填项project用于在结果中标记项目名{ test_cases: [ { question: Your question here, ground_truth: Expected answer from your data, project: evaluation_project_name } ] }文档同时提醒sample_dataset.json里是 3 组关于 LightRAG 的通用问题实际文件里包含 6 条test_cases评估自己的系统时应替换为与你索引文档匹配的问题。如果你的 LightRAG 服务不在本地默认端口python lightrag/evaluation/eval_rag_quality.py --ragendpoint http://my-server.com:9621 # 或简写 python lightrag/evaluation/eval_rag_quality.py -d my_test.json -r http://localhost:9621脚本运行时会先打印配置摘要LLM 模型、Embedding 模型、端点、Top-K、重试与超时、测试用例数、API 地址、结果目录然后进入两阶段流水线先调用 LightRAG 的/query接口生成回答再交给 RAGAS 打分。评估器对/query的请求体中mode固定为mix、response_type为Multiple Paragraphstop_k取EVAL_QUERY_TOP_K默认 10并且通过include_references: true和include_chunk_content: true取回每个引用文件的 chunk 内容——这些实际检索到的 chunk 会作为 RAGAS 计算 Context Precision / Context Recall 的contexts输入而不是 ground truth。查看与解读结果结果自动保存到lightrag/evaluation/results/目录results_YYYYMMDD_HHMMSS.json完整指标与明细results_YYYYMMDD_HHMMSS.csv每行一个测试用例包含faithfulness、answer_relevance、context_recall、context_precision、ragas_score、status等列方便导入表格工具运行结束时终端会输出两个部分逐题结果表Faith / AnswRel / CtxRec / CtxPrec / RAGAS 及成功标记以及BENCHMARK RESULTS (Average)汇总各指标平均值、RAGAS 分的最小/最大值、成功率和耗时。下面是文档给出的示例输出实际数值以你自己的运行结果为准INFO: EVALUATION RESULTS SUMMARY INFO: # | Question | Faith | AnswRel | CtxRec | CtxPrec | RAGAS | Status INFO: 1 | How does LightRAG solve the hallucination probl... | 1.0000 | 1.0000 | 1.0000 | 1.0000 | 1.0000 | ✓ INFO: 2 | What are the three main components required in ... | 0.8500 | 0.5790 | 1.0000 | 1.0000 | 0.8573 | ✓ INFO: 3 | How does LightRAGs retrieval performance compa... | 0.8056 | 1.0000 | 1.0000 | 1.0000 | 0.9514 | ✓ ... INFO: Average Faithfulness: 0.9053 INFO: Average Answer Relevance: 0.8646 INFO: Average Context Recall: 1.0000 INFO: Average Context Precision: 1.0000 INFO: Average RAGAS Score: 0.9425低分如何解读文档给出了各指标低分对应的直接含义指标低分说明的问题Faithfulness回答中包含幻觉或与事实不符的信息Answer Relevance回答没有命中用户的问题Context Recall检索遗漏了重要信息Context Precision检索到的文档中混入了无关噪声针对本文关注的两个指标文档给出的优化方向是Faithfulness 偏低改进实体抽取质量、改进文档切块、调整检索温度Context Precision 偏低使用更小、更聚焦的 chunk、加强过滤、改进切块策略。如果你用样例语料跑评估文档给出的预期是每题约 89–100% 的 RAGAS 分sample_documents/README.md写的是 ~91-100%可用来验证整条链路是否配置正确。常见问题排查出现Warning: LM returned 1 generations instead of requested 3或 Context Precision 为 NaN文档指出这通常意味着 API 限流或并发请求过载——RAGAS 每个测试用例会发起多次 LLM 调用其中 Context Precision 对每篇检索到的文档各调用一次 LLMEVAL_QUERY_TOP_K10时即 10 次并发评估会再把这些调用翻倍。按文档建议的顺序处理串行评估EVAL_MAX_CONCURRENT1降低EVAL_QUERY_TOP_K例如设为 5Context Precision 的 LLM 调用减半调大重试与超时EVAL_LLM_MAX_RETRIES10、EVAL_LLM_TIMEOUT180及以上如有条件换用配额更高的 API如 OpenAI Tier 2或无速率限制的自托管 OpenAI 兼容服务。HTTP 429 限流错误调大EVAL_LLM_MAX_RETRIES并调小EVAL_MAX_CONCURRENT。ModuleNotFoundError: No module named ragas执行pip install ragas datasets。AttributeError: InstructorLLM object has no attribute agenerate_prompt或结果为 NaNRAGAS 0.3.x需要显式配置评估模型——设置OPENAI_API_KEY默认或EVAL_LLM_BINDING_API_KEY框架会自动创建 LLM 与 Embeddings 实例。No sample_dataset.json found确认在项目根目录运行脚本。评估期间 LightRAG 查询 API 报错确认 API Key 已配置在.env中、网络连接稳定且python lightrag/api/lightrag_server.py启动的 API 服务在配置的 URL 上可访问、文档已索引完成。边界与限制评估必须对着一个已索引文档、正在运行的 LightRAG API 服务进行脚本本身不负责启动服务或索引文档。评估打分端的 LLM 与 Embedding 必须是 OpenAI 兼容接口且需要消耗真实 API 调用额度EVAL_QUERY_TOP_K越高Context Precision 带来的 LLM 调用量越大越容易触发限流。仓库样例文档是为 LightRAG 默认实体抽取提示设计的清晰实体-关系模式语料文档明确提示换成自己的数据后如需更好效果可自定义lightrag/prompt.py中的抽取提示。更多细节可参考 RAGAS 评估框架说明、评估脚本 与 样例数据集。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LightRAG 如何用 RAGAS 评估问答质量并解读 Faithfulness、Context Precision 结果
LightRAG 如何用 RAGAS 评估问答质量并解读 Faithfulness、Context Precision 结果【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAGLightRAG 在lightrag/evaluation/目录下内置了一套基于 RAGASRetrieval Augmented Generation Assessment的无参考评估框架它对 LightRAG API 服务发起真实查询用 LLM 对回答质量打分并把结果汇总为 JSON 和 CSV。适合已经有一个索引好文档、正在运行的 LightRAG 实例想要量化回答是否忠实于检索到的上下文、检索结果是否干净的开发者。RAGAS 会计算 Faithfulness、Answer Relevance、Context Recall、Context Precision 四个指标并给出综合 RAGAS 分。评估指标Faithfulness 与 Context Precision 各测什么项目文档lightrag/evaluation/README_EVALUASTION_RAGAS.md对四个核心指标的定义和参考分数如下指标衡量内容参考分数Faithfulness回答基于检索到的上下文是否事实准确 0.80Answer Relevance回答是否切题、回答了用户的问题 0.80Context Recall文档中的相关信息是否都被检索到 0.80Context Precision检索到的上下文是否干净、不含无关噪声 0.80RAGAS Score上述指标的平均值 0.80Faithfulness 关注生成端分数低说明回答里出现了上下文中没有、甚至与上下文矛盾的内容即幻觉。Context Precision 关注检索端分数低说明召回的文档里混入了与问题无关的内容。文档同时给出各分数区间的定性判断0.80–1.00 为 ExcellentProduction-ready0.60–0.80 为 Good仍有改进空间0.40–0.60 为 Poor需要优化0.00–0.40 为 Critical问题严重。准备条件运行评估前需要满足三个条件缺一不可LightRAG API 服务正在运行。评估器默认查询http://localhost:9621文档给出的启动方式是python lightrag/api/lightrag_server.py待评估的文档已索引进 LightRAG 实例。仓库自带一套样例lightrag/evaluation/sample_documents/下的 5 个 Markdown 文件01_lightrag_overview.md到05_evaluation_and_deployment.md与lightrag/evaluation/sample_dataset.json里的 6 条测试问题一一对应。文档建议通过 WebUI 上传这些样例文件完成索引你自己的评估场景则用你自己的语料和对应的问题。评估依赖已安装且需要可用的 API KeyRAGAS 打分本身要调用 LLM 和 Embedding 接口# 直接安装 pip install ragas datasets langfuse # 或使用 pyproject.toml 中已定义的 evaluation 额外依赖 pip install -e .[evaluation]pyproject.toml里evaluation依赖包含lightrag-hku[api]、ragas0.3.7、datasets4.3.0。有一个关键硬性要求评估用的 LLM 和 Embedding 端点必须是 OpenAI 兼容接口。文档明确说明自定义端点必须实现 OpenAI API 格式例如 vLLM、SGLang、LocalAI不兼容的端点会导致评估失败。可选先跑离线检索自检在调用 LightRAG、Embedding、LLM 和 RAGAS 之前可以先用仓库自带的离线检查确认样例问题能否从样例文档中按词法检索到预期文档全程不产生 API/模型调用python lightrag/evaluation/offline_retrieval_check.py --strict配置评估模型与端点评估器通过环境变量读取 RAGAS 打分用的模型配置。所有变量及其默认值来自lightrag/evaluation/README_EVALUASTION_RAGAS.md变量默认值说明EVAL_LLM_MODELgpt-4o-miniRAGAS 评估使用的 LLM 模型EVAL_LLM_BINDING_API_KEY回退到OPENAI_API_KEYLLM 评估的 API KeyEVAL_LLM_BINDING_HOST可选自定义 OpenAI 兼容 LLM 端点 URLEVAL_EMBEDDING_MODELtext-embedding-3-large评估使用的 Embedding 模型EVAL_EMBEDDING_BINDING_API_KEY回退链EVAL_LLM_BINDING_API_KEY→OPENAI_API_KEYEmbedding 的 API KeyEVAL_EMBEDDING_BINDING_HOST回退到EVAL_LLM_BINDING_HOST自定义 OpenAI 兼容 Embedding 端点EVAL_MAX_CONCURRENT2并发评估的测试用例数1串行EVAL_QUERY_TOP_K10每次查询向 LightRAG 请求的实体/关系数EVAL_LLM_MAX_RETRIES5LLM 请求最大重试次数EVAL_LLM_TIMEOUT180LLM 请求超时秒最简用法是只设置 OpenAI KeyLLM 和 Embedding 都走 OpenAI 官方 APIexport OPENAI_API_KEYsk-xxx python lightrag/evaluation/eval_rag_quality.py如果想让 LLM 和 Embedding 共用同一个自定义 OpenAI 兼容端点例如本地服务Embedding 会自动继承 LLM 的端点配置export EVAL_LLM_BINDING_API_KEYyour-custom-key export EVAL_LLM_BINDING_HOSThttp://localhost:8000/v1 export EVAL_LLM_MODELqwen-plus export EVAL_EMBEDDING_MODELBAAI/bge-m3 python lightrag/evaluation/eval_rag_quality.py这些变量也可以写入项目根目录的.env文件脚本会自动加载操作系统环境变量优先于.env。此外评估器访问 LightRAG API 时如果设置了LIGHTRAG_API_KEY环境变量会带上X-API-Key请求头用于认证。运行评估在项目根目录下执行README 的 No sample_dataset.json found 排查条目强调必须在项目根目录运行cd /path/to/Lighrag cd /path/to/LightRAG # 替换为你的 LightRAG 仓库路径 python lightrag/evaluation/eval_rag_quality.py说明/path/to/LightRAG是文档中的占位写法替换为你本地克隆的 LightRAG 仓库目录即可。脚本支持两个命令行参数参数简写默认值说明--dataset-dsample_dataset.json测试数据集 JSON 文件路径--ragendpoint-rhttp://localhost:9621或$LIGHTRAG_API_URLLightRAG API 端点 URL评估自己的语料时把问题写入自己的数据集文件并指向它python lightrag/evaluation/eval_rag_quality.py --dataset my_test.json数据集格式如下question与ground_truth是必填项project用于在结果中标记项目名{ test_cases: [ { question: Your question here, ground_truth: Expected answer from your data, project: evaluation_project_name } ] }文档同时提醒sample_dataset.json里是 3 组关于 LightRAG 的通用问题实际文件里包含 6 条test_cases评估自己的系统时应替换为与你索引文档匹配的问题。如果你的 LightRAG 服务不在本地默认端口python lightrag/evaluation/eval_rag_quality.py --ragendpoint http://my-server.com:9621 # 或简写 python lightrag/evaluation/eval_rag_quality.py -d my_test.json -r http://localhost:9621脚本运行时会先打印配置摘要LLM 模型、Embedding 模型、端点、Top-K、重试与超时、测试用例数、API 地址、结果目录然后进入两阶段流水线先调用 LightRAG 的/query接口生成回答再交给 RAGAS 打分。评估器对/query的请求体中mode固定为mix、response_type为Multiple Paragraphstop_k取EVAL_QUERY_TOP_K默认 10并且通过include_references: true和include_chunk_content: true取回每个引用文件的 chunk 内容——这些实际检索到的 chunk 会作为 RAGAS 计算 Context Precision / Context Recall 的contexts输入而不是 ground truth。查看与解读结果结果自动保存到lightrag/evaluation/results/目录results_YYYYMMDD_HHMMSS.json完整指标与明细results_YYYYMMDD_HHMMSS.csv每行一个测试用例包含faithfulness、answer_relevance、context_recall、context_precision、ragas_score、status等列方便导入表格工具运行结束时终端会输出两个部分逐题结果表Faith / AnswRel / CtxRec / CtxPrec / RAGAS 及成功标记以及BENCHMARK RESULTS (Average)汇总各指标平均值、RAGAS 分的最小/最大值、成功率和耗时。下面是文档给出的示例输出实际数值以你自己的运行结果为准INFO: EVALUATION RESULTS SUMMARY INFO: # | Question | Faith | AnswRel | CtxRec | CtxPrec | RAGAS | Status INFO: 1 | How does LightRAG solve the hallucination probl... | 1.0000 | 1.0000 | 1.0000 | 1.0000 | 1.0000 | ✓ INFO: 2 | What are the three main components required in ... | 0.8500 | 0.5790 | 1.0000 | 1.0000 | 0.8573 | ✓ INFO: 3 | How does LightRAGs retrieval performance compa... | 0.8056 | 1.0000 | 1.0000 | 1.0000 | 0.9514 | ✓ ... INFO: Average Faithfulness: 0.9053 INFO: Average Answer Relevance: 0.8646 INFO: Average Context Recall: 1.0000 INFO: Average Context Precision: 1.0000 INFO: Average RAGAS Score: 0.9425低分如何解读文档给出了各指标低分对应的直接含义指标低分说明的问题Faithfulness回答中包含幻觉或与事实不符的信息Answer Relevance回答没有命中用户的问题Context Recall检索遗漏了重要信息Context Precision检索到的文档中混入了无关噪声针对本文关注的两个指标文档给出的优化方向是Faithfulness 偏低改进实体抽取质量、改进文档切块、调整检索温度Context Precision 偏低使用更小、更聚焦的 chunk、加强过滤、改进切块策略。如果你用样例语料跑评估文档给出的预期是每题约 89–100% 的 RAGAS 分sample_documents/README.md写的是 ~91-100%可用来验证整条链路是否配置正确。常见问题排查出现Warning: LM returned 1 generations instead of requested 3或 Context Precision 为 NaN文档指出这通常意味着 API 限流或并发请求过载——RAGAS 每个测试用例会发起多次 LLM 调用其中 Context Precision 对每篇检索到的文档各调用一次 LLMEVAL_QUERY_TOP_K10时即 10 次并发评估会再把这些调用翻倍。按文档建议的顺序处理串行评估EVAL_MAX_CONCURRENT1降低EVAL_QUERY_TOP_K例如设为 5Context Precision 的 LLM 调用减半调大重试与超时EVAL_LLM_MAX_RETRIES10、EVAL_LLM_TIMEOUT180及以上如有条件换用配额更高的 API如 OpenAI Tier 2或无速率限制的自托管 OpenAI 兼容服务。HTTP 429 限流错误调大EVAL_LLM_MAX_RETRIES并调小EVAL_MAX_CONCURRENT。ModuleNotFoundError: No module named ragas执行pip install ragas datasets。AttributeError: InstructorLLM object has no attribute agenerate_prompt或结果为 NaNRAGAS 0.3.x需要显式配置评估模型——设置OPENAI_API_KEY默认或EVAL_LLM_BINDING_API_KEY框架会自动创建 LLM 与 Embeddings 实例。No sample_dataset.json found确认在项目根目录运行脚本。评估期间 LightRAG 查询 API 报错确认 API Key 已配置在.env中、网络连接稳定且python lightrag/api/lightrag_server.py启动的 API 服务在配置的 URL 上可访问、文档已索引完成。边界与限制评估必须对着一个已索引文档、正在运行的 LightRAG API 服务进行脚本本身不负责启动服务或索引文档。评估打分端的 LLM 与 Embedding 必须是 OpenAI 兼容接口且需要消耗真实 API 调用额度EVAL_QUERY_TOP_K越高Context Precision 带来的 LLM 调用量越大越容易触发限流。仓库样例文档是为 LightRAG 默认实体抽取提示设计的清晰实体-关系模式语料文档明确提示换成自己的数据后如需更好效果可自定义lightrag/prompt.py中的抽取提示。更多细节可参考 RAGAS 评估框架说明、评估脚本 与 样例数据集。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考