Skip to content

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

feat: Add VLM backup configuration for automatic failover (#2040)

MaojiaSheng81fb3f5c3b81
diff --git a/openviking/models/vlm/__init__.py b/openviking/models/vlm/__init__.py
index fda37f840..ae04683cd 100644
--- a/openviking/models/vlm/__init__.py
+++ b/openviking/models/vlm/__init__.py
@@ -8,12 +8,13 @@ from .backends.kimi_vlm import KimiVLM
from .backends.litellm_vlm import LiteLLMVLMProvider
from .backends.openai_vlm import OpenAIVLM
from .backends.volcengine_vlm import VolcEngineVLM
-from .base import VLMBase, VLMFactory
+from .base import VLMBase, VLMFactory, FailoverVLM
from .registry import get_all_provider_names, is_valid_provider
__all__ = [
"VLMBase",
"VLMFactory",
+ "FailoverVLM",
"OpenAIVLM",
"CodexVLM",
"KimiVLM",
diff --git a/openviking/models/vlm/backends/litellm_vlm.py b/openviking/models/vlm/backends/litellm_vlm.py
index d328274a6..cf58c76be 100644
--- a/openviking/models/vlm/backends/litellm_vlm.py
+++ b/openviking/models/vlm/backends/litellm_vlm.py
@@ -395,10 +395,11 @@ class LiteLLMVLMProvider(VLMBase):
images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion synchronously."""
- kwargs = self._build_vision_kwargs(prompt, images, thinking, tools, None, messages)
+ kwargs = self._build_vision_kwargs(prompt, images, thinking, tools, tool_choice, messages)
def _call() -> Union[str, VLMResponse]:
t0 = time.perf_counter()
@@ -422,10 +423,11 @@ class LiteLLMVLMProvider(VLMBase):
images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion asynchronously."""
- kwargs = self._build_vision_kwargs(prompt, images, thinking, tools, None, messages)
+ kwargs = self._build_vision_kwargs(prompt, images, thinking, tools, tool_choice, messages)
async def _call() -> Union[str, VLMResponse]:
t0 = time.perf_counter()
diff --git a/openviking/models/vlm/backends/openai_vlm.py b/openviking/models/vlm/backends/openai_vlm.py
index 47fe8f58e..513cd0402 100644
--- a/openviking/models/vlm/backends/openai_vlm.py
+++ b/openviking/models/vlm/backends/openai_vlm.py
@@ -393,11 +393,12 @@ class OpenAIVLM(VLMBase):
images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion"""
client = self.get_client()
- kwargs = self._build_vision_kwargs(prompt, images, tools, None, messages, thinking)
+ kwargs = self._build_vision_kwargs(prompt, images, tools, tool_choice, messages, thinking)
def _call() -> Union[str, VLMResponse]:
t0 = time.perf_counter()
@@ -421,11 +422,12 @@ class OpenAIVLM(VLMBase):
images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion asynchronously"""
client = self.get_async_client()
- kwargs = self._build_vision_kwargs(prompt, images, tools, None, messages, thinking)
+ kwargs = self._build_vision_kwargs(prompt, images, tools, tool_choice, messages, thinking)
async def _call() -> Union[str, VLMResponse]:
t0 = time.perf_counter()
diff --git a/openviking/models/vlm/backends/volcengine_vlm.py b/openviking/models/vlm/backends/volcengine_vlm.py
index 8f385abb4..5429d5a4c 100644
--- a/openviking/models/vlm/backends/volcengine_vlm.py
+++ b/openviking/models/vlm/backends/volcengine_vlm.py
@@ -308,6 +308,7 @@ class VolcEngineVLM(OpenAIVLM):
images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion via Chat Completions API."""
@@ -331,7 +332,7 @@ class VolcEngineVLM(OpenAIVLM):
kwargs["max_tokens"] = max_tokens
if tools:
kwargs["tools"] = tools
- kwargs["tool_choice"] = "auto"
+ kwargs["tool_choice"] = tool_choice or "auto"
client = self.get_client()
t0 = time.perf_counter()
@@ -349,6 +350,7 @@ class VolcEngineVLM(OpenAIVLM):
images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion asynchronously via Chat Completions API."""
@@ -372,7 +374,7 @@ class VolcEngineVLM(OpenAIVLM):
kwargs["max_tokens"] = max_tokens
if tools:
kwargs["tools"] = tools
- kwargs["tool_choice"] = "auto"
+ kwargs["tool_choice"] = tool_choice or "auto"
client = self.get_async_client()
t0 = time.perf_counter()
diff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.py
index c77318dc4..6d962d7af 100644
--- a/openviking/models/vlm/base.py
+++ b/openviking/models/vlm/base.py
@@ -332,3 +332,249 @@ class VLMFactory:
from .registry import get_all_provider_names
return get_all_provider_names()
+
+
+class FailoverVLM(VLMBase):
+ """VLM wrapper that provides failover to a backup VLM instance.
+
+ When the primary VLM instance fails with retryable errors (like rate limits),
+ this wrapper will automatically switch to using the backup VLM instance.
+ """
+
+ def __init__(self, primary: VLMBase, backup: VLMBase):
+ """Initialize FailoverVLM with primary and backup VLM instances.
+
+ Args:
+ primary: The primary VLM instance to use first
+ backup: The backup VLM instance to use when primary fails
+ """
+ # Use a dummy config since we're wrapping existing instances
+ config = {
+ "model": primary.model,
+ "provider": primary.provider,
+ }
+ super().__init__(config)
+
+ self.primary = primary
+ self.backup = backup
+ self._logger = logging.getLogger(__name__)
+ self._using_backup = False
+
+ def _should_failover(self, error: Exception) -> bool:
+ """Determine if an error should trigger failover to backup.
+
+ Args:
+ error: The exception that occurred
+
+ Returns:
+ True if failover should be attempted, False otherwise
+ """
+ # Check for common retryable/failover error patterns
+ error_str = str(error).lower()
+
+ # Rate limiting errors
+ rate_limit_patterns = [
+ "rate limit",
+ "ratelimit",
+ "too many requests",
+ "429",
+ "quota",
+ ]
+
+ # Server errors
+ server_error_patterns = [
+ "500",
+ "502",
+ "503",
+ "504",
+ "server error",
+ "service unavailable",
+ "timeout",
+ ]
+
+ # Connection errors
+ connection_patterns = [
+ "connection",
+ "network",
+ "unreachable",
+ ]
+
+ all_patterns = rate_limit_patterns + server_error_patterns + connection_patterns
+
+ return any(pattern in error_str for pattern in all_patterns)
+
+ def _get_completion_with_failover(
+ self,
+ method_name: str,
+ *args,
+ **kwargs
+ ):
+ """Execute a VLM method with failover support.
+
+ Args:
+ method_name: Name of the method to call on VLM instances
+ *args: Positional arguments to pass to the method
+ **kwargs: Keyword arguments to pass to the method
+
+ Returns:
+ The result from the VLM method
+
+ Raises:
+ The last exception encountered if both primary and backup fail
+ """
+ last_error = None
+
+ # Try primary first if not already using backup
+ if not self._using_backup:
+ try:
+ method = getattr(self.primary, method_name)
+ result = method(*args, **kwargs)
+ # If successful and we were in failover mode, consider switching back
+ # (but we'll stay conservative and keep using backup for this session)
+ return result
+ except Exception as e:
+ last_error = e
+ if self._should_failover(e):
+ self._logger.warning(
+ f"Primary VLM failed with error: {e}, switching to backup"
+ )
+ self._using_backup = True
+ else:
+ # Not a failover-worthy error, re-raise
+ raise
+
+ # Try backup
+ try:
+ method = getattr(self.backup, method_name)
+ return method(*args, **kwargs)
+ except Exception as e:
+ last_error = e
+ self._logger.error(f"Backup VLM also failed with error: {e}")
+ raise last_error
+
+ async def _get_completion_with_failover_async(
+ self,
+ method_name: str,
+ *args,
+ **kwargs
+ ):
+ """Execute an async VLM method with failover support.
+
+ Args:
+ method_name: Name of the async method to call on VLM instances
+ *args: Positional arguments to pass to the method
+ **kwargs: Keyword arguments to pass to the method
+
+ Returns:
+ The result from the async VLM method
+
+ Raises:
+ The last exception encountered if both primary and backup fail
+ """
+ last_error = None
+
+ # Try primary first if not already using backup
+ if not self._using_backup:
+ try:
+ method = getattr(self.primary, method_name)
+ result = await method(*args, **kwargs)
+ return result
+ except Exception as e:
+ last_error = e
+ if self._should_failover(e):
+ self._logger.warning(
+ f"Primary VLM failed with error: {e}, switching to backup"
+ )
+ self._using_backup = True
+ else:
+ raise
+
+ # Try backup
+ try:
+ method = getattr(self.backup, method_name)
+ return await method(*args, **kwargs)
+ except Exception as e:
+ last_error = e
+ self._logger.error(f"Backup VLM also failed with error: {e}")
+ raise last_error
+
+ def get_completion(
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
+ """Get text completion with failover support."""
+ return self._get_completion_with_failover(
+ "get_completion",
+ prompt=prompt,
+ thinking=thinking,
+ tools=tools,
+ tool_choice=tool_choice,
+ messages=messages,
+ )
+
+ async def get_completion_async(
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
+ """Get text completion asynchronously with failover support."""
+ return await self._get_completion_with_failover_async(
+ "get_completion_async",
+ prompt=prompt,
+ thinking=thinking,
+ tools=tools,
+ tool_choice=tool_choice,
+ messages=messages,
+ )
+
+ def get_vision_completion(
+ self,
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
+ thinking: bool = False,
+ tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
+ """Get vision completion with failover support."""
+ return self._get_completion_with_failover(
+ "get_vision_completion",
+ prompt=prompt,
+ images=images,
+ thinking=thinking,
+ tools=tools,
+ tool_choice=tool_choice,
+ messages=messages,
+ )
+
+ async def get_vision_completion_async(
+ self,
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
+ thinking: bool = False,
+ tools: Optional[List[Dict[str, Any]]] = None,
+ tool_choice: Optional[str] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
+ """Get vision completion asynchronously with failover support."""
+ return await self._get_completion_with_failover_async(
+ "get_vision_completion_async",
+ prompt=prompt,
+ images=images,
+ thinking=thinking,
+ tools=tools,
+ tool_choice=tool_choice,
+ messages=messages,
+ )
+
+ @property
+ def is_using_backup(self) -> bool:
+ """Check if currently using the backup VLM instance."""
+ return self._using_backup
diff --git a/openviking_cli/utils/config/vlm_config.py b/openviking_cli/utils/config/vlm_config.py
index 3d154c7f7..c2e52cd37 100644
--- a/openviking_cli/utils/config/vlm_config.py
+++ b/openviking_cli/utils/config/vlm_config.py
@@ -21,6 +21,7 @@ def _normalize_provider_name(name: Optional[str]) -> Optional[str]:
class VLMConfig(BaseModel):
"""VLM configuration, supports multiple provider backends."""
+ backup: Optional["VLMConfig"] = Field(default=None, description="Backup VLM configuration for failover")
model: Optional[str] = Field(default=None, description="Model name")
api_key: Optional[str] = Field(default=None, description="API key")
api_base: Optional[str] = Field(default=None, description="API base URL")
@@ -133,6 +134,14 @@ class VLMConfig(BaseModel):
raise ValueError("VLM configuration requires 'api_key' to be set")
return self
+ @model_validator(mode="after")
+ def validate_no_recursive_backup(self):
+ """Prevent recursive backup configurations"""
+ if self.backup is not None:
+ if self.backup.backup is not None:
+ raise ValueError("Backup VLM configuration cannot have its own backup (recursive backups are not allowed)")
+ return self
+
def _migrate_legacy_config(self):
"""Migrate legacy config to providers structure."""
if self.api_key and self.provider:
@@ -237,9 +246,17 @@ class VLMConfig(BaseModel):
"""Get VLM instance."""
if self._vlm_instance is None:
config_dict = self._build_vlm_config_dict()
- from openviking.models.vlm import VLMFactory
+ from openviking.models.vlm import VLMFactory, FailoverVLM
- self._vlm_instance = VLMFactory.create(config_dict)
+ primary = VLMFactory.create(config_dict)
+
+ # If backup is configured, wrap with FailoverVLM
+ if self.backup is not None and self.backup._has_any_config():
+ backup_config_dict = self.backup._build_vlm_config_dict()
+ backup = VLMFactory.create(backup_config_dict)
+ self._vlm_instance = FailoverVLM(primary, backup)
+ else:
+ self._vlm_instance = primary
return self._vlm_instance
def _build_vlm_config_dict(self) -> Dict[str, Any]:
@@ -348,3 +365,7 @@ class VLMConfig(BaseModel):
tools=tools,
messages=messages,
)
+
+
+# Resolve forward reference for backup field
+VLMConfig.model_rebuild()
diff --git a/tests/unit/test_vlm_failover.py b/tests/unit/test_vlm_failover.py
new file mode 100644
index 000000000..d265d542d
--- /dev/null
+++ b/tests/unit/test_vlm_failover.py
@@ -0,0 +1,348 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Tests for VLM failover/backup configuration functionality."""
+
+import pytest
+from unittest.mock import Mock, AsyncMock
+
+from openviking.models.vlm.base import FailoverVLM, VLMResponse
+from openviking_cli.utils.config.vlm_config import VLMConfig
+
+
+class TestVLMBackupConfig:
+ """Tests for VLMConfig backup field validation."""
+
+ def test_backup_config_allowed(self):
+ """Test that backup configuration is allowed when not recursive."""
+ backup_config = VLMConfig(
+ model="backup-model",
+ api_key="backup-key",
+ provider="openai",
+ )
+ config = VLMConfig(
+ model="primary-model",
+ api_key="primary-key",
+ provider="volcengine",
+ backup=backup_config,
+ )
+ assert config.backup is not None
+ assert config.backup.model == "backup-model"
+
+ def test_recursive_backup_config_rejected(self):
+ """Test that recursive backup configurations are rejected."""
+ nested_backup = VLMConfig(
+ model="nested-model",
+ api_key="nested-key",
+ provider="openai",
+ )
+ backup_config = VLMConfig(
+ model="backup-model",
+ api_key="backup-key",
+ provider="openai",
+ backup=nested_backup,
+ )
+ with pytest.raises(ValueError, match="recursive backups are not allowed"):
+ VLMConfig(
+ model="primary-model",
+ api_key="primary-key",
+ provider="volcengine",
+ backup=backup_config,
+ )
+
+ def test_backup_without_own_backup_allowed(self):
+ """Test that backup config without its own backup is allowed."""
+ backup_config = VLMConfig(
+ model="backup-model",
+ api_key="backup-key",
+ provider="openai",
+ )
+ config = VLMConfig(
+ model="primary-model",
+ api_key="primary-key",
+ provider="volcengine",
+ backup=backup_config,
+ )
+ # Should not raise
+ config.validate_no_recursive_backup()
+
+
+class TestFailoverVLM:
+ """Tests for FailoverVLM wrapper."""
+
+ def test_initialization(self):
+ """Test that FailoverVLM initializes correctly with primary and backup."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+
+ failover = FailoverVLM(primary, backup)
+
+ assert failover.primary is primary
+ assert failover.backup is backup
+ assert failover.is_using_backup is False
+
+ def test_primary_success(self):
+ """Test that primary is used when it succeeds."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_completion.return_value = "primary response"
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+
+ failover = FailoverVLM(primary, backup)
+
+ result = failover.get_completion(prompt="test")
+
+ assert result == "primary response"
+ primary.get_completion.assert_called_once()
+ backup.get_completion.assert_not_called()
+ assert failover.is_using_backup is False
+
+ def test_primary_fails_non_retryable(self):
+ """Test that non-retryable errors don't trigger failover."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_completion.side_effect = ValueError("invalid prompt")
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+
+ failover = FailoverVLM(primary, backup)
+
+ with pytest.raises(ValueError, match="invalid prompt"):
+ failover.get_completion(prompt="test")
+
+ primary.get_completion.assert_called_once()
+ backup.get_completion.assert_not_called()
+ assert failover.is_using_backup is False
+
+ def test_primary_fails_rate_limit_fails_to_backup(self):
+ """Test that rate limit errors trigger failover to backup."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_completion.side_effect = Exception("rate limit exceeded (429)")
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+ backup.get_completion.return_value = "backup response"
+
+ failover = FailoverVLM(primary, backup)
+
+ result = failover.get_completion(prompt="test")
+
+ assert result == "backup response"
+ primary.get_completion.assert_called_once()
+ backup.get_completion.assert_called_once()
+ assert failover.is_using_backup is True
+
+ def test_primary_fails_timeout_fails_to_backup(self):
+ """Test that timeout errors trigger failover to backup."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_completion.side_effect = Exception("request timeout")
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+ backup.get_completion.return_value = "backup response"
+
+ failover = FailoverVLM(primary, backup)
+
+ result = failover.get_completion(prompt="test")
+
+ assert result == "backup response"
+ assert failover.is_using_backup is True
+
+ def test_primary_fails_server_error_fails_to_backup(self):
+ """Test that server errors trigger failover to backup."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_completion.side_effect = Exception("server error 503")
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+ backup.get_completion.return_value = "backup response"
+
+ failover = FailoverVLM(primary, backup)
+
+ result = failover.get_completion(prompt="test")
+
+ assert result == "backup response"
+ assert failover.is_using_backup is True
+
+ def test_both_fail_raises_last_error(self):
+ """Test that if both primary and backup fail, the last error is raised."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_completion.side_effect = Exception("rate limit exceeded (429)")
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+ backup.get_completion.side_effect = Exception("backup also failed")
+
+ failover = FailoverVLM(primary, backup)
+
+ with pytest.raises(Exception, match="backup also failed"):
+ failover.get_completion(prompt="test")
+
+ primary.get_completion.assert_called_once()
+ backup.get_completion.assert_called_once()
+
+ def test_stays_on_backup_after_switch(self):
+ """Test that once switched to backup, subsequent calls use backup."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_completion.side_effect = Exception("rate limit exceeded (429)")
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+ backup.get_completion.return_value = "backup response"
+
+ failover = FailoverVLM(primary, backup)
+
+ # First call triggers failover
+ result1 = failover.get_completion(prompt="test1")
+ assert result1 == "backup response"
+ assert failover.is_using_backup is True
+
+ # Second call should use backup directly, not try primary again
+ backup.get_completion.return_value = "backup response 2"
+ result2 = failover.get_completion(prompt="test2")
+ assert result2 == "backup response 2"
+ assert primary.get_completion.call_count == 1 # Only called once
+
+ def test_vision_completion_failover(self):
+ """Test failover works for vision completion."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_vision_completion.side_effect = Exception("rate limit exceeded (429)")
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+ backup.get_vision_completion.return_value = "backup vision response"
+
+ failover = FailoverVLM(primary, backup)
+
+ result = failover.get_vision_completion(prompt="describe", images=["test.jpg"])
+
+ assert result == "backup vision response"
+ primary.get_vision_completion.assert_called_once()
+ backup.get_vision_completion.assert_called_once()
+
+ @pytest.mark.asyncio
+ async def test_async_completion_failover(self):
+ """Test failover works for async completion."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_completion_async = AsyncMock(
+ side_effect=Exception("rate limit exceeded (429)")
+ )
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+ backup.get_completion_async = AsyncMock(return_value="backup async response")
+
+ failover = FailoverVLM(primary, backup)
+
+ result = await failover.get_completion_async(prompt="test")
+
+ assert result == "backup async response"
+ primary.get_completion_async.assert_called_once()
+ backup.get_completion_async.assert_called_once()
+
+ @pytest.mark.asyncio
+ async def test_async_vision_completion_failover(self):
+ """Test failover works for async vision completion."""
+ primary = Mock()
+ primary.model = "primary-model"
+ primary.provider = "volcengine"
+ primary.get_vision_completion_async = AsyncMock(
+ side_effect=Exception("rate limit exceeded (429)")
+ )
+
+ backup = Mock()
+ backup.model = "backup-model"
+ backup.provider = "openai"
+ backup.get_vision_completion_async = AsyncMock(
+ return_value="backup async vision response"
+ )
+
+ failover = FailoverVLM(primary, backup)
+
+ result = await failover.get_vision_completion_async(
+ prompt="describe", images=["test.jpg"]
+ )
+
+ assert result == "backup async vision response"
+
+
+class TestVLMConfigWithBackup:
+ """Tests for VLMConfig with backup configuration integration."""
+
+ def test_config_without_backup_creates_single_instance(self, monkeypatch):
+ """Test that config without backup creates a single VLM instance."""
+ mock_factory = Mock()
+ mock_vlm = Mock()
+ mock_factory.create.return_value = mock_vlm
+
+ monkeypatch.setattr("openviking.models.vlm.VLMFactory", mock_factory)
+
+ config = VLMConfig(
+ model="test-model",
+ api_key="test-key",
+ provider="volcengine",
+ )
+
+ instance = config.get_vlm_instance()
+
+ assert instance is mock_vlm
+ mock_factory.create.assert_called_once()
+
+ def test_config_with_backup_creates_failover_instance(self, monkeypatch):
+ """Test that config with backup creates a FailoverVLM instance."""
+ mock_factory = Mock()
+ mock_primary = Mock()
+ mock_backup = Mock()
+ mock_factory.create.side_effect = [mock_primary, mock_backup]
+
+ monkeypatch.setattr("openviking.models.vlm.VLMFactory", mock_factory)
+
+ backup_config = VLMConfig(
+ model="backup-model",
+ api_key="backup-key",
+ provider="openai",
+ )
+ config = VLMConfig(
+ model="primary-model",
+ api_key="primary-key",
+ provider="volcengine",
+ backup=backup_config,
+ )
+
+ instance = config.get_vlm_instance()
+
+ # Should be a FailoverVLM instance
+ assert hasattr(instance, "primary")
+ assert hasattr(instance, "backup")