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 是评估侧模型名称


首轮 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 scripts/01_upload_docs.py
python scripts/02_wait_ingestion.py
python scripts/03_export_chunks.py
python scripts/04_parse_docs.py
python scripts/05_generate_testset.py
python scripts/06_review_testset.py
python scripts/07_run_weknora_qa.py
python scripts/08_build_ragas_input.py
python scripts/09_run_ragas_eval.py
python scripts/10_report.py


首轮建议只使用 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 控制生成输出预算，避免和后续评测用的 ragas.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