> ## 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.

# Use VikingDB storage

The `viking` backend integrates with the managed VikingDB knowledge base service. Files are first uploaded to TOS (object storage), then registered into a VikingDB collection; splitting, embedding, and retrieval all run server-side, so **no local embedding is required**. It is the recommended backend for production.

## When to use

* You need a managed, ready-to-use knowledge base service without maintaining a vector store yourself;
* You want server-side splitting, embedding, and reranking;
* You need metadata-filtered retrieval.

## Prerequisites

* A Volcengine or BytePlus account with a VikingDB knowledge base created;
* A TOS bucket for uploading files;
* On first use, the backend automatically creates the target collection if it does not exist.

## Usage

```python lines theme={null}
from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

# index must start with a letter, contain only letters/digits/underscores, length 1-128
kb = KnowledgeBase(backend="viking", index="company_faq")
kb.add_from_text("The standard annual leave is 15 days per year, available after one year of service.")

agent = Agent(
    name="demo",
    instruction="Answer the user; when needed, use the `load_knowledgebase` tool to search the knowledge base.",
    knowledgebase=kb,
)
```

You can also pass project and credentials explicitly via `backend_config`:

```python lines theme={null}
from veadk.knowledgebase import KnowledgeBase
from veadk.configs.database_configs import TOSConfig

kb = KnowledgeBase(
    backend="viking",
    index="company_faq",
    backend_config={
        "index": "company_faq",
        "volcengine_access_key": "your-ak",
        "volcengine_secret_key": "your-sk",
        "volcengine_project": "default",
        "version": "2",
        "tos_config": TOSConfig(
            endpoint="tos-cn-beijing.volces.com",
            region="cn-beijing",
        ),
    },
)
```

## Parameters

### Constructor parameters

`backend_config` supports the following settings:

| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `index` | `str` | No default; provided by `KnowledgeBase` | VikingDB collection name; must start with a letter, contain only letters/digits/underscores, length 1-128. |
| `volcengine_access_key` | `str \| None` | See below | Access key (AK). Reads `BYTEPLUS_ACCESS_KEY` in `byteplus` mode, otherwise `VOLCENGINE_ACCESS_KEY`. Falls back to VeFaaS IAM temporary credentials when absent. |
| `volcengine_secret_key` | `str \| None` | See below | Secret key (SK). Reads `BYTEPLUS_SECRET_KEY` in `byteplus` mode, otherwise `VOLCENGINE_SECRET_KEY`. |
| `session_token` | `str` | See below | STS temporary-credential token. Reads `BYTEPLUS_SESSION_TOKEN` in `byteplus` mode, otherwise `VOLCENGINE_SESSION_TOKEN`. |
| `volcengine_project` | `str` | Read from env var `DATABASE_VIKING_PROJECT`, defaults to `default` | VikingDB knowledge base project. |
| `resource_id` | `str` | Read from env var `DATABASE_VIKING_RESOURCE_ID`, defaults to `""` | VikingDB knowledge base resource ID, used for request routing in multi-resource scenarios. Left empty to omit. |
| `version` | `str` | Read from env var `DATABASE_VIKING_VERSION`, defaults to `"2"` | Collection version, either `"2"` or `"4"`. |
| `cloud_provider` | `str` | Read from env var `CLOUD_PROVIDER`, defaults to `volces` | Cloud provider, `volces` or `byteplus`; determines the endpoint and default region. |
| `region` | `str` | Derived from `cloud_provider` (`cn-beijing` for `volces`, `cn-hongkong` for `byteplus`), overridable via `DATABASE_VIKING_REGION` | Service region. In `volces` mode, when not set explicitly it reads `DATABASE_VIKING_REGION` and then `REGION`, defaulting to `cn-beijing` if neither is set. In `byteplus` mode, an unset or Chinese-mainland region (`cn-beijing`, `cn-shanghai`, `cn-guangzhou`) is automatically mapped to `cn-hongkong`; other regions are used as-is. |
| `base_url` | `str` | Derived from `region` and `cloud_provider` | Knowledge base API base URL, overridable via `DATABASE_VIKING_BASE_URL`. |
| `host` | `str` | Derived from `region` and `cloud_provider` | Knowledge base API host. |
| `schema` | `str` | `https` | Request scheme. |
| `tos_config` | `TOSConfig` | Read automatically from `DATABASE_TOS_*` env vars | TOS config used for uploading files. |

