Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.mdindex 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.mdindex 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.pyindex 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_loggerfrom openviking_cli.utils.config import get_openviking_configfrom 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().embeddingconfigured_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_sourceembed_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.pyindex 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, castfrom 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 selfdef _create_embedder(diff --git a/tests/unit/test_embedding_vectorize_strategy.py b/tests/unit/test_embedding_vectorize_strategy.pyindex 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.pyindex 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