feat: implement multi-credential priority call design

[fengluodb]

Description

为 OpenViking 客户端（ov.conf）增加多模型凭证 + 按序自动 fallback能力：同一个 VLM / Embedding 模型可配置一个扁平有序的凭证列表（数组顺序即调用优先级，每条带稳定 id），调用失败时按错误类型自动 fallback
到下一条凭证，并在高优先级凭证冷却后自动 failback。

Related Issue

Type of Change

[✓] New feature (non-breaking change that adds functionality)
[✓] Bug fix (non-breaking change that fixes an issue)
[✓] Refactoring (no functional changes)

Changes Made

核心特性

• 新增 OrderedCredentialSwitcher（N 级有序凭证切换状态机，含逐级 failback），MultiCredentialVLM 与 FailoverEmbedder 包装器；配置层 VLMConfig.credentials / EmbeddingModelConfig.credentials，旧 backup
字段自动归一化兼容。
• 鉴权方式从旧顶层配置切换为 credentials 时，模型/维度未变可无损复用已有向量（allow_metadata_override，默认 False，dimension 变化仍强制 rebuild）。

错误分类与切换策略

• 拆分错误类：PERMANENT(400 参数错误) / 新增 AUTH(401/403/欠费) / 新增 CONTENT_SAFETY / INPUT_TOO_LARGE / QUOTA_EXCEEDED / TRANSIENT / UNKNOWN。
• 切换策略：请求级错误（400 / 输入过大 / 内容安全）fail-fast 并 re-raise 原始异常；凭证级 AUTH 与 QUOTA_EXCEEDED 前移；TRANSIENT 用尽底层重试后前移；UNKNOWN 保守前移。
• circuit breaker 对 AUTH 同样立即熔断。

评审整改

• get_active_index() 改为纯读、无副作用；新增 maybe_failback() 专司 failback（切换时打 info 日志）。
• 移除全局 total_max_retries，凭证耗尽仅由 idx >= n 判定（修复 >10 凭证提前失败）。
• EmbeddingCredential 移除 6 个模型行为字段（修复 or 合并吞掉 0/False）。
• FailoverEmbedder.get_dimension 抛错替代魔法值 2048。
• token usage 改用公开访问器；修复 embedder 共享单例 tracker 导致的重复累加。

Testing

[✓] I have added tests that prove my fix is effective or that my feature works
[✓] New and existing unit tests pass locally with my changes
[✓] I have tested this on the following platforms:
[✓] macOS

测试：test_ordered_credential_switcher / test_vlm_failover / test_failover_embedder_permanent_advance / test_embedding_credential_model_override / test_model_retry / test_circuit_breaker，共 127 passed。

Checklist

[✓] My code follows the project's coding style
[✓] I have performed a self-review of my code
[✓] I have commented my code, particularly in hard-to-understand areas
[ ] I have made corresponding changes to the documentation（ov.conf 文档/示例待补）
[✓] My changes generate no new warnings
[ ] Any dependent changes have been merged and published

Additional Notes

• 设计前提：同一模型的所有凭证指向同一逻辑模型（endpoint 可不同）。因此请求级错误换凭证无意义 → fail-fast；凭证级错误（key 失效/欠费）才前移。
• 每条凭证的瞬时重试由其底层实例的 max_retries 负责，无全局重试上限。
• 向后兼容：旧 backup、旧顶层鉴权配置均自动归一化为 credentials，存量配置零改动。

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit 159b88c)

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🏅 Score: 85

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 Multiple PR themes Sub-PR theme: Add multi-credential support for embedders Relevant files: openviking_cli/utils/config/embedding_config.py openviking/models/embedder/base.py tests/unit/test_failover_embedder_permanent_advance.py tests/unit/test_embedding_credential_model_override.py Sub-PR theme: Add multi-credential support for VLMs Relevant files: openviking_cli/utils/config/vlm_config.py openviking/models/vlm/base.py openviking/models/vlm/init.py tests/unit/test_vlm_failover.py Sub-PR theme: Implement OrderedCredentialSwitcher and error classification updates Relevant files: openviking/utils/model_retry.py tests/unit/test_ordered_credential_switcher.py

