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

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

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

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

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