OpenViking RAG Benchmark 实战：从零搭建 RAG 检索增强生成评估流水线

OpenViking RAG Benchmark 实战：从零搭建 RAG 检索增强生成评估流水线

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

OpenViking 仓库在benchmark/RAG/下内置了一个独立的 RAG（检索增强生成）系统评估框架，用于量化 OpenViking 在文档摄取、向量检索与答案生成全链路上的表现。本文基于 benchmark/RAG/README_zh.md 展开，并结合pipeline.py、vector_store.py、metrics.py等源码实现，带你完成数据集准备、配置调优、分阶段运行、结果判读与实验复现的完整闭环，读完后可独立用 4 个标准数据集（Locomo、SyllabusQA、Qasper、FinanceBench）对 OpenViking 的 RAG 能力做可复现的基准评测。

框架定位与项目结构

RAG Benchmark 是一个独立的评估框架，完全兼容最新版本的 OpenViking。它的职责边界很清晰：Benchmark 自身不管理任何向量存储，而是通过 Python HTTP SDK 连接一个由配置决定的 OpenViking Server，内容和向量索引的存储位置完全由 Server 侧管理。

目录结构如下（位于benchmark/RAG/）：

benchmark/RAG/ ├── src/ # 源代码 │ ├── __init__.py │ ├── pipeline.py # 评估核心流水线 │ ├── adapters/ # 数据集适配器 │ │ ├── base.py # 基础适配器类 │ │ ├── locomo_adapter.py # Locomo 数据集适配器 │ │ ├── syllabusqa_adapter.py # SyllabusQA 数据集适配器 │ │ ├── qasper_adapter.py # Qasper 数据集适配器 │ │ └── financebench_adapter.py # FinanceBench 数据集适配器 │ └── core/ # 核心组件 │ ├── logger.py # 日志模块 │ ├── vector_store.py # 向量存储包装器 │ ├── llm_client.py # LLM 客户端包装器 │ ├── metrics.py # 指标计算 │ ├── judge_util.py # LLM 评判工具 │ └── monitor.py # 监控工具 ├── config/ # 配置文件 │ ├── config.yaml # 主配置文件 │ ├── locomo_config.yaml # Locomo 数据集配置 │ ├── syllabusqa_config.yaml # SyllabusQA 数据集配置 │ ├── qasper_config.yaml # Qasper 数据集配置 │ └── financebench_config.yaml # FinanceBench 数据集配置 ├── scripts/ # 工具脚本 │ ├── download_dataset.py # 数据集下载脚本 │ ├── sample_dataset.py # 数据集抽样脚本 │ ├── prepare_dataset.py # 统一数据集准备脚本 │ └── run_sampling.py # 自定义抽样脚本 ├── raw_data/ # 原始数据集目录（下载） ├── datasets/ # 抽样数据集目录 ├── Output/ # 输出结果目录 ├── run.py # 主执行脚本 └── README.md

快速开始

1. 安装依赖

在仓库根目录执行：

cd OpenViking uv pip install -e ".[benchmark]" source .venv/bin/activate

2. 数据集准备工作流

数据集准备分为两个步骤：

1. 下载：从官方源下载原始数据集到raw_data/目录
2. 抽样：从原始数据集抽样（可选）到datasets/目录

原始数据源 → 下载 → raw_data/{dataset_name}/ → 抽样 → datasets/{dataset_name}/

下载数据集（download_dataset.py）：

cd benchmark/RAG # 下载所有配置的数据集 python scripts/download_dataset.py # 下载特定数据集 python scripts/download_dataset.py --dataset Locomo # 强制重新下载，即使已存在 python scripts/download_dataset.py --dataset Locomo --force

抽样数据集（sample_dataset.py）：

# 抽样所有数据集（使用完整数据集，不抽样） python scripts/sample_dataset.py # 抽样特定数据集（使用完整数据集，不抽样） python scripts/sample_dataset.py --dataset Locomo # 按 QA 数量抽样 python scripts/sample_dataset.py --dataset Locomo --sample-size 100 # 按文档数量抽样（推荐） python scripts/sample_dataset.py --dataset Locomo --num-docs 5 # 使用完整数据集（显式，不抽样） python scripts/sample_dataset.py --dataset Locomo --full # 指定随机种子（可重现） python scripts/sample_dataset.py --dataset Locomo --num-docs 5 --seed 42

