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

# 使用 TOS 向量库存储

`tos_vector` 后端使用火山引擎 TOS（对象存储）的**向量桶**作为向量存储。知识文本在本地经 embedding 模型向量化后，写入 TOS 向量索引，检索时按余弦相似度召回。首次使用时会自动创建向量桶与索引（若不存在）。

## 何时使用

* 已开通火山引擎账号，希望使用 TOS 向量桶托管向量数据；
* 需要持久化的向量存储，同时保留在本地控制 embedding 的能力。

## 依赖

```bash lines theme={null}
pip install "veadk-python[extensions]"
```

## 使用示例

运行前配置 `MODEL_EMBEDDING_NAME`、`MODEL_EMBEDDING_DIM`、`MODEL_EMBEDDING_API_BASE` 与 `MODEL_EMBEDDING_API_KEY`。`extensions` 包含 llama-index、embedding 适配器及向量存储连接器；模型文本会发送到配置的 embedding 服务。使用 BytePlus 或其他模型服务时应显式设置匹配的地址、模型与凭证，火山方舟默认地址不会自动切换

同时提供火山引擎 AK/SK、账号 ID、向量桶名称与服务区域。初始化会创建或访问向量桶与索引，需相应权限且可能产生费用；资料内容与向量会发送到 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("公司的标准年假为每年 15 天，入职满一年起享受。")
for entry in kb.search("年假", top_k=3):
    print(entry.content)

