OpenViking

简体中文

English

简体中文

English

外观

llms.txt

配置 ​

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 可以省略。

配置示例 ​

火山引擎（豆包模型）
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"
  }
}
OpenAI 模型
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"
  }
}
火山引擎 Embedding + Codex VLM

使用 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"
  }
}
火山引擎 Embedding + Kimi Coding VLM
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。

火山引擎 Embedding + GLM Coding Plan VLM
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 这类支持视觉输入的模型。

配置部分 ​

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_concurrentint最大并发 Embedding 请求数（embedding.max_concurrent，默认：10）
max_retriesintEmbedding provider 瞬时错误的最大重试次数（embedding.max_retries，默认：3；0 表示禁用重试）
text_sourcestr文本文件向量化时使用的文本来源。content_only 读取原文内容；summary_first 优先使用摘要，没有摘要时回退到原文；summary_only 只使用摘要。默认：content_only
max_input_tokensint使用原文内容向量化时，发送给 embedding 模型的最大估算 token 数。默认：4096
providerstr"openai"、"azure"、"volcengine"、"vikingdb"、"jina"、"ollama"、"gemini"、"voyage"、"dashscope"、"minimax"、"cohere"、"litellm" 或 "local"
api_keystrAPI Key
modelstr模型名称
dimensionint向量维度
inputstr输入类型："text" 或 "multimodal"
batch_sizeint批量请求大小
encoding_formatstr（仅 OpenAI / Azure）Embedding 值的传输格式："float" 或 "base64"。留空时使用 OpenAI Python SDK 默认值；当上游网关无法正确处理 base64 embedding payload 时，可设置为 "float"。
extra_bodyobject（仅 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_thresholdint连续失败多少次后熔断（默认：5）
circuit_breaker.reset_timeoutfloat基础恢复等待时间（秒，默认：60）
circuit_breaker.max_reset_timeoutfloat指数退避后的最大恢复等待时间（秒，默认：600）

可用模型

模型维度输入类型说明
doubao-embedding-vision-2512151024multimodal推荐
doubao-embedding-2506151024text仅文本

使用 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 上提供 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-v31024text针对中文优化
text-embedding-v41024text针对中文优化
tongyi-embedding-vision-plus1152multimodal支持通过 enable_fusion 启用融合向量
tongyi-embedding-vision-flash768multimodal更快，成本更低
qwen3-vl-embedding2560multimodal文本 + 图像 + 视频
qwen2.5-vl-embedding1024multimodal文本 + 图像 + 视频

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

参数类型默认值说明
input_typestr"multimodal" 或 "text"嵌入模式（默认: "multimodal"）
enable_fusionboolfalse为 tongyi-embedding-vision-* 模型启用融合向量
res_levelint2图像分辨率级别（1=高，2=中，3=低）
max_video_framesint16视频最大嵌入帧数