抽样策略有三种：

1. 文档级抽样（推荐）：--num-docs N先抽 N 个文档，保留文档中的所有 QA；
2. QA 级抽样：--sample-size N随机选择文档，直到 QA 计数达到 N；
3. 完整数据集：--full或不指定抽样参数。

从 run_sampling.py 源码可以看到，官方基准测试使用的是一组固定的**分层抽样（stratified）**参数，全部使用seed=42保证可重现性：

一键准备（prepare_dataset.py）一步完成下载和抽样：

# 准备所有数据集（使用完整数据集，不抽样） python scripts/prepare_dataset.py # 准备特定数据集，抽样 5 个文档 python scripts/prepare_dataset.py --dataset Locomo --num-docs 5 # 使用完整数据集（显式，不抽样） python scripts/prepare_dataset.py --dataset Locomo --full # 跳过下载，只抽样现有数据 python scripts/prepare_dataset.py --dataset Locomo --num-docs 5 --skip-download # 跳过抽样，只下载 python scripts/prepare_dataset.py --dataset Locomo --skip-sampling

3. 更新配置文件中的 dataset_path

准备数据集后，需要更新评估配置文件中的paths.dataset_path。配置文件位于benchmark/RAG/config/，各数据集示例：

• Locomo：dataset_path: "datasets/Locomo/locomo10.json"
• SyllabusQA：dataset_path: "datasets/SyllabusQA"（目录）
• Qasper：dataset_path: "datasets/Qasper"（目录）
• FinanceBench：dataset_path: "datasets/FinanceBench/financebench_open_source.jsonl"

注意：对 SyllabusQA、Qasper 这类多文件数据集，dataset_path应指向目录，适配器会自动查找并加载所有相关文件。

以 locomo_config.yaml 为例，配置中支持{dataset_name}和{retrieval_topk}模板变量：

project_name: "RAG_Benchmark" # ===========Modify Configuration================ dataset_name: "Locomo" adapter: module: "src.adapters.locomo_adapter" class_name: "LocomoAdapter" execution: max_workers: 8 ingest_workers: 8 retrieval_topk: 5 max_queries: 20 skip_ingestion: false ingest_mode: "directory" retrieval_instruction: "" # ================================== paths: dataset_path: "datasets/{dataset_name}/locomo10.json" doc_output_dir: "ov_storage/{dataset_name}/{dataset_name}_processed_docs" output_dir: "Output/{dataset_name}/experiment_test_top_{retrieval_topk}" log_file: "Output/{dataset_name}/experiment_test_top_{retrieval_topk}/benchmark.log" llm: model: "doubao-seed-2-0-pro-260215" temperature: 0 base_url: "https://ark.cn-beijing.volces.com/api/v3" api_key: "your_api_key_here"

从 run.py 源码看，这些模板变量会在启动时用当前配置的dataset_name与retrieval_topk渲染，随后统一解析为相对于benchmark/RAG/目录的绝对路径。这意味着你调整retrieval_topk后，输出目录experiment_test_top_{retrieval_topk}会自动区分不同 Top-K 实验，互不覆盖。

4. 配置 LLM

llm配置段中的模型同时承担两个角色：

• 答案生成：从检索到的上下文生成答案；
• LLM 作为评判者（LLM-as-judge）：评估生成答案与黄金答案的匹配度。

从 llm_client.py 源码看，底层通过langchain_openai.ChatOpenAI封装，因此任何兼容 OpenAI 接口（base_url+api_key）的服务都可以接入；生成失败时会进行 3 次线性退避重试，仍失败则抛出RuntimeError终止当前任务。api_key支持配置文件中直接给出，也可通过api_key_env_var指定的环境变量注入（见 run.py），后者更利于避免密钥进入版本控制。

