# 配置

OpenViking 使用 JSON 配置文件（`ov.conf`）进行设置。配置文件支持 Embedding、VLM、Rerank、存储、解析器等多个模块的配置。

首次配置推荐优先使用：

```bash
openviking-server init
openviking-server doctor
```

`openviking-server init` 会分别引导你填写 Embedding 和 VLM 的配置。对于 `OpenAI`、`Volcengine`、`Kimi`、`GLM` 这类 API 型 VLM，按提示填写对应的 VLM API Key；如果要使用 Codex 作为 VLM，请选择 `OpenAI Codex`，向导会自动帮你处理已有 Codex 鉴权的导入，或直接引导你完成登录。

## 快速开始

在用户配置目录 `~/.openviking/` 下创建 `ov.conf`：

```json
{
  "storage": {
    "workspace": "./data",
    "vectordb": {
      "name": "context",
      "backend": "local"
    },
    "agfs": {
      "backend": "local"
    }
  },
  "embedding": {
    "dense": {
      "api_base" : "<api-endpoint>",
      "api_key"  : "<your-api-key>",
      "provider" : "<provider-type>",
      "dimension": 1024,
      "model"    : "<model-name>"
    }
  },
  "vlm": {
    "api_base" : "<api-endpoint>",
    "api_key"  : "<your-api-key>",
    "provider" : "<provider-type>",
    "model"    : "<model-name>"
  }
}

```

如果 `provider` 是 `openai-codex`，并且 Codex OAuth 已经就绪，则 `vlm.api_key` 可以省略。

## 配置示例

<details>
<summary><b>火山引擎（豆包模型）</b></summary>

```json
{
  "embedding": {
    "dense": {
      "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
      "api_key"  : "your-volcengine-api-key",
      "provider" : "volcengine",
      "dimension": 1024,
      "model"    : "doubao-embedding-vision-251215",
      "input": "multimodal"
    }
  },
  "vlm": {
    "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
    "api_key"  : "your-volcengine-api-key",
    "provider" : "volcengine",
    "model"    : "doubao-seed-2-0-lite-260428"
  }
}
```

</details>

<details>
<summary><b>OpenAI 模型</b></summary>

```json
{
  "embedding": {
    "dense": {
      "api_base" : "https://api.openai.com/v1",
      "api_key"  : "your-openai-api-key",
      "provider" : "openai",
      "dimension": 1536,
      "model"    : "text-embedding-3-small"
    }
  },
  "vlm": {
    "api_base" : "https://api.openai.com/v1",
    "api_key"  : "your-openai-api-key",
    "provider" : "openai",
    "model"    : "gpt-5.4"
  }
}
```

</details>

<details>
<summary><b>火山引擎 Embedding + Codex VLM</b></summary>

使用 `openviking-server init` 完成 Codex 登录/导入后，再执行 `openviking-server doctor`。

```json
{
  "embedding": {
    "dense": {
      "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
      "api_key"  : "your-volcengine-api-key",
      "provider" : "volcengine",
      "dimension": 1024,
      "model"    : "doubao-embedding-vision-251215"
    }
  },
  "vlm": {
    "provider" : "openai-codex",
    "model"    : "gpt-5.4",
    "api_base" : "https://chatgpt.com/backend-api/codex"
  }
}
```

</details>

<details>
<summary><b>火山引擎 Embedding + Kimi Coding VLM</b></summary>

```json
{
  "embedding": {
    "dense": {
      "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
      "api_key"  : "your-volcengine-api-key",
      "provider" : "volcengine",
      "dimension": 1024,
      "model"    : "doubao-embedding-vision-251215"
    }
  },
  "vlm": {
    "provider" : "kimi",
    "model"    : "kimi-code",
    "api_key"  : "your-kimi-subscription-api-key",
    "api_base" : "https://api.kimi.com/coding"
  }
}
```

`kimi` 会自动应用 Kimi Coding 的默认配置，包括默认的 Kimi Coding User-Agent。

</details>

<details>
<summary><b>火山引擎 Embedding + GLM Coding Plan VLM</b></summary>

```json
{
  "embedding": {
    "dense": {
      "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
      "api_key"  : "your-volcengine-api-key",
      "provider" : "volcengine",
      "dimension": 1024,
      "model"    : "doubao-embedding-vision-251215"
    }
  },
  "vlm": {
    "provider" : "glm",
    "model"    : "glm-4.6v",
    "api_key"  : "your-zai-api-key",
    "api_base" : "https://api.z.ai/api/coding/paas/v4"
  }
}
```

如果 OpenViking 需要处理图片，请使用 `glm-4.6v` 或 `glm-5v-turbo` 这类支持视觉输入的模型。

</details>

## 配置部分

### embedding

用于向量搜索的 Embedding 模型配置，支持 dense、sparse 和 hybrid 三种模式。

#### Dense Embedding

```json
{
  "embedding": {
    "max_concurrent": 10,
    "max_retries": 3,
    "text_source": "content_only",
    "max_input_tokens": 4096,
    "dense": {
      "provider": "volcengine",
      "api_key": "your-api-key",
      "model": "doubao-embedding-vision-251215",
      "dimension": 1024,
      "input": "multimodal",
      "batch_size": 32
    }
  }
}
```

**参数**

| 参数 | 类型 | 说明 |
|------|------|------|
| `max_concurrent` | int | 最大并发 Embedding 请求数（`embedding.max_concurrent`，默认：`10`） |
| `max_retries` | int | Embedding provider 瞬时错误的最大重试次数（`embedding.max_retries`，默认：`3`；`0` 表示禁用重试） |
| `text_source` | str | 文本文件向量化时使用的文本来源。`content_only` 读取原文内容；`summary_first` 优先使用摘要，没有摘要时回退到原文；`summary_only` 只使用摘要。默认：`content_only` |
| `max_input_tokens` | int | 使用原文内容向量化时，发送给 embedding 模型的最大估算 token 数。默认：`4096` |
| `provider` | str | `"openai"`、`"azure"`、`"volcengine"`、`"vikingdb"`、`"jina"`、`"ollama"`、`"gemini"`、`"voyage"`、`"dashscope"`、`"minimax"`、`"cohere"`、`"litellm"` 或 `"local"` |
| `api_key` | str | API Key |
| `model` | str | 模型名称 |
| `dimension` | int | 向量维度 |
| `input` | str | 输入类型：`"text"` 或 `"multimodal"` |
| `batch_size` | int | 批量请求大小 |
| `encoding_format` | str | （仅 OpenAI / Azure）Embedding 值的传输格式：`"float"` 或 `"base64"`。留空时使用 OpenAI Python SDK 默认值；当上游网关无法正确处理 base64 embedding payload 时，可设置为 `"float"`。 |
| `extra_body` | object | （仅 OpenAI / Azure）合并进每次 embedding 请求体的额外 JSON 字段。适用于接受厂商专有字段的 OpenAI 兼容网关，例如 OpenRouter 的 provider 路由 `{"provider": {"sort": "latency"}}`。发生冲突时，显式设置的 `query_param`/`document_param` 键优先。 |

`embedding.max_retries` 仅对瞬时错误生效，例如 `429`、`5xx`、超时和连接错误；`400`、`401`、`403`、`AccountOverdue` 这类永久错误不会自动重试。退避策略为指数退避，初始延迟 `0.5s`，上限 `8s`，并带随机抖动。

#### Embedding 熔断（Circuit Breaker）

当 embedding provider 出现连续瞬时错误（如 `429`、`5xx`）时，OpenViking 会触发熔断，在一段时间内暂停调用 provider，并将 embedding 任务重新入队。超过基础 `reset_timeout` 后进入 HALF_OPEN，允许一次探测请求；如果探测失败，则下一次 `reset_timeout` 翻倍（上限为 `max_reset_timeout`）。

