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(search) Add lightweight query planner config for intent analysis (#2224)
agent2b5fb5bd7ad7
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 42ef8cbac..cdb50b738 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -686,6 +686,29 @@ For OpenAI-compatible providers that return SSE (Server-Sent Events) format resp> **Note**: The OpenAI SDK requires `stream=true` to properly parse SSE responses. When using providers that force SSE format, you must set this option to `true`.+### query_planner++Optional lightweight model for retrieval intent analysis and query planning. It uses the same configuration shape as `vlm`, but only affects `search()` intent analysis and query expansion. If `query_planner` is omitted or empty, OpenViking falls back to `vlm` for backward compatibility.++Only add this section when the planner model is already available in your environment. For example, the Ollama model below must be pulled and served locally before use.++```json+{+ "query_planner": {+ "provider": "litellm",+ "model": "ollama/guoxuter/ov_intent_analysis_sft:v1_q8",+ "api_base": "http://127.0.0.1:11434",+ "temperature": 0.0,+ "timeout": 60,+ "extra_request_body": {+ "think": false+ }+ }+}+```++Use `query_planner` when you want a smaller or cheaper model to handle retrieval planning while keeping a stronger `vlm` for semantic extraction, memory extraction, and multimodal processing.+### feishuConfiguration for Feishu/Lark cloud document parsing. See [Resources](../api/02-resources.md) for supported URL patterns.diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex aa36ce5a4..33cb3b65c 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -656,6 +656,29 @@ LiteLLM 的 Bedrock bearer-token API-key 鉴权,请设置 `forward_api_key=tru> **注意**: OpenAI SDK 需要 `stream=true` 才能正确解析 SSE 响应。使用强制返回 SSE 格式的 provider 时,必须将此选项设置为 `true`。+### query_planner++可选的轻量模型配置,用于检索前的意图分析和 query 规划/改写。配置结构与 `vlm` 相同,但只影响 `search()` 的意图分析和 query expansion。未配置或配置为空时,OpenViking 会回退到 `vlm`,保持向后兼容。++只有在环境里已经部署好 planner 模型时才需要添加这一段配置。例如下面的 Ollama 模型需要先在本地 pull 并启动后才能使用。++```json+{+ "query_planner": {+ "provider": "litellm",+ "model": "ollama/guoxuter/ov_intent_analysis_sft:v1_q8",+ "api_base": "http://127.0.0.1:11434",+ "temperature": 0.0,+ "timeout": 60,+ "extra_request_body": {+ "think": false+ }+ }+}+```++适合用小模型承担检索规划,同时保留更强的 `vlm` 处理语义提取、记忆提取和多模态内容。+### feishu飞书/Lark 云端文档解析配置。支持的 URL 格式详见[资源管理](../api/02-resources.md)。diff --git a/openviking/retrieve/intent_analyzer.py b/openviking/retrieve/intent_analyzer.pyindex e7550065d..007832e25 100644--- a/openviking/retrieve/intent_analyzer.py+++ b/openviking/retrieve/intent_analyzer.py@@ -61,8 +61,10 @@ class IntentAnalyzer:target_abstract,)- # Call LLM- response = await get_openviking_config().vlm.get_completion_async(prompt)+ # Call the lightweight query planner when configured; otherwise keep using VLM.+ config = get_openviking_config()+ query_planner = config.get_query_planner()+ response = await query_planner.get_completion_async(prompt)# Parse resultparsed = parse_json_from_response(response)diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.pyindex 067137f9f..05d7958f9 100644--- a/openviking_cli/utils/config/open_viking_config.py+++ b/openviking_cli/utils/config/open_viking_config.py@@ -69,6 +69,14 @@ class OpenVikingConfig(BaseModel):vlm: VLMConfig = Field(default_factory=VLMConfig, description="VLM configuration")+ query_planner: Optional[VLMConfig] = Field(+ default=None,+ description=(+ "Optional lightweight model configuration for retrieval intent analysis and query "+ "planning. Falls back to vlm when unset or empty."+ ),+ )+rerank: RerankConfig = Field(default_factory=RerankConfig, description="Rerank configuration")retrieval: RetrievalConfig = Field(@@ -293,6 +301,12 @@ class OpenVikingConfig(BaseModel):"""Convert configuration to dictionary."""return self.model_dump()+ def get_query_planner(self) -> VLMConfig:+ """Return the model config used for retrieval intent analysis and query planning."""+ if self.query_planner is not None and self.query_planner._has_any_config():+ return self.query_planner+ return self.vlm+class OpenVikingConfigSingleton:"""Global singleton for OpenVikingConfig.diff --git a/scripts/test_ov_intent_planner.py b/scripts/test_ov_intent_planner.pynew file mode 100644index 000000000..f30206e44--- /dev/null+++ b/scripts/test_ov_intent_planner.py@@ -0,0 +1,223 @@+#!/usr/bin/env python3+"""Smoke-test OpenViking intent analysis through the configured query_planner.++This calls OpenViking's IntentAnalyzer directly. It does not call Ollama with a+hand-written payload, so it verifies the same model path used by search()+intent analysis.+"""++from __future__ import annotations++import argparse+import asyncio+import importlib.util+import json+import os+import sys+import time+from dataclasses import asdict+from pathlib import Path+from typing import Any++from openviking_cli.retrieve.types import ContextType+from openviking_cli.utils.config import OPENVIKING_CONFIG_ENV+from openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton++DEFAULT_CONFIG = Path.home() / ".openviking" / "ov.conf"+EXPECTED_MODEL = "ollama/guoxuter/ov_intent_analysis_sft:v1_q8"+++CASES: dict[str, dict[str, Any]] = {+ "rfc": {+ "name": "operational RFC task",+ "compression_summary": "",+ "recent_messages": [+ ("user", "帮我写一份 RFC 文档"),+ ("assistant", "好的,标题是什么?"),+ ],+ "current_message": "标题就叫《支付链路重构》,按公司标准模板来",+ "context_type": None,+ "target_abstract": "",+ },+ "format": {+ "name": "informational format question",+ "compression_summary": "",+ "recent_messages": [+ ("user", "我在做新项目的技术选型"),+ ("assistant", "好的,需要参考什么资料?"),+ ],+ "current_message": "RFC 文档的标准格式是什么?",+ "context_type": None,+ "target_abstract": "",+ },+ "chat": {+ "name": "conversational small talk",+ "compression_summary": "",+ "recent_messages": [+ ("user", "你好"),+ ("assistant", "你好,有什么可以帮你?"),+ ],+ "current_message": "今天天气挺好的",+ "context_type": None,+ "target_abstract": "",+ },+ "memory": {+ "name": "restricted memory query",+ "compression_summary": "",+ "recent_messages": [+ ("user", "帮我对比下这次活动和上月会员日的 ROI"),+ ],+ "current_message": "活动周期 7 天,预计 10 万用户参与",+ "context_type": ContextType.MEMORY,+ "target_abstract": "User's long-term memory; preferences / events / historical KPIs",+ },+}+++def _message(i: int, role: str, text: str):+ from openviking.message import Message, TextPart++ return Message(id=f"case-msg-{i}", role=role, parts=[TextPart(text=text)])+++def _messages(raw_messages: list[tuple[str, str]]) -> list[Any]:+ return [_message(i, role, text) for i, (role, text) in enumerate(raw_messages, start=1)]+++def _load_config(config_path: Path, *, preserve_log_output: bool = False):+ os.environ[OPENVIKING_CONFIG_ENV] = str(config_path)+ data = json.loads(config_path.read_text(encoding="utf-8-sig"))+ if not preserve_log_output:+ data.setdefault("log", {})+ data["log"]["output"] = "stdout"+ return OpenVikingConfigSingleton.initialize(config_dict=data)+++def _load_intent_analyzer_class():+ module_path = (+ Path(__file__).resolve().parents[1] / "openviking" / "retrieve" / "intent_analyzer.py"+ )+ spec = importlib.util.spec_from_file_location("_ov_intent_analyzer_direct", module_path)+ if spec is None or spec.loader is None:+ raise RuntimeError(f"Could not load IntentAnalyzer from {module_path}")+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module.IntentAnalyzer+++def _planner_summary(config: Any) -> dict[str, Any]:+ planner = config.get_query_planner()+ return {+ "provider": planner.provider,+ "model": planner.model,+ "api_base": planner.api_base,+ "max_tokens": planner.max_tokens,+ "timeout": planner.timeout,+ "extra_request_body": planner.extra_request_body,+ "uses_query_planner": planner is config.query_planner,+ }+++def _print_plan(case_key: str, case_name: str, elapsed: float, plan: Any) -> None:+ print(f"\n=== {case_key}: {case_name} ===")+ print(f"elapsed_seconds: {elapsed:.3f}")+ print(f"reasoning: {plan.reasoning[:400]}")+ if not plan.queries:+ print("queries: []")+ return+ print("queries:")+ for idx, query in enumerate(plan.queries, start=1):+ context_type = query.context_type.value if query.context_type else None+ print(f" {idx}. [{context_type}] p={query.priority} {query.query}")+ if query.intent:+ print(f" intent: {query.intent}")+++async def _run_case(+ intent_analyzer_class: Any,+ case_key: str,+ case: dict[str, Any],+) -> dict[str, Any]:+ analyzer = intent_analyzer_class(max_recent_messages=5)+ start = time.perf_counter()+ plan = await analyzer.analyze(+ compression_summary=case["compression_summary"],+ messages=_messages(case["recent_messages"]),+ current_message=case["current_message"],+ context_type=case["context_type"],+ target_abstract=case["target_abstract"],+ )+ elapsed = time.perf_counter() - start+ _print_plan(case_key, case["name"], elapsed, plan)+ return {+ "case": case_key,+ "elapsed_seconds": elapsed,+ "plan": {+ "reasoning": plan.reasoning,+ "queries": [asdict(query) for query in plan.queries],+ },+ }+++async def _main() -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument(+ "--config",+ default=str(DEFAULT_CONFIG),+ help="Path to ov.conf. Defaults to ~/.openviking/ov.conf.",+ )+ parser.add_argument(+ "--case",+ choices=["all", *CASES.keys()],+ default="all",+ help="Scenario to run.",+ )+ parser.add_argument(+ "--json",+ action="store_true",+ help="Print a machine-readable summary at the end.",+ )+ parser.add_argument(+ "--preserve-log-output",+ action="store_true",+ help="Use ov.conf log.output as-is. By default this smoke test logs to stdout.",+ )+ args = parser.parse_args()++ config_path = Path(args.config).expanduser()+ config = _load_config(config_path, preserve_log_output=args.preserve_log_output)+ intent_analyzer_class = _load_intent_analyzer_class()+ planner = _planner_summary(config)++ print(f"config: {config_path}")+ print("query_planner:")+ print(json.dumps(planner, ensure_ascii=False, indent=2))++ if not planner["uses_query_planner"]:+ print("ERROR: ov.conf did not load a dedicated query_planner.", file=sys.stderr)+ return 2+ if planner["model"] != EXPECTED_MODEL:+ print(+ f"ERROR: expected model {EXPECTED_MODEL!r}, got {planner['model']!r}.",+ file=sys.stderr,+ )+ return 2++ selected = CASES.keys() if args.case == "all" else [args.case]+ results = []+ for case_key in selected:+ results.append(await _run_case(intent_analyzer_class, case_key, CASES[case_key]))++ if args.json:+ print("\n=== json_summary ===")+ print(json.dumps({"query_planner": planner, "results": results}, ensure_ascii=False))++ return 0+++if __name__ == "__main__":+ try:+ raise SystemExit(asyncio.run(_main()))+ except Exception as exc:+ print(f"ERROR: {type(exc).__name__}: {exc}", file=sys.stderr)+ raise SystemExit(1)diff --git a/tests/retrieve/test_intent_analyzer_query_planner.py b/tests/retrieve/test_intent_analyzer_query_planner.pynew file mode 100644index 000000000..ad31b7832--- /dev/null+++ b/tests/retrieve/test_intent_analyzer_query_planner.py@@ -0,0 +1,94 @@+from types import SimpleNamespace++import pytest++from openviking.retrieve import intent_analyzer as intent_module+from openviking.retrieve.intent_analyzer import IntentAnalyzer+from openviking_cli.utils.config.open_viking_config import OpenVikingConfig+++class RecordingModel:+ def __init__(self, response: str):+ self.response = response+ self.prompts: list[str] = []++ async def get_completion_async(self, prompt: str):+ self.prompts.append(prompt)+ return self.response+++def _query_plan_response(query: str) -> str:+ return f"""{{+ "reasoning": "test",+ "queries": [+ {{+ "query": "{query}",+ "context_type": "memory",+ "intent": "test intent",+ "priority": 1+ }}+ ]+ }}"""+++def test_openviking_config_accepts_query_planner_vlm_config():+ config = OpenVikingConfig.from_dict(+ {+ "query_planner": {+ "provider": "litellm",+ "model": "ollama/qwen3.5:4b",+ "api_base": "http://127.0.0.1:11434",+ "extra_request_body": {"think": False},+ }+ }+ )++ assert config.query_planner is not None+ assert config.query_planner.provider == "litellm"+ assert config.query_planner.model == "ollama/qwen3.5:4b"+ assert config.query_planner.api_base == "http://127.0.0.1:11434"+ assert config.query_planner.extra_request_body == {"think": False}+++def test_openviking_config_uses_vlm_when_query_planner_is_absent_or_empty():+ missing_config = OpenVikingConfig.from_dict({})+ assert missing_config.get_query_planner() is missing_config.vlm++ empty_config = OpenVikingConfig.from_dict({"query_planner": {}})+ assert empty_config.get_query_planner() is empty_config.vlm+++async def test_intent_analyzer_uses_query_planner_when_configured(monkeypatch):+ planner = RecordingModel(_query_plan_response("planned query"))+ vlm = RecordingModel(_query_plan_response("vlm query"))+ config = SimpleNamespace(get_query_planner=lambda: planner)++ monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)++ result = await IntentAnalyzer().analyze(+ compression_summary="",+ messages=[],+ current_message="where is my preference?",+ )++ assert result.queries[0].query == "planned query"+ assert len(planner.prompts) == 1+ assert vlm.prompts == []+++async def test_intent_analyzer_falls_back_to_vlm_without_query_planner(monkeypatch):+ vlm = RecordingModel(_query_plan_response("vlm query"))+ config = SimpleNamespace(get_query_planner=lambda: vlm)++ monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)++ result = await IntentAnalyzer().analyze(+ compression_summary="",+ messages=[],+ current_message="where is my preference?",+ )++ assert result.queries[0].query == "vlm query"+ assert len(vlm.prompts) == 1