初始化提交

backend/app/ai_provider/routing/__init__.py

@@ -0,0 +1,14 @@
+from app.ai_provider.routing.multimodal import MultiModalDecision, MultiModalRouter
+from app.ai_provider.routing.permissions import (
+    CapabilityPermissionController,
+    PermissionRule,
+)
+from app.ai_provider.routing.selector import ModelSelector
+
+__all__ = [
+    "MultiModalDecision",
+    "MultiModalRouter",
+    "ModelSelector",
+    "PermissionRule",
+    "CapabilityPermissionController",
+]

backend/app/ai_provider/routing/multimodal.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+
+class MultiModalDecision(StrEnum):
+    """基于消息内容分析的选路决策。
+
+    每个值代表所选模型必须满足的一项能力需求。
+    PLAIN_TEXT 表示不需要特殊能力。
+    """
+
+    PLAIN_TEXT = "plain_text"
+    VISION = "vision"
+    THINKING = "thinking"
+    TOOL_USE = "tool_use"
+    STRUCTURED_OUTPUT = "structured_output"
+
+
+class MultiModalRouter:
+    """分析消息列表以确定所需的模型能力。
+
+    用法::
+
+        messages = [{"role": "user", "content": "Hello"}]
+        decisions = MultiModalRouter.decide_from_messages(messages)
+        # -> {MultiModalDecision.PLAIN_TEXT}
+
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "What's in this image?"},
+                    {"type": "image_url", "image_url": {"url": "..."}},
+                ],
+            },
+        ]
+        decisions = MultiModalRouter.decide_from_messages(messages)
+        # -> {MultiModalDecision.VISION}
+    """
+
+    @staticmethod
+    def decide_from_messages(messages: list[dict[str, Any]]) -> set[MultiModalDecision]:
+        """分析消息并返回所需能力的集合。
+
+        参数:
+            messages: 消息字典列表，每个字典至少包含 ``role`` 和 ``content`` 键（兼容 OpenAI 格式）。
+
+        返回:
+            :class:`MultiModalDecision` 值的集合。如果未检测到特殊能力，
+            返回 ``{PLAIN_TEXT}``。
+        """
+        if not messages:
+            return {MultiModalDecision.PLAIN_TEXT}
+
+        decisions: set[MultiModalDecision] = set()
+
+        for msg in messages:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+
+            # --- VISION: content is a list of blocks with image type ---
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict):
+                        block_type = block.get("type", "")
+                        if block_type in ("image_url", "image"):
+                            decisions.add(MultiModalDecision.VISION)
+
+            # --- TOOL_USE: assistant sent tool_calls, or message is tool result ---
+            if msg.get("tool_calls"):
+                decisions.add(MultiModalDecision.TOOL_USE)
+            if role == "tool":
+                decisions.add(MultiModalDecision.TOOL_USE)
+
+            # --- THINKING: assistant included reasoning ---
+            if msg.get("reasoning"):
+                decisions.add(MultiModalDecision.THINKING)
+
+        return decisions if decisions else {MultiModalDecision.PLAIN_TEXT}

backend/app/ai_provider/routing/permissions.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import fnmatch
+from typing import Any
+
+
+class PermissionRule:
+    """模型能力访问控制的单条权限规则。
+
+    规则使用 ``fnmatch`` 风格的通配符模式匹配模型名称。
+
+    参数:
+        model_pattern: ``fnmatch`` 模式，用于匹配模型名（如 ``"deepseek-*"``）。
+        capability: 此规则管控的能力（如 ``"vision"``）。
+        allowed: 能力是否允许（``True`` 允许，``False`` 拒绝）。
+
+    示例::
+
+        # 拒绝 "basic-*" 模型上的 vision 能力
+        PermissionRule(model_pattern="basic-*", capability="vision", allowed=False)
+
+        # 允许所有模型的 thinking 能力
+        PermissionRule(model_pattern="*", capability="thinking", allowed=True)
+    """
+
+    def __init__(
+        self,
+        model_pattern: str,
+        capability: str,
+        allowed: bool = True,
+    ) -> None:
+        self.model_pattern = model_pattern
+        self.capability = capability
+        self.allowed = allowed
+
+    def match(self, model_name: str) -> bool:
+        """检查此规则是否适用于给定的模型名。"""
+        return fnmatch.fnmatch(model_name, self.model_pattern)
+
+    def __repr__(self) -> str:
+        verb = "ALLOW" if self.allowed else "DENY"
+        return f"PermissionRule({verb} {self.capability} on {self.model_pattern!r})"
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, PermissionRule):
+            return NotImplemented
+        return (
+            self.model_pattern == other.model_pattern
+            and self.capability == other.capability
+            and self.allowed == other.allowed
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.model_pattern, self.capability, self.allowed))
+
+
+class CapabilityPermissionController:
+    """控制哪些模型允许哪些能力。
+
+    按顺序评估 :class:`PermissionRule` 列表。
+    **最后匹配的规则** 胜出（最具体的规则应放在较宽泛的规则之后）。
+    如果没有规则匹配某个模型/能力对，该能力**默认允许**。
+
+    用法::
+
+        controller = CapabilityPermissionController([
+            PermissionRule(model_pattern="*", capability="vision", allowed=False),
+            PermissionRule(model_pattern="vision-*", capability="vision", allowed=True),
+        ])
+
+        controller.check("fast-model", "vision")  # False
+        controller.check("vision-model", "vision")  # True
+    """
+
+    def __init__(self, rules: list[PermissionRule] | None = None) -> None:
+        self._rules = list(rules) if rules else []
+
+    def check(self, model_name: str, capability: str) -> bool:
+        """检查 *capability* 是否在 *model_name* 上被允许。
+
+        返回 ``True`` 表示允许，``False`` 表示拒绝。
+        """
+        result: bool | None = None
+        for rule in self._rules:
+            if rule.capability == capability and rule.match(model_name):
+                result = rule.allowed
+        # Default: allow if no rule matched
+        return result if result is not None else True
+
+    def is_allowed(self, model_name: str, capability: str) -> bool:
+        """:meth:`check` 的别名。"""
+        return self.check(model_name, capability)
+
+    def filter_capabilities(
+        self,
+        model_name: str,
+        capabilities: set[str],
+    ) -> set[str]:
+        """返回 *capabilities* 中在 *model_name* 上允许的子集。"""
+        return {c for c in capabilities if self.check(model_name, c)}