```json
{
  "embedding": {
    "circuit_breaker": {
      "failure_threshold": 5,
      "reset_timeout": 60,
      "max_reset_timeout": 600
    }
  }
}
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `circuit_breaker.failure_threshold` | int | 连续失败多少次后熔断（默认：`5`） |
| `circuit_breaker.reset_timeout` | float | 基础恢复等待时间（秒，默认：`60`） |
| `circuit_breaker.max_reset_timeout` | float | 指数退避后的最大恢复等待时间（秒，默认：`600`） |

**可用模型**

| 模型 | 维度 | 输入类型 | 说明 |
|------|------|----------|------|
| `doubao-embedding-vision-251215` | 1024 | multimodal | 推荐 |
| `doubao-embedding-250615` | 1024 | text | 仅文本 |

使用 `input: "multimodal"` 时，OpenViking 可以嵌入文本、图片（PNG、JPG 等）和混合内容。以图搜图需要该模式；纯文本 embedding 模型仍会索引图片 summary，但不能接收图片查询。

**支持的 provider:**
- `openai`: OpenAI Embedding API
- `azure`: Azure OpenAI Embedding API
- `volcengine`: 火山引擎 Embedding API
- `vikingdb`: VikingDB Embedding API
- `jina`: Jina AI Embedding API
- `ollama`: Ollama 本地 OpenAI 兼容 Embedding API
- `voyage`: Voyage AI Embedding API
- `minimax`: MiniMax Embedding API
- `cohere`: Cohere Embedding API
- `gemini`: Google Gemini Embedding API（仅文本；需安装 `google-genai>=1.0.0`）
- `dashscope`: DashScope（阿里通义）Embedding API
- `litellm`: LiteLLM Embedding API
- `local`: 本地 GGUF embedding 模型

**OpenAI 兼容 provider 的 JSON float embedding 示例:**

```json
{
  "embedding": {
    "dense": {
      "provider": "openai",
      "api_key": "your-api-key",
      "api_base": "https://your-openai-compatible-endpoint/v1",
      "model": "text-embedding-3-large",
      "dimension": 3072,
      "encoding_format": "float"
    }
  }
}
```

`encoding_format` 是可选字段，只会传给 `provider: "openai"` 和 `provider: "azure"`。留空时使用 OpenAI Python SDK 默认行为；如果 OpenAI 兼容上游网关无法正确反序列化 base64 embedding payload，可设置为 `"float"`。

**OpenRouter provider 路由示例:**

```json
{
  "embedding": {
    "dense": {
      "provider": "openai",
      "api_key": "your-openrouter-api-key",
      "api_base": "https://openrouter.ai/api/v1",
      "model": "qwen/qwen3-embedding-8b",
      "dimension": 4096,
      "extra_body": {
        "provider": {
          "sort": "latency"
        }
      }
    }
  }
}
```

`extra_body` 会合并进每次 embedding 请求，因此无需改动代码即可调优接受厂商专有字段的 OpenAI 兼容网关（例如 OpenRouter 的 provider 路由偏好）。该字段只会传给 `provider: "openai"` 和 `provider: "azure"`。

**Azure OpenAI provider 的 JSON float embedding 示例:**

```json
{
  "embedding": {
    "dense": {
      "provider": "azure",
      "api_key": "your-azure-api-key",
      "api_base": "https://your-resource-name.openai.azure.com",
      "api_version": "2025-01-01-preview",
      "model": "your-embedding-deployment-name",
      "dimension": 3072,
      "encoding_format": "float"
    }
  }
}
```

对于 Azure OpenAI，`model` 必须填写 Azure 中配置的 embedding deployment name。

**minimax provider 配置示例:**

```json
{
  "embedding": {
    "dense": {
      "provider": "minimax",
      "api_key": "your-minimax-api-key",
      "model": "embo-01",
      "dimension": 1536,
      "query_param": "query",
      "document_param": "db",
      "extra_headers": {
        "GroupId": "your-group-id"
      }
    }
  }
}
```

**vikingdb provider 配置示例:**

```json
{
  "embedding": {
    "dense": {
      "provider": "vikingdb",
      "model": "bge_large_zh",
      "ak": "your-access-key",
      "sk": "your-secret-key",
      "region": "cn-beijing",
      "dimension": 1024
    }
  }
}
```

**jina provider 配置示例:**

```json
{
  "embedding": {
    "dense": {
      "provider": "jina",
      "api_key": "jina_xxx",
      "model": "jina-embeddings-v5-text-small",
      "dimension": 1024
    }
  }
}
```

可用 Jina 模型:
- `jina-embeddings-v5-text-small`: 677M 参数, 1024 维, 最大序列长度 32768 (默认)
- `jina-embeddings-v5-text-nano`: 239M 参数, 768 维, 最大序列长度 8192

**本地部署 (GGUF/MLX):** Jina 嵌入模型是开源的, 在 [Hugging Face](https://huggingface.co/jinaai) 上提供 GGUF 和 MLX 格式。可以使用任何 OpenAI 兼容的推理服务器 (如 llama.cpp、MLX、vLLM) 本地运行, 并将 `api_base` 指向本地端点:

```json
{
  "embedding": {
    "dense": {
      "provider": "jina",
      "api_key": "local",
      "api_base": "http://localhost:8080/v1",
      "model": "jina-embeddings-v5-text-nano",
      "dimension": 768
    }
  }
}
```

获取 API Key: https://jina.ai

**gemini provider 配置示例:**

> **注意：** 需安装 `pip install "google-genai>=1.0.0"`。异步批量嵌入：`pip install "openviking[gemini-async]"`。

```json
{
  "embedding": {
    "dense": {
      "provider": "gemini",
      "api_key": "your-google-api-key",
      "model": "gemini-embedding-2-preview",
      "dimension": 3072
    }
  }
}
```

可用 Gemini 嵌入模型:
- `gemini-embedding-2-preview`: 8192 token 输入限制, 1–3072 输出维度 (MRL)
- `gemini-embedding-001`: 2048 token 输入限制, 1–3072 输出维度 (MRL)
- `text-embedding-004`: 2048 token 输入限制, 768 输出维度（固定）

推荐维度: `768`、`1536` 或 `3072`（默认: `3072`）。

获取 API Key: https://aistudio.google.com/apikey

**DashScope（阿里通义）provider 配置示例:**

```json
{
  "embedding": {
    "dense": {
      "provider": "dashscope",
      "api_key": "${DASHSCOPE_API_KEY}",
      "model": "text-embedding-v4",
      "dimension": 1024
    }
  }
}
```

**可用 DashScope 模型:**

| 模型 | 维度 | 输入类型 | 说明 |
|------|------|----------|------|
| `text-embedding-v3` | 1024 | text | 针对中文优化 |
| `text-embedding-v4` | 1024 | text | 针对中文优化 |
| `tongyi-embedding-vision-plus` | 1152 | multimodal | 支持通过 `enable_fusion` 启用融合向量 |
| `tongyi-embedding-vision-flash` | 768 | multimodal | 更快，成本更低 |
| `qwen3-vl-embedding` | 2560 | multimodal | 文本 + 图像 + 视频 |
| `qwen2.5-vl-embedding` | 1024 | multimodal | 文本 + 图像 + 视频 |

**多模态参数**（仅文本+图像/视频模型支持）:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `input_type` | str | `"multimodal"` 或 `"text"` | 嵌入模式（默认: `"multimodal"`） |
| `enable_fusion` | bool | `false` | 为 `tongyi-embedding-vision-*` 模型启用融合向量 |
| `res_level` | int | `2` | 图像分辨率级别（1=高，2=中，3=低） |
| `max_video_frames` | int | `16` | 视频最大嵌入帧数 |

**端点选择** — DashScope 为中国区（`cn`）和国际区（`intl`）提供 `api_base` 默认值:

| 区域 | `api_base` | 说明 |
|------|-----------|------|
| 中国 | `https://dashscope.aliyuncs.com`（默认） | 推荐中国大陆用户使用 |
| 国际 | `https://dashscope-intl.aliyuncs.com` | 推荐中国境外用户使用 |

也支持设置完整 URL 来自定义端点地址。

获取 API Key: https://dashscope.console.aliyun.com/api-key

**非对称检索**（索引和查询使用不同的 task type）:

```json
{
  "embedding": {
    "dense": {
      "provider": "gemini",
      "api_key": "your-google-api-key",
      "model": "gemini-embedding-2-preview",
      "dimension": 3072,
      "query_param": "RETRIEVAL_QUERY",
      "document_param": "RETRIEVAL_DOCUMENT"
    }
  }
}
```

支持的 task type: `RETRIEVAL_QUERY`、`RETRIEVAL_DOCUMENT`、`SEMANTIC_SIMILARITY`、`CLASSIFICATION`、`CLUSTERING`、`CODE_RETRIEVAL_QUERY`、`QUESTION_ANSWERING`、`FACT_VERIFICATION`。

#### Sparse Embedding

> **注意：** 火山引擎的 Sparse embedding 从 `doubao-embedding-vision-251215` 模型版本起支持。

```json
{
  "embedding": {
    "sparse": {
      "provider": "volcengine",
      "api_key": "your-api-key",
      "model": "doubao-embedding-vision-251215"
    }
  }
}
```

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

支持两种方式：

**方式一：使用单一混合模型**

```json
{
  "embedding": {
    "hybrid": {
      "provider": "volcengine",
      "api_key": "your-api-key",
      "model": "doubao-embedding-hybrid",
      "dimension": 1024
    }
  }
}
```

**方式二：组合 dense + sparse**

```json
{
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "api_key": "your-api-key",
      "model": "doubao-embedding-vision-251215",
      "dimension": 1024
    },
    "sparse": {
      "provider": "volcengine",
      "api_key": "your-api-key",
      "model": "doubao-embedding-vision-251215"
    }
  }
}
```

### vlm

用于语义提取（L0/L1 生成）的视觉语言模型。

```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",
    "max_retries": 3,
    "media": {
      "enabled": true,
      "max_concurrent": 2,
      "file_processing_timeout": 1800,
      "file_poll_interval": 3,
      "video_fps": 1.0
    }
  }
}
```

**参数**

| 参数 | 类型 | 说明 |
|------|------|------|
| `api_key` | str | API Key。`openai-codex` 在 Codex OAuth 可用时可省略；使用 provider 原生凭据的 `litellm` 路由也可省略 |
| `forward_api_key` | bool | 仅 LiteLLM 使用。覆盖是否把 `api_key` 透传给 LiteLLM。默认情况下，OpenViking 不会把占位 key 透传给 `bedrock/`、`sagemaker/`、`vertex_ai/` 等 AWS/GCP 原生鉴权路由；如果明确使用 LiteLLM 的 Bedrock bearer-token API-key 鉴权，可设为 `true` |
| `model` | str | 模型名称 |
| `api_base` | str | API 端点（可选） |
| `thinking` | bool | 启用思考模式（仅对部分火山模型生效，默认：`false`） |
| `max_concurrent` | int | 语义处理阶段 LLM 最大并发调用数（默认：`64`） |
| `max_retries` | int | VLM provider 瞬时错误的最大重试次数（默认：`3`；`0` 表示禁用重试） |
| `credentials` | array | 有序 VLM 凭据/模型列表，索引 0 优先级最高。每项可单独覆盖 `provider`、`model`、`api_key`、`api_base`、`api_version`、`extra_headers`、`extra_request_body` 和 `stream` |
| `failback_timeout_seconds` | float | 切换到低优先级 credential 后，尝试逐级切回的时间阈值（默认：`600`） |
| `failback_request_count` | int | 低优先级 credential 成功处理多少次请求后尝试逐级切回（默认：`50`） |
| `backup` | object | 可选的备用 VLM 配置（结构与 `vlm` 相同），当主 VLM 遇到限流、`5xx`、超时或连接失败等可重试错误时自动切换。仅支持 1 层备用 &mdash; 备用 VLM 本身不能再嵌套 `backup` |
| `timeout` | float | 单次 VLM API 请求的 HTTP 超时时间（秒），传递给底层 OpenAI/LiteLLM 客户端。慢端点（如 DashScope、本地推理）可调大。必须 `> 0`（默认：`600.0`） |
| `extra_headers` | object | 兼容 HTTP provider 的自定义请求头。`kimi` 默认已注入所需订阅请求头，也支持在这里覆盖或扩展 |
| `extra_request_body` | object | 传给 OpenAI 兼容 completion 请求的额外 JSON body 字段，可用于 Ollama `{"think": false}` 等 provider 专有参数 |
| `stream` | bool | 启用流式模式（OpenAI 兼容 provider 可用，默认：`false`） |
| `media` | object | 音视频运行参数；音视频理解复用该 VLM 的 provider、模型、凭据、client、超时、重试、请求头、输出 token 限制、故障切换和 token 统计 |
| `media.enabled` | bool | 启用音视频理解（默认：`false`） |
| `media.max_concurrent` | int | 音视频调用最大并发数（默认：`2`） |
| `media.file_processing_timeout` | float | Provider 侧媒体预处理最长等待秒数（默认：`1800`） |
| `media.file_poll_interval` | float | Provider 侧媒体预处理轮询间隔秒数（默认：`3`） |
| `media.video_fps` | float | Provider 支持时使用的视频采样帧率，范围 `0.2` 到 `5.0`（默认：`1.0`） |

