RAG评估代码生成

请你为我的 RAG 问答项目生成一套完整、可运行、工程化的“RAG 自动评估系统”Python 代码。 本次评估系统请以 Ragas 框架为核心，目标是将 RAG 系统的效果评估从“肉眼观察、凭感觉调参”，变成“可量化、可对比、可定位问题、可持续优化”的标准评估流程。 重要要求： 1. 请优先查阅并适配当前安装版本的 Ragas 官方 API，使用最新可用写法，不要直接照搬旧版 ragas.testset.generator、ragas.testset.evolutions 等可能已变化的历史代码。 2. 如果不同版本 Ragas API 存在差异，请在代码中做好兼容性说明，或者提供“当前推荐写法 + 旧版替代写法”。 3. 代码要能在 Windows + Anaconda 环境中运行。 4. 所有代码要有清晰中文注释。 5. 代码结构要工程化，便于我后续接入自己的 RAG 项目。 ================================================== 一、评估系统总体目标 ================================================== 请为我的 RAG 项目实现以下完整流程： 第 1 步：读取我的知识库文档 - 支持 TXT、Markdown、PDF 文本抽取后的文档列表 - 统一转换为 Ragas 测试集生成或后续检索所需的数据结构 第 2 步：基于文档自动生成“合成真值测试集” - 利用 Ragas 的 synthetic testset generation 能力 - 根据本地文档生成评估问题与参考答案 - 测试集应覆盖不同难度与不同类型问题： 1. simple：单文档直接问答 2. reasoning：需要理解与推理的问题 3. multi_context / multi-hop：需要结合多个上下文片段的问题 - 允许通过配置调整各类问题的占比，例如： - simple：50% - reasoning：25% - multi_context：25% - 允许配置 test_size，例如 20、50、100 - 将生成的测试集保存为 CSV / JSONL，避免每次重复消耗 API - 保存字段至少包括： - question - reference / ground_truth - contexts 或生成测试集时所依赖的参考上下文 - question_type - difficulty（如可支持） 第 3 步：将测试问题输入我的 RAG 系统 - 请预留一个统一接口函数： def run_rag(question: str, retrieval_mode: str = "vector") -> dict: return { "question": question, "answer": "...", "contexts": ["检索到的片段1", "检索到的片段2"], "retrieved_doc_ids": ["doc_1", "doc_2"], "retrieval_latency": 0.21, "generation_latency": 1.37, "total_latency": 1.58 } - 请先提供一个 Mock 示例，保证代码可直接跑通 - 同时明确说明：我后续只需要把 run_rag() 替换成自己的真实 RAG 检索 + 生成逻辑即可 第 4 步：支持不同检索策略对比实验 请实现一个可配置的实验框架，用于比较： 1. 向量检索 Vector Search 2. 混合检索 Hybrid Search 3. 后续可扩展： - BM25 - Reranker - 不同 top_k - 不同 embedding 模型 - 不同 chunk_size / chunk_overlap 代码应支持类似下面的配置： EXPERIMENTS = [ {"name": "vector_top5", "retrieval_mode": "vector", "top_k": 5}, {"name": "hybrid_top5", "retrieval_mode": "hybrid", "top_k": 5} ] 并分别执行评估，输出不同策略的评估指标，最终生成对比报告。 ================================================== 二、必须实现的 Ragas 评估指标 ================================================== 请使用 Ragas 对以下核心指标进行评估： 1. Context Precision 中文含义：上下文精度 评估重点： - 检索回来的上下文中，真正与问题回答相关的信息是否排在前面 - 检索结果是否混入过多无关噪声 用途： - 判断检索结果“准不准” - 如果该指标低，说明检索片段里无关内容偏多，或者排序不佳 2. Context Recall 中文含义：上下文召回率 评估重点： - 标准答案所需的关键信息，是否被检索上下文充分覆盖 用途： - 判断检索结果“全不全” - 如果该指标低，说明知识没召回，可能需要调整： - chunk 切分 - top_k - embedding 模型 - 检索策略 3. Faithfulness 中文含义：忠实度 / 事实依托度 评估重点： - 最终回答是否严格依据检索到的上下文 - 是否出现上下文中没有依据的内容 用途： - 判断是否存在幻觉 - 如果该指标低，说明生成模型可能在“瞎编”，需要优化提示词或拒答机制 4. Answer Relevancy / Response Relevancy 中文含义：回答相关性 评估重点： - 回答是否真正针对用户问题 - 是否答非所问、偏题、废话过多 用途： - 判断回答是否“对题” - 如果该指标低，说明 prompt 或上下文组织方式需要优化 5. Answer Correctness 中文含义：答案正确性 评估重点： - 模型答案与参考答案在事实和语义层面是否一致 用途： - 判断端到端最终回答是否正确 - 该指标是面向业务的最终效果指标 如果当前版本 Ragas 中这些指标类名或导入方式发生变化，请使用官方当前版本的正确写法，并在代码里注明。 ================================================== 三、评估数据组织要求 ================================================== 请将数据转换为适合 Ragas 评估的数据结构。 每条评估样本应至少包含： - user_input / question - retrieved_contexts / contexts - response / answer - reference / ground_truth 请确保最终可传入 Ragas evaluate 或当前版本对应的评估入口。 如果当前版本官方推荐使用 EvaluationDataset、SingleTurnSample 等结构，请使用官方推荐方式； 如果仍支持 Dataset 格式，也可以提供 Dataset 版本示例。 ================================================== 四、核心代码模块要求 ================================================== 请按照工程化思路组织代码，至少拆分为以下文件： 1. config.py 作用： - 配置 API Key - 配置生成测试集参数 - 配置实验组 - 配置 Ragas 指标 - 配置输出目录 2. document_loader.py 作用： - 加载文档 - 支持读取 txt / md / PDF 抽取后的纯文本 - 转换为后续测试集生成所需格式 3. testset_generator.py 作用： - 使用 Ragas 根据文档生成合成测试集 - 支持设置 test_size - 支持设置问题类型比例 - 输出 CSV / JSONL 文件 4. rag_runner.py 作用： - 实现 run_rag() - 提供 mock 示例 - 预留接入我的真实 RAG 系统的接口 5. evaluation_builder.py 作用： - 将： - testset 中的问题与 ground truth - run_rag() 产生的 answer 与 contexts 拼接成 Ragas 可评估数据集 6. ragas_evaluator.py 作用： - 使用 Ragas 计算： - Context Precision - Context Recall - Faithfulness - Answer Relevancy - Answer Correctness - 返回逐条分数与整体平均分 7. experiment_runner.py 作用： - 批量运行多组检索策略实验 - 例如向量检索 vs 混合检索 - 输出每组指标结果 8. visualization.py 作用： - 使用 matplotlib 生成可视化图表 - 不要使用 seaborn - 每张图单独生成 - 包括： 1. 多策略核心指标柱状图 2. Context Precision / Recall 对比图 3. Faithfulness / Answer Relevancy / Answer Correctness 对比图 4. 单条样本得分分布图 5. 检索耗时与生成耗时对比图 9. report_generator.py 作用： - 输出 Markdown 评估报告 - 报告中包含总体结论、指标表格、问题定位、优化建议 10. main.py 作用： - 一键执行全流程： 文档读取 → 测试集生成 → RAG 执行 → Ragas 评估 → 可视化 → 报告输出 ================================================== 五、输出文件要求 ================================================== 请最终生成以下文件： 1. generated_testset.csv - 自动生成的合成真值测试集 2. evaluation_input.csv - RAG 实际回答后的待评估数据 3. evaluation_results_vector.csv - 向量检索实验逐条结果 4. evaluation_results_hybrid.csv - 混合检索实验逐条结果 5. metrics_summary.csv - 不同实验组核心指标平均值汇总 6. metrics_summary.json - 机器可读的汇总指标 7. evaluation_report.md - 人类可读的完整评估报告 8. charts/ - 保存所有评估图表 ================================================== 六、评估报告内容要求 ================================================== evaluation_report.md 至少包含： 1. 项目评估说明 - 本次评估目标 - 使用了哪些指标 - 为什么需要分开评估检索和生成 2. 实验设置 - 测试集大小 - 问题类型比例 - 参与对比的检索策略 - 使用的评估模型 3. 核心指标结果总表 示例： | 评估维度 | 指标 | Vector Search | Hybrid Search | Diff | |---|---|---:|---:|---:| | 检索 | Context Precision | 0.90 | 0.85 | -0.05 | | 检索 | Context Recall | 0.94 | 0.91 | -0.03 | | 生成 | Faithfulness | 0.96 | 0.93 | -0.03 | | 生成 | Answer Relevancy | 0.91 | 0.89 | -0.02 | | 端到端 | Answer Correctness | 0.88 | 0.85 | -0.03 | 4. 指标解读 - 如果 Context Recall 低，应如何优化 - 如果 Context Precision 低，应如何优化 - 如果 Faithfulness 低，应如何优化 - 如果 Answer Relevancy 低，应如何优化 - 如果 Answer Correctness 低，应如何优化 5. 检索策略对比分析 - 哪种策略更好 - 是否出现“混合检索反而引入噪声”的现象 - 是否存在召回提升但忠实度下降的问题 6. 失败案例分析 - 找出分数最低的 Top 10 样本 - 展示： - 问题 - 参考答案 - 实际回答 - 检索上下文 - 各指标得分 - 帮助定位问题出在检索还是生成 7. 最终优化建议 请根据评估指标自动生成建议，例如： - Context Recall 低： - 增大 top_k - 优化 chunk_size - 提高 chunk overlap - 更换 embedding 模型 - Context Precision 低： - 降低 top_k - 引入 reranker - 改善混合检索权重 - Faithfulness 低： - 强化“仅依据上下文回答” - 加入“上下文不足时拒答” - 减少无关上下文干扰 - Answer Correctness 低： - 提升检索质量 - 优化 Prompt - 更换生成模型 ================================================== 七、可视化要求 ================================================== 请使用 matplotlib 生成以下图表，保存为 PNG： 1. 不同实验组核心指标对比柱状图 - X轴：指标 - Y轴：得分 - 对比 Vector Search 与 Hybrid Search 2. 检索类指标对比图 - Context Precision - Context Recall 3. 生成类指标对比图 - Faithfulness - Answer Relevancy - Answer Correctness 4. 各样本 Answer Correctness 分布直方图 5. Faithfulness 与 Answer Correctness 的散点图 - 用于观察： 是否存在“答案看似正确但并不忠实于上下文”的情况 6. 延迟对比图 - retrieval_latency - generation_latency - total_latency ================================================== 八、代码健壮性要求 ================================================== 请确保代码： 1. 可直接运行 2. 自动创建输出目录 3. 使用 tqdm 显示进度条 4. 对 API 调用异常进行 try-except 处理 5. 能跳过失败样本并记录错误日志 6. 能够从已生成的测试集文件继续评估，避免重复生成 7. 支持断点式使用： - 只生成测试集 - 只跑 RAG - 只做评估 - 只生成报告 ================================================== 九、依赖文件要求 ================================================== 请给出 requirements.txt，至少包含： - ragas - pandas - tqdm - matplotlib - datasets（如果需要） - langchain / langchain-openai（如果代码使用） - python-dotenv - 其他当前方案必须依赖的库 ================================================== 十、模型角色设计 ================================================== 请允许配置不同模型角色： 1. generation_llm - 我的 RAG 系统实际用于回答问题的模型 2. evaluator_llm - Ragas 或评估时使用的裁判模型 - 建议与生成模型分离，尽量使用能力更强、稳定性更高的评估模型 3. embeddings - 用于测试集生成或评估过程中需要的 embedding 模型 请统一从 config.py 或 .env 中读取。 ================================================== 十一、最终你要输出的内容 ================================================== 请依次给我： 1. 项目目录结构 2. requirements.txt 3. .env.example 4. config.py 5. document_loader.py 6. testset_generator.py 7. rag_runner.py 8. evaluation_builder.py 9. ragas_evaluator.py 10. experiment_runner.py 11. visualization.py 12. report_generator.py 13. main.py 14. 示例数据与示例运行方式 15. 如何把 run_rag() 替换成我的真实 RAG 系统 16. 如何解读评估结果 17. 如何基于评估结果优化 RAG 代码请尽可能完整，不要只给思路或伪代码。