> ## 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}
import os

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": os.environ["DATABASE_OPENVIKING_API_KEY"],
        # 可选；不传时默认 default
        "openviking_user_id": "product_app",
    },
)
kb.add_from_text("Annual leave is 15 days per year")
for entry in kb.search("annual leave"):
    print(entry.content)

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()
```

## 参数

### KnowledgeBase 参数

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `backend` | `str \| BaseKnowledgebaseBackend` | `"local"` | 本页设为 `openviking`；也可传后端实例 |
| `backend_config` | `dict` | `{}` | 非空时必须包含 index；不会自动合并外层 index |
| `index` | `str` | `""` | 索引名称；无配置字典时回退到 app\_name |
| `app_name` | `str` | `""` | index 的回退值，不是检索时的用户权限过滤器 |
| `top_k` | `int` | `10` | 默认检索数量；search(top\_k=0) 使用此值 |
| `name` | `str` | `"user_knowledgebase"` | 向智能体描述的知识库名称 |
| `description` | `str` | `"This knowledgebase stores some user-related information."` | 向智能体说明用途 |
| `enable_profile` | `bool` | `False` | 启用资料画像；需先生成画像文件，普通检索保持关闭 |
| `query_with_user_profile` | `bool` | `False` | 借助智能体绑定的 Viking 长期记忆画像生成查询；不要求知识库本身使用 Viking |

### 后端配置

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `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_id` | `None` | 使用上下文搜索时提供会话标识 |
| `search` | `telemetry` | `false` | 是否为本次检索启用 OpenViking 遥测 |

使用 `wait=False` 只确认提交导入，不能确认知识已可检索。`hydrate_results=True` 会额外读取命中资源，受 `read_limit` 限制，不保证完整文档全部返回。`Runner.user_id` 不会自动改变知识库的资源目录；面向不同租户时显式配置目录与服务端访问权限

示例检索结果应包含年假规则。若返回为空，先确认写入返回成功、模型维度一致及服务端处理完成，再检查网络与权限；托管后端不保证导入后立即可检索。绑定 Agent 后仍需完成模型配置才能运行问答