`vlm.max_retries` 仅对瞬时错误生效，例如 `429`、`5xx`、超时和连接错误；认证、鉴权、欠费等永久错误不会自动重试。退避策略为指数退避，初始延迟 `0.5s`，上限 `8s`，并带随机抖动。

**可用模型**

| 模型 | 说明 |
|------|------|
| `doubao-seed-2-0-lite-260428` | 推荐用于语义提取 |
| `doubao-pro-32k` | 用于更长上下文 |

添加资源时，VLM 生成：

1. **L0（摘要）**：~100 token 摘要
2. **L1（概览）**：~2k token 概览，包含导航信息

如果未配置 VLM，L0/L1 将直接从内容生成（语义性较弱），多模态资源的描述可能有限。

**支持的 provider：**
- `volcengine`：火山引擎 VLM API
- `openai`：OpenAI 兼容 VLM API
- `openai-codex`：通过 ChatGPT/Codex OAuth 使用 Codex VLM
- `kimi`：Kimi Coding 订阅端点，内置 provider 默认配置
- `glm`：Z.AI GLM Coding Plan 端点，使用 OpenAI 兼容请求格式
- `litellm`：LiteLLM VLM API，支持 `bedrock/`、`sagemaker/`、`vertex_ai/`、`azure/` 等显式 LiteLLM 路由

对于 `openai-codex`，请通过 `openviking-server init` 完成鉴权，再使用 `openviking-server doctor` 做校验。

对于 `litellm`，当底层路由使用环境变量或 provider 原生凭据时可以省略
`api_key`，例如 Bedrock/SageMaker 的 AWS IAM/IRSA，或 Vertex AI 的
ADC/service-account 凭据。Azure 路由仍会正常使用 `api_key`。如果明确要使用
LiteLLM 的 Bedrock bearer-token API-key 鉴权，请设置 `forward_api_key=true`。

**自定义 HTTP Headers**

对于 OpenAI 兼容的 provider（如 OpenRouter），可以通过 `extra_headers` 添加自定义 HTTP 请求头：

```json
{
  "vlm": {
    "provider": "openai",
    "api_key": "your-api-key",
    "model": "gpt-4o",
    "api_base": "https://openrouter.ai/api/v1",
    "extra_headers": {
      "HTTP-Referer": "https://your-site.com",
      "X-Title": "Your App Name"
    }
  }
}
```

常见使用场景：
- **OpenRouter**: 需要 `HTTP-Referer` 和 `X-Title` 来标识应用
- **Kimi Coding**: 需要自定义 user agent 或追加订阅请求头时可以在这里覆盖
- **自定义代理**: 添加认证头或追踪头
- **API 网关**: 添加版本或路由标识

**自定义请求 Body**

对于接受 provider 专有 JSON body 字段的 OpenAI 兼容 provider，可以通过 `extra_request_body` 配置。OpenViking 会把这些字段合并到 OpenAI SDK 或 LiteLLM 发送的 `extra_body` 中：

```json
{
  "vlm": {
    "provider": "litellm",
    "api_key": "ollama",
    "model": "ollama/llama3.1",
    "api_base": "http://127.0.0.1:11434",
    "extra_request_body": {
      "think": false
    }
  }
}
```

**流式模式**

对于返回 SSE（Server-Sent Events）格式响应的 OpenAI 兼容 provider，启用 `stream` 模式：

```json
{
  "vlm": {
    "provider": "openai",
    "api_key": "your-api-key",
    "model": "gpt-4o",
    "api_base": "https://api.example.com/v1",
    "stream": true
  }
}
```

> **注意**: OpenAI SDK 需要 `stream=true` 才能正确解析 SSE 响应。使用强制返回 SSE 格式的 provider 时，必须将此选项设置为 `true`。

**音视频理解**

音频和视频理解是当前 VLM 的可选能力，复用相同的 provider、模型、凭据、client、请求超时、重试、请求头、最大输出 token、故障切换链路和 token 统计。通过嵌套的 `vlm.media` 参数启用，不再单独配置媒体模型。

```json
{
  "vlm": {
    "provider": "volcengine",
    "api_key": "${VOLCENGINE_API_KEY}",
    "model": "${VOLCENGINE_MODEL}",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "timeout": 1200,
    "max_retries": 3,
    "max_tokens": 4096,
    "media": {
      "enabled": true,
      "file_processing_timeout": 1800,
      "file_poll_interval": 3,
      "max_concurrent": 2,
      "video_fps": 1.0
    }
  }
}
```

VLM 的 `model` 填写对应的方舟模型 endpoint ID。`video_fps` 仅用于视频，控制发送给方舟的视频采样帧率。