5. 配置 OpenViking

如需自定义 OpenViking 配置（用于数据摄取和检索），在benchmark/RAG目录中创建ov.conf文件即可覆盖默认设置。从 run.py 源码确认：启动时若检测到该文件，会自动设置环境变量OPENVIKING_CONFIG_FILE指向它。

配置格式可参考仓库根目录的 examples/ov.conf.example，benchmark/RAG/目录下也提供了一份针对 Benchmark 场景的 ov.conf.example，其中声明了摄取环节实际依赖的嵌入与 VLM 模型：

{ "storage": { "agfs": {} }, "log": { "level": "INFO", "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s", "output": "stdout" }, "embedding": { "dense": { "model": "doubao-embedding-vision-251215", "api_key": "your_api_key_here", "api_base": "https://ark.cn-beijing.volces.com/api/v3", "dimension": 1024, "provider": "volcengine", "input": "multimodal", "batch_size": 8 }, "max_concurrent": 10 }, "vlm": { "model": "doubao-seed-2-0-pro-260215", "api_key": "your_api_key_here", "api_base": "https://ark.cn-beijing.volces.com/api/v3", "temperature": 0.0, "max_retries": 240, "provider": "volcengine", "thinking": false, "max_concurrent": 64 } }

配置指南：关键参数逐项说明

RAG Benchmark 使用 YAML 配置文件控制整个评估过程。各配置段含义如下：

1. 基本配置

   • dataset_name：正在评估的数据集名称，同时参与输出路径模板渲染；

2. 适配器配置

   • adapter.module：数据集适配器的 Python 模块路径（如src.adapters.locomo_adapter）；
   • adapter.class_name：数据集适配器的类名（如LocomoAdapter）；

   从 run.py 源码看，适配器是动态加载的：框架通过importlib.import_module加载模块并用getattr取出类，模块或类名错误时会打印清晰的配置检查提示后退出。

3. 执行配置（execution）

   • max_workers：答案生成/评估阶段的并发工作线程数；
   • ingest_workers：文档摄取的工作线程数（per_file模式下生效）；
   • retrieval_topk：每个查询要检索的文档数（默认 5）；
   • max_queries：限制要处理的查询数（null= 全部）。从 pipeline.py 的_prepare_tasks可见，它在遍历 sample 的 QA 时按全局索引截断；
   • skip_ingestion：跳过文档摄取，复用已有向量索引；
   • ingest_mode：摄取模式，directory或per_file；
   • retrieval_instruction：检索的自定义指令（默认为空，详见后文高级配置）。

4. 路径配置（paths）

   • dataset_path：数据集文件或目录的路径；
   • doc_output_dir：处理后的文档输出目录；
   • output_dir：评估结果目录；
   • log_file：日志文件路径。

5. LLM 配置（llm）

   • model：模型名称；temperature：生成温度（基准测试用 0 保证确定性）；
   • base_url：API 基础地址；api_key：API 密钥（建议用环境变量替代明文）。

支持的数据集

每个数据集在config/目录中有独立的配置文件，按需选择即可：

# 使用 Locomo 数据集评估 python run.py --config config/locomo_config.yaml # 使用 SyllabusQA 数据集评估 python run.py --config config/syllabusqa_config.yaml # 使用 Qasper 数据集评估 python run.py --config config/qasper_config.yaml # 使用 FinanceBench 数据集评估 python run.py --config config/financebench_config.yaml

也可以复制一份配置文件进行自定义：

cp config/locomo_config.yaml config/my_custom_config.yaml # 编辑 config/my_custom_config.yaml python run.py --config config/my_custom_config.yaml

评估流水线：五个阶段的源码级拆解

评估过程包括 5 个主要阶段。入口脚本run.py --step支持all/gen/eval/del四种模式，分别对应流水线中 pipeline.py 的run_generation()、run_evaluation()、run_deletion()三个方法：

阶段 1：数据准备

