OpenViking增加评估模块，欢迎讨论

[chuanbao666]

关于OpenViking性能评估，考虑增加一个eval模块

目前ov正在快速迭代，但缺少对性能（检索效果、速度）的评估方法，很难评估迭代的性能提升。参考LangChain、LlamaIndex与一些调研，打算增加一个评估模块。目前先关注检索问答效果、速度等方面。

• 暂时先针对检索问答场景，先搞两个小型测试集（代码库测试集、文档库测试集），基本OpenViking自身仓库与文档，各挑选20个问题，并让oc来回答这些问题，生成最后的评测集，主要用于日常的迭代验证（oc是用推理+关键字来检索，准确性相比单纯embeding方式应该更高，依此作为基线来验证ov的检索性能）
• eval模块可对接ragas，后续方便集成一些公开的评测集
• eval模型后面评估维度会增加速度、token用量等
• 相关代码见 feat/eval分支

大家有啥想法或建议，欢迎讨论~

---

OpenViking Eval 模块

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

模块作用

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

• 检索质量评估：精确度、召回率、相关性
• 生成质量评估：忠实度、答案相关性
• 性能评估：检索速度、端到端延迟
• 框架集成：支持 RAGAS、TruLens 等主流评测工具

模块设计

openviking/eval/
├── types.py         # 数据类型：EvalSample, EvalDataset, EvalResult
├── base.py          # 评估器基类：BaseEvaluator
├── ragas.py         # RAGAS 框架集成
├── generator.py     # 数据集生成器
├── pipeline.py      # RAG 查询流水线
├── rag_eval.py      # CLI 评估工具
└── 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

# 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()
    summary = await evaluator.evaluate_dataset(dataset)
    
    # 输出结果
    for metric, score in summary.mean_scores.items():
        print(f"{metric}: {score:.2f}")

asyncio.run(main())

示例 2：CLI 工具评估

# 基础评估
python -m openviking.eval.rag_eval \
    --docs_dir ./docs \
    --question_file ./questions.jsonl \
    --output ./results.json

# 启用 RAGAS 指标
python -m openviking.eval.rag_eval \
    --docs_dir ./docs \
    --question_file ./questions.jsonl \
    --ragas \
    --output ./results.json

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

在 OpenViking 仓库根目录下执行：

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

评估指标

类别	指标	说明
检索质量	context_precision	上下文精确度
	context_recall	上下文召回率
生成质量	faithfulness	答案忠实度
	answer_relevance	答案相关性
性能指标	retrieval_time	检索耗时
	total_latency	端到端延迟

相关文件

• CLI 工具：rag_eval.py
• 示例数据：datasets/local_doc_example_glm5.jsonl
• 测试文件：tests/eval/

[ZaynJarvis]

在 openviking 接入其他 agent 如 opencode/openclaw 之后的评估手段，会在这里讨论吗

[chuanbao666]

也可以这里讨论，增加评估模块只是一个开头，后续其他场景、维度的评估都可以加进来

[shaoeric]

1. 目前看起来只有最终response的评估，是否可以增加 L1 L2 L3 三级的 recall和precision的指标计算
2. 目前是离线评估，即已有问题、上下文、回答，是否可以增加在线评估接口，只有问题jsonl，模型自己去dataset中检索对应的上下文，并生成回答，最后做评估 输出报告
3. 对比基线：希望增加竞品结果对比，相同llm或者相同vlm场景下，纯embedding、oc、ragflow、page index，至少第一个版本需要多个产品对比，后续发版只需要自身对比

[chuanbao666]

1. 针对rag场景先开个头。要体现viking fs设计优势，分层的recall、precision是有必要的，后面要加上
2. 在线评估可以考虑一下，还得看看大模型评估的成本、速度、稳定性（在大型datasets，llm不借助索引手段来检索的话，成本会很高，小型dataset似乎没必要）
3. 与竞品的对比是要加上的

[shaoeric]

在线评估 提供接口 并保证结果正确 服务稳定即可

[shaoeric]

4. 希望还能自己定义custom eval方法，比如单选 多选，语义相似等，目前其他评估框架的问题是比较混乱 想自定义扩展比较困难，希望能做到verl的score和 batch score的定义方式，并以metrics字典形式返回