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(embedding): add Ollama provider support for local embedding (#644)
ChenXiaofeie5abe88f045f
diff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.mdindex 4992480e8..24a42dfe8 100644--- a/docs/en/faq/faq.md+++ b/docs/en/faq/faq.md@@ -126,6 +126,7 @@ Config files at the default path `~/.openviking/ov.conf` are loaded automaticall| `openai` | OpenAI Embedding API || `vikingdb` | VikingDB Embedding API || `jina` | Jina AI Embedding API |+| `ollama` | Ollama (local OpenAI-compatible server, no API key required) |Supports Dense, Sparse, and Hybrid embedding modes.diff --git a/docs/zh/faq/faq.md b/docs/zh/faq/faq.mdindex 680300058..956016aa7 100644--- a/docs/zh/faq/faq.md+++ b/docs/zh/faq/faq.md@@ -125,6 +125,7 @@ pip install openviking --upgrade --force-reinstall| `openai` | OpenAI Embedding API || `vikingdb` | VikingDB Embedding API || `jina` | Jina AI Embedding API |+| `ollama` | Ollama(本地 OpenAI 兼容服务器,无需 API Key) |支持 Dense、Sparse 和 Hybrid 三种 Embedding 模式。diff --git a/examples/ov.conf.example b/examples/ov.conf.exampleindex 3582f8775..249c0a136 100644--- a/examples/ov.conf.example+++ b/examples/ov.conf.example@@ -44,6 +44,16 @@"input": "multimodal"}},+ "embedding_ollama_example": {+ "_comment": "For local deployment with Ollama (no API key required):",+ "dense": {+ "provider": "ollama",+ "model": "nomic-embed-text",+ "api_base": "http://localhost:11434/v1",+ "dimension": 768,+ "input": "text"+ }+ },"vlm": {"model": "doubao-seed-2-0-pro-260215","api_key": "{your-api-key}",diff --git a/openviking/models/embedder/openai_embedders.py b/openviking/models/embedder/openai_embedders.pyindex b474215ed..48805e90e 100644--- a/openviking/models/embedder/openai_embedders.py+++ b/openviking/models/embedder/openai_embedders.py@@ -62,11 +62,13 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):self.api_base = api_baseself.dimension = dimension- if not self.api_key:- raise ValueError("api_key is required")+ # Allow missing api_key when api_base is set (e.g. local OpenAI-compatible servers)+ if not self.api_key and not self.api_base:+ raise ValueError("api_key is required (or set api_base for local servers)")# Initialize OpenAI client- client_kwargs = {"api_key": self.api_key}+ # Use a placeholder api_key when not provided (for local OpenAI-compatible servers)+ client_kwargs = {"api_key": self.api_key or "no-key"}if self.api_base:client_kwargs["base_url"] = self.api_baseself.client = openai.OpenAI(**client_kwargs)diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.pyindex 17e77266a..59215eb72 100644--- a/openviking_cli/utils/config/embedding_config.py+++ b/openviking_cli/utils/config/embedding_config.py@@ -16,7 +16,7 @@ class EmbeddingModelConfig(BaseModel):input: str = Field(default="multimodal", description="Input type: 'text' or 'multimodal'")provider: Optional[str] = Field(default="volcengine",- description="Provider type: 'openai', 'volcengine', 'vikingdb', 'jina'",+ description="Provider type: 'openai', 'volcengine', 'vikingdb', 'jina', 'ollama'",)backend: Optional[str] = Field(default="volcengine",@@ -57,16 +57,21 @@ class EmbeddingModelConfig(BaseModel):if not self.provider:raise ValueError("Embedding provider is required")- if self.provider not in ["openai", "volcengine", "vikingdb", "jina"]:+ if self.provider not in ["openai", "volcengine", "vikingdb", "jina", "ollama"]:raise ValueError(- f"Invalid embedding provider: '{self.provider}'. Must be one of: 'openai', 'volcengine', 'vikingdb', 'jina'"+ f"Invalid embedding provider: '{self.provider}'. Must be one of: 'openai', 'volcengine', 'vikingdb', 'jina', 'ollama'")# Provider-specific validationif self.provider == "openai":- if not self.api_key:+ # Allow missing api_key when api_base is set (e.g. local OpenAI-compatible servers)+ if not self.api_key and not self.api_base:raise ValueError("OpenAI provider requires 'api_key' to be set")+ elif self.provider == "ollama":+ # Ollama runs locally, no API key required+ pass+elif self.provider == "volcengine":if not self.api_key:raise ValueError("Volcengine provider requires 'api_key' to be set")@@ -154,7 +159,7 @@ class EmbeddingConfig(BaseModel):OpenAIDenseEmbedder,lambda cfg: {"model_name": cfg.model,- "api_key": cfg.api_key,+ "api_key": cfg.api_key or "no-key", # Placeholder for local OpenAI-compatible servers"api_base": cfg.api_base,"dimension": cfg.dimension,"max_tokens": cfg.max_tokens,@@ -234,6 +239,17 @@ class EmbeddingConfig(BaseModel):"dimension": cfg.dimension,},),+ # Ollama: local OpenAI-compatible embedding server, no real API key needed+ ("ollama", "dense"): (+ OpenAIDenseEmbedder,+ lambda cfg: {+ "model_name": cfg.model,+ "api_key": cfg.api_key or "no-key", # Ollama ignores the key, but client requires non-empty+ "api_base": cfg.api_base or "http://localhost:11434/v1",+ "dimension": cfg.dimension,+ "max_tokens": cfg.max_tokens,+ },+ ),}key = (provider, embedder_type)diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.pyindex 665c6e15a..1ab715170 100644--- a/tests/misc/test_config_validation.py+++ b/tests/misc/test_config_validation.py@@ -156,6 +156,50 @@ def test_embedding_validation():else:print(f" Fail (provider='volcengine' should have priority, got '{config_b.provider}')")+ # Test 5: Ollama provider (no API key required)+ print("\n5. Test Ollama provider (no API key required)...")+ try:+ _ = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ provider="ollama",+ model="nomic-embed-text",+ dimension=768,+ )+ )+ print(" Pass (Ollama does not require API key)")+ except ValueError as e:+ print(f" Fail: {e}")++ # Test 6: Ollama provider with custom api_base+ print("\n6. Test Ollama provider with custom api_base...")+ try:+ _ = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ provider="ollama",+ model="nomic-embed-text",+ api_base="http://localhost:11434/v1",+ dimension=768,+ )+ )+ print(" Pass")+ except ValueError as e:+ print(f" Fail: {e}")++ # Test 7: OpenAI provider with api_base but no api_key (local OpenAI-compatible server)+ print("\n7. Test OpenAI provider with api_base but no api_key...")+ try:+ _ = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ provider="openai",+ model="text-embedding-3-small",+ api_base="http://localhost:8080/v1",+ dimension=1536,+ )+ )+ print(" Pass (OpenAI provider allows missing api_key when api_base is set)")+ except ValueError as e:+ print(f" Fail: {e}")+def test_vlm_validation():"""Test VLM config validation"""diff --git a/tests/unit/test_ollama_embedding_factory.py b/tests/unit/test_ollama_embedding_factory.pynew file mode 100644index 000000000..d2b3caf17--- /dev/null+++ b/tests/unit/test_ollama_embedding_factory.py@@ -0,0 +1,174 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0+"""Tests for the ollama embedding factory in EmbeddingConfig._create_embedder.++Regression tests for two bugs fixed in the ollama factory lambda:+ 1. max_tokens was not forwarded to OpenAIDenseEmbedder (so user-configured+ chunking thresholds were silently ignored for Ollama).+ 2. The api_key placeholder was "ollama" instead of "no-key", inconsistent+ with the openai factory and the placeholder used inside OpenAIDenseEmbedder.+"""++import pytest+from unittest.mock import MagicMock, patch++from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig+++def _make_mock_openai_class():+ """Return a mock openai.OpenAI class that records constructor kwargs."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)],+ usage=None,+ )+ mock_openai_class = MagicMock(return_value=mock_client)+ return mock_openai_class, mock_client+++def _make_ollama_cfg(**kwargs) -> EmbeddingModelConfig:+ defaults = dict(provider="ollama", model="nomic-embed-text", dimension=768)+ defaults.update(kwargs)+ return EmbeddingModelConfig(**defaults)+++@patch("openai.OpenAI")+class TestOllamaFactoryMaxTokens:+ """max_tokens must be forwarded from config to OpenAIDenseEmbedder."""++ def test_custom_max_tokens_is_forwarded(self, mock_openai_class):+ """When max_tokens=512, the created embedder should report max_tokens=512."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)], usage=None+ )+ mock_openai_class.return_value = mock_client++ cfg = _make_ollama_cfg(max_tokens=512)+ embedder = EmbeddingConfig(dense=cfg)._create_embedder("ollama", "dense", cfg)++ assert embedder.max_tokens == 512++ def test_none_max_tokens_uses_default(self, mock_openai_class):+ """When max_tokens is not set (None), the embedder should use its default (8000)."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)], usage=None+ )+ mock_openai_class.return_value = mock_client++ cfg = _make_ollama_cfg() # max_tokens not set -> None+ assert cfg.max_tokens is None++ embedder = EmbeddingConfig(dense=cfg)._create_embedder("ollama", "dense", cfg)++ assert embedder.max_tokens == 8000 # class-level default++ def test_openai_factory_max_tokens_also_forwarded(self, mock_openai_class):+ """Sanity: the openai factory also forwards max_tokens (parity check)."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)], usage=None+ )+ mock_openai_class.return_value = mock_client++ cfg = EmbeddingModelConfig(+ provider="openai",+ model="text-embedding-3-small",+ api_key="sk-test",+ dimension=1536,+ max_tokens=4096,+ )+ embedder = EmbeddingConfig(dense=cfg)._create_embedder("openai", "dense", cfg)++ assert embedder.max_tokens == 4096+++@patch("openai.OpenAI")+class TestOllamaFactoryApiKeyPlaceholder:+ """The api_key placeholder for ollama must be "no-key", not "ollama"."""++ def test_no_api_key_uses_no_key_placeholder(self, mock_openai_class):+ """When no api_key is provided, openai.OpenAI must be called with api_key='no-key'."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)], usage=None+ )+ mock_openai_class.return_value = mock_client++ cfg = _make_ollama_cfg() # no api_key+ EmbeddingConfig(dense=cfg)._create_embedder("ollama", "dense", cfg)++ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs["api_key"] == "no-key", (+ f"Expected placeholder 'no-key' but got {call_kwargs['api_key']!r}. "+ "The ollama factory must use the same placeholder as the openai factory."+ )++ def test_explicit_api_key_is_passed_through(self, mock_openai_class):+ """When an api_key is explicitly provided, it must be passed through unchanged."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)], usage=None+ )+ mock_openai_class.return_value = mock_client++ cfg = _make_ollama_cfg(api_key="my-custom-key")+ EmbeddingConfig(dense=cfg)._create_embedder("ollama", "dense", cfg)++ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs["api_key"] == "my-custom-key"++ def test_openai_factory_also_uses_no_key_placeholder(self, mock_openai_class):+ """Parity check: the openai factory also uses 'no-key' when api_base is set."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)], usage=None+ )+ mock_openai_class.return_value = mock_client++ cfg = EmbeddingModelConfig(+ provider="openai",+ model="text-embedding-3-small",+ api_base="http://localhost:8080/v1",+ dimension=1536,+ )+ EmbeddingConfig(dense=cfg)._create_embedder("openai", "dense", cfg)++ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs["api_key"] == "no-key"+++@patch("openai.OpenAI")+class TestOllamaFactoryApiBase:+ """The ollama factory must supply the correct api_base."""++ def test_default_api_base_is_localhost_ollama(self, mock_openai_class):+ """When api_base is not set, it should default to http://localhost:11434/v1."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)], usage=None+ )+ mock_openai_class.return_value = mock_client++ cfg = _make_ollama_cfg() # no api_base+ EmbeddingConfig(dense=cfg)._create_embedder("ollama", "dense", cfg)++ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs["base_url"] == "http://localhost:11434/v1"++ def test_custom_api_base_is_forwarded(self, mock_openai_class):+ """When api_base is explicitly set, it must override the default."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)], usage=None+ )+ mock_openai_class.return_value = mock_client++ cfg = _make_ollama_cfg(api_base="http://gpu-server:11434/v1")+ EmbeddingConfig(dense=cfg)._create_embedder("ollama", "dense", cfg)++ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs["base_url"] == "http://gpu-server:11434/v1"diff --git a/tests/unit/test_openai_embedder_chunking.py b/tests/unit/test_openai_embedder_chunking.pyindex fd6d72f5d..514aa4df2 100644--- a/tests/unit/test_openai_embedder_chunking.py+++ b/tests/unit/test_openai_embedder_chunking.py@@ -447,3 +447,84 @@ class TestBaseMaxTokensConfigurable:embedder = ConcreteEmbedder(model_name="test", max_tokens=32768)assert embedder.max_tokens == 32768+++@patch("openai.OpenAI")+class TestOpenAIEmbedderWithoutApiKey:+ """Test cases for OpenAI embedder without api_key (local servers)."""++ def test_init_with_api_base_no_api_key(self, mock_openai_class):+ """OpenAIDenseEmbedder should initialize with api_base but no api_key."""+ mock_client = _make_mock_openai_client()+ mock_openai_class.return_value = mock_client++ mod = _load_openai_embedders()+ OpenAIDenseEmbedder = mod.OpenAIDenseEmbedder++ # Should NOT raise when api_base is set but api_key is not+ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_base="http://localhost:11434/v1",+ dimension=DIMENSION,+ )++ assert embedder is not None+ # Verify OpenAI client was initialized with placeholder key+ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs["api_key"] == "no-key"+ assert call_kwargs["base_url"] == "http://localhost:11434/v1"++ def test_init_without_api_key_or_api_base_raises(self, mock_openai_class):+ """OpenAIDenseEmbedder should raise when neither api_key nor api_base is set."""+ mock_client = _make_mock_openai_client()+ mock_openai_class.return_value = mock_client++ mod = _load_openai_embedders()+ OpenAIDenseEmbedder = mod.OpenAIDenseEmbedder++ # Should raise when neither is provided+ with pytest.raises(ValueError, match="api_key is required"):+ OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ dimension=DIMENSION,+ )++ def test_init_with_api_key_works_normally(self, mock_openai_class):+ """OpenAIDenseEmbedder should work normally with api_key provided."""+ mock_client = _make_mock_openai_client()+ mock_openai_class.return_value = mock_client++ mod = _load_openai_embedders()+ OpenAIDenseEmbedder = mod.OpenAIDenseEmbedder++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ dimension=DIMENSION,+ )++ assert embedder is not None+ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs["api_key"] == "test-api-key"++ def test_embed_with_api_base_no_api_key(self, mock_openai_class):+ """Embedding should work with api_base but no api_key (local server)."""+ mock_client = _make_mock_openai_client()+ mock_openai_class.return_value = mock_client++ mod = _load_openai_embedders()+ OpenAIDenseEmbedder = mod.OpenAIDenseEmbedder++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_base="http://localhost:11434/v1",+ dimension=DIMENSION,+ )++ result = embedder.embed("Hello world")++ assert result.dense_vector is not None+ assert len(result.dense_vector) == DIMENSION+ mock_client.embeddings.create.assert_called()