适配器将原始数据集转换为 OpenViking 友好格式。以 locomo_adapter.py 为例，data_prepare()把 session 格式的对话 JSON 转写为带时间信息的 Markdown（每个 sample 一个{sample_id}_doc.md文件），并返回StandardDoc列表（sample_id 到文档路径的映射）。从源码结构看，load_and_transform()还会跳过 Locomo 中category == "5"的问题（对抗性类别），并为空答案填充"Not mentioned"作为黄金答案。

阶段 2：数据摄取

处理后的文档通过 OpenViking SDK 摄取进 Server 的向量存储，同时为文档创建嵌入。vector_store.py 中的VikingStoreWrapper.ingest()揭示了两种摄取模式的实际差异：

• directory模式：先对所有文档路径求公共祖先目录（os.path.commonpath），然后整个目录作为一个资源调用client.add_resource(path=common_ancestor, wait=True)。这是推荐模式——目录级摄取让 OpenViking 把整个会话/文档集当作一个整体构建层级结构；
• per_file模式：逐个文件调用add_resource，每个文件是独立文档。

无论哪种模式，SDK 都以options={"telemetry": True}请求服务端返回遥测数据，Benchmark 从中提取 LLM 输入/输出 token 与嵌入 token 统计，写入报告的Insertion Efficiency段落——这就是摄取阶段 token 开销指标的来源。

阶段 3：答案生成

对每个问题执行"检索 → 构建提示 → 生成答案"。pipeline.py 的_process_generation_task展示了完整细节：

1. 构造增强查询：若配置了retrieval_instruction，最终查询为f"{retrieval_instruction} {qa.question}"，否则直接用原始问题；
2. 检索：self.db.retrieve(query=..., topk=retrieval_topk)，底层是client.find(query, target_uri="viking://resources", limit=topk)；
3. 内容读取：对每个检索结果，若level == 2（叶子级资源）则read_resource(uri)读取全文，否则拼接该层级的abstract与overview；每个上下文块截断至前 8000 字符；
4. 召回计算：用MetricsCalculator.check_recall(retrieved_texts, qa.evidence)对照黄金证据计算召回；
5. 提示构建与生成：adapter.build_prompt(qa, context_blocks)生成完整提示，经 LLM 生成答案后由post_process_answer()后处理；
6. token 统计：输入 token = 提示 + 问题的 tiktoken（cl100k_base）计数，输出 token 为答案计数。

所有任务通过ThreadPoolExecutor(max_workers=max_workers)并发执行，任一任务异常都会被记录并在结束后抛出聚合的RuntimeError。

阶段 4：评估

读取generated_answers.json，对每条记录：

• F1：与每个黄金答案分别计算 token 级 F1，取最大值（兼容 Qasper 这类多标注者数据集）；
• Accuracy（LLM 评判）：调用 judge_util.py 的llm_grader()进行打分。评判提示按数据集路由：
  • Locomo使用Locomo_0or4提示，只允许0 或 4两档（对时间类问题要求宽松：只要指向同一日期即判 4 分）；
  • 其他数据集使用Generic_0-4提示，按 0–4 五档评分细则（4 = 完美、3 = 良好、2 = 部分正确、1 = 差、0 = 错误），且多黄金答案以" | "分隔、命中任一即可。
  • 评判输出要求是 JSON{"score": ..., "reasoning": ...}，解析失败时有正则兜底（先匹配"score": n，再匹配任意 0–4 整数）。

此外 pipeline.py 中还有一个拒绝回答启发式：若生成答案与黄金答案同时命中拒答词表（not mentioned、unknown等，见 metrics.py 的check_refusal），则直接给 F1 = 1.0、Accuracy = 4，prompt_type记为Heuristic_Refusal_Check——正确处理"不可回答"被视为成功。

阶段 5：数据删除

run_deletion()调用VikingStoreWrapper.clear()，即client.rm("viking://resources", recursive=True)，清理本次实验摄取的文档，并记录删除耗时到报告。

对应命令行用法：

