OpenViking Observer API 运行观测指南队列、向量库、模型、锁与检索的组件级健康监控【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingObserver API 是 OpenViking 内置的组件级观测入口通过一组无参数 HTTP 端点即可实时获取队列、VikingDB 向量库、模型子系统VLM / embedding / rerank、分布式锁、检索质量与文件系统操作的即时状态。本文以官方 API 文档为主体结合仓库源码与测试用例完整讲解 7 个 observer 端点的接口语义、健康判定规则、多语言 SDK 与 CLI 调用方式帮助你在排查故障与日常巡检时快速定位组件异常。Observer API 总览Observer API 的核心价值在于把分散在存储层、模型层、检索层的运行时状态统一收敛为结构化的健康快照。从源码结构看它由三层组成HTTP 路由层openviking/server/routers/observer.py定义了以/api/v1/observer为前缀的 7 个端点统一挂载在 FastAPI 路由器上每个端点依赖get_request_context完成请求鉴权服务层openviking/service/debug_service.py中的ObserverService负责把路由调用映射到具体的观察者实现并以统一的ComponentStatus/SystemStatus数据类返回结果观察者层openviking/storage/observers/目录下的QueueObserver、VikingDBObserver、ModelsObserver、RetrievalObserver、FilesystemObserver分别继承抽象基类BaseObserver各自实现get_status_table()、is_healthy()、has_errors()三个方法。BaseObserverbase_observer.py定义了观察者的统一接口get_status_table()将状态格式化为可读的表格字符串is_healthy()判断被观测系统是否健康has_errors()判断是否存在错误。而ComponentStatusdebug_service.py则是所有端点响应中的统一结构包含四个字段字段类型说明namestr组件名称queue / vikingdb / models / lock / retrieval / filesystemis_healthybool组件是否健康has_errorsbool组件是否存在错误statusstr组件状态表格字符串所有端点的 HTTP 响应都遵循统一的Response包装格式外层包含status恒为ok、result上述ComponentStatus或SystemStatus的字典与time本次查询耗时秒。服务端默认端口与鉴权Observer 端点默认通过 OpenViking HTTP 服务暴露示例中服务地址为http://localhost:1933。所有查询都需要携带 API Key即请求头X-API-Key: your-key未通过鉴权的请求会被路由层的get_request_context依赖拦截相关鉴权测试见 tests/server/test_auth.py。observer.queue队列系统状态API 实现介绍获取队列系统状态embedding 与语义处理队列展示各队列的待处理Pending、进行中In Progress、已完成Processed和错误Errors数量。代码入口openviking/server/routers/observer.py:observer_queue— HTTP 路由openviking/service/debug_service.py:ObserverService.queue— 核心实现openviking/storage/observers/queue_observer.py— 队列观察者接口和参数说明无参数。源码实现要点ObserverService.queue首先通过get_queue_manager()获取队列管理器若尚未初始化则返回Not initialized的异常状态。正常路径下QueueObserver调用队列管理器的check_status()获取各命名队列的QueueStatus并额外统计语义队列Semantic的 DAG 处理进度pending_nodes、in_progress_nodes、done_nodes、total_nodes。值得注意的是源码生成的表格比文档示例更完整除了 Pending / In Progress / Processed / Errors 之外还包含Requeued重入队次数列以及一行Semantic-Nodes语义队列的 DAG 节点统计最后以 TOTAL 汇总行结束见 queue_observer.py。健康判定规则QueueObserver._has_active_errors当某个队列的error_count 0且队列尚未完成not status.is_complete时判定为存在活跃错误即has_errors Trueis_healthy not has_errors。使用示例HTTP APIGET /api/v1/observer/queuecurl -X GET http://localhost:1933/api/v1/observer/queue \ -H X-API-Key: your-keyPython SDKprint(client.observer.queue()) # 输出: # [queue] (healthy) # Queue Pending In Progress Processed Errors Total # Embedding 0 0 10 0 10 # Semantic 0 0 10 0 10 # TOTAL 0 0 20 0 20TypeScript SDKconsole.log(await client.queueStatus());TypeScript SDK 中queueStatus()直接请求/api/v1/observer/queue端点见 sdk/typescript/src/client.ts。Go SDKstatus, err : client.QueueStatus(ctx) if err ! nil { return err } fmt.Println(status[is_healthy])Go SDK 的QueueStatus同样封装了对/api/v1/observer/queue的调用见 sdk/go/system.go。CLIov observer queue响应示例{ status: ok, result: { name: queue, is_healthy: true, has_errors: false, status: Queue Pending In Progress Processed Errors Total\nEmbedding 0 0 10 0 10\nSemantic 0 0 10 0 10\nTOTAL 0 0 20 0 20 }, time: 0.1 }observer.vikingdb向量库状态API 实现介绍获取 VikingDB 状态集合、索引、向量数量。代码入口openviking/server/routers/observer.py:observer_vikingdb— HTTP 路由openviking/service/debug_service.py:ObserverService.vikingdb— 核心实现openviking/storage/observers/vikingdb_observer.py— VikingDB 观察者crates/ov_cli/src/commands/observer.rs— CLI 命令接口和参数说明无参数。源码实现要点VikingDBObserver首先通过collection_exists()判断集合是否存在不存在时返回No collections found。对每个集合它统计index_count与vector_count两个指标Index Count当前 OpenViking 流程中每个集合管理一个默认索引因此固定为1Vector Count通过self._vikingdb_manager.count(ctxctx)实时统计向量条数统计失败时该行状态标记为ERROR并附带错误信息。健康判定规则has_errors通过run_async(self._vikingdb_manager.health_check())检测健康检查抛出异常即视为有错误is_healthy not has_errors。因此该端点不仅能反映向量是否存在更能反映向量库服务本身是否可用见 vikingdb_observer.py。使用示例HTTP APIGET /api/v1/observer/vikingdbcurl -X GET http://localhost:1933/api/v1/observer/vikingdb \ -H X-API-Key: your-keyPython SDKprint(client.observer.vikingdb()) # 输出: # [vikingdb] (healthy) # Collection Index Count Vector Count Status # context 1 55 OK # TOTAL 1 55 # 访问特定属性 print(client.observer.vikingdb().is_healthy) # True print(client.observer.vikingdb().status) # 状态表字符串TypeScript SDKconsole.log(await client.vikingDBStatus());Go SDKstatus, err : client.VikingDBStatus(ctx) if err ! nil { return err } fmt.Println(status[is_healthy])CLIov observer vikingdb响应示例{ status: ok, result: { name: vikingdb, is_healthy: true, has_errors: false, status: Collection Index Count Vector Count Status\ncontext 1 55 OK\nTOTAL 1 55 }, time: 0.1 }observer.models模型子系统聚合状态API 实现介绍获取模型子系统的聚合状态VLM、embedding、rerank检查各模型提供者是否健康可用。代码入口openviking/server/routers/observer.py:observer_models— HTTP 路由openviking/service/debug_service.py:ObserverService.models— 核心实现openviking/storage/observers/models_observer.py— 模型观察者crates/ov_cli/src/commands/observer.rs— CLI 命令接口和参数说明无参数。源码实现要点ObserverService.models从配置对象OpenVikingConfig中依次构建三个模型实例VLM通过self._config.vlm.get_vlm_instance()获取Embedding当self._config.embedding存在时通过get_embedder()获取Rerank当self._config.rerank配置存在且is_available()为真时通过RerankClient.from_config()构建。ModelsObserver的核心能力是按模型 × 提供者维度输出 token 用量统计见 models_observer.py。对每个模型实例它会优先调用get_token_usage()或_token_tracker.to_dict()读取累计的调用数据表格列包括Model、Provider、Calls、Prompt、Completion、Total、Last Updated。当 VLM 无用量数据时会退化为展示已配置模型身份Status: configured作为兜底。健康判定规则值得注意is_healthy只要VLM、embedding、rerank 三者中至少有一个实例可用即为 Truehas_errors恒为 Falsetoken 用量统计本身不跟踪错误。这意味着 models 端点反映的是模型子系统是否已正确配置并可用而非各提供者实时调用是否报错。使用示例HTTP APIGET /api/v1/observer/modelscurl -X GET http://localhost:1933/api/v1/observer/models \ -H X-API-Key: your-keyPython SDKprint(client.observer.models()) # 输出: # [models] (healthy) # provider_model healthy detail # dense_embedding yes ... # rerank yes ... # vlm yes ...TypeScript SDKconsole.log(await client.modelsStatus());Go SDKstatus, err : client.ModelsStatus(ctx) if err ! nil { return err } fmt.Println(status[is_healthy])CLIov observer models响应示例{ status: ok, result: { name: models, is_healthy: true, has_errors: false, status: provider_model healthy detail\ndense_embedding yes ...\nrerank yes ...\nvlm yes ... }, time: 0.1 }observer.lock分布式锁系统状态API 实现介绍获取分布式锁系统状态。代码入口openviking/server/routers/observer.py:observer_lock— HTTP 路由openviking/service/debug_service.py:ObserverService.lock— 核心实现接口和参数说明无参数。源码实现要点lock 端点与其它组件不同它没有独立的观察者类而是通过 RAGFS 底层的pathlock_observe()快照实现见 debug_service.py。ObserverService.lock通过get_viking_fs()获取文件系统实例调用viking_fs._async_agfs.pathlock_observe()得到锁子系统快照并整理为四行状态Active locks当前活跃的锁数量Waiting locks等待中的锁数量Stale locks removed已清理的过期锁数量Conflicts检测到的锁冲突数量。健康判定规则冲突数与过期锁清理数属于保留的诊断信息而非当前故障因此该端点is_healthy恒为 True、has_errors恒为 False一旦pathlock_observe()调用异常例如 RAGFS 未就绪则返回Not initialized且标记为不健康。使用示例HTTP APIGET /api/v1/observer/lockcurl -X GET http://localhost:1933/api/v1/observer/lock \ -H X-API-Key: your-key注意公开 SDK 和 CLI 目前没有单独的 lock observer 方法。请使用 HTTP API 查询该组件ov observer system会在汇总状态中包含它。响应示例{ status: ok, result: { name: lock, is_healthy: true, has_errors: false, status: ... }, time: 0.1 }observer.retrieval检索质量指标API 实现介绍获取检索质量指标。代码入口openviking/server/routers/observer.py:observer_retrieval— HTTP 路由openviking/service/debug_service.py:ObserverService.retrieval— 核心实现openviking/storage/observers/retrieval_observer.py— 检索观察者crates/ov_cli/src/commands/observer.rs— CLI 命令接口和参数说明无参数。源码实现要点RetrievalObserver不直接访问存储层而是读取HierarchicalRetriever累积的检索诊断数据通过openviking.retrieve.retrieval_stats的get_stats_collector()惰性获取避免循环依赖。其snapshot()输出的指标包括见 retrieval_observer.py指标含义Total Queries累计检索查询次数Total Results累计返回结果条数Avg Results/Query平均每次查询结果数Zero-Result Queries / Rate空结果查询次数与占比Avg / Min / Max Score结果得分分布最小值 - 最大值Rerank Used / Rerank Fallback重排使用次数与降级次数Avg / Max Latency (ms)检索平均与最大延迟Queries by Context Type按上下文类型的查询次数分布按次数降序健康判定规则非常明确空检索结果是合法结果结果数量与得分仅为诊断信息不决定组件健康状态。因此is_healthy恒为 True、has_errors恒为 False。当total_queries 0时状态表返回No retrieval queries recorded.。使用示例HTTP APIGET /api/v1/observer/retrievalcurl -X GET http://localhost:1933/api/v1/observer/retrieval \ -H X-API-Key: your-keyCLIov observer retrieval响应示例{ status: ok, result: { name: retrieval, is_healthy: true, has_errors: false, status: ... }, time: 0.1 }observer.filesystem文件系统操作指标API 实现介绍获取文件系统操作指标。代码入口openviking/server/routers/observer.py:observer_filesystem— HTTP 路由openviking/service/debug_service.py:ObserverService.filesystem— 核心实现openviking/storage/observers/filesystem_observer.py— 文件系统观察者crates/ov_cli/src/commands/observer.rs— CLI 命令接口和参数说明无参数。源码实现要点FilesystemObserver读取 RAGFS 累积的操作统计通过ObserverService.get_filesystem_stats转发到_agfs_client.get_stats并按挂载点Mount逐项展示见 filesystem_observer.py。每个挂载点的输出包含挂载路径与插件名Mount: path (plugin: name)各操作类型的统计表Operation、Count、Avg (ms)、Min (ms)、Max (ms)汇总行Total Operations、Total Time (s)、Overall Avg (ms)。若统计为空则返回No filesystem statistics available.若 RAGFS 客户端未就绪则返回空统计。健康判定规则当前版本is_healthy与has_errors分别恒为 True / False除非出现统计获取异常此时状态字符串会携带错误信息。使用示例HTTP APIGET /api/v1/observer/filesystemcurl -X GET http://localhost:1933/api/v1/observer/filesystem \ -H X-API-Key: your-keyCLIov observer filesystem响应示例{ status: ok, result: { name: filesystem, is_healthy: true, has_errors: false, status: ... }, time: 0.1 }observer.system整体系统状态API 实现介绍获取整体系统状态包括所有组件queue、vikingdb、models、lock、retrieval、filesystem。代码入口openviking/server/routers/observer.py:observer_system— HTTP 路由openviking/service/debug_service.py:ObserverService.system— 核心实现crates/ov_cli/src/commands/observer.rs— CLI 命令接口和参数说明无参数。源码实现要点ObserverService.system将 6 个组件queue、vikingdb、models、lock、retrieval、filesystem的状态聚合为SystemStatus见 debug_service.py。聚合规则errors收集所有has_errors为 True 的组件格式为name has errorsis_healthy仅当所有组件的is_healthy都为 True 时系统才健康all(...)。由于 retrieval、filesystem、lock 三个组件默认恒为健康实际决定系统级健康状态的通常是 queue队列活跃错误、vikingdb向量库健康检查与 models至少一个模型实例可用。此外ObserverService.is_healthy()还提供了DebugService.is_healthy()的快捷健康检查依赖未就绪vikingdb 或 config 缺失时直接返回 False可用于探活场景。使用示例HTTP APIGET /api/v1/observer/systemcurl -X GET http://localhost:1933/api/v1/observer/system \ -H X-API-Key: your-keyPython SDKprint(client.observer.system()) # 输出: # [queue] (healthy) # ... # # [vikingdb] (healthy) # ... # # [models] (healthy) # ... # # [system] (healthy)TypeScript SDKconsole.log(await client.getStatus());TypeScript SDK 中getStatus()请求/api/v1/observer/system同时提供isHealthy()便捷方法判断is_healthy true见 sdk/typescript/src/client.ts。Go SDKstatus, err : client.GetStatus(ctx) if err ! nil { return err } fmt.Println(status[is_healthy])CLIov observer system响应示例{ status: ok, result: { is_healthy: true, errors: [], components: { queue: { name: queue, is_healthy: true, has_errors: false, status: ... }, vikingdb: { name: vikingdb, is_healthy: true, has_errors: false, status: ... }, models: { name: models, is_healthy: true, has_errors: false, status: ... }, lock: { name: lock, is_healthy: true, has_errors: false, status: ... }, retrieval: { name: retrieval, is_healthy: true, has_errors: false, status: ... }, filesystem: { name: filesystem, is_healthy: true, has_errors: false, status: ... } } }, time: 0.1 }各组件健康判定规则速查组件is_healthy 判定has_errors 判定数据来源queue无活跃错误error_count 0且未完成即健康存在活跃错误时为 True队列管理器check_status() 语义 DAG 统计vikingdb健康检查不抛异常健康检查抛异常时为 True集合存在性、向量计数、health_check()modelsVLM / embedding / rerank 至少一个实例可用恒为 False模型实例 token 用量统计lock快照获取成功即健康恒为 False冲突与过期锁仅为诊断信息RAGFSpathlock_observe()快照retrieval恒为 True恒为 False空检索是合法结果HierarchicalRetriever累积统计filesystem恒为 True当前版本恒为 False当前版本RAGFS 挂载点操作统计验证与测试Observer API 的行为在仓库测试中有直接覆盖tests/server/test_api_observer.py 验证了queue、vikingdb、models、system四个端点返回 200 及结构化结果tests/api_test/api/client.py 封装了对应的 API 客户端查询方法tests/server/test_auth.py 验证了/api/v1/observer/system在启用鉴权时的访问控制行为。CLI 命令ov observer queue|vikingdb|models|retrieval|filesystem|system的实现见 crates/ov_cli/src/commands/observer.rs其内部即是对上述 HTTP 端点的封装调用。相关文档Metrics — Prometheus 指标抓取面向长期监控与指标可视化系统状态 — 健康检查和一致性检查提供Health、CheckConsistency等更粗粒度的探活能力。实际运维中可将三者组合使用用/health做基础探活、用 Observer API 做组件级故障定位、用 Prometheus 指标做趋势观测。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考