# 运行观测 Observer API 提供队列、向量库、模型、锁、检索和文件系统等组件的即时状态。 ## Observer API Observer API 提供详细的组件级监控。 ### observer.queue #### 1. API 实现介绍 获取队列系统状态（embedding 和语义处理队列）。显示各队列的待处理、进行中、已完成和错误数量。 **代码入口**: - `openviking/server/routers/observer.py:observer_queue` - HTTP 路由 - `openviking/service/debug_service.py:ObserverService.queue` - 核心实现 - `openviking/storage/observers/queue_observer.py` - 队列观察者 #### 2. 接口和参数说明 无参数。 #### 3. 使用示例 **HTTP API** ``` GET /api/v1/observer/queue ``` ```bash curl -X GET http://localhost:1933/api/v1/observer/queue \ -H "X-API-Key: your-key" ``` **Python SDK** ```python print(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 20 ``` **TypeScript SDK** ```typescript console.log(await client.queueStatus()); ``` **Go SDK** ```go status, err := client.QueueStatus(ctx) if err != nil { return err } fmt.Println(status["is_healthy"]) ``` **CLI** ```bash ov observer queue ``` **响应示例** ```json { "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 #### 1. 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 命令 #### 2. 接口和参数说明 无参数。 #### 3. 使用示例 **HTTP API** ``` GET /api/v1/observer/vikingdb ``` ```bash curl -X GET http://localhost:1933/api/v1/observer/vikingdb \ -H "X-API-Key: your-key" ``` **Python SDK** ```python print(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 SDK** ```typescript console.log(await client.vikingDBStatus()); ``` **Go SDK** ```go status, err := client.VikingDBStatus(ctx) if err != nil { return err } fmt.Println(status["is_healthy"]) ``` **CLI** ```bash ov observer vikingdb ``` **响应示例** ```json { "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 #### 1. 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 命令 #### 2. 接口和参数说明 无参数。 #### 3. 使用示例 **HTTP API** ``` GET /api/v1/observer/models ``` ```bash curl -X GET http://localhost:1933/api/v1/observer/models \ -H "X-API-Key: your-key" ``` **Python SDK** ```python print(client.observer.models()) # 输出: # [models] (healthy) # provider_model healthy detail # dense_embedding yes ... # rerank yes ... # vlm yes ... ``` **TypeScript SDK** ```typescript console.log(await client.modelsStatus()); ``` **Go SDK** ```go status, err := client.ModelsStatus(ctx) if err != nil { return err } fmt.Println(status["is_healthy"]) ``` **CLI** ```bash ov observer models ``` **响应示例** ```json { "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 #### 1. API 实现介绍 获取分布式锁系统状态。 **代码入口**: - `openviking/server/routers/observer.py:observer_lock` - HTTP 路由 - `openviking/service/debug_service.py:ObserverService.lock` - 核心实现 - `openviking/storage/observers/lock_observer.py` - 锁观察者 - `crates/ov_cli/src/commands/observer.rs` - CLI 命令 #### 2. 接口和参数说明 无参数。 #### 3. 使用示例 **HTTP API** ``` GET /api/v1/observer/lock ``` ```bash curl -X GET http://localhost:1933/api/v1/observer/lock \ -H "X-API-Key: your-key" ``` 公开 SDK 和 CLI 目前没有单独的 lock observer 方法。请使用 HTTP API 查询该组件；`ov observer system` 会在汇总状态中包含它。 **响应示例** ```json { "status": "ok", "result": { "name": "lock", "is_healthy": true, "has_errors": false, "status": "..." }, "time": 0.1 } ``` --- ### observer.retrieval #### 1. 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 命令 #### 2. 接口和参数说明 无参数。 #### 3. 使用示例 **HTTP API** ``` GET /api/v1/observer/retrieval ``` ```bash curl -X GET http://localhost:1933/api/v1/observer/retrieval \ -H "X-API-Key: your-key" ``` **CLI** ```bash ov observer retrieval ``` **响应示例** ```json { "status": "ok", "result": { "name": "retrieval", "is_healthy": true, "has_errors": false, "status": "..." }, "time": 0.1 } ``` --- ### observer.filesystem #### 1. 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 命令 #### 2. 接口和参数说明 无参数。 #### 3. 使用示例 **HTTP API** ``` GET /api/v1/observer/filesystem ``` ```bash curl -X GET http://localhost:1933/api/v1/observer/filesystem \ -H "X-API-Key: your-key" ``` **CLI** ```bash ov observer filesystem ``` **响应示例** ```json { "status": "ok", "result": { "name": "filesystem", "is_healthy": true, "has_errors": false, "status": "..." }, "time": 0.1 } ``` --- ### observer.system #### 1. API 实现介绍 获取整体系统状态，包括所有组件（queue、vikingdb、models、lock、retrieval）。 **代码入口**: - `openviking/server/routers/observer.py:observer_system` - HTTP 路由 - `openviking/service/debug_service.py:ObserverService.system` - 核心实现 - `crates/ov_cli/src/commands/observer.rs` - CLI 命令 #### 2. 接口和参数说明 无参数。 #### 3. 使用示例 **HTTP API** ``` GET /api/v1/observer/system ``` ```bash curl -X GET http://localhost:1933/api/v1/observer/system \ -H "X-API-Key: your-key" ``` **Python SDK** ```python print(client.observer.system()) # 输出: # [queue] (healthy) # ... # # [vikingdb] (healthy) # ... # # [models] (healthy) # ... # # [system] (healthy) ``` **TypeScript SDK** ```typescript console.log(await client.getStatus()); ``` **Go SDK** ```go status, err := client.GetStatus(ctx) if err != nil { return err } fmt.Println(status["is_healthy"]) ``` **CLI** ```bash ov observer system ``` **响应示例** ```json { "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": "..." } } }, "time": 0.1 } ``` --- ## 相关文档 - [Metrics](09-metrics.md) - Prometheus 指标抓取 - [系统状态](07-system.md) - 健康检查和一致性检查