agent = Agent(
    name="demo",
    instruction="回答用户问题，必要时用 `load_knowledgebase` 工具检索知识库。",
    knowledgebase=kb,
)
```

也可以通过 `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",
        ),
    },
)
```

## 参数

### KnowledgeBase 参数

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `backend` | `str \| BaseKnowledgebaseBackend` | `"local"` | 本页设为 `tos_vector`；也可传后端实例 |
| `backend_config` | `dict` | `{}` | 非空时必须包含 index；不会自动合并外层 index |
| `index` | `str` | `""` | 索引名称；无配置字典时回退到 app\_name |
| `app_name` | `str` | `""` | index 的回退值，不是检索时的用户权限过滤器 |
| `top_k` | `int` | `10` | 默认检索数量；search(top\_k=0) 使用此值 |
| `name` | `str` | `"user_knowledgebase"` | 向智能体描述的知识库名称 |
| `description` | `str` | `"This knowledgebase stores some user-related information."` | 向智能体说明用途 |
| `enable_profile` | `bool` | `False` | 启用资料画像；需先生成画像文件，普通检索保持关闭 |
| `query_with_user_profile` | `bool` | `False` | 借助智能体绑定的 Viking 长期记忆画像生成查询；不要求知识库本身使用 Viking |

### 构造参数

`backend_config` 支持以下配置项：

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `index` | `str` | 无默认，由 `KnowledgeBase` 传入 | TOS 向量索引名 |
| `volcengine_access_key` | `str \| None` | 读取环境变量 `VOLCENGINE_ACCESS_KEY` | 火山引擎访问密钥 AK |
| `volcengine_secret_key` | `str \| None` | 读取环境变量 `VOLCENGINE_SECRET_KEY` | 火山引擎访问密钥 SK |
| `tos_vector_bucket_name` | `str \| None` | 读取环境变量 `DATABASE_TOS_VECTOR_BUCKET` | TOS 向量桶名 |
| `tos_vector_account_id` | `str \| None` | 读取环境变量 `DATABASE_TOS_VECTOR_ACCOUNT_ID` | 火山引擎账号 ID |
| `tos_vector_config` | `TOSVectorConfig` | 自动从 `DATABASE_TOS_VECTOR_*` 环境变量读取 | TOS 向量客户端配置 |
| `session_token` | `str` | `""` | 此后端不传递该字段；STS 应使用 tos\_vector\_config.security\_token |
| `embedding_config` | `EmbeddingModelConfig` | 自动从 `MODEL_EMBEDDING_*` 环境变量读取 | embedding 模型配置 |

### TOS 向量客户端配置

`tos_vector_config` 为 `TOSVectorConfig`，环境变量前缀 `DATABASE_TOS_VECTOR_`：

| 配置项 | 环境变量 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- | :- |
| `endpoint` | `DATABASE_TOS_VECTOR_ENDPOINT` | `str` | `tosvectors-cn-beijing.volces.com` | TOS 向量服务接入点 |
| `region` | `DATABASE_TOS_VECTOR_REGION` | `str` | `cn-beijing` | 区域。未显式设置时回退到 `REGION` 环境变量，仍为空时默认 `cn-beijing` |
| `security_token` | `DATABASE_TOS_VECTOR_SECURITY_TOKEN` | `str \| None` | `None` | STS 临时凭证令牌 |
| `max_retry_count` | `DATABASE_TOS_VECTOR_MAX_RETRY_COUNT` | `int` | `3` | 最大重试次数 |
| `max_connections` | `DATABASE_TOS_VECTOR_MAX_CONNECTIONS` | `int` | `1024` | 最大连接数 |
| `connection_time` | `DATABASE_TOS_VECTOR_CONNECTION_TIME` | `int` | `10` | 连接超时（秒） |
| `socket_timeout` | `DATABASE_TOS_VECTOR_SOCKET_TIMEOUT` | `int` | `30` | Socket 超时（秒） |
| `enable_verify_ssl` | `DATABASE_TOS_VECTOR_ENABLE_VERIFY_SSL` | `bool` | `true` | 是否校验 SSL 证书 |
| `dns_cache_time` | `DATABASE_TOS_VECTOR_DNS_CACHE_TIME` | `int` | `15` | DNS 缓存时间（秒） |
| `proxy_host` | `DATABASE_TOS_VECTOR_PROXY_HOST` | `str \| None` | `None` | 代理主机 |
| `proxy_port` | `DATABASE_TOS_VECTOR_PROXY_PORT` | `int \| None` | `None` | 代理端口 |
| `proxy_username` | `DATABASE_TOS_VECTOR_PROXY_USERNAME` | `str \| None` | `None` | 代理用户名 |
| `proxy_password` | `DATABASE_TOS_VECTOR_PROXY_PASSWORD` | `str \| None` | `None` | 代理密码 |
| `high_latency_log_threshold` | `DATABASE_TOS_VECTOR_HIGH_LATENCY_LOG_THRESHOLD` | `int` | `100` | 高延迟日志阈值，单位由 TOS SDK 定义 |
| `credentials_provider` | `DATABASE_TOS_VECTOR_CREDENTIALS_PROVIDER` | `object \| None` | `None` | TOS SDK 凭证提供对象，仅在代码中配置 |
| `except100_continue_threshold` | `DATABASE_TOS_VECTOR_EXCEPT100_CONTINUE_THRESHOLD` | `int` | `65536` | 触发 100-continue 的请求体阈值 |
| `user_agent_product_name` | `DATABASE_TOS_VECTOR_USER_AGENT_PRODUCT_NAME` | `str \| None` | `None` | User-Agent 产品名 |
| `user_agent_soft_name` | `DATABASE_TOS_VECTOR_USER_AGENT_SOFT_NAME` | `str \| None` | `None` | User-Agent 软件名 |
| `user_agent_soft_version` | `DATABASE_TOS_VECTOR_USER_AGENT_SOFT_VERSION` | `str \| None` | `None` | User-Agent 软件版本 |
| `user_agent_customized_key_values` | `DATABASE_TOS_VECTOR_USER_AGENT_CUSTOMIZED_KEY_VALUES` | `dict[str, str] \| None` | `None` | 自定义 User-Agent 键值 |

### embedding 配置

`embedding_config` 为 `EmbeddingModelConfig`，环境变量前缀 `MODEL_EMBEDDING_`：

| 配置项 | 环境变量 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- | :- |
| `name` | `MODEL_EMBEDDING_NAME` | `str` | `doubao-embedding-vision-250615` | embedding 模型名 |
| `dim` | `MODEL_EMBEDDING_DIM` | `int` | `2048` | embedding 向量维度，用于创建向量索引；距离度量为余弦相似度 |
| `api_base` | `MODEL_EMBEDDING_API_BASE` | `str` | `https://ark.cn-beijing.volces.com/api/v3/` | embedding 服务的 API 地址 |
| `api_key` | `MODEL_EMBEDDING_API_KEY` | `str` | 依次回退到 `MODEL_AGENT_API_KEY` 或自动获取的 Ark 令牌 | 访问 embedding 服务的密钥 |

## 环境变量配置

```bash lines theme={null}
# 火山引擎凭证与 TOS 向量桶
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 模型
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` 与 `add_from_files` 尚在完善中，处理部分文件（如包含图片的文档）时可能存在缺失。文本注入（`add_from_text`）已可稳定使用。
</Warning>

全局 BytePlus 配置可映射 AK/SK，但此后端不会据此自动切换 TOS 向量服务地址；应显式配置目标服务支持的地址与区域。显式 AK/SK 不提供会话令牌时，设置 `DATABASE_TOS_VECTOR_SECURITY_TOKEN`；外层 `session_token` 无效。已存在索引必须匹配 embedding 维度，更换模型或维度时应新建索引并重新导入

示例检索结果应包含年假规则。若返回为空，先确认写入返回成功、模型维度一致及服务端处理完成，再检查网络与权限；托管后端不保证导入后立即可检索。绑定 Agent 后仍需完成模型配置才能运行问答