README.md



WeKnora Ragas Eval

独立的 WeKnora Ragas 评估项目。它只调用 WeKnora 公开 API，不依赖 WeKnora 内置的 /evaluation 接口。

完整服务器测试流程见 TESTING_GUIDE.md。


安装

python -m venv .venv
source .venv/bin/activate
pip install -e .


如果需要更好的 PDF 解析能力：

pip install -e ".[pdf]"


开发和测试工具：

pip install -e ".[dev,pdf]"


配置

cp .env.example .env


编辑 .env 后确认：


WEKNORA_BASE_URL 指向 WeKnora API v1，例如 http://localhost:9090/api/v1


WEKNORA_API_KEY 是 WeKnora API Key

WEKNORA_KB_ID 是目标知识库 ID；如果还没有，先运行 python scripts/00_create_kb.py


WEKNORA_KB_NAME 是创建知识库时使用的名称

RAGAS_LLM_BASE_URL 指向 vLLM 的 OpenAI-compatible /v1


RAGAS_EMBEDDING_BASE_URL 指向 Infinity embedding 的 OpenAI-compatible /v1


RAGAS_*_MODEL 是评估侧模型名称

RAGAS_ENABLE_THINKING=false 只会在本评估项目的 RAGAS LLM 请求中发送 chat_template_kwargs.enable_thinking=false，不会改变 WeKnora 检索/问答服务的模型配置

RAGAS_HTTP_KEEPALIVE=false 会让 RAGAS LLM 请求使用短连接，规避长流程中 async HTTP 连接清理问题

RAGAS_TESTSET_TRANSFORMS=single_hop_entities 会让 prechunked 只运行单跳 QA 所需的实体抽取 transform；设为 default 可回到 Ragas 默认 prechunked transforms


测试集生成模式

TESTSET_RAGAS_MODE 控制 05_generate_testset.py 如何用 Ragas 生成 QA：


direct：工程兜底模式。脚本直接把 WeKnora chunks 构造成单跳场景，再调用 Ragas 的 single-hop sample generator 生成 QA。它跳过 Ragas 的文档 transform 和 scenario generation，最稳，但不是完整的 Ragas testset generation 流程。

prechunked：Ragas 面向“已经切好 chunk”的标准入口，对应 generate_with_chunks()。这里的 pre-chunked 指输入已经是 WeKnora 导出的 chunk，不需要 Ragas 再从原始文档切分。当前配置默认只启用 single_hop_entities transform，并限制为 single-hop QA，避免不相关 chunk 被组合成 multi-hop 问题。

langchain_docs：Ragas 面向 LangChain Document 的原始文档入口，对应 generate_with_langchain_docs()。它可能触发标题、摘要、拆分等默认文档预处理，不适合作为本项目主路径，只保留给对比实验。


当前推荐先用 direct 跑通评测闭环；需要验证 Ragas 标准 pre-chunked 生成链路时，再切换到 prechunked。


首轮 Pilot

把原始文件放到 data/raw_docs/，脚本会按扩展名自动识别 PDF 和 XLSX。也兼容旧目录：


data/raw_docs/*.pdf
data/raw_docs/*.xlsx
data/raw_docs/pdf/*.pdf
data/raw_docs/xlsx/*.xlsx


按顺序执行：

python scripts/00_create_kb.py
python scripts/00_check_models.py
python workflows/01_ingest_export.py
python workflows/02_generate_testset.py
python workflows/03_review_testset.py
python workflows/04_evaluate_report.py


合并后的 workflow 只调用原有脚本，不复制业务逻辑。新旧步骤对应关系：


workflows/01_ingest_export.py = scripts/01_upload_docs.py + scripts/02_wait_ingestion.py + scripts/03_export_chunks.py


workflows/02_generate_testset.py = scripts/04_parse_docs.py + scripts/05_generate_testset.py


workflows/03_review_testset.py = scripts/06_review_testset.py


workflows/04_evaluate_report.py = scripts/07_run_weknora_qa.py + scripts/08_build_ragas_input.py + scripts/09_run_ragas_eval.py + scripts/10_report.py


每个 workflow 结束时都会打印本阶段生成的文件路径。

首轮建议只使用 2 个 PDF、1 个 XLSX 和 10 条审核通过 QA，确认 retrieved_contexts、response、Ragas 输入字段都正常后再扩展样本量。

默认 04_parse_docs.py 从 WeKnora 导出的 data/exported/chunks.jsonl 构造测试集来源，不再重复调用外部 PDF 解析器。05_generate_testset.py 默认使用 Ragas 结合评估侧 LLM 自动生成 QA；生成阶段使用 TESTSET_RAGAS_MODE=direct，直接把 WeKnora chunks 组装成 Ragas KnowledgeGraph 并生成单跳 QA，避免 Ragas 默认文档预处理链路重新抽标题、摘要和实体。生成阶段还会用 TESTSET_MAX_DOCUMENT_CHARS 限制单条来源上下文长度，用 TESTSET_GENERATOR_MAX_TOKENS 控制生成输出预算，并按来源文件轮询抽样，避免测试集集中在单个文件。local、mineru 和 rule_based 只作为可选实验/兜底配置保留。


主要产物


data/exported/knowledge.jsonl
data/exported/chunks.jsonl
data/parsed_docs/documents.jsonl
data/parsed_docs/parse_summary.json
data/testsets/testset.raw.jsonl
data/testsets/testset.reviewed.jsonl
data/runs/weknora_answers.jsonl
data/runs/ragas_input.jsonl
data/reports/ragas_scores.csv
data/reports/summary.md