端点选择 — 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_keystrAPI Key。openai-codex 在 Codex OAuth 可用时可省略；使用 provider 原生凭据的 litellm 路由也可省略
forward_api_keybool仅 LiteLLM 使用。覆盖是否把 api_key 透传给 LiteLLM。默认情况下，OpenViking 不会把占位 key 透传给 bedrock/、sagemaker/、vertex_ai/ 等 AWS/GCP 原生鉴权路由；如果明确使用 LiteLLM 的 Bedrock bearer-token API-key 鉴权，可设为 true
modelstr模型名称
api_basestrAPI 端点（可选）
thinkingbool启用思考模式（仅对部分火山模型生效，默认：false）
max_concurrentint语义处理阶段 LLM 最大并发调用数（默认：64）
max_retriesintVLM provider 瞬时错误的最大重试次数（默认：3；0 表示禁用重试）
credentialsarray有序 VLM 凭据/模型列表，索引 0 优先级最高。每项可单独覆盖 provider、model、api_key、api_base、api_version、extra_headers、extra_request_body 和 stream
failback_timeout_secondsfloat切换到低优先级 credential 后，尝试逐级切回的时间阈值（默认：600）
failback_request_countint低优先级 credential 成功处理多少次请求后尝试逐级切回（默认：50）
backupobject可选的备用 VLM 配置（结构与 vlm 相同），当主 VLM 遇到限流、5xx、超时或连接失败等可重试错误时自动切换。仅支持 1 层备用 — 备用 VLM 本身不能再嵌套 backup
timeoutfloat单次 VLM API 请求的 HTTP 超时时间（秒），传递给底层 OpenAI/LiteLLM 客户端。慢端点（如 DashScope、本地推理）可调大。必须 > 0（默认：600.0）
extra_headersobject兼容 HTTP provider 的自定义请求头。kimi 默认已注入所需订阅请求头，也支持在这里覆盖或扩展
extra_request_bodyobject传给 OpenAI 兼容 completion 请求的额外 JSON body 字段，可用于 Ollama {"think": false} 等 provider 专有参数
streambool启用流式模式（OpenAI 兼容 provider 可用，默认：false）
mediaobject音视频运行参数；音视频理解复用该 VLM 的 provider、模型、凭据、client、超时、重试、请求头、输出 token 限制、故障切换和 token 统计
media.enabledbool启用音视频理解（默认：false）
media.max_concurrentint音视频调用最大并发数（默认：2）
media.file_processing_timeoutfloatProvider 侧媒体预处理最长等待秒数（默认：1800）
media.file_poll_intervalfloatProvider 侧媒体预处理轮询间隔秒数（默认：3）
media.video_fpsfloatProvider 支持时使用的视频采样帧率，范围 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 作为音视频理解模型。它们是可直接采用的推荐示例，并非完整的支持模型列表；方舟会持续更新模型及其输入能力。视频理解的可选模型请参考方舟官方视频输入能力列表，音频理解的可选模型请参考方舟官方音频输入能力列表。如果 model 填写的是 ep-* 推理接入点 ID，请确认该接入点背后的基础模型支持对应的媒体输入。OpenViking 不会在配置加载时校验模型的音频或视频能力。

可接入格式与可理解格式

类型现有 Parser 可接入并保存本版本可由方舟理解
音频MP3、WAV、OGG、FLAC、AAC、M4A、OPUS、AC3MP3、WAV、AAC、M4A
视频MP4、AVI、MOV、MKV、WEBM、FLV、WMV、TSMP4、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 的隐私、留存和计费条款。详见火山方舟官方音频理解文档和视频理解文档。

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。该模型基于 Qwen3.5-0.8B 进行微调，可本地部署，适合用小模型承担检索规划：在闲聊、问候或上下文已足够的场景下拒绝检索，从而减少不必要的记忆注入和 token 消耗；需要检索时，再生成面向 skill、resource、memory 的结构化查询。此前的 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 格式详见资源管理。

json
{
  "feishu": {
    "app_id": "",
    "app_secret": "",
    "domain": "https://open.feishu.cn",
    "max_rows_per_sheet": 1000,
    "max_records_per_table": 1000
  }
}
参数类型说明
app_idstr飞书应用 ID（也可通过 FEISHU_APP_ID 环境变量设置）
app_secretstr飞书应用密钥（也可通过 FEISHU_APP_SECRET 环境变量设置）
domainstr飞书 API 域名。Lark 国际版请设为 https://open.larksuite.com
max_rows_per_sheetint电子表格每个 sheet 最大导入行数（默认 1000）
max_records_per_tableint多维表格每个表最大导入记录数（默认 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 配置字段用于远程代码资源的网络防护和代码托管白名单。提取路线详见 代码骨架提取。

远程资源网络防护 ​

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

字段类型说明默认值
github_domainslist[str]允许的 GitHub 主机（在此添加你的 GitHub Enterprise 主机）["github.com", "www.github.com"]
gitlab_domainslist[str]允许的 GitLab 主机（在此添加你的自建 GitLab 主机）["gitlab.com", "www.gitlab.com"]
azure_devops_domainslist[str]允许的 Azure DevOps 主机["dev.azure.com", "ssh.dev.azure.com", "vs-ssh.visualstudio.com"]
code_hosting_domainslist[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
  }
}

