> ## 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 Context Search storage

The `context_search` backend integrates with the managed Volcengine Context Search service. Files are uploaded to TOS (object storage) via pre-signed URLs, then registered into a Context Search RAG scene; splitting, embedding, and retrieval all run server-side, so **no local embedding is required**.

## When to use

* You need a managed semantic-search service without maintaining a vector store yourself;
* You have created a RAG scene and a search engine in Volcengine Context Search.

## Prerequisites

* A Volcengine account with a Context Search RAG scene whose scene ID is a numeric string;
* The search engine's Endpoint and API Key (required for retrieval).

## Usage

First set the AK/SK, scene, and engine variables below, and replace the example numeric ID with your actual RAG scene ID. Uploads require scene write permissions; searches require the engine API key. The engine must index the same scene. Data is uploaded for remote processing

```python lines theme={null}
from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

# index is the Context Search scene ID (Scene Id), a numeric string
kb = KnowledgeBase(backend="context_search", index="123456789")
kb.precheck_index_naming()
assert kb.add_from_text("The standard annual leave is 15 days per year, available after one year of service.")
for entry in kb.search("annual leave", top_k=3):
    print(entry.content)

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 engine info explicitly via `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"],
    },
)
```

## Parameters

### KnowledgeBase parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `backend` | `str \| BaseKnowledgebaseBackend` | `"local"` | Set to `context_search` or pass a backend instance |
| `backend_config` | `dict` | `{}` | Must include index when nonempty; does not merge the outer index |
| `index` | `str` | `""` | Index name; falls back to app\_name when no configuration dictionary is supplied |
| `app_name` | `str` | `""` | Fallback for index; not a user authorization filter |
| `top_k` | `int` | `10` | Default result count; search(top\_k=0) uses this value |
| `name` | `str` | `"user_knowledgebase"` | Knowledge-base name shown to the agent |
| `description` | `str` | `"This knowledgebase stores some user-related information."` | Explains the knowledge base to the agent |
| `enable_profile` | `bool` | `False` | Enables document profiles; generate profile files first, or leave disabled for ordinary retrieval |
| `query_with_user_profile` | `bool` | `False` | Uses the agent’s Viking long-term memory profile to guide queries; the knowledge backend itself need not be Viking |

### Constructor parameters

`backend_config` supports the following settings:

| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `index` | `str` | No default; provided by `KnowledgeBase` | Scene ID (Scene Id), a numeric string; used as the scene ID when `context_search_engine_id` is empty. |
| `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). |
| `volcengine_session_token` | `str \| None` | Read from env var `VOLCENGINE_SESSION_TOKEN` | STS temporary-credential token. |
| `context_search_region` | `str \| None` | Read from env var `DATABASE_CONTEXT_SEARCH_REGION`; defaults to `cn-beijing` (`ap-southeast-1` under `byteplus`) | Service region. |
| `context_search_project` | `str \| None` | Read from env var `DATABASE_CONTEXT_SEARCH_PROJECT`; defaults to `default` | Context Search project name. |
| `context_search_engine_id` | `str \| None` | Read from env var `DATABASE_CONTEXT_SEARCH_ENGINE_ID` | Search engine ID; when set, takes precedence as the scene ID. |
| `context_search_engine_endpoint` | `str \| None` | Read from env var `DATABASE_CONTEXT_SEARCH_ENGINE_ENDPOINT` | Search engine endpoint, required for retrieval. |
| `context_search_engine_apikey` | `str \| None` | Read from env var `DATABASE_CONTEXT_SEARCH_ENGINE_APIKEY` | Search engine API key, required for retrieval. |
| `context_search_service` | `str` | `ctxsearch` | Service identifier. |
| `context_search_version` | `str` | `2025-09-01` | API version. |
| `context_search_host` | `str` | `ctxsearch.volcengineapi.com` | API host. Replaced with `byteplusapi.com` under `byteplus`. |
| `context_search_scheme` | `str` | `https` | Request scheme. |

## Environment variables

```bash lines theme={null}
# Volcengine credentials
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>
  Embedding and retrieval both run server-side in Context Search, so this backend requires no embedding model configuration. Ingestion is asynchronous: after files are uploaded, wait for server-side indexing to complete before searching.
</Note>

<Warning>
  `index` (the scene ID) must be a numeric string, otherwise initialization fails; successful construction does not verify the scene; call `kb.precheck_index_naming()` to validate its ID and access permissions. Before retrieval, `context_search_engine_endpoint` and `context_search_engine_apikey` must be set, otherwise `search` fails.
</Warning>

`CLOUD_PROVIDER=byteplus` changes the default region and API host. Global configuration can map BytePlus AK/SK to the fields read by this backend. Explicitly provide STS tokens through `volcengine_session_token` or `VOLCENGINE_SESSION_TOKEN`; the endpoint, credentials, and scene must belong to the same environment. Directory ingestion recursively scans all files; exclude content that should not be uploaded before importing

The example search should return the annual-leave policy. For empty results, check successful ingestion, matching embedding dimensions, completed server processing, network access, and permissions. Managed ingestion may not be immediately searchable. Running the configured Agent also requires model credentials