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

```bash lines theme={null}
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

```python lines theme={null}
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`:

```python lines theme={null}
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

```bash lines theme={null}
# 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"
```

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

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