Skip to content

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

feat(config): 配置检索打分和 embedding 输入 (#1770)

Qin Haojieb35d38a323b2
diff --git a/README.md b/README.md
index 2e4a86eaa..1e1b7e267 100644
--- a/README.md
+++ b/README.md
@@ -323,7 +323,9 @@ If you prefer manual configuration, create `~/.openviking/ov.conf`, remove the c
"dimension": 1024, // Vector dimension
"model" : "<model-name>" // Embedding model name (e.g., doubao-embedding-vision-251215 or text-embedding-3-large)
},
- "max_concurrent": 10 // Max concurrent embedding requests (default: 10)
+ "max_concurrent": 10, // Max concurrent embedding requests (default: 10)
+ "text_source": "content_only", // Text file vectorization source: content_only|summary_first|summary_only
+ "max_input_tokens": 4096 // Max estimated raw text tokens sent to embedding
},
"vlm": {
"api_base" : "<api-endpoint>", // API endpoint address
diff --git a/docs/en/concepts/07-retrieval.md b/docs/en/concepts/07-retrieval.md
index b1666881d..2fcceb3cd 100644
--- a/docs/en/concepts/07-retrieval.md
+++ b/docs/en/concepts/07-retrieval.md
@@ -107,7 +107,7 @@ while dir_queue:
for r in results:
# Score propagation
- final_score = 0.5 * embedding_score + 0.5 * parent_score
+ final_score = score_propagation_alpha * embedding_score + (1 - score_propagation_alpha) * parent_score
if final_score > threshold:
collected.append(r)
@@ -124,7 +124,7 @@ while dir_queue:
| Parameter | Value | Description |
|-----------|-------|-------------|
-| `SCORE_PROPAGATION_ALPHA` | 0.5 | 50% embedding + 50% parent |
+| `retrieval.score_propagation_alpha` | 0.5 | Child-score weight in the propagation blend; `0.5` means 50% child score + 50% parent score |
| `MAX_CONVERGENCE_ROUNDS` | 3 | Convergence detection rounds |
| `GLOBAL_SEARCH_TOPK` | 10 | Global search candidates |
| `MAX_RELATIONS` | 5 | Max relations per resource |
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 00283aae7..70ebb15ac 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -193,6 +193,8 @@ Embedding model configuration for vector search, supporting dense, sparse, and h
"embedding": {
"max_concurrent": 10,
"max_retries": 3,
+ "text_source": "content_only",
+ "max_input_tokens": 4096,
"dense": {
"provider": "volcengine",
"api_key": "your-api-key",
@@ -210,6 +212,8 @@ Embedding model configuration for vector search, supporting dense, sparse, and h
|-----------|------|-------------|
| `max_concurrent` | int | Maximum concurrent embedding requests (`embedding.max_concurrent`, default: `10`) |
| `max_retries` | int | Maximum retry attempts for transient embedding provider errors (`embedding.max_retries`, default: `3`; `0` disables retry) |
+| `text_source` | str | Text used for vectorizing text files. `content_only` reads raw content, `summary_first` uses summary when available and falls back to content, `summary_only` uses only summary. Default: `content_only` |
+| `max_input_tokens` | int | Maximum estimated raw text tokens sent to the embedding model when content is used. Default: `4096` |
| `provider` | str | `"volcengine"`, `"openai"`, `"vikingdb"`, `"jina"`, `"voyage"`, `"dashscope"`, or `"gemini"` |
| `api_key` | str | API key |
| `model` | str | Model name |
@@ -723,6 +727,26 @@ Reranking model for search result refinement. Supports VikingDB (Volcengine), Co
If rerank is not configured, search uses vector similarity only.
+### retrieval
+
+Retrieval ranking configuration for final search scores.
+
+```json
+{
+ "retrieval": {
+ "hotness_alpha": 0.0,
+ "score_propagation_alpha": 0.5
+ }
+}
+```
+
+| Parameter | Type | Description | Default |
+|-----------|------|-------------|---------|
+| `hotness_alpha` | float | Weight for blending hotness into final retrieval scores. `0.0` disables the hotness boost and keeps scores equal to semantic similarity; `1.0` uses only hotness. Valid range: `0.0` to `1.0`. | `0.0` |
+| `score_propagation_alpha` | float | Weight for each child result's own score when blending with its parent score during hierarchical retrieval. `0.5` keeps the existing equal blend; `1.0` ignores the parent score; `0.0` uses only the parent score. Valid range: `0.0` to `1.0`. | `0.5` |
+
+Keep `hotness_alpha` at `0.0` when you need scores to reflect pure vector similarity. Set it above `0.0` only when frequently accessed or recently updated contexts should receive a ranking boost.
+
### storage
Storage configuration for context data, including file storage (RAGFS) and vector database storage (VectorDB).
@@ -1140,6 +1164,8 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry
"embedding": {
"max_concurrent": 10,
"max_retries": 3,
+ "text_source": "content_only",
+ "max_input_tokens": 4096,
"dense": {
"provider": "volcengine",
"api_key": "string",
@@ -1167,6 +1193,10 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry
"threshold": 0.1,
"extra_headers": {}
},
+ "retrieval": {
+ "hotness_alpha": 0.0,
+ "score_propagation_alpha": 0.5
+ },
"encryption": {
"enabled": false,
"provider": "local|vault|volcengine_kms",
diff --git a/docs/zh/concepts/07-retrieval.md b/docs/zh/concepts/07-retrieval.md
index 6b622c5e1..28a1fbb70 100644
--- a/docs/zh/concepts/07-retrieval.md
+++ b/docs/zh/concepts/07-retrieval.md
@@ -107,7 +107,7 @@ while dir_queue:
for r in results:
# 分数传播
- final_score = 0.5 * embedding_score + 0.5 * parent_score
+ final_score = score_propagation_alpha * embedding_score + (1 - score_propagation_alpha) * parent_score
if final_score > threshold:
collected.append(r)
@@ -124,7 +124,7 @@ while dir_queue:
| 参数 | 值 | 说明 |
|------|-----|------|
-| `SCORE_PROPAGATION_ALPHA` | 0.5 | 50% embedding + 50% parent |
+| `retrieval.score_propagation_alpha` | 0.5 | 分数传播混合中子节点自身分数的权重;`0.5` 表示 50% 子节点分数 + 50% 父节点分数 |
| `MAX_CONVERGENCE_ROUNDS` | 3 | 收敛检测轮数 |
| `GLOBAL_SEARCH_TOPK` | 10 | 全局搜索候选数 |
| `MAX_RELATIONS` | 5 | 每资源最大关联数 |
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index d024dccef..d3312aff9 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -194,6 +194,8 @@ openviking-server doctor
"embedding": {
"max_concurrent": 10,
"max_retries": 3,
+ "text_source": "content_only",
+ "max_input_tokens": 4096,
"dense": {
"provider": "volcengine",
"api_key": "your-api-key",
@@ -212,6 +214,8 @@ openviking-server doctor
|------|------|------|
| `max_concurrent` | int | 最大并发 Embedding 请求数(`embedding.max_concurrent`,默认:`10`) |
| `max_retries` | int | Embedding provider 瞬时错误的最大重试次数(`embedding.max_retries`,默认:`3`;`0` 表示禁用重试) |
+| `text_source` | str | 文本文件向量化时使用的文本来源。`content_only` 读取原文内容;`summary_first` 优先使用摘要,没有摘要时回退到原文;`summary_only` 只使用摘要。默认:`content_only` |
+| `max_input_tokens` | int | 使用原文内容向量化时,发送给 embedding 模型的最大估算 token 数。默认:`4096` |
| `provider` | str | `"volcengine"`、`"openai"`、`"vikingdb"`、`"jina"`、`"voyage"`、`"minimax"`、`"dashscope"` 或 `"gemini"` |
| `api_key` | str | API Key |
| `model` | str | 模型名称 |
@@ -695,6 +699,26 @@ AST 提取支持:Python、JavaScript/TypeScript、Rust、Go、Java、C/C++。
如果未配置 Rerank,搜索仅使用向量相似度。
+### retrieval
+
+最终搜索分数的召回排序配置。
+
+```json
+{
+ "retrieval": {
+ "hotness_alpha": 0.0,
+ "score_propagation_alpha": 0.5
+ }
+}
+```
+
+| 参数 | 类型 | 说明 | 默认值 |
+|------|------|------|--------|
+| `hotness_alpha` | float | hotness 分数在最终召回分数中的混合权重。`0.0` 表示关闭 hotness boost,最终分数等于语义相似度;`1.0` 表示只使用 hotness。有效范围:`0.0` 到 `1.0`。 | `0.0` |
+| `score_propagation_alpha` | float | 层级检索中,子节点自身分数与父节点传播分数混合时,子节点自身分数的权重。`0.5` 保持当前 50/50 行为;`1.0` 表示忽略父节点分数;`0.0` 表示只使用父节点分数。有效范围:`0.0` 到 `1.0`。 | `0.5` |
+
+如果需要分数严格反映向量相似度,保持 `hotness_alpha` 为 `0.0`。只有当希望高频访问或最近更新的上下文获得排序提升时,才将它设置为大于 `0.0`。
+
### storage
用于存储上下文数据 ,包括文件存储(RAGFS)和向量库存储(VectorDB)。
@@ -1114,6 +1138,8 @@ openviking add-resource ./docs --exclude "*.tmp"
"embedding": {
"max_concurrent": 10,
"max_retries": 3,
+ "text_source": "content_only",
+ "max_input_tokens": 4096,
"dense": {
"provider": "volcengine",
"api_key": "string",
@@ -1141,6 +1167,10 @@ openviking add-resource ./docs --exclude "*.tmp"
"threshold": 0.1,
"extra_headers": {}
},
+ "retrieval": {
+ "hotness_alpha": 0.0,
+ "score_propagation_alpha": 0.5
+ },
"encryption": {
"enabled": false,
"provider": "local|vault|volcengine_kms",
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index 7e3ee09a3..6838e9900 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -89,6 +89,8 @@
"provider": "volcengine",
"input": "multimodal"
},
+ "text_source": "content_only",
+ "max_input_tokens": 4096,
"circuit_breaker": {
"failure_threshold": 5,
"reset_timeout": 60,
@@ -157,6 +159,10 @@
"model": "qwen3-rerank",
"threshold": 0.1
},
+ "retrieval": {
+ "hotness_alpha": 0.0,
+ "score_propagation_alpha": 0.5
+ },
"auto_generate_l0": true,
"auto_generate_l1": true,
"default_search_mode": "thinking",
diff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.py
index 338caf8ec..bdcde7a0c 100644
--- a/openviking/retrieve/hierarchical_retriever.py
+++ b/openviking/retrieve/hierarchical_retriever.py
@@ -31,7 +31,7 @@ from openviking_cli.retrieve.types import (
RelatedContext,
TypedQuery,
)
-from openviking_cli.utils.config import RerankConfig
+from openviking_cli.utils.config import RerankConfig, RetrievalConfig
from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
@@ -47,10 +47,8 @@ class HierarchicalRetriever:
MAX_CONVERGENCE_ROUNDS = 3 # Stop after multiple rounds with unchanged topk
MAX_RELATIONS = 5 # Maximum relations per resource
- SCORE_PROPAGATION_ALPHA = 0.5 # Score propagation coefficient
DIRECTORY_DOMINANCE_RATIO = 1.2 # Directory score must exceed max child score
GLOBAL_SEARCH_TOPK = 10 # Global retrieval count (more candidates = better rerank precision)
- HOTNESS_ALPHA = 0.2 # Weight for hotness score in final ranking (0 = disabled)
LEVEL_URI_SUFFIX = {0: ".abstract.md", 1: ".overview.md"}
def __init__(
@@ -58,6 +56,7 @@ class HierarchicalRetriever:
storage: VikingDBManager,
embedder: Optional[Any],
rerank_config: Optional[RerankConfig] = None,
+ retrieval_config: Optional[RetrievalConfig] = None,
):
"""Initialize hierarchical retriever with rerank_config.
@@ -65,10 +64,14 @@ class HierarchicalRetriever:
storage: VikingVectorIndexBackend instance
embedder: Embedder instance (supports dense/sparse/hybrid)
rerank_config: Rerank configuration (optional, will fallback to vector search only)
+ retrieval_config: Retrieval ranking configuration.
"""
self.vector_store = storage
self.embedder = embedder
self.rerank_config = rerank_config
+ self.retrieval_config = retrieval_config or RetrievalConfig()
+ self.hotness_alpha = self.retrieval_config.hotness_alpha
+ self.score_propagation_alpha = self.retrieval_config.score_propagation_alpha
# Use rerank threshold if available, otherwise use a default
self.threshold = rerank_config.threshold if rerank_config else 0
@@ -405,7 +408,7 @@ class HierarchicalRetriever:
f"[RecursiveSearch] Added initial candidate: {uri} (score: {score:.4f})"
)
- alpha = self.SCORE_PROPAGATION_ALPHA
+ alpha = self.score_propagation_alpha
# Initialize: process starting points
for uri, score in starting_points:
@@ -505,9 +508,8 @@ class HierarchicalRetriever:
"""Convert candidate results to MatchedContext list.
Blends semantic similarity with a hotness score derived from
- ``active_count`` and ``updated_at`` so that frequently-accessed,
- recently-updated contexts get a ranking boost. The blend weight
- is controlled by ``HOTNESS_ALPHA`` (0 disables the boost).
+ ``active_count`` and ``updated_at`` when configured. The blend weight
+ is controlled by ``retrieval.hotness_alpha`` (0 disables the boost).
"""
results = []
@@ -530,25 +532,26 @@ class HierarchicalRetriever:
if not math.isfinite(semantic_score):
semantic_score = 0.0
- # --- hotness boost ---
- updated_at_raw = c.get("updated_at")
- if isinstance(updated_at_raw, str):
- try:
- updated_at_val = parse_iso_datetime(updated_at_raw)
- except (ValueError, TypeError):
+ alpha = self.hotness_alpha
+ if alpha > 0:
+ updated_at_raw = c.get("updated_at")
+ if isinstance(updated_at_raw, str):
+ try:
+ updated_at_val = parse_iso_datetime(updated_at_raw)
+ except (ValueError, TypeError):
+ updated_at_val = None
+ elif isinstance(updated_at_raw, datetime):
+ updated_at_val = updated_at_raw
+ else:
updated_at_val = None
- elif isinstance(updated_at_raw, datetime):
- updated_at_val = updated_at_raw
- else:
- updated_at_val = None
-
- h_score = hotness_score(
- active_count=c.get("active_count", 0),
- updated_at=updated_at_val,
- )
- alpha = self.HOTNESS_ALPHA
- final_score = (1 - alpha) * semantic_score + alpha * h_score
+ h_score = hotness_score(
+ active_count=c.get("active_count", 0),
+ updated_at=updated_at_val,
+ )
+ final_score = (1 - alpha) * semantic_score + alpha * h_score
+ else:
+ final_score = semantic_score
if not math.isfinite(final_score):
final_score = 0.0
level = c.get("level", 2)
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 63293dd84..11fbeb71c 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -274,6 +274,7 @@ class OpenVikingService:
query_embedder=self._embedder,
rerank_config=config.rerank,
vector_store=self._vikingdb_manager,
+ retrieval_config=config.retrieval,
enable_recorder=enable_recorder,
encryptor=self._encryptor,
)
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index fe932f322..112a07341 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -49,7 +49,7 @@ from openviking_cli.utils.uri import VikingURI
if TYPE_CHECKING:
from openviking.storage.transaction.lock_handle import LockHandle
from openviking.storage.viking_vector_index_backend import VikingVectorIndexBackend
- from openviking_cli.utils.config import RerankConfig
+ from openviking_cli.utils.config import RerankConfig, RetrievalConfig
logger = get_logger(__name__)
@@ -112,6 +112,7 @@ def init_viking_fs(
query_embedder: Optional[Any] = None,
rerank_config: Optional["RerankConfig"] = None,
vector_store: Optional["VikingVectorIndexBackend"] = None,
+ retrieval_config: Optional["RetrievalConfig"] = None,
timeout: int = 10,
enable_recorder: bool = False,
encryptor: Optional[Any] = None,
@@ -123,6 +124,7 @@ def init_viking_fs(
agfs_config: AGFS configuration object for backend settings
query_embedder: Embedder instance
rerank_config: Rerank configuration
+ retrieval_config: Retrieval ranking configuration
vector_store: Vector store instance
enable_recorder: Whether to enable IO recording
encryptor: FileEncryptor instance for encryption/decryption
@@ -134,6 +136,7 @@ def init_viking_fs(
query_embedder=query_embedder,
rerank_config=rerank_config,
vector_store=vector_store,
+ retrieval_config=retrieval_config,
encryptor=encryptor,
)
@@ -205,6 +208,7 @@ class VikingFS:
query_embedder: Optional[Any] = None,
rerank_config: Optional["RerankConfig"] = None,
vector_store: Optional["VikingVectorIndexBackend"] = None,
+ retrieval_config: Optional["RetrievalConfig"] = None,
timeout: int = 10,
encryptor: Optional[Any] = None,
):
@@ -212,6 +216,7 @@ class VikingFS:
self.query_embedder = query_embedder
self.rerank_config = rerank_config
self.vector_store = vector_store
+ self.retrieval_config = retrieval_config
self._encryptor = encryptor
self._bound_ctx: contextvars.ContextVar[Optional[RequestContext]] = contextvars.ContextVar(
"vikingfs_bound_ctx", default=None
@@ -1113,6 +1118,7 @@ class VikingFS:
storage=storage,
embedder=embedder,
rerank_config=self.rerank_config,
+ retrieval_config=self.retrieval_config,
)
# Infer context_type (None = search all types)
@@ -1271,6 +1277,7 @@ class VikingFS:
storage=storage,
embedder=embedder,
rerank_config=self.rerank_config,
+ retrieval_config=self.retrieval_config,
)
async def _execute(tq: TypedQuery):
diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.py
index e0e23ca1b..04148b9cc 100644
--- a/openviking/utils/embedding_utils.py
+++ b/openviking/utils/embedding_utils.py
@@ -6,6 +6,7 @@ Embedding utilities for OpenViking.
Common logic for creating Context objects and enqueuing them to EmbeddingQueue.
"""
+import math
import os
from datetime import datetime, timezone
from typing import Dict, Optional
@@ -22,6 +23,46 @@ from openviking_cli.utils import VikingURI, get_logger
from openviking_cli.utils.config import get_openviking_config
logger = get_logger(__name__)
+_EMBEDDING_TRUNCATION_SUFFIX = "\n...(truncated for embedding)"
+
+
+def _estimate_embedding_input_tokens(text: str) -> int:
+ """Estimate tokens for the raw text embedding input guard."""
+ if not text:
+ return 0
+ cjk_chars = sum(
+ 1
+ for char in text
+ if "\u4e00" <= char <= "\u9fff"
+ or "\u3040" <= char <= "\u30ff"
+ or "\uac00" <= char <= "\ud7af"
+ )
+ other_chars = len(text) - cjk_chars
+ return max(1, cjk_chars + math.ceil(other_chars / 4))
+
+
+def _truncate_embedding_input(
+ text: str,
+ max_tokens: int,
+ suffix: str = _EMBEDDING_TRUNCATION_SUFFIX,
+) -> str:
+ """Trim raw text before embedding using the local estimate above."""
+ if not text:
+ return text
+ if max_tokens <= 0:
+ return suffix.lstrip()
+ if _estimate_embedding_input_tokens(text) <= max_tokens:
+ return text
+
+ low = 0
+ high = len(text)
+ while low < high:
+ mid = (low + high + 1) // 2
+ if _estimate_embedding_input_tokens(text[:mid]) <= max_tokens:
+ low = mid
+ else:
+ high = mid - 1
+ return text[:low].rstrip() + suffix
async def _decrement_embedding_tracker(semantic_msg_id: Optional[str], count: int) -> None:
@@ -326,14 +367,9 @@ async def vectorize_file(
content_type = get_resource_content_type(file_name)
embedding_cfg = get_openviking_config().embedding
- configured_text_source = getattr(embedding_cfg, "text_source", "summary_first")
+ configured_text_source = getattr(embedding_cfg, "text_source", "content_only")
effective_text_source = "summary_only" if use_summary else configured_text_source
- max_input_chars = int(getattr(embedding_cfg, "max_input_chars", 1000) or 1000)
-
- def _truncate_text(value: str) -> str:
- if len(value) <= max_input_chars:
- return value
- return value[:max_input_chars] + "\n...(truncated for embedding)"
+ max_input_tokens = int(getattr(embedding_cfg, "max_input_tokens", 4096) or 4096)
if content_type is None:
# Unsupported file type: fall back to summary if available
@@ -356,7 +392,7 @@ async def vectorize_file(
content = await viking_fs.read_file(file_path, ctx=ctx)
if isinstance(content, bytes):
content = content.decode("utf-8", errors="replace")
- content = _truncate_text(content)
+ content = _truncate_embedding_input(content, max_input_tokens)
context.set_vectorize(Vectorize(text=content))
except Exception as e:
logger.warning(
diff --git a/openviking_cli/utils/config/__init__.py b/openviking_cli/utils/config/__init__.py
index e600004cf..64a5a6489 100644
--- a/openviking_cli/utils/config/__init__.py
+++ b/openviking_cli/utils/config/__init__.py
@@ -77,6 +77,7 @@ from .parser_config import (
)
from .prompts_config import PromptsConfig
from .rerank_config import RerankConfig
+from .retrieval_config import RetrievalConfig
from .storage_config import StorageConfig
from .telemetry_config import TelemetryConfig, TracerConfig
from .vectordb_config import VectorDBBackendConfig
@@ -131,6 +132,7 @@ __all__ = [
"OpenVikingConfigSingleton",
"OVCLIConfig",
"RerankConfig",
+ "RetrievalConfig",
"StorageConfig",
"VectorDBBackendConfig",
"VLMConfig",
diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.py
index d490f1619..16e40c9c8 100644
--- a/openviking_cli/utils/config/embedding_config.py
+++ b/openviking_cli/utils/config/embedding_config.py
@@ -358,13 +358,13 @@ class EmbeddingConfig(BaseModel):
description="Maximum retry attempts for embedding provider calls (0 disables retry)",
)
text_source: str = Field(
- default="summary_first",
+ default="content_only",
description="Text source for file vectorization: summary_first|summary_only|content_only",
)
- max_input_chars: int = Field(
- default=1000,
+ max_input_tokens: int = Field(
+ default=4096,
ge=100,
- description="Maximum characters sent to embeddings when raw text fallback is used",
+ description="Maximum estimated tokens sent to embeddings when raw text fallback is used",
)
model_config = {"extra": "forbid"}
diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.py
index 46d85b35d..c8058e056 100644
--- a/openviking_cli/utils/config/open_viking_config.py
+++ b/openviking_cli/utils/config/open_viking_config.py
@@ -38,6 +38,7 @@ from .parser_config import (
)
from .prompts_config import PromptsConfig
from .rerank_config import RerankConfig
+from .retrieval_config import RetrievalConfig
from .storage_config import StorageConfig
from .telemetry_config import TelemetryConfig
from .vlm_config import VLMConfig
@@ -64,6 +65,11 @@ class OpenVikingConfig(BaseModel):
rerank: RerankConfig = Field(default_factory=RerankConfig, description="Rerank configuration")
+ retrieval: RetrievalConfig = Field(
+ default_factory=RetrievalConfig,
+ description="Retrieval ranking configuration",
+ )
+
# Encryption configuration
encryption: EncryptionConfig = Field(
default_factory=EncryptionConfig, description="Encryption configuration"
diff --git a/openviking_cli/utils/config/retrieval_config.py b/openviking_cli/utils/config/retrieval_config.py
new file mode 100644
index 000000000..b29c28ecd
--- /dev/null
+++ b/openviking_cli/utils/config/retrieval_config.py
@@ -0,0 +1,30 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from pydantic import BaseModel, Field
+
+
+class RetrievalConfig(BaseModel):
+ """Configuration for retrieval ranking behavior."""
+
+ hotness_alpha: float = Field(
+ default=0.0,
+ ge=0.0,
+ le=1.0,
+ description=(
+ "Weight for blending hotness into final retrieval scores. "
+ "0 disables hotness boost; 1 uses only hotness."
+ ),
+ )
+ score_propagation_alpha: float = Field(
+ default=0.5,
+ ge=0.0,
+ le=1.0,
+ description=(
+ "Weight for each child result's own score when blending with its parent score "
+ "during hierarchical retrieval. 0 uses only the parent score; "
+ "1 uses only the child score."
+ ),
+ )
+
+ model_config = {"extra": "forbid"}
diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.py
index 45af89ee6..36bb233ca 100644
--- a/tests/retrieve/test_hierarchical_retriever_rerank.py
+++ b/tests/retrieve/test_hierarchical_retriever_rerank.py
@@ -9,7 +9,7 @@ from openviking.retrieve.hierarchical_retriever import HierarchicalRetriever, Re
from openviking.server.identity import RequestContext, Role
from openviking_cli.retrieve.types import ContextType, TypedQuery
from openviking_cli.session.user_id import UserIdentifier
-from openviking_cli.utils.config import RerankConfig
+from openviking_cli.utils.config import RerankConfig, RetrievalConfig
class DummyEmbedResult:
@@ -182,6 +182,35 @@ class LevelTwoGlobalStorage(DummyStorage):
return []
+class DirectChildProxy:
+ async def search_children_in_tenant(
+ self,
+ parent_uri: str,
+ query_vector=None,
+ sparse_query_vector=None,
+ context_type=None,
+ target_directories=None,
+ extra_filter=None,
+ limit: int = 10,
+ ):
+ return [
+ {
+ "uri": f"{parent_uri}/file-a",
+ "abstract": "child A",
+ "_score": 0.2,
+ "level": 2,
+ "context_type": "resource",
+ },
+ {
+ "uri": f"{parent_uri}/file-b",
+ "abstract": "child B",
+ "_score": 0.8,
+ "level": 2,
+ "context_type": "resource",
+ },
+ ]
+
+
class FakeRerankClient:
def __init__(self, scores):
self.scores = list(scores)
@@ -366,3 +395,83 @@ async def test_quick_mode_skips_rerank(monkeypatch):
"viking://resources/file-a",
]
assert fake_client.calls == []
+
+
+async def test_score_propagation_alpha_uses_configured_weight():
+ retriever = HierarchicalRetriever(
+ storage=DummyStorage(),
+ embedder=None,
+ rerank_config=None,
+ retrieval_config=RetrievalConfig(score_propagation_alpha=1.0),
+ )
+
+ candidates = await retriever._recursive_search(
+ vector_proxy=DirectChildProxy(),
+ query="hello",
+ query_vector=None,
+ sparse_query_vector=None,
+ starting_points=[("viking://resources", 0.4)],
+ limit=1,
+ mode=RetrieverMode.QUICK,
+ )
+
+ assert candidates[0]["uri"] == "viking://resources/file-b"
+ assert candidates[0]["_final_score"] == pytest.approx(0.8)
+
+
+async def test_default_retrieval_config_uses_semantic_score_without_hotness(monkeypatch):
+ monkeypatch.setattr(
+ "openviking.retrieve.hierarchical_retriever.hotness_score",
+ lambda *args, **kwargs: pytest.fail("hotness_score should not be called by default"),
+ )
+ retriever = HierarchicalRetriever(
+ storage=DummyStorage(),
+ embedder=None,
+ rerank_config=None,
+ )
+
+ result = await retriever._convert_to_matched_contexts(
+ [
+ {
+ "uri": "viking://resources/file-a",
+ "abstract": "child A",
+ "_score": 1.0,
+ "level": 2,
+ "context_type": "resource",
+ }
+ ],
+ ctx=_ctx(),
+ )
+
+ assert result[0].score == pytest.approx(1.0)
+
+
+async def test_retrieval_hotness_alpha_blends_when_configured(monkeypatch):
+ monkeypatch.setattr(
+ "openviking.retrieve.hierarchical_retriever.hotness_score",
+ lambda *args, **kwargs: 0.5,
+ )
+ retriever = HierarchicalRetriever(
+ storage=DummyStorage(),
+ embedder=None,
+ rerank_config=None,
+ retrieval_config=RetrievalConfig(hotness_alpha=0.2),
+ )
+
+ result = await retriever._convert_to_matched_contexts(
+ [
+ {
+ "uri": "viking://resources/file-a",
+ "abstract": "child A",
+ "_score": 1.0,
+ "level": 2,
+ "context_type": "resource",
+ }
+ ],
+ ctx=_ctx(),
+ )
+
+ assert result[0].score == pytest.approx(0.9)
diff --git a/tests/test_config_loader.py b/tests/test_config_loader.py
index 39dc0b7ca..a9ed1455d 100644
--- a/tests/test_config_loader.py
+++ b/tests/test_config_loader.py
@@ -186,6 +186,37 @@ def test_openviking_config_warns_when_agent_scope_mode_is_configured(monkeypatch
OpenVikingConfigSingleton.reset_instance()
+def test_openviking_config_retrieval_hotness_alpha_defaults_to_zero(monkeypatch):
+ monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")
+
+ from openviking_cli.utils.config.open_viking_config import (
+ OpenVikingConfig,
+ OpenVikingConfigSingleton,
+ )
+
+ config = OpenVikingConfig.from_dict({})
+
+ assert config.retrieval.hotness_alpha == 0.0
+ assert config.retrieval.score_propagation_alpha == 0.5
+
+ OpenVikingConfigSingleton.reset_instance()
+
+
[email protected]("field_name", ["hotness_alpha", "score_propagation_alpha"])
+def test_openviking_config_retrieval_alpha_validates_range(monkeypatch, field_name):
+ monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")
+
+ from openviking_cli.utils.config.open_viking_config import (
+ OpenVikingConfig,
+ OpenVikingConfigSingleton,
+ )
+
+ with pytest.raises(ValueError):
+ OpenVikingConfig.from_dict({"retrieval": {field_name: 1.5}})
+
+ OpenVikingConfigSingleton.reset_instance()
+
+
def test_openviking_config_singleton_preserves_value_error_for_bad_config(tmp_path, monkeypatch):
monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")
diff --git a/tests/test_memory_lifecycle.py b/tests/test_memory_lifecycle.py
index f5b68730f..af4a9eabd 100644
--- a/tests/test_memory_lifecycle.py
+++ b/tests/test_memory_lifecycle.py
@@ -106,8 +106,8 @@ class TestHotnessBlending:
# B should overtake A due to hotness
assert blended_b > blended_a
- def test_default_alpha_preserves_semantic_dominance(self):
- """With default alpha=0.2, a large semantic gap is not overturned."""
+ def test_small_alpha_preserves_semantic_dominance(self):
+ """With a small alpha, a large semantic gap is not overturned."""
alpha = 0.2
# Memory A: much higher semantic, cold
diff --git a/tests/unit/test_embedding_vectorize_strategy.py b/tests/unit/test_embedding_vectorize_strategy.py
index 7bbb2c28c..bfd6a8c1c 100644
--- a/tests/unit/test_embedding_vectorize_strategy.py
+++ b/tests/unit/test_embedding_vectorize_strategy.py
@@ -25,17 +25,23 @@ def test_embedding_text_source_validation_accepts_supported_values():
assert cfg.text_source == value
+def test_embedding_text_source_defaults_to_content_only():
+ cfg = _cfg()
+ assert cfg.text_source == "content_only"
+ assert cfg.max_input_tokens == 4096
+
+
@pytest.mark.parametrize("bad_value", ["summary", "content", "auto", ""])
def test_embedding_text_source_validation_rejects_invalid_values(bad_value):
with pytest.raises(ValueError, match="embedding.text_source"):
_cfg(text_source=bad_value)
-def test_embedding_max_input_chars_validation_accepts_reasonable_value():
- cfg = _cfg(max_input_chars=1000)
- assert cfg.max_input_chars == 1000
+def test_embedding_max_input_tokens_validation_accepts_reasonable_value():
+ cfg = _cfg(max_input_tokens=1000)
+ assert cfg.max_input_tokens == 1000
-def test_embedding_max_input_chars_validation_rejects_too_small_value():
+def test_embedding_max_input_tokens_validation_rejects_too_small_value():
with pytest.raises(ValueError):
- _cfg(max_input_chars=10)
+ _cfg(max_input_tokens=10)
diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.py
index 5be9a387e..0eded560d 100644
--- a/tests/unit/test_vectorize_file_strategy.py
+++ b/tests/unit/test_vectorize_file_strategy.py
@@ -34,6 +34,8 @@ class DummyFS:
class DummyUser:
account_id = "default"
+ user_id = "default"
+ agent_id = "default-agent"
def user_space_name(self):
return "user/default"
@@ -46,6 +48,10 @@ class DummyReq:
def __init__(self):
self.user = DummyUser()
self.account_id = "default"
+ self.namespace_policy = types.SimpleNamespace(
+ isolate_user_scope_by_agent=False,
+ isolate_agent_scope_by_user=False,
+ )
@pytest.mark.asyncio
@@ -57,7 +63,7 @@ async def test_vectorize_file_uses_summary_first(monkeypatch):
embedding_utils,
"get_openviking_config",
lambda: types.SimpleNamespace(
- embedding=types.SimpleNamespace(text_source="summary_first", max_input_chars=1000)
+ embedding=types.SimpleNamespace(text_source="summary_first", max_input_tokens=1000)
),
)
monkeypatch.setattr(
@@ -81,13 +87,14 @@ async def test_vectorize_file_uses_summary_first(monkeypatch):
@pytest.mark.asyncio
async def test_vectorize_file_truncates_content_when_content_only(monkeypatch):
queue = DummyQueue()
+ content = " ".join(f"token-{i}" for i in range(200))
monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))
- monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("A" * 1500))
+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS(content))
monkeypatch.setattr(
embedding_utils,
"get_openviking_config",
lambda: types.SimpleNamespace(
- embedding=types.SimpleNamespace(text_source="content_only", max_input_chars=1000)
+ embedding=types.SimpleNamespace(text_source="content_only", max_input_tokens=20)
),
)
monkeypatch.setattr(
@@ -105,5 +112,5 @@ async def test_vectorize_file_truncates_content_when_content_only(monkeypatch):
assert len(queue.items) == 1
text = queue.items[0].get_vectorization_text()
- assert text.startswith("A" * 1000)
assert text.endswith("...(truncated for embedding)")
+ assert "token-199" not in text