服务端配置

首次配置建议使用 openviking-server init，保存后运行 openviking-server doctor。

OpenViking 服务端和 Python SDK 嵌入模式读取 ov.conf。默认路径是：

text

~/.openviking/ov.conf

也可以通过环境变量或启动参数指定其他文件：

bash

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf
openviking-server --config /path/to/ov.conf

服务端启动时读取配置。修改模型、检索、存储或 server 配置后，需要重启服务；重启后建议运行 openviking-server doctor。

配置结构

json

{
  "embedding": {},
  "vlm": {},
  "query_planner": {},
  "rerank": {},
  "retrieval": {},
  "storage": {},
  "server": {},
  "memory": {},
  "parsers": {},
  "encryption": {},
  "log": {},
  "telemetry": {}
}

未配置的可选模块使用默认值。ov.conf 不允许未知字段，字段名写错时服务端会拒绝加载。

顶层配置

配置项	类型 / 可选值	默认值	作用
`default_account`	string	`"default"`	SDK 嵌入模式使用的默认账号
`default_user`	string	`"default"`	SDK 嵌入模式使用的默认用户
`embedding`	object	内置本地 Dense 模型	向量化模型和稀疏/混合检索配置；默认使用 `local` / `bge-small-zh-v1.5-f16`
`vlm`	object	空配置	内容理解、摘要和记忆抽取使用的模型；使用相关能力前需要配置可用模型
`query_planner`	object / `null`	`null`	检索意图分析模型；未配置时回退到 `vlm`
`rerank`	object	disabled	检索结果重排模型
`retrieval`	object	见下表	检索排序和意图分析策略
`grep`	object	内置默认值	文本搜索引擎配置
`storage`	object	本地存储	工作目录、文件系统和向量数据库
`queue_workers`	object	见下表	QueueFS 消费 worker 的运行时并发配置
`server`	object	本地开发模式	HTTP 服务、鉴权、上传和可观测性
`memory`	object	见下表	会话提交后的记忆与技能抽取
`parsers`	object	各解析器默认值	PDF、代码、图片、音视频等解析行为
`semantic`	object	内置默认值	abstract 和 overview 的生成限制
`parser_api`	object	disabled	第三方文件解析 API
`connector`	object	disabled	外部 Connector 数据导入服务
`encryption`	object	disabled	文件和敏感字段加密
`git`	object	local	版本管理后端，可使用 `local` 或 `s3`
`log`	object	控制台日志	日志级别、格式和文件输出
`telemetry`	object	disabled	OpenTelemetry trace 上报
`oauth`	object	disabled	MCP OAuth 2.1 配置
`prompts`	object	内置模板	自定义 Prompt 模板目录
`ingest`	object	内置默认值	会话日志导入配置
`output_language_override`	string	`""`	强制摘要和记忆输出语言；空值表示自动识别
`allow_private_networks`	boolean	`false`	是否允许抓取内网或私有地址资源

auto_generate_l0、auto_generate_l1、default_search_mode 和 default_search_limit 是已弃用的兼容字段。旧配置文件仍可加载这些字段，但它们不会影响运行时行为。

模型配置

API 型 embedding、vlm、query_planner 和 rerank 配置会复用部分字段名，但各模块使用独立 schema。请只使用下表中对应模块支持的字段。

json

{
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "model": "doubao-embedding-vision-251215",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "<your-ark-api-key>",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "provider": "volcengine",
    "model": "doubao-seed-2-0-code-preview-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "<your-ark-api-key>",
    "temperature": 0,
    "max_retries": 3,
    "thinking": false
  },
  "query_planner": {
    "provider": "volcengine",
    "model": "doubao-seed-2-0-code-preview-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "<your-ark-api-key>",
    "thinking": false
  },
  "rerank": {
    "provider": "vikingdb",
    "ak": "<your-volcengine-ak>",
    "sk": "<your-volcengine-sk>",
    "host": "api-vikingdb.vikingdb.cn-beijing.volces.com",
    "model_name": "doubao-seed-rerank",
    "model_version": "251028",
    "threshold": 0.1,
    "max_input_tokens": 0
  }
}

字段 / 路径	适用模块	作用
`provider`、`model`、`api_base`、`api_key`	Embedding、VLM、Query Planner、Rerank	模型服务、地址和凭证
`api_version`	Embedding、VLM、Query Planner	Azure 等服务的 API 版本
`extra_headers`	Embedding、VLM、Query Planner、Rerank	附加请求头
`extra_request_body`	VLM、Query Planner	附加的 Completion 请求参数
`extra_body`	`embedding.dense` / `sparse` / `hybrid`	附加的 Embedding 请求参数
`timeout`	VLM、Query Planner、Rerank	单次请求超时，单位为秒
`embedding.max_retries`、`vlm.max_retries`、`query_planner.max_retries`	Embedding、VLM、Query Planner	请求失败重试次数；Rerank 没有 `max_retries` 字段

