使用 Context Search 存储

context_search 后端对接火山引擎 Context Search 托管检索服务。文件通过预签名地址上传至 TOS（对象存储），再登记进 Context Search 的 RAG 场景，切分、向量化与检索均在服务端完成，因此无需本地 embedding。

何时使用

需要托管的语义检索服务，免于自行维护向量库；
已在火山引擎 Context Search 创建 RAG 场景与检索引擎。

前置条件

已开通火山引擎账号并创建 Context Search 的 RAG 场景，其场景 ID 为纯数字字符串；
已获取检索引擎的 Endpoint 与 API Key（检索时必需）。

使用示例

先设置下文 AK/SK、场景与检索引擎环境变量，并把示例中的数字替换为实际 RAG 场景 ID。上传需要场景数据写入权限，查询需要引擎 API Key；引擎应索引同一场景。数据会上传到远端并产生服务端处理

from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

# index 即 Context Search 的场景 ID（Scene Id），须为纯数字字符串
kb = KnowledgeBase(backend="context_search", index="123456789")
kb.precheck_index_naming()
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

kb = KnowledgeBase(
    backend="context_search",
    index="123456789",
    backend_config={
        "index": "123456789",
        "volcengine_access_key": os.environ["VOLCENGINE_ACCESS_KEY"],
        "volcengine_secret_key": os.environ["VOLCENGINE_SECRET_KEY"],
        "context_search_project": "default",
        "context_search_engine_endpoint": "https://your-engine-endpoint",
        "context_search_engine_apikey": os.environ["DATABASE_CONTEXT_SEARCH_ENGINE_APIKEY"],
    },
)

参数

KnowledgeBase 参数

参数	类型	默认值	说明
`backend`	`str \| BaseKnowledgebaseBackend`	`"local"`	本页设为 `context_search`；也可传后端实例
`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` 传入	场景 ID（Scene Id），须为纯数字字符串；当 `context_search_engine_id` 为空时作为场景 ID 使用
`volcengine_access_key`	`str \| None`	读取环境变量 `VOLCENGINE_ACCESS_KEY`	火山引擎访问密钥 AK
`volcengine_secret_key`	`str \| None`	读取环境变量 `VOLCENGINE_SECRET_KEY`	火山引擎访问密钥 SK
`volcengine_session_token`	`str \| None`	读取环境变量 `VOLCENGINE_SESSION_TOKEN`	STS 临时凭证令牌
`context_search_region`	`str \| None`	读取环境变量 `DATABASE_CONTEXT_SEARCH_REGION`；缺省 `cn-beijing`（`byteplus` 为 `ap-southeast-1`）	服务区域
`context_search_project`	`str \| None`	读取环境变量 `DATABASE_CONTEXT_SEARCH_PROJECT`；缺省 `default`	Context Search 项目名
`context_search_engine_id`	`str \| None`	读取环境变量 `DATABASE_CONTEXT_SEARCH_ENGINE_ID`	检索引擎 ID，设置后优先作为场景 ID
`context_search_engine_endpoint`	`str \| None`	读取环境变量 `DATABASE_CONTEXT_SEARCH_ENGINE_ENDPOINT`	检索引擎 Endpoint，检索时必需
`context_search_engine_apikey`	`str \| None`	读取环境变量 `DATABASE_CONTEXT_SEARCH_ENGINE_APIKEY`	检索引擎 API Key，检索时必需
`context_search_service`	`str`	`ctxsearch`	服务标识
`context_search_version`	`str`	`2025-09-01`	API 版本
`context_search_host`	`str`	`ctxsearch.volcengineapi.com`	API 主机名。`byteplus` 下自动替换为 `byteplusapi.com`
`context_search_scheme`	`str`	`https`	请求协议

环境变量配置

# 火山引擎凭证
export VOLCENGINE_ACCESS_KEY="your-ak"
export VOLCENGINE_SECRET_KEY="your-sk"

# Context Search
export DATABASE_CONTEXT_SEARCH_PROJECT="default"
export DATABASE_CONTEXT_SEARCH_REGION="cn-beijing"
export DATABASE_CONTEXT_SEARCH_ENGINE_ID="123456789"
export DATABASE_CONTEXT_SEARCH_ENGINE_ENDPOINT="https://your-engine-endpoint"
export DATABASE_CONTEXT_SEARCH_ENGINE_APIKEY="your-engine-apikey"

向量化与检索均在 Context Search 服务端完成，本后端无需配置 embedding 模型。知识注入为异步过程，文件上传后需等待服务端完成索引才可检索。

index（场景 ID）必须为纯数字字符串，否则会报错；初始化成功不代表场景已验证；可先调用 kb.precheck_index_naming() 检查场景格式与访问权限。检索前必须配置 context_search_engine_endpoint 与 context_search_engine_apikey，否则 search 会报错。

CLOUD_PROVIDER=byteplus 调整默认区域与 API 主机，全局配置可将 BytePlus AK/SK 映射为后端读取的凭证。STS 令牌应通过 volcengine_session_token 或 VOLCENGINE_SESSION_TOKEN 显式提供；服务端点、凭证与场景必须属于同一环境。目录导入递归扫描所有文件，导入前排除不应上传的资料示例检索结果应包含年假规则。若返回为空，先确认写入返回成功、模型维度一致及服务端处理完成，再检查网络与权限；托管后端不保证导入后立即可检索。绑定 Agent 后仍需完成模型配置才能运行问答

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

使用 Context Search 存储

何时使用

前置条件

使用示例

参数

KnowledgeBase 参数

构造参数

环境变量配置

​何时使用

​前置条件

​使用示例

​参数

​KnowledgeBase 参数

​构造参数

​环境变量配置

何时使用

前置条件

使用示例

参数

KnowledgeBase 参数

构造参数

环境变量配置