OpenViking/openviking/eval

OpenViking Eval 模块

OpenViking 的评估模块，提供 RAG 系统的多维度评估能力。

模块作用

Eval 模块支持对 RAG 系统进行全面评估：

• 检索质量评估：精确度、召回率、相关性
• 生成质量评估：忠实度、答案相关性
• 性能评估：检索速度、端到端延迟
• 框架集成：支持 RAGAS等主流评测工具
• 存储层评估：IO 操作录制与回放，对比不同存储后端性能

模块设计

openviking/eval/
├── ragas/           # RAGAS 框架集成模块（包含所有评估相关代码）
│   ├── __init__.py  # RAGAS 评估器与核心类型导出
│   ├── base.py      # 评估器基类：BaseEvaluator
│   ├── types.py     # 数据类型：EvalSample, EvalDataset, EvalResult
│   ├── generator.py # 数据集生成器
│   ├── pipeline.py  # RAG 查询流水线
│   ├── playback.py  # Playback 回放器
│   ├── record_analysis.py  # Record 分析器
│   ├── rag_eval.py  # CLI 评估工具
│   ├── play_recorder.py # Playback CLI 工具
│   └── analyze_records.py # Record 分析 CLI 工具
├── recorder/        # IO 录制器模块
│   ├── __init__.py  # IORecorder 录制器
│   ├── wrapper.py   # 存储层包装器
│   ├── async_writer.py # 异步写入器
│   ├── recording_client.py # AGFS 客户端包装器
│   └── playback.py  # 向后兼容的 playback 模块
└── datasets/        # 示例数据集

核心类型

# 评估样本
EvalSample(
    query="问题",
    context=["检索上下文"],
    response="生成答案",
    ground_truth="标准答案"
)

# 评估数据集
EvalDataset(name="dataset", samples=[...])

# 评估结果
EvalResult(sample=..., scores={"faithfulness": 0.85})

评估器接口

class BaseEvaluator(ABC):
    async def evaluate_sample(self, sample: EvalSample) -> EvalResult
    async def evaluate_dataset(self, dataset: EvalDataset) -> SummaryResult

安装方法

# 基础安装
pip install openviking --upgrade --force-reinstall

# RAGAS 评估支持
pip install ragas datasets

用法示例

示例 1：RAGAS 评估

import asyncio
from openviking.eval import EvalSample, EvalDataset, RagasEvaluator

async def main():
    # 准备评估数据
    samples = [
        EvalSample(
            query="OpenViking 是什么？",
            context=["OpenViking 是上下文数据库..."],
            response="OpenViking 是 AI Agent 数据库",
            ground_truth="OpenViking 是开源上下文数据库"
        ),
    ]
    dataset = EvalDataset(name="eval", samples=samples)
    
    # 运行评估（可配置性能参数）
    evaluator = RagasEvaluator(
        max_workers=8,      # 并发数
        batch_size=5,       # 批处理大小
        timeout=120,        # 超时时间（秒）
        max_retries=2,      # 最大重试次数
    )
    summary = await evaluator.evaluate_dataset(dataset)
    
    # 输出结果
    for metric, score in summary.mean_scores.items():
        print(f"{metric}: {score:.2f}")

asyncio.run(main())

示例 2：CLI 工具评估

# 基础评估
# --docs_dir 评估前会将指定的路径加载到 OpenViking 中
python -m openviking.eval.ragas.rag_eval \
    --docs_dir ./docs \
    --question_file ./questions.jsonl \
    --config ./ov.conf \
    --output ./results.json

# 直接评估，不加载文档库
# 启用 RAGAS 指标
python -m openviking.eval.ragas.rag_eval \
    --question_file ./questions.jsonl \
    --ragas \
    --output ./results.json

# 启用 IO 录制（用于存储层评估）
python -m openviking.eval.ragas.rag_eval \
    --docs_dir ./docs \
    --question_file ./questions.jsonl \
    --recorder \
    --output ./results.json

示例 3：基于本仓库的评估

在 OpenViking 仓库根目录下执行：

# 评估文档检索效果
python -m openviking.eval.ragas.rag_eval \
    --docs_dir ./docs \
    --docs_dir ./README.md \
    --question_file ./openviking/eval/datasets/local_doc_example_glm5.jsonl \
    --output ./eval_results.json

存储层评估

IO Recorder 录制器

IO Recorder 用于录制评估过程中的所有 IO 操作（FS、VikingDB），记录请求参数、响应结果、耗时等信息。

from openviking.eval.recorder import init_recorder, get_recorder

# 初始化录制器
init_recorder(enabled=True)

# 进行评估操作...
# 操作会自动记录到 ./records/io_recorder_YYYYMMDD.jsonl

# 获取统计信息
recorder = get_recorder()
stats = recorder.get_stats()
print(f"Total operations: {stats['total_count']}")
print(f"FS operations: {stats['fs_count']}")
print(f"VikingDB operations: {stats['vikingdb_count']}")