推荐使用 `doubao-seed-2-0-lite-260428` 或 `doubao-seed-2-0-mini-260428` 作为音视频理解模型。它们是可直接采用的推荐示例，并非完整的支持模型列表；方舟会持续更新模型及其输入能力。视频理解的可选模型请参考方舟官方[视频输入能力列表](https://console.volcengine.com/ark/region:cn-beijing/docs/82379/1330310?lang=zh#ff5ef604)，音频理解的可选模型请参考方舟官方[音频输入能力列表](https://console.volcengine.com/ark/region:cn-beijing/docs/82379/1330310?lang=zh#9619c0ba)。如果 `model` 填写的是 `ep-*` 推理接入点 ID，请确认该接入点背后的基础模型支持对应的媒体输入。OpenViking 不会在配置加载时校验模型的音频或视频能力。

**可接入格式与可理解格式**

| 类型 | 现有 Parser 可接入并保存 | 本版本可由方舟理解 |
|------|--------------------------|--------------------|
| 音频 | MP3、WAV、OGG、FLAC、AAC、M4A、OPUS、AC3 | MP3、WAV、AAC、M4A |
| 视频 | MP4、AVI、MOV、MKV、WEBM、FLV、WMV、TS | MP4、AVI、MOV |

不在“可理解”列中的格式继续沿用现有 Parser 和存储行为；OpenViking 不会对这些文件转码，也不会把它们发送给理解模型。当文件被识别为音频或视频叶子节点时，空媒体摘要会使用文件名入库。

对于支持的文件，OpenViking 将媒体上传到方舟 Files API，且不显式指定 `expire_at`，因此文件保留时间遵循方舟的默认策略。文件处理完成后，OpenViking 通过禁用响应存储的 Responses API 请求引用其 `file_id`，最后在较短的清理超时内尝试删除方舟文件。远端删除属于 best-effort；如果删除失败或超时，不会覆盖已经成功的理解结果，文件将继续遵循方舟的默认保留策略。本地临时文件独立清理，即使远端清理失败或请求被取消也会删除。

- 目录中只有一个音频或视频文件且理解成功时，该摘要直接成为目录 L1，并通过现有语义链路派生 L0，不再调用通用 VLM 做第二次总结。
- 媒体位于混合目录时，其摘要仍参与现有通用 VLM 聚合。
- 音视频理解未启用、理解格式不支持或模型最终失败时，媒体摘要为空；目录 L0/L1 生成保持原有通用行为，被识别为音频或视频的叶子节点则使用文件名作为 DETAIL 向量和 BM25 内容。Provider 错误和媒体理解状态文字不会写入媒体摘要或叶子索引。

媒体处理会把文件内容发送给所配置的外部 provider。禁用响应存储和 best-effort 删除可以降低非预期留存风险，但不能替代 provider 自身的隐私与留存控制；上传文件未显式指定过期时间，其保留周期由方舟的默认策略决定。方舟 Files 的存储/处理以及 Responses 的模型 token 可能产生费用；启用前请确认 provider 的隐私、留存和计费条款。详见火山方舟官方[音频理解文档](https://docs.volcengine.com/docs/82379/2377589?lang=zh)和[视频理解文档](https://docs.volcengine.com/docs/82379/1895586?lang=zh)。

### query_planner

可选的轻量模型配置，用于检索前的意图分析和 query 规划/改写。配置结构与 `vlm` 相同，但只影响 `search()` 的意图分析和 query expansion。未配置或配置为空时，OpenViking 会回退到 `vlm`，保持向后兼容。

> 在 `openviking-server init` 里可勾选启用本地轻量 query planner，向导会自动拉取 Ollama 模型并写入 `query_planner` 配置。对于已知的 query planner 模型，`search()` 会在运行时自动选择匹配的内置 prompt；不在映射表中的模型继续使用 `retrieval.intent_analysis`。

推荐优先使用本地 Ollama 模型 [`guoxuter/ov_intent_analysis_sft:v7_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v7_q8)。该模型基于 Qwen3.5-0.8B 进行微调，可本地部署，适合用小模型承担检索规划：在闲聊、问候或上下文已足够的场景下拒绝检索，从而减少不必要的记忆注入和 token 消耗；需要检索时，再生成面向 `skill`、`resource`、`memory` 的结构化查询。此前的 [`v4_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v4_q8) 版本仍作为可选项继续支持。

使用前请先拉取模型，并确保 Ollama 服务可访问：

```bash
ollama pull guoxuter/ov_intent_analysis_sft:v7_q8
```

然后在 OpenViking 配置中添加：

```json
{
  "query_planner": {
    "provider": "litellm",
    "model": "ollama/guoxuter/ov_intent_analysis_sft:v7_q8",
    "api_base": "http://127.0.0.1:11434",
    "temperature": 0.0,
    "timeout": 60,
    "extra_request_body": {
      "think": false
    }
  }
}
```

对于 `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` 处理语义提取、记忆提取和多模态内容。


### feishu

飞书/Lark 云端文档解析配置。支持的 URL 格式详见[资源管理](../api/02-resources.md)。

```json
{
  "feishu": {
    "app_id": "",
    "app_secret": "",
    "domain": "https://open.feishu.cn",
    "max_rows_per_sheet": 1000,
    "max_records_per_table": 1000
  }
}
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `app_id` | str | 飞书应用 ID（也可通过 `FEISHU_APP_ID` 环境变量设置） |
| `app_secret` | str | 飞书应用密钥（也可通过 `FEISHU_APP_SECRET` 环境变量设置） |
| `domain` | str | 飞书 API 域名。Lark 国际版请设为 `https://open.larksuite.com` |
| `max_rows_per_sheet` | int | 电子表格每个 sheet 最大导入行数（默认 `1000`） |
| `max_records_per_table` | int | 多维表格每个表最大导入记录数（默认 `1000`） |

**依赖**：已默认包含在 `openviking[bot]` 安装中

**Lark 国际版**：对于 Lark URL（`*.larksuite.com`），请将 `domain` 设为 `https://open.larksuite.com`。

### code

代码骨架提取内置在代码摘要流程中，不再提供解析器级配置。OpenViking 会在语言存在维护中的 `tags.scm` 时优先使用 tags query；不存在对应的 `tags.scm` 时，使用 `tree-sitter-language-pack.process()`；当前提取路线无可用结果时，才将 `semantic.code_summary` 作为兜底处理。

当前保留的 `code` 配置字段用于远程代码资源的网络防护和代码托管白名单。提取路线详见 [代码骨架提取](../concepts/06-extraction.md#代码骨架提取)。

#### 远程资源网络防护

通过 URL 拉取资源时，OpenViking 会拒绝环回、链路本地、私有及其他非公网目标，以及不在代码托管白名单中的主机，并抛出 `PermissionDeniedError`。要从自建 GitHub Enterprise / GitLab / Azure DevOps 拉取代码，请将主机加入 `code` 下对应的白名单：

| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `github_domains` | list[str] | 允许的 GitHub 主机（在此添加你的 GitHub Enterprise 主机） | `["github.com", "www.github.com"]` |
| `gitlab_domains` | list[str] | 允许的 GitLab 主机（在此添加你的自建 GitLab 主机） | `["gitlab.com", "www.gitlab.com"]` |
| `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`（默认关闭，因此仅允许公网地址）：

```json
{
  "allow_private_networks": false,
  "code": {
    "github_domains": ["github.com", "github.example.com"]
  }
}
```

需要 GitHub、GitLab 或 Azure DevOps 专属 URL 语义时，应配置到对应的平台字段；
其他 Git 主机统一添加到 `code_hosting_domains`。

### rerank

用于搜索结果精排的 Rerank 模型。支持 VikingDB (火山引擎)、Cohere 和 OpenAI 兼容接口。

**火山引擎 (VikingDB):**

```json
{
  "rerank": {
    "provider": "vikingdb",
    "ak": "your-access-key",
    "sk": "your-secret-key",
    "model_name": "doubao-seed-rerank",
    "model_version": "251028"
  }
}
```

**OpenAI 兼容提供方 (如 DashScope):**

```json
{
  "rerank": {
    "provider": "openai",
    "api_key": "your-api-key",
    "api_base": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",
    "model": "qwen3-rerank",
    "timeout": 120,
    "max_input_tokens": 2048,
    "threshold": 0.1
  }
}
```

**参数**

| 参数 | 类型 | 说明 |
|------|------|------|
| `provider` | str | `"vikingdb"`、`"cohere"` 或 `"openai"`。省略时基于字段自动识别。 |
| `ak` | str | VikingDB Access Key（仅 `vikingdb` 提供方使用） |
| `sk` | str | VikingDB Secret Key（仅 `vikingdb` 提供方使用） |
| `model_name` | str | 模型名称（仅 `vikingdb` 提供方使用，默认：`doubao-seed-rerank`） |
| `api_key` | str | API Key（用于 `openai` 或 `cohere` 提供方） |
| `api_base` | str | 接口地址（用于 `openai` 提供方） |
| `model` | str | 模型名称（用于 `openai` 提供方） |
| `timeout` | float | OpenAI 兼容 provider 的 HTTP 请求超时时间，单位为秒。对于较慢或冷启动的本地 rerank 服务可适当增大。默认：`30.0` |
| `max_input_tokens` | int | 每个 query-document 对发送给 reranker 的最大估算原始文本 token 数；超长输入会保留开头和结尾。`0` 表示不截断。默认：`0` |
| `threshold` | float | 分数阈值，范围为 `0.0` 到 `1.0`。低于此值的结果会被过滤。默认：`0.1` |
| `extra_headers` | object | 自定义 HTTP 请求头（OpenAI 兼容 provider 可用，可选） |

**支持的提供方:**
- `vikingdb`: 火山引擎 VikingDB Rerank API (使用 AK/SK)
- `cohere`: Cohere Rerank API
- `openai`: OpenAI 兼容的 Rerank 接口

如果未配置 Rerank，搜索仅使用向量相似度。

### retrieval

最终搜索分数的召回排序配置。

```json
{
  "retrieval": {
    "hotness_alpha": 0.0,
    "score_propagation_alpha": 1.0,
    "recall_intent_timeout_s": 5.0,
    "recall_rewrite_timeout_s": 30.0
  }
}
```

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `hotness_alpha` | float | hotness 分数在最终召回分数中的混合权重。`0.0` 表示关闭 hotness boost，最终分数等于语义相似度；`1.0` 表示只使用 hotness。有效范围：`0.0` 到 `1.0`。 | `0.0` |
| `score_propagation_alpha` | float | 层级检索中，子节点自身分数与父节点传播分数混合时，子节点自身分数的权重。`1.0` 表示忽略父节点分数（仅使用语义相似度）；`0.5` 表示与父节点分数等权混合；`0.0` 表示只使用父节点分数。有效范围：`0.0` 到 `1.0`。 | `1.0` |

如果需要分数严格反映向量相似度，保持 `hotness_alpha` 为 `0.0`。只有当希望高频访问或最近更新的上下文获得排序提升时，才将它设置为大于 `0.0`。

`/search` 的 `mode="context"` 组装面用到两个超时熔断：

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `recall_intent_timeout_s` | float | 会话感知查询扩展的超时；超时后回退为用户原查询 | `5.0` |
| `recall_rewrite_timeout_s` | float | digest 重写的超时；超时后 `digest` 为空并照常返回 `rendered` | `30.0` |

两个 LLM 环节都是纯 opt-in：查询扩展需要传 `session_id`，重写需要传 `rewrite`。任一环节失败都优雅降级，不会阻塞召回。

### grep

Grep 引擎配置，用于内容模式搜索。这些设置为服务端配置，不支持请求级别覆盖。

```json
{
  "grep": {
    "engine": "auto",
    "switch_to_remote_threshold": 10000
  }
}
```

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `engine` | str | 搜索引擎模式：`"auto"` 在可用时使用 VikingDB BM25 召回，不可用时回退到本地文件系统搜索；`"fs"` 强制仅使用本地文件系统搜索。 | `"auto"` |
| `switch_to_remote_threshold` | int | 切换到 VikingDB BM25 召回的 L2 记录数阈值。当搜索范围内的 L2 文件数达到此阈值时，使用 VikingDB BM25 进行第一阶段召回；否则使用本地文件系统搜索。设为 `0` 表示始终使用 VikingDB BM25。必须 ≥ 0。 | `10000` |

对于 VikingDB / Volcengine FullText grep，OpenViking 会写入 `content` text 字段用于 BM25 召回。源上下文中保留完整内容，仅在最终写入向量库 adapter payload 时将该字段截断到 **1 MB**，以满足后端 payload 限制。只有 VikingDB 系后端使用 `content`；其它后端（`local`、`cuvs`、`qdrant`、`opengauss`、`http`）不写入该字段。

### storage

用于存储上下文数据 ，包括文件存储（RAGFS）和向量库存储（VectorDB）。

#### 根级配置

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `workspace` | str | 本地数据存储路径（主要配置） | "./data" |
| `skip_process_lock` | bool | 是否跳过 `storage.workspace` 的启动进程锁检查。启用后，OpenViking 不会检查或创建 `.openviking.pid` 锁文件。 | `false` |
| `agfs` | object | RAGFS（Rust 实现的 AGFS）配置 | {} |
| `vectordb` | object | 向量库存储配置 | {} |


```json
{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "timeout": 10
    },
    "vectordb": {
      "backend": "local"
    }
  }
}
```

#### agfs (RAGFS)

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `backend` | str | `"local"`、`"s3"` 或 `"memory"` | `"local"` |
| `timeout` | float | 请求超时时间（秒） | `10.0` |
| `backups` | object | 多写存储配置。配置后顶层 `backend` 作为 primary，`backups.items[]` 作为 backup | `null` |
| `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') | - |


**配置示例**

RAGFS 默认使用 Rust binding 模式，通过 Rust 实现直接访问文件系统。

> [!WARNING]
> `storage.agfs` 已不再支持 AGFS HTTP client 模式，也无需再配置旧的 HTTP client 入口。当前 AGFS / RAGFS 文件系统访问仅通过 Rust binding（`RAGFSBindingClient`）在进程内完成。这不影响 OpenViking server 的 HTTP API、`ov` CLI，或 `AsyncHTTPClient` / `SyncHTTPClient` 访问 OpenViking 服务端的能力。

##### 多写存储配置

`storage.agfs.backups` 用于启用多写存储。未配置时，OpenViking 保持单 backend 模式。

```json
{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "redirects": [
        {
          "type": "FileExtensionPolicy",
          "extensions": ["(pdf|ppt|zip)"],
          "target": ["s3-backup"]
        }
      ],
      "backups": {
        "sync_type": "async",
        "items": [
          {
            "name": "s3-backup",
            "backend": "s3",
            "s3": {
              "bucket": "openviking-backup",
              "region": "cn-beijing",
              "endpoint": "https://tos-s3-cn-beijing.volces.com",
              "access_key": "your-ak",
              "secret_key": "your-sk",
              "prefix": "multi-write"
            }
          }
        ]
      }
    }
  }
}
```

`backups` 常用字段：

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `sync_type` | str | 多写同步模式，支持 `"async"` 或 `"sync"` | `"async"` |
| `write_ack_count` | int | `sync` 模式下返回前需要的 backup 确认数 | 全部 backup |
| `write_ack_timeout_ms` | int | `sync` 模式下等待 backup 确认的超时时间，单位毫秒 | `null` |
| `write_concurrency` | int | 异步 backup 写入并发上限 | `null` |
| `items` | array | backup backend 列表，每个 item 复用普通 backend 配置并增加 `name`、`operations`、`excludes`、`encryption` 等字段 | `[]` |

`redirects` 常用字段：

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `type` | str | 策略类型，支持 `"FileExtensionPolicy"` 或 `"FileOverSizePolicy"` | 必填 |
| `extensions` | array | `FileExtensionPolicy` 使用的扩展名正则列表，例如 `["(pdf\|ppt)"]` | `[]` |
| `max_size_mb` | int | `FileOverSizePolicy` 使用的文件大小阈值，单位 MB | `null` |
| `target` | array | 命中策略后写入的 backup `name` 列表 | 必填 |

按文件大小重定向示例：

```json
{
  "type": "FileOverSizePolicy",
  "max_size_mb": 100,
  "target": ["s3-backup"]
}
```

注意：

- `redirects` 配置在顶层 `storage.agfs`，表示 primary 的重定向策略。
- `target` 必须引用 `backups.items[]` 中已经定义的 backup `name`。
- 命中 redirect 的文件仍会通过普通文件系统 API 呈现为可读、可列举的文件。

更多配置示例见 [多写存储指南](./13-multi-write-storage.md)。

##### QueueFS 配置

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `mode` | str | QueueFS 命名空间模式：`"shared"` 使用 `/queue`；`"worker"` 为每个 worker 隔离到 `/queue/worker-<index\|pid>` | `"shared"` |
| `backend` | str | QueueFS 后端：`"memory"`、`"sqlite"`、`"sqlite3"` 或 `"redis"` | `"sqlite"` |
| `db_path` | str（可选） | 当 backend 为 `"sqlite"` 或 `"sqlite3"` 时使用的 QueueFS sqlite 数据库路径 | `null` |
| `recover_stale_sec` | int | 启动时恢复超过该秒数的 `processing` 队列消息；`0` 表示恢复全部 stale processing 消息 | `0` |
| `busy_timeout_ms` | int | QueueFS sqlite 的 busy timeout，单位毫秒 | `5000` |
| `redis` | object | 当 backend 为 `"redis"` 时使用的连接参数 | 见下表 |

QueueFS Redis 参数：

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `mode` | str | Redis 拓扑模式：`"singleton"`、`"cluster"` 或 `"sentinel"` | `"singleton"` |
| `endpoints` | array[str] | Singleton 的唯一数据节点、Cluster 初始节点或 Sentinel 节点；仅允许协议、主机和端口，认证与 DB 使用独立字段 | `["redis://127.0.0.1:6379"]` |
| `master_name` | str（可选） | Sentinel master 名称；Sentinel 模式必须配置 | `null` |
| `username` | str（可选） | Redis ACL 用户名 | `null` |
| `password` | str（可选） | Redis ACL 密码 | `null` |
| `sentinel_username` | str（可选） | Sentinel ACL 用户名 | `null` |
| `sentinel_password` | str（可选） | Sentinel ACL 密码 | `null` |
| `db` | int | Redis database 编号 | `0` |
| `connect_timeout_ms` | int | Redis 数据节点物理建连超时，单位毫秒 | `3000` |
| `command_timeout_ms` | int | 命令读写超时，单位毫秒 | `3000` |
| `key_prefix` | str | Redis key 隔离前缀，不能为空；所有 QueueFS key 使用 `{key_prefix}:ov:*` | `"default"` |
| `tls_enabled` | bool | 对 `redis://` endpoint 强制启用 TLS | `false` |
| `tls_insecure_skip_verify` | bool | 跳过 TLS 证书校验，仅用于受控测试环境 | `false` |

说明：

- 即使主 AGFS 存储后端是 `local`、`s3` 或 `memory`，QueueFS 默认仍使用 `sqlite`。
- `mode=shared` 会继续使用历史上的全局队列命名空间 `/queue`；`mode=worker` 会为每个 worker 隔离到 `/queue/worker-<index|pid>`。
- `db_path` 仅在 QueueFS backend 为 `sqlite` 或 `sqlite3` 时生效。
- `recover_stale_sec` 和 `busy_timeout_ms` 仅在 QueueFS backend 为 `sqlite` 或 `sqlite3` 时生效。
- Redis Singleton 模式必须且只能配置一个 endpoint。
- Redis Cluster 模式的 endpoints 是初始节点，且必须配置 `db=0`；slot 路由、`MOVED`/`ASK` 处理和节点重连由 redis-rs 完成。
- Redis Sentinel 模式的 endpoints 是 Sentinel 节点，并且必须配置非空 `master_name`；master 发现和故障切换后的重连由 redis-rs 完成。
- Redis Sentinel 模式下，`connect_timeout_ms` 作用于发现 Master 后的数据节点连接；redis-rs 同步 Sentinel discovery 不暴露物理建连 timeout，该阶段由内部固定 5 秒的 pool checkout timeout 限制调用方等待。
- `username` 和 `password` 用于 Redis 数据节点；`sentinel_username` 和 `sentinel_password` 仅用于 Sentinel 节点。
- Redis backend 使用 `{key_prefix}:ov:*` key；连接同一 Redis database 的不同业务必须配置不同的 `key_prefix`。
- Redis backend 的实例心跳 TTL 为 30 秒，每 10 秒续约一次。
- Redis backend 会在独立的 startup recovery 线程中按实例心跳状态执行三次有界 `recover_stale` 扫描，时间点分别为启动后立即、30 秒和 60 秒，用于覆盖容器异常退出后旧实例心跳尚未过期的恢复窗口；运行期间不做长期周期恢复。
- `tls_insecure_skip_verify=true` 时必须同时设置 `tls_enabled=true`。
- 如果同时设置了 `storage.agfs.queuefs.db_path` 和旧字段 `storage.agfs.queue_db_path`，以前者为准。
- 如果 QueueFS backend 为 `memory`，则 `db_path` 和旧字段 `queue_db_path` 都会被忽略。

示例：

```json
{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "queuefs": {
        "mode": "shared",
        "backend": "sqlite",
        "db_path": "./data/_system/queue/custom-queue.db"
      }
    }
  }
}
```

Redis QueueFS 配置示例：

```json
{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "queuefs": {
        "mode": "shared",
        "backend": "redis",
        "redis": {
          "mode": "singleton",
          "endpoints": ["redis://127.0.0.1:6379"],
          "master_name": null,
          "username": null,
          "password": null,
          "sentinel_username": null,
          "sentinel_password": null,
          "db": 0,
          "connect_timeout_ms": 3000,
          "command_timeout_ms": 3000,
          "key_prefix": "default",
          "tls_enabled": false,
          "tls_insecure_skip_verify": false
        }
      }
    }
  }
}
```

Redis Cluster 只需配置可用于发现拓扑的初始节点：

```json
{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "queuefs": {
        "mode": "shared",
        "backend": "redis",
        "redis": {
          "mode": "cluster",
          "endpoints": [
            "redis://redis-cluster-0:6379",
            "redis://redis-cluster-1:6379"
          ],
          "db": 0,
          "key_prefix": "default"
        }
      }
    }
  }
}
```

Redis Sentinel 分别配置数据节点和 Sentinel 的 ACL：

```json
{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "queuefs": {
        "mode": "shared",
        "backend": "redis",
        "redis": {
          "mode": "sentinel",
          "endpoints": [
            "redis://redis-sentinel-0:26379",
            "redis://redis-sentinel-1:26379"
          ],
          "master_name": "mymaster",
          "username": "queue-user",
          "password": "queue-password",
          "sentinel_username": "sentinel-user",
          "sentinel_password": "sentinel-password",
          "db": 0,
          "key_prefix": "default"
        }
      }
    }
  }
}
```

```json
{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "queuefs": {
        "mode": "worker",
        "backend": "memory"
      }
    }
  }
}
```

旧字段兼容示例：

```json
{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "queue_db_path": "./data/_system/queue/queue.db"
    }
  }
}
```

##### Session Auto Commit 配置

`memory.session_auto_commit` 用于控制服务端 session 自动 commit 的全局行为。

```json
{
  "memory": {
    "session_auto_commit": {
      "default_enabled": false,
      "idle_enabled": false,
      "check_interval_seconds": 60.0,
      "scan_batch_size": 16,
      "scan_batch_pause_seconds": 0.0
    }
  }
}
```

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `default_enabled` | bool | 对未显式传入 `auto_commit_policy` 的新 session，是否默认开启 auto commit。为 `false` 时，这类 session 保持关闭 | `false` |
| `idle_enabled` | bool | 是否启用服务端 idle timeout 自动 commit 调度器。关闭后，不会启动 idle scheduler；但 token / message-count 的即时触发仍然生效 | `false` |
| `check_interval_seconds` | float | idle scheduler 的检查周期，单位秒，必须大于 `0` | `60.0` |
| `scan_batch_size` | int | 每个 idle 扫描批次最多并发读取的 session meta 文件数量，必须大于 `0` | `16` |
| `scan_batch_pause_seconds` | float | idle 扫描批次之间的可选暂停时间，单位秒，用于降低大量 session 扫描时的存储压力 | `0.0` |

说明：

- `memory.session_auto_commit` 是服务端全局配置，不是单个 session 的业务 policy。
- session 级别的自动触发参数通过 session 级 `auto_commit_policy` 设置（见下表）。它只能在创建 session 时通过 `POST /api/v1/sessions` 的顶层 `auto_commit_policy` 字段设置，之后通过 `GET /api/v1/sessions/{session_id}` 查看；不支持运行期 PATCH 修改。
- `default_enabled=false` 时，未传 `auto_commit_policy` 创建的 session 保持 auto commit 关闭，返回 `auto_commit_policy: null`。显式传 `{}` 或任意 policy 字段会为该 session 开启 auto commit，并用下方默认值补齐缺失字段。
- `default_enabled=true` 时，未传 `auto_commit_policy` 创建的 session 会带上下方默认 policy。
- `idle_enabled=false` 时：
  - 不会启动 `SessionAutoCommitScheduler`
- `idle_enabled=true` 时：
  - `SessionAutoCommitScheduler` 会按固定周期扫描 AGFS `/local/{account}/user/{user}/sessions` 下的 session `.meta.json`
  - 不会做单独的启动恢复扫描，idle 检查只发生在周期扫描时
- token 和 message-count 自动触发在消息写入后内联执行，不依赖 scheduler，也不受这个开关影响。

###### 单 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 | 10000 | 50000 | 当未提交的 pending token 超过该值（严格大于）时，会在消息写入后触发一次自动 commit。 |
| `message_count_threshold` | int | 50 | 500 | 当未提交的 live message 数量超过该值（严格大于）时，会在消息写入后触发一次自动 commit。 |
| `idle_timeout_seconds` | int | 86400 | 604800 | 有未提交内容的 session 在空闲这么多秒后，进入服务端 idle scheduler 的处理范围。idle 触发的 commit 会归档全部积压消息，并忽略 `keep_recent_count`。 |
| `keep_recent_count` | int | 2 | 500 | 阈值触发的自动 commit 后保留（不归档）的最近 live message 数量。idle 超时触发的 commit 会忽略该值并归档所有消息。 |
| `min_commit_interval_seconds` | int | 0 | 604800 | 两次自动 commit 之间的最小间隔秒数（节流）。 |

代码入口：`openviking/session/auto_commit_policy.py:AutoCommitPolicy`。


##### S3 后端配置

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `bucket` | str | S3 存储桶名称 | null |
| `region` | str | 存储桶所在的 AWS 区域（例如 us-east-1, cn-beijing） | null |
| `access_key` | str | S3 访问密钥 ID | null |
| `secret_key` | str | 与访问密钥 ID 对应的 S3 秘密访问密钥 | null |
| `endpoint` | str | 自定义 S3 端点，对于 MinIO 或 LocalStack 等 S3 兼容服务是必需的。可以填完整 URL（`https://...` 或 `http://...`），也可以只填主机名；只填主机名时会根据 `use_ssl` 自动补 `https://` 或 `http://` | null |
| `prefix` | str | 用于命名空间隔离的可选键前缀 | "" |
| `use_ssl` | bool | 为 S3 连接启用/禁用 SSL（HTTPS）。也用于决定 `endpoint` 仅填主机名时自动补的协议前缀 | true |
| `use_path_style` | bool | true 表示对 MinIO 和某些 S3 兼容服务使用 PathStyle；false 表示对 TOS 和某些 S3 兼容服务使用 VirtualHostStyle | true |
| `auto_detect_content_type` | bool | 上传时根据 object key / 文件名后缀自动推断 MIME 类型，并写入 S3 对象的 `Content-Type` | false |
| `directory_marker_mode` | str | 目录 marker 的持久化方式，可选 `none`、`empty`、`nonempty` | `"empty"` |
| `normalize_encoding_chars` | str | 需要在 S3 object key 中转义为 `!HH` 十六进制字节的字符集合；空字符串表示关闭编码 | `"?#%+@"` |

`directory_marker_mode` 用来控制 RAGFS 在 S3 中如何落目录对象：

- `empty` 是默认值。RAGFS 会写入 0 字节目录 marker，并保留空目录语义。
- `nonempty` 会写入非空目录 marker。对于 TOS 这类拒绝 0 字节目录 marker 的 S3 兼容后端，应使用这个模式。
- `none` 会让 RAGFS 采用更接近原生 S3 prefix 的目录语义，不再创建目录 marker 对象。此时空目录不会被持久化，只有目录下至少存在一个子对象后，相关目录才可能被发现。

典型选择：

- 对 MinIO、SeaweedFS 以及大多数 PathStyle 后端，保持默认 `empty` 即可。
- 对 TOS 或其他拒绝 0 字节目录 marker 的 VirtualHostStyle 后端，使用 `nonempty`。
- 如果你想完全使用 prefix 风格行为，并且不需要持久化空目录，可以使用 `none`。

`normalize_encoding_chars` 用来控制 RAGFS 在发起 S3 请求前需要重写哪些字符：

- 默认值是 `"?#%+@"`，所以只会转义 `?`、`#`、`%`、`+`、`@`。
- 被转义的字节会编码成 `!HH`，其中 `HH` 是该字节的大写十六进制值。
- 没有列在 `normalize_encoding_chars` 里的字符，包括中文和其他 Unicode 字符，都会保持原样。
- 设为 `""` 时，会在 object key 中保留原始路径段。

`auto_detect_content_type` 默认关闭，以兼容历史行为。开启后，RAGFS 会根据 object key / 文件名后缀推断 MIME 类型，并写入 S3 对象的 `Content-Type`：

- 探测依据是 object key / 文件名后缀，不做文件内容 sniff。
- key 以 `/` 结尾的目录 marker 不会写 `Content-Type`。
- 无法识别的后缀会回退到 `application/octet-stream`。

示例：

```json
{
  "storage": {
    "agfs": {
      "backend": "s3",
      "s3": {
        "bucket": "my-bucket",
        "endpoint": "s3.amazonaws.com",
        "region": "us-east-1",
        "access_key": "your-ak",
        "secret_key": "your-sk",
        "auto_detect_content_type": true
      }
    }
  }
}
```

<details>
<summary><b>PathStyle S3</b></summary>
支持 PathStyle 模式的 S3 存储， 如 MinIO、SeaweedFS.

```json
{
  "storage": {
    "agfs": {
      "backend": "s3",
      "s3": {
        "bucket": "my-bucket",
        "endpoint": "s3.amazonaws.com",
        "region": "us-east-1",
        "access_key": "your-ak",
        "secret_key": "your-sk",
        "normalize_encoding_chars": "?#%+@"
      }
    }
  }
}
```
</details>


<details>
<summary><b>VirtualHostStyle S3</b></summary>
支持 VirtualHostStyle 模式的 S3 存储， 如 TOS.

```json
{
  "storage": {
    "agfs": {
      "backend": "s3",
      "s3": {
        "bucket": "my-bucket",
        "endpoint": "s3.amazonaws.com",
        "region": "us-east-1",
        "access_key": "your-ak",
        "secret_key": "your-sk",
        "use_path_style": false,
        "directory_marker_mode": "nonempty",
        "normalize_encoding_chars": "?#%+@"
      }
    }
  }
}
```

</details>

#### vectordb

向量库存储的配置

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `backend` | str | VectorDB 后端类型: 'local'（基于文件）, 'http'（远程服务）, 'volcengine'（云上 VikingDB）, 'vikingdb'（私有部署）, 'cuvs'（本地存储 + GPU dense search）, 'qdrant' 或 'opengauss' | "local" |
| `name` | str | VectorDB 的集合名称 | "context" |
| `url` | str | 'http' 类型的远程服务 URL（例如 'http://localhost:5000'） | null |
| `project_name` | str | 项目名称（别名 project） | "default" |
| `distance_metric` | str | 向量相似度搜索的距离度量（例如 'cosine', 'l2', 'ip'） | "cosine" |
| `dimension` | int | 向量嵌入的维度 | 0 |
| `sparse_weight` | float | 混合向量搜索的稀疏权重，仅在使用混合索引时生效 | 0.0 |
| `volcengine` | object | 'volcengine' 类型的 VikingDB 配置 | - |
| `vikingdb` | object | 'vikingdb' 类型的私有部署配置 | - |
| `cuvs` | object | NVIDIA cuVS 配置，也用于在 'local' 下显式开启显存感知自动模式，参见 [cuVS 使用指南](./16-cuvs.md) | - |
| `qdrant` | object | 'qdrant' 类型的 Qdrant 配置 | - |
| `opengauss` | object | 'opengauss' 原生向量后端配置 | - |

默认使用本地模式
```
{
  "storage": {
    "vectordb": {
      "backend": "local"
    }
  }
}
```

<details>
<summary><b>volcengine vikingDB</b></summary>
支持火山引擎云上部署的 VikingDB

```json
{
  "storage": {
    "vectordb": {
      "name": "context",
      "backend": "volcengine",
      "project": "default",
      "volcengine": {
        "region": "cn-beijing",
        "ak": "your-access-key",
        "sk": "your-secret-key"
      }
  }
}
```
</details>

<details>
<summary><b>openGauss</b></summary>

需要 openGauss 服务端支持原生 `vector` 类型，并使用允许远程连接的数据库用户。
可通过 `pip install "openviking[opengauss]"` 安装可选驱动。
官方容器中的初始 `omm` 用户可能限制远程登录，必要时请为 OpenViking 创建普通数据库用户。

```json
{
  "storage": {
    "vectordb": {
      "name": "context",
      "backend": "opengauss",
      "project": "default",
      "distance_metric": "cosine",
      "dimension": 1024,
      "opengauss": {
        "host": "127.0.0.1",
        "port": 5432,
        "user": "openviking",
        "password": "your-password",
        "db_name": "postgres",
        "schema": "public",
        "mode": "standalone"
      }
    }
  }
}
```

分布式 openGauss 部署可将 `mode` 设为 `"distributed"`；OpenViking 会尝试把元数据表标记为 reference table，并按 `id` 分布集合表。
</details>



## 配置文件

OpenViking 使用两个配置文件：

| 配置文件 | 用途 | 默认路径 |
|---------|------|---------|
| `ov.conf` | SDK 嵌入模式 + 服务端配置 | `~/.openviking/ov.conf` |
| `ovcli.conf` | HTTP 客户端和 CLI 连接远程服务端 | `~/.openviking/ovcli.conf` |

配置文件放在默认路径时，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
# 方式一：环境变量
export OPENVIKING_CONFIG_FILE=/path/to/ov.conf
export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf

# 方式二：命令行参数（仅 serve 命令）
openviking-server --config /path/to/ov.conf
```

### ov.conf

本文档上方各配置段（embedding、vlm、rerank、storage）均属于 `ov.conf`。SDK 嵌入模式和服务端共用此文件。

如需配置 memory 相关行为，可在 `ov.conf` 中添加 `memory` 段：

```json
{
  "memory": {
    "custom_templates_dir": "/path/to/custom-memory"
  }
}
```

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `version` | 已废弃且会被忽略。OpenViking 始终使用 v3 记忆抽取链路；已有配置中保留该字段仍可正常加载，不会报错。 | `"v3"` |
| `custom_templates_dir` | 自定义 memory templates 目录。设置后会在内置模板之外加载该目录中的模板。 | `""` |
| `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-配置)。 | 见上文 |

