OpenViking Eval 模块实战指南RAG 多维评估与存储层录制回放【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking Eval 是 OpenViking 内置的 RAG 系统评估模块覆盖检索质量、生成质量、性能与存储层四个维度的量化评测并原生集成 RAGAS 等主流评测框架。本文围绕 openviking/eval/README.md 展开结合仓库源码与测试用例带你掌握从数据集构造、RAGAS 评估器调用、CLI 一键评测到存储层 IO 录制—分析—回放的完整评估工作流并理解每一层背后的实现原理。模块定位与评估能力总览Eval 模块服务于一个核心目标用可量化的方式回答OpenViking 的 RAG 效果到底怎么样。它把评估拆解为四个互补的维度检索质量评估精确度、召回率、相关性衡量检索回来的上下文是否既准确又完整生成质量评估忠实度、答案相关性衡量基于上下文的生成答案是否可信、是否切题性能评估检索速度、端到端延迟衡量检索链路的实时性存储层评估IO 操作录制与回放对比不同存储后端本地 FS、S3 远程 FS、不同向量索引后端的性能差异定位性能瓶颈。前两个维度由 RAGAS 框架集成承载第三个维度由内置 RAGEvaluator 的时序统计承载第四个维度则依赖独立的 Recorder / Playback 子模块。四者共同构成一套效果 性能 存储三位一体的评估体系。从目录结构上看模块分为三块详见 openviking/eval/init.py 与 openviking/eval/ragas/init.pyopenviking/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/ # 示例数据集其中ragas/与recorder/的边界很清晰前者面向评测后者面向存储层观测。recorder/playback.py被保留为向后兼容的模块实际回放逻辑以ragas/playback.py中的IOPlayback为准见下文存储层评估章节。核心数据类型与评估器接口评估样本三件套EvalSample / EvalDataset / EvalResult评估的数据模型由 openviking/eval/ragas/types.py 定义全部基于 pydantic 构建# 评估样本 EvalSample( query问题, context[检索上下文], response生成答案, ground_truth标准答案 ) # 评估数据集 EvalDataset(namedataset, samples[...]) # 评估结果 EvalResult(sample..., scores{faithfulness: 0.85})在实际源码中EvalSample还包含一个可选的meta字典字段Dict[str, Any]用于携带来源、文件路径等附加元数据EvalDataset额外支持description字段并实现了__len__便于直接len(dataset)。EvalResult的scores是指标名 → 分数的字典另有一个feedback字段可承载定性反馈或错误信息。当对一个数据集完成逐样本评估后会聚合出SummaryResult其字段为SummaryResult( dataset_namedataset, sample_countN, mean_scores{faithfulness: 0.85, answer_relevancy: 0.91, ...}, results[EvalResult, ...], )BaseEvaluator 抽象基类openviking/eval/ragas/base.py 定义了所有评估器的统一契约class BaseEvaluator(ABC): async def evaluate_sample(self, sample: EvalSample) - EvalResult async def evaluate_dataset(self, dataset: EvalDataset) - SummaryResult值得注意的是BaseEvaluator已经内置了数据集级评估的默认实现evaluate_dataset会遍历dataset.samples逐条调用evaluate_sample再通过_summarize对每个指标做均值聚合若数据集为空则返回sample_count0的空SummaryResult。因此子类只需实现单样本评估即可免费获得数据集聚合能力。RagasEvaluator正是这样做的——但它选择直接覆写evaluate_dataset以利用 RAGAS 的批量评估与并发能力。安装与依赖Eval 模块随 OpenViking 主包分发基础安装方式# 基础安装 pip install openviking --upgrade --force-reinstall # RAGAS 评估支持 pip install ragas datasets其中ragas与datasets仅在启用 RAGAS 指标时需要。若缺失RagasEvaluator的构造函数会抛出带有安装提示的ImportError见 openviking/eval/ragas/init.py 中evaluate_dataset与__init__的导入保护逻辑。RAGAS 评估还必须配置一个 LLM 作为评判模型支持三种配置来源按优先级排列环境变量RAGAS_LLM_API_KEY、RAGAS_LLM_API_BASE、RAGAS_LLM_MODELOpenViking 的 VLM 配置~/.openviking/ov.conf中的vlm段构造RagasEvaluator时显式传入llm参数。三者都未配置时evaluate_dataset会抛出ValueError并给出完整的三条配置指引。从源码看LLM 默认通过langchain_openai.ChatOpenAIragas.llms.LangchainLLMWrapper适配模型名缺省回退为gpt-4o-mini。用法示例RAGAS 评估示例 1Python API 编程式评估最直接的用法是构造EvalSample列表并用RagasEvaluator评估import asyncio from openviking.eval import EvalSample, EvalDataset, RagasEvaluator async def main(): # 准备评估数据 samples [ EvalSample( queryOpenViking 是什么, context[OpenViking 是上下文数据库...], responseOpenViking 是 AI Agent 数据库, ground_truthOpenViking 是开源上下文数据库 ), ] dataset EvalDataset(nameeval, samplessamples) # 运行评估可配置性能参数 evaluator RagasEvaluator( max_workers8, # 并发数 batch_size5, # 批处理大小 timeout120, # 超时时间秒 max_retries2, # 最大重试次数 ) summary await evaluator.evaluate_dataset(dataset) # 输出结果 for metric, score in summary.mean_scores.items(): print(f{metric}: {score:.2f}) asyncio.run(main())从 openviking/eval/ragas/init.py 的实现可以看到evaluate_dataset的完整执行链路把EvalDataset的query/context/response/ground_truth组装成datasets.Dataset.from_dict的 RAGAS 标准格式构造RunConfig(timeout, max_retries, max_workers)与batch_size一起传入 RAGAS 的evaluate()通过asyncio.get_event_loop().run_in_executor把同步的 RAGAS 评估调度到线程池避免阻塞事件循环从评估结果的 pandas DataFrame 中按指标名提取逐样本分数剔除 NaN 后计算均值封装为SummaryResult返回。默认启用四个指标Faithfulness、AnswerRelevancy、ContextPrecision、ContextRecall也可通过metrics参数传入自定义指标列表show_progress控制进度条raise_exceptions控制失败时是否抛出异常。示例 2CLI 工具评估CLI 入口是rag_eval.py模块路径openviking.eval.ragas.rag_eval其参数与行为详见 openviking/eval/ragas/rag_eval.py# 基础评估 # --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完整参数说明参数默认值说明--docs_dir无可多次指定文档目录或文件路径评估前通过add_resource(waitTrue, timeout300)加载进 OpenViking--code_dir无可多次指定代码仓库路径处理方式同--docs_dir--question_file必填JSONL 格式的问题文件每行需含question字段可选answer、files--config./ov.confOpenViking 配置文件路径--urlhttp://127.0.0.1:1933OpenViking HTTP 服务地址--top_k5每个问题检索的上下文条数--output无评估结果 JSON 输出路径--ragas关闭评估完成后追加运行 RAGAS 指标CLI 的评估主流程由RAGEvaluator承载它通过openviking_sdk.SyncHTTPClient连接 OpenViking 服务将docs_dir/code_dir指向的资源逐个add_resource加入再对每个问题执行client.search(query, limittop_k)检索检索结果同时聚合memories、resources、skills三类上下文并记录每次检索耗时。最终输出的metrics包含total_questions、avg_contexts_per_question、retrieval_success_rate、avg_retrieval_time_ms、total_retrieval_time_ms。若指定--ragas还会把检索结果组装成EvalSample以检索到的 content 为 context交给RagasEvaluator跑一轮忠实度与相关性评估。--question_file的解析逻辑位于load_questions()逐行读取 JSONL跳过空行缺失question字段或 JSON 非法的行会打印告警并跳过。示例 3基于本仓库的评估仓库自带一份示例问题集 openviking/eval/datasets/local_doc_example_glm5.jsonl共 19 条覆盖核心定位、分层记忆、会话生命周期、技能系统、存储架构、检索质量等主题每条包含question、files、answer。在 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--docs_dir支持重复指定可同时把docs/文档目录和README.md单文件加载进 OpenViking再基于预置问题集做端到端评估。运行前需要本地 OpenViking 服务可用默认监听127.0.0.1:1933并确保ov.conf已配置 embedding/VLM。存储层评估录制—分析—回放存储层评估是 OpenViking Eval 最有特色的能力它把一次评估过程中对FS文件系统与VikingDB向量库的全部 IO 操作录下来之后可以在任意存储后端配置下重放从而定量对比本地存储与远程存储如 S3、Volcengine VikingDB的性能差异且无需真实业务负载。IO Recorder 录制器IO Recorder 负责录制评估过程中的所有 IO 操作记录请求参数、响应结果、耗时等信息。其核心实现在 openviking/eval/recorder/recorder.pyfrom openviking.eval.recorder import init_recorder, get_recorder # 初始化录制器 init_recorder(enabledTrue) # 进行评估操作... # 操作会自动记录到 ./records/io_recorder_YYYYMMDD.jsonl # 获取统计信息 recorder get_recorder() stats recorder.get_stats() print(fTotal operations: {stats[total_count]}) print(fFS operations: {stats[fs_count]}) print(fVikingDB operations: {stats[vikingdb_count]})实现细节值得展开单例 线程安全IORecorder通过类级别的_instance与threading.Lock实现全局单例文件写入使用独立的_file_lock支持多线程并发录制记录文件命名默认目录./records文件名io_recorder_YYYYMMDD.jsonl按天滚动也可通过record_file参数指定JSON 序列化_serialize_response对 bytes 类型编码为{__bytes__: ...}对复杂对象递归转为 JSON 兼容结构确保记录文件可直接被 JSONL 工具消费双层录制RecordingVikingFSopenviking/eval/recorder/wrapper.py在 VikingFS 操作层面每条记录一条同时通过_AGFSCallCollector收集该操作内部触发的所有底层 AGFS 调用形成VikingFS 操作 → 多条 AGFS 调用的父子关系便于分析单次高层操作的开销构成编程式录制除record_fs/record_vikingdb方法外还提供RecordContext上下文管理器自动计时__enter__记开始时间__exit__计算耗时并落盘异常自动标记successFalse。支持录制的操作类型枚举定义在 openviking/eval/recorder/types.pyFS 侧有read/write/ls/stat/mkdir/rm/mv/grep/tree/globVikingDB 侧有insert/update/upsert/delete/get/exists/search/filter/create_collection/drop_collection/collection_exists/list_collections。每条IORecord含timestamp、io_type、operation、request、response、latency_ms、success、error、agfs_calls字段。Record Analysis 分析器Record Analysis 用于分析录制的 IO 操作提供全面的统计信息。入口是 openviking/eval/ragas/analyze_records.py核心统计逻辑在 openviking/eval/ragas/record_analysis.py# 分析所有记录 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分析输出分三层总体概览total_records、FS/VikingDB 操作数、总耗时、时间范围逐操作统计OperationStats每个操作类型的count、total/avg/min/max_latency_ms、成功数、失败数、成功率百分比VikingFS 细粒度统计VikingFSStats仅当记录含agfs_calls时输出包括 AGFS 调用总数、平均每次 VikingFS 操作触发的 AGFS 调用数、AGFS 总耗时/平均耗时/成功率。CLI 额外支持--quiet参数不打印详细统计以及--fs/--vikingdb与--io-type的组合过滤语义显式--io-type优先未指定时由--fs/--vikingdb推导。Playback 回放器Playback 用于回放录制的 IO 操作对比不同存储后端的性能差异。CLI 入口是 openviking/eval/ragas/play_recorder.py核心实现在 openviking/eval/ragas/playback.py# 使用远程配置回放 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 readIOPlayback的关键机制后端初始化通过--config_file指定 ov.conf解析storage.agfs与storage.vectordb配置用init_viking_fs与VikingVectorIndexBackend构建目标后端FS 与 VikingDB 可通过enable_fs/enable_vikingdb独立开关FS 操作回放按record.operation动态调用viking_fs上的同名方法{__bytes__: ...}占位符在回放时还原为真实 bytes若记录含 AGFS 调用会用_AGFSCallCollector包裹底层 AGFS 客户端回放后与录制时的调用序列逐一比对操作名、请求参数、成功状态支持check_agfs_calls开关VikingDB 操作回放对insert/update/upsert/delete/get/exists/search/filter/create_collection/drop_collection/collection_exists做了完整的参数还原与映射如insert走upsert、update先get再合并upsert、search还原 query vector / filter / limit错误语义匹配_errors_match内置了 no such file、not a directory、permission denied、already exists、timeout 等九类错误模式回放产生的同类错误视为行为一致不计为失败过滤与抽样play()支持io_type/operation过滤以及limit/offset抽样便于先小规模试跑统计输出PlaybackStats汇总成功/失败数、原始总耗时 vs 回放总耗时并计算speedup_ratio1 表示回放更快1 表示更慢CLI 中分别显示Speedup与Slowdown同时按 FS / VikingDB 操作类型输出原始平均耗时 vs 回放平均耗时对照表。存储层评估完整流程四步闭环如下对应 openviking/eval/ragas/README.md 中的流程说明录制阶段使用--recorder参数运行评估记录所有 IO 操作分析阶段使用analyze_records分析录制的记录回放阶段使用不同的配置文件回放对比性能差异分析结果查看各操作的耗时对比识别性能瓶颈# 步骤 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 回放耗时典型用法是先用本地 FS 配置跑一次完整评估并录制随后换成 S3/Volcengine 配置回放同一批记录。由于录制与回放共享完全相同的操作序列与请求参数耗时差异即为存储后端本身的性能差距可精准定位是文件系统瓶颈还是向量检索瓶颈。评估指标体系RAGAS 指标类别指标说明检索质量context_precision上下文精确度context_recall上下文召回率生成质量faithfulness答案忠实度answer_relevance答案相关性这四者是RagasEvaluator的默认指标集源码中显式导入ragas.metrics下的Faithfulness、AnswerRelevancy、ContextPrecision、ContextRecall四个类。需要其他指标时构造RagasEvaluator(metrics[...])传入即可。性能指标指标说明retrieval_time检索耗时total_latency端到端延迟这两个指标来自 CLI 评估路径RAGEvaluator.retrieve()以time.time()前后差值记录单次检索耗时评估结束后聚合为avg_retrieval_time_ms与total_retrieval_time_ms见 openviking/eval/ragas/rag_eval.py 的_calculate_metrics。端到端延迟则由各检索耗时累计得到。存储层指标操作类型说明fs.read文件读取fs.write文件写入fs.ls目录列表fs.stat文件信息fs.tree目录树遍历vikingdb.search向量搜索vikingdb.upsert向量写入vikingdb.filter标量过滤存储层指标由录制阶段产生。get_stats()会按{io_type}.{operation}组合键聚合并次数与总耗时更细粒度的 min/max/avg 耗时、成功率等则由analyze_records的OperationStats输出。实际操作类型以 openviking/eval/recorder/types.py 中的FSOperation/VikingDBOperation枚举为准FS 共 10 种、VikingDB 共 12 种。RAGAS 性能配置RAGAS 评估支持以下性能配置参数既可在构造RagasEvaluator时直接传入也可通过环境变量全局控制参数默认值环境变量说明max_workers16RAGAS_MAX_WORKERS并发 worker 数量batch_size10RAGAS_BATCH_SIZE批处理大小timeout180RAGAS_TIMEOUT超时时间秒max_retries3RAGAS_MAX_RETRIES最大重试次数环境变量配置方式# 通过环境变量配置 export RAGAS_MAX_WORKERS8 export RAGAS_BATCH_SIZE5 export RAGAS_TIMEOUT120 export RAGAS_MAX_RETRIES2 python -m openviking.eval.ragas.rag_eval --docs_dir ./docs --question_file ./questions.jsonl --ragas从源码看配置优先级为构造函数显式参数 RagasConfig 环境变量默认值。RagasConfig.from_env()openviking/eval/ragas/init.py读取上述四个环境变量生成默认配置RagasEvaluator.__init__中显式传入的max_workers等参数优先于config中的值。最终max_workers、timeout、max_retries进入 RAGAS 的RunConfigbatch_size直接传给evaluate()。实践中建议根据评判 LLM 的限流情况调节max_workers与max_retries并发过高易触发限流适当提高重试次数可提升大批量评估的稳定性。相关源码与测试索引CLI 工具openviking/eval/ragas/rag_eval.pyRAGAS 集成openviking/eval/ragas/init.py评估器基类openviking/eval/ragas/base.py数据类型openviking/eval/ragas/types.py数据集生成器openviking/eval/ragas/generator.pyRAG 查询流水线openviking/eval/ragas/pipeline.py记录分析器openviking/eval/ragas/record_analysis.py分析 CLIopenviking/eval/ragas/analyze_records.py回放器openviking/eval/ragas/playback.py回放 CLIopenviking/eval/ragas/play_recorder.pyIO 录制器openviking/eval/recorder/init.py录制器实现openviking/eval/recorder/recorder.py存储层包装器openviking/eval/recorder/wrapper.py录制类型定义openviking/eval/recorder/types.py示例数据openviking/eval/datasets/local_doc_example_glm5.jsonl测试文件tests/eval/含 test_ragas_basic.py、test_ragas_eval.py、test_ragas_validation.py、tests/storage/test_recorder.py结语OpenViking Eval 模块把RAG 效果评估与存储层性能评估统一进了一个可复现的工作流前者的核心是EvalSample → EvalDataset → RagasEvaluator → SummaryResult这条清晰的数据管线配合 RAGAS 的四项指标与max_workers/batch_size/timeout/max_retries性能参数后者的核心是rag_eval --recorder → analyze_records → play_recorder三步闭环用同一批录制的 IO 操作在不同存储后端上重放对比。评估数据通过 JSONL 保存天然可审计、可版本化既能支撑开发期的回归验证也能服务于生产环境的存储选型与性能容量规划。对于希望为自己的 RAG 系统建立量化评估体系、或对比不同存储后端成本的开发者这套模块提供了一个开箱即用的起点。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenViking Eval 模块实战指南：RAG 多维评估与存储层录制回放
OpenViking Eval 模块实战指南RAG 多维评估与存储层录制回放【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking Eval 是 OpenViking 内置的 RAG 系统评估模块覆盖检索质量、生成质量、性能与存储层四个维度的量化评测并原生集成 RAGAS 等主流评测框架。本文围绕 openviking/eval/README.md 展开结合仓库源码与测试用例带你掌握从数据集构造、RAGAS 评估器调用、CLI 一键评测到存储层 IO 录制—分析—回放的完整评估工作流并理解每一层背后的实现原理。模块定位与评估能力总览Eval 模块服务于一个核心目标用可量化的方式回答OpenViking 的 RAG 效果到底怎么样。它把评估拆解为四个互补的维度检索质量评估精确度、召回率、相关性衡量检索回来的上下文是否既准确又完整生成质量评估忠实度、答案相关性衡量基于上下文的生成答案是否可信、是否切题性能评估检索速度、端到端延迟衡量检索链路的实时性存储层评估IO 操作录制与回放对比不同存储后端本地 FS、S3 远程 FS、不同向量索引后端的性能差异定位性能瓶颈。前两个维度由 RAGAS 框架集成承载第三个维度由内置 RAGEvaluator 的时序统计承载第四个维度则依赖独立的 Recorder / Playback 子模块。四者共同构成一套效果 性能 存储三位一体的评估体系。从目录结构上看模块分为三块详见 openviking/eval/init.py 与 openviking/eval/ragas/init.pyopenviking/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/ # 示例数据集其中ragas/与recorder/的边界很清晰前者面向评测后者面向存储层观测。recorder/playback.py被保留为向后兼容的模块实际回放逻辑以ragas/playback.py中的IOPlayback为准见下文存储层评估章节。核心数据类型与评估器接口评估样本三件套EvalSample / EvalDataset / EvalResult评估的数据模型由 openviking/eval/ragas/types.py 定义全部基于 pydantic 构建# 评估样本 EvalSample( query问题, context[检索上下文], response生成答案, ground_truth标准答案 ) # 评估数据集 EvalDataset(namedataset, samples[...]) # 评估结果 EvalResult(sample..., scores{faithfulness: 0.85})在实际源码中EvalSample还包含一个可选的meta字典字段Dict[str, Any]用于携带来源、文件路径等附加元数据EvalDataset额外支持description字段并实现了__len__便于直接len(dataset)。EvalResult的scores是指标名 → 分数的字典另有一个feedback字段可承载定性反馈或错误信息。当对一个数据集完成逐样本评估后会聚合出SummaryResult其字段为SummaryResult( dataset_namedataset, sample_countN, mean_scores{faithfulness: 0.85, answer_relevancy: 0.91, ...}, results[EvalResult, ...], )BaseEvaluator 抽象基类openviking/eval/ragas/base.py 定义了所有评估器的统一契约class BaseEvaluator(ABC): async def evaluate_sample(self, sample: EvalSample) - EvalResult async def evaluate_dataset(self, dataset: EvalDataset) - SummaryResult值得注意的是BaseEvaluator已经内置了数据集级评估的默认实现evaluate_dataset会遍历dataset.samples逐条调用evaluate_sample再通过_summarize对每个指标做均值聚合若数据集为空则返回sample_count0的空SummaryResult。因此子类只需实现单样本评估即可免费获得数据集聚合能力。RagasEvaluator正是这样做的——但它选择直接覆写evaluate_dataset以利用 RAGAS 的批量评估与并发能力。安装与依赖Eval 模块随 OpenViking 主包分发基础安装方式# 基础安装 pip install openviking --upgrade --force-reinstall # RAGAS 评估支持 pip install ragas datasets其中ragas与datasets仅在启用 RAGAS 指标时需要。若缺失RagasEvaluator的构造函数会抛出带有安装提示的ImportError见 openviking/eval/ragas/init.py 中evaluate_dataset与__init__的导入保护逻辑。RAGAS 评估还必须配置一个 LLM 作为评判模型支持三种配置来源按优先级排列环境变量RAGAS_LLM_API_KEY、RAGAS_LLM_API_BASE、RAGAS_LLM_MODELOpenViking 的 VLM 配置~/.openviking/ov.conf中的vlm段构造RagasEvaluator时显式传入llm参数。三者都未配置时evaluate_dataset会抛出ValueError并给出完整的三条配置指引。从源码看LLM 默认通过langchain_openai.ChatOpenAIragas.llms.LangchainLLMWrapper适配模型名缺省回退为gpt-4o-mini。用法示例RAGAS 评估示例 1Python API 编程式评估最直接的用法是构造EvalSample列表并用RagasEvaluator评估import asyncio from openviking.eval import EvalSample, EvalDataset, RagasEvaluator async def main(): # 准备评估数据 samples [ EvalSample( queryOpenViking 是什么, context[OpenViking 是上下文数据库...], responseOpenViking 是 AI Agent 数据库, ground_truthOpenViking 是开源上下文数据库 ), ] dataset EvalDataset(nameeval, samplessamples) # 运行评估可配置性能参数 evaluator RagasEvaluator( max_workers8, # 并发数 batch_size5, # 批处理大小 timeout120, # 超时时间秒 max_retries2, # 最大重试次数 ) summary await evaluator.evaluate_dataset(dataset) # 输出结果 for metric, score in summary.mean_scores.items(): print(f{metric}: {score:.2f}) asyncio.run(main())从 openviking/eval/ragas/init.py 的实现可以看到evaluate_dataset的完整执行链路把EvalDataset的query/context/response/ground_truth组装成datasets.Dataset.from_dict的 RAGAS 标准格式构造RunConfig(timeout, max_retries, max_workers)与batch_size一起传入 RAGAS 的evaluate()通过asyncio.get_event_loop().run_in_executor把同步的 RAGAS 评估调度到线程池避免阻塞事件循环从评估结果的 pandas DataFrame 中按指标名提取逐样本分数剔除 NaN 后计算均值封装为SummaryResult返回。默认启用四个指标Faithfulness、AnswerRelevancy、ContextPrecision、ContextRecall也可通过metrics参数传入自定义指标列表show_progress控制进度条raise_exceptions控制失败时是否抛出异常。示例 2CLI 工具评估CLI 入口是rag_eval.py模块路径openviking.eval.ragas.rag_eval其参数与行为详见 openviking/eval/ragas/rag_eval.py# 基础评估 # --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完整参数说明参数默认值说明--docs_dir无可多次指定文档目录或文件路径评估前通过add_resource(waitTrue, timeout300)加载进 OpenViking--code_dir无可多次指定代码仓库路径处理方式同--docs_dir--question_file必填JSONL 格式的问题文件每行需含question字段可选answer、files--config./ov.confOpenViking 配置文件路径--urlhttp://127.0.0.1:1933OpenViking HTTP 服务地址--top_k5每个问题检索的上下文条数--output无评估结果 JSON 输出路径--ragas关闭评估完成后追加运行 RAGAS 指标CLI 的评估主流程由RAGEvaluator承载它通过openviking_sdk.SyncHTTPClient连接 OpenViking 服务将docs_dir/code_dir指向的资源逐个add_resource加入再对每个问题执行client.search(query, limittop_k)检索检索结果同时聚合memories、resources、skills三类上下文并记录每次检索耗时。最终输出的metrics包含total_questions、avg_contexts_per_question、retrieval_success_rate、avg_retrieval_time_ms、total_retrieval_time_ms。若指定--ragas还会把检索结果组装成EvalSample以检索到的 content 为 context交给RagasEvaluator跑一轮忠实度与相关性评估。--question_file的解析逻辑位于load_questions()逐行读取 JSONL跳过空行缺失question字段或 JSON 非法的行会打印告警并跳过。示例 3基于本仓库的评估仓库自带一份示例问题集 openviking/eval/datasets/local_doc_example_glm5.jsonl共 19 条覆盖核心定位、分层记忆、会话生命周期、技能系统、存储架构、检索质量等主题每条包含question、files、answer。在 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--docs_dir支持重复指定可同时把docs/文档目录和README.md单文件加载进 OpenViking再基于预置问题集做端到端评估。运行前需要本地 OpenViking 服务可用默认监听127.0.0.1:1933并确保ov.conf已配置 embedding/VLM。存储层评估录制—分析—回放存储层评估是 OpenViking Eval 最有特色的能力它把一次评估过程中对FS文件系统与VikingDB向量库的全部 IO 操作录下来之后可以在任意存储后端配置下重放从而定量对比本地存储与远程存储如 S3、Volcengine VikingDB的性能差异且无需真实业务负载。IO Recorder 录制器IO Recorder 负责录制评估过程中的所有 IO 操作记录请求参数、响应结果、耗时等信息。其核心实现在 openviking/eval/recorder/recorder.pyfrom openviking.eval.recorder import init_recorder, get_recorder # 初始化录制器 init_recorder(enabledTrue) # 进行评估操作... # 操作会自动记录到 ./records/io_recorder_YYYYMMDD.jsonl # 获取统计信息 recorder get_recorder() stats recorder.get_stats() print(fTotal operations: {stats[total_count]}) print(fFS operations: {stats[fs_count]}) print(fVikingDB operations: {stats[vikingdb_count]})实现细节值得展开单例 线程安全IORecorder通过类级别的_instance与threading.Lock实现全局单例文件写入使用独立的_file_lock支持多线程并发录制记录文件命名默认目录./records文件名io_recorder_YYYYMMDD.jsonl按天滚动也可通过record_file参数指定JSON 序列化_serialize_response对 bytes 类型编码为{__bytes__: ...}对复杂对象递归转为 JSON 兼容结构确保记录文件可直接被 JSONL 工具消费双层录制RecordingVikingFSopenviking/eval/recorder/wrapper.py在 VikingFS 操作层面每条记录一条同时通过_AGFSCallCollector收集该操作内部触发的所有底层 AGFS 调用形成VikingFS 操作 → 多条 AGFS 调用的父子关系便于分析单次高层操作的开销构成编程式录制除record_fs/record_vikingdb方法外还提供RecordContext上下文管理器自动计时__enter__记开始时间__exit__计算耗时并落盘异常自动标记successFalse。支持录制的操作类型枚举定义在 openviking/eval/recorder/types.pyFS 侧有read/write/ls/stat/mkdir/rm/mv/grep/tree/globVikingDB 侧有insert/update/upsert/delete/get/exists/search/filter/create_collection/drop_collection/collection_exists/list_collections。每条IORecord含timestamp、io_type、operation、request、response、latency_ms、success、error、agfs_calls字段。Record Analysis 分析器Record Analysis 用于分析录制的 IO 操作提供全面的统计信息。入口是 openviking/eval/ragas/analyze_records.py核心统计逻辑在 openviking/eval/ragas/record_analysis.py# 分析所有记录 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分析输出分三层总体概览total_records、FS/VikingDB 操作数、总耗时、时间范围逐操作统计OperationStats每个操作类型的count、total/avg/min/max_latency_ms、成功数、失败数、成功率百分比VikingFS 细粒度统计VikingFSStats仅当记录含agfs_calls时输出包括 AGFS 调用总数、平均每次 VikingFS 操作触发的 AGFS 调用数、AGFS 总耗时/平均耗时/成功率。CLI 额外支持--quiet参数不打印详细统计以及--fs/--vikingdb与--io-type的组合过滤语义显式--io-type优先未指定时由--fs/--vikingdb推导。Playback 回放器Playback 用于回放录制的 IO 操作对比不同存储后端的性能差异。CLI 入口是 openviking/eval/ragas/play_recorder.py核心实现在 openviking/eval/ragas/playback.py# 使用远程配置回放 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 readIOPlayback的关键机制后端初始化通过--config_file指定 ov.conf解析storage.agfs与storage.vectordb配置用init_viking_fs与VikingVectorIndexBackend构建目标后端FS 与 VikingDB 可通过enable_fs/enable_vikingdb独立开关FS 操作回放按record.operation动态调用viking_fs上的同名方法{__bytes__: ...}占位符在回放时还原为真实 bytes若记录含 AGFS 调用会用_AGFSCallCollector包裹底层 AGFS 客户端回放后与录制时的调用序列逐一比对操作名、请求参数、成功状态支持check_agfs_calls开关VikingDB 操作回放对insert/update/upsert/delete/get/exists/search/filter/create_collection/drop_collection/collection_exists做了完整的参数还原与映射如insert走upsert、update先get再合并upsert、search还原 query vector / filter / limit错误语义匹配_errors_match内置了 no such file、not a directory、permission denied、already exists、timeout 等九类错误模式回放产生的同类错误视为行为一致不计为失败过滤与抽样play()支持io_type/operation过滤以及limit/offset抽样便于先小规模试跑统计输出PlaybackStats汇总成功/失败数、原始总耗时 vs 回放总耗时并计算speedup_ratio1 表示回放更快1 表示更慢CLI 中分别显示Speedup与Slowdown同时按 FS / VikingDB 操作类型输出原始平均耗时 vs 回放平均耗时对照表。存储层评估完整流程四步闭环如下对应 openviking/eval/ragas/README.md 中的流程说明录制阶段使用--recorder参数运行评估记录所有 IO 操作分析阶段使用analyze_records分析录制的记录回放阶段使用不同的配置文件回放对比性能差异分析结果查看各操作的耗时对比识别性能瓶颈# 步骤 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 回放耗时典型用法是先用本地 FS 配置跑一次完整评估并录制随后换成 S3/Volcengine 配置回放同一批记录。由于录制与回放共享完全相同的操作序列与请求参数耗时差异即为存储后端本身的性能差距可精准定位是文件系统瓶颈还是向量检索瓶颈。评估指标体系RAGAS 指标类别指标说明检索质量context_precision上下文精确度context_recall上下文召回率生成质量faithfulness答案忠实度answer_relevance答案相关性这四者是RagasEvaluator的默认指标集源码中显式导入ragas.metrics下的Faithfulness、AnswerRelevancy、ContextPrecision、ContextRecall四个类。需要其他指标时构造RagasEvaluator(metrics[...])传入即可。性能指标指标说明retrieval_time检索耗时total_latency端到端延迟这两个指标来自 CLI 评估路径RAGEvaluator.retrieve()以time.time()前后差值记录单次检索耗时评估结束后聚合为avg_retrieval_time_ms与total_retrieval_time_ms见 openviking/eval/ragas/rag_eval.py 的_calculate_metrics。端到端延迟则由各检索耗时累计得到。存储层指标操作类型说明fs.read文件读取fs.write文件写入fs.ls目录列表fs.stat文件信息fs.tree目录树遍历vikingdb.search向量搜索vikingdb.upsert向量写入vikingdb.filter标量过滤存储层指标由录制阶段产生。get_stats()会按{io_type}.{operation}组合键聚合并次数与总耗时更细粒度的 min/max/avg 耗时、成功率等则由analyze_records的OperationStats输出。实际操作类型以 openviking/eval/recorder/types.py 中的FSOperation/VikingDBOperation枚举为准FS 共 10 种、VikingDB 共 12 种。RAGAS 性能配置RAGAS 评估支持以下性能配置参数既可在构造RagasEvaluator时直接传入也可通过环境变量全局控制参数默认值环境变量说明max_workers16RAGAS_MAX_WORKERS并发 worker 数量batch_size10RAGAS_BATCH_SIZE批处理大小timeout180RAGAS_TIMEOUT超时时间秒max_retries3RAGAS_MAX_RETRIES最大重试次数环境变量配置方式# 通过环境变量配置 export RAGAS_MAX_WORKERS8 export RAGAS_BATCH_SIZE5 export RAGAS_TIMEOUT120 export RAGAS_MAX_RETRIES2 python -m openviking.eval.ragas.rag_eval --docs_dir ./docs --question_file ./questions.jsonl --ragas从源码看配置优先级为构造函数显式参数 RagasConfig 环境变量默认值。RagasConfig.from_env()openviking/eval/ragas/init.py读取上述四个环境变量生成默认配置RagasEvaluator.__init__中显式传入的max_workers等参数优先于config中的值。最终max_workers、timeout、max_retries进入 RAGAS 的RunConfigbatch_size直接传给evaluate()。实践中建议根据评判 LLM 的限流情况调节max_workers与max_retries并发过高易触发限流适当提高重试次数可提升大批量评估的稳定性。相关源码与测试索引CLI 工具openviking/eval/ragas/rag_eval.pyRAGAS 集成openviking/eval/ragas/init.py评估器基类openviking/eval/ragas/base.py数据类型openviking/eval/ragas/types.py数据集生成器openviking/eval/ragas/generator.pyRAG 查询流水线openviking/eval/ragas/pipeline.py记录分析器openviking/eval/ragas/record_analysis.py分析 CLIopenviking/eval/ragas/analyze_records.py回放器openviking/eval/ragas/playback.py回放 CLIopenviking/eval/ragas/play_recorder.pyIO 录制器openviking/eval/recorder/init.py录制器实现openviking/eval/recorder/recorder.py存储层包装器openviking/eval/recorder/wrapper.py录制类型定义openviking/eval/recorder/types.py示例数据openviking/eval/datasets/local_doc_example_glm5.jsonl测试文件tests/eval/含 test_ragas_basic.py、test_ragas_eval.py、test_ragas_validation.py、tests/storage/test_recorder.py结语OpenViking Eval 模块把RAG 效果评估与存储层性能评估统一进了一个可复现的工作流前者的核心是EvalSample → EvalDataset → RagasEvaluator → SummaryResult这条清晰的数据管线配合 RAGAS 的四项指标与max_workers/batch_size/timeout/max_retries性能参数后者的核心是rag_eval --recorder → analyze_records → play_recorder三步闭环用同一批录制的 IO 操作在不同存储后端上重放对比。评估数据通过 JSONL 保存天然可审计、可版本化既能支撑开发期的回归验证也能服务于生产环境的存储选型与性能容量规划。对于希望为自己的 RAG 系统建立量化评估体系、或对比不同存储后端成本的开发者这套模块提供了一个开箱即用的起点。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 中间件与 `run()` 运行时搭建客户端渲染的 Remix 应用)
