> ## 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 Volcengine 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 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` | Read from env var `VOLCENGINE_ACCESS_KEY` | Volcengine access key (AK). Falls back to vefaas IAM temporary credentials when absent. |
| `volcengine_secret_key` | `str \| None` | Read from env var `VOLCENGINE_SECRET_KEY` | Volcengine secret key (SK). |
| `session_token` | `str` | `""` | STS temporary-credential token. |
| `volcengine_project` | `str` | Read from env var `DATABASE_VIKING_PROJECT`, defaults to `default` | VikingDB knowledge base project. |
| `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. |
| `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. |

### 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. Switches to `tos-ap-southeast-1.bytepluses.com` under `byteplus`. |
| `region` | `DATABASE_TOS_REGION` | `str` | `cn-beijing` | TOS region. Switches to `ap-southeast-1` under `byteplus`. |
| `bucket` | `DATABASE_TOS_BUCKET` | `str` | `veadk-default-bucket` | TOS bucket name. When empty, the default bucket is used and created automatically. |

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