cd benchmark/RAG # 运行完整评估（数据摄取、答案生成、评估和数据删除） python run.py --config config/locomo_config.yaml # 只运行数据摄取和答案生成阶段 python run.py --config config/locomo_config.yaml --step gen # 只运行评估阶段（需要前一步生成的答案） python run.py --config config/locomo_config.yaml --step eval # 只运行数据删除阶段 python run.py --config config/locomo_config.yaml --step del

评估指标与召回算法

框架输出五类指标：Recall（检索召回率）、F1 Score（答案 F1）、Accuracy（LLM 评判分 0–4）、Latency（检索延迟）、Token Usage（令牌用量）。

其中检索召回并非简单的字符串匹配。metrics.py 的check_recall采用"严格匹配 + 软匹配兜底"双层策略：

1. 将所有检索块拼接后归一化（小写、去标点、去冠词）；
2. 严格匹配：证据若作为完整子串出现，直接计命中；
3. 长度阻断：若证据的有效 token 数低于min_soft_match_tokens（默认 4，如短 ID、实体名），严格匹配失败后禁止软匹配，防止短文本被宽泛命中；
4. 软匹配兜底：对长文本证据，计算其 token 在检索文本中的覆盖率，达到soft_threshold（默认 0.8）即计命中；
5. 各证据等权，最终得分 = 命中数 / 证据总数。

答案 F1 同样是归一化后的 token 级 SQuAD 风格 F1（precision、recall 调和平均）。

输出文件与结果判读

评估结果保存在Output/目录（具体由output_dir配置决定），结构如下：

Output/ └── {dataset_name}/ └── experiment_{experiment_name}/ ├── generated_answers.json # LLM 生成的答案 ├── qa_eval_detailed_results.json # 详细评估结果 ├── benchmark_metrics_report.json # 聚合指标报告 ├── docs/ # 处理后的文档（如果 skip_ingestion=false） └── benchmark.log # 日志文件

从 pipeline.py 的_update_report可见，指标报告采用"读取已有 JSON → 合并写入"策略，因此--step gen与--step eval分步执行时，摄取统计与评估统计能自然累积到同一份报告中。

1.benchmark_metrics_report.json（摘要报告）：

{ "Insertion Efficiency (Total Dataset)": { "Total Insertion Time (s)": 131.98, "Total Input Tokens": 142849, "Total Output Tokens": 52077, "Total Embedding Tokens": 95626 }, "Query Efficiency (Average Per Query)": { "Average Retrieval Time (s)": 0.17, "Average Input Tokens": 3364.46, "Average Output Tokens": 15.5 }, "Dataset": "Locomo", "Total Queries Evaluated": 100, "Performance Metrics": { "Average F1 Score": 0.318, "Average Recall": 0.724, "Average Accuracy (Hit 0-4)": 2.36, "Average Accuracy (normalization)": 0.59 } }

字段含义：Insertion Efficiency为文档摄取性能统计（来自摄取遥测）；Query Efficiency为每个查询的性能均值；Performance Metrics为核心评估分数，其中标准化准确率 = 平均 Accuracy / 4。

2.generated_answers.json（生成的答案），单个记录示例：

{ "_global_index": 0, "sample_id": "conv-26", "question": "Would Caroline pursue writing as a career option?", "gold_answers": ["Likely no; though she likes reading, she wants to be a counselor"], "category": "3", "evidence": ["D7:5", "D7:9"], "retrieval": { "latency_sec": 0.288, "uris": ["viking://resources/...", "viking://resources/..."] }, "llm": { "final_answer": "Not mentioned" }, "metrics": { "Recall": 1.0 }, "token_usage": { "total_input_tokens": 2643, "llm_output_tokens": 2 } }

字段含义：_global_index为唯一查询标识符；retrieval.uris记录检索命中的 OpenViking 资源 URI，可用于回查命中内容；metrics.Recall为 0–1 的检索召回分；token_usage为令牌消耗统计。

3.qa_eval_detailed_results.json（详细评估），单个记录示例：

