轻量 RAG 智能体自动化评测工具：RAGAS 指标 + Langfuse 追踪。支持对接多种智能体 / RAG 平台对话 API，对金标准数据集批量收集回答并评分。
| 能力 | 说明 |
|---|---|
| 多平台对话 | AGENT_PLATFORM 切换 FastGPT、OpenAI 兼容、Dify、Coze、百炼、RAGFlow 等 |
| 检索上下文 | 各平台解析 quoteList / reference / retriever_resources 等，供 RAGAS 使用 |
| 金标准答案 | data/golden_dataset.jsonl 维护 ground_truth / ground_truth_contexts |
| RAGAS 指标 | faithfulness、answer_relevancy、context_precision、context_recall |
| Langfuse | 每条问题一条 trace：智能体生成 + RAGAS 分数（可选） |
① 环境配置
编辑 .env：智能体平台（AGENT_*）、RAGAS 评判 LLM / Embedding、可选 Langfuse
↓
② 金标准数据准备
维护 data/golden_dataset.jsonl：question、ground_truth、ground_truth_contexts 等
↓
③ 智能体 API 调用（collect）
按金标准逐条提问，经 agent_client 对接 FastGPT / Dify / OpenAI 兼容等平台
↓
④ 对话结果采集与持久化
汇总 answer、contexts、chat_id 等，写入 results/collected_*.jsonl
↓
⑤ RAGAS 评分（score）
读取 collected_*.jsonl，按 RAGAS_MAX_* 裁剪 contexts / answer 后逐条评分
├─ 预检（preflight，可选）：评判 LLM、向量模型、answer_relevancy 的 n 次生成
├─ faithfulness
│ └─ 评判 LLM：从 answer 抽陈述，对照 contexts 判是否可支撑（幻觉检测）
├─ answer_relevancy
│ ├─ 评判 LLM：由 answer 反向生成问题（strictness 控制次数）
│ └─ 向量模型：生成问题 embedding 与原始 question 算相似度
├─ context_precision
│ ├─ 评判 LLM：逐条 context 判是否与 question 相关
│ └─ 向量模型：相关 context 与 ground_truth 语义匹配
└─ context_recall（有 ground_truth_contexts 时启用）
├─ 评判 LLM：判 ground_truth 要点是否被 contexts 覆盖
└─ 向量模型：要点与检索片段语义召回比对
↓
⑥ 评分结果输出
生成 results/ragas_scores_*.csv（逐条明细）与 ragas_summary_*.json（汇总均值）
↓
⑦ 结果解读（可选）
将 CSV / 汇总 JSON 提供给大模型，归纳逐条亮点、问题与改进建议
（可选）③～⑥ 同步写入 Langfuse Trace，按样本关联对话与 RAGAS 分数
一键执行 ③→⑥：python run_eval.py all
lite-rag-eval/
├── activate.bat # Windows 虚拟环境激活
├── docs/ # 配置与技术文档
├── .env.example # 环境变量模板
├── run_eval.py # 主入口
├── agent_client.py # 多平台智能体客户端
├── data/golden_dataset.jsonl
└── results/ # 运行输出（git 忽略）
cd lite-rag-eval
python -m venv .venv
activate.bat
pip install -r requirements.txt
copy .env.example .env编辑 .env：至少配置评测对象（AGENT_*）与 RAGAS 评判 LLM / Embedding（OPENAI_API_*、RAGAS_*）。各平台详细配置见 docs/智能体平台配置.md。
# 一键 collect + score
python run_eval.py all
# 预检评判 API（推荐）
python run_eval.py preflight
# 收集智能体回答
python run_eval.py collect
# RAGAS 评分
python run_eval.py score
# 单条诊断：按指标串行评分，打印每步耗时（定位卡住环节）
python run_eval.py score-debug --id qa_001
# 仅评部分样本
python run_eval.py score --ids qa_001
# 指定样本
python run_eval.py collect --ids qa_001,qa_002输出目录为 results/：收集见 收集结果说明，评分见 评分结果说明。
data/golden_dataset.jsonl 每行一条 JSON。示例数据为通用安全生产场景，已脱敏，可按业务替换。
| 字段 | 必填 | 说明 | 作用 |
|---|---|---|---|
id |
是 | 样本唯一标识，如 qa_001 |
collect --ids 子集筛选；Langfuse trace 关联；结果 jsonl 中对齐样本 |
question |
是 | 发给智能体的用户问题 | collect 阶段调用对话 API 的输入 |
ground_truth |
是 | 期望回答要点（摘要，非逐字标准答案） | RAGAS answer_relevancy 等指标的参考回答 |
ground_truth_contexts |
否 | 期望被检索到的片段或关键词列表 | 有值时启用 RAGAS context_recall；可与实际 contexts 对比召回质量 |
metadata |
否 | 自定义标签，如 category、scene |
不参与 RAGAS 计分；写入 Langfuse trace，便于按场景筛选与分析 |
collect 将金标准与智能体返回合并写入 JSONL：results/collected_YYYYMMDD_HHMMSS.jsonl，并同步更新 results/collected_latest.jsonl（供默认 score 输入）。每行一条 JSON：
| 字段 | 说明 | 作用 |
|---|---|---|
id |
样本 ID，与金标准一致 | 对齐样本；score 与 Langfuse 关联 |
question |
用户问题 | 与金标准相同；RAGAS 输入 |
ground_truth |
期望回答要点 | RAGAS 参考回答；score 输入 |
ground_truth_contexts |
期望检索片段/关键词 | 有值时启用 context_recall |
answer |
智能体实际回答 | RAGAS 评测对象；faithfulness / answer_relevancy 等 |
contexts |
智能体返回的检索上下文列表 | RAGAS 检索质量指标；为空时 context 类指标受限 |
chat_id |
平台会话/对话 ID | 多轮扩展、问题排查 |
error |
调用失败时的错误信息 | 非空则该条不参与 score |
metadata |
金标准中的自定义标签 | Langfuse trace；结果分析分组 |
也可用 python run_eval.py score --input results/collected_xxx.jsonl 指定历史收集文件。
score 会生成明细 CSV 与汇总 JSON。仅 error 为空的样本参与评分；送入 RAGAS 前会按 .env 中 RAGAS_MAX_* 裁剪 contexts 与 answer 长度。
每行对应一条成功样本，主要列如下：
| 字段 | 说明 | 作用 |
|---|---|---|
user_input |
用户问题 | RAGAS 对 question 的列名 |
response |
智能体回答 | RAGAS 对 answer 的列名 |
retrieved_contexts |
检索上下文 | RAGAS 对 contexts 的列名 |
reference |
金标准回答 | RAGAS 对 ground_truth 的列名 |
ground_truth_contexts |
期望检索片段 | 有金标准上下文时出现 |
faithfulness |
忠实度（0～1） | 回答是否基于检索内容，越高越不易幻觉 |
answer_relevancy |
回答相关性（0～1） | 回答与问题的相关程度 |
context_precision |
上下文精确度（0～1） | 检索片段与问题的相关程度 |
context_recall |
上下文召回（0～1） | 检索是否覆盖金标准要点；仅当金标准含 ground_truth_contexts 时计算 |
指标列为浮点数；API 失败或样本被跳过时可能为 NaN。
| 字段 | 说明 | 作用 |
|---|---|---|
run_name |
本次运行名称 | 对应 .env 中 EVAL_RUN_NAME |
input_file |
评分的收集结果路径 | 追溯数据来源 |
sample_count |
参与评分的样本数 | 不含 collect 失败的条目 |
trim_stats |
裁剪统计 | 各样本 context/answer 裁剪前后字符数 |
metrics |
各指标汇总 | 每项含 mean / min / max / valid_count；终端也会打印均值 |
未配置 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY 时自动跳过追踪。
云服务：在 Langfuse Cloud 创建项目，将密钥写入 .env，默认 LANGFUSE_HOST=https://cloud.langfuse.com。
本地部署：按官方文档自建实例，详见 Langfuse 中文 README。部署完成后在 .env 中设置：
LANGFUSE_HOST=http://localhost:3000
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
EVAL_RUN_NAME=lite-rag-evalUI 中可看到：EVAL_RUN_NAME 批次 trace、agent-chat generation、以及 ragas_* 分数。
完成 collect + score（或 python run_eval.py all）后，可在 Langfuse 与本地评分结果中对照查看每条样本的表现。
每条样本以 {EVAL_RUN_NAME}:{id} 写入 Trace，可在 Langfuse Tracing 页按批次筛选，查看问题输入、智能体回答与 RAGAS 分数关联。
将 results/ragas_scores_*.csv 与汇总 JSON 等评分结果提供给大模型（如 ChatGPT、DeepSeek 等），由其按 RAGAS 四维指标（F / AR / CP / CR）归纳表现较好与需改进的样本，并分析检索噪声、上下文缺失等可能原因。下图为示例分析报告。
| 现象 | 处理 |
|---|---|
| RAGAS 指标全 NaN | 检查 RAGAS_LLM_MODEL 与 API 密钥，先跑 preflight |
LLM returned 1 generations instead of requested 3 |
设 RAGAS_ANSWER_RELEVANCY_STRICTNESS=1 |
| faithfulness 报 max_tokens / 截断 | 减小 .env 中 RAGAS_MAX_* 或 RAGAS_MAX_TOKENS |
| collect 时 contexts 为空 | 确认平台已开启引用返回，见 平台配置说明 |
score 极慢或像卡住 |
context 过多/过长；减小 RAGAS_MAX_CONTEXTS（建议 ≤5）、RAGAS_MAX_CONTEXT_TOTAL_CHARS（建议 ≤5000）；可设 RAGAS_RUN_TIMEOUT 避免无限等待；用 score-debug --id qa_001 逐指标看哪一步慢 |
- 智能体平台配置
- Langfuse 本地部署：langfuse/langfuse README.cn.md