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

Before running, configure MODEL_EMBEDDING_NAME, MODEL_EMBEDDING_DIM, MODEL_EMBEDDING_API_BASE, and MODEL_EMBEDDING_API_KEY. The extensions extra includes llama-index, embedding adapters, and vector-store connectors. Text is sent to the configured embedding service. For BytePlus or another provider, explicitly set the matching endpoint, model, and credentials; the default Ark endpoint does not automatically switch Also provide Volcengine AK/SK, account ID, vector-bucket name, and region. Initialization creates or accesses the bucket and index, requires permissions, and may incur charges. Content and vectors are sent to TOS

from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

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

import os

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": os.environ["VOLCENGINE_ACCESS_KEY"],
        "volcengine_secret_key": os.environ["VOLCENGINE_SECRET_KEY"],
        "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

KnowledgeBase parameters

Parameter	Type	Default	Description
`backend`	`str \| BaseKnowledgebaseBackend`	`"local"`	Set to `tos_vector` 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`	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`	`""`	Not forwarded by this backend; use tos_vector_config.security_token for STS
`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_:

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).
`proxy_host`	`DATABASE_TOS_VECTOR_PROXY_HOST`	`str \| None`	`None`	Proxy host
`proxy_port`	`DATABASE_TOS_VECTOR_PROXY_PORT`	`int \| None`	`None`	Proxy port
`proxy_username`	`DATABASE_TOS_VECTOR_PROXY_USERNAME`	`str \| None`	`None`	Proxy username
`proxy_password`	`DATABASE_TOS_VECTOR_PROXY_PASSWORD`	`str \| None`	`None`	Proxy password
`high_latency_log_threshold`	`DATABASE_TOS_VECTOR_HIGH_LATENCY_LOG_THRESHOLD`	`int`	`100`	High-latency log threshold in TOS SDK units
`credentials_provider`	`DATABASE_TOS_VECTOR_CREDENTIALS_PROVIDER`	`object \| None`	`None`	TOS SDK credential provider; configure an object in code
`except100_continue_threshold`	`DATABASE_TOS_VECTOR_EXCEPT100_CONTINUE_THRESHOLD`	`int`	`65536`	Request body threshold for 100-continue
`user_agent_product_name`	`DATABASE_TOS_VECTOR_USER_AGENT_PRODUCT_NAME`	`str \| None`	`None`	User-Agent product name
`user_agent_soft_name`	`DATABASE_TOS_VECTOR_USER_AGENT_SOFT_NAME`	`str \| None`	`None`	User-Agent software name
`user_agent_soft_version`	`DATABASE_TOS_VECTOR_USER_AGENT_SOFT_VERSION`	`str \| None`	`None`	User-Agent software version
`user_agent_customized_key_values`	`DATABASE_TOS_VECTOR_USER_AGENT_CUSTOMIZED_KEY_VALUES`	`dict[str, str] \| None`	`None`	Custom User-Agent key-value pairs

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.

Global BytePlus configuration can map AK/SK, but does not automatically switch this backend’s TOS Vector endpoint. Explicitly configure a supported endpoint and region for the target service. Set DATABASE_TOS_VECTOR_SECURITY_TOKEN for a temporary credential token; the outer session_token has no effect. Existing indexes must match the embedding dimension; create a new index and reimport when changing models or dimensions 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

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

When to use

Dependencies

Usage

Parameters

KnowledgeBase parameters

Constructor parameters

TOS vector client config

Embedding config

Environment variables

​When to use

​Dependencies

​Usage

​Parameters

​KnowledgeBase parameters

​Constructor parameters

​TOS vector client config

​Embedding config

​Environment variables

When to use

Dependencies

Usage

Parameters

KnowledgeBase parameters

Constructor parameters

TOS vector client config

Embedding config

Environment variables