<Note>
  Credential resolution checks `AGENTKIT_CLOUD_PROVIDER` and then `CLOUD_PROVIDER` to determine the cloud provider. When set to `byteplus`, credentials are read from `BYTEPLUS_ACCESS_KEY`, `BYTEPLUS_SECRET_KEY`, and `BYTEPLUS_SESSION_TOKEN`; otherwise from `VOLCENGINE_ACCESS_KEY`, `VOLCENGINE_SECRET_KEY`, and `VOLCENGINE_SESSION_TOKEN`.
</Note>

### TOS config

`tos_config` is a `TOSConfig` with env prefix `DATABASE_TOS_`:

| Field | Env var | Type | Default | Description |
| :- | :- | :- | :- | :- |
| `endpoint` | `DATABASE_TOS_ENDPOINT` | `str` | `tos-cn-beijing.volces.com` | TOS endpoint. When not explicitly configured, if `region` is set explicitly or resolved from `REGION`, the endpoint is derived as `tos-<region>.volces.com`. Under `byteplus`, when not explicitly configured, it is automatically aligned with the knowledge base region (e.g., `tos-cn-hongkong.bytepluses.com` when the region is `cn-hongkong`). |
| `region` | `DATABASE_TOS_REGION` | `str` | `cn-beijing` | TOS region. In `volces` mode, when not set explicitly it falls back to the `REGION` environment variable and then the default `cn-beijing`. Under `byteplus`, when not explicitly configured, it is automatically aligned with the knowledge base region. |
| `bucket` | `DATABASE_TOS_BUCKET` | `str` | `veadk-default-bucket` | TOS bucket name. When empty, the default bucket is used and created automatically. |

<Note>
  Under `byteplus`, the TOS region and endpoint are resolved in the following priority: an explicitly passed `tos_config` takes precedence; otherwise `DATABASE_TOS_REGION` and `DATABASE_TOS_ENDPOINT` environment variables are used; if neither is set, the TOS region and endpoint are automatically aligned with the knowledge base region. TOS bucket creation also uses the aligned region.
</Note>

### Retrieval parameters

Besides `query` and `top_k`, the `search` method also supports:

| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `metadata` | `dict \| None` | `None` | Filter retrieval by document metadata; all key-value pairs must match. |
| `rerank` | `bool` | `True` | Whether to enable server-side reranking. |

## Environment variables

```bash lines theme={null}
# Volcengine credentials
export VOLCENGINE_ACCESS_KEY="your-ak"
export VOLCENGINE_SECRET_KEY="your-sk"

# VikingDB knowledge base
export DATABASE_VIKING_PROJECT="default"
export DATABASE_VIKING_VERSION="2"
export DATABASE_VIKING_REGION="cn-beijing"

# TOS bucket used for file uploads
export DATABASE_TOS_BUCKET="your_bucket_name"
export DATABASE_TOS_ENDPOINT="tos-cn-beijing.volces.com"
export DATABASE_TOS_REGION="cn-beijing"
```

<Note>
  Embedding, splitting, and retrieval all run server-side in VikingDB, so this backend requires no embedding model configuration. Profile-related features such as `enable_profile` and `query_with_user_profile` also depend on the Viking family of backends.
</Note>

<Warning>
  `index` (the collection name) must start with a letter, contain only letters, digits, and underscores, and be 1-128 characters long; otherwise initialization fails. `version` supports only `"2"` or `"4"`.
</Warning>