Skip to content

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

fix(embedding): deprecate summary_only without dropping content fallback (#5056)

Evod53e3d584306
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index d31ded75d..f96531c38 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -213,7 +213,7 @@ Embedding model configuration for vector search, supporting dense, sparse, and h
|-----------|------|-------------|
| `max_concurrent` | int | Maximum concurrent embedding requests (`embedding.max_concurrent`, default: `10`; must be `>= 1`) |
| `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` |
+| `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` is a deprecated alias for `summary_first`; existing configurations still load, log a warning, and normalize to `summary_first`. 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 | `"openai"`, `"azure"`, `"volcengine"`, `"vikingdb"`, `"jina"`, `"ollama"`, `"gemini"`, `"voyage"`, `"dashscope"`, `"minimax"`, `"cohere"`, `"litellm"`, or `"local"` |
| `api_key` | str | API key |
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index c711b05e6..721efb62e 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -215,7 +215,7 @@ openviking-server doctor
|------|------|------|
| `max_concurrent` | int | 最大并发 Embedding 请求数(`embedding.max_concurrent`,默认:`10`;必须 `>= 1`) |
| `max_retries` | int | Embedding provider 瞬时错误的最大重试次数(`embedding.max_retries`,默认:`3`;`0` 表示禁用重试) |
-| `text_source` | str | 文本文件向量化时使用的文本来源。`content_only` 读取原文内容;`summary_first` 优先使用摘要,没有摘要时回退到原文;`summary_only` 只使用摘要。默认:`content_only` |
+| `text_source` | str | 文本文件向量化时使用的文本来源。`content_only` 读取原文内容;`summary_first` 优先使用摘要,没有摘要时回退到原文;`summary_only` 已弃用,作为 `summary_first` 的兼容别名;旧配置仍可加载,会记录警告并归一为 `summary_first`。默认:`content_only` |
| `max_input_tokens` | int | 使用原文内容向量化时,发送给 embedding 模型的最大估算 token 数。默认:`4096` |
| `provider` | str | `"openai"`、`"azure"`、`"volcengine"`、`"vikingdb"`、`"jina"`、`"ollama"`、`"gemini"`、`"voyage"`、`"dashscope"`、`"minimax"`、`"cohere"`、`"litellm"` 或 `"local"` |
| `api_key` | str | API Key |
diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.py
index 57f20638b..9488c6bb8 100644
--- a/openviking/utils/embedding_utils.py
+++ b/openviking/utils/embedding_utils.py
@@ -40,7 +40,7 @@ from openviking_cli.utils import VikingURI, get_logger
from openviking_cli.utils.config import get_openviking_config
from openviking_cli.utils.config.embedding_config import (
SUMMARY_TEXT_SOURCES,
- TEXT_SOURCE_SUMMARY_ONLY,
+ TEXT_SOURCE_SUMMARY_FIRST,
)
logger = get_logger(__name__)
@@ -552,7 +552,7 @@ async def vectorize_file(
content_type = await _resolve_resource_content_type(file_path, file_name, viking_fs, ctx)
embedding_cfg = get_openviking_config().embedding
configured_text_source = embedding_cfg.text_source
- effective_text_source = TEXT_SOURCE_SUMMARY_ONLY if use_summary else configured_text_source
+ effective_text_source = TEXT_SOURCE_SUMMARY_FIRST if use_summary else configured_text_source
embed_summary = bool(summary and effective_text_source in SUMMARY_TEXT_SOURCES)
if content_type in (ResourceContentType.AUDIO, ResourceContentType.VIDEO):
diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.py
index bb0c6b0b2..aba2242c2 100644
--- a/openviking_cli/utils/config/embedding_config.py
+++ b/openviking_cli/utils/config/embedding_config.py
@@ -4,10 +4,13 @@ from typing import Any, ClassVar, List, Literal, Optional, Tuple, cast
from pydantic import BaseModel, Field, model_validator
+from openviking_cli.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
TEXT_SOURCE_CONTENT_ONLY = "content_only"
TEXT_SOURCE_SUMMARY_FIRST = "summary_first"
-TEXT_SOURCE_SUMMARY_ONLY = "summary_only"
-SUMMARY_TEXT_SOURCES = frozenset({TEXT_SOURCE_SUMMARY_FIRST, TEXT_SOURCE_SUMMARY_ONLY})
+SUMMARY_TEXT_SOURCES = frozenset({TEXT_SOURCE_SUMMARY_FIRST})
TEXT_SOURCES = SUMMARY_TEXT_SOURCES | {TEXT_SOURCE_CONTENT_ONLY}
@@ -649,7 +652,7 @@ class EmbeddingConfig(BaseModel):
)
text_source: str = Field(
default=TEXT_SOURCE_CONTENT_ONLY,
- description="Text source for file vectorization: summary_first|summary_only|content_only",
+ description="Text source for file vectorization: summary_first|content_only",
)
max_input_tokens: int = Field(
default=4096,
@@ -695,10 +698,14 @@ class EmbeddingConfig(BaseModel):
raise ValueError(
"At least one embedding configuration (dense, sparse, or hybrid) is required"
)
- if self.text_source not in TEXT_SOURCES:
- raise ValueError(
- "embedding.text_source must be one of: summary_first, summary_only, content_only"
+ if self.text_source == "summary_only":
+ logger.warning(
+ "embedding.text_source=summary_only is deprecated; use summary_first instead. "
+ "Files without a summary still fall back to content for vectorization."
)
+ self.text_source = TEXT_SOURCE_SUMMARY_FIRST
+ if self.text_source not in TEXT_SOURCES:
+ raise ValueError("embedding.text_source must be one of: summary_first, content_only")
return self
def _create_embedder(
diff --git a/tests/unit/test_embedding_vectorize_strategy.py b/tests/unit/test_embedding_vectorize_strategy.py
index 1f3743a1e..22ef058a7 100644
--- a/tests/unit/test_embedding_vectorize_strategy.py
+++ b/tests/unit/test_embedding_vectorize_strategy.py
@@ -20,11 +20,18 @@ def _cfg(**kwargs):
def test_embedding_text_source_validation_accepts_supported_values():
- for value in ["summary_first", "summary_only", "content_only"]:
+ for value in ["summary_first", "content_only"]:
cfg = _cfg(text_source=value)
assert cfg.text_source == value
+def test_embedding_legacy_summary_only_normalizes_and_round_trips(caplog):
+ cfg = _cfg(text_source="summary_only")
+ assert cfg.text_source == "summary_first"
+ assert "summary_only is deprecated" in caplog.text
+ assert EmbeddingConfig.model_validate_json(cfg.model_dump_json()).text_source == "summary_first"
+
+
def test_embedding_text_source_defaults_to_content_only():
cfg = _cfg()
assert cfg.text_source == "content_only"
diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.py
index 1efe1a980..3d9853d31 100644
--- a/tests/unit/test_vectorize_file_strategy.py
+++ b/tests/unit/test_vectorize_file_strategy.py
@@ -165,26 +165,38 @@ async def test_vectorize_disambiguates_typescript_and_mpeg_ts(monkeypatch):
@pytest.mark.asyncio
-async def test_vectorize_file_uses_summary_first(monkeypatch):
[email protected]("text_source", ["summary_first", "summary_only"])
[email protected]("summary", ["short summary", ""])
+async def test_vectorize_file_uses_summary_first(monkeypatch, text_source, summary):
+ from openviking_cli.utils.config.embedding_config import EmbeddingConfig
+
+ cfg = EmbeddingConfig(
+ dense={
+ "provider": "openai",
+ "model": "text-embedding-3-small",
+ "api_base": "http://localhost:8080/v1",
+ "dimension": 1536,
+ },
+ text_source=text_source,
+ max_input_tokens=1000,
+ )
queue = DummyQueue()
monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))
- monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("X" * 5000))
+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("raw content"))
monkeypatch.setattr(
embedding_utils,
"get_openviking_config",
- lambda: types.SimpleNamespace(
- embedding=types.SimpleNamespace(text_source="summary_first", max_input_tokens=1000)
- ),
+ lambda: types.SimpleNamespace(embedding=cfg),
)
await embedding_utils.vectorize_file(
file_path="viking://user/default/resources/test.md",
- summary_dict={"name": "test.md", "summary": "short summary"},
+ summary_dict={"name": "test.md", "summary": summary},
parent_uri="viking://user/default/resources",
ctx=DummyReq(),
)
assert len(queue.items) == 1
- assert queue.items[0].message == "short summary"
+ assert queue.items[0].message == (summary or "raw content")
assert "content" not in queue.items[0].context_data