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

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:

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

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.

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

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

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.

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

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

When to use

Prerequisites

Usage

Parameters

Constructor parameters

TOS config

Retrieval parameters

Environment variables

​When to use

​Prerequisites

​Usage

​Parameters

​Constructor parameters

​TOS config

​Retrieval parameters

​Environment variables

When to use

Prerequisites

Usage

Parameters

Constructor parameters

TOS config

Retrieval parameters

Environment variables