### ovcli.conf

你可以手动编辑此文件，也可以用 `ov config` 交互式生成。如果你维护着多个服务端的配置，可以用 `ov config switch` 在它们之间切换。

如需按步骤配置 CLI，请阅读 [OpenViking CLI 配置指南](../getting-started/05-cli-setup.md)。

HTTP 客户端（`SyncHTTPClient` / `AsyncHTTPClient`）和 CLI 工具连接远程服务端的配置文件：

```json
{
  "url": "http://localhost:1933",
  "api_key": "your-secret-key",
  "profile": false,
  "upload": {
    "mode": "local",
    "ignore_dirs": "node_modules,.cache,.nx",
    "include": "*.md,*.pdf",
    "exclude": "*.tmp,*.log"
  }
}
```

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `url` | 服务端地址 | （必填） |
| `api_key` | API Key 认证（root key 或 user key） | `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` |
| `upload.ignore_dirs` | `add-resource` 默认忽略目录列表（CSV） | `null` |
| `upload.include` | `add-resource` 默认包含模式（CSV） | `null` |
| `upload.exclude` | `add-resource` 默认排除模式（CSV） | `null` |
| `upload.mode` | Python HTTP client 的临时上传后端：`"local"`（仅当前实例本地磁盘）或 `"shared"`（分布式共享存储）。Rust `ov` CLI 不读取这个字段；如需 shared 上传，请设置 `OPENVIKING_UPLOAD_MODE=shared`。 | `null`（使用服务端 `temp_upload.default_mode`，默认仍为 `"local"`） |

