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

<Note>
  API key authentication and the associated management-precheck behavior on this page are unreleased Preview features, verified against public source `adcdfdcc6a5a213b249a8caad435b939c01df7f6`. Stable VeADK 1.1.13 does not include them. Install that source before using the API key examples
</Note>

```bash theme={null}
python -m pip install "veadk-python @ git+https://github.com/volcengine/veadk-python.git@adcdfdcc6a5a213b249a8caad435b939c01df7f6"
```

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

Set the AK/SK, project, region, and TOS bucket below first. Initialization may create a collection; ingestion uploads documents for server-side processing. These actions require resource permissions and may incur charges

```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")
assert kb.add_from_text("The standard annual leave is 15 days per year, available after one year of service.")
for entry in kb.search("annual leave", top_k=3):
    print(entry.content)

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

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": os.environ["VOLCENGINE_ACCESS_KEY"],
        "volcengine_secret_key": os.environ["VOLCENGINE_SECRET_KEY"],
        "volcengine_project": "default",
        "version": "2",
        "tos_config": TOSConfig(
            endpoint="tos-cn-beijing.volces.com",
            region="cn-beijing",
        ),
    },
)
```

Search an existing collection using an API key:

```python lines theme={null}
import os

from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(
    backend="viking",
    index="company_faq",
    backend_config={
        "index": "company_faq",
        "api_key": os.environ["DATABASE_VIKING_API_KEY"],
        "volcengine_project": "default",
    },
)
```

## Parameters

### KnowledgeBase parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `backend` | `str \| BaseKnowledgebaseBackend` | `"local"` | Set to `viking` or pass a backend instance |
| `backend_config` | `dict` | `{}` | Must include index when nonempty; does not merge the outer index |
| `index` | `str` | `""` | Index name; falls back to app\_name when no configuration dictionary is supplied |
| `app_name` | `str` | `""` | Fallback for index; not a user authorization filter |
| `top_k` | `int` | `10` | Default result count; search(top\_k=0) uses this value |
| `name` | `str` | `"user_knowledgebase"` | Knowledge-base name shown to the agent |
| `description` | `str` | `"This knowledgebase stores some user-related information."` | Explains the knowledge base to the agent |
| `enable_profile` | `bool` | `False` | Enables document profiles; generate profile files first, or leave disabled for ordinary retrieval |
| `query_with_user_profile` | `bool` | `False` | Uses the agent’s Viking long-term memory profile to guide queries; the knowledge backend itself need not be Viking |

### 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. |
| `api_key` | `str \| None` | Read from env var `DATABASE_VIKING_API_KEY`, defaults to `None` | VikingDB knowledge base API key for searching existing collections. When set, knowledge search uses API key auth; collection management still requires AK/SK or IAM credentials. |
| `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>

<Note>
  When `api_key` is set, knowledge search uses API key auth. If `volcengine_access_key` and `volcengine_secret_key` are not configured, the backend skips collection management precheck (existence check and auto-creation). Creating, deleting, listing collections, and operations such as `add_from_text` / `add_from_files` that upload through TOS still require valid AK/SK or IAM credentials. When both API key and AK/SK are configured, search uses the API key and management uses AK/SK or IAM.
</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"

# Optional: use API key to search existing collections
export DATABASE_VIKING_API_KEY="your-vikingdb-api-key"

# 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. `query_with_user_profile` requires Viking long-term memory on the agent; it does not impose that requirement on the knowledge backend
</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>

The example search should return the annual-leave policy. For empty results, check successful ingestion, matching embedding dimensions, completed server processing, network access, and permissions. Managed ingestion may not be immediately searchable. Running the configured Agent also requires model credentials