⚡ Recommended focus areas for review Potential regression in legacy backup config handling When migrating legacy backup config to credentials, the code clears self.backup before checking if there are explicit credentials. This could lead to loss of backup config if explicit credentials are added but migration logic runs first. Verify that the migration order preserves explicit credentials. def _normalize_credentials(self): """Normalize credentials configuration: 1. Migrate legacy backup config to credentials 2. Migrate top-level credentials to credentials list 3. Assign default IDs to credentials without IDs 4. Apply top-level defaults to credentials """ migrated_credentials = [] # Step 1: Migrate legacy backup config if self.backup is not None and self.backup._has_any_config(): # Primary credential from top-level primary_cred = VLMCredential( id="legacy-primary", provider=self.provider, model=self.model, api_key=self.api_key, api_base=self.api_base, api_version=self.api_version, forward_api_key=self.forward_api_key, extra_headers=self.extra_headers, extra_request_body=self.extra_request_body, stream=self.stream, ) migrated_credentials.append(primary_cred) # Backup credential backup_cred = VLMCredential( id="legacy-backup", provider=self.backup.provider, model=self.backup.model, api_key=self.backup.api_key, api_base=self.backup.api_base, api_version=self.backup.api_version, forward_api_key=self.backup.forward_api_key, extra_headers=self.backup.extra_headers, extra_request_body=self.backup.extra_request_body, stream=self.backup.stream, ) migrated_credentials.append(backup_cred) # Clear backup to avoid double processing self.backup = None # Step 2: If no credentials from backup migration and no explicit credentials, # create credentials from top-level config if not migrated_credentials and not self.credentials: if self._has_legacy_provider_config(): migrated_credentials.append( VLMCredential( id="default", provider=self.provider, model=self.model, api_key=self.api_key, api_base=self.api_base, api_version=self.api_version, forward_api_key=self.forward_api_key, extra_headers=self.extra_headers, extra_request_body=self.extra_request_body, stream=self.stream, ) ) # Step 3: Merge migrated credentials with existing credentials if migrated_credentials: # Only use migrated if no explicit credentials exist if not self.credentials: self.credentials = migrated_credentials # Step 4: Assign default IDs and apply top-level defaults Inconsistent token usage handling between FailoverEmbedder and MultiCredentialVLM FailoverEmbedder returns only the first embedder's token usage (claiming shared singleton), while MultiCredentialVLM merges all instances' trackers. Verify that embedder token trackers are actually shared to avoid undercounting. def get_token_usage(self) -> Dict[str, Any]: """Get combined token usage across credential instances. Embedders share a process-wide singleton token tracker (see ``_get_token_tracker``), so every wrapped embedder reports the same usage. Return a single instance's usage directly; merging would double-count. """ if not self._embedders: return {} return self._embedders[0].get_token_usage()

[github-actions]

PR Code Suggestions ✨

Latest suggestions up to 159b88c
Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix logger usage in MultiCredentialVLM to use get_logger The MultiCredentialVLM class uses logging.getLogger(name) directly, which is inconsistent with the rest of the codebase that uses get_logger from openviking_cli.utils. Additionally, the logging module is not imported, which would cause a runtime error. Let's fix this by using get_logger instead. openviking/models/vlm/base.py [12-622] from openviking.utils.model_retry import ( OrderedCredentialSwitcher, PrimaryBackupSwitcher, classify_api_error, ) from openviking_cli.utils import get_logger ... - self._logger = logging.getLogger(__name__) + self._logger = get_logger(__name__) Suggestion importance[1-10]: 6 __ Why: Identifies a missing import for logging and inconsistent logger usage. The fix uses the already imported get_logger from openviking_cli.utils, aligning with the rest of the codebase and resolving a potential runtime error.	Low

---

Previous suggestions

Suggestions up to commit 2cefa7a

