Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs(guides): review configuration, deployment and observability guides (#5508)
Zayn Jarvisfbf82caf6b9b
diff --git a/docs/en/concepts/12-metrics.md b/docs/en/concepts/12-metrics.mdindex 1b3f088b4..c6fc7920d 100644--- a/docs/en/concepts/12-metrics.md+++ b/docs/en/concepts/12-metrics.md@@ -1,6 +1,6 @@# Metrics-OpenViking provides a machine-oriented metrics system for exposing runtime health, request quality, model usage, resource processing throughput, and probe health states.+OpenViking provides a machine-oriented metrics system for exposing runtime health, request status, model usage, resource processing throughput, and probe health states.Unlike the human-facing `/api/v1/observer/*` endpoints and the analytics-oriented `/api/v1/stats/*` endpoints, Metrics are designed for:@@ -94,7 +94,7 @@ The first exporter implementation is the Prometheus exporter, which renders regi### Accessing `/metrics`-In the current implementation, `/metrics` is not wired to `get_request_context` or other auth dependencies, so from the code-path perspective it currently behaves as a public scrape endpoint.+`/metrics` does not require an OpenViking API key. Restrict access at the gateway or reverse proxy when needed.```bashcurl http://localhost:1933/metrics@@ -124,7 +124,7 @@ scrape_configs:| `context_type` | retrieval context type | `resource` || `provider` | model or external service provider | `volcengine` || `model_name` | model name | `doubao-seed-1-8-251228` |-| `stage` | stage label (defined by each metric family) | resource stage: `parse`; token attribution stage: `embed_query` |+| `stage` | stage label (defined by each metric family) | resource stage: `parse_artifact`; token attribution stage: `embed_query` || `valid` | whether the current sample is fresh and valid | `1` / `0` |Notes:@@ -132,12 +132,12 @@ Notes:- `account_id` is only enabled on controlled allowlisted metric families to prevent high-cardinality growth- `valid=0` means the current state/probe sample is a fallback or stale value, not that the label itself is malformed- `stage` semantics depend on the metric family:- - `openviking_resource_stage_*`: resource ingestion pipeline stages (for example `parse/persist/process`)+ - `openviking_resource_stage_*`: resource ingestion pipeline stages (for example `parse_artifact/target_resolve/content_commit`)- `openviking_operation_tokens_total`: token attribution stages (for example `embed_query/rerank/vlm`)## Key Metric Families-The metric summaries below are based on representative metrics currently exposed by the collectors in `openviking/metrics/collectors/`.+The tables list representative metrics defined by the collectors. A series appears only when its feature is enabled, the relevant event occurs, and collection succeeds. An absent series does not necessarily mean zero.### Requests and Operations@@ -168,14 +168,20 @@ Typical usage:| `openviking_resource_stage_duration_seconds` | Histogram | `account_id, stage, status` | duration distribution of ingestion stages || `openviking_resource_wait_duration_seconds` | Histogram | `account_id, operation` | resource ingestion wait duration distribution (for example queue waiting) |-Typical `stage` values include:+Current built-in resource event producers emit these `stage` values, depending on the path taken:-- `request`-- `parse`-- `summarize`-- `persist`-- `finalize`-- `process`+- `source_prepare`+- `parse_artifact`+- `target_resolve`+- `update_plan`+- `content_commit`+- `derived_enqueue`+- `semantic_queue_wait`+- `semantic_execute`+- `embedding_queue_wait`+- `embedding_execute`++The telemetry bridge also recognizes legacy summary keys for `request`, `process`, `parse`, `finalize`, `summarize`, `wait`, and `watch`. The current resource summary builder does not produce those keys, so they are not additional stages emitted by the current import pipeline. `persist` is not in that bridge map.### Vector, Memory, and Semantic Metrics@@ -219,6 +225,8 @@ Notes:- `openviking_model_*` gives a unified cross-model view for embedding and VLM usage- `openviking_vlm_*` and `openviking_embedding_*` are better suited for workload-specific dashboards+- `*_requests_*` represents business requests; `*_calls_*`, call duration, and token families represent provider calls+- `openviking_operation_tokens_total` has no pre-aggregated `token_type="all/total"`; aggregate totals in TSDB queries### Queues, Locks, and Runtime State@@ -298,6 +306,8 @@ Python `get_stats()` retains its microsecond fields.| `openviking_task_running` | Gauge | `task_type` | running tasks tracked by task tracker || `openviking_task_completed` | Gauge | `task_type` | completed tasks tracked by task tracker || `openviking_task_failed` | Gauge | `task_type` | failed tasks tracked by task tracker |+| `openviking_task_cancelling` | Gauge | `task_type` | tasks being cancelled |+| `openviking_task_cancelled` | Gauge | `task_type` | cancelled tasks |### Cache@@ -395,7 +405,7 @@ For `/metrics` endpoint behavior and scrape usage, see [Metrics API](../api/09-m| `openviking_service_readiness` | Gauge | may include `valid` | main service readiness || `openviking_api_key_manager_readiness` | Gauge | may include `valid` | API key manager readiness || `openviking_storage_readiness` | Gauge | `probe, valid` | storage probe, for example `agfs` |-| `openviking_model_provider_readiness` | Gauge | `provider, valid` | model provider readiness |+| `openviking_model_provider_readiness` | Gauge | `provider, valid` | whether a VLM client can be created from configuration; no model request is sent || `openviking_async_system_readiness` | Gauge | `probe, valid` | async system readiness || `openviking_retrieval_backend_readiness` | Gauge | `probe, valid` | retrieval backend readiness || `openviking_encryption_component_health` | Gauge | `valid` | overall encryption component health |@@ -409,6 +419,8 @@ Meaning of `valid`:### Encryption (Operational Metrics)+These metrics are driven by Python encryption events and are not complete counts of all encrypted RAGFS file I/O. Assess file throughput together with RAGFS metrics and the enabled backends.+| Metric Family | Type | Common Labels | Meaning ||---------------|------|---------------|---------|| `openviking_encryption_operations_total` | Counter | `account_id, operation, status` | encrypt/decrypt operation count |@@ -456,6 +468,8 @@ Possible `model_type` values include:- `embedding`- `rerank`+`openviking_model_provider_readiness=1` does not verify credentials, quota, or remote inference. It only checks client construction. Use actual model-call errors and latency to assess requests.+## Configuration Example### Enabling Metrics@@ -478,8 +492,8 @@ In `ov.conf`, the metrics subsystem can be explicitly enabled through `server.ob"openviking_operation_requests_total","openviking_operation_duration_seconds","openviking_vlm_calls_total",- "openviking_vlm_call_duration_seconds",- "openviking_rerank_*"+ "openviking_vlm_call_duration_seconds",+ "openviking_rerank_*"]}}diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 597d21697..655afce0e 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -2,6 +2,10 @@OpenViking uses a JSON configuration file (`~/.openviking/ov.conf`) for settings.+Use this page when configuring the server. To connect to an existing server, follow [CLI Setup](../getting-started/05-cli-setup.md); clients do not need model or storage settings.++For a first setup, use the wizard below. For an existing installation, find the relevant section and merge its fields into your JSON configuration; do not replace the whole file with a partial example. Editing `ov.conf` requires a restart. The limited runtime update surface is described below.+For a first-time setup, the recommended flow is:```bash@@ -148,7 +152,8 @@ PATCH uses three states: an omitted field is unchanged, a concrete value sets or"provider" : "volcengine","dimension": 1024,"model" : "doubao-embedding-vision-251215",- "input": "multimodal"+ "input": "multimodal",+ "batch_size": 32}},"vlm": {@@ -497,21 +502,9 @@ Get your API key at https://jina.ai}```-Supported Voyage text embedding models include:-- `voyage-4-lite`-- `voyage-4`-- `voyage-4-large`-- `voyage-code-3`-- `voyage-context-3`-- `voyage-3`-- `voyage-3.5`-- `voyage-3.5-lite`-- `voyage-finance-2`-- `voyage-law-2`+Text models include `voyage-4-lite`, `voyage-4`, and `voyage-4-large`. See [Voyage Text Embeddings](https://docs.voyageai.com/docs/embeddings) for available models and output dimensions.-If `dimension` is omitted, OpenViking uses the model's default output dimension when creating the vector schema.--OpenViking also expects dense float vectors throughout storage and retrieval, so Voyage quantized output dtypes are not exposed in config.+If `dimension` is omitted, OpenViking uses its built-in model table (`voyage-3`, `voyage-3-large`, `voyage-3.5`, `voyage-3.5-lite`, `voyage-4`, `voyage-4-lite`, `voyage-4-large`, `voyage-code-3`, `voyage-context-3`, `voyage-finance-2`, `voyage-law-2`), falling back to 1024 for an unrecognized model. Set a supported output dimension explicitly for a new model. The current adapter sends plain text `input`; it does not send Voyage's `input_type`, expose quantized output, or implement specialized contextual embedding calls.**Local deployment (GGUF/MLX):** Jina embedding models are open-weight and available in GGUF and MLX formats on [Hugging Face](https://huggingface.co/jinaai). You can run them locally with any OpenAI-compatible server (e.g. llama.cpp, MLX, vLLM) and point the `api_base` to your local endpoint:@@ -629,7 +622,7 @@ Supported task types: `RETRIEVAL_QUERY`, `RETRIEVAL_DOCUMENT`, `SEMANTIC_SIMILAR#### Sparse Embedding-> **Note:** Volcengine sparse embedding is supported starting from model `doubao-embedding-vision-251215`.+> This example uses `doubao-embedding-vision-251215`. Check sparse text-output support for your selected model in the Ark [embedding documentation](https://docs.volcengine.com/docs/ark/vectorization?lang=zh&redirect=1).```json{@@ -670,7 +663,7 @@ Two approaches are supported:"hybrid": {"provider": "volcengine","api_key": "your-api-key",- "model": "doubao-embedding-hybrid",+ "model": "doubao-embedding-vision-251215","dimension": 1024}}@@ -704,6 +697,7 @@ Vision Language Model for semantic extraction (L0/L1 generation).```json{"vlm": {+ "provider": "volcengine","api_key": "your-api-key","model": "doubao-seed-2-0-lite-260428","api_base": "https://ark.cn-beijing.volces.com/api/v3",@@ -760,7 +754,7 @@ When resources are added, VLM generates:1. **L0 (Abstract)**: file or directory summary, with a default limit of 256 characters2. **L1 (Overview)**: directory overview with navigation, with a default limit of 4000 characters-If VLM is not configured, L0/L1 will be generated from content directly (less semantic), and multimodal resources may have limited descriptions.+When the VLM configuration reports `is_available() == false`, generic file summaries are empty and directory overviews fall back to a not-ready placeholder. Paths such as local code-skeleton extraction retain their own behavior. Do not treat this as completed semantic indexing; inspect the model configuration and processing task.**Supported providers:**- `volcengine`: Volcengine VLM API@@ -791,14 +785,14 @@ For OpenAI-compatible providers (e.g., OpenRouter), you can add custom HTTP head"api_base": "https://openrouter.ai/api/v1","extra_headers": {"HTTP-Referer": "https://your-site.com",- "X-Title": "Your App Name"+ "X-OpenRouter-Title": "Your App Name"}}}```Common use cases:-- **OpenRouter**: Requires `HTTP-Referer` and `X-Title` to identify your application+- **OpenRouter**: Optional `HTTP-Referer` and `X-OpenRouter-Title` headers provide [app attribution](https://openrouter.ai/docs/app-attribution), not API authentication; `X-Title` remains supported for compatibility- **Kimi Coding**: Override or extend the default subscription headers when you need a custom user agent- **OpenCode Go** (`https://opencode.ai/zen/go/v1`): Requests without `x-opencode-session` fail with HTTP 400 `MissingSessionID`. Set a fixed id, e.g. `"extra_headers": {"x-opencode-session": "openviking-<your-host>"}`. A fixed id works; OpenCode Go only uses it for routing and prompt-cache hints- **Custom proxies**: Add authentication or tracing headers@@ -874,7 +868,7 @@ Media processing sends file content to the configured external provider. Disable### query_planner-Optional lightweight model for retrieval intent analysis and query planning. It uses the same configuration shape as `vlm`, but only affects `search()` intent analysis and query expansion. If `query_planner` is omitted or empty, OpenViking falls back to `vlm` for backward compatibility.+Optional lightweight model for retrieval intent analysis and query planning. It uses the same configuration shape as `vlm` for `search()` intent analysis, query expansion, and optional server recall-digest rewriting. If `query_planner` is omitted or empty, OpenViking falls back to `vlm` for backward compatibility.> In `openviking-server init` you can optionally enable a local lightweight query planner; the wizard pulls the Ollama model and writes the `query_planner` config for you. For recognized query-planner models, `search()` selects the matching bundled prompt at runtime. Models not in the mapping keep using `retrieval.intent_analysis`.@@ -905,7 +899,7 @@ Then add the following to your OpenViking configuration:For `ollama/guoxuter/ov_intent_analysis_sft:v7_q8` (and `v4_q8`), OpenViking automatically uses the matching bundled prompt during search (`retrieval.ov_intent_analysis_sft_v7` and `retrieval.ov_intent_analysis_sft_v4` respectively). No prompt file replacement or `prompts.templates_dir` override is required. If you use an unmapped model, OpenViking keeps the default `retrieval.intent_analysis` prompt.-This lets a small model handle retrieval planning with lower latency, while keeping a stronger `vlm` for semantic extraction, memory extraction, and multimodal processing.+This lets a smaller model handle retrieval planning while a stronger `vlm` handles semantic extraction, memory extraction, and multimodal processing. Measure latency with your model, hardware, and request load.### feishu@@ -943,7 +937,7 @@ The remaining `code` configuration fields are for remote code resource network g#### Remote resource network guard-When ingesting a resource from a URL, OpenViking rejects loopback, link-local, private, and other non-public destinations, plus any host not on the code-hosting allowlist, raising `PermissionDeniedError`. To ingest code from self-hosted GitHub Enterprise / GitLab / Azure DevOps, add the host to the matching allowlist under `code`:+For URL ingestion, the default network check rejects destinations resolving to non-public addresses. Ordinary public URLs do not need to be on the code-hosting allowlist; trusted code hosts on that list bypass the address-range check. Add self-hosted GitHub Enterprise, GitLab, or Azure DevOps hosts to the corresponding platform list under `code`:| Field | Type | Description | Default ||-------|------|-------------|---------|@@ -952,11 +946,11 @@ When ingesting a resource from a URL, OpenViking rejects loopback, link-local, p| `azure_devops_domains` | list[str] | Allowed Azure DevOps hosts | `["dev.azure.com", "ssh.dev.azure.com", "vs-ssh.visualstudio.com"]` || `code_hosting_domains` | list[str] | Allowed generic code-hosting hosts | `["github.com", "gitlab.com", "gitcode.com", "gitee.com", "bitbucket.org", "codeberg.org", "gitea.com", "atomgit.com", "git.sr.ht"]` |-To ingest from private/internal network addresses (e.g. an internal mirror), set the top-level `allow_private_networks` to `true` (disabled by default, so only public addresses are allowed):+To allow other private-network targets, such as internal mirrors, set the top-level `allow_private_networks` to `true`. It is disabled by default; local hostnames such as `localhost` and its subdomains remain rejected. This example enables private-network access and registers a code host:```json{- "allow_private_networks": false,+ "allow_private_networks": true,"code": {"github_domains": ["github.com", "github.example.com"]}@@ -1140,7 +1134,7 @@ The `mode="context"` assembly face on `/search` uses two timeout fuses:| `recall_intent_timeout_s` | float | Timeout for session-aware query expansion; on timeout the original user query is used | `5.0` || `recall_rewrite_timeout_s` | float | Timeout for the digest rewrite; on timeout `digest` is empty and `rendered` is returned as usual | `30.0` |-Both LLM steps are strictly opt-in: expansion needs a `session_id`, the rewrite needs `rewrite`. Either one failing degrades gracefully and never blocks recall.+Query expansion requires a `session_id` with content and intent analysis enabled; rewriting requires `rewrite`. Each model call has its own timeout. On failure, retrieval falls back to the original query or the unrevised result.### grep@@ -1389,7 +1383,12 @@ Notes:- `mode=shared` keeps the historical global queue namespace at `/queue`; `mode=worker` isolates each worker under `/queue/worker-<index|pid>`.- `db_path` is only used when QueueFS backend is `sqlite` or `sqlite3`.- `backend=cache` automatically binds the global `cache.provider + cache.params` configuration.-- Redis Cluster slot routing, topology refresh, Sentinel discovery, and reconnects are handled by the Fred RedisProvider.+- `recover_stale_sec` and `busy_timeout_ms` apply only to SQLite backends.+- Redis Cluster endpoints are seed nodes, and `db` must be `0`. Slot routing, `MOVED`/`ASK`, topology refresh, and reconnects are handled by Fred RedisProvider.+- Redis Sentinel endpoints are Sentinel nodes and require a non-empty `master_name`; the provider handles master discovery and reconnects.+- `username` and `password` authenticate data nodes; `sentinel_username` and `sentinel_password` authenticate Sentinel nodes.+- All Redis reads go to the primary. Replica reads are not configurable.+- `tls_insecure_skip_verify=true` requires `rediss://` endpoints.- QueueFS cache keys use `{cache_key_prefix}:ov:*`; use different prefixes for deployments or tenants sharing one Redis cluster.- Redis backend runs three bounded `recover_stale` sweeps in a dedicated startup recovery thread at startup, 30 seconds, and 60 seconds to cover the heartbeat-expiry window after a container restart; it does not run long-lived periodic recovery.- If both `storage.agfs.queuefs.db_path` and legacy `storage.agfs.queue_db_path` are set, `storage.agfs.queuefs.db_path` wins.@@ -1442,55 +1441,6 @@ Legacy compatibility example:}```-##### Session Auto Commit Configuration--`memory.session_auto_commit` controls server-wide automatic session commit behavior.--```json-{- "memory": {- "session_auto_commit": {- "enabled": false,- "check_interval_seconds": 600.0,- "scan_rate_limit_files_per_second": 2.0- }- }-}-```--| Parameter | Type | Description | Default |-|-----------|------|-------------|---------|-| `enabled` | bool | Master switch for automatic session commits. When enabled, newly created sessions without an explicit `auto_commit_policy` get a default policy, and the idle-timeout background scheduler is started. When disabled, neither happens | `false` |-| `check_interval_seconds` | float | Minimum interval between two idle scan rounds in seconds. Must be greater than `0` | `600.0` |-| `scan_rate_limit_files_per_second` | float | Maximum number of session `.meta.json` files read per second during an idle scan. Must be greater than `0`. Bounds background storage IO when the sessions tree is very large | `2.0` |--Notes:--- `memory.session_auto_commit` is a server-wide control surface, not a per-session business policy.-- Per-session auto-commit behavior is configured through the session-level `auto_commit_policy` (see the table below). Set it when creating a session with `POST /api/v1/sessions`, or partially update it through `PATCH /api/v1/sessions/{session_id}/config`. Omitting `auto_commit_policy` from a PATCH preserves it; sending `null` disables automatic commits. Use `GET /api/v1/sessions/{session_id}` to inspect the effective policy.-- When `enabled=false`, sessions created without an explicit or `server.user_config_defaults.auto_commit_policy` policy keep auto commit disabled and return `auto_commit_policy: null`; `SessionAutoCommitScheduler` is not started.-- When `enabled=true`:- - Sessions without an explicit or deployment-default policy get the built-in policy below.- - `SessionAutoCommitScheduler` starts a scan round immediately, then waits at least `check_interval_seconds` before the next round. If a round already took longer than that interval, the next round starts immediately.- - Within a round, session `.meta.json` files are read serially at no more than `scan_rate_limit_files_per_second` to avoid IO spikes.- - It does not perform a dedicated startup recovery sweep; idle detection happens only on periodic scans.-- Token- and message-count auto commit run inline after message writes, do not depend on the scheduler, but still require the session to carry an `auto_commit_policy`.--###### Per-session Auto Commit Policy--When a session carries an `auto_commit_policy`, any field you omit falls back to the recommended default below. Sessions without a stored policy keep auto commit disabled. Values are clamped into `[0, max]`, and unknown keys are rejected with `InvalidArgumentError`. See [Sessions API](../api/05-sessions.md#create-session) for how to set and view it.--| Field | Type | Default | Max | Description |-|-------|------|---------|-----|-------------|-| `pending_token_threshold` | int | 150000 | 1000000 | When uncommitted pending tokens exceed this value (strictly greater-than), an auto commit is triggered after a message write. |-| `message_count_threshold` | int | 100 | 1000 | When the uncommitted live message count exceeds this value (strictly greater-than), an auto commit is triggered after a message write. |-| `idle_timeout_seconds` | int | 86400 | 604800 | After this many idle seconds, a session with uncommitted content becomes eligible for the server-side idle scheduler. Idle-timeout commits archive the full backlog and ignore `keep_recent_count`. |-| `keep_recent_count` | int | 0 | 500 | Number of recent live messages to keep (not archived) on a threshold-triggered auto commit. Idle-timeout commits ignore this and commit everything. |-| `min_commit_interval_seconds` | int | 0 | 604800 | Minimum seconds between two automatic commits (throttle). |--Code entry: `openviking/session/auto_commit_policy.py:AutoCommitPolicy`.--##### S3 Backend Configuration| Parameter | Type | Description | Default |@@ -1727,12 +1677,60 @@ For memory-related settings, add a `memory` section in `ov.conf`:| Field | Description | Default ||-------|-------------|---------|| `version` | Deprecated and ignored. OpenViking always uses the v3 memory extraction pipeline; existing configs that set this field still load without error. | `"v3"` |-| `custom_templates_dir` | Custom memory templates directory. If set, templates from this directory are loaded in addition to built-in templates. | `""` |+| `custom_templates_dir` | Custom memory schema directory. Later definitions replace the same `memory_type`; new types are added. See the [Prompt Guide](10-prompt-guide.md). | `""` || `extraction_enabled` | Whether session commit runs long-term memory extraction. | `true` || `session_skill_extraction_enabled` | Whether session commit also extracts reusable skills into the current user's skill directory. | `false` || `link_enabled` | Whether memory extraction writes and resolves memory links. | `false` || `session_auto_commit` | Server-wide automatic session commit controls. This belongs under `memory`, not under `server`; see [Session Auto Commit Configuration](#session-auto-commit-configuration). | See section above |+#### Session Auto Commit Configuration++`memory.session_auto_commit` controls server-wide automatic session commit behavior.++```json+{+ "memory": {+ "session_auto_commit": {+ "enabled": false,+ "check_interval_seconds": 600.0,+ "scan_rate_limit_files_per_second": 2.0+ }+ }+}+```++| Parameter | Type | Description | Default |+|-----------|------|-------------|---------|+| `enabled` | bool | Master switch for automatic session commits. When enabled, newly created sessions without an explicit `auto_commit_policy` get a default policy, and the idle-timeout background scheduler is started. When disabled, neither happens | `false` |+| `check_interval_seconds` | float | Minimum interval between two idle scan rounds in seconds. Must be greater than `0` | `600.0` |+| `scan_rate_limit_files_per_second` | float | Maximum number of session `.meta.json` files read per second during an idle scan. Must be greater than `0`. Bounds background storage IO when the sessions tree is very large | `2.0` |++Notes:++- `memory.session_auto_commit` is a server-wide control surface, not a per-session business policy.+- Per-session auto-commit behavior is configured through the session-level `auto_commit_policy` (see the table below). Set it when creating a session with `POST /api/v1/sessions`, or partially update it through `PATCH /api/v1/sessions/{session_id}/config`. Omitting `auto_commit_policy` from a PATCH preserves it; sending `null` disables automatic commits. Use `GET /api/v1/sessions/{session_id}` to inspect the effective policy.+- When `enabled=false`, sessions created without an explicit or `server.user_config_defaults.auto_commit_policy` policy keep auto commit disabled and return `auto_commit_policy: null`; `SessionAutoCommitScheduler` is not started.+- When `enabled=true`:+ - Sessions without an explicit or deployment-default policy get the built-in policy below.+ - `SessionAutoCommitScheduler` starts a scan round immediately, then waits at least `check_interval_seconds` before the next round. If a round already took longer than that interval, the next round starts immediately.+ - Within a round, session `.meta.json` files are read serially at no more than `scan_rate_limit_files_per_second` to avoid IO spikes.+ - It does not perform a dedicated startup recovery sweep; idle detection happens only on periodic scans.+- Token- and message-count auto commit run inline after message writes, do not depend on the scheduler, but still require the session to carry an `auto_commit_policy`.++##### Per-session Auto Commit Policy++When a session carries an `auto_commit_policy`, any field you omit falls back to the built-in default below. Sessions without a stored policy keep auto commit disabled. Values are clamped into `[0, max]`, and unknown keys are rejected with `InvalidArgumentError`. See [Sessions API](../api/05-sessions.md#create-session) for how to set and view it.++| Field | Type | Default | Max | Description |+|-------|------|---------|-----|-------------|+| `pending_token_threshold` | int | 150000 | 1000000 | When uncommitted pending tokens exceed this value (strictly greater-than), an auto commit is triggered after a message write. |+| `message_count_threshold` | int | 100 | 1000 | When the uncommitted live message count exceeds this value (strictly greater-than), an auto commit is triggered after a message write. |+| `idle_timeout_seconds` | int | 86400 | 604800 | After this many idle seconds, a session with uncommitted content becomes eligible for the server-side idle scheduler. Idle-timeout commits archive the full backlog and ignore `keep_recent_count`. |+| `keep_recent_count` | int | 0 | 500 | Number of recent live messages to keep (not archived) on a threshold-triggered auto commit. Idle-timeout commits ignore this and commit everything. |+| `min_commit_interval_seconds` | int | 0 | 604800 | Minimum seconds between two automatic commits (throttle). |++Code entry: `openviking/session/auto_commit_policy.py:AutoCommitPolicy`.+### ovcli.confYou can edit this file by hand, or generate it interactively with `ov config`. If you maintain configurations for multiple servers, switch between them with `ov config switch`.@@ -1758,7 +1756,8 @@ Config file for the HTTP client (`SyncHTTPClient` / `AsyncHTTPClient`) and CLI t| Field | Description | Default ||-------|-------------|---------|| `url` | Server address | (required) |-| `api_key` | API key for authentication (root key or user key) | `null` (no auth) |+| `api_key` | Normally a user/admin key for data access. A root key here only works for admin APIs in API Key mode | `null` (no auth) |+| `root_api_key` | Root key used by the `ov` CLI with `--sudo`, or as a fallback when `api_key` is unset. The Python HTTP SDK does not use this fallback | `null` || `account` | Optional trusted-mode account identity header value | `null` || `user` | Optional trusted-mode user identity header value | `null` || `profile` | Whether to append `profile=1` to HTTP requests by default. Applies to both the Python HTTP client and the `ov` CLI; `ov --profile` can enable it per invocation. Actual effect still depends on the server enabling `server.profile_enabled`. | `false` |@@ -1846,6 +1845,12 @@ Explicit `auth_mode: "api_key"` requires a non-empty `root_api_key`, including o`user_config_defaults` provides deployment defaults for add targets and memory extraction. For add operations, explicit request targets still win: `add_resource.to` / `add_resource.parent` take precedence over user defaults, and `add_skill.target_uri` takes precedence over user defaults. Memory policy precedence is Session policy > User `settings/user_config.json` policy > `server.user_config_defaults.memory_policy` > kernel default. `server.agent_evolution.enabled` supplies the startup default. Runtime resolution is Account override > Cluster runtime override > that startup value. Use the Admin settings APIs for changes without restarting; editing `ov.conf` directly takes effect after restart.+Supported add target URIs:++- `resource_uri` is used as the default `add_resource` parent directory, equivalent to `parent=<uri>, create_parent=true`. It must be a writable resource directory URI for the request user. Supported forms are `viking://resources` or `viking://resources/...`, `viking://~/resources` or `viking://~/resources/...`, `viking://user/{user_id}/resources` or `viking://user/{user_id}/resources/...`, and `viking://user/{user_id}/peers/{peer_id}/resources` or `viking://user/{user_id}/peers/{peer_id}/resources/...`. The `viking://~/...` home alias resolves per request user.+- `skill_uri` is used as the default `add_skill` target root. In v1, only `viking://~/skills` and `viking://agent/skills` are accepted; explicit `viking://user/{user_id}/skills` is not accepted.+- Legacy spellings: `viking://user/resources` and `viking://user/skills` written in earlier configs are auto-normalized to `viking://~/resources` and `viking://~/skills` when the config is loaded, and the server logs an info message. Prefer the `viking://~/...` form in new configs — outside `add_targets`, the uid-less spelling is rejected at the request boundary.+### Usage ReporterThe optional Usage Reporter extracts memory usage events from committed session tool parts. The built-in file log sink writes each event as one flat JSON object to a dedicated hourly rotating file:@@ -1887,12 +1892,6 @@ Each line has the following form:`event_time` is UTC. `tenant_id` combines the deployment resource ID, event account, user, and Experience URI. `memory.recalled` maps to `experience.recall.count`, while `memory.injected` maps to `experience.inject.count`. `object_id` is the stable Usage Event ID. Downstream consumers must deduplicate by the composite `(tenant_id, object_id)` key rather than by `object_id` globally. Aggregate usage with `sum(count)` after filtering by `tenant_id`, `event_name`, and the desired `event_time` range. File collection and downstream delivery remain best-effort.-Supported add target URIs:--- `resource_uri` is used as the default `add_resource` parent directory, equivalent to `parent=<uri>, create_parent=true`. It must be a writable resource directory URI for the request user. Supported forms are `viking://resources` or `viking://resources/...`, `viking://~/resources` or `viking://~/resources/...`, `viking://user/{user_id}/resources` or `viking://user/{user_id}/resources/...`, and `viking://user/{user_id}/peers/{peer_id}/resources` or `viking://user/{user_id}/peers/{peer_id}/resources/...`. The `viking://~/...` home alias resolves per request user.-- `skill_uri` is used as the default `add_skill` target root. In v1, only `viking://~/skills` and `viking://agent/skills` are accepted; explicit `viking://user/{user_id}/skills` is not accepted.-- Legacy spellings: `viking://user/resources` and `viking://user/skills` written in earlier configs are auto-normalized to `viking://~/resources` and `viking://~/skills` when the config is loaded, and the server logs an info message. Prefer the `viking://~/...` form in new configs — outside `add_targets`, the uid-less spelling is rejected at the request boundary.-For startup and deployment details see [Deployment](./03-deployment.md), for authentication see [Authentication](./04-authentication.md).## storage.transaction Section@@ -1936,7 +1935,7 @@ For details on the lock mechanism, see [Path Locks and Crash Recovery](../concep## Task Tracker Persistence-The task tracker records async task state for endpoints that return a `task_id` (task types include `session_commit`, `add_resource`, `add_skill`, and `admin_reindex`). Task records are always persisted in AGFS, so a `task_id` returned by one instance can be looked up from another instance and task history survives a restart.+The task tracker records async task state for endpoints that return a `task_id` (task types include `session_commit`, `add_resource`, `add_skill`, and `admin_reindex`). Task records are written to AGFS. Instances sharing the same persistent storage can query the same `task_id`, and task history survives a restart subject to retention cleanup. Records on the `memory` filesystem backend do not survive a process restart.No `storage.task_tracker` configuration is required. If an older configuration still includes `storage.task_tracker`, OpenViking logs a warning and ignores it.@@ -1950,7 +1949,7 @@ Task record files are stored under the owning account's system directory:## encryption Section-Enable at-rest data encryption to ensure data security and isolation in multi-tenant environments. Encryption is completely transparent to users with no API changes.+At-rest encryption protects newly written files with account-specific keys through the existing APIs. Existing plaintext files are not encrypted automatically; migrate or rewrite them separately.```json{@@ -2041,7 +2040,9 @@ Suitable for Volcengine cloud deployments:For detailed encryption explanations, see [Data Encryption](../concepts/10-encryption.md). For complete usage instructions, see [Encryption Guide](./08-encryption.md).-## Full Schema+## Configuration Structure++This illustrates the main sections, not a complete runnable configuration or JSON Schema. Replace `string` and `|`-separated options with actual values; see the module sections for fields omitted here.```json{@@ -2105,10 +2106,11 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry"workspace": "string","agfs": {"backend": "local|s3|memory",- "timeout": 10- },- "transaction": {- "lock_expire": 300.0+ "timeout": 10,+ "pathlock": {+ "provider": "filesystem",+ "lock_expire_secs": 30.0+ }},"vectordb": {"backend": "local|cuvs|http|volcengine|vikingdb",@@ -2164,7 +2166,7 @@ Error: VLM request timeoutError: Rate limit exceeded```-Volcengine has rate limits. Consider batch processing with delays or upgrading your plan.+Check the provider error to determine whether the limit applies to request count, token usage, or account quota, then adjust request pacing or request the corresponding quota.- Lower `embedding.max_concurrent` / `vlm.max_concurrent` first- Keep a small `max_retries` value for occasional `429`s; set it to `0` if you prefer fail-fast behaviordiff --git a/docs/en/guides/02-volcengine-purchase-guide.md b/docs/en/guides/02-volcengine-purchase-guide.mdindex 00ca259ea..3a7a3fdba 100644--- a/docs/en/guides/02-volcengine-purchase-guide.md+++ b/docs/en/guides/02-volcengine-purchase-guide.md@@ -1,6 +1,6 @@# Volcengine Model Purchase Guide-This guide introduces how to purchase and configure the model services required by OpenViking on Volcengine.+For self-hosted OpenViking, this guide covers activating Volcano Ark models, obtaining an API key, and verifying the server configuration. Managed OpenViking clients do not need these local model settings; see the [Quick Start](../getting-started/02-quickstart.md).## Overview@@ -88,7 +88,7 @@ After activation, use the model ID: `doubao-embedding-vision-251215`### Configuration Template-Create an `~/.openviking/ov.conf` file using the following template:+This template shows the configuration structure; replace all string placeholders before use. For an existing configuration, update only the model sections and preserve storage, authentication, and other settings:```json{@@ -97,8 +97,8 @@ Create an `~/.openviking/ov.conf` file using the following template:"api_key": "<your-api-key>","model": "<model-id>","api_base": "<api-endpoint>",- "temperature": <temperature-value>,- "max_retries": <retry-count>+ "temperature": 0.1,+ "max_retries": 3},"embedding": {"dense": {@@ -106,7 +106,7 @@ Create an `~/.openviking/ov.conf` file using the following template:"api_key": "<your-api-key>","model": "<model-id>","api_base": "<api-endpoint>",- "dimension": <vector-dimension>,+ "dimension": 1024,"input": "<input-type>"}}@@ -123,7 +123,7 @@ Create an `~/.openviking/ov.conf` file using the following template:| `api_key` | string | Yes | Volcano Ark API Key || `model` | string | Yes | Model ID, e.g., `doubao-seed-2-0-lite-260428` || `api_base` | string | No | API endpoint address, defaults to Beijing region endpoint, see Appendix - Regional Endpoints for details |-| `temperature` | float | No | Generation temperature, controls output randomness, range 0-1, recommended 0.1 |+| `temperature` | float | No | Generation temperature; supported values depend on the model. This example uses 0.1 || `max_retries` | int | No | Number of retries when request fails, recommended 3 |#### Embedding Configuration Fields@@ -134,18 +134,18 @@ Create an `~/.openviking/ov.conf` file using the following template:| `api_key` | string | Yes | Volcano Ark API Key || `model` | string | Yes | Model ID, e.g., `doubao-embedding-vision-251215` || `api_base` | string | No | API endpoint address, defaults to Beijing region endpoint, see Appendix - Regional Endpoints for details |-| `dimension` | int | Yes | Vector dimension, depends on the model (usually 1024 or 768) |+| `dimension` | int | Yes | Must match the model output and index; this example selects 1024 || `input` | string | No | Input type: `"multimodal"` (multimodal) or `"text"` (plain text), default `"multimodal"` |### Configuration Example-Save the following content as `~/.openviking/ov.conf`:+Add these model sections to `~/.openviking/ov.conf`, preserving existing unrelated settings:```json{"vlm": {"provider": "volcengine",- "api_key": "sk-1234567890abcdef1234567890abcdef",+ "api_key": "your-ark-api-key","model": "doubao-seed-2-0-lite-260428","api_base": "https://ark.cn-beijing.volces.com/api/v3","temperature": 0.1,@@ -154,7 +154,7 @@ Save the following content as `~/.openviking/ov.conf`:"embedding": {"dense": {"provider": "volcengine",- "api_key": "sk-1234567890abcdef1234567890abcdef",+ "api_key": "your-ark-api-key","model": "doubao-embedding-vision-251215","api_base": "https://ark.cn-beijing.volces.com/api/v3","dimension": 1024,@@ -164,32 +164,28 @@ Save the following content as `~/.openviking/ov.conf`:}```-> ⚠️ **Note**: Please replace the `api_key` in the example with your real API Key obtained in Step 3!+Replace both `your-ark-api-key` values with the key from Step 3. This model credential is separate from the user/admin key used to connect to OpenViking Server.## Verify Configuration### Test Connection-```python-import asyncio-from openviking_sdk import AsyncHTTPClient--async def test():- client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")- await client.initialize()+Check model configuration, then start the server:- # Test adding a simple resource- result = await client.add_resource(- path="https://example.com",- options={"reason": "Connection Test"},- )- print(f"✓ Configuration successful: {result['root_uri']}")+```bash+openviking-server doctor+openviking-server+```- await client.close()+In another terminal, configure the CLI and create `quickstart.md` using the [Quick Start](../getting-started/02-quickstart.md). Import it into an unused target:-asyncio.run(test())+```bash+ov add-resource ./quickstart.md --to viking://resources/model-check --wait --timeout 120+ov find "Who owns the backup process?" --uri viking://resources/model-check```+An accepted import does not establish that model configuration works. Wait for completion before searching; after a timeout, inspect the returned task ID, and after failure, read the task error.+### View UsageIn the Volcano Ark Console:@@ -204,16 +200,12 @@ In the Volcano Ark Console:| Model Type | Billing Unit ||------------|--------------|-| VLM | Billed by Input/Output Tokens |-| Embedding | Billed by text length |+| VLM | Check the selected model’s input/output billing rules in [Ark pricing](https://www.volcengine.com/product/ark) |+| Embedding | Check the selected model and input modality in [Ark pricing](https://www.volcengine.com/product/ark) |### Free Tier-Volcengine provides a free tier for new users:--- Free Tokens upon first activation-- Sufficient to complete the OpenViking trial experience-- See details: [Volcano Ark Pricing](https://www.volcengine.com/docs/82379/1399514)+Check your console and [Volcano Ark pricing](https://www.volcengine.com/product/ark) for credit availability, eligible models, expiration, and charges after credits run out. Measure token usage with a small document before estimating bulk-ingestion cost; credits do not guarantee coverage of every trial workload.## Troubleshooting@@ -226,7 +218,7 @@ Error: Invalid API Key```**Solution**:-1. Check if the API Key is copied correctly (complete string starting with `sk-`).+1. Check that the API key was copied completely without extra whitespace.2. Confirm that the API Key has not been deleted or expired.3. Re-create an API Key.@@ -238,7 +230,7 @@ Error: Model not activated**Solution**:1. Check the model status in the Volcano Ark Console.-2. Confirm that the model is in "Running" status.+2. Confirm that the selected model ID is available to the account.3. Check if the account balance is sufficient.#### Network Connection Issues@@ -251,7 +243,7 @@ Error: Connection timeout1. Check your network connection.2. Confirm that the `api_base` configuration is correct.3. If you are overseas, confirm that you can access Volcengine services.-4. Increase the timeout in the configuration.+4. If the service is reachable but slow, adjust the relevant timeout using the [Configuration Guide](01-configuration.md).### Getting Help@@ -271,13 +263,14 @@ Error: Connection timeout| Region | API Base ||--------|----------|| Beijing | `https://ark.cn-beijing.volces.com/api/v3` |-| Shanghai | `https://ark.cn-shanghai.volces.com/api/v3` |++This guide uses the Beijing endpoint from official examples. For another region, copy the model endpoint from the console rather than substituting a region name in the hostname.### Model Version Reference-| Model Name | Current Version | Release Date |-|------------|-----------------|--------------|-| Doubao-Seed-2.0 | `doubao-seed-2-0-lite-260428` | 2025-12-28 |-| Doubao-Embedding-Vision | `doubao-embedding-vision-251215` | 2025-06-15 |+| Purpose | Model ID used in this guide |+| --- | --- |+| VLM | `doubao-seed-2-0-lite-260428` |+| Embedding | `doubao-embedding-vision-251215` |-> Note: Model versions may be updated, please refer to the Volcano Ark Console for the latest information.+These are example versions, not a claim about the latest release. See [Ark model releases](https://docs.volcengine.com/docs/ark/model-release-announcement?lang=zh) for availability and [vectorization documentation](https://docs.volcengine.com/docs/ark/vectorization?lang=zh) for input and dimension settings. Before changing embedding models, check whether the existing index needs rebuilding.diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.mdindex a4a74bfcd..b81834c89 100644--- a/docs/en/guides/03-deployment.md+++ b/docs/en/guides/03-deployment.md@@ -62,9 +62,9 @@ openviking-server --config /path/to/ov.conf --host 127.0.0.1 --port 8000## Configuration-The server reads all configuration from `ov.conf`. See [Configuration Guide](./01-configuration.md) for full details on config file format.+The server reads `ov.conf` and supports the corresponding environment-variable and startup-option overrides. See [Configuration Guide](./01-configuration.md) for full details on config file format.-The `server` section in `ov.conf` controls server behavior:+Merge this listener, authentication, and storage excerpt with your existing embedding/VLM configuration:```json{@@ -104,7 +104,7 @@ openviking-server## Deploying with Systemd (Recommended)-For Linux systems, you can use Systemd to manage OpenViking as a service, enabling automatic restart and startup on boot. Firstly, you should tried to install and configure openviking on your own.+For Linux systems, you can use Systemd to manage OpenViking as a service, enabling automatic restart and startup on boot. Install, configure, and verify OpenViking before creating the service.### Create Systemd Service File@@ -235,7 +235,9 @@ Since the server binds to `0.0.0.0` inside the container (required for Docker po}```-The server will refuse to start without it. You can override the bind address via the `OPENVIKING_SERVER_HOST` environment variable if needed.+When `auth_mode` is unset and no `root_api_key` is configured, the server auto-detects dev mode and refuses to start on a non-loopback address. The example above uses API key authentication; see [Authentication](04-authentication.md) for other modes. Override the bind address with `OPENVIKING_SERVER_HOST` if needed.++The image enables Bot by default. In API key mode, Bot also needs a valid User/Admin key in `bot.ov_server.api_key`; a root key is not a data credential. For a server-only deployment, use `--without-bot` below. To run Bot, complete the identity settings in [VikingBot Configuration](17-vikingbot.md).**Upgrading from an older image:** images that started in `/app` resolved `./data` to `/app/data`, outside the default mount. Before removing the old container, stop it and back up its configured workspace (for example, `docker cp openviking:/app/data ./openviking-data-backup`). Restore that backup into the mounted host workspace, normally `~/.openviking/data`, before starting the replacement. Do not overwrite an existing workspace without checking which data to retain. Absolute workspace paths are unchanged; other relative paths now resolve from `/app/.openviking`.@@ -243,7 +245,7 @@ Upgrade the container:```bashdocker stop openvikingdocker pull ghcr.io/volcengine/openviking:latest-docker rm -f openviking+docker rm openviking# Then re-run docker run ...```@@ -326,12 +328,12 @@ Initial bootstrap can be completed entirely within the browser:#### Configuration Management- **Initial Configuration**: The template pre-populates `OPENVIKING_CONF_CONTENT` with a complete configuration referencing `${OPENAI_API_KEY}`. This variable is used only on the first startup, when `ov.conf` does not yet exist.-- **Later Changes**: After the first startup, edit the volume-backed `ov.conf` directly using `railway ssh` or `railway service files upload --overwrite`. Alternatively, delete `ov.conf` and redeploy to regenerate it from the current `OPENVIKING_CONF_CONTENT` value.+- **Later Changes**: After the first startup, edit the volume-backed `ov.conf` directly using the commands supported by your installed [Railway CLI](https://docs.railway.com/cli). To regenerate it, first back up the old configuration and verify `OPENVIKING_CONF_CONTENT`, then move the old file aside and redeploy. Check storage and authentication settings afterward.#### Pricing & Resource Sizing-- **Recommended Plan**: For continuous hosting, the **Hobby** plan ($5/mo, which includes $5 of usage credits) is recommended. At ~0.5 GB resident memory, typical monthly cost is around $5–$7.-- **Free/Trial Limitations**: Railway Free plan ($1/mo credit) is insufficient for continuous service. Trial credits ($5 one-time) are suitable for short-term evaluation; note that volumes are purged 30 days after trial expiration.+- **Estimate costs**: Check [Railway pricing](https://docs.railway.com/pricing) for the current plan and resource billing rules. Test with your document volume and request rate, then estimate costs from the usage dashboard.+- **Trial and retention**: Check [Railway trial rules](https://docs.railway.com/pricing/free-trial) and your account for credits, expiration, and volume retention. Back up data before the applicable retention deadline.> **Security Note**: The service is publicly accessible by default. Keep `OPENVIKING_ROOT_API_KEY` confidential and consult the [public access guide](12-public-access.md) before production rollout.@@ -423,7 +425,7 @@ For a detailed cloud deployment guide (including Volcengine TOS + VikingDB + Ark| Endpoint | Auth | Purpose ||----------|------|---------|-| `GET /health` | No | Liveness probe — returns `{"status": "ok"}` immediately |+| `GET /health` | No | Process liveness; normally returns `status: ok` and `healthy: true`, without verifying model credentials || `GET /ready` | No | Readiness probe — checks AGFS, VectorDB, APIKeyManager, Embedding, Ollama |```bash@@ -435,7 +437,7 @@ curl http://localhost:1933/ready# {"status":"ready","checks":{"agfs":{"status":"ok","checks":{"filesystem":"ok","multiwrite_sync":"not_supported"}},"vectordb":"ok","api_key_manager":"ok","embedding":"ok","ollama":"not_configured"}}```-Use `/health` for Kubernetes liveness probes and `/ready` for readiness probes.+Use `/health` for Kubernetes liveness probes and `/ready` for readiness probes. See the [System API](../api/07-system.md) for the individual checks.## Related Documentationdiff --git a/docs/en/guides/05-observability.md b/docs/en/guides/05-observability.mdindex 86f933d65..d185bcd34 100644--- a/docs/en/guides/05-observability.md+++ b/docs/en/guides/05-observability.md@@ -1,20 +1,12 @@# Observability & Diagnostics-This guide collects the current OpenViking observability entry points in one place, including:--- service health and component status-- request-level `telemetry`-- terminal-side `ov tui`-- web-side `Web Studio` (served by the OV server at `/studio`)-- `/metrics` time-series metrics--If you just want to know where to look first, start with the table below.+Choose an entry point based on the question you need to answer: service readiness, stored data, a single request, or a trend over time.## Choose the right entry point| Entry point | Best for | Typical use case || --- | --- | --- |-| `/health`, `observer/*` | service health, queue backlog, VikingDB and VLM status | deployment validation, on-call checks |+| `/health`, `/ready`, `observer/*` | service health, queue backlog, VikingDB and VLM status | deployment validation, on-call checks || `ov tui` | `viking://` trees, directory summaries, file content, vector records, image preview for supported image files | development debugging, verifying that data actually landed || `Web Studio` (`/studio`) | same-origin web UI on the OV server: Home shows token / retrieval / context-commit trends; Resources browses URIs; Retrieval runs find; Request Logs shows audit | interactive investigation without typing every command || `telemetry` | per-request duration, token usage, vector retrieval, ingestion stages | debugging one specific slow or unexpected call |@@ -24,19 +16,19 @@ If you just want to know where to look first, start with the table below.### Health check-`/health` provides a simple liveness check and does not require authentication.+`/health` provides a simple liveness check and does not require authentication. The following response is an excerpt. Use `/ready` for readiness checks. Model observer health alone does not verify provider credentials or request success; see [System Status](../api/07-system.md).```bashcurl http://localhost:1933/health``````json-{"status": "ok"}+{"status": "ok", "healthy": true}```### Overall system status-**Python SDK (HTTP)**+**Python HTTP SDK (`SyncHTTPClient`)**```pythonstatus = client.get_status()@@ -77,7 +69,7 @@ curl http://localhost:1933/api/v1/observer/system \| `GET /api/v1/observer/vikingdb` | VikingDB | Vector database status || `GET /api/v1/observer/models` | Models | VLM, embedding, and rerank model status || `GET /api/v1/observer/lock` | Lock | Lock and transaction status |-| `GET /api/v1/observer/retrieval` | Retrieval | Retrieval quality metrics |+| `GET /api/v1/observer/retrieval` | Retrieval | Retrieval counts and latency; not a relevance evaluation || `GET /api/v1/observer/filesystem` | Filesystem | Filesystem operation metrics |For example:@@ -89,7 +81,7 @@ curl http://localhost:1933/api/v1/observer/queue \### Quick health check-**Python SDK (HTTP)**+**Python HTTP SDK (`SyncHTTPClient`)**```pythonif client.is_healthy():@@ -109,11 +101,11 @@ curl http://localhost:1933/api/v1/debug/health \### Response time-Every API response includes an `X-Process-Time` header with the server-side processing time in seconds:+`X-Process-Time` reports seconds from request entry to response-header emission. For streamed responses, it does not include the time needed to send the full body:```bashcurl -v http://localhost:1933/api/v1/fs/ls?uri=viking:// \- -H "X-API-Key: your-key" 2>&1 | grep X-Process-Time+ -H "X-API-Key: your-key" 2>&1 | grep -i X-Process-Time# < X-Process-Time: 0.0023```@@ -185,7 +177,7 @@ The most useful pages for observability are:Write operations (`Add Resource`, `Add Memory`, tenant/user administration) are gated by the API key currently signed in — there's no separate `--write-enabled` switch.-From an observability standpoint, Studio talks to the same `/api/v1/console/*` BFF (dashboard summary, token series, context commits, audit logs) the old standalone console used — only the UI changed. For operations such as `find`, `add-resource`, and `session commit`, you can expand the result panel to inspect `telemetry.summary`.+From an observability standpoint, Studio reads dashboard summaries, token series, context commits, and audit logs through `/api/v1/console/*`. To inspect `telemetry.summary` for operations such as `find`, `add-resource`, and `session commit`, read the complete HTTP response as shown in [Operation Telemetry](07-operation-telemetry.md).Studio is best for interactive click-through debugging. If you need to feed observability data into your own logs or automation, prefer the HTTP API or SDK and request telemetry explicitly.@@ -381,7 +373,7 @@ Compared with `telemetry`, `/metrics` focuses on **aggregated time series**, whi### Enable metrics quickly-`/metrics` may be disabled by default. When the metrics subsystem is not enabled, the endpoint returns `404` with the message `Prometheus metrics are disabled.`.+`/metrics` is disabled by default. When the metrics subsystem is not enabled, the endpoint returns `404` with the message `Prometheus metrics are disabled.`.You do not need the full configuration to get started. Enabling the master switch under the `server` section is enough.@@ -485,7 +477,7 @@ For full fields, supported ranges, and more examples, see:### Access `/metrics` directly-In the current implementation, `/metrics` is not wired to `get_request_context` or other auth dependencies, so from the code-path perspective it currently behaves as a public scrape endpoint:+When enabled, `/metrics` is an unauthenticated scrape endpoint:```bashcurl http://localhost:1933/metrics@@ -515,7 +507,7 @@ Before importing the dashboard, make sure the Prometheus data source can already- run `openviking_http_requests_total` in the Prometheus UI- or run `openviking_service_readiness`-- if either query returns time series, Grafana should be able to render panels afterwards+- if either query returns time series, scraping works; each dashboard panel still needs its own metric samples and matching filtersIf there is no data yet, go back to the Prometheus scrape configuration above and verify `targets`, `metrics_path`, and network connectivity first.diff --git a/docs/en/guides/07-operation-telemetry.md b/docs/en/guides/07-operation-telemetry.mdindex 482074347..2eb75bf0f 100644--- a/docs/en/guides/07-operation-telemetry.md+++ b/docs/en/guides/07-operation-telemetry.md@@ -8,7 +8,7 @@ Use it when you want to:- inspect token or retrieval behavior- capture structured execution data in your own logs or observability pipeline-For the broader observability entry points, including health checks, `ov tui`, and `OpenViking Console`, see [Observability & Diagnostics](05-observability.md).+For the broader observability entry points, including health checks, `ov tui`, and `Web Studio`, see [Observability & Diagnostics](05-observability.md).## How it works@@ -50,7 +50,7 @@ Notes:- `telemetry.id` is an opaque correlation id- `telemetry.summary` is the structured payload intended for users- summary groups appear only when the operation produced them-- numeric `0` values are omitted from the response+- numeric zero values in optional groups are generally omitted; the cuVS memory estimates retain zero values## Supported operations@@ -66,10 +66,17 @@ Operation telemetry is currently available on these endpoints:- `POST /api/v1/sessions`- `POST /api/v1/sessions/{session_id}/messages`- `POST /api/v1/sessions/{session_id}/commit`+- `POST /api/v1/sessions/{session_id}/messages/batch`+- `PATCH /api/v1/sessions/{session_id}/config`+- `POST /api/v1/content/write`+- `POST /api/v1/content/batch-write`+- `POST /api/v1/content/set_tags`+- `POST /api/v1/skills/find`+- `PUT /api/v1/skills/{skill_name}`### Python SDK-The same telemetry model is available from the Python clients for:+The Python clients can request telemetry for the following operations. High-level return values do not necessarily expose the top-level HTTP telemetry object; see the Python example below:- `add_resource(...)`- `add_skill(...)`@@ -144,7 +151,7 @@ If a group does not apply to the operation, it is omitted.## Field reference-Only fields that are actually produced by an operation are returned. Missing groups should be treated as "not applicable" rather than as zero.+Only fields that are actually produced by an operation are returned. Missing groups may be inapplicable, uncollected, or pruned because their numeric values are zero. Do not interpret absence as a measured zero or as proof that a stage ran.### Top-level telemetry fields@@ -271,18 +278,20 @@ This group appears when OpenViking waits for queue-backed work to complete.### `summary.memory`-This group appears on memory-extraction flows such as `session.commit`.+This group describes collected memory-extraction metrics. The current commit response covers the synchronous archive/submission phase; background extraction can finish later. Legacy stage names below appear only if a code path records them; they are not a fixed sequence that every V3 extraction follows.| Field | Meaning || --- | --- || `summary.memory.extracted` | Final number of memories extracted by the operation || `summary.memory.extract.duration_ms` | Total duration of the memory-extraction flow |-| `summary.memory.extract.candidates.total` | Total extracted candidates before final actions |+| `summary.memory.extract.candidates.total` | Current V3 count: newly written URIs plus edited URIs, rather than all proposed candidates || `summary.memory.extract.candidates.standard` | Standard memory candidates || `summary.memory.extract.actions.created` | Number of newly created memories || `summary.memory.extract.actions.merged` | Number of merges into existing memories || `summary.memory.extract.actions.deleted` | Number of deleted old memories |-| `summary.memory.extract.actions.skipped` | Number of skipped candidates |+| `summary.memory.extract.actions.skipped` | Number of skipped operations |+| `summary.memory.extract.actions.failed` | Number of recorded extraction errors |+| `summary.memory.extract.actions_by_type` | Action counts grouped by memory type || `summary.memory.extract.stages.prepare_inputs_ms` | Time spent preparing extraction inputs || `summary.memory.extract.stages.llm_extract_ms` | Time spent in the LLM extraction call || `summary.memory.extract.stages.normalize_candidates_ms` | Time spent parsing and normalizing candidates |@@ -333,26 +342,30 @@ curl -X POST http://localhost:1933/api/v1/resources \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \-d '{- "path": "./docs/readme.md",+ "path": "https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md",+ "wait": true,+ "timeout": 120,"reason": "telemetry demo","telemetry": true}'```-### Python SDK--```python-from openviking_sdk import AsyncHTTPClient+### Python: read the complete HTTP response-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+The SDK can send `options={"telemetry": True}`, but current high-level methods such as `find()` return only `result`, discarding the top-level telemetry object. Use an HTTP request when your application needs the summary:-result = await client.find(- query="memory dedup",- options={"telemetry": True},-)-print(result["telemetry"]["summary"]["operation"])-print(result["telemetry"]["summary"]["duration_ms"])+```python+import httpx++with httpx.Client(base_url="http://localhost:1933", timeout=30) as client:+ response = client.post(+ "/api/v1/search/find",+ headers={"X-API-Key": "your-user-key"},+ json={"query": "memory dedup", "limit": 5, "telemetry": True},+ )+ response.raise_for_status()+ payload = response.json()+ print(payload["telemetry"]["summary"])```## Limitations and behavior@@ -360,8 +373,8 @@ print(result["telemetry"]["summary"]["duration_ms"])- OpenViking currently exposes summary-only telemetry to users- `{"telemetry": {"events": true}}` is not a supported public request shape- event-stream style selection is not part of the public API-- `session.commit` supports telemetry only when `wait=true`-- if you call `session.commit` with `wait=false` and request telemetry, the server returns `INVALID_ARGUMENT`+- Current `session.commit` has no `wait` parameter. Its response telemetry covers archiving/submission, not the eventual completion of background extraction. Poll the returned task ID when present; see [Sessions](../api/05-sessions.md).+- A resource import with `wait=false` may also finish after response telemetry is returned. Use wait mode when the summary should include processing completed within the request.- telemetry shape is stable at the top level, but optional summary groups vary by operation## Related docsdiff --git a/docs/en/guides/10-prompt-guide.md b/docs/en/guides/10-prompt-guide.mdindex fd9c7cca3..8858ecf5e 100644--- a/docs/en/guides/10-prompt-guide.md+++ b/docs/en/guides/10-prompt-guide.md@@ -151,16 +151,31 @@ When writing a memory schema, focus on:## Current Prompt Template Reference-The sections below list all current templates by category. Each entry explains which processing stage it belongs to and which external capabilities it mainly affects.+The sections below describe template purposes, inputs, and related processing stages. A file in the template directory does not mean a request uses it: the call path, model configuration, and feature switches determine whether it takes effect.When reading this section, a simple rule helps:- For regular prompt templates, focus on `Purpose` and `Key inputs`- For memory schemas, focus on `Purpose` and `Key fields`+### Check Whether a Template Is Used++| Template or category | Current usage conditions |+| --- | --- |+| `compression.ov_wm_v2`, `compression.ov_wm_v2_update` | Initial working-memory generation and later updates in `openviking/session/session.py` |+| `retrieval.intent_analysis` | Query planning when intent analysis is enabled and the session has usable content; specific planner models select dedicated templates, as described below |+| `retrieval.recall_rewrite` | Optional server recall compression over assembled context, producing a digest with source references |+| `semantic.*` | Selected by the semantic queue processor according to file type or directory task |+| `parsing.image_summary`, `parsing.audio_summary`, `parsing.video_summary` | Media summaries; audio and video also require an enabled VLM that supports the input |+| `memory/tools.yaml`, `memory/skills.yaml` | Built in with `enabled: false`; changing their descriptions does not enable them |+| `memory/experimental_memory/*.yaml` | Loaded when `memory.experimental_memory_switch` is enabled |+| `skill_extract/session_skills.yaml` | Separate schema for Session Skill extraction; see its loading rules below |++`compression.structured_summary`, `indexing.relevance_scoring`, `parsing.chapter_analysis`, `parsing.context_generation`, `parsing.semantic_grouping`, `processing.*`, and `test.skill_test_generation` remain in the template directory, but no corresponding call sites were found in the current server source. Their inputs and intended purposes are retained below for maintenance and extensions; editing them should not be assumed to change live results.+### Compression-These prompts are mainly used for session compression and working-memory updates. Long-term memory extraction uses the v2 schema-driven memory templates in the `memory` category.+These prompts are mainly used for session compression and working-memory updates. Long-term memory extraction uses schema definitions in the `memory` category.- `compression.ov_wm_v2`- Effective stage: first working-memory generation stage@@ -175,7 +190,7 @@ These prompts are mainly used for session compression and working-memory updates- Key inputs: `previous_working_memory`, `messages`- `compression.structured_summary`- - Effective stage: session archive summary generation stage+ - Intended stage: session archive summary generation stage- Affects: archived session summaries and downstream review/retrieval quality- Purpose: generates a structured summary for archived sessions- Key inputs: `latest_archive_overview`, `messages`@@ -185,7 +200,7 @@ These prompts are mainly used for session compression and working-memory updatesThis category is mainly used to support retrieval or indexing workflows with relevance judgments.- `indexing.relevance_scoring`- - Effective stage: candidate relevance evaluation stage+ - Intended stage: candidate relevance evaluation stage- Affects: retrieval ranking and candidate filtering quality- Purpose: evaluates how relevant candidate content is to the user's query- Key inputs: `query`, `candidate`@@ -236,7 +251,7 @@ These YAML files define the structure of different memory types. They are not si- Purpose: defines the storage structure for "who the user is"- Key fields: `content`-- `skills`+- `skills` (disabled by default)- Effective stage: skill-usage memory persistence and update stage- Affects: skill usage statistics, experience accumulation, and recommended workflows- Purpose: defines skill usage counts, success rates, best-fit scenarios, and related information@@ -248,7 +263,7 @@ These YAML files define the structure of different memory types. They are not si- Purpose: defines the agent's core truths, boundaries, vibe, and continuity- Key fields: `core_truths`, `boundaries`, `vibe`, `continuity`-- `tools`+- `tools` (disabled by default)- Effective stage: tool-usage memory persistence and update stage- Affects: tool usage experience, optimal parameters, and failure pattern accumulation- Purpose: defines the storage structure for tool call statistics and tool-usage experience@@ -265,13 +280,13 @@ These YAML files define the structure of different memory types. They are not siThese prompts are mainly used to convert raw resource content into structured nodes, chapters, summaries, or image overviews that are easier to retrieve and understand.- `parsing.chapter_analysis`- - Effective stage: long-document chapter splitting stage+ - Intended stage: long-document chapter splitting stage- Affects: document chapter structure and page organization- Purpose: analyzes document content and splits it into a reasonable chapter structure- Key inputs: `start_page`, `end_page`, `total_pages`, `content`- `parsing.context_generation`- - Effective stage: document node semantic generation stage+ - Intended stage: document node semantic generation stage- Affects: node abstract/overview quality and downstream retrieval matching- Purpose: generates shorter, retrieval-friendly semantic titles, abstracts, and overviews for text nodes- Key inputs: `title`, `content`, `children_info`, `instruction`, `context_type`, `is_leaf`@@ -283,29 +298,34 @@ These prompts are mainly used to convert raw resource content into structured no- Key inputs: `context`- `parsing.semantic_grouping`- - Effective stage: semantic grouping and splitting stage+ - Intended stage: semantic grouping and splitting stage- Affects: document node granularity and content chunking quality- Purpose: decides whether content should be merged or split based on semantics- Key inputs: `items`, `threshold`, `mode`+- `parsing.audio_summary`, `parsing.video_summary`+ - Effective stage: audio/video understanding, requiring an enabled VLM that supports the media input+ - Purpose: generates a media overview for semantic indexing, retaining topics, events, facts, and identifiable content+ - Key inputs: `filename`, `fallback_language`; the media file is supplied separately to the model+### ProcessingThese prompts are mainly used to distill strategies or experience from interaction records, tool chains, and resource background. They are used for post-processing and knowledge accumulation rather than direct one-turn user answering.- `processing.interaction_learning`- - Effective stage: post-interaction experience extraction stage+ - Intended stage: post-interaction experience extraction stage- Affects: reusable interaction experience and distillation of effective resources and successful skills- Purpose: extracts reusable experience from interaction records- Key inputs: `interactions_summary`, `effective_resources`, `successful_skills`- `processing.strategy_extraction`- - Effective stage: post-resource-addition strategy extraction stage+ - Intended stage: post-resource-addition strategy extraction stage- Affects: structured extraction and reuse of resource background intent- Purpose: extracts usage strategies from the reason, instruction, and abstract associated with resource addition- Key inputs: `reason`, `instruction`, `abstract`- `processing.tool_chain_analysis`- - Effective stage: tool-chain analysis stage+ - Intended stage: tool-chain analysis stage- Affects: tool combination pattern recognition and tool experience accumulation- Purpose: analyzes tool call chains and identifies valuable usage patterns- Key inputs: `tool_calls`@@ -320,6 +340,16 @@ These prompts are mainly used to understand user intent before retrieval and dec- Purpose: generates a retrieval plan using compressed summary, recent messages, and the current message- Key inputs: `compression_summary`, `recent_messages`, `current_message`, `context_type`, `target_abstract`+- `retrieval.ov_intent_analysis_sft_v4`, `retrieval.ov_intent_analysis_sft_v7`+ - Used when the query planner's `model` exactly matches `ollama/guoxuter/ov_intent_analysis_sft:v4_q8` or `ollama/guoxuter/ov_intent_analysis_sft:v7_q8`, respectively+ - Purpose: uses the corresponding model's query-planning contract; other models use `retrieval.intent_analysis`+ - Check the configured model before editing the default template to avoid changing an unused file++- `retrieval.recall_rewrite`+ - Effective stage: optional server compression after context assembly+ - Purpose: produces query-relevant bullets with source URIs; output must pass the caller's format and source validation+ - Key inputs: `query`, `rendered`, `max_bullets`+### SemanticThese prompts are mainly used to generate file-level and directory-level summaries and are an important part of semantic indexing.@@ -358,12 +388,17 @@ These prompts are mainly used to compress Skill content into summaries suitable- Purpose: extracts key retrieval information from a Skill's name, description, and content- Key inputs: `skill_name`, `skill_description`, `skill_content`+- `skill.privacy_extraction`+ - Effective stage: Skill privacy configuration extraction+ - Purpose: identifies private configuration items maintained by the user for placeholder replacement and privacy configuration storage+ - Key inputs: `skill_name`, `skill_description`, `skill_content`+### TestThese prompts are mainly used to help generate test cases.- `test.skill_test_generation`- - Effective stage: Skill testing support stage+ - Intended stage: Skill testing support stage- Affects: Skill scenario test design and validation sample generation- Purpose: generates test cases from the names and descriptions of multiple Skills- Key inputs: `skills_info`@@ -514,9 +549,11 @@ Available configuration:Loading behavior:-- Built-in memory schemas are loaded first-- If `memory.custom_templates_dir` is configured, schemas in that directory are loaded afterward-- As a result, memory customization behaves more like extension and supplementation than a full replacement of the built-in set+1. Load schemas from the built-in `memory/` directory.+2. If `memory.experimental_memory_switch` is enabled, load built-in `memory/experimental_memory/` schemas.+3. If `memory.custom_templates_dir` is configured, load that directory; otherwise, try `memory/` under the selected prompt directory.++A later definition with the same `memory_type` replaces the earlier one; new types are added. Only `.yaml` and `.yml` files directly in each directory are read, without recursive loading. Custom schemas can therefore add types or override built-in types; changing the name creates a separate type. Loading failures are logged, so check which schemas actually loaded.Example directory:@@ -552,6 +589,12 @@ Impact examples:- Modifying `tools`- affects tool experience accumulation and tool usage recommendations+### Session Skill Schemas++`skill_extract/session_skills.yaml` uses the memory schema format but is loaded separately by Session Skill extraction. It defines session skills the user asks to retain, distinct from the usage statistics in `memory/skills.yaml`.++The loader reads `skill_extract/` directly under the selected prompt directory, without the per-file built-in fallback used for regular prompts. When using a custom `prompts.templates_dir` or `OPENVIKING_PROMPT_TEMPLATES_DIR` with Session Skill extraction, also copy the built-in `skill_extract/` directory and check the schema loading logs. Copying only a file under `semantic/` is insufficient for this path.+### High-Risk Changes During CustomizationThe following changes are the most likely to break existing workflows:@@ -600,6 +643,8 @@ For a memory schema, focus on:- whether the new schema was loaded successfully- whether the target memory type actually participates in extraction and persistence+`PromptManager` caches regular templates by default. After editing files, restart the service process that uses them; embedded applications can clear the corresponding manager's cache and reload. Memory registries also need to be recreated. Do not assume a running process automatically reads new schemas.+### Then: Verify That External Results ChangedThe most effective validation is capability-focused:@@ -607,9 +652,11 @@ The most effective validation is capability-focused:- If you changed a `vision` template, re-parse images, tables, or scanned PDFs and check whether the results changed- If you changed a `semantic` or `parsing` template, re-import documents or files and check whether summaries and structure changed- If you changed a `retrieval` template, rerun the relevant search and check whether query planning and recall behavior changed-- If you changed a `compression` template, re-trigger session commit or memory processing and check whether extraction and merge results changed+- If you changed a `compression` template, trigger the relevant flow with a new test session and inspect working memory and the archive overview; these alone do not establish that long-term memory extraction changed- If you changed a `memory` schema, inspect the final persisted memory files, directories, and field structure+Compare the original and modified templates with the same inputs, model, and other configuration, using separate test resources or sessions. Include a fact that should be retained, irrelevant information that should be omitted, and a case with an easily missed condition. Check whether summaries preserve key facts, retrieval finds the correct sources, and memories reach the expected directory and update existing content correctly. Record failures, latency, and model usage; smoother wording does not establish better accuracy.+### Common Troubleshooting PatternsSymptoms and first things to check:@@ -634,14 +681,15 @@ openviking/prompts/templates/It contains:-- `compression/`: compression, extraction, and merging+- `compression/`: working-memory compression and archive summaries- `indexing/`: relevance evaluation- `memory/`: memory type definitions- `parsing/`: structure analysis and semantic node generation- `processing/`: experience and strategy extraction- `retrieval/`: retrieval intent analysis- `semantic/`: file and directory summaries-- `skill/`: Skill summaries+- `skill/`: Skill summaries and privacy configuration extraction+- `skill_extract/`: Session Skill schemas- `test/`: test case generation- `vision/`: image, page, and table understandingdiff --git a/docs/en/guides/11-grafana-prometheus.md b/docs/en/guides/11-grafana-prometheus.mdindex a120d0800..67bd83e8e 100644--- a/docs/en/guides/11-grafana-prometheus.md+++ b/docs/en/guides/11-grafana-prometheus.md@@ -1,6 +1,6 @@# Using Prometheus and Grafana to View OpenViking Metrics-This document provides a complete end-to-end guide from scratch:+Connect the metric endpoint to a dashboard in four steps:1. Start OpenViking and verify that `/metrics` is accessible2. Start Prometheus to scrape OpenViking metrics@@ -47,7 +47,7 @@ OpenViking must have metrics enabled first. Minimal configuration reference:}```-After writing the configuration to `~/.openviking/ov.conf`, restart OpenViking Server.+Merge the metrics section into `~/.openviking/ov.conf`, then restart OpenViking Server.If you have not started the service yet, you can refer to:@@ -65,13 +65,15 @@ curl http://localhost:30300/metricsIf the response includes text with the `openviking_` prefix, metrics are enabled. For example:```text-# HELP openviking_http_requests_total Total number of HTTP requests+# HELP openviking_http_requests_total OpenViking metric.# TYPE openviking_http_requests_total counter-openviking_http_requests_total{method="GET",route="/api/v1/system/status",status="200"} 12+openviking_http_requests_total{method="POST",route="/api/v1/search/find",status="200"} 12```If the response returns `Prometheus metrics are disabled.`, the configuration has not taken effect or the service has not been restarted.+The examples use port 30300; OpenViking defaults to 1933. Keep the scrape target aligned with the port you actually start.+## Step 2: Deploy Using the Repository's Built-in Compose FilesThe repository already provides a set of ready-to-run observability examples, located at:@@ -99,13 +101,15 @@ By default, this configuration does several things:- Starts Prometheus and maps the host port to `30909`- Starts Grafana and maps the host port to `13000`-- Automatically configures the Grafana data source to `http://127.0.0.1:30909`+- Configures the Grafana data source as `http://prometheus:9090` in the general setup, or `http://127.0.0.1:30909` in the host-network setup- Automatically loads the OpenViking demo dashboard from the repository- Automatically loads `OpenViking - Feedback Baseline`, making it easy to directly view the baseline metrics for `openviking_feedback_*` and `openviking_feedback_channel_*`+These are local demonstration configurations with `admin/admin` credentials. The host-network variant still binds Prometheus to `0.0.0.0`; its name describes how it reaches OpenViking, not restricted dashboard exposure. For local use, bind the dashboard services to loopback (Prometheus `--web.listen-address=127.0.0.1:30909`, Grafana `GF_SERVER_HTTP_ADDR=127.0.0.1`) or restrict their network access.+### Approach A: General-Purpose-Run directly:+Run from the OpenViking repository root. Choose one Compose setup, since both use the same host ports:```bashdocker compose -f examples/grafana/docker-compose.yml up -d@@ -136,7 +140,7 @@ The characteristics of this approach are:- Prometheus uses the host network and directly scrapes `127.0.0.1:30300/metrics`- Grafana also uses the host network and directly connects to `http://127.0.0.1:30909`- There is no need to change OpenViking to `0.0.0.0`-- It does not trigger the security restriction that "non-localhost listening must configure `root_api_key`"+- Dev mode can remain bound to loopback; see [Authentication](04-authentication.md) before changing the OpenViking bind addressThe access addresses are still:@@ -177,7 +181,7 @@ Explanation:If your OpenViking is not listening on `30300`, change the target address in this file to your actual port, then re-run:```bash-docker compose -f examples/grafana/docker-compose.yml up -d+docker compose -f examples/grafana/docker-compose.yml restart prometheus```If you are using the Linux localhost approach, the corresponding file to modify is:@@ -193,14 +197,14 @@ targets: ["127.0.0.1:1933"]Then re-run:```bash-docker compose -f examples/grafana/docker-compose.localhost.yml up -d+docker compose -f examples/grafana/docker-compose.localhost.yml restart prometheus```## Step 4: Optional - Create a Docker Network for Manual DeploymentIf you are using the compose files above, you do not need to perform this step manually, because Compose automatically creates the default network.-Only when you insist on using `docker run` to start Prometheus and Grafana separately do you need to create an independent network first:+For separate `docker run` commands, create a shared network first:```bashdocker network create openviking-observability@@ -218,8 +222,9 @@ On many machines, `9090` is already occupied by another service. To reduce confldocker run -d \--name prometheus \--network openviking-observability \- -p 30909:9090 \- -v "$PWD/prometheus.yml:/etc/prometheus/prometheus.yml:ro" \+ -p 127.0.0.1:30909:9090 \+ --add-host host.docker.internal:host-gateway \+ -v "$PWD/examples/grafana/prometheus.yml:/etc/prometheus/prometheus.yml:ro" \prom/prometheus```@@ -267,7 +272,7 @@ Similarly, `3000` on many machines is also often occupied. It is recommended todocker run -d \--name grafana \--network openviking-observability \- -p 13000:3000 \+ -p 127.0.0.1:13000:3000 \grafana/grafana```@@ -311,11 +316,9 @@ Confirm that both the `prometheus` and `grafana` containers are running.## Step 8: First Query Directly in Grafana Explore-After adding the data source, do not rush to import a dashboard. It is recommended to first verify basic queries in `Explore`.--It is recommended to try these queries first:+After adding the data source, verify these queries in `Explore`:-Request volume:+Requests per second:```promqlrate(openviking_http_requests_total[5m])@@ -345,7 +348,7 @@ Model call volume:rate(openviking_model_calls_total[5m])```-Token usage:+Tokens per second:```promqlrate(openviking_operation_tokens_total[5m])@@ -357,6 +360,8 @@ If you are not yet sure which metric names exist, you can first query:{__name__=~"openviking_.*"}```+`rate()` needs multiple samples in the selected window. Feedback snapshot gauges, even those named `_total`, should be queried as current values; see [Vikingbot metrics validation](12-vikingbot-metrics-validation.md).+## Step 9: Import the OpenViking Built-in DashboardsIf you are using the repository's built-in compose files, these two dashboards will be automatically loaded into the `OpenViking` folder after Grafana starts.@@ -448,7 +453,7 @@ If you are using the compose auto-import approach, you can also first confirm wh### 5. The Dashboard Imports Successfully but the Panels Are Empty-This is usually not because the dashboard file is corrupted, but because:+Check these causes before changing the dashboard:- The corresponding metric samples do not yet exist in Prometheus- The filter conditions do not match the current environmentdiff --git a/docs/en/guides/16-cuvs.md b/docs/en/guides/16-cuvs.mdindex 1e024ebeb..5e9e8f23b 100644--- a/docs/en/guides/16-cuvs.md+++ b/docs/en/guides/16-cuvs.md@@ -6,7 +6,7 @@ The `cuvs` backend keeps OpenViking's embedded record store, scalar indexes, spaUse Linux x86_64 or aarch64 with a supported NVIDIA GPU and a compatible CUDA driver. Check the [cuVS installation requirements](https://docs.nvidia.com/cuvs/installation) and [Python package guide](https://docs.nvidia.com/cuvs/installation/python) for the selected release. Current cuVS source builds require CUDA Toolkit 12.2 or newer and Ampere or newer GPUs; package requirements depend on the chosen release.-Install the package matching the host CUDA major version:+From an OpenViking source checkout, activate your Python virtual environment and run **one** of the following installation options, matching the host CUDA major version:```bash# CUDA 12@@ -118,10 +118,10 @@ Explicit `backend: "cuvs"` continues to use cuVS for supported dense queries.mutations are coalesced for `auto_rebuild_debounce_ms`, and a worker builds thenew immutable GPU snapshot without holding the cross-backend mutation lock.The 500 ms default avoids rebuilding most intermediate batches during normal-interactive ingestion. For a known multi-call bulk load, wrap all writes in+interactive ingestion. For code using the internal vector backend, wrap a known multi-call bulk load in`async with backend.bulk_ingest(ctx=ctx):`: native visibility and persistencestill advance per call, while derived GPU maintenance is deferred until the-outermost scope exits and then scheduled once. This scope is a maintenance hint,+outermost scope exits and then scheduled once. This internal API is not exposed by the HTTP SDK. The scope is a maintenance hint,not a transaction or atomicity boundary; exiting it schedules the rebuild butdoes not itself wait for GPU readiness. The vector backend benchmark adds thatexplicit readiness wait before timing search. Changing the debounce remains@@ -142,8 +142,7 @@ device payload to `N * dimension * 2` bytes. CAGRA additionally retains approxim`N * intermediate_graph_degree * 4` bytes while building. Each cached filterbitset costs approximately `ceil(N / 32) * 4` bytes.-Prior index-only runs measured the following `cudaMemGetInfo` deltas from just-before to just after build; each value is the median of five clean processes:+The [historical index benchmark](https://github.com/volcengine/OpenViking/blob/main/benchmark/cuvs/PRELIMINARY_RESULTS.md) used an NVIDIA H20, cuVS 26.06, CuPy 14.1.1, and CUDA runtime 12.9, before request micro-batching was added. It measured the following `cudaMemGetInfo` deltas immediately before and after build; each value is the median of five clean processes. Use the [benchmark harness](https://github.com/volcengine/OpenViking/blob/main/benchmark/cuvs/README.md) to measure your own configuration:| Dataset | cuVS algorithm | Measured GPU delta || --- | --- | ---: |@@ -186,8 +185,10 @@ presenting the comparison as equal-dtype or equal-memory. This separation isintentional for the initial opt-inintegration and leaves existing CPU behavior unchanged. In auto mode, thefilter candidate thresholds can select either representation per query, so-applications that require one fixed numerical representation should use an-explicit backend or disable the native-routing thresholds.+applications that require one fixed representation for dense queries should select+an explicit backend and dtype. Setting the routing thresholds to zero only removes+candidate-count routing; auto mode can still fall back for memory pressure, GPU+unavailability, or a dirty snapshot.Lower-precision GPU storage is explicit rather than an implicit cast. Setting`dtype: "float16"` casts both the cuVS dataset and every query to float16 fordiff --git a/docs/en/guides/17-vikingbot.md b/docs/en/guides/17-vikingbot.mdindex 6a653ecce..f4ec32f70 100644--- a/docs/en/guides/17-vikingbot.md+++ b/docs/en/guides/17-vikingbot.md@@ -19,7 +19,7 @@ uv tool install "openviking[bot]" --upgrade``````bash [pip]-pip install "openviking[bot]" --upgrade --force-reinstall+pip install "openviking[bot]" --upgrade``````bash [pipx]@@ -38,6 +38,8 @@ Verify the installation:vikingbot --version```+Use a virtual environment for the pip option. Source installation also requires the [development build dependencies](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING.md).+### Install from Source```bash@@ -94,6 +96,8 @@ openviking-server doctorSee the [OpenViking Configuration Guide](01-configuration.md) for details. VikingBot inherits the root-level `vlm` as its Agent model by default, so you normally do not need to configure `bot.agents` again.+For an `api_key` server, register a User/Admin key and set it in `bot.ov_server.api_key` before starting the Bot; the root management key cannot serve as that user key. See [Authentication](04-authentication.md). In inherited `trusted` mode the Bot uses the server’s trusted identity configuration.+### 2. Start Both Services```bash@@ -113,6 +117,8 @@ ov find "my response preference"The URL configured by `ov config` should point to the current OpenViking Server, which defaults to `http://127.0.0.1:1933`. If authentication is enabled, also configure the current caller's User/Admin API Key.+Memory extraction runs asynchronously after a commit. An immediate `ov find` may return no result; check that the memory task completed before using retrieval as a persistence check.+## Scenario B: Debug the Agent LocallyUse this scenario to try VikingBot quickly or develop Agents, Tools, and Skills. `vikingbot chat` runs the Agent directly in the current process, without starting the Gateway first.@@ -186,7 +192,9 @@ vikingbot chatvikingbot chat --session my-session```-When no OpenViking Server is available, VikingBot runs in standalone mode. Local files, Shell, Web, and Skills remain available, but OpenViking resource retrieval and long-term memory are disabled.+Without an explicit `bot.ov_server.server_url`, a connection failure to the inherited server allows standalone mode in local chat. An unavailable explicitly configured server stops startup. An inherited authentication-mode mismatch also stops startup; for an explicit server, Bot adopts the reported mode and validates the credentials. Authentication failures and unhealthy HTTP responses stop startup. In integrated server-managed startup, Bot keeps the inherited upstream while the server starts.++In standalone mode, local files, Shell, Web, and Skills remain available, but OpenViking resource retrieval and long-term memory are disabled.## Scenario C: Use the Gateway as a Unified Entry Point@@ -210,6 +218,7 @@ The following example connects the Gateway to an existing OpenViking Server:},"ov_server": {"server_url": "https://openviking.example.com",+ "api_key_type": "user","api_key": "<bot-openviking-user-api-key>"}}diff --git a/docs/en/guides/18-openviking-assets.md b/docs/en/guides/18-openviking-assets.mdindex 4cc321a7d..00163fc82 100644--- a/docs/en/guides/18-openviking-assets.md+++ b/docs/en/guides/18-openviking-assets.md@@ -118,7 +118,9 @@ Git assets support:| `connector` | Yes | v1 supports only `git`. || `description` | No | Human-readable purpose of the asset. || `params.repo_url` | Yes | Git clone URL. |-| `params.branch` | No | Branch to ingest; it cannot be empty when set. |+| `params.branch` | No | Branch to ingest; non-empty when set and mutually exclusive with `params.commit`. |+| `params.commit` | No | Full 40-character hexadecimal SHA for a pinned revision; mutually exclusive with `params.branch`. |+| `to` | No | Exact resource destination URI. Must agree with an existing State mapping for the same asset; selected assets cannot share a destination. || `auth_ref` | No | Overrides `defaults.git.auth_ref`. || `watch_interval` | No | Overrides `defaults.git.watch_interval`. |@@ -166,7 +168,7 @@ assets:- requests```-The team maintains one Catalog; editing an asset there updates every Manifest that selects it.+The team maintains one Catalog. Each Manifest uses its latest definitions the next time it is applied; editing the file alone does not change ingested resources.Because the two documents share a shape, a Catalog can also be applied directly with`ov add-resource -m catalog.yaml`, which ingests everything it defines.@@ -191,8 +193,7 @@ slashes, and lowercases the host. HTTPS, SSH, and SCP-style URLs for the same renormally produce the same locator, while different branches produce different assets.The asset name is not part of the identity. Renaming an asset without changing its source and-branch keeps it associated with the existing resource. Changing the source or branch produces a-new asset and leaves the previous one as an orphan.+ref keeps it associated with the existing resource. Changing the source, branch, or pinned commit produces a new asset identity. Without an explicit `to`, the previous entry becomes an orphan. With `to`, the CLI can adopt the single existing State entry at that destination and sync it under the new identity.For safety, clone URLs cannot:@@ -246,6 +247,8 @@ ov add-resource --manifest manifest.yaml --args dry_run:trueIf any repository is unreadable, dry-run exits immediately with `PERMISSION_DENIED` and does notproduce an executable plan.+For a pinned `params.commit`, preflight checks repository access through HEAD; fetch/checkout verifies the exact SHA during import. A passing dry-run does not prove that the pinned commit is available.+### Apply the ManifestRemove `dry_run` after reviewing the plan:@@ -258,6 +261,8 @@ The repository contains a complete example — a shared Catalog plus a Manifestit — under[`examples/openviking-assets`](https://github.com/volcengine/OpenViking/tree/main/examples/openviking-assets).+Without `--wait`, successful submission does not mean parsing, semantic processing, and indexing have finished. Use `--wait` or inspect the returned task before validating retrieval. A branch follows changing content; pin `params.commit` and use `watch_interval: 0` when you need a fixed source revision.+## CredentialsManifests and Catalogs carry only `auth_ref` aliases and must not contain tokens, passwords, or@@ -337,7 +342,9 @@ Application rules:| State has no resource URI for the `asset_id` | Create a new resource. || State has an existing resource URI | Sync by passing the URI as `to` to `add_resource`. || An asset is no longer selected | Report it as an orphan; keep its resource and State entry. |-| The source or branch changes the `asset_id` | Create a new asset and report the old one as an orphan. |+| Source or ref changes, with no explicit `to` | Create a new asset and report the old one as an orphan. |+| A new identity declares `to` matching one State entry | Adopt that destination and sync under the new identity. |+| An existing identity declares a different `to` | Fail before submission; reconcile the resource and State mapping first. |State belongs to one execution environment and is not part of the Catalog or Manifest protocol.A repository that shares Manifests should normally add this to its `.gitignore`:@@ -360,7 +367,7 @@ managed by OpenViking Watches and connectors.3. `defaults.git.watch_interval`;4. `0`, which disables automatic refresh.-Temporarily apply a 60-minute interval to every selected asset:+Apply a 60-minute refresh interval to every selected asset; the resulting Watch continues on the server:```bashov add-resource --manifest manifest.yaml --watch-interval 60diff --git a/docs/zh/concepts/12-metrics.md b/docs/zh/concepts/12-metrics.mdindex ab6c40525..ad6375199 100644--- a/docs/zh/concepts/12-metrics.md+++ b/docs/zh/concepts/12-metrics.md@@ -1,6 +1,6 @@# 指标与 Metrics-OpenViking 提供一套面向机器抓取的指标体系,用于暴露系统运行态、请求质量、模型调用情况、资源处理吞吐、探针健康状态等信息。+OpenViking 提供一套面向机器抓取的指标体系,用于暴露系统运行态、请求状态、模型调用情况、资源处理吞吐、探针健康状态等信息。与人类排障用的 `/api/v1/observer/*` 和业务分析用的 `/api/v1/stats/*` 不同,Metrics 的目标是:@@ -94,7 +94,7 @@ MetricRegistry 是进程内的指标注册中心,用于保存当前指标值### 访问 `/metrics`-当前实现中,`/metrics` 未接入 `get_request_context` 等鉴权依赖,因此从代码行为上看,它当前等价于公开抓取端点。+`/metrics` 不要求 OpenViking API Key。需要限制访问时,在网关或反向代理上配置抓取权限。```bashcurl http://localhost:1933/metrics@@ -124,7 +124,7 @@ scrape_configs:| `context_type` | 检索上下文类型 | `resource` || `provider` | 模型或外部服务提供方 | `volcengine` || `model_name` | 模型名称 | `doubao-seed-1-8-251228` |-| `stage` | 阶段标签(按指标族定义) | 资源阶段:`parse`;Token 归因阶段:`embed_query` |+| `stage` | 阶段标签(按指标族定义) | 资源阶段:`parse_artifact`;Token 归因阶段:`embed_query` || `valid` | 当前样本是否为有效新鲜值 | `1` / `0` |其中:@@ -132,12 +132,12 @@ scrape_configs:- `account_id` 只在受控白名单指标上启用,避免高基数失控- `valid=0` 表示该状态/探针的当前样本是失败回退值或 stale fallback,不代表标签本身错误- `stage` 的语义依赖指标族:- - `openviking_resource_stage_*`:资源导入流水线阶段(如 `parse/persist/process`)+ - `openviking_resource_stage_*`:资源导入流水线阶段(如 `parse_artifact/target_resolve/content_commit`)- `openviking_operation_tokens_total`:Token Attribution 的归因阶段(如 `embed_query/rerank/vlm`)## 关键指标说明-下面的指标说明基于当前实际暴露的代表性指标输出(整理自 `openviking/metrics/collectors/`)。+下面列出 Collector 定义的代表性指标。某个指标是否出现,取决于功能是否启用、是否发生对应事件,以及 Collector 是否采集成功;未出现不能直接解释为数值为零。### 请求与操作@@ -168,14 +168,20 @@ scrape_configs:| `openviking_resource_stage_duration_seconds` | Histogram | `account_id, stage, status` | 资源导入阶段耗时分布 || `openviking_resource_wait_duration_seconds` | Histogram | `account_id, operation` | 资源导入等待耗时分布(例如队列等待) |-典型 `stage` 包括:+当前内置资源事件按执行路径上报以下 `stage` 值:-- `request`-- `parse`-- `summarize`-- `persist`-- `finalize`-- `process`+- `source_prepare`+- `parse_artifact`+- `target_resolve`+- `update_plan`+- `content_commit`+- `derived_enqueue`+- `semantic_queue_wait`+- `semantic_execute`+- `embedding_queue_wait`+- `embedding_execute`++Telemetry bridge 还识别旧摘要键,对应 `request`、`process`、`parse`、`finalize`、`summarize`、`wait`、`watch`。当前资源摘要构建器不生成这些键,因此它们不是当前导入流水线额外上报的阶段。该转换表也不包含 `persist`。### 向量检索、记忆与语义节点@@ -221,7 +227,7 @@ scrape_configs:- `openviking_vlm_*` 和 `openviking_embedding_*` 更适合业务侧针对性看板- `*_requests_*` 更偏“业务请求视角”- `*_calls_* / *_call_duration_* / *_tokens_*` 更偏“模型调用视角”(按 `provider/model_name` 聚合)- - `openviking_operation_tokens_total` 不存 `token_type="all/total"` 这类预聚合标签,总账建议在 TSDB 查询侧用 `sum(...)` 聚合得到+- `openviking_operation_tokens_total` 不存 `token_type="all/total"` 这类预聚合标签,总账建议在 TSDB 查询侧用 `sum(...)` 聚合得到### 队列、锁与系统运行态@@ -299,6 +305,8 @@ Python `get_stats()` 保留原有微秒字段。| `openviking_task_running` | Gauge | `task_type` | task tracker 执行中任务数 || `openviking_task_completed` | Gauge | `task_type` | task tracker 已完成任务数 || `openviking_task_failed` | Gauge | `task_type` | task tracker 失败任务数 |+| `openviking_task_cancelling` | Gauge | `task_type` | 正在取消的任务数 |+| `openviking_task_cancelled` | Gauge | `task_type` | 已取消任务数 |### Cache@@ -396,7 +404,7 @@ max by (job) (openviking_feedback_events_total{valid="0"})| `openviking_service_readiness` | Gauge | 可含 `valid` | 服务主 readiness || `openviking_api_key_manager_readiness` | Gauge | 可含 `valid` | API Key Manager readiness || `openviking_storage_readiness` | Gauge | `probe, valid` | 存储探针,例如 `agfs` |-| `openviking_model_provider_readiness` | Gauge | `provider, valid` | 模型提供方 readiness |+| `openviking_model_provider_readiness` | Gauge | `provider, valid` | VLM 客户端能否按配置创建;不发实际模型请求 || `openviking_async_system_readiness` | Gauge | `probe, valid` | 异步系统 readiness || `openviking_retrieval_backend_readiness` | Gauge | `probe, valid` | 检索后端 readiness || `openviking_encryption_component_health` | Gauge | `valid` | 加密组件总体健康 |@@ -410,6 +418,8 @@ max by (job) (openviking_feedback_events_total{valid="0"})### 加密(运行指标)+以下指标由 Python 加密事件驱动,不应当作所有 RAGFS 加密文件 I/O 的完整计数。评估实际文件读写吞吐时,还需结合 RAGFS 指标和启用的后端。+| 指标族 | 类型 | 常见标签 | 含义 ||--------|------|----------|------|| `openviking_encryption_operations_total` | Counter | `account_id, operation, status` | encrypt/decrypt 操作次数 |@@ -457,6 +467,8 @@ max by (job) (openviking_feedback_events_total{valid="0"})- `embedding`- `rerank`+`openviking_model_provider_readiness=1` 不证明模型认证、额度或远端推理可用;它只检查客户端实例能否创建。模型调用错误和耗时应结合实际调用指标判断。+## 配置示例### 启用 Metricsdiff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 4264e3dba..416afd834 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -2,6 +2,10 @@OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支持 Embedding、VLM、Rerank、存储、解析器等多个模块的配置。+本页供配置服务端时查阅。只连接已有服务端时,使用 [CLI 配置指南](../getting-started/05-cli-setup.md),无需在客户端配置模型或存储。++首次配置可以运行下面的向导。已有配置时,按要调整的能力查找对应段落,将示例字段合并到现有 JSON 对象中;不要用一个局部示例覆盖整份文件。修改 `ov.conf` 后需重启服务,运行时可修改的少数字段见下文。+首次配置推荐优先使用:```bash@@ -306,7 +310,7 @@ OpenAI 已于 2026 年 8 月 31 日[停止在 ChatGPT 登录的 Codex 中提供| `provider` | str | `"openai"`、`"azure"`、`"volcengine"`、`"vikingdb"`、`"jina"`、`"ollama"`、`"gemini"`、`"voyage"`、`"dashscope"`、`"minimax"`、`"cohere"`、`"litellm"` 或 `"local"` || `api_key` | str | API Key || `model` | str | 模型名称 |-| `dimension` | int | 向量维度 |+| `dimension` | int | 向量维度;Voyage 对应 `output_dimension` || `input` | str | 输入类型:`"text"` 或 `"multimodal"` || `batch_size` | int | 批量请求大小 || `encoding_format` | str | (仅 OpenAI / Azure)Embedding 值的传输格式:`"float"` 或 `"base64"`。留空时使用 OpenAI Python SDK 默认值;当上游网关无法正确处理 base64 embedding payload 时,可设置为 `"float"`。 |@@ -478,6 +482,26 @@ OpenAI 已于 2026 年 8 月 31 日[停止在 ChatGPT 登录的 Codex 中提供- `jina-embeddings-v5-text-small`: 677M 参数, 1024 维, 最大序列长度 32768 (默认)- `jina-embeddings-v5-text-nano`: 239M 参数, 768 维, 最大序列长度 8192+**Voyage provider 配置示例:**++```json+{+ "embedding": {+ "dense": {+ "provider": "voyage",+ "api_key": "pa-xxx",+ "api_base": "https://api.voyageai.com/v1",+ "model": "voyage-4-lite",+ "dimension": 1024+ }+ }+}+```++可使用 `voyage-4-lite`、`voyage-4`、`voyage-4-large` 等文本模型。可用模型与维度见 [Voyage 文本 Embedding 文档](https://docs.voyageai.com/docs/embeddings)。++省略 `dimension` 时,OpenViking 按内置模型表(`voyage-3`、`voyage-3-large`、`voyage-3.5`、`voyage-3.5-lite`、`voyage-4`、`voyage-4-lite`、`voyage-4-large`、`voyage-code-3`、`voyage-context-3`、`voyage-finance-2`、`voyage-law-2`)选择维度;未识别的模型回退为 1024。使用新模型时,请显式填写其支持的输出维度。当前适配器发送普通文本 `input`,不传递 Voyage 的 `input_type`,也不支持量化输出或需要专用上下文接口的调用方式。+**本地部署 (GGUF/MLX):** Jina 嵌入模型是开源的, 在 [Hugging Face](https://huggingface.co/jinaai) 上提供 GGUF 和 MLX 格式。可以使用任何 OpenAI 兼容的推理服务器 (如 llama.cpp、MLX、vLLM) 本地运行, 并将 `api_base` 指向本地端点:```json@@ -596,7 +620,7 @@ SDK 1.39.0 起提供所需的客户端上下文管理器和关闭方法,用于#### Sparse Embedding-> **注意:** 火山引擎的 Sparse embedding 从 `doubao-embedding-vision-251215` 模型版本起支持。+> 以下示例使用 `doubao-embedding-vision-251215`。所选模型是否支持文本 sparse 输出,请核对方舟[向量化文档](https://docs.volcengine.com/docs/ark/vectorization?lang=zh&redirect=1)。```json{@@ -635,7 +659,7 @@ provider,并设置 `storage.vectordb.sparse_weight > 0`。自托管模型的"hybrid": {"provider": "volcengine","api_key": "your-api-key",- "model": "doubao-embedding-hybrid",+ "model": "doubao-embedding-vision-251215","dimension": 1024}}@@ -726,7 +750,7 @@ provider,并设置 `storage.vectordb.sparse_weight > 0`。自托管模型的1. **L0(摘要)**:文件或目录摘要,默认字符上限为 2562. **L1(概览)**:目录概览,包含导航信息,默认字符上限为 4000-如果未配置 VLM,L0/L1 将直接从内容生成(语义性较弱),多模态资源的描述可能有限。+VLM 配置返回 `is_available() == false` 时,通用文件摘要会返回空内容,目录概览会退回“尚未就绪”的占位内容;可由本地解析器提取的代码骨架等仍按各自路径处理。这种状态不能视为已完成语义索引,应检查模型配置和对应处理任务。**支持的 provider:**- `volcengine`:火山引擎 VLM API@@ -756,14 +780,14 @@ LiteLLM 的 Bedrock bearer-token API-key 鉴权,请设置 `forward_api_key=tru"api_base": "https://openrouter.ai/api/v1","extra_headers": {"HTTP-Referer": "https://your-site.com",- "X-Title": "Your App Name"+ "X-OpenRouter-Title": "Your App Name"}}}```常见使用场景:-- **OpenRouter**: 需要 `HTTP-Referer` 和 `X-Title` 来标识应用+- **OpenRouter**:可选的 `HTTP-Referer` 和 `X-OpenRouter-Title` 用于[应用归属与展示](https://openrouter.ai/docs/app-attribution),不作为 API 认证凭据;`X-Title` 仍可兼容- **Kimi Coding**: 需要自定义 user agent 或追加订阅请求头时可以在这里覆盖- **OpenCode Go**(`https://opencode.ai/zen/go/v1`): 请求不带 `x-opencode-session` 会返回 HTTP 400 `MissingSessionID`。配置一个固定值即可,例如 `"extra_headers": {"x-opencode-session": "openviking-<your-host>"}`。OpenCode Go 只用这个 id 做路由和 prompt cache 优化,固定值不影响使用- **自定义代理**: 添加认证头或追踪头@@ -839,7 +863,7 @@ VLM 的 `model` 填写对应的方舟模型 endpoint ID。`video_fps` 仅用于### query_planner-可选的轻量模型配置,用于检索前的意图分析和 query 规划/改写。配置结构与 `vlm` 相同,但只影响 `search()` 的意图分析和 query expansion。未配置或配置为空时,OpenViking 会回退到 `vlm`,保持向后兼容。+可选的轻量模型配置,用于检索前的意图分析和 query 规划/改写。配置结构与 `vlm` 相同,用于 `search()` 的意图分析、query expansion,以及可选的服务端 recall 摘要重写。未配置或配置为空时,OpenViking 会回退到 `vlm`,保持向后兼容。> 在 `openviking-server init` 里可勾选启用本地轻量 query planner,向导会自动拉取 Ollama 模型并写入 `query_planner` 配置。对于已知的 query planner 模型,`search()` 会在运行时自动选择匹配的内置 prompt;不在映射表中的模型继续使用 `retrieval.intent_analysis`。@@ -870,7 +894,7 @@ ollama pull guoxuter/ov_intent_analysis_sft:v7_q8对于 `ollama/guoxuter/ov_intent_analysis_sft:v7_q8`(以及 `v4_q8`),OpenViking 会在 search 阶段自动使用对应的内置 prompt(分别为 `retrieval.ov_intent_analysis_sft_v7` 和 `retrieval.ov_intent_analysis_sft_v4`),不需要替换 prompt 文件,也不需要设置 `prompts.templates_dir`。如果使用未映射的模型,OpenViking 会继续使用默认的 `retrieval.intent_analysis` prompt。-这样可以用小模型承担检索规划,降低延迟,同时保留更强的 `vlm` 处理语义提取、记忆提取和多模态内容。+这样可以用小模型承担检索规划,同时保留更强的 `vlm` 处理语义提取、记忆提取和多模态内容。延迟需按模型、硬件和请求负载测量。### feishu@@ -909,7 +933,7 @@ ollama pull guoxuter/ov_intent_analysis_sft:v7_q8#### 远程资源网络防护-通过 URL 拉取资源时,OpenViking 会拒绝环回、链路本地、私有及其他非公网目标,以及不在代码托管白名单中的主机,并抛出 `PermissionDeniedError`。要从自建 GitHub Enterprise / GitLab / Azure DevOps 拉取代码,请将主机加入 `code` 下对应的白名单:+通过 URL 拉取资源时,默认网络检查会拒绝解析到非公网地址的目标。普通公网 URL 无需加入代码托管白名单;列入白名单的可信代码主机会跳过地址范围检查。接入自建 GitHub Enterprise / GitLab / Azure DevOps 时,可将主机加入 `code` 下对应的平台列表:| 字段 | 类型 | 说明 | 默认值 ||------|------|------|--------|@@ -918,11 +942,11 @@ ollama pull guoxuter/ov_intent_analysis_sft:v7_q8| `azure_devops_domains` | list[str] | 允许的 Azure DevOps 主机 | `["dev.azure.com", "ssh.dev.azure.com", "vs-ssh.visualstudio.com"]` || `code_hosting_domains` | list[str] | 允许的通用代码托管主机 | `["github.com", "gitlab.com", "gitcode.com", "gitee.com", "bitbucket.org", "codeberg.org", "gitea.com", "atomgit.com", "git.sr.ht"]` |-要从私有/内网地址(例如内部镜像)拉取,请将顶层的 `allow_private_networks` 设为 `true`(默认关闭,因此仅允许公网地址):+如果需要允许其他私有网络目标(例如内部镜像),可将顶层 `allow_private_networks` 设为 `true`。该开关默认关闭;`localhost` 及其子域等本地主机名仍会被拒绝。下面同时演示启用私有网络访问和添加代码主机:```json{- "allow_private_networks": false,+ "allow_private_networks": true,"code": {"github_domains": ["github.com", "github.example.com"]}@@ -1101,7 +1125,7 @@ Jev 适配器将 query 和候选文档作为共享的 System One `state`,支| `recall_intent_timeout_s` | float | 会话感知查询扩展的超时;超时后回退为用户原查询 | `5.0` || `recall_rewrite_timeout_s` | float | digest 重写的超时;超时后 `digest` 为空并照常返回 `rendered` | `30.0` |-两个 LLM 环节都是纯 opt-in:查询扩展需要传 `session_id`,重写需要传 `rewrite`。任一环节失败都优雅降级,不会阻塞召回。+查询扩展需要传入有内容的 `session_id` 并启用意图分析,重写需要传入 `rewrite`。这些模型调用受各自超时限制;失败后回退到未扩展的查询或未重写的结果。### grep@@ -1180,7 +1204,7 @@ Glob 引擎配置,用于路径模式匹配。这些设置为服务端配置,| `redirects` | array | 多写存储的文件重定向策略。命中后文件写入指定 backup,而不是 primary | `[]` || `queuefs` | object | QueueFS 配置。控制 `/queue` 的命名空间模式、后端和运行时参数 | `{ "mode": "shared", "backend": "sqlite", "recover_stale_sec": 0, "busy_timeout_ms": 5000 }` || `queue_db_path` | str(可选)| 旧版兼容字段,用于覆盖 QueueFS 的 sqlite 数据库文件路径。已被 `storage.agfs.queuefs.db_path` 取代。未设置时默认为 `{storage.workspace}/_system/queue/queue.db`。适用于 workspace 卷不支持 sqlite 的场景(例如某些网络文件系统) | `null` |-| `s3` | object | S3 backend configuration (when backend is 's3') | - |+| `s3` | object | S3 后端配置(`backend=s3` 时使用) | - |**配置示例**@@ -1410,55 +1434,6 @@ RAGFS 默认使用 Rust binding 模式,通过 Rust 实现直接访问文件系}```-##### Session Auto Commit 配置--`memory.session_auto_commit` 用于控制服务端 session 自动 commit 的全局行为。--```json-{- "memory": {- "session_auto_commit": {- "enabled": false,- "check_interval_seconds": 600.0,- "scan_rate_limit_files_per_second": 2.0- }- }-}-```--| 参数 | 类型 | 说明 | 默认值 |-|------|------|------|--------|-| `enabled` | bool | 自动 commit 总开关。开启后:未显式传入 `auto_commit_policy` 的新 session 会套用默认 policy,同时启动后台 idle 扫描器;关闭后两者都不发生 | `false` |-| `check_interval_seconds` | float | 两轮 idle 扫描之间的最小间隔,单位秒,必须大于 `0` | `600.0` |-| `scan_rate_limit_files_per_second` | float | idle 扫描时每秒最多读取的 session `.meta.json` 文件数,必须大于 `0`,用于限制大量 session 扫描时的存储 IO 压力 | `2.0` |--说明:--- `memory.session_auto_commit` 是服务端全局配置,不是单个 session 的业务 policy。-- session 级别的自动触发参数通过 session 级 `auto_commit_policy` 设置(见下表)。可以在创建 session 时通过 `POST /api/v1/sessions` 设置,也可以通过 `PATCH /api/v1/sessions/{session_id}/config` 部分更新。PATCH 时省略 `auto_commit_policy` 会保留现有策略,传 `null` 会禁用自动 commit;通过 `GET /api/v1/sessions/{session_id}` 查看生效策略。-- `enabled=false` 时:既无显式 policy、也无 `server.user_config_defaults.auto_commit_policy` 的新 Session 保持 auto commit 关闭,并返回 `auto_commit_policy: null`;同时不启动 `SessionAutoCommitScheduler`。-- `enabled=true` 时:- - 既无显式 policy、也无部署级默认 policy 的新 Session 会带上下方内置 policy。- - `SessionAutoCommitScheduler` 启动后立即开始一轮扫描,之后每轮结束后至少等待 `check_interval_seconds` 再开始下一轮;若一轮耗时已超过该值,则立即开始下一轮。- - 扫描过程中以 `scan_rate_limit_files_per_second` 为上限串行读取 session `.meta.json`,避免瞬时 IO 洪峰。- - 不会做单独的启动恢复扫描,idle 检查只发生在周期扫描时。-- token 和 message-count 自动触发在消息写入后内联执行,不依赖 scheduler,但同样以 session 是否带有 `auto_commit_policy` 为前提。--###### 单 session 自动 commit 策略--当 session 带有 `auto_commit_policy` 时,未传的字段会回退到下方推荐默认值。没有存储 policy 的 session 保持 auto commit 关闭。取值会被 clamp 到 `[0, 上限]`,未知字段会以 `InvalidArgumentError` 拒绝。设置和查看方式见 [Sessions API](../api/05-sessions.md#create-session)。--| 字段 | 类型 | 默认值 | 上限 | 说明 |-|------|------|--------|------|------|-| `pending_token_threshold` | int | 150000 | 1000000 | 当未提交的 pending token 超过该值(严格大于)时,会在消息写入后触发一次自动 commit。 |-| `message_count_threshold` | int | 100 | 1000 | 当未提交的 live message 数量超过该值(严格大于)时,会在消息写入后触发一次自动 commit。 |-| `idle_timeout_seconds` | int | 86400 | 604800 | 有未提交内容的 session 在空闲这么多秒后,进入服务端 idle scheduler 的处理范围。idle 触发的 commit 会归档全部积压消息,并忽略 `keep_recent_count`。 |-| `keep_recent_count` | int | 0 | 500 | 阈值触发的自动 commit 后保留(不归档)的最近 live message 数量。idle 超时触发的 commit 会忽略该值并归档所有消息。 |-| `min_commit_interval_seconds` | int | 0 | 604800 | 两次自动 commit 之间的最小间隔秒数(节流)。 |--代码入口:`openviking/session/auto_commit_policy.py:AutoCommitPolicy`。--##### S3 后端配置| 参数 | 类型 | 说明 | 默认值 |@@ -1692,12 +1667,60 @@ openviking-server --config /path/to/ov.conf| 字段 | 说明 | 默认值 ||------|------|--------|| `version` | 已废弃且会被忽略。OpenViking 始终使用 v3 记忆抽取链路;已有配置中保留该字段仍可正常加载,不会报错。 | `"v3"` |-| `custom_templates_dir` | 自定义 memory templates 目录。设置后会在内置模板之外加载该目录中的模板。 | `""` |+| `custom_templates_dir` | 自定义 memory schema 目录。后加载的同名 `memory_type` 会覆盖内置定义,新类型会追加;详见 [Prompt 指南](10-prompt-guide.md)。 | `""` || `extraction_enabled` | session commit 时是否执行长期记忆抽取。 | `true` || `session_skill_extraction_enabled` | session commit 时是否同时抽取可复用 skill 到当前用户的 skill 目录。 | `false` || `link_enabled` | 记忆抽取是否写入和解析 memory links。 | `false` || `session_auto_commit` | 服务端 session 自动 commit 的全局控制项。该配置属于 `memory` 段,不属于 `server` 段;详见 [Session Auto Commit 配置](#session-auto-commit-配置)。 | 见上文 |+#### Session Auto Commit 配置++`memory.session_auto_commit` 用于控制服务端 session 自动 commit 的全局行为。++```json+{+ "memory": {+ "session_auto_commit": {+ "enabled": false,+ "check_interval_seconds": 600.0,+ "scan_rate_limit_files_per_second": 2.0+ }+ }+}+```++| 参数 | 类型 | 说明 | 默认值 |+|------|------|------|--------|+| `enabled` | bool | 自动 commit 总开关。开启后:未显式传入 `auto_commit_policy` 的新 session 会套用默认 policy,同时启动后台 idle 扫描器;关闭后两者都不发生 | `false` |+| `check_interval_seconds` | float | 两轮 idle 扫描之间的最小间隔,单位秒,必须大于 `0` | `600.0` |+| `scan_rate_limit_files_per_second` | float | idle 扫描时每秒最多读取的 session `.meta.json` 文件数,必须大于 `0`,用于限制大量 session 扫描时的存储 IO 压力 | `2.0` |++说明:++- `memory.session_auto_commit` 是服务端全局配置,不是单个 session 的业务 policy。+- session 级别的自动触发参数通过 session 级 `auto_commit_policy` 设置(见下表)。可以在创建 session 时通过 `POST /api/v1/sessions` 设置,也可以通过 `PATCH /api/v1/sessions/{session_id}/config` 部分更新。PATCH 时省略 `auto_commit_policy` 会保留现有策略,传 `null` 会禁用自动 commit;通过 `GET /api/v1/sessions/{session_id}` 查看生效策略。+- `enabled=false` 时:既无显式 policy、也无 `server.user_config_defaults.auto_commit_policy` 的新 Session 保持 auto commit 关闭,并返回 `auto_commit_policy: null`;同时不启动 `SessionAutoCommitScheduler`。+- `enabled=true` 时:+ - 既无显式 policy、也无部署级默认 policy 的新 Session 会带上下方内置 policy。+ - `SessionAutoCommitScheduler` 启动后立即开始一轮扫描,之后每轮结束后至少等待 `check_interval_seconds` 再开始下一轮;若一轮耗时已超过该值,则立即开始下一轮。+ - 扫描过程中以 `scan_rate_limit_files_per_second` 为上限串行读取 session `.meta.json`,避免瞬时 IO 洪峰。+ - 不会做单独的启动恢复扫描,idle 检查只发生在周期扫描时。+- token 和 message-count 自动触发在消息写入后内联执行,不依赖 scheduler,但同样以 session 是否带有 `auto_commit_policy` 为前提。++##### 单 session 自动 commit 策略++当 session 带有 `auto_commit_policy` 时,未传的字段会回退到下方内置默认值。没有存储 policy 的 session 保持 auto commit 关闭。取值会被 clamp 到 `[0, 上限]`,未知字段会以 `InvalidArgumentError` 拒绝。设置和查看方式见 [Sessions API](../api/05-sessions.md#create-session)。++| 字段 | 类型 | 默认值 | 上限 | 说明 |+|------|------|--------|------|------|+| `pending_token_threshold` | int | 150000 | 1000000 | 当未提交的 pending token 超过该值(严格大于)时,会在消息写入后触发一次自动 commit。 |+| `message_count_threshold` | int | 100 | 1000 | 当未提交的 live message 数量超过该值(严格大于)时,会在消息写入后触发一次自动 commit。 |+| `idle_timeout_seconds` | int | 86400 | 604800 | 有未提交内容的 session 在空闲这么多秒后,进入服务端 idle scheduler 的处理范围。idle 触发的 commit 会归档全部积压消息,并忽略 `keep_recent_count`。 |+| `keep_recent_count` | int | 0 | 500 | 阈值触发的自动 commit 后保留(不归档)的最近 live message 数量。idle 超时触发的 commit 会忽略该值并归档所有消息。 |+| `min_commit_interval_seconds` | int | 0 | 604800 | 两次自动 commit 之间的最小间隔秒数(节流)。 |++代码入口:`openviking/session/auto_commit_policy.py:AutoCommitPolicy`。+### ovcli.conf你可以手动编辑此文件,也可以用 `ov config` 交互式生成。如果你维护着多个服务端的配置,可以用 `ov config switch` 在它们之间切换。@@ -1723,7 +1746,8 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远| 字段 | 说明 | 默认值 ||------|------|--------|| `url` | 服务端地址 | (必填) |-| `api_key` | API Key 认证(root key 或 user key) | `null`(无认证) |+| `api_key` | 通常填写用于数据访问的 user/admin key。API Key 模式下,这里填 root key 只能调用管理 API | `null`(无认证) |+| `root_api_key` | `ov` CLI 带 `--sudo` 时使用的 root key;CLI 在 `api_key` 未设置时也会回退到它。Python HTTP SDK 不使用该回退 | `null` || `account` | 可选的 trusted 模式 account 身份 header | `null` || `user` | 可选的 trusted 模式 user 身份 header | `null` || `profile` | 是否默认给 HTTP 请求追加 `profile=1`。对 Python HTTP client 和 `ov` CLI 都生效;也可通过 CLI 的 `--profile` 单次开启。是否真正生效还取决于服务端是否开启 `server.profile_enabled`。 | `false` |@@ -1811,6 +1835,12 @@ ov add-resource ./docs --exclude "*.tmp"`user_config_defaults` 提供添加目标和记忆抽取的部署级默认配置。添加操作中,显式请求目标仍然优先:`add_resource.to` / `add_resource.parent` 优先于用户默认值,`add_skill.target_uri` 优先于用户默认值。记忆策略优先级为 Session 策略 > User `settings/user_config.json` 策略 > `server.user_config_defaults.memory_policy` > 内核默认策略。`server.agent_evolution.enabled` 提供启动默认值,运行时优先级为 Account 覆盖 > Cluster 运行时覆盖 > 启动值。无需重启的修改应使用 Admin settings 接口;直接编辑 `ov.conf` 需要重启后生效。+支持的 add target URI:++- `resource_uri` 作为 `add_resource` 的默认父目录使用,等价于 `parent=<uri>, create_parent=true`。它必须是当前请求用户可写的 resource 目录 URI,支持 `viking://resources` 或 `viking://resources/...`、`viking://~/resources` 或 `viking://~/resources/...`、`viking://user/{user_id}/resources` 或 `viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources` 或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。`viking://~/...` 家目录别名会按请求用户解析。+- `skill_uri` 作为 `add_skill` 的默认目标根目录使用。v1 只允许 `viking://~/skills` 和 `viking://agent/skills`;不支持显式写成 `viking://user/{user_id}/skills`。+- 旧写法兼容:早期配置中的 `viking://user/resources` 和 `viking://user/skills` 会在配置加载时自动归一化为 `viking://~/resources` 和 `viking://~/skills`,并打印一条 info 日志。新配置请直接使用 `viking://~/...`;在 `add_targets` 之外,无 uid 的写法会在请求入口被拒绝。+### Usage Reporter可选的 Usage Reporter 从已 commit session 的 tool parts 中抽取记忆使用事件。内置文件日志 Sink 将每个事件写成一行扁平 JSON,并按小时滚动专用日志文件:@@ -1851,19 +1881,13 @@ ov add-resource ./docs --exclude "*.tmp"`event_time` 使用 UTC 时间。`tenant_id` 由部署 resource ID、事件所属的 account、user 和 Experience URI 拼接。`memory.recalled` 映射为 `experience.recall.count`,`memory.injected` 映射为 `experience.inject.count`。`object_id` 是稳定的 Usage Event ID。下游必须使用 `(tenant_id, object_id)` 复合键去重,不能跨 tenant 仅按 `object_id` 全局去重。查询时按 `tenant_id`、`event_name` 和 `event_time` 范围过滤,再通过 `sum(count)` 汇总。文件采集和下游投递仍为 best-effort。-支持的 add target URI:--- `resource_uri` 作为 `add_resource` 的默认父目录使用,等价于 `parent=<uri>, create_parent=true`。它必须是当前请求用户可写的 resource 目录 URI,支持 `viking://resources` 或 `viking://resources/...`、`viking://~/resources` 或 `viking://~/resources/...`、`viking://user/{user_id}/resources` 或 `viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources` 或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。`viking://~/...` 家目录别名会按请求用户解析。-- `skill_uri` 作为 `add_skill` 的默认目标根目录使用。v1 只允许 `viking://~/skills` 和 `viking://agent/skills`;不支持显式写成 `viking://user/{user_id}/skills`。-- 旧写法兼容:早期配置中的 `viking://user/resources` 和 `viking://user/skills` 会在配置加载时自动归一化为 `viking://~/resources` 和 `viking://~/skills`,并打印一条 info 日志。新配置请直接使用 `viking://~/...`;在 `add_targets` 之外,无 uid 的写法会在请求入口被拒绝。-启动方式和部署详情见 [服务部署](./03-deployment.md),认证详情见 [认证](./04-authentication.md)。<a id="encryption"></a>## encryption 段-启用静态数据加密,确保多租户环境下的数据安全与隔离。加密功能对用户完全透明,API 无变化。+启用静态数据加密后,存储层按账户加密新写入的文件,客户端沿用现有 API。已有明文文件不会自动加密,需单独迁移或重写。```json{@@ -1995,7 +2019,7 @@ ov add-resource ./docs --exclude "*.tmp"## Task Tracker 持久化-任务跟踪器记录异步任务状态,适用于返回 `task_id` 的接口(任务类型包括 `session_commit`、`add_resource`、`add_skill`、`admin_reindex`)。Task 记录始终持久化到 AGFS,因此一个实例返回的 `task_id` 可以在另一个实例上查询,任务历史也能在重启后继续访问。+任务跟踪器记录异步任务状态,适用于返回 `task_id` 的接口(任务类型包括 `session_commit`、`add_resource`、`add_skill`、`admin_reindex`)。Task 记录写入 AGFS,共享同一持久化存储的实例可以查询同一个 `task_id`,任务历史可在重启后访问,但仍受保留清理策略影响。使用 `memory` 文件存储后端时,记录不能跨进程重启保留。无需配置 `storage.task_tracker`。如果旧配置里仍包含 `storage.task_tracker`,OpenViking 会记录 warning 并忽略它。@@ -2005,7 +2029,9 @@ Task 记录文件位于所属账号的系统目录:/local/{account_id}/_system/tasks/{user_id}/{task_id}.json```-## 完整 Schema+## 配置结构示意++下面展示主要配置段的结构,不是可直接运行的完整配置或 JSON Schema。`string` 和用 `|` 连接的选项需要替换为实际值;没有列出的字段见前文各模块。```json{@@ -2069,10 +2095,11 @@ Task 记录文件位于所属账号的系统目录:"workspace": "string","agfs": {"backend": "local|s3|memory",- "timeout": 10- },- "transaction": {- "lock_expire": 300.0+ "timeout": 10,+ "pathlock": {+ "provider": "filesystem",+ "lock_expire_secs": 30.0+ }},"vectordb": {"backend": "local|cuvs|http|volcengine|vikingdb",@@ -2128,7 +2155,7 @@ Error: VLM request timeoutError: Rate limit exceeded```-火山引擎有速率限制。考虑批量处理时添加延迟或升级套餐。+先从 provider 返回的错误中确认限制的是请求数、token 用量还是账户配额,再调整请求节奏或申请相应额度。- 优先降低 `embedding.max_concurrent` / `vlm.max_concurrent`- 对偶发 `429` 可保留少量 `max_retries`;若希望快速失败,可将其设为 `0`diff --git a/docs/zh/guides/02-volcengine-purchase-guide.md b/docs/zh/guides/02-volcengine-purchase-guide.mdindex ae7622c88..c9feda58a 100644--- a/docs/zh/guides/02-volcengine-purchase-guide.md+++ b/docs/zh/guides/02-volcengine-purchase-guide.md@@ -1,6 +1,6 @@# 火山引擎模型购买指南-本指南介绍如何在火山引擎购买和配置 OpenViking 所需的模型服务。+本指南适用于自建 OpenViking:开通火山方舟模型、取得 API Key,并验证服务端配置。使用托管 OpenViking 时,无需在客户端配置这些模型,见[快速开始](../getting-started/02-quickstart.md)。## 概述@@ -90,7 +90,7 @@ OpenViking 需要以下模型服务:### 配置模板-创建 `~/.openviking/ov.conf` 文件,使用以下模板:+以下模板说明配置结构;替换所有字符串占位值后再使用。已有配置时只更新相关段落,保留存储、认证等其他配置:```json{@@ -99,8 +99,8 @@ OpenViking 需要以下模型服务:"api_key": "<your-api-key>","model": "<model-id>","api_base": "<api-endpoint>",- "temperature": <temperature-value>,- "max_retries": <retry-count>+ "temperature": 0.1,+ "max_retries": 3},"embedding": {"dense": {@@ -108,7 +108,7 @@ OpenViking 需要以下模型服务:"api_key": "<your-api-key>","model": "<model-id>","api_base": "<api-endpoint>",- "dimension": <vector-dimension>,+ "dimension": 1024,"input": "<input-type>"}}@@ -125,7 +125,7 @@ OpenViking 需要以下模型服务:| `api_key` | string | 是 | 火山方舟 API Key || `model` | string | 是 | 模型 ID,如 `doubao-seed-2-0-lite-260428` || `api_base` | string | 否 | API 端点地址,默认为北京区域端点,具体可见附录-区域端点 |-| `temperature` | float | 否 | 生成温度,控制输出随机性,范围 0-1,推荐 0.1 |+| `temperature` | float | 否 | 生成温度;支持范围取决于模型,本例使用 0.1 || `max_retries` | int | 否 | 请求失败时的重试次数,推荐 3 |#### Embedding 配置字段@@ -136,18 +136,18 @@ OpenViking 需要以下模型服务:| `api_key` | string | 是 | 火山方舟 API Key || `model` | string | 是 | 模型 ID,如 `doubao-embedding-vision-251215` || `api_base` | string | 否 | API 端点地址,默认为北京区域端点,具体可见附录-区域端点 |-| `dimension` | int | 是 | 向量维度,取决于模型(通常为 1024 或 768) |+| `dimension` | int | 是 | 向量维度,必须与模型输出及索引一致;本例选择 1024 || `input` | string | 否 | 输入类型:`"multimodal"`(多模态)或 `"text"`(纯文本),默认`"multimodal"` |### 配置示例-将以下内容保存为 `~/.openviking/ov.conf`:+将以下模型段落写入 `~/.openviking/ov.conf`,并保留已有的其他配置:```json{"vlm": {"provider": "volcengine",- "api_key": "sk-1234567890abcdef1234567890abcdef",+ "api_key": "your-ark-api-key","model": "doubao-seed-2-0-lite-260428","api_base": "https://ark.cn-beijing.volces.com/api/v3","temperature": 0.1,@@ -156,7 +156,7 @@ OpenViking 需要以下模型服务:"embedding": {"dense": {"provider": "volcengine",- "api_key": "sk-1234567890abcdef1234567890abcdef",+ "api_key": "your-ark-api-key","model": "doubao-embedding-vision-251215","api_base": "https://ark.cn-beijing.volces.com/api/v3","dimension": 1024,@@ -166,32 +166,28 @@ OpenViking 需要以下模型服务:}```-> ⚠️ **注意**:请将示例中的 `api_key` 替换为你在第 3 步获取的真实 API Key!+将两处 `your-ark-api-key` 替换为第 3 步取得的 API Key。这里是模型凭据,与连接 OpenViking Server 的 user/admin key 不同。## 验证配置### 测试连接-```python-import asyncio-from openviking_sdk import AsyncHTTPClient--async def test():- client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")- await client.initialize()+先检查模型配置,再启动服务:- # 添加简单资源测试- result = await client.add_resource(- path="https://example.com",- options={"reason": "测试连接"},- )- print(f"✓ 配置成功: {result['root_uri']}")+```bash+openviking-server doctor+openviking-server+```- await client.close()+另开终端,按[快速开始](../getting-started/02-quickstart.md)配置 CLI 并创建其中的 `quickstart.md`,然后导入到未使用的目录:-asyncio.run(test())+```bash+ov add-resource ./quickstart.md --to viking://resources/model-check --wait --timeout 120+ov find "谁负责备份流程?" --uri viking://resources/model-check```+导入请求被接受不代表模型配置验证成功。等任务完成后再检索;超时可通过返回的 task ID 查询进度,失败则查看任务错误。+### 查看使用情况在火山方舟控制台:@@ -206,16 +202,12 @@ asyncio.run(test())| 模型类型 | 计费单位 ||---------|---------|-| VLM | 按输入/输出 Token 计费 |-| Embedding | 按文本长度计费 |+| VLM | 所选模型的输入/输出计费规则见[方舟价格说明](https://www.volcengine.com/product/ark) |+| Embedding | 所选模型及输入模态的计费规则见[方舟价格说明](https://www.volcengine.com/product/ark) |### 免费额度-火山引擎为新用户提供免费额度:--- 首次开通赠送 Token-- 足够完成 OpenViking 的试用体验-- 详见:[火山方舟定价说明](https://www.volcengine.com/docs/82379/1399514)+是否有赠送额度、适用模型、有效期及超额计费方式,以账户控制台和[火山方舟价格说明](https://www.volcengine.com/product/ark)为准。先用小文档观察实际 token 消耗,再估算批量导入成本;免费额度不保证覆盖任意规模的试用。## 故障排除@@ -228,7 +220,7 @@ Error: Invalid API Key```**解决方法**:-1. 检查 API Key 是否正确复制(完整的 `sk-` 开头字符串)+1. 检查 API Key 是否完整复制、有无多余空格2. 确认 API Key 未被删除或过期3. 重新创建 API Key@@ -240,7 +232,7 @@ Error: Model not activated**解决方法**:1. 在火山方舟控制台检查模型状态-2. 确认模型处于"运行中"状态+2. 确认所选模型 ID 对当前账号可用3. 检查账户余额是否充足#### 网络连接问题@@ -253,7 +245,7 @@ Error: Connection timeout1. 检查网络连接2. 确认 `api_base` 配置正确3. 如在海外,确认可访问火山引擎服务-4. 增加配置中的超时时间+4. 服务可达但处理较慢时,再按[配置指南](01-configuration.md)调整相应超时### 获取帮助@@ -273,13 +265,14 @@ Error: Connection timeout| 区域 | API Base ||------|----------|| 北京 | `https://ark.cn-beijing.volces.com/api/v3` |-| 上海 | `https://ark.cn-shanghai.volces.com/api/v3` |++本文使用官方示例中的北京端点。其他地域请复制控制台给出的模型调用地址,不要只替换域名中的地域字符串。### 模型版本对照-| 模型名称 | 当前版本 | 发布日期 |-|---------|---------|---------|-| Doubao-Seed-2.0 | `doubao-seed-2-0-lite-260428` | 2025-12-28 |-| Doubao-Embedding-Vision | `doubao-embedding-vision-251215` | 2025-06-15 |+| 用途 | 本文示例模型 ID |+| --- | --- |+| VLM | `doubao-seed-2-0-lite-260428` |+| Embedding | `doubao-embedding-vision-251215` |-> 注:模型版本可能更新,请以火山方舟控制台显示为准。+这些是示例版本,不代表最新版本。可用版本见[方舟模型发布记录](https://docs.volcengine.com/docs/ark/model-release-announcement?lang=zh),Embedding 的输入和维度配置见[向量化文档](https://docs.volcengine.com/docs/ark/vectorization?lang=zh)。更换 Embedding 模型前,应检查现有索引是否需要重建。diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.mdindex 64aedd0a4..37e3e2cca 100644--- a/docs/zh/guides/03-deployment.md+++ b/docs/zh/guides/03-deployment.md@@ -62,9 +62,9 @@ openviking-server --config /path/to/ov.conf --host 127.0.0.1 --port 8000## 配置-服务端从 `ov.conf` 读取所有配置。配置文件各段详情见 [配置指南](01-configuration.md)。+服务端从 `ov.conf` 读取配置,也支持相应环境变量和启动参数覆盖。配置文件各段详情见 [配置指南](01-configuration.md)。-`ov.conf` 中的 `server` 段控制服务端行为:+以下是服务监听、认证和存储的配置片段,需要与已有 Embedding/VLM 配置合并:```json{@@ -230,7 +230,9 @@ Docker 镜像默认会同时启动:}```-未设置时服务将拒绝启动。如需自定义绑定地址,可通过环境变量 `OPENVIKING_SERVER_HOST` 覆盖。+未指定 `auth_mode` 且未配置 `root_api_key` 时,服务会自动进入 dev 模式,而 dev 模式监听非回环地址会拒绝启动。上面的示例用于 API Key 认证,其他认证方式见[认证指南](04-authentication.md)。如需自定义绑定地址,可通过 `OPENVIKING_SERVER_HOST` 覆盖。++镜像默认启用 Bot。API Key 模式下,Bot 还需要在 `bot.ov_server.api_key` 中配置可用的 User/Admin key,不能把 root key 当数据访问凭据。只部署 OpenViking Server 时使用下文的 `--without-bot`,需要 Bot 时按[VikingBot 配置](17-vikingbot.md)完成身份设置。**从旧镜像升级:** 运行目录为 `/app` 的旧镜像会把 `./data` 解析为默认挂载之外的 `/app/data`。删除旧容器前,先停止容器并备份其实际工作区(例如 `docker cp openviking:/app/data ./openviking-data-backup`)。启动替换容器前,将备份恢复到挂载的宿主机工作区,通常为 `~/.openviking/data`。若目标工作区已存在,先确认要保留的数据,不要直接覆盖。绝对工作区路径不变;其他相对路径现在以 `/app/.openviking` 为基准。@@ -238,7 +240,7 @@ Docker 镜像默认会同时启动:```bashdocker stop openvikingdocker pull ghcr.io/volcengine/openviking:latest-docker rm -f openviking+docker rm openviking# 然后重新 docker run ...```@@ -321,12 +323,12 @@ docker compose up -d#### 配置管理- **首次生成配置**:模板在 `OPENVIKING_CONF_CONTENT` 中预置了完整配置并引用 `${OPENAI_API_KEY}`。该变量仅在首次启动且 `ov.conf` 尚不存在时生效。-- **后续修改配置**:首次启动后,请通过 `railway ssh` 或 `railway service files upload --overwrite` 直接修改持久卷上的 `ov.conf`;也可以删除 `ov.conf` 后重新部署,让服务按当前 `OPENVIKING_CONF_CONTENT` 重新生成配置文件。+- **后续修改配置**:首次启动后,请按所安装的 [Railway CLI](https://docs.railway.com/cli) 文档 直接修改持久卷上的 `ov.conf`;需要重新生成时,先备份原配置并核对 `OPENVIKING_CONF_CONTENT`,再移走原配置并重新部署;生成后检查存储和认证设置。#### 资源与费用参考-- **推荐配置**:长期运行建议选择 **Hobby** 计划($5/月,包含 $5 用量抵扣)。以 ~0.5 GB 常驻内存估算,月均成本通常在 $5–$7 左右。-- **免费额度说明**:Railway Free 计划($1/月额度)不足以支持服务常驻运行;Trial 赠金适合短期体验评估,额度到期 30 天后持久卷将被清理,请注意按需备份数据。+- **费用估算**:套餐和资源计费规则见 [Railway 官方说明](https://docs.railway.com/pricing)。先用自己的文档规模和请求量试跑,再根据用量面板估算成本。+- **试用与数据保留**:试用额度、有效期和持久卷保留期限,以[Railway 试用说明](https://docs.railway.com/pricing/free-trial)及账户显示为准。请在对应保留期限前备份数据。> **安全提示**:服务部署后默认监听并暴露于公网。请妥善保管 `OPENVIKING_ROOT_API_KEY`,在对外开放前请阅读[公网访问安全指南](12-public-access.md)。@@ -418,7 +420,7 @@ helm install openviking ./deploy/helm/openviking \| 端点 | 认证 | 用途 ||------|------|------|-| `GET /health` | 否 | 存活探针 — 立即返回 `{"status": "ok"}` |+| `GET /health` | 否 | 进程存活检查;正常时返回 `status: ok`、`healthy: true`,不验证模型凭据 || `GET /ready` | 否 | 就绪探针 — 检查 AGFS、VectorDB、APIKeyManager、Embedding、Ollama |```bash@@ -430,7 +432,7 @@ curl http://localhost:1933/ready# {"status":"ready","checks":{"agfs":{"status":"ok","checks":{"filesystem":"ok","multiwrite_sync":"not_supported"}},"vectordb":"ok","api_key_manager":"ok","embedding":"ok","ollama":"not_configured"}}```-在 Kubernetes 中,使用 `/health` 作为存活探针,`/ready` 作为就绪探针。+在 Kubernetes 中,使用 `/health` 作为存活探针,`/ready` 作为就绪探针。各项检查的含义见[系统 API](../api/07-system.md)。## 相关文档diff --git a/docs/zh/guides/05-observability.md b/docs/zh/guides/05-observability.mdindex 10c049f51..f9a4c04a9 100644--- a/docs/zh/guides/05-observability.md+++ b/docs/zh/guides/05-observability.md@@ -1,20 +1,12 @@# 可观测性与排障-这份指南把 OpenViking 当前和“观测”有关的入口放在一起介绍,包括:--- 服务健康检查与组件状态-- 请求级 `telemetry`-- 终端侧 `ov tui`-- Web 侧 `Web Studio`(同 OV server,路径 `/studio`)-- `/metrics` 时序指标--如果你只想快速判断“该看哪里”,先看下面这张表。+按排查目标选择入口:服务是否就绪、数据是否写入、单次请求发生了什么,或一段时间内指标如何变化。## 先选哪个入口| 入口 | 适合看什么 | 典型场景 || --- | --- | --- |-| `/health`、`observer/*` | 服务是否健康、队列是否堆积、VikingDB/VLM 状态 | 部署验收、值班巡检 |+| `/health`、`/ready`、`observer/*` | 服务是否健康、队列是否堆积、VikingDB/VLM 状态 | 部署验收、值班巡检 || `ov tui` | `viking://` 文件树、目录摘要、文件正文、向量记录、受支持图片文件的预览 | 开发调试、核对资源是否真正落库 || `Web Studio`(`/studio`) | 同 OV server 的 Web UI:Home 看 token / 检索 / context commits 趋势,Resources 浏览 URI,Retrieval 直接发 find,Request Logs 看审计日志 | 不想手敲命令时做交互式排查 || `telemetry` | 单次请求耗时、token、向量检索、资源处理阶段 | 排查一次具体调用为什么慢、为什么结果异常 |@@ -24,19 +16,19 @@### 健康检查-`/health` 提供简单的存活检查,不需要认证。+`/health` 提供无需认证的存活检查,下方仅展示部分响应字段。就绪检查用 `/ready`。模型 observer 的健康状态不证明凭证有效或调用成功,详见[系统状态](../api/07-system.md)。```bashcurl http://localhost:1933/health``````json-{"status": "ok"}+{"status": "ok", "healthy": true}```### 整体系统状态-**Python SDK (HTTP)**+**Python HTTP SDK(`SyncHTTPClient`)**```pythonstatus = client.get_status()@@ -77,7 +69,7 @@ curl http://localhost:1933/api/v1/observer/system \| `GET /api/v1/observer/vikingdb` | VikingDB | 向量数据库状态 || `GET /api/v1/observer/models` | Models | VLM、Embedding 和 Rerank 模型状态 || `GET /api/v1/observer/lock` | Lock | 锁和事务状态 |-| `GET /api/v1/observer/retrieval` | Retrieval | 检索质量指标 |+| `GET /api/v1/observer/retrieval` | Retrieval | 检索次数和耗时,不代表相关性评估 || `GET /api/v1/observer/filesystem` | Filesystem | 文件系统操作指标 |例如:@@ -89,7 +81,7 @@ curl http://localhost:1933/api/v1/observer/queue \### 快速健康检查-**Python SDK (HTTP)**+**Python HTTP SDK(`SyncHTTPClient`)**```pythonif client.is_healthy():@@ -109,11 +101,11 @@ curl http://localhost:1933/api/v1/debug/health \### 响应时间-每个 API 响应都包含一个 `X-Process-Time` 请求头,表示服务端处理时间(单位为秒):+`X-Process-Time` 表示请求进入服务端到发送响应头的耗时,单位为秒。流式响应不包含完整响应体的传输时间:```bashcurl -v http://localhost:1933/api/v1/fs/ls?uri=viking:// \- -H "X-API-Key: your-key" 2>&1 | grep X-Process-Time+ -H "X-API-Key: your-key" 2>&1 | grep -i X-Process-Time# < X-Process-Time: 0.0023```@@ -185,7 +177,7 @@ http://127.0.0.1:1933/studio写操作(`Add Resource`、`Add Memory`、租户/用户管理)通过当前已登录的 API key 鉴权,没有额外的 `--write-enabled` 开关需要打开。-从观测角度看,Studio 的一个优点是直接调用 `/api/v1/console/*` BFF 的统计接口(dashboard summary、token series、context commits、audit logs),跟旧 console 复用同一套数据,只是 UI 换了。对于 `find`、`add-resource` 和 `session commit` 这类操作,结果面板可以展开看 `telemetry.summary`。+Studio 从 `/api/v1/console/*` 读取 dashboard summary、token series、context commits 和 audit logs。查看 `find`、`add-resource` 和 `session commit` 等操作的 `telemetry.summary` 时,按[操作遥测](07-operation-telemetry.md)读取完整 HTTP 响应。Studio 更适合“边点边看”的交互式排查;如果你要把观测数据接到自己的日志系统或自动化链路,建议直接调用 HTTP API 或 SDK,并显式请求 telemetry。@@ -484,7 +476,7 @@ OpenViking 将信号级别的可观测性配置统一放在 `server.observabilit### 直接访问 `/metrics`-当前实现中,`/metrics` 未接入 `get_request_context` 等鉴权依赖,因此从代码行为上看,它当前等价于公开抓取端点:+启用后,`/metrics` 是无需认证的抓取端点:```bashcurl http://localhost:1933/metrics@@ -514,7 +506,7 @@ scrape_configs:- 在 Prometheus UI 里执行 `openviking_http_requests_total`- 或执行 `openviking_service_readiness`-- 如果已经能返回时间序列,说明 Grafana 后续就能正常出图+- 返回时间序列说明抓取正常;各面板还需要对应指标产生样本,且筛选条件匹配如果这一步没有数据,先回到上面的 Prometheus 抓取配置,确认 `targets`、`metrics_path` 和网络连通性。diff --git a/docs/zh/guides/07-operation-telemetry.md b/docs/zh/guides/07-operation-telemetry.mdindex a6fb04ce7..347eae7d6 100644--- a/docs/zh/guides/07-operation-telemetry.md+++ b/docs/zh/guides/07-operation-telemetry.md@@ -8,7 +8,7 @@- 观察 token 或检索行为- 把结构化执行摘要接入你自己的日志或观测系统-更完整的观测入口说明,包括健康检查、`ov tui` 和 `OpenViking Console`,请先看 [可观测性与排障](05-observability.md)。+更完整的观测入口说明,包括健康检查、`ov tui` 和 `Web Studio`,请先看 [可观测性与排障](05-observability.md)。## 基本说明@@ -50,7 +50,7 @@ Telemetry 是按需返回的。只有你显式请求时,OpenViking 才会在- `telemetry.id` 是不透明的关联 ID- `telemetry.summary` 是面向调用方的结构化摘要- 只有本次操作实际产出的分组才会返回-- 数值型 `0` 默认不会出现在响应里+- 可选分组中的数值 0 通常会省略;cuVS 的显存估算保留零值## 当前支持范围@@ -66,10 +66,17 @@ Telemetry 是按需返回的。只有你显式请求时,OpenViking 才会在- `POST /api/v1/sessions`- `POST /api/v1/sessions/{session_id}/messages`- `POST /api/v1/sessions/{session_id}/commit`+- `POST /api/v1/sessions/{session_id}/messages/batch`+- `PATCH /api/v1/sessions/{session_id}/config`+- `POST /api/v1/content/write`+- `POST /api/v1/content/batch-write`+- `POST /api/v1/content/set_tags`+- `POST /api/v1/skills/find`+- `PUT /api/v1/skills/{skill_name}`### Python SDK-Python 客户端里,下面这些调用支持相同的 telemetry 语义:+Python 客户端的下列操作可请求 telemetry。高层方法的返回值不一定保留 HTTP 顶层 telemetry,读取完整摘要见下文 Python 示例:- `add_resource(...)`- `add_skill(...)`@@ -144,7 +151,7 @@ summary 顶层这 3 个基础字段总会存在:## 字段说明-只有这次操作实际产出的字段才会返回。某个分组缺失时,应理解为“不适用”,而不是默认等于 0。+只有这次操作实际产出的字段才会返回。分组缺失可能表示不适用、未采集,或零值被裁剪。不能据此认定数值为 0,也不能证明该阶段已经执行。### 顶层 telemetry 字段@@ -265,18 +272,20 @@ admission,所以其 `gpu_gate_queue` 为零;worker 侧等待仍计入 `batch### `summary.memory`-这个分组常见于 `session.commit` 这类记忆提取流程。+这个分组描述已采集的记忆提取指标。当前 commit 响应仅覆盖同步归档和任务提交,后台提取可能随后完成。下表保留的旧阶段名称仅在对应路径实际记录时出现,不代表每次 V3 提取都会依次执行这些阶段。| 字段 | 含义 || --- | --- || `summary.memory.extracted` | 本次操作最终抽取出的 memory 数量 || `summary.memory.extract.duration_ms` | memory extract 主流程总耗时 |-| `summary.memory.extract.candidates.total` | 最终动作执行前的候选总数 |+| `summary.memory.extract.candidates.total` | 当前 V3 为新写入 URI 数与编辑 URI 数之和,不代表所有提议的候选 || `summary.memory.extract.candidates.standard` | 普通 memory candidate 数量 || `summary.memory.extract.actions.created` | 新建 memory 数量 || `summary.memory.extract.actions.merged` | 合并到已有 memory 的次数 || `summary.memory.extract.actions.deleted` | 删除旧 memory 的次数 |-| `summary.memory.extract.actions.skipped` | 被跳过的 candidate 数量 |+| `summary.memory.extract.actions.skipped` | 被跳过的操作数 |+| `summary.memory.extract.actions.failed` | 已记录的提取错误数 |+| `summary.memory.extract.actions_by_type` | 按记忆类型分组的动作计数 || `summary.memory.extract.stages.prepare_inputs_ms` | 提取前准备输入数据的耗时 || `summary.memory.extract.stages.llm_extract_ms` | 调用 LLM 做提取的耗时 || `summary.memory.extract.stages.normalize_candidates_ms` | 解析并归一化候选的耗时 |@@ -327,26 +336,30 @@ curl -X POST http://localhost:1933/api/v1/resources \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \-d '{- "path": "./docs/readme.md",+ "path": "https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md",+ "wait": true,+ "timeout": 120,"reason": "telemetry demo","telemetry": true}'```-### Python SDK--```python-from openviking_sdk import AsyncHTTPClient+### Python:读取完整 HTTP 响应-client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")-await client.initialize()+SDK 可发送 `options={"telemetry": True}`,但当前 `find()` 等高层方法只返回 `result`,不会保留顶层 telemetry。应用需要读取摘要时,使用 HTTP 请求:-result = await client.find(- query="memory dedup",- options={"telemetry": True},-)-print(result["telemetry"]["summary"]["operation"])-print(result["telemetry"]["summary"]["duration_ms"])+```python+import httpx++with httpx.Client(base_url="http://localhost:1933", timeout=30) as client:+ response = client.post(+ "/api/v1/search/find",+ headers={"X-API-Key": "your-user-key"},+ json={"query": "memory dedup", "limit": 5, "telemetry": True},+ )+ response.raise_for_status()+ payload = response.json()+ print(payload["telemetry"]["summary"])```## 限制与注意事项@@ -354,8 +367,8 @@ print(result["telemetry"]["summary"]["duration_ms"])- 当前对外只提供 summary-only telemetry- `{"telemetry": {"events": true}}` 不是当前支持的公开请求形态- 事件流风格的选择参数不属于当前公开接口-- `session.commit` 只有在 `wait=true` 时才支持 telemetry-- 如果 `session.commit` 使用 `wait=false` 并请求 telemetry,服务端会返回 `INVALID_ARGUMENT`+- 当前 `session.commit` 没有 `wait` 参数。响应 telemetry 覆盖归档和提交,不代表后台提取完成。有 task ID 时继续查询任务状态,见[会话](../api/05-sessions.md)。+- 资源导入使用 `wait=false` 时,后台处理也可能在响应返回后继续。需要摘要包含请求内完成的处理时,使用等待模式。- telemetry 的顶层结构稳定,但具体有哪些 summary 分组取决于实际操作## 相关文档diff --git a/docs/zh/guides/10-prompt-guide.md b/docs/zh/guides/10-prompt-guide.mdindex 589541ee2..8912b716b 100644--- a/docs/zh/guides/10-prompt-guide.md+++ b/docs/zh/guides/10-prompt-guide.md@@ -151,16 +151,31 @@ peer_enabled: true## 当前 Prompt 模板说明-下面按类别列出当前全部模板。每个条目都说明它用于哪个处理环节,以及主要影响哪类对外能力。+下面按类别说明模板用途、输入和相关处理环节。模板文件存在不代表当前请求会调用它;调用路径、模型配置与功能开关共同决定是否生效。阅读这一节时,可以用一个简单规则:- 普通 prompt 模板,重点看“作用”和“关键输入”- memory schema,重点看“作用”和“关键字段”+### 先确认模板是否生效++| 模板或类别 | 当前使用条件 |+| --- | --- |+| `compression.ov_wm_v2`、`compression.ov_wm_v2_update` | 会话 working memory 的首次生成与后续更新,见 `openviking/session/session.py` |+| `retrieval.intent_analysis` | 启用意图分析且会话中有可用内容时,用于查询规划;特定 query planner 模型会选择专用模板,见下文 |+| `retrieval.recall_rewrite` | 启用服务端 recall 压缩时,将已组装上下文改写为带来源的摘要 |+| `semantic.*` | 语义处理队列根据文件类型或目录任务选择模板 |+| `parsing.image_summary`、`parsing.audio_summary`、`parsing.video_summary` | 媒体摘要路径;音视频还要求启用支持对应输入的 VLM |+| `memory/tools.yaml`、`memory/skills.yaml` | 内置 `enabled: false`,仅修改描述不会自动启用 |+| `memory/experimental_memory/*.yaml` | 启用 `memory.experimental_memory_switch` 后加载 |+| `skill_extract/session_skills.yaml` | Session Skill 提取使用的独立 schema,加载方式见下文 |++`compression.structured_summary`、`indexing.relevance_scoring`、`parsing.chapter_analysis`、`parsing.context_generation`、`parsing.semantic_grouping`、`processing.*` 和 `test.skill_test_generation` 保留在模板目录中,但当前服务端源码未找到对应的调用入口。下文保留其输入与用途,供维护和扩展参考;不要据此判断修改它们就会改变在线结果。+### Compression-这一类 prompt 主要用于 session 压缩和 working memory 更新。长期记忆抽取使用 `memory` 类别下的 v2 schema-driven memory templates。+这一类 prompt 主要用于 session 压缩和 working memory 更新。长期记忆提取使用 `memory` 类中的 schema 定义。- `compression.ov_wm_v2`- 生效环节:首次 working memory 生成阶段@@ -175,7 +190,7 @@ peer_enabled: true- 关键输入:`previous_working_memory`、`messages`- `compression.structured_summary`- - 生效环节:session archive 摘要生成阶段+ - 设计用途对应环节:session archive 摘要生成阶段- 影响能力:历史会话压缩摘要、后续回顾和检索效果- 作用:为归档后的 session 生成结构化摘要- 关键输入:`latest_archive_overview`、`messages`@@ -185,7 +200,7 @@ peer_enabled: true这一类 prompt 主要用于为检索或索引辅助流程做相关性判断。- `indexing.relevance_scoring`- - 生效环节:候选内容相关性评估阶段+ - 设计用途对应环节:候选内容相关性评估阶段- 影响能力:检索结果排序、候选筛选质量- 作用:评估候选内容与用户查询之间的相关性- 关键输入:`query`、`candidate`@@ -236,7 +251,7 @@ peer_enabled: true- 作用:定义“用户是谁”这一类稳定信息的存储结构- 关键字段:`content`-- `skills`+- `skills`(默认禁用)- 生效环节:skill 使用记忆落盘与更新阶段- 影响能力:skill 使用统计、经验沉淀与推荐流程- 作用:定义 skill 使用次数、成功率、适用场景等信息@@ -248,7 +263,7 @@ peer_enabled: true- 作用:定义 agent 的核心真值、边界、风格和连续性- 关键字段:`core_truths`、`boundaries`、`vibe`、`continuity`-- `tools`+- `tools`(默认禁用)- 生效环节:工具使用记忆落盘与更新阶段- 影响能力:工具使用经验、最佳参数、失败模式沉淀- 作用:定义工具调用统计和工具使用经验的存储结构@@ -265,13 +280,13 @@ peer_enabled: true这一类 prompt 主要用于把原始资源内容转成适合检索和理解的结构化节点、章节、摘要或图像概述。- `parsing.chapter_analysis`- - 生效环节:长文档章节划分阶段+ - 设计用途对应环节:长文档章节划分阶段- 影响能力:文档章节结构、页面组织效果- 作用:分析文档内容并划分合理的章节结构- 关键输入:`start_page`、`end_page`、`total_pages`、`content`- `parsing.context_generation`- - 生效环节:文档节点语义生成阶段+ - 设计用途对应环节:文档节点语义生成阶段- 影响能力:节点 abstract/overview 质量、后续检索匹配效果- 作用:为文本节点生成更短、更适合检索的语义标题、abstract 和 overview- 关键输入:`title`、`content`、`children_info`、`instruction`、`context_type`、`is_leaf`@@ -283,29 +298,34 @@ peer_enabled: true- 关键输入:`context`- `parsing.semantic_grouping`- - 生效环节:语义分组与切分阶段+ - 设计用途对应环节:语义分组与切分阶段- 影响能力:文档节点粒度、内容块切分质量- 作用:根据语义决定内容应该合并还是拆分- 关键输入:`items`、`threshold`、`mode`+- `parsing.audio_summary`、`parsing.video_summary`+ - 生效环节:音视频内容理解,要求 VLM 支持并启用对应媒体输入+ - 作用:生成用于语义索引的媒体概览,保留主题、事件、事实与可识别的内容+ - 关键输入:`filename`、`fallback_language`;媒体文件通过模型输入另行传入+### Processing这一类 prompt 主要用于从交互记录、工具链和资源背景中提炼策略或经验,不直接面向单次用户问答,而是面向后处理和知识沉淀。- `processing.interaction_learning`- - 生效环节:交互后经验提炼阶段+ - 设计用途对应环节:交互后经验提炼阶段- 影响能力:可复用交互经验、有效资源和成功 skill 的沉淀- 作用:从交互记录中抽取可复用经验- 关键输入:`interactions_summary`、`effective_resources`、`successful_skills`- `processing.strategy_extraction`- - 生效环节:资源添加后策略提炼阶段+ - 设计用途对应环节:资源添加后策略提炼阶段- 影响能力:资源背景意图的结构化提炼和后续复用- 作用:从资源添加原因、指令和抽象信息中提炼使用策略- 关键输入:`reason`、`instruction`、`abstract`- `processing.tool_chain_analysis`- - 生效环节:工具链分析阶段+ - 设计用途对应环节:工具链分析阶段- 影响能力:工具组合模式识别、工具经验沉淀- 作用:分析工具调用链并识别有价值的使用模式- 关键输入:`tool_calls`@@ -320,6 +340,16 @@ peer_enabled: true- 作用:结合压缩摘要、最近消息和当前消息生成检索计划- 关键输入:`compression_summary`、`recent_messages`、`current_message`、`context_type`、`target_abstract`+- `retrieval.ov_intent_analysis_sft_v4`、`retrieval.ov_intent_analysis_sft_v7`+ - 生效条件:query planner 的 `model` 分别精确匹配 `ollama/guoxuter/ov_intent_analysis_sft:v4_q8` 或 `ollama/guoxuter/ov_intent_analysis_sft:v7_q8`+ - 作用:使用对应模型的查询规划协议;其他模型使用 `retrieval.intent_analysis`+ - 修改默认模板前先检查模型配置,避免改到未使用的模板++- `retrieval.recall_rewrite`+ - 生效环节:服务端上下文组装后的可选压缩+ - 作用:根据当前查询生成带来源 URI 的要点;输出需满足调用方的格式与来源校验+ - 关键输入:`query`、`rendered`、`max_bullets`+### Semantic这一类 prompt 主要用于文件级和目录级摘要生成,是语义索引构建的重要部分。@@ -358,12 +388,17 @@ peer_enabled: true- 作用:从 Skill 名称、描述和正文中抽取关键检索信息- 关键输入:`skill_name`、`skill_description`、`skill_content`+- `skill.privacy_extraction`+ - 生效环节:Skill 隐私配置提取+ - 作用:识别需要由用户维护的私有配置项,供占位符替换与隐私配置存储使用+ - 关键输入:`skill_name`、`skill_description`、`skill_content`+### Test这一类 prompt 主要用于辅助生成测试样例。- `test.skill_test_generation`- - 生效环节:Skill 测试辅助阶段+ - 设计用途对应环节:Skill 测试辅助阶段- 影响能力:Skill 场景测试设计与验证样例生成- 作用:根据多个 Skill 的名称和描述生成测试用例- 关键输入:`skills_info`@@ -514,9 +549,11 @@ export OPENVIKING_PROMPT_TEMPLATES_DIR=/path/to/custom-prompts加载行为:-- 内置 memory schema 会先加载-- 如果配置了 `memory.custom_templates_dir`,再继续加载自定义目录中的 schema-- 因此,memory 自定义更接近“扩展和补充”,而不是完全替换整套内置模板+1. 先加载内置 `memory/` 目录中的 schema。+2. 若启用 `memory.experimental_memory_switch`,再加载内置 `memory/experimental_memory/`。+3. 若配置 `memory.custom_templates_dir`,加载该目录;否则尝试加载所选 prompt 目录下的 `memory/`。++后加载的同名 `memory_type` 会替换先前定义,新的类型会追加。目录只读取直接包含的 `.yaml` 和 `.yml` 文件,不递归加载子目录。因此,自定义 schema 既能新增类型,也能覆盖内置类型;改名会创建另一种类型。加载失败会记录日志,应检查实际加载结果。示例目录:@@ -552,6 +589,12 @@ custom-memory/- 修改 `tools`- 影响工具经验沉淀和工具使用建议结果+### Session Skill Schema++`skill_extract/session_skills.yaml` 使用 memory schema 格式,但由 Session Skill 提取链路单独加载。它定义用户要求记住的会话技能,与 `memory/skills.yaml` 中的技能使用统计不同。++加载器直接读取所选 prompt 目录下的 `skill_extract/`,没有普通 prompt 的逐文件内置回退。使用自定义 `prompts.templates_dir` 或 `OPENVIKING_PROMPT_TEMPLATES_DIR` 且需要 Session Skill 提取时,应同时复制内置 `skill_extract/` 目录,并检查 schema 加载日志。仅复制一个 `semantic/` 文件不足以满足这条链路。+### 自定义时的高风险改动以下改动最容易破坏现有链路:@@ -600,6 +643,8 @@ custom-memory/- 新 schema 是否被成功加载- 目标记忆类型是否真的参与了提取和落盘+普通模板默认会被 `PromptManager` 缓存。更改文件后,重启使用这些模板的服务进程;内嵌开发场景可清理对应 manager 的缓存并重新加载。Memory registry 也需要重新创建,不能假设已运行的进程会自动读取新的 schema。+### 再验证对外结果是否变化从使用者角度验证最有效:@@ -607,9 +652,11 @@ custom-memory/- 如果改的是 `vision` 类模板,就重新解析图片、表格或扫描 PDF,看结果是否变化- 如果改的是 `semantic` 或 `parsing` 类模板,就重新导入文档或文件,看摘要和结构是否变化- 如果改的是 `retrieval` 类模板,就重新执行相关搜索,看 query 规划和召回效果是否变化-- 如果改的是 `compression` 类模板,就重新触发 session commit 或 memory 处理流程,看记忆抽取和合并结果是否变化+- 如果改的是 `compression` 类模板,就用新的测试会话触发对应流程,检查 working memory 与归档概览;它们不能单独证明长期记忆提取已改变- 如果改的是 `memory` 类 schema,就检查最终落盘的记忆文件内容、目录和字段结构是否符合预期+比较修改前后的效果时,保持输入、模型和其他配置不变,使用独立测试资源或会话。至少包含一个应保留的事实、一个应忽略的无关信息,以及一个容易遗漏条件的例子。按目标检查:摘要有没有丢失关键事实,检索是否召回正确来源,记忆是否存到预期目录并正确更新已有内容。记录失败样例、耗时和模型用量;表达更顺不代表结果更准确。+### 常见排查思路现象与优先检查项:@@ -634,14 +681,15 @@ openviking/prompts/templates/其中:-- `compression/`:压缩、提取、合并+- `compression/`:working memory 压缩和归档摘要- `indexing/`:相关性评估- `memory/`:记忆类型定义- `parsing/`:结构分析与语义节点生成- `processing/`:经验与策略提炼- `retrieval/`:检索意图分析- `semantic/`:文件和目录摘要-- `skill/`:Skill 摘要+- `skill/`:Skill 摘要与隐私配置提取+- `skill_extract/`:Session Skill schema- `test/`:测试样例生成- `vision/`:图片、页面、表格理解diff --git a/docs/zh/guides/11-grafana-prometheus.md b/docs/zh/guides/11-grafana-prometheus.mdindex 72b8920a7..5d84f7fd8 100644--- a/docs/zh/guides/11-grafana-prometheus.md+++ b/docs/zh/guides/11-grafana-prometheus.md@@ -1,6 +1,6 @@# 使用 Prometheus 和 Grafana 查看 OpenViking 指标-这份文档给出一条从零开始的完整链路:+按四步把指标接到看板:1. 启动 OpenViking 并确认 `/metrics` 可访问2. 启动 Prometheus 抓取 OpenViking 指标@@ -47,7 +47,7 @@ OpenViking 需要先启用 metrics。最小配置参考:}```-配置写入 `~/.openviking/ov.conf` 后,重启 OpenViking Server。+将 metrics 片段合并到现有 `~/.openviking/ov.conf` 后,重启 OpenViking Server。如果你还没有启动服务,可参考:@@ -65,13 +65,15 @@ curl http://localhost:30300/metrics如果返回包含 `openviking_` 前缀的文本,说明 metrics 已经启用。例如:```text-# HELP openviking_http_requests_total Total number of HTTP requests+# HELP openviking_http_requests_total OpenViking metric.# TYPE openviking_http_requests_total counter-openviking_http_requests_total{method="GET",route="/api/v1/system/status",status="200"} 12+openviking_http_requests_total{method="POST",route="/api/v1/search/find",status="200"} 12```如果返回 `Prometheus metrics are disabled.`,说明配置未生效或服务未重启。+本文示例使用 30300 端口,OpenViking 默认端口为 1933。抓取目标应与实际启动端口一致。+## 第 2 步:使用仓库自带 compose 文件部署仓库里已经提供了一套可直接启动的观测示例,文件位于:@@ -99,13 +101,15 @@ openviking_http_requests_total{method="GET",route="/api/v1/system/status",status- 启动 Prometheus,并把宿主机端口映射到 `30909`- 启动 Grafana,并把宿主机端口映射到 `13000`-- 自动把 Grafana 数据源配置为 `http://127.0.0.1:30909`+- 通用方案的数据源是 `http://prometheus:9090`,宿主机网络方案是 `http://127.0.0.1:30909`- 自动加载仓库里的 OpenViking demo dashboard- 自动加载 `OpenViking - Feedback Baseline`,方便直接查看 `openviking_feedback_*` 与 `openviking_feedback_channel_*` 的基线指标+这些是使用 `admin/admin` 凭证的本地演示配置。localhost 方案中的 Prometheus 仍监听 `0.0.0.0`,名称只表示它连接 OpenViking 的方式。仅本地使用时,将看板服务绑定 loopback(Prometheus 使用 `--web.listen-address=127.0.0.1:30909`,Grafana 设置 `GF_SERVER_HTTP_ADDR=127.0.0.1`),或限制网络访问。+### 方案 A:通用方案-直接执行:+在 OpenViking 仓库根目录执行。两套 Compose 使用相同宿主机端口,选择其中一套:```bashdocker compose -f examples/grafana/docker-compose.yml up -d@@ -136,7 +140,7 @@ docker compose -f examples/grafana/docker-compose.localhost.yml up -d- Prometheus 使用宿主机网络,直接抓取 `127.0.0.1:30300/metrics`- Grafana 也使用宿主机网络,并直接连接 `http://127.0.0.1:30909`- 不需要把 OpenViking 改成 `0.0.0.0`-- 不会触发“非 localhost 监听必须配置 `root_api_key`”这条安全限制+- Dev 模式可继续监听 loopback;更改 OpenViking 监听地址前,先查看[认证要求](04-authentication.md)访问地址仍然是:@@ -177,7 +181,7 @@ scrape_configs:如果你的 OpenViking 不是监听在 `30300`,就把这个文件里的目标地址改成你的实际端口,然后重新执行:```bash-docker compose -f examples/grafana/docker-compose.yml up -d+docker compose -f examples/grafana/docker-compose.yml restart prometheus```如果你使用的是 Linux localhost 方案,对应修改的是:@@ -193,14 +197,14 @@ targets: ["127.0.0.1:1933"]然后重新执行:```bash-docker compose -f examples/grafana/docker-compose.localhost.yml up -d+docker compose -f examples/grafana/docker-compose.localhost.yml restart prometheus```## 第 4 步:可选,手动部署时创建 Docker 网络如果你使用的是上面的 compose 文件,这一步不需要手动执行,因为 Compose 会自动创建默认网络。-只有在你坚持使用 `docker run` 分开启动 Prometheus 和 Grafana 时,才需要先创建一个独立网络:+使用 `docker run` 分别启动时,先创建共享网络:```bashdocker network create openviking-observability@@ -218,8 +222,9 @@ docker network create openviking-observabilitydocker run -d \--name prometheus \--network openviking-observability \- -p 30909:9090 \- -v "$PWD/prometheus.yml:/etc/prometheus/prometheus.yml:ro" \+ -p 127.0.0.1:30909:9090 \+ --add-host host.docker.internal:host-gateway \+ -v "$PWD/examples/grafana/prometheus.yml:/etc/prometheus/prometheus.yml:ro" \prom/prometheus```@@ -267,7 +272,7 @@ Bind for 0.0.0.0:9090 failed: port is already allocateddocker run -d \--name grafana \--network openviking-observability \- -p 13000:3000 \+ -p 127.0.0.1:13000:3000 \grafana/grafana```@@ -311,11 +316,9 @@ docker ps## 第 8 步:先在 Grafana Explore 中直接查询-添加完数据源后,先不要急着导入 dashboard,建议先在 `Explore` 中验证基础查询。--推荐先试这些查询:+添加数据源后,在 `Explore` 中验证以下查询:-请求量:+每秒请求数:```promqlrate(openviking_http_requests_total[5m])@@ -345,7 +348,7 @@ openviking_queue_pendingrate(openviking_model_calls_total[5m])```-Token 用量:+每秒 token 数:```promqlrate(openviking_operation_tokens_total[5m])@@ -357,6 +360,8 @@ rate(openviking_operation_tokens_total[5m]){__name__=~"openviking_.*"}```+`rate()` 需要选定时间窗内有多个样本。反馈快照 gauge 即使名称以 `_total` 结尾,也应查询当前值,见 [Vikingbot 指标验证](12-vikingbot-metrics-validation.md)。+## 第 9 步:导入 OpenViking 自带 Dashboard如果你使用的是仓库自带 compose 文件,这两个 dashboard 会在 Grafana 启动后自动加载到 `OpenViking` 文件夹下。@@ -448,7 +453,7 @@ Bind for 0.0.0.0:9090 failed: port is already allocated### 5. Dashboard 导入成功但面板为空-这通常不是 dashboard 文件损坏,而是:+先核对以下原因,再修改 dashboard:- Prometheus 里还没有对应指标样本- 过滤条件和当前环境不匹配diff --git a/docs/zh/guides/16-cuvs.md b/docs/zh/guides/16-cuvs.mdindex b8a12b54f..97a37d8ad 100644--- a/docs/zh/guides/16-cuvs.md+++ b/docs/zh/guides/16-cuvs.md@@ -10,6 +10,8 @@ OpenViking 的 `cuvs` 后端保留本地后端的记录持久化、标量索引按所选版本核对 [cuVS 安装要求](https://docs.nvidia.com/cuvs/installation) 和 [Python 包安装指南](https://docs.nvidia.com/cuvs/installation/python)。当前 cuVS 源码构建要求 CUDA Toolkit 12.2+ 和 Ampere 或更新架构的 GPU;安装包要求取决于所选版本。+先进入 OpenViking 源码根目录并激活 Python 虚拟环境,再按宿主机 CUDA 大版本选择下面一组命令。+CUDA 12:```bash@@ -123,10 +125,10 @@ dense query 仍固定使用 cuVS。`auto_background_rebuild` 默认关闭。开启后,连续 mutation 会按`auto_rebuild_debounce_ms` 合并,worker 在不持有跨后端 mutation 锁的情况下构建新的 immutable GPU snapshot。默认 500 ms 用于避免普通 ingest 的中间 batch-反复触发构建。对于边界明确、由多次调用组成的 bulk load,可把所有写入放在+反复触发构建。使用内部 vector backend 的代码,可以把边界明确的批量写入放在`async with backend.bulk_ingest(ctx=ctx):` scope 内:native 可见性和持久化仍按每次调用推进,但 derived GPU maintenance 会延迟到最外层 scope 退出后只调度一次。-该 scope 只是 maintenance hint,不提供事务或原子性;退出 scope 只负责调度 rebuild,+这是内部 API,HTTP SDK 不提供该 scope。它只是 maintenance hint,不提供事务或原子性;退出 scope 只负责调度 rebuild,本身不等待 GPU ready。vector backend benchmark 会额外在正式计时 search 前显式等待最终 snapshot;无法识别 bulk 边界的调用方仍可按实际 batch 间隔调整 debounce。Auto仍为显式启用;未开启 Auto/background rebuild 时,该 scope 对派生维护为 no-op,不改变@@ -142,8 +144,7 @@ dense query 仍固定使用 cuVS。保存 graph,构建期间可能需要 `N * intermediate_graph_degree * 4` bytes 的intermediate graph。每个缓存 filter bitset 约占 `ceil(N / 32) * 4` bytes。-之前的 index-only 测试使用 `cudaMemGetInfo` 记录 build 前后的显存增量;下表每项-均为 5 个干净进程的中位数:+[历史索引测试](https://github.com/volcengine/OpenViking/blob/main/benchmark/cuvs/PRELIMINARY_RESULTS.md) 使用 NVIDIA H20、cuVS 26.06、CuPy 14.1.1 和 CUDA runtime 12.9,测试时尚未加入请求微批处理。下表通过 `cudaMemGetInfo` 记录构建前后的显存增量,每项取 5 个干净进程的中位数。部署容量需要使用[测试工具](https://github.com/volcengine/OpenViking/blob/main/benchmark/cuvs/README.md) 按自己的配置重新测量:| 数据集 | cuVS 算法 | 实测 GPU 增量 || --- | --- | ---: |@@ -178,8 +179,9 @@ record shadow 保存预处理后的 Python 浮点值;仅在创建 device datasBenchmark 必须同时报告两边的数据类型和 Recall@K,不能将结果描述为equal-dtype 或 equal-memory。这是首版 opt-in 集成的有意边界,现有 CPU 行为保持不变。auto 模式会根据 filter-候选阈值在两种表示之间选择;要求固定数值表示的应用应使用显式 backend,或将-native 路由阈值设为 0。+候选阈值在两种表示之间选择。需要为 dense query 固定数值表示时,应显式选择+backend 和 dtype。将阈值设为 0 只会关闭候选数路由;auto 模式仍可能因显存不足、+GPU 不可用或快照待重建而回退。GPU 低精度存储是显式能力,不做隐式 cast。设置 `dtype: "float16"` 会把 cuVSdataset 和每个 query 同时 cast 为 float16,brute-force 与 CAGRA 都不使用混合diff --git a/docs/zh/guides/17-vikingbot.md b/docs/zh/guides/17-vikingbot.mdindex 06892b946..7c9d216e9 100644--- a/docs/zh/guides/17-vikingbot.md+++ b/docs/zh/guides/17-vikingbot.md@@ -19,7 +19,7 @@ uv tool install "openviking[bot]" --upgrade``````bash [pip]-pip install "openviking[bot]" --upgrade --force-reinstall+pip install "openviking[bot]" --upgrade``````bash [pipx]@@ -38,6 +38,8 @@ pipx upgrade openvikingvikingbot --version```+使用 pip 时先激活虚拟环境。源码安装还需要准备[开发构建依赖](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING.md)。+### 从源码安装```bash@@ -94,6 +96,8 @@ openviking-server doctor详细配置见 [OpenViking 配置指南](01-configuration.md)。VikingBot 默认继承根级 `vlm` 作为 Agent 模型,因此通常不需要重复配置 `bot.agents`。+Server 使用 `api_key` 模式时,先注册 User/Admin Key 并写入 `bot.ov_server.api_key`;不能把 root 管理 Key 当作用户 Key 使用。操作见[认证指南](04-authentication.md)。继承 `trusted` 模式时,Bot 使用服务端的可信身份配置。+### 2. 一体启动```bash@@ -113,6 +117,8 @@ ov find "我的回答偏好"`ov config` 中的 URL 应指向当前 OpenViking Server,默认是 `http://127.0.0.1:1933`。如果 Server 开启了鉴权,还需要配置当前调用者的 User/Admin API Key。+记忆在 commit 后异步提取,立即运行 `ov find` 可能还没有结果。用检索验证记忆是否保存前,先确认记忆任务已完成。+## 场景 B:本地调试 Agent适合快速试用 VikingBot,或开发 Agent、Tool 和 Skill。`vikingbot chat` 会在当前进程中直接运行 Agent,不需要先启动 Gateway。@@ -185,7 +191,9 @@ vikingbot chatvikingbot chat --session my-session```-没有可用的 OpenViking Server 时,VikingBot 会以 standalone 方式运行。本地文件、Shell、Web 和 Skill 等能力仍可使用,但不会提供 OpenViking 资源检索和长期记忆能力。+本地 chat 未显式配置 `bot.ov_server.server_url` 时,连接继承的服务失败可降级为 standalone。显式配置的服务不可用时停止启动。继承的认证模式不匹配也会停止启动;显式配置远端服务时,Bot 会采用服务端报告的模式,再验证凭据。认证失败或收到不健康的 HTTP 响应都会停止启动。一体启动由服务端管理时,Bot 会保留继承的上游配置并等待服务启动。++standalone 模式下,本地文件、Shell、Web 和 Skill 等能力仍可使用,但不会提供 OpenViking 资源检索和长期记忆能力。## 场景 C:Gateway 统一入口@@ -209,6 +217,7 @@ vikingbot chat --session my-session},"ov_server": {"server_url": "https://openviking.example.com",+ "api_key_type": "user","api_key": "<bot-openviking-user-api-key>"}}diff --git a/docs/zh/guides/18-openviking-assets.md b/docs/zh/guides/18-openviking-assets.mdindex 6c92ddfc0..353bb09cb 100644--- a/docs/zh/guides/18-openviking-assets.md+++ b/docs/zh/guides/18-openviking-assets.md@@ -111,7 +111,9 @@ Git 资产支持:| `connector` | 是 | v1 只支持 `git`。 || `description` | 否 | 资产用途说明。 || `params.repo_url` | 是 | Git clone URL。 |-| `params.branch` | 否 | 要接入的分支;设置时不能为空。 |+| `params.branch` | 否 | 要接入的分支;设置时不能为空,与 `params.commit` 互斥。 |+| `params.commit` | 否 | 固定版本的完整 40 位十六进制 SHA,与 `params.branch` 互斥。 |+| `to` | 否 | 精确资源目标 URI。同一资产已有 State 映射时必须与其一致;本次选中的资产不能共用目标。 || `auth_ref` | 否 | 覆盖 `defaults.git.auth_ref`。 || `watch_interval` | 否 | 覆盖 `defaults.git.watch_interval`。 |@@ -158,7 +160,7 @@ assets:- requests```-全团队维护一份 Catalog;在 Catalog 中修改资产,所有选择它的 Manifest 都会生效。因为两种+全团队维护一份 Catalog。修改资产后,选择它的 Manifest 下次执行时会读取新定义;只编辑文件不会更新已导入的资源。因为两种文档同构,Catalog 也可以直接执行:`ov add-resource -m catalog.yaml` 会导入它定义的全部资产。CLI 按以下规则查找 Catalog 文件:@@ -179,8 +181,7 @@ connector + normalized locator + refGit URL 会去除协议、用户名前缀、端口、结尾的 `.git` 和 `/`,并把主机名统一为小写。因此,同一仓库的 HTTPS、SSH 和 SCP 风格地址通常会得到相同定位符;不同分支会得到不同资产。-资产名称不参与身份计算。重命名资产但保持来源和分支不变时,会继续关联原资源;修改来源或-分支时会产生新资产,旧资源被报告为 orphan。+资产名称不参与身份计算。重命名资产但保持来源和 ref 不变时,会继续关联原资源。修改来源、分支或固定 commit 会产生新的资产身份。没有指定 `to` 时,旧条目成为 orphan;指定 `to` 时,CLI 可以接管该目标下唯一的已有 State 条目,以新身份同步原资源。出于安全原因,clone URL 不能:@@ -232,6 +233,8 @@ ov add-resource --manifest manifest.yaml --args dry_run:true任何仓库不可读时,dry-run 立即以 `PERMISSION_DENIED` 退出,不再输出可执行计划。+使用 `params.commit` 固定版本时,预检通过 HEAD 检查仓库访问权限,实际导入的 fetch/checkout 才会验证该 SHA。dry-run 成功不代表指定 commit 一定可用。+### 应用 Manifest确认计划后去掉 `dry_run`:@@ -243,6 +246,8 @@ ov add-resource --manifest manifest.yaml仓库中包含一个完整示例(一份共享 Catalog 加一份按名选择的 Manifest),位于[`examples/openviking-assets`](https://github.com/volcengine/OpenViking/tree/main/examples/openviking-assets)。+未使用 `--wait` 时,提交成功不等于解析、语义处理和索引都已完成。验证检索前,使用 `--wait` 或检查返回的任务。分支内容会变化;需要固定源版本时,设置 `params.commit` 并使用 `watch_interval: 0`。+## 凭据Manifest 和 Catalog 只保存 `auth_ref` 别名,不应保存 token、密码或私钥。CLI 默认从以下@@ -316,7 +321,9 @@ State 使用 `openviking-assets-state/1` 协议,记录:| State 中没有该 `asset_id` 的资源 URI | create:创建新资源。 || State 中已有资源 URI | sync:把 URI 作为 `to` 再次调用 `add_resource`。 || 资产不再被 Manifest 选择 | 报告 orphan,保留资源和 State,不自动删除。 |-| `asset_id` 因来源或分支变化 | 创建新资产,旧资产成为 orphan。 |+| 来源或 ref 变化,且未显式指定 `to` | 创建新资产,旧资产成为 orphan。 |+| 新身份的 `to` 匹配唯一已有 State 条目 | 接管该目标,以新身份同步。 |+| 同一身份的 `to` 与 State 不同 | 提交前失败,需先处理资源和 State 映射。 |State 属于执行环境,不是 Catalog 或 Manifest 协议的一部分。共享 Manifest 仓库通常应在`.gitignore` 中加入:@@ -338,7 +345,7 @@ State 属于执行环境,不是 Catalog 或 Manifest 协议的一部分。共3. `defaults.git.watch_interval`;4. `0`,不自动刷新。-例如,临时把 Manifest 中全部资产调整为每 60 分钟刷新:+例如,把本次选中的资产调整为每 60 分钟刷新;创建的 Watch 会持续在服务端运行:```bashov add-resource --manifest manifest.yaml --watch-interval 60