`embedding.dense`

字段	类型 / 可选值	作用
`provider`	`openai`、`volcengine`、`azure`、`ollama`、`local` 等	Dense Embedding 服务
`dimension`	integer，`> 0`	向量维度，必须与模型输出及已有集合一致
`input`	`"text"` / `"multimodal"`	输入类型
`encoding_format`	`"float"` / `"base64"`	OpenAI 兼容接口的向量编码格式

更换模型或 dimension 可能与已有向量集合不兼容，需要迁移或重建索引。

`rerank`

字段	类型 / 可选值	默认值	作用
`provider`	`vikingdb`、`cohere`、`openai`、`litellm` / `null`	`null`	Rerank 服务类型；省略时根据凭证字段推断
`model`	string / `null`	`null`	OpenAI 兼容或 LiteLLM Rerank 模型
`threshold`	number	`0.1`	判定结果相关的最低分数
`max_input_tokens`	integer；`0` 或 `>= 128`	`0`	每个 query-document pair 的最大估算 token；`0` 表示不截断

Rerank 没有单独的 enabled 字段；配置了对应 provider 所需的凭证后才会启用。

检索配置

json

{
  "retrieval": {
    "hotness_alpha": 0,
    "score_propagation_alpha": 1,
    "enable_intent": true
  }
}

`retrieval`

字段	类型 / 可选值	默认值	作用
`hotness_alpha`	number，`0`–`1`	`0`	热度分数权重；`0` 表示关闭热度加权
`score_propagation_alpha`	number，`0`–`1`	`1`	层级检索时子结果自身分数的权重
`enable_intent`	boolean	`true`	有 `session_id` 时是否进行意图分析和查询规划

Search 和 Find 请求的默认 limit 为 10，可以在每次 API 或 SDK 请求中覆盖。retrieval.enable_intent 控制带 Session 的 Search 是否执行 LLM 查询规划；只有配置了可用的 rerank provider 时才会执行结果重排。

存储配置

json

{
  "storage": {
    "workspace": "./data",
    "skip_process_lock": false,
    "agfs": {
      "backend": "local"
    },
    "vectordb": {
      "backend": "local"
    }
  }
}

`storage`

字段	类型 / 常用值	默认值	作用
`workspace`	path	`"./data"`	OpenViking 工作目录
`agfs.backend`	`local`、`memory`、`s3`	`local`	文件与元数据存储后端
`vectordb.backend`	`local`、`cuvs`、`http`、`volcengine`、`vikingdb`	`local`	向量数据库后端
`vectordb.dimension`	integer	跟随 Embedding	向量集合维度
`skip_process_lock`	boolean	`false`	是否跳过 workspace 进程锁；仅在明确接受并发写风险时启用

远程存储后端还需要配置 endpoint、bucket/collection、鉴权和超时等字段。完整后端示例见配置指南。

队列 Worker 配置

`queue_workers.external_parse`

字段	类型	默认值	说明
`max_concurrent`	integer	`4`	同时消费的完整 ExternalParse 作业数，必须大于 `0`；修改后需重启服务

该配置控制队列作业并发，不等同于 vlm.media.max_concurrent 的音视频 VLM 调用并发，也不限制 Understanding API 的单独 HTTP 请求数。

HTTP 服务配置

json

{
  "server": {
    "host": "127.0.0.1",
    "port": 1933,
    "workers": 1,
    "auth_mode": "dev",
    "cors_origins": ["http://localhost:5173"],
    "profile_enabled": false,
    "temp_upload": {
      "default_mode": "local"
    }
  }
}

`server`

字段	类型 / 可选值	默认值	作用
`host`	IP / hostname	`"127.0.0.1"`	HTTP 监听地址
`port`	integer	`1933`	HTTP 监听端口
`workers`	integer	`1`	服务进程数量
`timeout_keep_alive`	integer（秒）	`5`	空闲 HTTP keep-alive 超时；应调大到超过上游空闲连接寿命
`auth_mode`	`dev`、`api_key`、`trusted` / `null`	`null`	鉴权模式；空值根据 `root_api_key` 自动判断
`root_api_key`	string / `null`	`null`	Root API Key；配置后默认启用 `api_key` 模式
`cors_origins`	string[]	`["*"]`	允许的跨域来源
`profile_enabled`	boolean	`false`	是否允许请求返回性能 profile
`with_bot`	boolean	`false`	是否启用 VikingBot API 代理
`bot_api_url`	URL	`http://localhost:18790`	VikingBot OpenAPI 地址
`public_base_url`	URL / `null`	`null`	外部访问使用的服务基准地址
`upload_signed_ttl_seconds`	integer	`600`	签名上传 URL 有效期
`temp_upload.default_mode`	`"local"` / `"shared"`	`"local"`	临时上传存储模式

