Skip to content

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

feat(embedding): add Ollama provider support for local embedding (#644)

ChenXiaofeie5abe88f045f
diff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.md
index 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.md
index 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.example
index 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.py
index 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_base
self.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_base
self.client = openai.OpenAI(**client_kwargs)
diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.py
index 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 validation
if 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.py
index 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.py
new file mode 100644
index 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.py
index 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()