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

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:

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

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

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.

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.

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

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

When to use

Prerequisites

Usage

Parameters

KnowledgeBase parameters

Constructor parameters

Environment variables

​When to use

​Prerequisites

​Usage

​Parameters

​KnowledgeBase parameters

​Constructor parameters

​Environment variables

When to use

Prerequisites

Usage

Parameters

KnowledgeBase parameters

Constructor parameters

Environment variables