Skip to content

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

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.md
index 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.md
index 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.yaml
new file mode 100644
index 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.0
diff --git a/openviking/retrieve/intent_analyzer.py b/openviking/retrieve/intent_analyzer.py
index 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.py
index 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.py
index 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_dict
assert 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_q8
patch("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.py
index 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")