Record Analysis 分析器

Record Analysis 用于分析录制的 IO 操作，提供全面的统计信息。

# 分析所有记录
python -m openviking.eval.ragas.analyze_records \
    --record_file ./records/io_recorder_20260214.jsonl

# 只分析 FS 操作
python -m openviking.eval.ragas.analyze_records \
    --record_file ./records/io_recorder_20260223.jsonl \
    --fs

# 只分析 VikingDB 操作
python -m openviking.eval.ragas.analyze_records \
    --record_file ./records/io_recorder_20260214.jsonl \
    --vikingdb

# 过滤特定操作类型
python -m openviking.eval.ragas.analyze_records \
    --record_file ./records/io_recorder_20260214.jsonl \
    --io-type fs \
    --operation read

# 保存结果到文件
python -m openviking.eval.ragas.analyze_records \
    --record_file ./records/io_recorder_20260214.jsonl \
    --output analysis.json

Playback 回放器

Playback 用于回放录制的 IO 操作，对比不同存储后端的性能差异。

# 使用远程配置回放
python -m openviking.eval.ragas.play_recorder \
    --record_file ./records/io_recorder_20260223.jsonl \
    --config_file ./.local/s3/ov-local.conf \
    --output ./records/playback_results.json

# 只测试 FS 操作
python -m openviking.eval.ragas.play_recorder \
    --record_file ./records/io_recorder_20260214.jsonl \
    --config_file ./ov.conf \
    --fs

# 只测试 VikingDB 操作
python -m openviking.eval.ragas.play_recorder \
    --record_file ./records/io_recorder_20260214.jsonl \
    --config_file ./ov.conf \
    --vikingdb

# 过滤特定操作类型
python -m openviking.eval.ragas.play_recorder \
    --record_file ./records/io_recorder_20260214.jsonl \
    --config_file ./ov.conf \
    --io-type fs \
    --operation read

存储层评估流程

1. 录制阶段：使用 --recorder 参数运行评估，记录所有 IO 操作
2. 分析阶段：使用 analyze_records 分析录制的记录
3. 回放阶段：使用不同的配置文件回放，对比性能差异
4. 分析结果：查看各操作的耗时对比，识别性能瓶颈

# 步骤 1：使用本地存储录制
python -m openviking.eval.ragas.rag_eval \
    --docs_dir ./docs \
    --question_file ./questions.jsonl \
    --recorder \
    --config ./ov-local.conf

# 步骤 2：分析录制的记录
python -m openviking.eval.ragas.analyze_records \
    --record_file ./records/io_recorder_20260215.jsonl

# 步骤 3：使用远程存储回放
python -m openviking.eval.ragas.play_recorder \
    --record_file ./records/io_recorder_20260215.jsonl \
    --config_file ./ov.conf

# 步骤 4：对比分析
# 输出会显示各操作的原始耗时 vs 回放耗时

评估指标

RAGAS 指标

类别	指标	说明
检索质量	context_precision	上下文精确度
	context_recall	上下文召回率
生成质量	faithfulness	答案忠实度
	answer_relevance	答案相关性

性能指标

指标	说明
retrieval_time	检索耗时
total_latency	端到端延迟

存储层指标

操作类型	说明
fs.read	文件读取
fs.write	文件写入
fs.ls	目录列表
fs.stat	文件信息
fs.tree	目录树遍历
vikingdb.search	向量搜索
vikingdb.upsert	向量写入
vikingdb.filter	标量过滤

RAGAS 性能配置

RAGAS 评估支持以下性能配置参数：

参数	默认值	环境变量	说明
max_workers	16	RAGAS_MAX_WORKERS	并发 worker 数量
batch_size	10	RAGAS_BATCH_SIZE	批处理大小
timeout	180	RAGAS_TIMEOUT	超时时间（秒）
max_retries	3	RAGAS_MAX_RETRIES	最大重试次数

# 通过环境变量配置
export RAGAS_MAX_WORKERS=8
export RAGAS_BATCH_SIZE=5
export RAGAS_TIMEOUT=120
export RAGAS_MAX_RETRIES=2

python -m openviking.eval.ragas.rag_eval --docs_dir ./docs --question_file ./questions.jsonl --ragas

相关文件

• CLI 工具：rag_eval.py
• RAGAS 集成：ragas/__init__.py
• 评估器基类：ragas/base.py
• 数据类型：ragas/types.py
• 数据集生成器：ragas/generator.py
• RAG 查询流水线：ragas/pipeline.py
• 记录分析器：ragas/record_analysis.py
• 分析 CLI：ragas/analyze_records.py
• 回放器：ragas/playback.py
• 回放 CLI：ragas/play_recorder.py
• IO 录制器：recorder/__init__.py
• 示例数据：datasets/local_doc_example_glm5.jsonl
• 测试文件：tests/eval/、tests/storage/test_recorder.py