Use OpenViking storage

The openviking backend delegates resource parsing, indexing, and retrieval to OpenViking, so VeADK does not need a local embedding model. Each index maps to viking://resources/<index>/ by default. This backend is available in VeADK 1.0.3 and later.

Dependencies

The OpenViking SDK is part of VeADK’s base dependencies:

pip install veadk-python

Prepare a reachable OpenViking service and a service-owner API key. In production, inject credentials through environment variables or a secret manager:

export DATABASE_OPENVIKING_URL="https://openviking.example.com"
export DATABASE_OPENVIKING_API_KEY="your-openviking-api-key"

Imported documents are sent to the configured OpenViking service. Before processing personal, business, or other sensitive data, verify that the service location, access controls, and retention policy meet your requirements.

Example

from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(
    backend="openviking",
    index="product_docs",
    backend_config={
        "index": "product_docs",
        "url": "https://openviking.example.com",
        "api_key": "your-openviking-api-key",
    },
)
kb.add_from_directory("./docs")

agent = Agent(knowledgebase=kb)

Parameters

Parameter	Type	Default	Description
`index`	`str`	None	Knowledge-base name used to build the default resource URI. It cannot be empty.
`url`	`str \| None`	Environment	OpenViking service URL.
`api_key`	`str \| None`	Environment	OpenViking API key.
`account`	`str \| None`	Environment	OpenViking account.
`user`	`str \| None`	Environment	OpenViking user.
`actor_peer_id`	`str \| None`	Environment	Identity used for resource operations.
`target_uri`	`str \| None`	`viking://resources/<index>/`	Resource URI used for ingestion and retrieval.
`wait`	`bool`	`true`	Whether ingestion waits for processing to finish.
`import_timeout`	`float \| None`	`300`	Resource-ingestion timeout in seconds.
`hydrate_results`	`bool`	`true`	Whether to read full content for matched resources.
`read_limit`	`int`	`200`	Maximum amount of content read from a matched resource.
`score_threshold`	`float \| None`	`None`	Minimum relevance score for search results.
`use_context_search`	`bool`	`false`	Whether to use OpenViking context search.

Environment variables

The parameters map to DATABASE_OPENVIKING_URL, DATABASE_OPENVIKING_API_KEY, DATABASE_OPENVIKING_ACCOUNT, DATABASE_OPENVIKING_USER, DATABASE_OPENVIKING_ACTOR_PEER_ID, DATABASE_OPENVIKING_TARGET_URI, DATABASE_OPENVIKING_WAIT, DATABASE_OPENVIKING_IMPORT_TIMEOUT, DATABASE_OPENVIKING_HYDRATE_RESULTS, DATABASE_OPENVIKING_READ_LIMIT, DATABASE_OPENVIKING_SCORE_THRESHOLD, and DATABASE_OPENVIKING_USE_CONTEXT_SEARCH. The URL, API key, account, user, actor peer ID, and target URI also accept the corresponding OPENVIKING_* variables.

Per-operation overrides

Constructor parameters define the defaults. These keyword arguments can override them for one ingestion or search operation.

Method	Parameters	Default	Description
`add_from_directory`	`target_uri`, `wait`, `timeout`	Instance configuration	Override the destination, wait behavior, and timeout.
`add_from_directory`	`strict`, `directly_upload_media`, `preserve_structure`, `telemetry`	`false`, `true`, `true`, `false`	Control strict mode, media upload, directory preservation, and telemetry.
`add_from_directory`	`ignore_dirs`, `include`, `exclude`, `args`	`None`	Filter directories and files and pass additional ingestion arguments.
`add_from_directory`	`watch_interval`	`0`	Directory polling interval; `0` disables continuous watching.
`add_from_files`	`target_uri`, `wait`, `timeout`	Instance configuration	Override the destination, wait behavior, and timeout.
`add_from_files`	`strict`, `reason`, `instruction`, `directly_upload_media`, `telemetry`	`false`, `""`, `""`, `true`, `false`	Control single-file ingestion behavior.
`search`	`target_uri`, `score_threshold`, `use_context_search`	Instance configuration	Override the search scope, threshold, and search mode.
`search`	`filter`, `context_type`, `tags`	`None`	Pass retrieval filters to OpenViking.
`search`	`session`, `session_id`	`None`	Supply session information for context search.
`search`	`telemetry`	`false`	Enable OpenViking telemetry for this search.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Dependencies

Example

Parameters

Environment variables

Per-operation overrides