参数

参数类型说明
providerstr"vikingdb"、"cohere" 或 "openai"。省略时基于字段自动识别。
akstrVikingDB Access Key（仅 vikingdb 提供方使用）
skstrVikingDB Secret Key（仅 vikingdb 提供方使用）
model_namestr模型名称（仅 vikingdb 提供方使用，默认：doubao-seed-rerank）
api_keystrAPI Key（用于 openai 或 cohere 提供方）
api_basestr接口地址（用于 openai 提供方）
modelstr模型名称（用于 openai 提供方）
timeoutfloatOpenAI 兼容 provider 的 HTTP 请求超时时间，单位为秒。对于较慢或冷启动的本地 rerank 服务可适当增大。默认：30.0
max_input_tokensint每个 query-document 对发送给 reranker 的最大估算原始文本 token 数；超长输入会保留开头和结尾。0 表示不截断。默认：0
thresholdfloat分数阈值，范围为 0.0 到 1.0。低于此值的结果会被过滤。默认：0.1
extra_headersobject自定义 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_alphafloathotness 分数在最终召回分数中的混合权重。0.0 表示关闭 hotness boost，最终分数等于语义相似度；1.0 表示只使用 hotness。有效范围：0.0 到 1.0。0.0
score_propagation_alphafloat层级检索中，子节点自身分数与父节点传播分数混合时，子节点自身分数的权重。1.0 表示忽略父节点分数（仅使用语义相似度）；0.5 表示与父节点分数等权混合；0.0 表示只使用父节点分数。有效范围：0.0 到 1.0。1.0

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

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

参数类型说明默认值
recall_intent_timeout_sfloat会话感知查询扩展的超时；超时后回退为用户原查询5.0
recall_rewrite_timeout_sfloatdigest 重写的超时；超时后 digest 为空并照常返回 rendered30.0

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

grep ​

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

json
{
  "grep": {
    "engine": "auto",
    "switch_to_remote_threshold": 10000
  }
}
参数类型说明默认值
enginestr搜索引擎模式："auto" 在可用时使用 VikingDB BM25 召回，不可用时回退到本地文件系统搜索；"fs" 强制仅使用本地文件系统搜索。"auto"
switch_to_remote_thresholdint切换到 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）。

根级配置 ​

参数类型说明默认值
workspacestr本地数据存储路径（主要配置）"./data"
skip_process_lockbool是否跳过 storage.workspace 的启动进程锁检查。启用后，OpenViking 不会检查或创建 .openviking.pid 锁文件。false
agfsobjectRAGFS（Rust 实现的 AGFS）配置{}
vectordbobject向量库存储配置{}
json
{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "timeout": 10
    },
    "vectordb": {
      "backend": "local"
    }
  }
}

agfs (RAGFS) ​

参数类型说明默认值
backendstr"local"、"s3" 或 "memory""local"
timeoutfloat请求超时时间（秒）10.0
backupsobject多写存储配置。配置后顶层 backend 作为 primary，backups.items[] 作为 backupnull
redirectsarray多写存储的文件重定向策略。命中后文件写入指定 backup，而不是 primary[]
queuefsobjectQueueFS 配置。控制 /queue 的命名空间模式、后端和运行时参数{ "mode": "shared", "backend": "sqlite", "recover_stale_sec": 0, "busy_timeout_ms": 5000 }
queue_db_pathstr（可选）旧版兼容字段，用于覆盖 QueueFS 的 sqlite 数据库文件路径。已被 storage.agfs.queuefs.db_path 取代。未设置时默认为 {storage.workspace}/_system/queue/queue.db。适用于 workspace 卷不支持 sqlite 的场景（例如某些网络文件系统）null
s3objectS3 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_typestr多写同步模式，支持 "async" 或 "sync""async"
write_ack_countintsync 模式下返回前需要的 backup 确认数全部 backup
write_ack_timeout_msintsync 模式下等待 backup 确认的超时时间，单位毫秒null
write_concurrencyint异步 backup 写入并发上限null
itemsarraybackup backend 列表，每个 item 复用普通 backend 配置并增加 name、operations、excludes、encryption 等字段[]

