Use TOS Vector storage

The tos_vector backend uses a vector bucket in Volcengine TOS (object storage) as the vector store. Knowledge text is embedded locally by an embedding model, written to a TOS vector index, and retrieved by cosine similarity. On first use, the vector bucket and index are created automatically if they do not exist.

When to use

You have a Volcengine account and want to host vector data in a TOS vector bucket;
You need persistent vector storage while keeping control of embedding locally.

Dependencies

pip install "veadk-python[extensions]"

Usage

from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(backend="tos_vector", 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 credentials and config explicitly via backend_config:

from veadk.knowledgebase import KnowledgeBase
from veadk.configs.database_configs import TOSVectorConfig

kb = KnowledgeBase(
    backend="tos_vector",
    index="company_faq",
    backend_config={
        "index": "company_faq",
        "volcengine_access_key": "your-ak",
        "volcengine_secret_key": "your-sk",
        "tos_vector_bucket_name": "your-vector-bucket",
        "tos_vector_account_id": "your-account-id",
        "tos_vector_config": TOSVectorConfig(
            endpoint="tosvectors-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`	TOS vector index name.
`volcengine_access_key`	`str \| None`	Read from env var `VOLCENGINE_ACCESS_KEY`	Volcengine access key (AK).
`volcengine_secret_key`	`str \| None`	Read from env var `VOLCENGINE_SECRET_KEY`	Volcengine secret key (SK).
`tos_vector_bucket_name`	`str \| None`	Read from env var `DATABASE_TOS_VECTOR_BUCKET`	TOS vector bucket name.
`tos_vector_account_id`	`str \| None`	Read from env var `DATABASE_TOS_VECTOR_ACCOUNT_ID`	Volcengine account ID.
`tos_vector_config`	`TOSVectorConfig`	Read automatically from `DATABASE_TOS_VECTOR_*` env vars	TOS vector client config.
`session_token`	`str`	`""`	STS temporary-credential token.
`embedding_config`	`EmbeddingModelConfig`	Read automatically from `MODEL_EMBEDDING_*` env vars	Embedding model config.

TOS vector client config

tos_vector_config is a TOSVectorConfig with env prefix DATABASE_TOS_VECTOR_ (common fields shown):

Field	Env var	Type	Default	Description
`endpoint`	`DATABASE_TOS_VECTOR_ENDPOINT`	`str`	`tosvectors-cn-beijing.volces.com`	TOS vector service endpoint.
`region`	`DATABASE_TOS_VECTOR_REGION`	`str`	`cn-beijing`	Region. Falls back to the `REGION` environment variable when not explicitly set, then defaults to `cn-beijing`.
`security_token`	`DATABASE_TOS_VECTOR_SECURITY_TOKEN`	`str \| None`	`None`	STS temporary-credential token.
`max_retry_count`	`DATABASE_TOS_VECTOR_MAX_RETRY_COUNT`	`int`	`3`	Maximum retry count.
`max_connections`	`DATABASE_TOS_VECTOR_MAX_CONNECTIONS`	`int`	`1024`	Maximum connections.
`connection_time`	`DATABASE_TOS_VECTOR_CONNECTION_TIME`	`int`	`10`	Connection timeout (seconds).
`socket_timeout`	`DATABASE_TOS_VECTOR_SOCKET_TIMEOUT`	`int`	`30`	Socket timeout (seconds).
`enable_verify_ssl`	`DATABASE_TOS_VECTOR_ENABLE_VERIFY_SSL`	`bool`	`true`	Whether to verify the SSL certificate.
`dns_cache_time`	`DATABASE_TOS_VECTOR_DNS_CACHE_TIME`	`int`	`15`	DNS cache time (seconds).

TOSVectorConfig also exposes advanced fields such as proxy settings (proxy_host/proxy_port/proxy_username/proxy_password), high_latency_log_threshold, and user_agent_*; the defaults are usually fine.

Embedding config

embedding_config is an EmbeddingModelConfig with env prefix MODEL_EMBEDDING_:

Field	Env var	Type	Default	Description
`name`	`MODEL_EMBEDDING_NAME`	`str`	`doubao-embedding-vision-250615`	Embedding model name.
`dim`	`MODEL_EMBEDDING_DIM`	`int`	`2048`	Embedding vector dimension; used to create the vector index. Distance metric is cosine similarity.
`api_base`	`MODEL_EMBEDDING_API_BASE`	`str`	`https://ark.cn-beijing.volces.com/api/v3/`	API base of the embedding service.
`api_key`	`MODEL_EMBEDDING_API_KEY`	`str`	Falls back to `MODEL_AGENT_API_KEY`, then an auto-fetched Ark token	Key for accessing the embedding service.

Environment variables

# Volcengine credentials and TOS vector bucket
export VOLCENGINE_ACCESS_KEY="your-ak"
export VOLCENGINE_SECRET_KEY="your-sk"
export DATABASE_TOS_VECTOR_BUCKET="your-vector-bucket"
export DATABASE_TOS_VECTOR_ACCOUNT_ID="your-account-id"
export DATABASE_TOS_VECTOR_ENDPOINT="tosvectors-cn-beijing.volces.com"
export DATABASE_TOS_VECTOR_REGION="cn-beijing"

# Embedding model
export MODEL_EMBEDDING_NAME="doubao-embedding-vision-250615"
export MODEL_EMBEDDING_DIM=2048
export MODEL_EMBEDDING_API_KEY="your-ark-api-key"

add_from_directory and add_from_files are still being refined and may have gaps when handling some files (e.g., documents containing images). Text ingestion (add_from_text) is stable.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

When to use

Dependencies

Usage

Parameters

Constructor parameters

TOS vector client config

Embedding config

Environment variables