first commit
This commit is contained in:
222
docs/sample-pdf-question-bank-workflow.md
Normal file
222
docs/sample-pdf-question-bank-workflow.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# `sample-pdf-question-bank` 端到端使用说明
|
||||
|
||||
这篇文档对应仓库里的真实案例：先把 PDF 解析成 question bank，再用 online evaluator 基于证据 chunk 生成答案并打分。
|
||||
|
||||
完整链路是：
|
||||
|
||||
```text
|
||||
PDFs
|
||||
-> dataset_build
|
||||
-> sample-pdf-question-bank.csv + latest/source_chunks.jsonl
|
||||
-> online adapter
|
||||
-> answer + contexts
|
||||
-> ragas metrics
|
||||
```
|
||||
|
||||
## 1. 先准备环境
|
||||
|
||||
先复制环境变量模板：
|
||||
|
||||
```powershell
|
||||
Copy-Item .env.example .env
|
||||
```
|
||||
|
||||
这条案例链路依赖两类能力：
|
||||
|
||||
- OpenAI 兼容模型
|
||||
- `OPENAI_API_KEY`
|
||||
- `OPENAI_BASE_URL`
|
||||
- 阿里云文档解析
|
||||
- `ALIBABA_ACCESS_KEY_ID`
|
||||
- `ALIBABA_ACCESS_KEY_SECRET`
|
||||
- `ALIBABA_ENDPOINT`
|
||||
|
||||
默认还会用到这些模型配置：
|
||||
|
||||
- `DATASET_GENERATOR_MODEL=qwen3.6-plus`
|
||||
- `RAGAS_JUDGE_MODEL=deepseek-v4-flash`
|
||||
- `RAGAS_EMBEDDING_MODEL=text-embedding-v3`
|
||||
|
||||
如果少了 `OPENAI_API_KEY`，dataset build 里的题库生成和 online eval 都无法运行。
|
||||
如果少了阿里云凭据，PDF 解析阶段无法运行。
|
||||
|
||||
## 2. 跑 dataset build
|
||||
|
||||
使用 sample 配置：
|
||||
|
||||
- config: [scenarios/dataset_build/sample-pdf-build.yaml](/C:/Users/A200477427/Learnings/ragas-template/scenarios/dataset_build/sample-pdf-build.yaml)
|
||||
|
||||
执行命令：
|
||||
|
||||
```powershell
|
||||
uv run main.py --dataset-build-config scenarios/dataset_build/sample-pdf-build.yaml
|
||||
or
|
||||
.\.venv\Scripts\python.exe main.py --dataset-build-config scenarios/dataset_build/sample-pdf-build.yaml
|
||||
```
|
||||
|
||||
这一步会做四件事：
|
||||
|
||||
1. 扫描 `datasets/raw/pdfs` 下的 PDF
|
||||
2. 调用阿里云解析生成结构化 `source chunks`
|
||||
3. 调用 LLM 生成 question bank 草稿
|
||||
4. 写出稳定 dataset 和详细 run 资产
|
||||
|
||||
## 3. 看 build 产物
|
||||
|
||||
跑完以后，你会看到两类输出。
|
||||
|
||||
第一类是稳定入口，给后续 online eval 和教程使用：
|
||||
|
||||
- question bank CSV:
|
||||
[datasets/raw/generated/sample-pdf-question-bank.csv](/C:/Users/A200477427/Learnings/ragas-template/datasets/raw/generated/sample-pdf-question-bank.csv)
|
||||
- latest source chunks:
|
||||
[source_chunks.jsonl](/C:/Users/A200477427/Learnings/ragas-template/outputs/dataset-builds/sample-pdf-question-bank/latest/source_chunks.jsonl)
|
||||
- latest dataset draft:
|
||||
[dataset_draft.csv](/C:/Users/A200477427/Learnings/ragas-template/outputs/dataset-builds/sample-pdf-question-bank/latest/dataset_draft.csv)
|
||||
- latest metadata:
|
||||
[metadata.json](/C:/Users/A200477427/Learnings/ragas-template/outputs/dataset-builds/sample-pdf-question-bank/latest/metadata.json)
|
||||
|
||||
第二类是带时间戳的 run 级资产，用来审计和排查：
|
||||
|
||||
- 目录模式：
|
||||
`outputs/dataset-builds/sample-pdf-question-bank/<run_id>/`
|
||||
|
||||
其中常见文件有：
|
||||
|
||||
- `documents.jsonl`
|
||||
- `semantic_blocks.jsonl`
|
||||
- `source_chunks.jsonl`
|
||||
- `dataset_draft.csv`
|
||||
- `parse_failures.csv`
|
||||
- `metadata.json`
|
||||
|
||||
理解这个区别很重要：
|
||||
|
||||
- 稳定入口用于“继续往下跑”
|
||||
- 时间戳目录用于“回看某次具体构建”
|
||||
|
||||
## 4. question bank CSV 里是什么
|
||||
|
||||
sample build 输出的是 online-ready question bank，不是离线评测格式。
|
||||
|
||||
核心字段包括：
|
||||
|
||||
- `question`
|
||||
- `ground_truth`
|
||||
- `source_chunk_ids`
|
||||
- `doc_id`
|
||||
- `doc_name`
|
||||
|
||||
它故意不预写 `answer`。
|
||||
原因是这条链路的目标是在线评测：由 adapter 在评测时，根据 `source_chunk_ids` 去 `source_chunks.jsonl` 里取证据，再调用模型生成 `answer`。
|
||||
|
||||
## 5. 跑 online eval
|
||||
|
||||
使用 sample online scenario：
|
||||
|
||||
- scenario: [scenarios/online/sample-pdf-question-bank-online.yaml](/C:/Users/A200477427/Learnings/ragas-template/scenarios/online/sample-pdf-question-bank-online.yaml)
|
||||
- adapter: [apps/pdf_question_bank/adapter.py](/C:/Users/A200477427/Learnings/ragas-template/apps/pdf_question_bank/adapter.py)
|
||||
|
||||
执行命令：
|
||||
|
||||
```powershell
|
||||
uv run main.py --scenario scenarios/online/sample-pdf-question-bank-online.yaml
|
||||
or
|
||||
.\.venv\Scripts\python.exe main.py --scenario scenarios/online/sample-pdf-question-bank-online.yaml
|
||||
```
|
||||
|
||||
这个 scenario 的关键点有两个：
|
||||
|
||||
1. dataset 指向稳定 question bank CSV
|
||||
2. `app_adapter.static_kwargs.source_chunks_path` 指向稳定的 `latest/source_chunks.jsonl`
|
||||
|
||||
因此，只要你重新跑过 sample dataset build，online scenario 就不需要再手改时间戳路径。
|
||||
|
||||
## 6. online adapter 在做什么
|
||||
|
||||
`apps/pdf_question_bank/adapter.py` 的处理方式是固定的：
|
||||
|
||||
1. 从题库行里读取 `source_chunk_ids`
|
||||
2. 打开 `source_chunks.jsonl`
|
||||
3. 只解析被引用的 chunk
|
||||
4. 把这些 chunk 文本原样作为 `contexts`
|
||||
5. 用这些证据 prompt 模型生成 `answer`
|
||||
6. 把 `resolved_chunk_ids` 和模型响应写进 `raw_response`
|
||||
|
||||
所以评测关系是：
|
||||
|
||||
- `ground_truth` 是参考答案
|
||||
- `answer` 是运行时生成答案
|
||||
- `contexts` 是题目显式引用的证据块
|
||||
|
||||
这条链路没有单独做 retrieval。
|
||||
它评测的是“给定明确证据后，应用/模型能否稳定生成正确答案”。
|
||||
|
||||
## 7. 结果在哪里看
|
||||
|
||||
online eval 完成后，结果会写到：
|
||||
|
||||
- `outputs/online/sample-pdf-question-bank/<run_id>/`
|
||||
|
||||
常见文件包括：
|
||||
|
||||
- `scores.csv`
|
||||
- `invalid.csv`
|
||||
- `summary.md`
|
||||
- `metadata.json`
|
||||
|
||||
优先看这几个点：
|
||||
|
||||
- `scores.csv`：逐题指标分数
|
||||
- `invalid.csv`：哪些样本因为 adapter 失败或空结果被剔除了
|
||||
- `summary.md`：汇总视图
|
||||
|
||||
## 8. 常见问题
|
||||
|
||||
### `source_chunk_ids` 找不到
|
||||
|
||||
这通常表示 question bank CSV 和 `source_chunks.jsonl` 不是同一次 build 的产物。
|
||||
|
||||
正确做法：
|
||||
|
||||
1. 重新跑一次 `sample-pdf-build.yaml`
|
||||
2. 确认 `outputs/dataset-builds/sample-pdf-question-bank/latest/source_chunks.jsonl` 已更新
|
||||
3. 再运行 online scenario
|
||||
|
||||
### dataset build 成功，但 online eval 结果是 invalid
|
||||
|
||||
先看 `invalid.csv`。
|
||||
当前实现里，以下情况会进入 invalid：
|
||||
|
||||
- adapter 生成 `answer` 为空
|
||||
- adapter 返回 `contexts` 为空
|
||||
- adapter 在解析 chunk 或调模型时抛异常
|
||||
|
||||
### 只想快速看离线 smoke，不想重建题库
|
||||
|
||||
直接运行：
|
||||
|
||||
- [scenarios/offline/sample-pdf-offline-smoke.yaml](/C:/Users/A200477427/Learnings/ragas-template/scenarios/offline/sample-pdf-offline-smoke.yaml)
|
||||
|
||||
这个案例是固化好的离线 smoke dataset，不依赖 online adapter。
|
||||
|
||||
## 9. 换成你自己的 PDF 时改哪里
|
||||
|
||||
如果你要复用这条模式处理自己的 PDF，最少只改这几个点：
|
||||
|
||||
1. 复制一份 dataset build YAML
|
||||
2. 修改 `input.path` 指向你的 PDF 或 PDF 目录
|
||||
3. 修改 `output.dataset_path` 为你的 question bank CSV
|
||||
4. 修改 `output.artifact_dir` 为你的 build 资产根目录
|
||||
5. 复制一份 online scenario
|
||||
6. 修改 `dataset` 指向你的 question bank CSV
|
||||
7. 修改 `app_adapter.static_kwargs.source_chunks_path` 指向你的 `artifact_dir/latest/source_chunks.jsonl`
|
||||
|
||||
不需要改 question bank CSV 的字段结构。
|
||||
也不需要把 `answer` 预先写进 CSV。
|
||||
|
||||
如果你的 online answer 逻辑仍然是“根据显式证据块生成答案”，就可以继续复用：
|
||||
|
||||
- [apps/pdf_question_bank/adapter.py](/C:/Users/A200477427/Learnings/ragas-template/apps/pdf_question_bank/adapter.py)
|
||||
|
||||
如果你的应用是 HTTP 服务或有自己独立的 RAG 流程，再换成对应 adapter 即可。
|
||||
Reference in New Issue
Block a user