本地目录上传会默认遵循 `.gitignore`（根目录和子目录，含 `!` 反向规则）。`ignore_dirs/include/exclude` 会在此基础上进一步过滤。

trusted 网关部署下，也可以在单次命令里用 CLI 参数覆盖这些身份字段：

```bash
openviking --account acme --user alice ls viking://
```

对于 `add-resource`，上传过滤参数会与 `ovcli.conf` 默认值做合并（追加），不会覆盖：

```bash
# ovcli.conf: upload.exclude="*.log"
openviking add-resource ./docs --exclude "*.tmp"
# 实际发送给服务端的 exclude: "*.log,*.tmp"
```

详见 [服务部署](./03-deployment.md)。

## server 段

将 OpenViking 作为 HTTP 服务运行时，在 `ov.conf` 中添加 `server` 段：

```json
{
  "server": {
    "host": "127.0.0.1",
    "port": 1933,
    "auth_mode": "api_key",
    "root_api_key": "your-secret-root-key",
    "profile_enabled": false,
    "cors_origins": ["*"],
    "public_base_url": "https://ov.example.com",
    "upload_signed_ttl_seconds": 600,
    "temp_upload": {
      "default_mode": "local",
      "shared_max_size_bytes": 536870912,
      "shared_prefix": "viking://upload"
    },
    "user_config_defaults": {
      "add_targets": {
        "resource_uri": "viking://user/resources",
        "skill_uri": "viking://user/skills"
      }
    },
    "agent_evolution": {
      "enabled": false
    }
  }
}
```

| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `host` | str | 绑定地址 | `127.0.0.1` |
| `port` | int | 绑定端口 | `1933` |
| `auth_mode` | str | 认证模式：`"api_key"` 或 `"trusted"`。默认值为 `"api_key"` | `"api_key"` |
| `root_api_key` | str | Root API Key。在 `api_key` 模式下启用多租户认证；在 `trusted` 模式下它只是可选附加保护，不负责解析普通用户身份 | `null` |
| `profile_enabled` | bool | 是否允许 HTTP 请求通过 `profile=1` 开启请求级 cProfile。关闭时服务端会忽略该请求参数；开启后，CLI 可以显示返回的 `profile`，而 Python HTTP client 默认只触发服务端 profile，不会把顶层 `profile` 字段自动附着到大多数 SDK 返回值上。 | `false` |
| `cors_origins` | list | CORS 允许的来源 | `["*"]` |
| `public_base_url` | str | MCP `add_resource` 工具向客户端返回的上传指令里使用的对外可见 base URL。解析顺序：环境变量 `OPENVIKING_PUBLIC_BASE_URL` → 本字段 → 请求头 `X-Forwarded-Host` / `X-Forwarded-Proto` → 请求头 `Host` → 监听地址兜底。当 server 部署在反向代理后且代理不转发 `X-Forwarded-*` 时，请显式设置本字段（或环境变量）。 | `null` |
| `upload_signed_ttl_seconds` | int | MCP `add_resource` 为本地文件上传 mint 的一次性 token 的过期时间（秒），走 `POST /api/v1/resources/temp_upload?token=...`。 | `600`（10 分钟） |
| `temp_upload.default_mode` | str | `POST /api/v1/resources/temp_upload` 的服务端默认模式（客户端未显式传 `upload_mode` 时使用）：`"local"`（仅当前实例本地磁盘，单机默认行为）或 `"shared"`（分布式共享存储，多副本部署可跨实例消费）。 | `"local"` |
| `temp_upload.shared_max_size_bytes` | int | `shared` 模式下接受的最大文件大小（字节）。超过此阈值的请求会在写入对象存储之前被拒绝。 | `536870912`（512 MiB） |
| `temp_upload.shared_prefix` | str | 分配 shared `temp_file_id` 对象时使用的 URI 前缀。 | `"viking://upload"` |
| `user_config_defaults.add_targets.resource_uri` | str | `add_resource` 未传 `to` 和 `parent` 时使用的部署级默认资源添加目录。`viking://user/...` 会按请求用户解析。 | `null` |
| `user_config_defaults.add_targets.skill_uri` | str | `add_skill` 未传 `target_uri` 时使用的部署级默认技能添加根目录。仅允许 `viking://user/skills` 和 `viking://agent/skills`。 | `null` |
| `agent_evolution.enabled` | bool | 实例级 Agent 进化开关。开启时，session commit 可按 session `memory_policy` 生成或更新 cases、trajectories 和 experiences；关闭时，所有账号和用户均停止生产这三类记忆。已有记忆仍可读取和检索。 | `false` |

`api_key` 模式使用 API Key 认证，也是默认模式；`trusted` 模式信任上游网关或受信调用方注入的 `X-OpenViking-Account` / `X-OpenViking-User` 请求头。

在 `api_key` 模式下配置 `root_api_key` 后，服务端启用正式多租户认证，并通过 Admin API 创建工作区和用户 key。在 `trusted` 模式下，普通请求不需要先注册 user key；每个请求都会根据注入的身份头解析成 `USER`。只有在 `auth_mode = "api_key"` 且未配置 `root_api_key` 时，服务端才会进入开发模式。

`user_config_defaults` 仅用于添加目标的用户级默认配置。添加操作中，显式请求目标仍然优先：`add_resource.to` / `add_resource.parent` 优先于用户默认值，`add_skill.target_uri` 优先于用户默认值。`agent_evolution.enabled` 是当前 OpenViking 实例的统一开关，不支持用户级覆盖。HTTP Server 的 worker 会在 session commit 时从启动阶段解析出的 `ov.conf` 路径读取当前值，因此合法的文件更新无需重启服务即可生效。

### Usage Reporter