redirects 常用字段：

参数类型说明默认值
typestr策略类型，支持 "FileExtensionPolicy" 或 "FileOverSizePolicy"必填
extensionsarrayFileExtensionPolicy 使用的扩展名正则列表，例如 ["(pdf|ppt)"][]
max_size_mbintFileOverSizePolicy 使用的文件大小阈值，单位 MBnull
targetarray命中策略后写入的 backup name 列表必填

按文件大小重定向示例：

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

注意：

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

更多配置示例见 多写存储指南。

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

QueueFS Redis 参数：

参数类型说明默认值
modestrRedis 拓扑模式："singleton"、"cluster" 或 "sentinel""singleton"
endpointsarray[str]Singleton 的唯一数据节点、Cluster 初始节点或 Sentinel 节点；仅允许协议、主机和端口，认证与 DB 使用独立字段["redis://127.0.0.1:6379"]
master_namestr（可选）Sentinel master 名称；Sentinel 模式必须配置null
usernamestr（可选）Redis ACL 用户名null
passwordstr（可选）Redis ACL 密码null
sentinel_usernamestr（可选）Sentinel ACL 用户名null
sentinel_passwordstr（可选）Sentinel ACL 密码null
dbintRedis database 编号0
connect_timeout_msintRedis 数据节点物理建连超时，单位毫秒3000
command_timeout_msint命令读写超时，单位毫秒3000
key_prefixstrRedis key 隔离前缀，不能为空；所有 QueueFS key 使用 {key_prefix}:ov:*"default"
tls_enabledbool对 redis:// endpoint 强制启用 TLSfalse
tls_insecure_skip_verifybool跳过 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_enabledbool对未显式传入 auto_commit_policy 的新 session，是否默认开启 auto commit。为 false 时，这类 session 保持关闭false
idle_enabledbool是否启用服务端 idle timeout 自动 commit 调度器。关闭后，不会启动 idle scheduler；但 token / message-count 的即时触发仍然生效false
check_interval_secondsfloatidle scheduler 的检查周期，单位秒，必须大于 060.0
scan_batch_sizeint每个 idle 扫描批次最多并发读取的 session meta 文件数量，必须大于 016
scan_batch_pause_secondsfloatidle 扫描批次之间的可选暂停时间，单位秒，用于降低大量 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。

字段类型默认值上限说明
pending_token_thresholdint1000050000当未提交的 pending token 超过该值（严格大于）时，会在消息写入后触发一次自动 commit。
message_count_thresholdint50500当未提交的 live message 数量超过该值（严格大于）时，会在消息写入后触发一次自动 commit。
idle_timeout_secondsint86400604800有未提交内容的 session 在空闲这么多秒后，进入服务端 idle scheduler 的处理范围。idle 触发的 commit 会归档全部积压消息，并忽略 keep_recent_count。
keep_recent_countint2500阈值触发的自动 commit 后保留（不归档）的最近 live message 数量。idle 超时触发的 commit 会忽略该值并归档所有消息。
min_commit_interval_secondsint0604800两次自动 commit 之间的最小间隔秒数（节流）。

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

S3 后端配置 ​
参数类型说明默认值
bucketstrS3 存储桶名称null
regionstr存储桶所在的 AWS 区域（例如 us-east-1, cn-beijing）null
access_keystrS3 访问密钥 IDnull
secret_keystr与访问密钥 ID 对应的 S3 秘密访问密钥null
endpointstr自定义 S3 端点，对于 MinIO 或 LocalStack 等 S3 兼容服务是必需的。可以填完整 URL（https://... 或 http://...），也可以只填主机名；只填主机名时会根据 use_ssl 自动补 https:// 或 http://null
prefixstr用于命名空间隔离的可选键前缀""
use_sslbool为 S3 连接启用/禁用 SSL（HTTPS）。也用于决定 endpoint 仅填主机名时自动补的协议前缀true
use_path_stylebooltrue 表示对 MinIO 和某些 S3 兼容服务使用 PathStyle；false 表示对 TOS 和某些 S3 兼容服务使用 VirtualHostStyletrue
auto_detect_content_typebool上传时根据 object key / 文件名后缀自动推断 MIME 类型，并写入 S3 对象的 Content-Typefalse
directory_marker_modestr目录 marker 的持久化方式，可选 none、empty、nonempty"empty"
normalize_encoding_charsstr需要在 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
      }
    }
  }
}
PathStyle S3 支持 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": "?#%+@"
      }
    }
  }
}
VirtualHostStyle S3 支持 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": "?#%+@"
      }
    }
  }
}

