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(bot): support VLM credential failover (#3503)
DuTao3319ffd5b76e
diff --git a/bot/vikingbot/cli/commands.py b/bot/vikingbot/cli/commands.pyindex 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 Noneextra_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.pyindex 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 sectiondefault_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 sectionbot_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_datastorage_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 = Noneif 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 configexcept (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.modelif "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 setbot_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.pyindex a9b8c54cf..4746564ad 100644--- a/bot/vikingbot/config/schema.py+++ b/bot/vikingbot/config/schema.py@@ -5,8 +5,11 @@ from pathlib import Pathfrom typing import Any, Dict, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator, model_validator+from pydantic.json_schema import SkipJsonSchemafrom 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_vlmclass 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 = Falsemode: 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+@propertydef 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_configov_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 vlmprovider_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_namereturn None, Nonediff --git a/bot/vikingbot/console/web_console.py b/bot/vikingbot/console/web_console.pyindex 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, Tupleimport 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 Configfrom 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_consumedconfig = 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.pyindex 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.pynew file mode 100644index 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.mdindex 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.mdindex 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```bashdiff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 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.mdindex 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. 启动对话```bashdiff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.pyindex 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.pyindex 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")