Category	Suggestion	Impact
General	Add logger and centralize AllCredentialsFailedError 1) Add loguru logger initialization to this file (used by OrderedCredentialSwitcher). 2) Move AllCredentialsFailedError here to avoid duplicate definitions in embedder and vlm base files. openviking/utils/model_retry.py [340] -class OrderedCredentialSwitcher: +import threading\nimport time\nfrom typing import Any, List, Optional\n\nfrom openviking_cli.utils import get_logger\n\nlogger = get_logger(__name__)\n\n\nclass AllCredentialsFailedError(Exception):\n """Raised when all credentials in the chain have failed."""\n\n def __init__(self, errors: list[tuple[str, str, Exception, int]]):\n """Initialize the error with a list of credential failures.\n\n Args:\n errors: List of tuples containing (credential_id, error_class, exception, attempts)\n """\n self.errors = errors\n message = "All credentials failed:\\n" + "\\n".join(\n f" - {cred_id}: {error_class} - {exc}" for cred_id, error_class, exc, attempts in errors\n )\n super().__init__(message)\n\n\nclass OrderedCredentialSwitcher: Suggestion importance[1-10]: 6 __ Why: Centralizes AllCredentialsFailedError to avoid duplicate definitions in embedder and VLM base files, and adds proper logger initialization, improving code maintainability and consistency.	Low
	Use loguru logger for consistent logging Replace standard library logging with loguru logger (used throughout the codebase) for consistent structured logging. openviking/models/vlm/base.py [638] - self._logger = logging.getLogger(__name__) + from openviking_cli.utils import get_logger\n self._logger = get_logger(__name__) Suggestion importance[1-10]: 5 __ Why: Replaces standard library logging with get_logger (used elsewhere in the codebase) for consistent logging, a minor but useful maintainability improvement.	Low
	Import centralized exception class Remove duplicate AllCredentialsFailedError and import it from openviking.utils.model_retry instead. openviking/models/embedder/base.py [649-662] -class AllCredentialsFailedError(Exception):\n """Raised when all credentials in the chain have failed."""\n\n def __init__(self, errors: list[tuple[str, str, Exception, int]]):\n """Initialize the error with a list of credential failures.\n\n Args:\n errors: List of tuples containing (credential_id, error_class, exception, attempts)\n """\n self.errors = errors\n message = "All credentials failed:\\n" + "\\n".join(\n f" - {cred_id}: {error_class} - {exc}" for cred_id, error_class, exc, attempts in errors\n )\n super().__init__(message) +from openviking.utils.model_retry import AllCredentialsFailedError Suggestion importance[1-10]: 5 __ Why: Removes duplicate exception definition and supports importing from a centralized location, improving code consistency, though corresponding changes in other files (e.g., vlm/base.py, import files) would also be needed for full implementation.	Low

[github-actions]

Persistent review updated to latest commit 159b88c

[qin-ctx]

本次 review 发现 3 个 blocking 问题，主要是新 credentials 归一化没有完整保留旧 providers 语义，以及 embedding credential 的 provider/model/auth fallback 在校验、维度、运行时构造之间不一致。

Non-blocking:

• PR 已注明 ov.conf 文档/示例待补；这是用户可见新配置格式，建议补 credentials 示例和旧 backup/providers 迁移说明。
• 当前 commit 中有多条 fix/format，建议合并前 squash 或改成可追踪的 conventional commits.

[qin-ctx]

本次 review 仍发现 1 个 blocking 问题：credentials 模式跳过了 embedding provider-specific 校验，会放行 litellm 未设置 dimension 等无效配置，导致 schema 维度和运行时 embedder 行为不一致。

Non-blocking:

• CI lint 当前失败：ruff format --check 提示 openviking/storage/collection_schemas.py 和 openviking_cli/utils/config/embedding_config.py 需要格式化。
• PR 已注明 ov.conf 文档/示例待补；这是用户可见的新配置格式，建议补 credentials 示例和旧 backup/providers 迁移说明。
• 当前 commit 中有多条 fix/format，建议合并前 squash 或改成可追踪的 conventional commits。

[qin-ctx]

本次 review 仍发现 1 个 blocking 兼容性问题：旧的 providers + backup VLM 配置在迁移到 credentials 时会丢失 primary provider/api_key，导致原本可用的配置变为不可用。\n\nNon-blocking:\n- is_exhausted 目前作为公开观测属性暴露，但生产 failover loop 没有通过 on_failure() 推进 exhausted 状态，语义容易误导。\n- PR 已注明 ov.conf 文档/示例待补；这是用户可见的新配置格式，建议补 credentials 示例和旧 backup/providers 迁移说明。\n- 当前 commit 中有多条 fix/format，建议合并前 squash 或改成可追踪的 conventional commits.