vectordb ​

向量库存储的配置

参数类型说明默认值
backendstrVectorDB 后端类型: 'local'（基于文件）, 'http'（远程服务）, 'volcengine'（云上 VikingDB）, 'vikingdb'（私有部署）, 'cuvs'（本地存储 + GPU dense search）, 'qdrant' 或 'opengauss'"local"
namestrVectorDB 的集合名称"context"
urlstr'http' 类型的远程服务 URL（例如 'http://localhost:5000'）null
project_namestr项目名称（别名 project）"default"
distance_metricstr向量相似度搜索的距离度量（例如 'cosine', 'l2', 'ip'）"cosine"
dimensionint向量嵌入的维度0
sparse_weightfloat混合向量搜索的稀疏权重，仅在使用混合索引时生效0.0
volcengineobject'volcengine' 类型的 VikingDB 配置-
vikingdbobject'vikingdb' 类型的私有部署配置-
cuvsobjectNVIDIA cuVS 配置，也用于在 'local' 下显式开启显存感知自动模式，参见 cuVS 使用指南-
qdrantobject'qdrant' 类型的 Qdrant 配置-
opengaussobject'opengauss' 原生向量后端配置-

默认使用本地模式

{
  "storage": {
    "vectordb": {
      "backend": "local"
    }
  }
}
volcengine vikingDB 支持火山引擎云上部署的 VikingDB
json
{
  "storage": {
    "vectordb": {
      "name": "context",
      "backend": "volcengine",
      "project": "default",
      "volcengine": {
        "region": "cn-beijing",
        "ak": "your-access-key",
        "sk": "your-secret-key"
      }
  }
}
openGauss

需要 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 分布集合表。

配置文件 ​

OpenViking 使用两个配置文件：

配置文件用途默认路径
ov.confSDK 嵌入模式 + 服务端配置~/.openviking/ov.conf
ovcli.confHTTP 客户端和 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_enabledsession commit 时是否执行长期记忆抽取。true
session_skill_extraction_enabledsession commit 时是否同时抽取可复用 skill 到当前用户的 skill 目录。false
link_enabled记忆抽取是否写入和解析 memory links。false
session_auto_commit服务端 session 自动 commit 的全局控制项。该配置属于 memory 段，不属于 server 段；详见 Session Auto Commit 配置。见上文

ovcli.conf ​

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

如需按步骤配置 CLI，请阅读 OpenViking CLI 配置指南。

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_keyAPI Key 认证（root key 或 user key）null（无认证）
account可选的 trusted 模式 account 身份 headernull
user可选的 trusted 模式 user 身份 headernull
profile是否默认给 HTTP 请求追加 profile=1。对 Python HTTP client 和 ov CLI 都生效；也可通过 CLI 的 --profile 单次开启。是否真正生效还取决于服务端是否开启 server.profile_enabled。false
upload.ignore_dirsadd-resource 默认忽略目录列表（CSV）null
upload.includeadd-resource 默认包含模式（CSV）null
upload.excludeadd-resource 默认排除模式（CSV）null
upload.modePython 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"

详见 服务部署。

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
    }
  }
}
字段类型说明默认值
hoststr绑定地址127.0.0.1
portint绑定端口1933
auth_modestr认证模式："api_key" 或 "trusted"。默认值为 "api_key""api_key"
root_api_keystrRoot API Key。在 api_key 模式下启用多租户认证；在 trusted 模式下它只是可选附加保护，不负责解析普通用户身份null
profile_enabledbool是否允许 HTTP 请求通过 profile=1 开启请求级 cProfile。关闭时服务端会忽略该请求参数；开启后，CLI 可以显示返回的 profile，而 Python HTTP client 默认只触发服务端 profile，不会把顶层 profile 字段自动附着到大多数 SDK 返回值上。false
cors_originslistCORS 允许的来源["*"]
public_base_urlstrMCP add_resource 工具向客户端返回的上传指令里使用的对外可见 base URL。解析顺序：环境变量 OPENVIKING_PUBLIC_BASE_URL → 本字段 → 请求头 X-Forwarded-Host / X-Forwarded-Proto → 请求头 Host → 监听地址兜底。当 server 部署在反向代理后且代理不转发 X-Forwarded-* 时，请显式设置本字段（或环境变量）。null
upload_signed_ttl_secondsintMCP add_resource 为本地文件上传 mint 的一次性 token 的过期时间（秒），走 POST /api/v1/resources/temp_upload?token=...。600（10 分钟）
temp_upload.default_modestrPOST /api/v1/resources/temp_upload 的服务端默认模式（客户端未显式传 upload_mode 时使用）："local"（仅当前实例本地磁盘，单机默认行为）或 "shared"（分布式共享存储，多副本部署可跨实例消费）。"local"
temp_upload.shared_max_size_bytesintshared 模式下接受的最大文件大小（字节）。超过此阈值的请求会在写入对象存储之前被拒绝。536870912（512 MiB）
temp_upload.shared_prefixstr分配 shared temp_file_id 对象时使用的 URI 前缀。"viking://upload"
user_config_defaults.add_targets.resource_uristradd_resource 未传 to 和 parent 时使用的部署级默认资源添加目录。viking://user/... 会按请求用户解析。null
user_config_defaults.add_targets.skill_uristradd_skill 未传 target_uri 时使用的部署级默认技能添加根目录。仅允许 viking://user/skills 和 viking://agent/skills。null
agent_evolution.enabledbool实例级 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。