文件加密与 API Key 哈希

文件加密和 API Key 哈希在顶层 encryption 中配置，不属于 server：

json

{
  "encryption": {
    "enabled": false,
    "api_key_hashing": {
      "enabled": false
    }
  }
}

字段	类型 / 可选值	默认值	作用
`encryption.enabled`	boolean	`false`	是否启用文件级 AES 加密
`encryption.api_key_hashing.enabled`	boolean	`false`	是否使用 Argon2id 保存 API Key

Provider 和密钥管理配置见加密指南。

鉴权模式

值	使用场景
`dev`	仅监听本机地址的开发环境，不要求 API Key
`api_key`	服务端校验 root/user/admin key
`trusted`	由受信任网关注入 account/user 身份

记忆配置

json

{
  "memory": {
    "custom_templates_dir": "",
    "experimental_memory_switch": false,
    "eager_prefetch": true,
    "prefetch_search_topn": 5,
    "extraction_enabled": true,
    "session_skill_extraction_enabled": false,
    "link_enabled": false,
    "v2_lock_retry_interval_seconds": 0.2,
    "v2_lock_max_retries": 0
  }
}

`memory`

字段	类型 / 可选值	默认值	作用
`custom_templates_dir`	path	`""`	附加的自定义记忆模板目录
`experimental_memory_switch`	boolean	`false`	是否启用实验性记忆模板
`eager_prefetch`	boolean	`true`	是否在抽取前预取并读取记忆内容
`prefetch_search_topn`	integer，`>= 1`	`5`	预取时读取的检索结果数量
`extraction_enabled`	boolean	`true`	session commit 时是否抽取长期记忆
`session_skill_extraction_enabled`	boolean	`false`	是否同时抽取可复用 Skill
`link_enabled`	boolean	`false`	是否生成和解析记忆链接
`v2_lock_retry_interval_seconds`	number，`>= 0`	`0.2`	记忆锁获取失败后的重试间隔
`v2_lock_max_retries`	integer，`>= 0`	`0`	最大重试次数；`0` 表示不限次数

解析器配置

解析器放在 parsers 下：

json

{
  "parsers": {
    "pdf": {},
    "code": {
      "code_summary_mode": "ast",
      "extract_functions": true,
      "extract_classes": true,
      "max_token_limit": 50000
    },
    "image": {},
    "audio": {},
    "video": {},
    "markdown": {},
    "excel": {},
    "html": {},
    "text": {},
    "directory": {},
    "feishu": {
      "domain": "https://open.feishu.cn",
      "max_rows_per_sheet": 1000,
      "max_records_per_table": 1000,
      "download_images": true
    },
    "webfeed": {}
  }
}

配置项	作用
`pdf`	PDF 文本、图片和版面解析
`code`	代码仓库文件类型、忽略规则和安全限制
`image`	图片理解和 OCR
`audio`、`video`	音视频内容解析
`markdown`、`html`、`text`	文本文档分段
`excel`	Excel 工作表解析与分段
`directory`	目录扫描和忽略规则
`feishu`	飞书文档访问与解析
`webfeed`	Sitemap、RSS 和 Atom 导入

各模型 provider、解析器、存储后端和加密后端包含较多专用字段，完整字段表和配置示例见配置指南。

最小示例

json

{
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "model": "doubao-embedding-vision-251215",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "<your-ark-api-key>",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "provider": "volcengine",
    "model": "doubao-seed-2-0-code-preview-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "<your-ark-api-key>",
    "thinking": false
  },
  "storage": {
    "workspace": "./data"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 1933
  }
}

服务端配置 ​

配置结构 ​

顶层配置 ​

模型配置 ​

embedding.dense ​

rerank ​

检索配置 ​

retrieval ​

存储配置 ​

storage ​

队列 Worker 配置 ​

queue_workers.external_parse ​

HTTP 服务配置 ​

server ​

文件加密与 API Key 哈希 ​

鉴权模式 ​

记忆配置 ​

memory ​

解析器配置 ​

最小示例 ​

服务端配置

配置结构

顶层配置

模型配置

`embedding.dense`

`rerank`

检索配置

`retrieval`

存储配置

`storage`

队列 Worker 配置

`queue_workers.external_parse`

HTTP 服务配置

`server`

文件加密与 API Key 哈希

鉴权模式

记忆配置

`memory`

解析器配置

最小示例