> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 OpenViking 存储

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

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

## 依赖

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

```bash lines theme={null}
pip install veadk-python
```

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

```bash lines theme={null}
export DATABASE_OPENVIKING_URL="https://openviking.example.com"
export DATABASE_OPENVIKING_API_KEY="your-openviking-api-key"
```

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

## 使用示例

```python lines theme={null}
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`：

```python lines theme={null}
kb = KnowledgeBase(
    backend="openviking",
    index="product_docs",
)
kb.add_from_directory("./docs")
```

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

```python lines theme={null}
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 遥测。 |