backend/app/ai_provider/routing/selector.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.ai_provider.config.models import ModelConfig
+from app.ai_provider.core.registry import ModelRegistry
+from app.ai_provider.routing.multimodal import MultiModalDecision
+from app.ai_provider.types.errors import AIProviderError
+
+_SELECTOR_CAPABILITY_MAP: dict[MultiModalDecision, str] = {
+    MultiModalDecision.VISION: "vision",
+    MultiModalDecision.THINKING: "thinking",
+    MultiModalDecision.TOOL_USE: "tool_use",
+    MultiModalDecision.STRUCTURED_OUTPUT: "structured_output",
+    MultiModalDecision.PLAIN_TEXT: "chat",
+}
+
+
+class ModelSelector:
+    """为给定上下文选择最佳模型。
+
+    用法::
+
+        selector = ModelSelector(registry)
+        model = selector.select({"capabilities": {"vision", "thinking"}})
+        model = selector.select({"preferred": "fast-model"})
+        model = selector.select_from_decisions({MultiModalDecision.VISION})
+    """
+
+    def __init__(self, registry: ModelRegistry) -> None:
+        self._registry = registry
+
+    def select(self, context: dict[str, Any]) -> ModelConfig:
+        """根据给定的上下文选择模型。
+
+        上下文键:
+
+        * ``capabilities`` (``set[str]``, 可选) — 必需的能力。
+        * ``preferred`` (``str``, 可选) — 偏好的模型名或别名。
+        * ``avoid`` (``set[str]``, 可选) — 要排除的模型名。
+
+        如果给了偏好模型但不能满足所有必需的能力，此方法会回退到
+        能满足要求的模型。
+        """
+        capabilities: set[str] = set(context.get("capabilities", set()))
+        preferred: str | None = context.get("preferred")
+        avoid: set[str] = set(context.get("avoid", set()))
+
+        # If preferred is given, resolve it and check capabilities
+        if preferred is not None:
+            model = self._registry.resolve(preferred)
+            if (
+                not capabilities or self._model_satisfies_all(model, capabilities)
+            ) and model.name not in avoid:
+                return model
+
+        # Find models that satisfy all required capabilities
+        if capabilities:
+            return self._select_by_capabilities(capabilities, avoid)
+
+        # Fall back to default
+        return self._registry.resolve()
+
+    def select_from_decisions(
+        self,
+        decisions: set[MultiModalDecision],
+    ) -> ModelConfig:
+        """基于 :class:`MultiModalDecision` 值选择模型。
+
+        将决策翻译为能力字符串并委托给 :meth:`select`。
+        """
+        capabilities: set[str] = set()
+        for d in decisions:
+            cap = _SELECTOR_CAPABILITY_MAP.get(d)
+            if cap and cap != "chat":
+                capabilities.add(cap)
+        return self.select({"capabilities": capabilities})
+
+    # ------------------------------------------------------------------
+
+    def _select_by_capabilities(
+        self,
+        capabilities: set[str],
+        avoid: set[str],
+    ) -> ModelConfig:
+        """找到支持所有必需能力的模型。"""
+        # Narrow down by each capability (ModelConfig is unhashable, use lists)
+        candidates: list[ModelConfig] = list(self._registry.list_all())
+
+        for cap in capabilities:
+            cap_models = list(self._registry.list_by_capability(cap))
+            cap_names = {m.name for m in cap_models}
+            candidates = [m for m in candidates if m.name in cap_names]
+
+        # Remove avoided models
+        candidates = [m for m in candidates if m.name not in avoid]
+
+        if not candidates:
+            raise AIProviderError(
+                message=f"No active model supports all capabilities: {capabilities}",
+                code="CAPABILITY_NOT_FOUND",
+                status_code=404,
+            )
+
+        # Prefer higher-weight models (higher = better)
+        return max(candidates, key=lambda m: m.weight)
+
+    @staticmethod
+    def _model_satisfies_all(model: ModelConfig, capabilities: set[str]) -> bool:
+        caps = model.resolved_capabilities()
+        return all(caps.get(cap, False) for cap in capabilities)