使用 OpenViking 存储

openviking 后端使用 OpenViking 服务解析、索引和检索资源，无需在 VeADK 进程中配置 embedding 模型。每个 index 默认对应 viking://user/<openviking_user_id>/resources/<index>/ 资源目录，其中 openviking_user_id 是资源所属的 owner/context 标识，未配置时为 default。该后端从 VeADK 1.0.3 开始提供。

openviking_user_id 表示 OpenViking 中资源目录与记忆的 owner/context，用于在同一个 OpenViking 服务内隔离不同应用或租户的资源。它与 Runner.user_id（终端用户标识）是不同的概念。

依赖

OpenViking SDK 已包含在 VeADK 的基础依赖中：

pip install veadk-python

准备可访问的 OpenViking 服务和 service owner API Key。生产环境应通过环境变量或密钥管理服务注入凭证：

export DATABASE_OPENVIKING_URL="https://openviking.example.com"
export DATABASE_OPENVIKING_API_KEY="your-openviking-api-key"

导入的文档会发送到配置的 OpenViking 服务。处理个人信息、业务数据或其他敏感内容前，请确认服务部署位置、访问权限和数据保留策略符合要求。

使用示例

from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(
    backend="openviking",
    index="product_docs",
    backend_config={
        "index": "product_docs",
        "url": "https://openviking.example.com",
        "api_key": "填入 OpenViking API Key",
        # 可选；不传时默认 default
        "openviking_user_id": "product_app",
    },
)
kb.add_from_directory("./docs")

agent = Agent(knowledgebase=kb)

未传 backend_config 时，url、api_key 与 openviking_user_id 从 DATABASE_OPENVIKING_* 环境变量读取，index 来自 KnowledgeBase(index=...) 或 app_name：

kb = KnowledgeBase(
    backend="openviking",
    index="product_docs",
)
kb.add_from_directory("./docs")

不再使用知识库时应调用 close() 释放后端持有的 OpenViking 客户端连接：

kb.close()

参数

参数	类型	默认值	说明
`index`	`str`	无	知识库名称，同时用于生成默认资源目录。不能为空。
`openviking_user_id`	`str \| None`	`DATABASE_OPENVIKING_USER_ID` 或 `default`	OpenViking owner/context 标识，用于构建默认资源目录。只允许字母、数字、`.`、`_`、`@`、`-`，不能为 `.` 或 `..`。
`url`	`str \| None`	环境变量配置	OpenViking 服务地址。
`api_key`	`str \| None`	环境变量配置	OpenViking API Key。
`account`	`str \| None`	环境变量配置	OpenViking 账号。
`user`	`str \| None`	环境变量配置	OpenViking 用户。
`actor_peer_id`	`str \| None`	环境变量配置	执行资源操作的身份标识。
`target_uri`	`str \| None`	`viking://user/<openviking_user_id>/resources/<index>/`	导入与检索使用的资源目录。显式配置时直接使用该值。
`wait`	`bool`	`true`	导入资源时是否等待处理完成。
`import_timeout`	`float \| None`	`300`	等待资源导入完成的超时秒数。
`hydrate_results`	`bool`	`true`	是否读取命中资源的完整内容。
`read_limit`	`int`	`200`	读取单个命中资源时的最大内容长度。
`score_threshold`	`float \| None`	`None`	检索结果的最低相关性分数。
`use_context_search`	`bool`	`false`	是否使用 OpenViking 的上下文检索模式。

openviking_user_id 未配置时按 DATABASE_OPENVIKING_USER_ID、OPENVIKING_USER_ID 的顺序查找环境变量，都未配置时使用 default。user_id 作为兼容别名仍可使用，与 openviking_user_id 等效。

环境变量

参数分别对应 DATABASE_OPENVIKING_URL、DATABASE_OPENVIKING_API_KEY、DATABASE_OPENVIKING_USER_ID、DATABASE_OPENVIKING_ACCOUNT、DATABASE_OPENVIKING_USER、DATABASE_OPENVIKING_ACTOR_PEER_ID、DATABASE_OPENVIKING_TARGET_URI、DATABASE_OPENVIKING_WAIT、DATABASE_OPENVIKING_IMPORT_TIMEOUT、DATABASE_OPENVIKING_HYDRATE_RESULTS、DATABASE_OPENVIKING_READ_LIMIT、DATABASE_OPENVIKING_SCORE_THRESHOLD 与 DATABASE_OPENVIKING_USE_CONTEXT_SEARCH。URL、API Key、user ID、account、user、actor peer ID 与目标 URI 也兼容同名的 OPENVIKING_* 环境变量。

操作级覆盖参数

构造参数提供默认行为；下列参数可以在单次导入或检索中通过关键字参数覆盖。

方法	参数	默认值	说明
`add_from_directory`	`target_uri`、`wait`、`timeout`	使用实例配置	覆盖目标目录、等待行为与超时时间。
`add_from_directory`	`strict`、`directly_upload_media`、`preserve_structure`、`telemetry`	`false`、`true`、`true`、`false`	控制严格模式、媒体上传、目录结构保留与遥测。
`add_from_directory`	`ignore_dirs`、`include`、`exclude`、`args`	`None`	控制目录和文件筛选，并传递额外导入参数。
`add_from_directory`	`watch_interval`	`0`	目录监听间隔；`0` 表示不持续监听。
`add_from_files`	`target_uri`、`wait`、`timeout`	使用实例配置	覆盖目标目录、等待行为与超时时间。
`add_from_files`	`strict`、`reason`、`instruction`、`directly_upload_media`、`telemetry`	`false`、`""`、`""`、`true`、`false`	控制单文件导入行为。
`search`	`target_uri`、`score_threshold`、`use_context_search`	使用实例配置	覆盖检索范围、阈值与搜索方式。
`search`	`filter`、`context_type`、`tags`	`None`	向 OpenViking 传递检索过滤条件。
`search`	`session`、`session_id`	`None`	使用上下文搜索时提供会话信息。
`search`	`telemetry`	`false`	是否为本次检索启用 OpenViking 遥测。

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

依赖

使用示例

参数

环境变量

操作级覆盖参数

​依赖

​使用示例

​参数

​环境变量

​操作级覆盖参数

依赖

使用示例

参数

环境变量

操作级覆盖参数