可选的 Usage Reporter 从已 commit session 的 tool parts 中抽取记忆使用事件。内置文件日志 Sink 将每个事件写成一行 `{"key": ..., "value": ...}` JSON envelope，并按小时滚动专用日志文件：

```json
{
  "server": {
    "usage_reporter": {
      "enabled": true,
      "extractors": ["memory_usage"],
      "sinks": [
        {
          "type": "file_log",
          "config": {
            "path": "/var/log/openviking_usage/usage.log",
            "resource_id_env": "OV_RESOURCE_ID",
            "rotation_interval_hours": 1,
            "backup_count": 168
          }
        }
      ]
    }
  }
}
```

内置 `file_log` Sink 替代了此前的 `http` Sink。原来使用
`"type": "http"` 的部署需要迁移为 `file_log` 并采集专用日志文件，或配置实现
原投递协议的 `custom` Sink。

启动服务前，需要设置 `resource_id_env` 指定的环境变量。Sink 会自动创建父目录、立即追加事件、按 UTC 每小时滚动文件，并保留 `backup_count` 个历史文件；它不会写入 OpenViking 默认 stdout 日志。

每行是包含 `key` 和 `value` 字段的 JSON envelope。`key` 与原 Kafka 消息键一致，格式为 `resource_id|account_id|user_id|resource_uri`；`resource_uri` 为空时使用 `session_id`。`value` 是原 Kafka 消息的完整对象，包含 `count_name`、`op_type`、`amount`、`timestamp`、`unique_id`、`tags`、`extra` 和 `prefix`。JSON envelope 能完整保留 key 内部的分隔符。文件采集和下游投递仍为 best-effort，消费端应按 `value.unique_id` 去重。

支持的 add target URI：

- `resource_uri` 作为 `add_resource` 的默认父目录使用，等价于 `parent=<uri>, create_parent=true`。它必须是当前请求用户可写的 resource 目录 URI，支持 `viking://resources` 或 `viking://resources/...`、`viking://user/resources` 或 `viking://user/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://user/...` 短写会按请求用户解析。
- `skill_uri` 作为 `add_skill` 的默认目标根目录使用。v1 只允许 `viking://user/skills` 和 `viking://agent/skills`；不支持显式写成 `viking://user/{user_id}/skills`。

启动方式和部署详情见 [服务部署](./03-deployment.md)，认证详情见 [认证](./04-authentication.md)。

<a id="encryption"></a>

## encryption 段

启用静态数据加密，确保多租户环境下的数据安全与隔离。加密功能对用户完全透明，API 无变化。

```json
{
  "encryption": {
    "enabled": true,
    "provider": "local|vault|volcengine_kms"
  }
}
```

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `enabled` | bool | 是否启用加密 | `false` |
| `provider` | str | 密钥提供程序：`"local"`、`"vault"` 或 `"volcengine_kms"` | - |
| `api_key_hashing.enabled` | bool | 是否对 API key 字段启用 Argon2id 单向哈希（与文件级 `enabled` 独立控制），详见 [加密指南](./08-encryption.md) | `false` |

### Local（本地文件）

适合开发环境和单节点部署：

```json
{
  "encryption": {
    "enabled": true,
    "provider": "local",
    "local": {
      "key_file": "~/.openviking/master.key"
    }
  }
}
```

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `local.key_file` | str | 根密钥文件路径 | `~/.openviking/master.key` |

### Vault（HashiCorp Vault）

适合生产环境和多云部署：

```json
{
  "encryption": {
    "enabled": true,
    "provider": "vault",
    "vault": {
      "address": "https://vault.example.com:8200",
      "token": "vault-token-xxx",
      "mount_point": "transit",
      "key_name": "openviking-root"
    }
  }
}
```

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `vault.address` | str | Vault 服务地址 | - |
| `vault.token` | str | Vault 访问令牌 | - |
| `vault.mount_point` | str | Transit 引擎挂载点 | `"transit"` |
| `vault.key_name` | str | 根密钥名称 | `"openviking-root"` |

### Volcengine KMS（火山引擎）

适合火山引擎云部署：

```json
{
  "encryption": {
    "enabled": true,
    "provider": "volcengine_kms",
    "volcengine_kms": {
      "key_id": "kms-key-id-xxx",
      "region": "cn-beijing",
      "access_key": "AKLTxxxxxxxx",
      "secret_key": "Tmpxxxxxxxx"
    }
  }
}
```

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `volcengine_kms.key_id` | str | KMS 密钥 ID | - |
| `volcengine_kms.region` | str | 区域 | `"cn-beijing"` |
| `volcengine_kms.access_key` | str | 火山引擎 Access Key | - |
| `volcengine_kms.secret_key` | str | 火山引擎 Secret Key | - |

加密功能的详细说明见 [数据加密](../concepts/10-encryption.md)，完整使用流程见 [加密指南](./08-encryption.md)。

## storage.transaction 段

`storage.transaction` 已废弃，仅保留为兼容旧配置。新配置请使用 `storage.agfs.pathlock`。若旧字段仍然出现，OpenViking 会在运行时给出 warning；其中 `lock_timeout` 和 `lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置，`redo_recovery_enabled` 则会被忽略。

推荐写法：

```json
{
  "storage": {
    "agfs": {
      "pathlock": {
        "lock_timeout_secs": 5.0,
        "lock_expire_secs": 1800.0
      }
    }
  }
}
```

兼容旧写法（不推荐新项目继续使用）：

```json
{
  "storage": {
    "transaction": {
      "lock_timeout": 5.0,
      "lock_expire": 1800.0
    }
  }
}
```

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `lock_timeout` | float | 已废弃。改用 `storage.agfs.pathlock.lock_timeout_secs`。未显式配置新字段时会自动映射。 | `0.0` |
| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。未显式配置新字段时会自动映射。 | `1800.0` |
| `redo_recovery_enabled` | bool | 已废弃且忽略。当前版本的 `session.commit` phase-2 恢复由持久化 `session_commit` 队列负责。 | `true` |

路径锁机制的详细说明见 [路径锁与崩溃恢复](../concepts/09-transaction.md)。

## Task Tracker 持久化

任务跟踪器记录异步任务状态，适用于返回 `task_id` 的接口（任务类型包括 `session_commit`、`add_resource`、`add_skill`、`admin_reindex`）。Task 记录始终持久化到 AGFS，因此一个实例返回的 `task_id` 可以在另一个实例上查询，任务历史也能在重启后继续访问。

无需配置 `storage.task_tracker`。如果旧配置里仍包含 `storage.task_tracker`，OpenViking 会记录 warning 并忽略它。

Task 记录文件位于所属账号的系统目录：

```text
/local/{account_id}/_system/tasks/{user_id}/{task_id}.json
```

## 完整 Schema

```json
{
  "embedding": {
    "max_concurrent": 10,
    "max_retries": 3,
    "text_source": "content_only",
    "max_input_tokens": 4096,
    "dense": {
      "provider": "volcengine",
      "api_key": "string",
      "model": "string",
      "dimension": 1024,
      "input": "multimodal",
      "encoding_format": "float|base64"
    }
  },
  "vlm": {
    "provider": "string",
    "api_key": "string",
    "model": "string",
    "api_base": "string",
    "thinking": false,
    "max_concurrent": 64,
    "max_retries": 3,
    "extra_headers": {},
    "extra_request_body": {},
    "stream": false
  },
  "rerank": {
    "provider": "volcengine|openai",
    "api_key": "string",
    "model": "string",
    "api_base": "string",
    "max_input_tokens": 0,
    "threshold": 0.1,
    "extra_headers": {}
  },
  "retrieval": {
    "hotness_alpha": 0.0,
    "score_propagation_alpha": 1.0
  },
  "encryption": {
    "enabled": false,
    "provider": "local|vault|volcengine_kms",
    "local": {
      "key_file": "~/.openviking/master.key"
    },
    "vault": {
      "address": "https://vault.example.com:8200",
      "token": "string",
      "mount_point": "transit",
      "key_name": "openviking-root"
    },
    "volcengine_kms": {
      "key_id": "string",
      "region": "cn-beijing",
      "access_key": "string",
      "secret_key": "string"
    }
  },
  "storage": {
    "workspace": "string",
    "agfs": {
      "backend": "local|s3|memory",
      "timeout": 10
    },
    "transaction": {
      "lock_timeout": 0.0,
      "lock_expire": 300.0
    },
    "vectordb": {
      "backend": "local|remote",
      "url": "string",
      "project": "string"
    }
  },
  "server": {
    "host": "string",
    "port": 1933,
    "root_api_key": "string",
    "cors_origins": ["string"]
  }
}
```

说明：
- `storage.vectordb.sparse_weight` 用于混合（dense + sparse）索引/检索的权重，仅在使用 hybrid 索引时生效；设置为 > 0 才会启用 sparse 信号。

## 故障排除

### API Key 错误

```
Error: Invalid API key
```

检查 API Key 是否正确且有相应权限。

### 维度不匹配

```
Error: Vector dimension mismatch
```

确保配置中的 `dimension` 与模型输出维度匹配。

### VLM 超时

```
Error: VLM request timeout
```

- 检查网络连接
- 增加配置中的超时时间
- 对偶发超时，适当增大 `vlm.max_retries`
- 尝试更小的模型
- 如为批量导入场景，结合降低 `vlm.max_concurrent`

### 速率限制

```
Error: Rate limit exceeded
```

火山引擎有速率限制。考虑批量处理时添加延迟或升级套餐。
- 优先降低 `embedding.max_concurrent` / `vlm.max_concurrent`
- 对偶发 `429` 可保留少量 `max_retries`；若希望快速失败，可将其设为 `0`

## 相关文档

- [火山引擎购买指南](./02-volcengine-purchase-guide.md) - API Key 获取
- [API 概览](../api/01-overview.md) - 客户端初始化
- [服务部署](./03-deployment.md) - Server 配置
- [上下文层级](../concepts/03-context-layers.md) - L0/L1/L2