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

# 使用 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；引擎应索引同一场景。数据会上传到远端并产生服务端处理

```python lines theme={null}
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` 显式传入凭证与检索引擎信息：

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

## 环境变量配置

```bash lines theme={null}
# 火山引擎凭证
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"
```

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

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

`CLOUD_PROVIDER=byteplus` 调整默认区域与 API 主机，全局配置可将 BytePlus AK/SK 映射为后端读取的凭证。STS 令牌应通过 `volcengine_session_token` 或 `VOLCENGINE_SESSION_TOKEN` 显式提供；服务端点、凭证与场景必须属于同一环境。目录导入递归扫描所有文件，导入前排除不应上传的资料

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