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
feat(retrieval): recommend ov_intent_analysis_sft v7_q8 query planner (#2624)
Guoxuter9506101bd305
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex cc6fd0e4c..06f38e445 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -692,12 +692,12 @@ Optional lightweight model for retrieval intent analysis and query planning. It> In `openviking-server init` you can optionally enable a local lightweight query planner; the wizard pulls the Ollama model and writes the `query_planner` config for you. For recognized query-planner models, `search()` selects the matching bundled prompt at runtime. Models not in the mapping keep using `retrieval.intent_analysis`.-We recommend the local Ollama model [`guoxuter/ov_intent_analysis_sft:v4_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v4_q8). Fine-tuned from Qwen3.5-0.8B, it can be deployed locally and is well suited to letting a small model handle retrieval planning: for small talk, greetings, or turns where the context is already sufficient, it returns no queries to reduce unnecessary memory injection and token consumption; when retrieval is needed, it emits structured queries targeting `skill`, `resource`, and `memory`.+We recommend the local Ollama model [`guoxuter/ov_intent_analysis_sft:v7_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v7_q8). Fine-tuned from Qwen3.5-0.8B, it can be deployed locally and is well suited to letting a small model handle retrieval planning: for small talk, greetings, or turns where the context is already sufficient, it returns no queries to reduce unnecessary memory injection and token consumption; when retrieval is needed, it emits structured queries targeting `skill`, `resource`, and `memory`. The earlier [`v4_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v4_q8) revision is still supported as an alternative.Pull the model first and make sure the Ollama service is reachable:```bash-ollama pull guoxuter/ov_intent_analysis_sft:v4_q8+ollama pull guoxuter/ov_intent_analysis_sft:v7_q8```Then add the following to your OpenViking configuration:@@ -706,7 +706,7 @@ Then add the following to your OpenViking configuration:{"query_planner": {"provider": "litellm",- "model": "ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ "model": "ollama/guoxuter/ov_intent_analysis_sft:v7_q8","api_base": "http://127.0.0.1:11434","temperature": 0.0,"timeout": 60,@@ -717,7 +717,7 @@ Then add the following to your OpenViking configuration:}```-For `ollama/guoxuter/ov_intent_analysis_sft:v4_q8`, OpenViking automatically uses the bundled `retrieval.ov_intent_analysis_sft_v4` prompt during search. No prompt file replacement or `prompts.templates_dir` override is required. If you use an unmapped model, OpenViking keeps the default `retrieval.intent_analysis` prompt; `v1_q8` remains compatible with that default.+For `ollama/guoxuter/ov_intent_analysis_sft:v7_q8` (and `v4_q8`), OpenViking automatically uses the matching bundled prompt during search (`retrieval.ov_intent_analysis_sft_v7` and `retrieval.ov_intent_analysis_sft_v4` respectively). No prompt file replacement or `prompts.templates_dir` override is required. If you use an unmapped model, OpenViking keeps the default `retrieval.intent_analysis` prompt.This lets a small model handle retrieval planning with lower latency, while keeping a stronger `vlm` for semantic extraction, memory extraction, and multimodal processing.diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex c05c82d7c..e945500a2 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -662,12 +662,12 @@ LiteLLM 的 Bedrock bearer-token API-key 鉴权,请设置 `forward_api_key=tru> 在 `openviking-server init` 里可勾选启用本地轻量 query planner,向导会自动拉取 Ollama 模型并写入 `query_planner` 配置。对于已知的 query planner 模型,`search()` 会在运行时自动选择匹配的内置 prompt;不在映射表中的模型继续使用 `retrieval.intent_analysis`。-推荐优先使用本地 Ollama 模型 [`guoxuter/ov_intent_analysis_sft:v4_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v4_q8)。该模型基于 Qwen3.5-0.8B 进行微调,可本地部署,适合用小模型承担检索规划:在闲聊、问候或上下文已足够的场景下拒绝检索,从而减少不必要的记忆注入和 token 消耗;需要检索时,再生成面向 `skill`、`resource`、`memory` 的结构化查询。+推荐优先使用本地 Ollama 模型 [`guoxuter/ov_intent_analysis_sft:v7_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v7_q8)。该模型基于 Qwen3.5-0.8B 进行微调,可本地部署,适合用小模型承担检索规划:在闲聊、问候或上下文已足够的场景下拒绝检索,从而减少不必要的记忆注入和 token 消耗;需要检索时,再生成面向 `skill`、`resource`、`memory` 的结构化查询。此前的 [`v4_q8`](https://ollama.com/guoxuter/ov_intent_analysis_sft:v4_q8) 版本仍作为可选项继续支持。使用前请先拉取模型,并确保 Ollama 服务可访问:```bash-ollama pull guoxuter/ov_intent_analysis_sft:v4_q8+ollama pull guoxuter/ov_intent_analysis_sft:v7_q8```然后在 OpenViking 配置中添加:@@ -676,7 +676,7 @@ ollama pull guoxuter/ov_intent_analysis_sft:v4_q8{"query_planner": {"provider": "litellm",- "model": "ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ "model": "ollama/guoxuter/ov_intent_analysis_sft:v7_q8","api_base": "http://127.0.0.1:11434","temperature": 0.0,"timeout": 60,@@ -687,7 +687,7 @@ ollama pull guoxuter/ov_intent_analysis_sft:v4_q8}```-对于 `ollama/guoxuter/ov_intent_analysis_sft:v4_q8`,OpenViking 会在 search 阶段自动使用内置的 `retrieval.ov_intent_analysis_sft_v4` prompt,不需要替换 prompt 文件,也不需要设置 `prompts.templates_dir`。如果使用未映射的模型,OpenViking 会继续使用默认的 `retrieval.intent_analysis` prompt;`v1_q8` 与该默认 prompt 兼容。+对于 `ollama/guoxuter/ov_intent_analysis_sft:v7_q8`(以及 `v4_q8`),OpenViking 会在 search 阶段自动使用对应的内置 prompt(分别为 `retrieval.ov_intent_analysis_sft_v7` 和 `retrieval.ov_intent_analysis_sft_v4`),不需要替换 prompt 文件,也不需要设置 `prompts.templates_dir`。如果使用未映射的模型,OpenViking 会继续使用默认的 `retrieval.intent_analysis` prompt。这样可以用小模型承担检索规划,降低延迟,同时保留更强的 `vlm` 处理语义提取、记忆提取和多模态内容。diff --git a/openviking/prompts/templates/retrieval/ov_intent_analysis_sft_v7.yaml b/openviking/prompts/templates/retrieval/ov_intent_analysis_sft_v7.yamlnew file mode 100644index 000000000..46f5390f0--- /dev/null+++ b/openviking/prompts/templates/retrieval/ov_intent_analysis_sft_v7.yaml@@ -0,0 +1,177 @@+metadata:+ # Loaded directly through the query-planner model -> prompt mapping in+ # openviking.retrieve.intent_analyzer.+ id: "retrieval.ov_intent_analysis_sft_v7"+ name: "Intent Analysis v7"+ description: "v7 prompt for the ov_intent_analysis_sft query-planner model."+ version: "7.0.0"+ language: "en"+ category: "retrieval"++variables:+ - name: "compression_summary"+ type: "string"+ description: "Session summary"+ default: ""+ required: false++ - name: "recent_messages"+ type: "string"+ description: "Recent conversation"+ required: true++ - name: "current_message"+ type: "string"+ description: "Current message"+ required: true++ - name: "context_type"+ type: "string"+ description: "Restricted context type (skill/resource/memory)"+ default: ""+ required: false++ - name: "target_abstract"+ type: "string"+ description: "Abstract of target directory"+ default: ""+ required: false++template: |+ You are OpenViking's context query planner, responsible for analyzing task context gaps and generating queries.++ ## Session Context++ ### Session Summary+ {{ compression_summary }}++ ### Recent Conversation+ {{ recent_messages }}++ ### Current Message+ {{ current_message }}+ {% if context_type %}++ ## Search Scope Constraints++ **Restricted Context Type**: {{ context_type }}+ {% if target_abstract %}+ **Target Directory Abstract**: {{ target_abstract }}+ {% endif %}++ **Important**: You can only generate `{{ context_type }}` type queries, do not generate other types.+ {% endif %}++ ## Your Task++ Analyze the current task, identify context gaps, and generate queries to fill in the required information.++ **Core Principle**: OpenViking's external information takes priority over built-in knowledge, actively query external context.++ ## Context Types and Query Styles++ OpenViking supports the following context types, **each type has a different query style**:++ ### 1. skill (Execution Capability)++ **Purpose**: Executable tools, functions, APIs, automation scripts++ **When to Query**:+ - Task contains action verbs (create, generate, write, build, analyze, process)+ - Need to perform specific operations++ ### 2. resource (Knowledge Resources)++ **Purpose**: Documents, specifications, guides, code, configurations, and other structured knowledge++ **When to Query**:+ - Need reference materials, templates, specifications+ - Need to understand knowledge, concepts, definitions++ ### 3. memory (User/Agent Memory)++ **Purpose**: User personalization information or Agent execution experience++ **When to Query**:+ - Need personalized customization (user memory)+ - Need to learn from historical experience (agent memory)++ ## Analysis Method++ ### Step 1: Identify Task Type++ **Operational Tasks** (containing actions):+ - Characteristics: Verbs like create, generate, write, build, transform, calculate, analyze, process+ - Typical context combination: `skill + resource + memory`++ **Informational Tasks** (acquiring knowledge):+ - Characteristics: What is, how to understand, why, concept explanation, etc.+ - Typical context combination: `resource + memory`++ **Conversational Tasks** (small talk):+ - Characteristics: Greetings, small talk, confirmation of understanding, etc.+ - Usually no query needed++ ### Step 2: Check Context Coverage++ Analyze whether the session context (summary + recent conversation) already contains the information needed to complete the task:++ - **Fully covered**: Skip queries for that type+ - **Partially covered**: Generate supplementary queries+ - **Not covered**: Generate complete queries++ **Note**: Only skip information that has been **explicitly and in detail** discussed in the context.++ ### Step 3: Generate Queries++ **Important Principles**:++ 1. **Don't over-transform**:+ - ❌ Don't convert "Create XX" to "XX format/specification"++ 2. **Multi-type combination**:+ - A task may require multiple context types+ - Operational tasks typically need: skill (execution) + resource (reference) + memory (preference/experience)++ 3. **Multiple queries per type**:+ - Can generate multiple queries for the same type+ - Maximum 5 queries++ 4. **Queries should be concise and specific**:+ - Queries should be short, specific, and retrievable+ - Avoid lengthy descriptions++ 5. **Priority setting**:+ - 1 = Highest priority (core requirement)+ - 3 = Medium priority (helpful)+ - 5 = Lowest priority (optional)++ 6. **Query Style** (optimize for vector / semantic retrieval):+ - Queries are embedded and matched against indexed content by **semantic similarity**. Write each query so its embedding lands close to the target content — not necessarily a verbatim fragment, any phrasing that captures the same meaning works.+ - **Declarative, not interrogative**: state the information need as a noun/verb phrase rather than a question. Drop question framings ("what / who / when / how is ...").+ - **One information need per query**: each query targets one retrievable fact, relation, comparison, event, or procedure. Do not pile unrelated intents into one query.+ - **Self-contained**: resolve pronouns and references using the session context; the retriever only sees the query string.+ - **Concept-dense and natural**: use a grammatical, well-formed phrase carrying the key entities, attributes, and qualifiers. Avoid both bare single keywords and telegraphic word-salad.+ - **No retrieval-meta words**: exclude words describing the act of retrieval or generic containers ("find", "search", "records", "information about", "content", "details", etc.) — they do not appear in the target content and only dilute the embedding.+ - **Keep discriminative specifics**: preserve names, dates, places, and domain terms from the task — they anchor the embedding to the right content.++ ## Output Format++ ```json+ {+ "reasoning": "1. Task type (operational/informational/conversational); 2. What context is needed (skill/resource/memory); 3. What is already in context; 4. What is missing and needs to be queried",+ "queries": [+ {+ "query": "Specific query text (following the style of the corresponding type)",+ "context_type": "skill|resource|memory",+ "intent": "Purpose of the query",+ "priority": 1-5+ }+ ]+ }+ ```++ Please output JSON:++llm_config:+ temperature: 0.0diff --git a/openviking/retrieve/intent_analyzer.py b/openviking/retrieve/intent_analyzer.pyindex af6498485..2c92708d8 100644--- a/openviking/retrieve/intent_analyzer.py+++ b/openviking/retrieve/intent_analyzer.py@@ -22,6 +22,7 @@ DEFAULT_INTENT_ANALYSIS_PROMPT = "retrieval.intent_analysis"# Model-specific query-planner prompts. Models not listed here keep using the# default intent-analysis prompt for backward compatibility.QUERY_PLANNER_PROMPT_BY_MODEL: dict[str, str] = {+ "ollama/guoxuter/ov_intent_analysis_sft:v7_q8": "retrieval.ov_intent_analysis_sft_v7","ollama/guoxuter/ov_intent_analysis_sft:v4_q8": "retrieval.ov_intent_analysis_sft_v4",}diff --git a/openviking_cli/setup_wizard.py b/openviking_cli/setup_wizard.pyindex 594208ac7..ff9171588 100644--- a/openviking_cli/setup_wizard.py+++ b/openviking_cli/setup_wizard.py@@ -405,16 +405,16 @@ VLM_PRESETS: list[VLMPreset] = [# intent analyzer based on the configured model name.QUERY_PLANNER_PRESETS: list[QueryPlannerPreset] = [QueryPlannerPreset(- "ov_intent_analysis_sft v4_q8",- "guoxuter/ov_intent_analysis_sft:v4_q8",- "ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ "ov_intent_analysis_sft v7_q8",+ "guoxuter/ov_intent_analysis_sft:v7_q8",+ "ollama/guoxuter/ov_intent_analysis_sft:v7_q8","~0.8B, recommended",),QueryPlannerPreset(- "ov_intent_analysis_sft v1_q8",- "guoxuter/ov_intent_analysis_sft:v1_q8",- "ollama/guoxuter/ov_intent_analysis_sft:v1_q8",- "~0.8B, compatible with the bundled prompt",+ "ov_intent_analysis_sft v4_q8",+ "guoxuter/ov_intent_analysis_sft:v4_q8",+ "ollama/guoxuter/ov_intent_analysis_sft:v4_q8",+ "~0.8B",),]diff --git a/tests/cli/test_setup_wizard.py b/tests/cli/test_setup_wizard.pyindex 21510ee9a..8e767ed01 100644--- a/tests/cli/test_setup_wizard.py+++ b/tests/cli/test_setup_wizard.py@@ -507,14 +507,14 @@ class TestQueryPlanner:assert "prompts" not in config_dictassert not (config_path.parent / "prompts").exists()- def test_wizard_v1_sets_planner_and_returns_none(self, tmp_path):+ def test_wizard_v4_sets_planner_and_returns_none(self, tmp_path):config_dict: dict = {"embedding": {}, "vlm": {}}config_path = tmp_path / "ov.conf"with (patch.dict(os.environ, {"OPENVIKING_CONFIG_FILE": str(config_path)}, clear=False),patch("openviking_cli.setup_wizard._prompt_confirm", return_value=True),patch("openviking_cli.setup_wizard.get_ollama_models", return_value=[]),- patch("openviking_cli.setup_wizard._prompt_choice", return_value=2), # v1_q8+ patch("openviking_cli.setup_wizard._prompt_choice", return_value=2), # v4_q8patch("openviking_cli.setup_wizard.is_model_available", return_value=True),patch("builtins.print"),):diff --git a/tests/retrieve/test_intent_analyzer_query_planner.py b/tests/retrieve/test_intent_analyzer_query_planner.pyindex 8e9e47d3e..234eda7d6 100644--- a/tests/retrieve/test_intent_analyzer_query_planner.py+++ b/tests/retrieve/test_intent_analyzer_query_planner.py@@ -60,6 +60,12 @@ def test_openviking_config_uses_vlm_when_query_planner_is_absent_or_empty():def test_query_planner_prompt_mapping_defaults_for_unknown_models():+ assert (+ intent_module.resolve_intent_analysis_prompt_id(+ SimpleNamespace(model="ollama/guoxuter/ov_intent_analysis_sft:v7_q8")+ )+ == "retrieval.ov_intent_analysis_sft_v7"+ )assert (intent_module.resolve_intent_analysis_prompt_id(SimpleNamespace(model="ollama/guoxuter/ov_intent_analysis_sft:v4_q8")