使用 TOS 向量库存储

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

何时使用

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

依赖

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

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 显式传入凭证与配置：

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 服务的密钥

环境变量配置

# 火山引擎凭证与 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"

add_from_directory 与 add_from_files 尚在完善中，处理部分文件（如包含图片的文档）时可能存在缺失。文本注入（add_from_text）已可稳定使用。

全局 BytePlus 配置可映射 AK/SK，但此后端不会据此自动切换 TOS 向量服务地址；应显式配置目标服务支持的地址与区域。显式 AK/SK 不提供会话令牌时，设置 DATABASE_TOS_VECTOR_SECURITY_TOKEN；外层 session_token 无效。已存在索引必须匹配 embedding 维度，更换模型或维度时应新建索引并重新导入示例检索结果应包含年假规则。若返回为空，先确认写入返回成功、模型维度一致及服务端处理完成，再检查网络与权限；托管后端不保证导入后立即可检索。绑定 Agent 后仍需完成模型配置才能运行问答

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

何时使用

依赖

使用示例

参数

KnowledgeBase 参数

构造参数

TOS 向量客户端配置

embedding 配置

环境变量配置

​何时使用

​依赖

​使用示例

​参数

​KnowledgeBase 参数

​构造参数

​TOS 向量客户端配置

​embedding 配置

​环境变量配置

何时使用

依赖

使用示例

参数

KnowledgeBase 参数

构造参数

TOS 向量客户端配置

embedding 配置

环境变量配置