Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(vectordb): add volcengine_api_key data-plane backend for VikingDB (#1588)

dingben557b1735157c
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index cb319b220..d0979655a 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -27,6 +27,8 @@
"region": "cn-beijing",
"ak": null,
"sk": null,
+ "api_key": null,
+ "host": "api-vikingdb.vikingdb.cn-beijing.volces.com",
"session_token": null
}
},
diff --git a/openviking/storage/collection_schemas.py b/openviking/storage/collection_schemas.py
index f4d5a9d43..06e7b3802 100644
--- a/openviking/storage/collection_schemas.py
+++ b/openviking/storage/collection_schemas.py
@@ -214,6 +214,17 @@ async def init_context_collection(storage) -> bool:
raise ValueError("Vector DB collection name is required")
collection_name = name
embedding_meta = _build_embedding_metadata(config)
+ vectordb_cfg = config.storage.vectordb
+ uses_volcengine_data_plane = bool(
+ vectordb_cfg.backend == "volcengine"
+ and getattr(getattr(vectordb_cfg, "volcengine", None), "api_key", None)
+ )
+ if uses_volcengine_data_plane:
+ logger.info(
+ "Skip collection bootstrap for volcengine data-plane backend; "
+ "collection/index/schema must be pre-created out of band"
+ )
+ return False
schema = CollectionSchemas.context_collection(
collection_name,
vector_dim,
diff --git a/openviking/storage/vectordb/collection/volcengine_api_key_collection.py b/openviking/storage/vectordb/collection/volcengine_api_key_collection.py
new file mode 100644
index 000000000..f454b4e07
--- /dev/null
+++ b/openviking/storage/vectordb/collection/volcengine_api_key_collection.py
@@ -0,0 +1,488 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from openviking.storage.errors import ConnectionError
+from openviking.storage.vectordb.collection.collection import ICollection
+from openviking.storage.vectordb.collection.result import (
+ AggregateResult,
+ DataItem,
+ FetchDataInCollectionResult,
+ SearchItemResult,
+ SearchResult,
+)
+from openviking.storage.vectordb.collection.volcengine_clients import (
+ ClientForDataApi,
+ ClientForDataApiWithApiKey,
+)
+from openviking_cli.utils.logger import default_logger as logger
+
+
+class VolcengineApiKeyCollection(ICollection):
+ """VikingDB data-plane collection implementation using Bearer API key."""
+
+ def __init__(
+ self,
+ api_key: str,
+ host: Optional[str] = None,
+ region: Optional[str] = None,
+ meta_data: Optional[Dict[str, Any]] = None,
+ ):
+ resolved_host = (host or "").rstrip("/") or (
+ ClientForDataApi._global_host.get(region or "") if region else None
+ )
+ if not resolved_host:
+ raise ValueError(
+ "host or region is required for Volcengine API key data-plane access"
+ )
+ self.data_client = ClientForDataApiWithApiKey(api_key, resolved_host)
+ self.meta_data = meta_data if meta_data is not None else {}
+ self.project_name = self.meta_data.get("ProjectName", "default")
+ self.collection_name = self.meta_data.get("CollectionName", "")
+ self.index_name = self.meta_data.get("IndexName", "default")
+
+ @staticmethod
+ def _build_response_error(response: Any, action: str) -> ConnectionError:
+ try:
+ result = response.json()
+ except json.JSONDecodeError:
+ result = {}
+
+ message = ""
+ if isinstance(result, dict):
+ message = (
+ result.get("message")
+ or result.get("msg")
+ or result.get("error")
+ or response.text
+ )
+ else:
+ message = response.text
+
+ return ConnectionError(
+ f"Request to {action} failed: {response.status_code} {message}"
+ )
+
+ @staticmethod
+ def _sanitize_uri_value(v: Any) -> Any:
+ """Remove viking:// prefix and normalize to /... format; return None for empty values."""
+ if not isinstance(v, str):
+ return v
+ s = v.strip()
+ if s in {"/", "viking://"}:
+ return "/"
+ if s.startswith("viking://"):
+ s = s[len("viking://") :]
+ s = s.strip("/")
+ if not s:
+ return None
+ return f"/{s}"
+
+ @classmethod
+ def _sanitize_payload(cls, obj: Any) -> Any:
+ """Recursively sanitize URI-related values in data/filter payload."""
+ if isinstance(obj, dict):
+ return cls._sanitize_dict_payload(obj)
+ if isinstance(obj, list):
+ return cls._sanitize_list_payload(obj)
+ return obj
+
+ @classmethod
+ def _sanitize_dict_payload(cls, obj: Dict[str, Any]) -> Any:
+ field_name = obj.get("field")
+ if (
+ field_name in ("uri", "parent_uri")
+ and "conds" in obj
+ and isinstance(obj["conds"], list)
+ ):
+ new_conds = cls._sanitize_filter_conds(obj["conds"])
+ if not new_conds:
+ return None
+ obj = dict(obj)
+ obj["conds"] = new_conds
+
+ if obj.get("op") == "prefix" and "prefix" in obj:
+ obj = dict(obj)
+ if not cls._sanitize_prefix(obj):
+ return None
+
+ return cls._sanitize_dict_keys(obj)
+
+ @classmethod
+ def _sanitize_filter_conds(cls, conds: List[Any]) -> List[Any]:
+ new_conds = []
+ for x in conds:
+ if isinstance(x, str):
+ sv = cls._sanitize_uri_value(x)
+ if sv:
+ new_conds.append(sv)
+ else:
+ y = cls._sanitize_payload(x)
+ if y is not None:
+ new_conds.append(y)
+ return new_conds
+
+ @classmethod
+ def _sanitize_prefix(cls, obj: Dict[str, Any]) -> bool:
+ pv = cls._sanitize_uri_value(obj.get("prefix"))
+ if pv is None:
+ return False
+ obj["prefix"] = pv
+ return True
+
+ @classmethod
+ def _sanitize_dict_keys(cls, obj: Dict[str, Any]) -> Dict[str, Any]:
+ new_obj: Dict[str, Any] = {}
+ for k, v in obj.items():
+ if k in ("uri", "parent_uri"):
+ sv = cls._sanitize_uri_value(v)
+ if sv is not None:
+ new_obj[k] = sv
+ else:
+ y = cls._sanitize_payload(v)
+ if y is not None:
+ new_obj[k] = y
+ return new_obj
+
+ @classmethod
+ def _sanitize_list_payload(cls, obj: List[Any]) -> List[Any]:
+ sanitized_list = []
+ for x in obj:
+ y = cls._sanitize_payload(x)
+ if y is not None:
+ sanitized_list.append(y)
+ return sanitized_list
+
+ def _data_post(self, path: str, data: Dict[str, Any]):
+ safe_data = self._sanitize_payload(data)
+ response = self.data_client.do_req("POST", path, req_body=safe_data)
+ if response.status_code != 200:
+ raise self._build_response_error(response, path)
+ try:
+ result = response.json()
+ return result.get("result", {})
+ except json.JSONDecodeError:
+ logger.warning("Invalid JSON response from %s", path)
+ return {}
+
+ def _data_get(self, path: str, params: Dict[str, Any]):
+ response = self.data_client.do_req("GET", path, req_params=params)
+ if response.status_code != 200:
+ raise self._build_response_error(response, path)
+ try:
+ result = response.json()
+ return result.get("result", {})
+ except json.JSONDecodeError:
+ logger.warning("Invalid JSON response from %s", path)
+ return {}
+
+ def _parse_fetch_result(self, data: Dict[str, Any]) -> FetchDataInCollectionResult:
+ result = FetchDataInCollectionResult()
+ if isinstance(data, dict):
+ if "fetch" in data:
+ fetch = data.get("fetch", [])
+ result.items = [
+ DataItem(
+ id=item.get("id"),
+ fields=item.get("fields"),
+ )
+ for item in fetch
+ ]
+ if "ids_not_exist" in data:
+ result.ids_not_exist = data.get("ids_not_exist", [])
+ return result
+
+ def _parse_search_result(self, data: Dict[str, Any]) -> SearchResult:
+ result = SearchResult()
+ if isinstance(data, dict) and "data" in data:
+ data_list = data.get("data", [])
+ result.data = [
+ SearchItemResult(
+ id=item.get("id"),
+ fields=item.get("fields"),
+ score=item.get("score"),
+ )
+ for item in data_list
+ ]
+ return result
+
+ def _parse_aggregate_result(
+ self,
+ data: Dict[str, Any],
+ op: str = "count",
+ field: Optional[str] = None,
+ ) -> AggregateResult:
+ result = AggregateResult(op=op, field=field)
+ if isinstance(data, dict):
+ if "agg" in data:
+ result.agg = data["agg"]
+ else:
+ result.agg = data
+ return result
+
+ def _base_data_payload(self, index_name: Optional[str] = None) -> Dict[str, Any]:
+ payload = {
+ "project": self.project_name,
+ "collection_name": self.collection_name,
+ }
+ if index_name:
+ payload["index_name"] = index_name
+ return payload
+
+ def update(
+ self,
+ fields: Optional[Dict[str, Any]] = None,
+ description: Optional[str] = None,
+ ):
+ raise NotImplementedError(
+ "volcengine api_key mode is data-plane only; update is not supported"
+ )
+
+ def get_meta_data(self):
+ return {
+ "ProjectName": self.project_name,
+ "CollectionName": self.collection_name,
+ "IndexName": self.index_name,
+ "Description": "data-plane only backend",
+ }
+
+ def close(self):
+ pass
+
+ def drop(self):
+ raise NotImplementedError(
+ "volcengine api_key mode is data-plane only; drop is not supported"
+ )
+
+ def create_index(self, index_name: str, meta_data: Dict[str, Any]):
+ raise NotImplementedError(
+ "volcengine api_key mode is data-plane only; create_index is not supported"
+ )
+
+ def has_index(self, index_name: str):
+ return index_name == self.index_name
+
+ def get_index(self, index_name: str):
+ return None
+
+ def list_indexes(self):
+ return [self.index_name]
+
+ def update_index(
+ self,
+ index_name: str,
+ scalar_index: Optional[Dict[str, Any]] = None,
+ description: Optional[str] = None,
+ ):
+ raise NotImplementedError(
+ "volcengine api_key mode is data-plane only; update_index is not supported"
+ )
+
+ def get_index_meta_data(self, index_name: str):
+ if index_name != self.index_name:
+ return None
+ return {
+ "IndexName": self.index_name,
+ "Description": "data-plane only backend",
+ }
+
+ def drop_index(self, index_name: str):
+ raise NotImplementedError(
+ "volcengine api_key mode is data-plane only; drop_index is not supported"
+ )
+
+ def upsert_data(self, data_list: List[Dict[str, Any]], ttl: int = 0):
+ path = "/api/vikingdb/data/upsert"
+ data = {
+ **self._base_data_payload(),
+ "data": data_list,
+ "ttl": ttl,
+ }
+ return self._data_post(path, data)
+
+ def fetch_data(self, primary_keys: List[Any]) -> FetchDataInCollectionResult:
+ path = "/api/vikingdb/data/fetch_in_collection"
+ data = {
+ **self._base_data_payload(),
+ "ids": primary_keys,
+ }
+ resp_data = self._data_post(path, data)
+ return self._parse_fetch_result(resp_data)
+
+ def delete_data(self, primary_keys: List[Any]):
+ path = "/api/vikingdb/data/delete"
+ data = {
+ **self._base_data_payload(),
+ "ids": primary_keys,
+ }
+ return self._data_post(path, data)
+
+ def delete_all_data(self):
+ path = "/api/vikingdb/data/delete"
+ data = {
+ **self._base_data_payload(),
+ "del_all": True,
+ }
+ return self._data_post(path, data)
+
+ def search_by_vector(
+ self,
+ index_name: str,
+ dense_vector: Optional[List[float]] = None,
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ sparse_vector: Optional[Dict[str, float]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ if dense_vector is None and sparse_vector is None:
+ raise ValueError("At least one of dense_vector or sparse_vector is required")
+
+ path = "/api/vikingdb/data/search/vector"
+ data = {
+ **self._base_data_payload(index_name=index_name),
+ "dense_vector": dense_vector,
+ "filter": filters,
+ "output_fields": output_fields,
+ "limit": limit,
+ "offset": offset,
+ }
+ if sparse_vector:
+ data["sparse_vector"] = sparse_vector
+ resp_data = self._data_post(path, data)
+ return self._parse_search_result(resp_data)
+
+ def search_by_keywords(
+ self,
+ index_name: str,
+ keywords: Optional[List[str]] = None,
+ query: Optional[str] = None,
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ path = "/api/vikingdb/data/search/keywords"
+ data = {
+ **self._base_data_payload(index_name=index_name),
+ "keywords": keywords,
+ "query": query,
+ "filter": filters,
+ "output_fields": output_fields,
+ "limit": limit,
+ "offset": offset,
+ }
+ resp_data = self._data_post(path, data)
+ return self._parse_search_result(resp_data)
+
+ def search_by_id(
+ self,
+ index_name: str,
+ id: Any,
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ path = "/api/vikingdb/data/search/id"
+ data = {
+ **self._base_data_payload(index_name=index_name),
+ "id": id,
+ "filter": filters,
+ "output_fields": output_fields,
+ "limit": limit,
+ "offset": offset,
+ }
+ resp_data = self._data_post(path, data)
+ return self._parse_search_result(resp_data)
+
+ def search_by_multimodal(
+ self,
+ index_name: str,
+ text: Optional[str] = None,
+ image: Optional[Any] = None,
+ video: Optional[Any] = None,
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ path = "/api/vikingdb/data/search/multi_modal"
+ data = {
+ **self._base_data_payload(index_name=index_name),
+ "text": text,
+ "image": image,
+ "video": video,
+ "filter": filters,
+ "output_fields": output_fields,
+ "limit": limit,
+ "offset": offset,
+ }
+ resp_data = self._data_post(path, data)
+ return self._parse_search_result(resp_data)
+
+ def search_by_random(
+ self,
+ index_name: str,
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ path = "/api/vikingdb/data/search/random"
+ data = {
+ **self._base_data_payload(index_name=index_name),
+ "filter": filters,
+ "output_fields": output_fields,
+ "limit": limit,
+ "offset": offset,
+ }
+ resp_data = self._data_post(path, data)
+ return self._parse_search_result(resp_data)
+
+ def search_by_scalar(
+ self,
+ index_name: str,
+ field: str,
+ order: Optional[str] = "desc",
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ path = "/api/vikingdb/data/search/scalar"
+ data = {
+ **self._base_data_payload(index_name=index_name),
+ "field": field,
+ "order": order,
+ "filter": filters,
+ "output_fields": output_fields,
+ "limit": limit,
+ "offset": offset,
+ }
+ resp_data = self._data_post(path, data)
+ return self._parse_search_result(resp_data)
+
+ def aggregate_data(
+ self,
+ index_name: str,
+ op: str = "count",
+ field: Optional[str] = None,
+ filters: Optional[Dict[str, Any]] = None,
+ cond: Optional[Dict[str, Any]] = None,
+ ) -> AggregateResult:
+ path = "/api/vikingdb/data/agg"
+ data = {
+ **self._base_data_payload(index_name=index_name),
+ "op": op,
+ "field": field,
+ "filter": filters,
+ }
+ if cond is not None:
+ data["cond"] = cond
+ resp_data = self._data_post(path, data)
+ return self._parse_aggregate_result(resp_data, op, field)
diff --git a/openviking/storage/vectordb/collection/volcengine_clients.py b/openviking/storage/vectordb/collection/volcengine_clients.py
index 7615d7697..6947e1791 100644
--- a/openviking/storage/vectordb/collection/volcengine_clients.py
+++ b/openviking/storage/vectordb/collection/volcengine_clients.py
@@ -140,3 +140,53 @@ class ClientForDataApi:
data=req.body,
timeout=DEFAULT_TIMEOUT,
)
+
+
+class ClientForDataApiWithApiKey:
+ """Data-plane-only client for Volcengine VikingDB using Bearer API key."""
+
+ def __init__(self, api_key: str, host: str):
+ self.api_key = api_key
+ self.host = host.rstrip("/")
+
+ if not self.api_key or not self.host:
+ raise ValueError("api_key and host are required for ClientForDataApiWithApiKey")
+
+ def prepare_request(self, method, path, params=None, data=None):
+ if Request is None:
+ raise ImportError(
+ "volcengine package is required. Please install it via 'pip install volcengine'"
+ )
+
+ r = Request()
+ r.set_shema("https")
+ r.set_method(method)
+ r.set_connection_timeout(DEFAULT_TIMEOUT)
+ r.set_socket_timeout(DEFAULT_TIMEOUT)
+ mheaders = {
+ "Accept": "application/json",
+ "Content-Type": "application/json",
+ "Host": self.host,
+ "Authorization": f"Bearer {self.api_key}",
+ }
+ r.set_headers(mheaders)
+ if params:
+ r.set_query(params)
+ r.set_host(self.host)
+ r.set_path(path)
+ if data is not None:
+ r.set_body(json.dumps(data))
+ return r
+
+ def do_req(self, req_method, req_path, req_params=None, req_body=None):
+ req = self.prepare_request(
+ method=req_method, path=req_path, params=req_params, data=req_body
+ )
+ return requests.request(
+ method=req.method,
+ url=f"https://{self.host}{req.path}",
+ headers=req.headers,
+ params=req.query,
+ data=req.body,
+ timeout=DEFAULT_TIMEOUT,
+ )
diff --git a/openviking/storage/vectordb_adapters/volcengine_adapter.py b/openviking/storage/vectordb_adapters/volcengine_adapter.py
index 0b8ca021a..133ac92b8 100644
--- a/openviking/storage/vectordb_adapters/volcengine_adapter.py
+++ b/openviking/storage/vectordb_adapters/volcengine_adapter.py
@@ -7,6 +7,9 @@ from __future__ import annotations
from typing import Any, Dict
from openviking.storage.vectordb.collection.collection import Collection
+from openviking.storage.vectordb.collection.volcengine_api_key_collection import (
+ VolcengineApiKeyCollection,
+)
from openviking.storage.vectordb.collection.volcengine_collection import (
VolcengineCollection,
get_or_create_volcengine_collection,
@@ -21,10 +24,12 @@ class VolcengineCollectionAdapter(CollectionAdapter):
def __init__(
self,
*,
- ak: str,
- sk: str,
- region: str,
+ ak: str | None,
+ sk: str | None,
+ region: str | None,
session_token: str | None,
+ api_key: str | None,
+ host: str | None,
project_name: str,
collection_name: str,
index_name: str,
@@ -36,22 +41,29 @@ class VolcengineCollectionAdapter(CollectionAdapter):
self._sk = sk
self._region = region
self._session_token = session_token
+ self._api_key = api_key
+ self._host = host
self._project_name = project_name
@classmethod
def from_config(cls, config: Any):
- if not (
- config.volcengine
- and config.volcengine.ak
- and config.volcengine.sk
- and config.volcengine.region
- ):
- raise ValueError("Volcengine backend requires AK, SK, and Region configuration")
+ cfg = getattr(config, "volcengine", None)
+ if not cfg:
+ raise ValueError("Volcengine backend requires volcengine configuration")
+ if cfg.api_key and not (cfg.host or cfg.region):
+ raise ValueError("Volcengine api_key mode requires host or region configuration")
+ if not cfg.api_key and not (cfg.ak and cfg.sk and cfg.region):
+ raise ValueError(
+ "Volcengine backend requires AK, SK, and Region configuration "
+ "when api_key is not set"
+ )
return cls(
- ak=config.volcengine.ak,
- sk=config.volcengine.sk,
- region=config.volcengine.region,
- session_token=config.volcengine.session_token,
+ ak=cfg.ak,
+ sk=cfg.sk,
+ region=cfg.region,
+ session_token=cfg.session_token,
+ api_key=cfg.api_key,
+ host=cfg.host,
project_name=config.project_name or "default",
collection_name=config.name or "context",
index_name=config.index_name or "default",
@@ -63,15 +75,36 @@ class VolcengineCollectionAdapter(CollectionAdapter):
"CollectionName": self._collection_name,
}
+ def _data_plane_meta(self) -> Dict[str, Any]:
+ meta = self._meta()
+ meta["IndexName"] = self._index_name
+ return meta
+
def _config(self) -> Dict[str, Any]:
return {
"AK": self._ak,
"SK": self._sk,
"Region": self._region,
"SessionToken": self._session_token,
+ "ApiKey": self._api_key,
+ "Host": self._host,
}
+ def _uses_api_key_auth(self) -> bool:
+ return bool(self._api_key)
+
def _new_collection_handle(self) -> Collection:
+ if self._uses_api_key_auth():
+ return Collection(
+ VolcengineApiKeyCollection(
+ api_key=self._api_key or "",
+ host=self._host,
+ region=self._region,
+ meta_data=self._data_plane_meta(),
+ )
+ )
+ if self._ak is None or self._sk is None or self._region is None:
+ raise ValueError("AK/SK mode requires ak, sk, and region")
return Collection(
VolcengineCollection(
ak=self._ak,
@@ -85,12 +118,20 @@ class VolcengineCollectionAdapter(CollectionAdapter):
def _load_existing_collection_if_needed(self) -> None:
if self._collection is not None:
return
+ if self._uses_api_key_auth():
+ self._collection = self._new_collection_handle()
+ return
candidate = self._new_collection_handle()
meta = candidate.get_meta_data() or {}
if meta and meta.get("CollectionName"):
self._collection = candidate
def _create_backend_collection(self, meta: Dict[str, Any]) -> Collection:
+ if self._uses_api_key_auth():
+ raise NotImplementedError(
+ "volcengine backend with api_key does not support create_collection; "
+ "pre-create collection/index/schema out of band"
+ )
payload = dict(meta)
payload.update(self._meta())
return get_or_create_volcengine_collection(
diff --git a/openviking_cli/utils/config/vectordb_config.py b/openviking_cli/utils/config/vectordb_config.py
index bf8c04b2b..0683ab09f 100644
--- a/openviking_cli/utils/config/vectordb_config.py
+++ b/openviking_cli/utils/config/vectordb_config.py
@@ -17,6 +17,10 @@ class VolcengineConfig(BaseModel):
ak: Optional[str] = Field(default=None, description="Volcengine Access Key")
sk: Optional[str] = Field(default=None, description="Volcengine Secret Key")
+ api_key: Optional[str] = Field(
+ default=None,
+ description="Optional VikingDB Data API key for data-plane-only access",
+ )
session_token: Optional[str] = Field(
default=None,
description="Optional Volcengine STS security token for temporary credentials",
@@ -27,8 +31,8 @@ class VolcengineConfig(BaseModel):
host: Optional[str] = Field(
default=None,
description=(
- "[Deprecated] Ignored in volcengine mode. "
- "Hosts are derived from `region` to route console/data APIs correctly."
+ "Optional VikingDB data API host. "
+ "Used together with `api_key` for data-plane-only access."
),
)
@@ -56,7 +60,11 @@ class VectorDBBackendConfig(BaseModel):
backend: str = Field(
default="local",
- description="VectorDB backend type: 'local' (file-based), 'http' (remote service), or 'volcengine' (VikingDB)",
+ description=(
+ "VectorDB backend type: 'local', 'http', "
+ "'volcengine' (AK/SK signed or API key data-plane only), "
+ "or 'vikingdb' (private deployment)"
+ ),
)
name: Optional[str] = Field(default=COLLECTION_NAME, description="Collection name for VectorDB")
@@ -140,15 +148,28 @@ class VectorDBBackendConfig(BaseModel):
raise ValueError("VectorDB http backend requires 'url' to be set")
elif self.backend == "volcengine":
- if not self.volcengine or not self.volcengine.ak or not self.volcengine.sk:
- raise ValueError("VectorDB volcengine backend requires 'ak' and 'sk' to be set")
- if not self.volcengine.region:
- raise ValueError("VectorDB volcengine backend requires 'region' to be set")
- if self.volcengine.host:
+ if self.volcengine and self.volcengine.host:
+ self.volcengine.host = self.volcengine.host.strip().rstrip("/")
+
+ uses_api_key = bool(self.volcengine and self.volcengine.api_key)
+ if uses_api_key:
+ if not self.volcengine or not (self.volcengine.host or self.volcengine.region):
+ raise ValueError(
+ "VectorDB volcengine backend with 'api_key' requires 'host' or 'region' to be set"
+ )
+ else:
+ if not self.volcengine or not self.volcengine.ak or not self.volcengine.sk:
+ raise ValueError(
+ "VectorDB volcengine backend requires 'ak' and 'sk' to be set "
+ "when 'api_key' is not configured"
+ )
+ if not self.volcengine.region:
+ raise ValueError("VectorDB volcengine backend requires 'region' to be set")
+ if self.volcengine and self.volcengine.host and not uses_api_key:
logger.warning(
- "VectorDB volcengine backend: 'volcengine.host' is deprecated and ignored. "
+ "VectorDB volcengine backend: 'volcengine.host' is ignored in AK/SK mode. "
"Using region-based console/data hosts for region='%s'.",
- self.volcengine.region,
+ self.volcengine.region or "",
)
elif self.backend == "vikingdb":
diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.py
index 6c9b9f23c..a0a66d4cb 100644
--- a/tests/misc/test_config_validation.py
+++ b/tests/misc/test_config_validation.py
@@ -7,7 +7,7 @@ import sys
from openviking_cli.utils.config.agfs_config import AGFSConfig, S3Config
from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig
-from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig
+from openviking_cli.utils.config.vectordb_config import VolcengineConfig, VectorDBBackendConfig
from openviking_cli.utils.config.vlm_config import VLMConfig
@@ -86,12 +86,73 @@ def test_vectordb_validation():
try:
_ = VectorDBBackendConfig(
backend="volcengine",
- volcengine={"ak": "test_ak", "sk": "test_sk", "region": "cn-beijing"},
+ volcengine=VolcengineConfig(ak="test_ak", sk="test_sk", region="cn-beijing"),
)
print(" Pass")
except ValueError as e:
print(f" Fail: {e}")
+ # Test 4: volcengine backend with api_key complete config
+ print("\n4. Test volcengine backend with api_key complete config...")
+ try:
+ _ = VectorDBBackendConfig(
+ backend="volcengine",
+ volcengine=VolcengineConfig(
+ api_key="vk-test-token",
+ host="api-vikingdb.vikingdb.cn-beijing.volces.com",
+ ),
+ )
+ print(" Pass")
+ except ValueError as e:
+ print(f" Fail: {e}")
+
+
+def test_vectordb_volcengine_validation_accepts_api_key_without_ak_sk():
+ config = VectorDBBackendConfig(
+ backend="volcengine",
+ volcengine=VolcengineConfig(
+ api_key="vk-test-token",
+ host="api-vikingdb.vikingdb.cn-beijing.volces.com",
+ ),
+ )
+
+ assert config.backend == "volcengine"
+ assert config.volcengine is not None
+ assert config.volcengine.api_key == "vk-test-token"
+ assert config.volcengine.host == "api-vikingdb.vikingdb.cn-beijing.volces.com"
+
+
+def test_vectordb_volcengine_without_api_key_still_requires_ak_sk():
+ try:
+ VectorDBBackendConfig(
+ backend="volcengine",
+ volcengine=VolcengineConfig(host="api-vikingdb.vikingdb.cn-beijing.volces.com"),
+ )
+ raise AssertionError("Expected ValueError for missing ak/sk")
+ except ValueError as e:
+ assert "ak" in str(e)
+
+
+def test_removed_volcengine_api_key_backend_name_is_rejected():
+ try:
+ VectorDBBackendConfig(
+ backend="volcengine_api_key",
+ )
+ raise AssertionError("Expected ValueError for removed backend name")
+ except ValueError as e:
+ assert "volcengine_api_key" in str(e)
+
+
+def test_vectordb_volcengine_api_key_auth_requires_host_or_region():
+ try:
+ VectorDBBackendConfig(
+ backend="volcengine",
+ volcengine=VolcengineConfig(api_key="vk-test-token"),
+ )
+ raise AssertionError("Expected ValueError for missing host/region in api_key mode")
+ except ValueError as e:
+ assert "host' or 'region" in str(e)
+
def test_vectordb_index_name_defaults_and_overrides():
default_config = VectorDBBackendConfig()
@@ -111,6 +172,7 @@ def test_embedding_validation():
print("\n1. Test no embedder config...")
try:
config = EmbeddingConfig()
+ assert config.dense is not None
print(
f" Pass (default provider={config.dense.provider}, model={config.dense.model}, dim={config.dimension})"
)
diff --git a/tests/storage/test_collection_schemas.py b/tests/storage/test_collection_schemas.py
index ce420e85c..8fdbec6c2 100644
--- a/tests/storage/test_collection_schemas.py
+++ b/tests/storage/test_collection_schemas.py
@@ -34,8 +34,19 @@ class _DummyEmbedder:
class _DummyConfig:
- def __init__(self, embedder: _DummyEmbedder, backend: str = "volcengine"):
- self.storage = SimpleNamespace(vectordb=SimpleNamespace(name="context", backend=backend))
+ def __init__(
+ self,
+ embedder: _DummyEmbedder,
+ backend: str = "volcengine",
+ volcengine_data_api_key: str | None = None,
+ ):
+ self.storage = SimpleNamespace(
+ vectordb=SimpleNamespace(
+ name="context",
+ backend=backend,
+ volcengine=SimpleNamespace(api_key=volcengine_data_api_key),
+ )
+ )
self.embedding = SimpleNamespace(
dimension=2,
get_embedder=lambda: embedder,
@@ -533,6 +544,39 @@ async def test_init_context_collection_excludes_parent_uri_for_local_backend(mon
assert "parent_uri" not in captured["schema"]["ScalarIndex"]
+async def test_init_context_collection_skips_bootstrap_for_api_key_auth_mode_on_volcengine(
+ monkeypatch,
+):
+ class _Storage:
+ async def create_collection(self, name, schema): # pragma: no cover
+ del name, schema
+ raise AssertionError("create_collection should not be called for data-plane backend")
+
+ async def get_collection_meta(self): # pragma: no cover
+ raise AssertionError("get_collection_meta should not be called for data-plane backend")
+
+ async def update_collection_description(self, description): # pragma: no cover
+ del description
+ raise AssertionError(
+ "update_collection_description should not be called for data-plane backend"
+ )
+
+ embedder = _DummyEmbedder()
+ monkeypatch.setattr(
+ "openviking_cli.utils.config.get_openviking_config",
+ lambda: _DummyConfig(
+ embedder,
+ backend="volcengine",
+ volcengine_data_api_key="vk-test-token",
+ ),
+ )
+
+ created = await init_context_collection(_Storage())
+
+ assert created is False
+
+
def test_single_account_backend_filters_parent_uri_against_current_schema():
class _Collection:
def get_meta_data(self):
diff --git a/tests/storage/test_volcengine_clients.py b/tests/storage/test_volcengine_clients.py
index 57ebc9adb..b2e34e4d0 100644
--- a/tests/storage/test_volcengine_clients.py
+++ b/tests/storage/test_volcengine_clients.py
@@ -3,12 +3,13 @@ from volcengine.base.Request import Request
from openviking.storage.vectordb.collection.volcengine_clients import (
ClientForConsoleApi,
ClientForDataApi,
+ ClientForDataApiWithApiKey,
)
from openviking.storage.vectordb.collection.volcengine_collection import VolcengineCollection
from openviking.storage.vectordb_adapters.volcengine_adapter import VolcengineCollectionAdapter
from openviking_cli.utils.config.vectordb_config import (
- VectorDBBackendConfig,
VolcengineConfig,
+ VectorDBBackendConfig,
)
@@ -107,6 +108,23 @@ def test_data_client_do_req_uses_signed_query_params(monkeypatch):
assert captured["params"]["X-Signature"] == "signed"
+def test_data_api_key_client_prepare_request_sets_bearer_auth():
+ client = ClientForDataApiWithApiKey(
+ api_key="vk-test-token",
+ host="api-vikingdb.vikingdb.cn-beijing.volces.com",
+ )
+
+ request = client.prepare_request(
+ "POST",
+ "/api/vikingdb/data/search/vector",
+ data={"project": "default"},
+ )
+
+ assert request.headers["Authorization"] == "Bearer vk-test-token"
+ assert request.headers["Host"] == "api-vikingdb.vikingdb.cn-beijing.volces.com"
+ assert request.path == "/api/vikingdb/data/search/vector"
+
+
def test_volcengine_adapter_preserves_session_token_from_config():
config = VectorDBBackendConfig(
backend="volcengine",
@@ -124,6 +142,26 @@ def test_volcengine_adapter_preserves_session_token_from_config():
assert adapter._config()["SessionToken"] == "test-session-token"
+def test_volcengine_adapter_supports_api_key_mode_from_config():
+ config = VectorDBBackendConfig(
+ backend="volcengine",
+ name="context",
+ project="default",
+ volcengine=VolcengineConfig(
+ api_key="vk-test-token",
+ host="api-vikingdb.vikingdb.cn-beijing.volces.com",
+ ),
+ )
+
+ adapter = VolcengineCollectionAdapter.from_config(config)
+
+ assert adapter.mode == "volcengine"
+ assert adapter.collection_name == "context"
+ assert adapter.index_name == "default"
+ assert adapter.collection_exists() is True
+ assert adapter._config()["ApiKey"] == "vk-test-token"
+
+
def test_volcengine_collection_get_meta_data_returns_empty_on_signature_error(monkeypatch):
class _Response:
status_code = 403