{ "_global_index": 18, "question": "When did Melanie sign up for a pottery class?", "gold_answers": ["2 July 2023"], "llm": { "final_answer": "2 July 2023 (mentioned in the conversation on 3 July 2023)" }, "metrics": { "Recall": 1.0, "F1": 0.375, "Accuracy": 4 }, "llm_evaluation": { "prompt_used": "Locomo_0or4", "reasoning": "The generated answer explicitly includes the exact date 2 July 2023 that matches the gold answer...", "normalized_score": 4 } }

字段含义：metrics.F1为答案 F1（0–1）；metrics.Accuracy为 LLM 评判分（0–4，4 = 完美）；llm_evaluation.reasoning保存评判器的推理过程；prompt_used标明使用了哪套评判提示（如Locomo_0or4、Generic_0-4或Heuristic_Refusal_Check）。

4.benchmark.log：带时间戳的详细执行日志，每条查询会输出问题摘要、Recall、延迟，评估阶段还会输出含检索 URI、双方答案与评判推理的分隔块，便于逐题排查。

5.docs/：Markdown 格式的处理后文档（skip_ingestion=false时生成），可用任意 Markdown 查看器打开。

基准测试结果参考与实验复现

以下为官方基准测试结果（top-5 检索），仅供参考：

测试配置详情：LLM 模型doubao-seed-2-0-pro-260215，API 基础地址https://ark.cn-beijing.volces.com/api/v3，温度 0（确定性输出），检索 Top-K 为 5，最大工作线程数 8，摄取工作线程数 8，摄取模式directory，检索指令为空。所有数据集使用相同的 LLM 和执行配置，特定于数据集的适配器和路径在各自 YAML 文件中配置。

复现步骤：

cd OpenViking/benchmark/RAG # 1. 安装依赖（如果尚未安装） uv pip install -e ".[benchmark]" source .venv/bin/activate # 2. 下载所有数据集 python scripts/download_dataset.py # 3. 对所有数据集运行一键抽样，使用与基准测试相同的参数 python scripts/run_sampling.py # 4. 配置您的 LLM API 密钥 # 编辑 config/ 目录下的配置文件，在 llm.api_key 字段中设置您的 API 密钥 # 5. 为每个数据集运行评估 python run.py --config config/locomo_config.yaml python run.py --config config/syllabusqa_config.yaml python run.py --config config/qasper_config.yaml python run.py --config config/financebench_config.yaml # 6. 在 Output/{dataset_name}/experiment_test_top_5/ 中查看结果

高级配置

检索指令（retrieval_instruction）

可以在配置文件中设置自定义检索指令，检索时它会被拼接到每个查询前面（对应_process_generation_task中的增强查询逻辑）。推荐格式：

# ===========Execution Configuration============ # Instruction for retrieval, empty by default # Recommended format: "Target_modality: xxx.\nInstruction:xxx.\nQuery:" retrieval_instruction: "Target_modality: text.\nInstruction:Locate the part of the conversation where the speakers discuss.\nQuery:"

格式三段各有语义：

• Target_modality: xxx.— 指定目标模态（文本、图像、音频等）；
• Instruction: xxx.— 为检索提供具体指令；
• Query:— 标记实际查询的起点。

当retrieval_instruction为空时，系统直接使用原始问题检索。

自定义数据集提示

RAG 使用"数据集 × 问题类型"粒度的提示指导 LLM 答案生成。每个适配器文件顶部都有一个CATEGORY_INSTRUCTIONS字典（如 locomo_adapter.py、syllabusqa_adapter.py、qasper_adapter.py、financebench_adapter.py），build_prompt()会按问题类别取出对应指令注入提示。

Locomo4 类问题的指令示例（类别 1，事实提取）：

Extract the exact factual answer from the conversation. - Use the exact words from the context when possible - If multiple items, separate with commas

类别 2（时间相关）要求密切关注对话中的 DATE 标签并计算相对时间；类别 3（推理）要求只基于上下文事实、只输出结论不解释推理；类别 4（理解/意义）要求识别象征与隐含意义。此外适配器定义了缺失信息规则：If no information is available to answer the question, write 'Not mentioned'，这正是评估阶段拒绝启发式能够生效的前提。