启动方式和部署详情见 服务部署，认证详情见 认证。

encryption 段 ​

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

json
{
  "encryption": {
    "enabled": true,
    "provider": "local|vault|volcengine_kms"
  }
}
参数类型说明默认值
enabledbool是否启用加密false
providerstr密钥提供程序："local"、"vault" 或 "volcengine_kms"-
api_key_hashing.enabledbool是否对 API key 字段启用 Argon2id 单向哈希（与文件级 enabled 独立控制），详见 加密指南false

Local（本地文件） ​

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

json
{
  "encryption": {
    "enabled": true,
    "provider": "local",
    "local": {
      "key_file": "~/.openviking/master.key"
    }
  }
}
参数类型说明默认值
local.key_filestr根密钥文件路径~/.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.addressstrVault 服务地址-
vault.tokenstrVault 访问令牌-
vault.mount_pointstrTransit 引擎挂载点"transit"
vault.key_namestr根密钥名称"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_idstrKMS 密钥 ID-
volcengine_kms.regionstr区域"cn-beijing"
volcengine_kms.access_keystr火山引擎 Access Key-
volcengine_kms.secret_keystr火山引擎 Secret Key-

加密功能的详细说明见 数据加密，完整使用流程见 加密指南。

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_timeoutfloat已废弃。改用 storage.agfs.pathlock.lock_timeout_secs。未显式配置新字段时会自动映射。0.0
lock_expirefloat已废弃。改用 storage.agfs.pathlock.lock_expire_secs。未显式配置新字段时会自动映射。1800.0
redo_recovery_enabledbool已废弃且忽略。当前版本的 session.commit phase-2 恢复由持久化 session_commit 队列负责。true

路径锁机制的详细说明见 路径锁与崩溃恢复。

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

相关文档 ​

Released under the Apache-2.0 License.

Copyright OpenViking contributors