Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: clarify config reload and hybrid search boundaries (#3206)

huangruiteng3b516d64142f
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index f3a0c8129..971b4b4d3 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -522,6 +522,21 @@ Supported task types: `RETRIEVAL_QUERY`, `RETRIEVAL_DOCUMENT`, `SEMANTIC_SIMILAR
}
```
+Sparse output is a provider capability, not an endpoint inferred from
+`storage.vectordb.sparse_weight`. OpenViking currently implements `sparse` and
+`hybrid` embedding providers for `volcengine` and `vikingdb`. The
+OpenAI-compatible, Ollama, and built-in `local` providers are dense-only; a
+self-hosted `/v1/embeddings` endpoint is therefore not treated as a sparse
+endpoint, and OpenViking does not probe a separate
+`/v1/embeddings/sparse` route.
+
+There is no automatic BM25 or other sparse-vector fallback when the configured
+embedder returns only dense vectors. To use hybrid retrieval, configure a
+supported sparse/hybrid provider and set `storage.vectordb.sparse_weight > 0`.
+Model memory requirements are provider/model-specific and are not controlled by
+OpenViking; size self-hosted models against their provider documentation before
+enabling them in production.
+
#### Hybrid Embedding
Two approaches are supported:
@@ -1299,6 +1314,26 @@ OpenViking uses two config files:
When config files are at the default path, OpenViking loads them automatically — no additional setup needed.
+> **Root-key two-file rule:** `server.root_api_key` in `ov.conf` is the
+> credential accepted by the server. `root_api_key` in `ovcli.conf` is the
+> client-side copy used by `ov --sudo`. If that CLI manages this server, keep
+> the two values identical and rotate both files together. The normal
+> tenant-scoped `api_key` remains a separate user/admin credential.
+
+### Reload boundary
+
+The server reads `ov.conf` during process startup and does not watch the file
+for changes. Editing `embedding`, `vlm`, `rerank`, `retrieval`, `storage`, or
+`server` settings requires restarting the OpenViking server. Queue work that is
+already running is not migrated to the new configuration, so use the normal
+service-manager restart procedure and verify with `openviking-server doctor`
+after the process comes back.
+
+`ovcli.conf` is client-side configuration. A new `ov` command or newly created
+HTTP client reads the current file; an already-running client or plugin may keep
+the values it loaded at construction time and should be restarted when its
+connection or credential settings change.
+
If config files are at a different location, there are two ways to specify:
```bash
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index c02f6784a..77a7c4523 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -492,6 +492,19 @@ openviking-server doctor
}
```
+Sparse 输出是 embedding provider 的能力,不会因为设置
+`storage.vectordb.sparse_weight` 就自动出现。OpenViking 当前只为
+`volcengine` 和 `vikingdb` 实现了 `sparse` / `hybrid` embedding provider;
+OpenAI 兼容接口、Ollama 和内置 `local` provider 目前都只支持 dense。
+因此,自托管的 `/v1/embeddings` 不会被自动当成 sparse 接口,OpenViking
+也不会额外探测 `/v1/embeddings/sparse` 路由。
+
+当 provider 只返回 dense vector 时,OpenViking 不会自动补充 BM25 或其他
+sparse-vector 兜底。若要启用混合检索,需要配置受支持的 sparse/hybrid
+provider,并设置 `storage.vectordb.sparse_weight > 0`。自托管模型的内存需求
+取决于具体 provider 和模型,不由 OpenViking 控制;生产启用前请按模型文档
+评估资源占用。
+
#### Hybrid Embedding
支持两种方式:
@@ -1272,6 +1285,22 @@ OpenViking 使用两个配置文件:
配置文件放在默认路径时,OpenViking 自动加载,无需额外设置。
+> **Root key 双文件规则:** `ov.conf` 中的 `server.root_api_key` 是服务端
+> 接受的凭据;`ovcli.conf` 中的 `root_api_key` 是 `ov --sudo` 使用的客户端
+> 副本。如果该 CLI 用于管理这个服务端,两处值必须一致,并在轮换时同时更新。
+> 普通租户数据使用的 `api_key` 仍是另一把 user/admin 凭据。
+
+### 配置重载边界
+
+服务端只在进程启动时读取 `ov.conf`,不会监听文件变化。修改 `embedding`、
+`vlm`、`rerank`、`retrieval`、`storage` 或 `server` 配置后,需要重启
+OpenViking 服务。已经运行中的队列任务不会自动迁移到新配置;请使用部署环境
+原有的服务管理方式重启,并在服务恢复后运行 `openviking-server doctor` 验证。
+
+`ovcli.conf` 属于客户端配置。新的 `ov` 命令或新建的 HTTP client 会读取当前
+文件;已经运行中的 client 或插件可能继续使用构造时加载的连接与凭据,修改后
+应重启对应客户端或插件。
+
如果配置文件在其他位置,有两种指定方式:
```bash