Skip to content

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

feat(bot): support VLM credential failover (#3503)

DuTao3319ffd5b76e
diff --git a/bot/vikingbot/cli/commands.py b/bot/vikingbot/cli/commands.py
index c82dd52d9..65b364ed8 100644
--- a/bot/vikingbot/cli/commands.py
+++ b/bot/vikingbot/cli/commands.py
@@ -264,7 +264,6 @@ def _init_prompt_session() -> None:
)
-
def _is_exit_command(command: str) -> bool:
"""Return True when input should end interactive chat."""
return command.lower() in EXIT_COMMANDS
@@ -304,12 +303,12 @@ def main(
pass
-def _make_provider(config, langfuse_client: None = None):
+def _make_provider(config, langfuse_client: Any = None):
"""Create LLM provider from configuration.
- When bot.agents.provider is explicitly set, uses openviking's VLMFactory
- to create the appropriate VLM backend and wraps it in VLMProviderAdapter.
- Otherwise falls back to the legacy LiteLLMProvider.
+ An explicit bot.agents.model or non-empty bot.agents.credentials uses the
+ Bot's own VLM configuration. Otherwise the complete root VLM configuration
+ is inherited, including its ordered credentials and failover behavior.
"""
from vikingbot.providers.litellm_provider import LiteLLMProvider
@@ -322,10 +321,86 @@ def _make_provider(config, langfuse_client: None = None):
provider_name = p.provider if p else None
extra_headers = p.extra_headers if p else {}
timeout = p.timeout if p else None
+ credentials = list(getattr(p, "credentials", None) or [])
- if not model:
+ if not model and not credentials:
raise RuntimeError("No LLM model configured. Please set it in ~/.openviking/ov.conf")
+ inherits_root_vlm = False
+ inherits_root_vlm_getter = getattr(config, "inherits_root_vlm", None)
+ if callable(inherits_root_vlm_getter):
+ inherits_root_vlm = bool(inherits_root_vlm_getter())
+
+ if inherits_root_vlm:
+ from openviking_cli.utils.config.vlm_config import VLMConfig
+ from vikingbot.providers.vlm_adapter import VLMProviderAdapter
+
+ root_vlm_getter = getattr(config, "get_root_vlm_config", None)
+ root_vlm = root_vlm_getter() if callable(root_vlm_getter) else None
+ if root_vlm is None:
+ raise RuntimeError("Root VLM configuration is unavailable")
+
+ # Re-validate a fresh copy so the Bot keeps its existing generation
+ # settings without sharing a cached VLM instance with another runtime.
+ root_vlm_data = root_vlm.model_dump()
+ root_vlm_data["temperature"] = temperature
+ root_vlm_data["thinking"] = thinking
+ if timeout is not None:
+ root_vlm_data["timeout"] = timeout
+ if extra_headers:
+ root_vlm_data["extra_headers"] = extra_headers
+ effective_vlm = VLMConfig.model_validate(root_vlm_data)
+ return VLMProviderAdapter(
+ vlm_instance=effective_vlm.get_vlm_instance(),
+ default_model=effective_vlm.model or model,
+ langfuse_client=langfuse_client,
+ )
+
+ if credentials:
+ from openviking_cli.utils.config.vlm_config import VLMConfig
+ from vikingbot.providers.vlm_adapter import VLMProviderAdapter
+
+ if not model:
+ missing_model_ids = [
+ credential.id or f"index-{index}"
+ for index, credential in enumerate(credentials)
+ if not credential.model
+ ]
+ if missing_model_ids:
+ raise RuntimeError(
+ "bot.agents.model is omitted, so every bot.agents.credentials "
+ "entry must define model; missing for: " + ", ".join(missing_model_ids)
+ )
+
+ bot_vlm_data: dict[str, Any] = {
+ # VLMConfig currently requires a parent model even when every
+ # credential has its own. Use the primary credential internally
+ # without persisting an outer bot.agents.model.
+ "model": model or credentials[0].model,
+ "temperature": temperature,
+ "thinking": thinking,
+ "credentials": credentials,
+ "failback_timeout_seconds": p.failback_timeout_seconds,
+ "failback_request_count": p.failback_request_count,
+ }
+ if provider_name:
+ bot_vlm_data["provider"] = provider_name
+ if timeout is not None:
+ bot_vlm_data["timeout"] = timeout
+ if api_key:
+ bot_vlm_data["api_key"] = api_key
+ if api_base:
+ bot_vlm_data["api_base"] = api_base
+ if extra_headers:
+ bot_vlm_data["extra_headers"] = extra_headers
+
+ effective_vlm = VLMConfig.model_validate(bot_vlm_data)
+ return VLMProviderAdapter(
+ vlm_instance=effective_vlm.get_vlm_instance(),
+ default_model=effective_vlm.model or credentials[0].model or "",
+ langfuse_client=langfuse_client,
+ )
+
# When provider is explicitly set, use VLMFactory to get the correct
# backend (e.g. VolcEngineVLM for volcengine, OpenAIVLM for openai).
# The VLM backend handles model name resolution internally, so no
@@ -643,7 +718,6 @@ def prepare_heartbeat(config, agent_loop, session_manager) -> HeartbeatService:
return heartbeat
-
# ============================================================================
# Agent Commands
# ============================================================================
@@ -651,6 +725,7 @@ def prepare_heartbeat(config, agent_loop, session_manager) -> HeartbeatService:
# Helper for thinking spinner context
+
def prepare_agent_channel(
config,
bus,
diff --git a/bot/vikingbot/config/loader.py b/bot/vikingbot/config/loader.py
index a234efa16..a201de1a1 100644
--- a/bot/vikingbot/config/loader.py
+++ b/bot/vikingbot/config/loader.py
@@ -66,6 +66,9 @@ def ensure_config(config_path: Path | None = None) -> Config:
# Create default config with empty bot section
default_config = Config()
+ # The built-in AgentsConfig model is a runtime fallback, not an
+ # explicit Bot model override. Do not persist it as one.
+ default_config.set_inherits_root_vlm(True)
save_config(default_config, config_path, include_defaults=True)
logger.info(f"[green]✓[/green] Created default config at {config_path}")
@@ -99,6 +102,21 @@ def load_config() -> Config:
# Extract bot section
bot_data = full_data.get("bot", {})
bot_data = convert_keys(bot_data)
+ raw_agents = bot_data.get("agents", {})
+ bot_model_explicit = bool(
+ isinstance(raw_agents, dict) and str(raw_agents.get("model") or "").strip()
+ )
+ bot_credentials_explicit = bool(
+ isinstance(raw_agents, dict)
+ and isinstance(raw_agents.get("credentials"), list)
+ and raw_agents["credentials"]
+ )
+ bot_vlm_explicit = bot_model_explicit or bot_credentials_explicit
+ if bot_credentials_explicit and not bot_model_explicit:
+ # AgentsConfig has a built-in model default for standalone
+ # legacy use. Do not let it become an implicit fallback for an
+ # explicitly configured Bot credential chain.
+ raw_agents["model"] = ""
# Extract storage.workspace from root level, default to ~/.openviking_data
storage_data = full_data.get("storage", {})
@@ -107,12 +125,21 @@ def load_config() -> Config:
else:
bot_data["storage_workspace"] = "~/.openviking/data"
- # Extract and merge vlm config for model settings only
- # Provider config is directly read from OpenVikingConfig at runtime
+ # Extract the root VLM config. When Bot does not explicitly configure
+ # agents.model or agents.credentials, the runtime inherits this
+ # complete config rather than only the flattened primary model.
vlm_data = full_data.get("vlm", {})
vlm_data = convert_keys(vlm_data)
+ root_vlm_config = None
if vlm_data:
- _merge_vlm_model_config(bot_data, vlm_data)
+ from openviking_cli.utils.config.vlm_config import VLMConfig
+
+ root_vlm_config = VLMConfig.model_validate(vlm_data)
+ _merge_vlm_model_config(
+ bot_data,
+ vlm_data,
+ inherit_model=not bot_vlm_explicit,
+ )
server_managed = _is_truthy_env(VIKINGBOT_WITH_OPENVIKING_SERVER_ENV)
bot_server_data = {} if server_managed else bot_data.get("ov_server", {})
@@ -137,6 +164,8 @@ def load_config() -> Config:
config.ov_server.set_config_source(ov_server_source)
config.ov_server.set_api_key_source(api_key_source)
config.ov_server.set_server_managed(server_managed)
+ config.set_root_vlm_config(root_vlm_config)
+ config.set_inherits_root_vlm(root_vlm_config is not None and not bot_vlm_explicit)
return config
except (json.JSONDecodeError, ValueError) as e:
@@ -145,11 +174,18 @@ def load_config() -> Config:
return Config()
-def _merge_vlm_model_config(bot_data: dict, vlm_data: dict) -> None:
+def _merge_vlm_model_config(
+ bot_data: dict,
+ vlm_data: dict,
+ *,
+ inherit_model: bool = True,
+) -> None:
"""
- Merge vlm model config into bot config.
+ Merge root VLM display/runtime defaults into Bot agents.
- Only sets model parameters - provider config is read directly from OpenVikingConfig.
+ The complete root VLM object is retained separately for credentials and
+ failover; these flattened fields keep existing AgentLoop configuration
+ behavior and support Bot-specific generation overrides.
"""
if vlm_data:
if "agents" not in bot_data:
@@ -159,6 +195,9 @@ def _merge_vlm_model_config(bot_data: dict, vlm_data: dict) -> None:
if vlm_data and "timeout" not in agents:
agents["timeout"] = vlm_data["timeout"] if "timeout" in vlm_data else 60.0
+ if not inherit_model:
+ return
+
# Set default model from vlm.model
if "agents" in bot_data:
if "model" in agents and agents["model"]:
@@ -710,6 +749,44 @@ def validate_openviking_auth(config: Config) -> None:
return
+def reconcile_vlm_inheritance_after_edit(previous: Config, edited: Config) -> None:
+ """Update root-VLM inheritance state after an editor rebuilds Config.
+
+ Editors such as the Web Console serialize and reconstruct ``Config``. The
+ hidden inheritance marker must survive an unchanged round-trip, but it must
+ be cleared when the user explicitly edits the Bot-owned model connection.
+
+ When Bot credentials are added to an inherited config, connection fields
+ flattened from the root VLM must not become implicit Bot-level fallbacks.
+ Preserve only fields whose values were explicitly changed by the editor.
+ """
+ if not previous.inherits_root_vlm():
+ return
+
+ connection_fields = ("model", "provider", "api_key", "api_base", "extra_headers")
+ credentials_changed = previous.agents.credentials != edited.agents.credentials
+ if credentials_changed:
+ empty_values = {
+ "model": "",
+ "provider": "",
+ "api_key": "",
+ "api_base": "",
+ "extra_headers": {},
+ }
+ for field in connection_fields:
+ if getattr(previous.agents, field) == getattr(edited.agents, field):
+ setattr(edited.agents, field, empty_values[field])
+ edited.set_inherits_root_vlm(False)
+ return
+
+ ownership_fields = ("model", "provider", "api_key", "api_base")
+ if any(
+ getattr(previous.agents, field) != getattr(edited.agents, field)
+ for field in ownership_fields
+ ):
+ edited.set_inherits_root_vlm(False)
+
+
def save_config(
config: Config, config_path: Path | None = None, include_defaults: bool = False
) -> None:
@@ -735,6 +812,14 @@ def save_config(
# Update bot section - only save fields that were explicitly set
bot_data = config.model_dump(exclude_unset=not include_defaults)
+ bot_data.pop("inherits_root_vlm_state", None)
+ if config.inherits_root_vlm() or (config.agents.credentials and not config.agents.model):
+ # model was populated from the root VLM by load_config(); persisting it
+ # under bot.agents would make the next load treat it as an explicit Bot
+ # override and silently stop inheriting root credentials.
+ agents_data = bot_data.get("agents")
+ if isinstance(agents_data, dict):
+ agents_data.pop("model", None)
if bot_data:
full_data["bot"] = convert_to_camel(bot_data)
else:
diff --git a/bot/vikingbot/config/schema.py b/bot/vikingbot/config/schema.py
index a9b8c54cf..4746564ad 100644
--- a/bot/vikingbot/config/schema.py
+++ b/bot/vikingbot/config/schema.py
@@ -5,8 +5,11 @@ from pathlib import Path
from typing import Any, Dict, Literal, Optional
from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator, model_validator
+from pydantic.json_schema import SkipJsonSchema
from pydantic_settings import BaseSettings, SettingsConfigDict
+from openviking_cli.utils.config.vlm_config import VLMCredential
+
class ChannelType(str, Enum):
"""Channel type enumeration."""
@@ -428,6 +431,8 @@ class ChannelsConfig(BaseModel):
class AgentsConfig(BaseModel):
"""Agent configuration."""
+ _inherits_root_vlm: bool = PrivateAttr(default=False)
+
model: str = "openai/doubao-seed-2-0-pro-260215"
temperature: float = Field(
default=0.7,
@@ -490,6 +495,27 @@ class AgentsConfig(BaseModel):
api_key: str = ""
api_base: str = ""
extra_headers: Optional[dict[str, str]] = Field(default_factory=dict)
+ credentials: list[VLMCredential] = Field(
+ default_factory=list,
+ description=(
+ "Ordered Bot-specific VLM credentials. A non-empty list makes VikingBot "
+ "use this Bot-owned chain even when bot.agents.model is omitted."
+ ),
+ )
+ failback_timeout_seconds: float = Field(
+ default=600.0,
+ description="Seconds before retrying a higher-priority Bot credential.",
+ )
+ failback_request_count: int = Field(
+ default=50,
+ description="Successful backup requests before retrying a higher-priority credential.",
+ )
+
+ def set_inherits_root_vlm(self, value: bool) -> None:
+ self._inherits_root_vlm = bool(value)
+
+ def inherits_root_vlm(self) -> bool:
+ return self._inherits_root_vlm
class ProviderConfig(BaseModel):
@@ -814,6 +840,9 @@ class SandboxConfig(BaseModel):
class Config(BaseSettings):
"""Root configuration for vikingbot."""
+ _root_vlm_config: Any = PrivateAttr(default=None)
+
+ inherits_root_vlm_state: SkipJsonSchema[bool] = Field(default=False, repr=False)
agents: AgentsConfig = Field(default_factory=AgentsConfig)
channels: list[Any] = Field(default_factory=list)
providers: ProvidersConfig = Field(
@@ -842,6 +871,25 @@ class Config(BaseSettings):
use_local_memory: bool = False
mode: BotMode = BotMode.NORMAL
+ @model_validator(mode="after")
+ def sync_root_vlm_inheritance_state(self) -> "Config":
+ """Restore runtime inheritance state after serialization round-trips."""
+ self.agents.set_inherits_root_vlm(self.inherits_root_vlm_state)
+ return self
+
+ def set_inherits_root_vlm(self, value: bool) -> None:
+ self.inherits_root_vlm_state = bool(value)
+ self.agents.set_inherits_root_vlm(value)
+
+ def inherits_root_vlm(self) -> bool:
+ return self.inherits_root_vlm_state
+
+ def set_root_vlm_config(self, vlm_config: Any) -> None:
+ self._root_vlm_config = vlm_config
+
+ def get_root_vlm_config(self) -> Any:
+ return self._root_vlm_config
+
@property
def read_only(self) -> bool:
"""Backward compatibility for read_only property."""
@@ -871,6 +919,9 @@ class Config(BaseSettings):
def _get_vlm_config(self) -> Optional[Dict[str, Any]]:
"""Get vlm config from OpenVikingConfig. Returns (vlm_config_dict)."""
+ if self._root_vlm_config is not None:
+ return self._root_vlm_config.model_dump()
+
from openviking_cli.utils.config import get_openviking_config
ov_config = get_openviking_config()
@@ -882,12 +933,47 @@ class Config(BaseSettings):
def _match_provider(
self, model: str | None = None
) -> tuple["ProviderConfig | None", str | None]:
- """Match provider config from ov.conf vlm section. Returns (config, spec_name)."""
- # Get from OpenVikingConfig vlm
+ """Match the effective Bot provider config. Returns (config, spec_name)."""
+ del model
+
+ if not self.inherits_root_vlm():
+ if self.agents.credentials:
+ credential = self.agents.credentials[0]
+ return (
+ ProviderConfig(
+ api_key=credential.api_key or "",
+ api_base=credential.api_base,
+ extra_headers=credential.extra_headers or {},
+ ),
+ credential.provider,
+ )
+ if self.agents.provider:
+ return (
+ ProviderConfig(
+ api_key=self.agents.api_key,
+ api_base=self.agents.api_base or None,
+ extra_headers=self.agents.extra_headers or {},
+ ),
+ self.agents.provider,
+ )
+ return None, None
+
vlm_config = self._get_vlm_config()
if vlm_config:
- provider_name = vlm_config.get("provider")
+ credentials = vlm_config.get("credentials") or []
+ if credentials:
+ credential = credentials[0]
+ return (
+ ProviderConfig(
+ api_key=credential.get("api_key") or "",
+ api_base=credential.get("api_base"),
+ extra_headers=credential.get("extra_headers") or {},
+ ),
+ credential.get("provider"),
+ )
+
+ provider_name = vlm_config.get("provider") or vlm_config.get("default_provider")
if provider_name:
# Build provider config from vlm
provider_config = ProviderConfig()
@@ -908,8 +994,7 @@ class Config(BaseSettings):
if vlm_config.get("api_base"):
provider_config.api_base = vlm_config["api_base"]
- if provider_config.api_key:
- return provider_config, provider_name
+ return provider_config, provider_name
return None, None
diff --git a/bot/vikingbot/console/web_console.py b/bot/vikingbot/console/web_console.py
index 01f777214..2b7f78b0e 100644
--- a/bot/vikingbot/console/web_console.py
+++ b/bot/vikingbot/console/web_console.py
@@ -5,7 +5,12 @@ from typing import Any, Dict, List, Optional, Tuple
import gradio as gr
-from vikingbot.config.loader import get_config_path, load_config, save_config
+from vikingbot.config.loader import (
+ get_config_path,
+ load_config,
+ reconcile_vlm_inheritance_after_edit,
+ save_config,
+)
from vikingbot.config.schema import Config
from vikingbot.observability.feedback_stats import (
FEEDBACK_STATS_SORT_FIELDS,
@@ -351,7 +356,8 @@ def create_config_tabs():
def save_config_fn(*args):
try:
- config_dict = load_config().model_dump()
+ previous_config = load_config()
+ config_dict = previous_config.model_dump()
remaining_args = list(args)
comp_idx = 0
@@ -366,6 +372,7 @@ def create_config_tabs():
comp_idx += num_consumed
config = Config(**config_dict)
+ reconcile_vlm_inheritance_after_edit(previous_config, config)
save_config(config)
return "✓ Config saved successfully! Please restart the gateway service for changes to take effect."
except Exception as e:
diff --git a/bot/vikingbot/providers/vlm_adapter.py b/bot/vikingbot/providers/vlm_adapter.py
index 28bd0eb76..cf830c56d 100644
--- a/bot/vikingbot/providers/vlm_adapter.py
+++ b/bot/vikingbot/providers/vlm_adapter.py
@@ -129,7 +129,13 @@ class VLMProviderAdapter(LLMProvider):
temperature: float = 0.7,
session_id: str | None = None,
) -> AsyncIterator[LLMStreamEvent]:
- if getattr(self._vlm, "provider", None) != "volcengine":
+ # Failover wrappers expose the primary provider name but intentionally
+ # do not expose a single provider client. Route them through chat() so
+ # get_completion_async() can select the active credential safely.
+ supports_native_volcengine_stream = getattr(
+ self._vlm, "provider", None
+ ) == "volcengine" and callable(getattr(self._vlm, "get_async_client", None))
+ if not supports_native_volcengine_stream:
async for event in super().chat_stream(
messages=messages,
tools=tools,
diff --git a/bot/vikingbot/tests/unit/test_bot_vlm_credentials.py b/bot/vikingbot/tests/unit/test_bot_vlm_credentials.py
new file mode 100644
index 000000000..6e4527fbe
--- /dev/null
+++ b/bot/vikingbot/tests/unit/test_bot_vlm_credentials.py
@@ -0,0 +1,463 @@
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.models.vlm import MultiCredentialVLM
+from vikingbot.config import loader
+from vikingbot.config.schema import Config
+from vikingbot.providers.vlm_adapter import VLMProviderAdapter
+
+
+def _write_config(tmp_path, monkeypatch, data):
+ config_path = tmp_path / "ov.conf"
+ config_path.write_text(json.dumps(data))
+ monkeypatch.setattr(loader, "CONFIG_PATH", config_path)
+ return loader.load_config()
+
+
+def test_bot_inherits_root_vlm_credentials_when_agents_model_is_omitted(tmp_path, monkeypatch):
+ config = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "model": "root-primary",
+ "credentials": [
+ {
+ "id": "root-primary",
+ "provider": "openai",
+ "model": "root-primary",
+ "api_key": "root-primary-key",
+ },
+ {
+ "id": "root-backup",
+ "provider": "openai",
+ "model": "root-backup",
+ "api_key": "root-backup-key",
+ },
+ ],
+ }
+ },
+ )
+
+ from vikingbot.cli.commands import _make_provider
+
+ provider = _make_provider(config)
+
+ assert config.agents.inherits_root_vlm() is True
+ assert isinstance(provider, VLMProviderAdapter)
+ assert isinstance(provider._vlm, MultiCredentialVLM)
+ assert config.get_provider_name() == "openai"
+ assert provider._vlm._credential_ids == ["root-primary", "root-backup"]
+ assert [vlm.model for vlm in provider._vlm._vlm_instances] == [
+ "root-primary",
+ "root-backup",
+ ]
+
+
+def test_explicit_bot_model_uses_bot_credentials_instead_of_root(tmp_path, monkeypatch):
+ config = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "model": "root-primary",
+ "credentials": [
+ {
+ "id": "root-primary",
+ "provider": "openai",
+ "api_key": "root-key",
+ }
+ ],
+ },
+ "bot": {
+ "agents": {
+ "model": "bot-primary",
+ "credentials": [
+ {
+ "id": "bot-primary",
+ "provider": "openai",
+ "model": "bot-primary",
+ "api_key": "bot-primary-key",
+ },
+ {
+ "id": "bot-backup",
+ "provider": "openai",
+ "model": "bot-backup",
+ "api_key": "bot-backup-key",
+ },
+ ],
+ "failback_timeout_seconds": 30,
+ "failback_request_count": 5,
+ }
+ },
+ },
+ )
+
+ from vikingbot.cli.commands import _make_provider
+
+ provider = _make_provider(config)
+
+ assert config.agents.inherits_root_vlm() is False
+ assert isinstance(provider._vlm, MultiCredentialVLM)
+ assert config.get_provider_name() == "openai"
+ assert provider._vlm._credential_ids == ["bot-primary", "bot-backup"]
+ assert [vlm.model for vlm in provider._vlm._vlm_instances] == [
+ "bot-primary",
+ "bot-backup",
+ ]
+ assert provider._vlm._switcher._failback_timeout == 30
+ assert provider._vlm._switcher._failback_request_count == 5
+
+
+async def test_bot_multi_credentials_preserve_thinking_for_chat(tmp_path, monkeypatch):
+ config = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "bot": {
+ "agents": {
+ "model": "bot-primary",
+ "thinking": True,
+ "credentials": [
+ {
+ "id": "bot-primary",
+ "provider": "openai",
+ "model": "bot-primary",
+ "api_key": "bot-primary-key",
+ },
+ {
+ "id": "bot-backup",
+ "provider": "openai",
+ "model": "bot-backup",
+ "api_key": "bot-backup-key",
+ },
+ ],
+ }
+ }
+ },
+ )
+
+ from vikingbot.cli.commands import _make_provider
+
+ provider = _make_provider(
+ config,
+ langfuse_client=SimpleNamespace(enabled=False, _client=None),
+ )
+ primary = provider._vlm._vlm_instances[0]
+ primary.get_completion_async = AsyncMock(return_value="ok")
+
+ response = await provider.chat(messages=[{"role": "user", "content": "hello"}])
+
+ assert provider._vlm.thinking is True
+ assert response.content == "ok"
+ assert primary.get_completion_async.await_args.kwargs["thinking"] is True
+
+
+def test_bot_credentials_without_outer_model_use_bot_chain(tmp_path, monkeypatch):
+ config = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "model": "root-primary",
+ "credentials": [
+ {
+ "id": "root-primary",
+ "provider": "openai",
+ "model": "root-primary",
+ "api_key": "root-key",
+ }
+ ],
+ },
+ "bot": {
+ "agents": {
+ "credentials": [
+ {
+ "id": "bot-primary",
+ "provider": "openai",
+ "model": "bot-primary",
+ "api_key": "bot-primary-key",
+ },
+ {
+ "id": "bot-backup",
+ "provider": "openai",
+ "model": "bot-backup",
+ "api_key": "bot-backup-key",
+ },
+ ]
+ }
+ },
+ },
+ )
+
+ from vikingbot.cli.commands import _make_provider
+
+ provider = _make_provider(config)
+
+ assert config.agents.inherits_root_vlm() is False
+ assert config.agents.model == ""
+ assert isinstance(provider._vlm, MultiCredentialVLM)
+ assert provider._vlm._credential_ids == ["bot-primary", "bot-backup"]
+ assert [vlm.model for vlm in provider._vlm._vlm_instances] == [
+ "bot-primary",
+ "bot-backup",
+ ]
+
+
+def test_explicit_bot_model_without_credentials_keeps_single_model_behavior(tmp_path, monkeypatch):
+ config = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "provider": "openai",
+ "model": "root-model",
+ "api_key": "root-key",
+ },
+ "bot": {
+ "agents": {
+ "provider": "openai",
+ "model": "bot-model",
+ "api_key": "bot-key",
+ }
+ },
+ },
+ )
+
+ from vikingbot.cli.commands import _make_provider
+
+ provider = _make_provider(config)
+
+ assert config.agents.inherits_root_vlm() is False
+ assert isinstance(provider, VLMProviderAdapter)
+ assert not isinstance(provider._vlm, MultiCredentialVLM)
+ assert provider._vlm.model == "bot-model"
+
+
+def test_saving_inherited_config_does_not_turn_root_model_into_bot_override(tmp_path, monkeypatch):
+ config = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "provider": "openai",
+ "model": "root-model",
+ "api_key": "root-key",
+ }
+ },
+ )
+
+ loader.save_config(config, tmp_path / "ov.conf")
+
+ saved = json.loads((tmp_path / "ov.conf").read_text())
+ assert saved["vlm"]["model"] == "root-model"
+ assert "model" not in saved.get("bot", {}).get("agents", {})
+
+ reloaded = loader.load_config()
+ assert reloaded.agents.inherits_root_vlm() is True
+
+
+def test_console_roundtrip_preserves_root_vlm_inheritance(tmp_path, monkeypatch):
+ config = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "model": "root-primary",
+ "credentials": [
+ {
+ "id": "root-primary",
+ "provider": "openai",
+ "model": "root-primary",
+ "api_key": "root-primary-key",
+ },
+ {
+ "id": "root-backup",
+ "provider": "openai",
+ "model": "root-backup",
+ "api_key": "root-backup-key",
+ },
+ ],
+ }
+ },
+ )
+
+ config_dict = config.model_dump()
+ rebuilt = Config(**config_dict)
+ loader.reconcile_vlm_inheritance_after_edit(config, rebuilt)
+
+ assert config.inherits_root_vlm() is True
+ assert rebuilt.inherits_root_vlm() is True
+ assert rebuilt.agents.inherits_root_vlm() is True
+ assert "inherits_root_vlm_state" not in Config.model_json_schema()["properties"]
+
+ loader.save_config(rebuilt, tmp_path / "ov.conf")
+
+ saved = json.loads((tmp_path / "ov.conf").read_text())
+ assert "inheritsRootVlmState" not in saved.get("bot", {})
+ assert "model" not in saved.get("bot", {}).get("agents", {})
+
+ reloaded = loader.load_config()
+ assert reloaded.inherits_root_vlm() is True
+ assert reloaded.agents.inherits_root_vlm() is True
+ assert [credential.id for credential in reloaded.get_root_vlm_config().credentials] == [
+ "root-primary",
+ "root-backup",
+ ]
+
+
+def test_console_edit_can_switch_from_root_vlm_to_bot_model(tmp_path, monkeypatch):
+ previous = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "provider": "openai",
+ "model": "root-model",
+ "api_key": "root-key",
+ }
+ },
+ )
+
+ config_dict = previous.model_dump()
+ config_dict["agents"]["model"] = "bot-model"
+ config_dict["agents"]["api_key"] = "bot-key"
+ edited = Config(**config_dict)
+
+ loader.reconcile_vlm_inheritance_after_edit(previous, edited)
+ loader.save_config(edited, tmp_path / "ov.conf")
+
+ saved = json.loads((tmp_path / "ov.conf").read_text())
+ assert saved["bot"]["agents"]["model"] == "bot-model"
+
+ reloaded = loader.load_config()
+ assert reloaded.inherits_root_vlm() is False
+ assert reloaded.agents.model == "bot-model"
+ assert reloaded.agents.api_key == "bot-key"
+
+
+def test_console_credentials_edit_does_not_persist_inherited_model(tmp_path, monkeypatch):
+ previous = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "provider": "openai",
+ "model": "root-model",
+ "api_key": "root-key",
+ "api_base": "https://root-gateway.example/v1",
+ "extra_headers": {"X-Root-Tenant": "root"},
+ }
+ },
+ )
+
+ config_dict = previous.model_dump()
+ config_dict["agents"]["credentials"] = [
+ {
+ "id": "bot-primary",
+ "provider": "openai",
+ "model": "bot-model",
+ "api_key": "bot-key",
+ }
+ ]
+ edited = Config(**config_dict)
+
+ loader.reconcile_vlm_inheritance_after_edit(previous, edited)
+ loader.save_config(edited, tmp_path / "ov.conf")
+
+ assert edited.inherits_root_vlm() is False
+ saved = json.loads((tmp_path / "ov.conf").read_text())
+ assert "model" not in saved["bot"]["agents"]
+ assert saved["bot"]["agents"]["provider"] == ""
+ assert saved["bot"]["agents"]["apiKey"] == ""
+ assert saved["bot"]["agents"]["apiBase"] == ""
+ assert saved["bot"]["agents"]["extraHeaders"] == {}
+
+ reloaded = loader.load_config()
+ assert reloaded.inherits_root_vlm() is False
+ assert reloaded.agents.model == ""
+ assert reloaded.agents.credentials[0].model == "bot-model"
+
+ from vikingbot.cli.commands import _make_provider
+
+ provider = _make_provider(reloaded)
+ assert provider._vlm.model == "bot-model"
+ assert provider._vlm.api_key == "bot-key"
+ assert provider._vlm.api_base is None
+ assert provider._vlm.extra_headers is None
+
+
+def test_console_bot_credentials_do_not_inherit_root_api_key(tmp_path, monkeypatch):
+ previous = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "provider": "openai",
+ "model": "root-model",
+ "api_key": "root-key",
+ "api_base": "https://root-gateway.example/v1",
+ }
+ },
+ )
+
+ config_dict = previous.model_dump()
+ config_dict["agents"]["credentials"] = [
+ {
+ "id": "bot-primary",
+ "provider": "openai",
+ "model": "bot-model",
+ }
+ ]
+ edited = Config(**config_dict)
+
+ loader.reconcile_vlm_inheritance_after_edit(previous, edited)
+ loader.save_config(edited, tmp_path / "ov.conf")
+
+ reloaded = loader.load_config()
+ assert reloaded.agents.api_key == ""
+ assert reloaded.agents.api_base == ""
+
+ from vikingbot.cli.commands import _make_provider
+
+ with pytest.raises(ValueError, match="requires 'api_key' to be set"):
+ _make_provider(reloaded)
+
+
+def test_saving_credentials_only_config_keeps_model_omitted(tmp_path, monkeypatch):
+ config = _write_config(
+ tmp_path,
+ monkeypatch,
+ {
+ "vlm": {
+ "provider": "openai",
+ "model": "root-model",
+ "api_key": "root-key",
+ },
+ "bot": {
+ "agents": {
+ "credentials": [
+ {
+ "id": "bot-primary",
+ "provider": "openai",
+ "model": "bot-primary",
+ "api_key": "bot-key",
+ }
+ ]
+ }
+ },
+ },
+ )
+
+ loader.save_config(config, tmp_path / "ov.conf")
+
+ saved = json.loads((tmp_path / "ov.conf").read_text())
+ assert "model" not in saved["bot"]["agents"]
+
+ reloaded = loader.load_config()
+ assert reloaded.agents.inherits_root_vlm() is False
+ assert reloaded.agents.model == ""
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 97fc5fee9..287f21de2 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -626,6 +626,9 @@ Vision Language Model for semantic extraction (L0/L1 generation).
| `thinking` | bool | Enable thinking mode for VolcEngine models (default: `false`) |
| `max_concurrent` | int | Maximum concurrent semantic LLM calls (default: `64`) |
| `max_retries` | int | Maximum retry attempts for transient VLM provider errors (default: `3`; `0` disables retry) |
+| `credentials` | array | Ordered VLM credential/model list, with index 0 having the highest priority. Each item can override `provider`, `model`, `api_key`, `api_base`, `api_version`, `extra_headers`, `extra_request_body`, and `stream` |
+| `failback_timeout_seconds` | float | Time threshold for attempting a step back toward a higher-priority credential after failover (default: `600`) |
+| `failback_request_count` | int | Successful requests on a lower-priority credential before attempting a step back (default: `50`) |
| `backup` | object | Optional backup VLM configuration (same shape as `vlm`) for automatic failover when the primary fails with retryable errors such as rate limits, `5xx` responses, or connection/timeout failures. Only one level of failover is supported — the backup itself cannot define a nested `backup` |
| `timeout` | float | Per-request HTTP timeout in seconds passed to the underlying OpenAI/LiteLLM client. Increase for slow endpoints (e.g., DashScope, local inference). Must be `> 0` (default: `600.0`) |
| `extra_headers` | object | Custom HTTP headers for compatible HTTP providers. `kimi` also accepts header overrides, but already injects the required subscription headers by default |
diff --git a/docs/en/guides/17-vikingbot.md b/docs/en/guides/17-vikingbot.md
index c159760c9..f49cce8dc 100644
--- a/docs/en/guides/17-vikingbot.md
+++ b/docs/en/guides/17-vikingbot.md
@@ -133,6 +133,40 @@ If `ov.conf` already contains a root-level `vlm`, VikingBot inherits it. You can
}
```
+The Bot can define its own ordered `credentials` failover chain. When every
+credential defines `model`, the outer `bot.agents.model` may be omitted:
+
+```json
+{
+ "bot": {
+ "agents": {
+ "credentials": [
+ {
+ "id": "bot-primary",
+ "provider": "volcengine",
+ "model": "bot-primary-model",
+ "api_key": "${BOT_PRIMARY_API_KEY}"
+ },
+ {
+ "id": "bot-backup",
+ "provider": "openai",
+ "model": "bot-backup-model",
+ "api_key": "${BOT_BACKUP_API_KEY}"
+ }
+ ],
+ "failback_timeout_seconds": 600,
+ "failback_request_count": 50
+ }
+ }
+}
+```
+
+The precedence is deterministic: a non-empty `bot.agents.model` or
+`bot.agents.credentials` uses the Bot's own model/credentials. When both are omitted,
+VikingBot inherits the complete root `vlm` model, credentials, and failover/failback
+settings. If Bot credentials are configured without an outer model, every credential
+must define its own `model`. The two credential chains are never mixed.
+
### 2. Start a Chat
```bash
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 0016b7700..86327b784 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -595,6 +595,9 @@ provider,并设置 `storage.vectordb.sparse_weight > 0`。自托管模型的
| `thinking` | bool | 启用思考模式(仅对部分火山模型生效,默认:`false`) |
| `max_concurrent` | int | 语义处理阶段 LLM 最大并发调用数(默认:`64`) |
| `max_retries` | int | VLM provider 瞬时错误的最大重试次数(默认:`3`;`0` 表示禁用重试) |
+| `credentials` | array | 有序 VLM 凭据/模型列表,索引 0 优先级最高。每项可单独覆盖 `provider`、`model`、`api_key`、`api_base`、`api_version`、`extra_headers`、`extra_request_body` 和 `stream` |
+| `failback_timeout_seconds` | float | 切换到低优先级 credential 后,尝试逐级切回的时间阈值(默认:`600`) |
+| `failback_request_count` | int | 低优先级 credential 成功处理多少次请求后尝试逐级切回(默认:`50`) |
| `backup` | object | 可选的备用 VLM 配置(结构与 `vlm` 相同),当主 VLM 遇到限流、`5xx`、超时或连接失败等可重试错误时自动切换。仅支持 1 层备用 — 备用 VLM 本身不能再嵌套 `backup` |
| `timeout` | float | 单次 VLM API 请求的 HTTP 超时时间(秒),传递给底层 OpenAI/LiteLLM 客户端。慢端点(如 DashScope、本地推理)可调大。必须 `> 0`(默认:`600.0`) |
| `extra_headers` | object | 兼容 HTTP provider 的自定义请求头。`kimi` 默认已注入所需订阅请求头,也支持在这里覆盖或扩展 |
diff --git a/docs/zh/guides/17-vikingbot.md b/docs/zh/guides/17-vikingbot.md
index b8562f0a3..28eadcd4a 100644
--- a/docs/zh/guides/17-vikingbot.md
+++ b/docs/zh/guides/17-vikingbot.md
@@ -133,6 +133,39 @@ ov find "我的回答偏好"
}
```
+`bot.agents` 可以配置自己的有序 `credentials` 主备链;每项都配置 `model` 时,
+外层 `bot.agents.model` 可以省略:
+
+```json
+{
+ "bot": {
+ "agents": {
+ "credentials": [
+ {
+ "id": "bot-primary",
+ "provider": "volcengine",
+ "model": "bot-primary-model",
+ "api_key": "${BOT_PRIMARY_API_KEY}"
+ },
+ {
+ "id": "bot-backup",
+ "provider": "openai",
+ "model": "bot-backup-model",
+ "api_key": "${BOT_BACKUP_API_KEY}"
+ }
+ ],
+ "failback_timeout_seconds": 600,
+ "failback_request_count": 50
+ }
+ }
+}
+```
+
+优先级是确定的:存在非空的 `bot.agents.model` 或 `bot.agents.credentials` 时,
+使用 Bot 自己的模型/credentials;两者都省略时,完整继承根级 `vlm` 的模型、
+credentials 和 failover/failback 设置。配置 Bot credentials 但省略外层 model
+时,每个 credential 都必须配置自己的 `model`。两条 credentials 链不会混用。
+
### 2. 启动对话
```bash
diff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.py
index d17ce0b2a..640e07e5c 100644
--- a/openviking/models/vlm/base.py
+++ b/openviking/models/vlm/base.py
@@ -331,6 +331,7 @@ class VLMFactory:
return LiteLLMVLMProvider(config)
+
def _annotate_vlm_error(exc: Exception, vlm_instance: "VLMBase") -> None:
"""Attach model and api_base info to an exception for better error diagnostics.
@@ -631,6 +632,7 @@ class MultiCredentialVLM(VLMBase):
config = {
"model": first.model,
"provider": first.provider,
+ "thinking": first.thinking,
}
super().__init__(config)
diff --git a/tests/unit/test_vikingbot_vlm_adapter_retry.py b/tests/unit/test_vikingbot_vlm_adapter_retry.py
index 90bc362a6..e51f8927e 100644
--- a/tests/unit/test_vikingbot_vlm_adapter_retry.py
+++ b/tests/unit/test_vikingbot_vlm_adapter_retry.py
@@ -28,6 +28,12 @@ class _FakeVLM:
return self.result
+class _FakeVolcEngineFailoverVLM(_FakeVLM):
+ provider = "volcengine"
+ model = "primary-model"
+ thinking = False
+
+
class _AsyncChunks:
def __init__(self, chunks):
self._chunks = chunks
@@ -186,6 +192,27 @@ async def test_chat_stream_retries_rate_limit_until_success(monkeypatch):
assert events[1].response.finish_reason == "stop"
+async def test_chat_stream_routes_failover_wrapper_through_completion_api():
+ fake_vlm = _FakeVolcEngineFailoverVLM([], result="fallback-safe")
+ adapter = VLMProviderAdapter(
+ fake_vlm,
+ "primary-model",
+ langfuse_client=_DisabledLangfuse(),
+ )
+
+ events = [
+ event
+ async for event in adapter.chat_stream(
+ messages=[{"role": "user", "content": "hello"}],
+ )
+ ]
+
+ assert fake_vlm.calls == 1
+ assert [event.type for event in events] == ["response"]
+ assert events[0].response.content == "fallback-safe"
+
+
def test_rate_limit_classifier_handles_target_error():
assert is_retryable_rate_limit_error(
RuntimeError("Error code: 429 - ModelAccountTpmRateLimitExceeded")