SyllabusQA覆盖 6 种问题类型：single factual、multi factual、single reasoning、multi reasoning、summarization、yes/no。Qasper覆盖 3 种答案类型：extractive（抽取式）、free_form（自由形式）、yes_no。FinanceBench覆盖 3 种问题类型：domain-relevant、metrics-generated、novel-generated。

自定义步骤：打开对应数据集的适配器文件 → 找到CATEGORY_INSTRUCTIONS字典 → 修改目标问题类型的提示文本 → 重新运行评估。

扩展：添加新数据集

接入新数据集需要实现 base.py 中BaseAdapter定义的接口：

1. 在src/adapters/中创建新的适配器类，继承BaseAdapter（构造参数为raw_file_path）；
2. 在config/中创建相应配置文件，将adapter.module/adapter.class_name指向新适配器；
3. 实现必要方法：
   • data_prepare(doc_dir)：把原始数据转换为 OpenViking 友好格式并返回List[StandardDoc]（sample_id → 文档路径）；
   • load_and_transform()：加载原始数据并转换为List[StandardSample]（含StandardQA列表：question、gold_answers、evidence、category）；
   • build_prompt(qa, context_blocks)：基于检索上下文构建完整提示，返回(full_prompt, meta)元组，meta用于后处理（例如选择题的选项映射）；
   • post_process_answer(qa, raw_answer, meta)：后处理 LLM 原始输出（基类默认仅去除首尾空白）。

由于run.py采用动态模块加载，无需修改任何框架代码即可接入。

与 OpenViking 的集成方式

• 通过 OpenViking Python HTTP SDK（openviking_sdk.SyncHTTPClient）完成数据摄取（add_resource）、检索（find）、内容读取（read）与清理（rm）；
• 通过benchmark/RAG/ov.conf或 SDK 环境变量配置 OpenViking 连接，存储位置由 Server 管理而非 Benchmark 进程；
• 该设计使 Benchmark 可以跟随 OpenViking Server 的最新能力（如层级化资源结构：检索结果的level字段决定读取全文还是摘要/概览）动态演进。

常见问题（FAQ）

问：已有向量索引，如何跳过数据摄取阶段？答：在配置文件中设置skip_ingestion: true，将复用现有向量索引。

问：可以只运行评估阶段而不重新摄取文档吗？答：可以。先运行--step gen生成答案，再运行--step eval评估。

问：收到 API 密钥错误怎么办？答：确认配置文件中llm.api_key字段设置了有效密钥（或使用api_key_env_var注入环境变量），并避免将密钥提交到版本控制。

问：如何限制处理的查询数量？答：设置max_queries为目标数量（如max_queries: 10），流水线会在构建任务列表时按全局索引截断。

问："directory" 和 "per_file" 摄取模式有什么区别？答：directory将整个目录视为一个资源（源码中是对所有文档求公共祖先后一次性add_resource），适合会话/文档集级整体摄取；per_file将每个文件视为独立文档逐个摄取。

问：如何自定义检索指令？答：设置retrieval_instruction，推荐格式"Target_modality: xxx.\nInstruction:xxx.\nQuery:"。

问：评估结果在哪里？答：在output_dir指定的目录，默认为Output/{dataset_name}/experiment_{experiment_name}/。

小结

OpenViking 的 RAG Benchmark 提供了一条"可复现、可分阶段、可扩展"的 RAG 评测路线：数据集下载与分层抽样保证实验可控，run.py --step gen/eval/del让摄取、生成、评判、清理相互解耦，VikingStoreWrapper薄封装 OpenViking SDK 使评测完全运行在真实 Server 之上，而 F1 + 严格/软双通道召回 + LLM-as-judge（Locomo 0/4 二值、通用 0–4 五档）的组合则覆盖了检索质量与答案质量两个维度。通过阅读benchmark/RAG/下的适配器与核心模块，你既可以快速复现官方基准数字，也可以按BaseAdapter接口把自有数据集纳入同一套评测体系。

该目录与 OpenViking 使用相同许可证（见仓库根目录 LICENSE）。

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking