feat: 添加格式转换追踪、模型过滤规则和 Provider 超时配置

1. Usage 格式转换追踪 - 新增 endpoint_api_format 和 has_format_conversion 字段 - 在用量记录中显示格式转换信息（请求格式 → 端点格式） - 兼容历史数据的回填逻辑 2. Provider API Key 模型过滤规则 - 新增 model_include_patterns 和 model_exclude_patterns 字段 - 支持 * 和 ? 通配符，不区分大小写 - 自动获取模型时应用过滤规则 3. Provider 超时配置 - 新增 stream_first_byte_timeout 和 request_timeout 字段 - 支持每个 Provider 单独配置超时时间 - 优先使用 Provider 配置，否则回退到全局配置 Close #122, Close #123 Co-Authored-By: AAEE86 <33052466+AAEE86@users.noreply.github.com>
2026-09-02 09:20:22 +08:00 · 2026-01-28 00:04:47 +08:00
parent 3c0bf5fdae
commit c732a03263
23 changed files with 652 additions and 97 deletions
--- a/src/api/admin/endpoints/keys.py
+++ b/src/api/admin/endpoints/keys.py
@@ -224,6 +224,10 @@ class AdminUpdateEndpointKeyAdapter(AdminApiAdapter):
        # 记录 allowed_models 变化前的值
        allowed_models_before = set(key.allowed_models or [])

+        # 记录过滤规则变化前的值（用于检测是否需要重新应用过滤）
+        include_patterns_before = key.model_include_patterns
+        exclude_patterns_before = key.model_exclude_patterns
+
        update_data = self.key_data.model_dump(exclude_unset=True)
        if "api_key" in update_data:
            update_data["api_key"] = crypto_service.encrypt(update_data["api_key"])
@@ -247,6 +251,17 @@ class AdminUpdateEndpointKeyAdapter(AdminApiAdapter):
            if isinstance(lm, list) and len(lm) == 0:
                update_data["locked_models"] = None

+        # 处理模型过滤规则：空字符串 -> None
+        if "model_include_patterns" in update_data:
+            patterns = update_data["model_include_patterns"]
+            if isinstance(patterns, list) and len(patterns) == 0:
+                update_data["model_include_patterns"] = None
+
+        if "model_exclude_patterns" in update_data:
+            patterns = update_data["model_exclude_patterns"]
+            if isinstance(patterns, list) and len(patterns) == 0:
+                update_data["model_exclude_patterns"] = None
+
        for field, value in update_data.items():
            setattr(key, field, value)
        key.updated_at = datetime.now(timezone.utc)
@@ -285,6 +300,27 @@ class AdminUpdateEndpointKeyAdapter(AdminApiAdapter):
                )
            db.commit()
            db.refresh(key)
+        elif auto_fetch_enabled_after:
+            # auto_fetch_models 保持开启状态，检查过滤规则是否变更
+            include_patterns_after = key.model_include_patterns
+            exclude_patterns_after = key.model_exclude_patterns
+            patterns_changed = (
+                include_patterns_before != include_patterns_after
+                or exclude_patterns_before != exclude_patterns_after
+            )
+            if patterns_changed:
+                # 过滤规则变更，重新应用过滤（使用缓存的上游模型数据）
+                logger.info(
+                    "[AUTO_FETCH] Key %s 过滤规则变更，重新应用过滤",
+                    self.key_id,
+                )
+                try:
+                    from src.services.model.fetch_scheduler import get_model_fetch_scheduler
+
+                    scheduler = get_model_fetch_scheduler()
+                    await scheduler._fetch_models_for_key_by_id(self.key_id)
+                except Exception as e:
+                    logger.error(f"重新应用过滤规则失败: {e}")

        # 任何字段更新都清除缓存，确保缓存一致性
        # 包括 is_active、allowed_models、capabilities 等影响权限和行为的字段
@@ -622,6 +658,12 @@ class AdminCreateProviderKeyAdapter(AdminApiAdapter):
            max_probe_interval_minutes=self.key_data.max_probe_interval_minutes,
            auto_fetch_models=self.key_data.auto_fetch_models,
            locked_models=self.key_data.locked_models if self.key_data.locked_models else None,
+            model_include_patterns=(
+                self.key_data.model_include_patterns if self.key_data.model_include_patterns else None
+            ),
+            model_exclude_patterns=(
+                self.key_data.model_exclude_patterns if self.key_data.model_exclude_patterns else None
+            ),
            request_count=0,
            success_count=0,
            error_count=0,
--- a/src/api/admin/providers/routes.py
+++ b/src/api/admin/providers/routes.py
@@ -295,6 +295,9 @@ class AdminCreateProviderAdapter(AdminApiAdapter):
                concurrent_limit=validated_data.concurrent_limit,
                max_retries=validated_data.max_retries,
                proxy=validated_data.proxy.model_dump() if validated_data.proxy else None,
+                # 超时配置
+                stream_first_byte_timeout=validated_data.stream_first_byte_timeout,
+                request_timeout=validated_data.request_timeout,
                config=validated_data.config,
            )

--- a/src/api/admin/providers/summary.py
+++ b/src/api/admin/providers/summary.py
@@ -310,6 +310,8 @@ def _build_provider_summary(db: Session, provider: Provider) -> ProviderWithEndp
        quota_expires_at=provider.quota_expires_at,
        max_retries=provider.max_retries,
        proxy=provider.proxy,
+        stream_first_byte_timeout=provider.stream_first_byte_timeout,
+        request_timeout=provider.request_timeout,
        total_endpoints=total_endpoints,
        active_endpoints=active_endpoints,
        total_keys=total_keys,
--- a/src/api/admin/usage/routes.py
+++ b/src/api/admin/usage/routes.py
@@ -802,6 +802,22 @@ class AdminUsageRecordsAdapter(AdminApiAdapter):
            if usage.provider_id and str(usage.provider_id) in provider_map:
                provider_name = provider_map[str(usage.provider_id)]

+            # 格式转换追踪（兼容历史数据：尽量回填可展示信息）
+            api_format = usage.api_format or (
+                endpoint.api_format if endpoint and endpoint.api_format else None
+            )
+            endpoint_api_format = usage.endpoint_api_format or (
+                endpoint.api_format if endpoint else None
+            )
+
+            has_format_conversion = usage.has_format_conversion
+            if has_format_conversion is None:
+                client_fmt = str(api_format or "").upper()
+                endpoint_fmt = str(endpoint_api_format or "").upper()
+                has_format_conversion = bool(
+                    client_fmt and endpoint_fmt and client_fmt != endpoint_fmt
+                )
+
            data.append(
                {
                    "id": usage.id,
@@ -842,8 +858,9 @@ class AdminUsageRecordsAdapter(AdminApiAdapter):
                    "has_fallback": fallback_map.get(usage.request_id, False),
                    "has_retry": retry_map.get(usage.request_id, False),
                    "has_rectified": rectified_map.get(usage.request_id, False),
-                    "api_format": usage.api_format
-                    or (endpoint.api_format if endpoint and endpoint.api_format else None),
+                    "api_format": api_format,
+                    "endpoint_api_format": endpoint_api_format,
+                    "has_format_conversion": bool(has_format_conversion),
                    "api_key_name": provider_api_key.name if provider_api_key else None,
                    "request_metadata": usage.request_metadata,  # Provider 响应元数据
                }
--- a/src/api/handlers/base/base_handler.py
+++ b/src/api/handlers/base/base_handler.py
@@ -109,6 +109,9 @@ class MessageTelemetry:
        provider_endpoint_id: Optional[str] = None,
        provider_api_key_id: Optional[str] = None,
        api_format: Optional[str] = None,
+        # 格式转换追踪
+        endpoint_api_format: Optional[str] = None,  # 端点原生 API 格式
+        has_format_conversion: bool = False,  # 是否发生了格式转换
        # 模型映射信息
        target_model: Optional[str] = None,
        # Provider 响应元数据（如 Gemini 的 modelVersion）
@@ -135,6 +138,8 @@ class MessageTelemetry:
            cache_read_input_tokens=cache_read_tokens,
            request_type="chat",
            api_format=api_format,
+            endpoint_api_format=endpoint_api_format,
+            has_format_conversion=has_format_conversion,
            is_stream=is_stream,
            response_time_ms=response_time_ms,
            first_byte_time_ms=first_byte_time_ms,  # 传递首字时间
@@ -195,6 +200,9 @@ class MessageTelemetry:
        response_body: Optional[Dict[str, Any]] = None,
        response_headers: Optional[Dict[str, Any]] = None,
        client_response_headers: Optional[Dict[str, Any]] = None,
+        # 格式转换追踪
+        endpoint_api_format: Optional[str] = None,
+        has_format_conversion: bool = False,
        # 模型映射信息
        target_model: Optional[str] = None,
    ) -> None:
@@ -230,6 +238,8 @@ class MessageTelemetry:
            cache_read_input_tokens=cache_read_tokens,
            request_type="chat",
            api_format=api_format,
+            endpoint_api_format=endpoint_api_format,
+            has_format_conversion=has_format_conversion,
            is_stream=is_stream,
            response_time_ms=response_time_ms,
            status_code=status_code,
@@ -265,6 +275,9 @@ class MessageTelemetry:
        response_body: Optional[Dict[str, Any]] = None,
        response_headers: Optional[Dict[str, Any]] = None,
        client_response_headers: Optional[Dict[str, Any]] = None,
+        # 格式转换追踪
+        endpoint_api_format: Optional[str] = None,
+        has_format_conversion: bool = False,
        target_model: Optional[str] = None,
    ) -> None:
        """
@@ -286,6 +299,8 @@ class MessageTelemetry:
            cache_read_input_tokens=cache_read_tokens,
            request_type="chat",
            api_format=api_format,
+            endpoint_api_format=endpoint_api_format,
+            has_format_conversion=has_format_conversion,
            is_stream=is_stream,
            response_time_ms=response_time_ms,
            first_byte_time_ms=first_byte_time_ms,
@@ -488,6 +503,9 @@ class BaseMessageHandler:
        key_id = ctx.key_id
        first_byte_time_ms = ctx.first_byte_time_ms
        api_format = ctx.api_format
+        # 格式转换追踪
+        endpoint_api_format = ctx.provider_api_format or None
+        has_format_conversion = ctx.needs_conversion

        # 如果 provider 为空，记录警告（不应该发生，但用于调试）
        if not provider:
@@ -512,6 +530,8 @@ class BaseMessageHandler:
                        provider_api_key_id=key_id,
                        first_byte_time_ms=first_byte_time_ms,
                        api_format=api_format,
+                        endpoint_api_format=endpoint_api_format,
+                        has_format_conversion=has_format_conversion,
                    )
                finally:
                    db.close()
--- a/src/api/handlers/base/chat_handler_base.py
+++ b/src/api/handlers/base/chat_handler_base.py
@@ -713,7 +713,8 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
        )

        # 流式请求使用 stream_first_byte_timeout 作为首字节超时
-        request_timeout = config.stream_first_byte_timeout
+        # 优先使用 Provider 配置，否则使用全局配置
+        request_timeout = provider.stream_first_byte_timeout or config.stream_first_byte_timeout

        # 创建 HTTP 客户端（支持代理配置，从 Provider 读取）
        from src.clients.http_client import HTTPClientPool
@@ -851,6 +852,9 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
            provider_request_headers=ctx.provider_request_headers,
            response_headers=ctx.response_headers,
            client_response_headers=client_response_headers,
+            # 格式转换追踪
+            endpoint_api_format=ctx.provider_api_format or None,
+            has_format_conversion=ctx.needs_conversion,
            target_model=ctx.mapped_model,
        )

@@ -987,7 +991,8 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
            from src.clients.http_client import HTTPClientPool

            # 非流式请求使用 http_request_timeout 作为整体超时
-            request_timeout = config.http_request_timeout
+            # 优先使用 Provider 配置，否则使用全局配置
+            request_timeout = provider.request_timeout or config.http_request_timeout
            http_client = await HTTPClientPool.get_proxy_client(
                proxy_config=provider.proxy,
            )
@@ -1140,6 +1145,9 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
                is_stream=False,
                provider_request_headers=provider_request_headers,
                api_format=api_format,
+                # 格式转换追踪
+                endpoint_api_format=provider_api_format_for_error or None,
+                has_format_conversion=needs_conversion_for_error,
                provider_id=provider_id,
                provider_endpoint_id=endpoint_id,
                provider_api_key_id=key_id,
@@ -1203,6 +1211,9 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
                provider_request_headers=provider_request_headers,
                response_headers=response_headers,
                client_response_headers={"content-type": "application/json"},
+                # 格式转换追踪
+                endpoint_api_format=provider_api_format_for_error or None,
+                has_format_conversion=needs_conversion_for_error,
                target_model=mapped_model_result,
            )
            client_format = (client_api_format_for_error or "").upper()
@@ -1249,6 +1260,9 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
                response_headers=error_response_headers,
                # 非流式失败返回给客户端的是 JSON 错误响应
                client_response_headers={"content-type": "application/json"},
+                # 格式转换追踪
+                endpoint_api_format=provider_api_format_for_error or None,
+                has_format_conversion=needs_conversion_for_error,
                # 模型映射信息
                target_model=mapped_model_result,
            )
--- a/src/api/handlers/base/cli_handler_base.py
+++ b/src/api/handlers/base/cli_handler_base.py
@@ -739,7 +739,8 @@ class CliMessageHandlerBase(BaseMessageHandler):
        )

        # 流式请求使用 stream_first_byte_timeout 作为首字节超时
-        request_timeout = config.stream_first_byte_timeout
+        # 优先使用 Provider 配置，否则使用全局配置
+        request_timeout = provider.stream_first_byte_timeout or config.stream_first_byte_timeout

        logger.debug(
            f"  └─ [{self.request_id}] 发送流式请求: "
@@ -1068,7 +1069,8 @@ class CliMessageHandlerBase(BaseMessageHandler):
                provider_parser = self.parser

            # 使用共享的 TTFB 超时函数读取首字节
-            ttfb_timeout = config.stream_first_byte_timeout
+            # 优先使用 Provider 配置，否则使用全局配置
+            ttfb_timeout = provider.stream_first_byte_timeout or config.stream_first_byte_timeout
            first_chunk, aiter = await read_first_chunk_with_ttfb_timeout(
                byte_iterator,
                timeout=ttfb_timeout,
@@ -1804,6 +1806,9 @@ class CliMessageHandlerBase(BaseMessageHandler):
                        response_body=response_body,
                        response_headers=ctx.response_headers,
                        client_response_headers=client_response_headers,
+                        # 格式转换追踪
+                        endpoint_api_format=ctx.provider_api_format or None,
+                        has_format_conversion=ctx.needs_conversion,
                        # 模型映射信息
                        target_model=ctx.mapped_model,
                    )
@@ -1845,6 +1850,9 @@ class CliMessageHandlerBase(BaseMessageHandler):
                        is_stream=True,
                        provider_request_headers=ctx.provider_request_headers,
                        api_format=ctx.api_format,
+                        # 格式转换追踪
+                        endpoint_api_format=ctx.provider_api_format or None,
+                        has_format_conversion=ctx.needs_conversion,
                        # Provider 侧追踪信息（用于记录真实成本）
                        provider_id=ctx.provider_id,
                        provider_endpoint_id=ctx.endpoint_id,
@@ -1977,6 +1985,9 @@ class CliMessageHandlerBase(BaseMessageHandler):
            provider_request_headers=ctx.provider_request_headers,
            response_headers=ctx.response_headers,
            client_response_headers=client_response_headers,
+            # 格式转换追踪
+            endpoint_api_format=ctx.provider_api_format or None,
+            has_format_conversion=ctx.needs_conversion,
            # 模型映射信息
            target_model=ctx.mapped_model,
        )
@@ -2101,7 +2112,8 @@ class CliMessageHandlerBase(BaseMessageHandler):
            from src.clients.http_client import HTTPClientPool

            # 非流式请求使用 http_request_timeout 作为整体超时
-            request_timeout = config.http_request_timeout
+            # 优先使用 Provider 配置，否则使用全局配置
+            request_timeout = provider.request_timeout or config.http_request_timeout
            http_client = await HTTPClientPool.get_proxy_client(
                proxy_config=provider.proxy,
            )
@@ -2274,6 +2286,9 @@ class CliMessageHandlerBase(BaseMessageHandler):
                is_stream=False,
                provider_request_headers=provider_request_headers,
                api_format=api_format,
+                # 格式转换追踪
+                endpoint_api_format=provider_api_format or None,
+                has_format_conversion=needs_conversion,
                # Provider 侧追踪信息（用于记录真实成本）
                provider_id=provider_id,
                provider_endpoint_id=endpoint_id,
@@ -2346,6 +2361,9 @@ class CliMessageHandlerBase(BaseMessageHandler):
                response_headers=error_response_headers,
                # 非流式失败返回给客户端的是 JSON 错误响应
                client_response_headers={"content-type": "application/json"},
+                # 格式转换追踪
+                endpoint_api_format=provider_api_format or None,
+                has_format_conversion=needs_conversion,
                # 模型映射信息
                target_model=mapped_model_result,
            )
--- a/src/api/handlers/base/stream_processor.py
+++ b/src/api/handlers/base/stream_processor.py
@@ -213,7 +213,8 @@ class StreamProcessor:

        try:
            # 使用共享的 TTFB 超时函数读取首字节
-            ttfb_timeout = config.stream_first_byte_timeout
+            # 优先使用 Provider 配置，否则使用全局配置
+            ttfb_timeout = provider.stream_first_byte_timeout or config.stream_first_byte_timeout
            first_chunk, aiter = await read_first_chunk_with_ttfb_timeout(
                byte_iterator,
                timeout=ttfb_timeout,
@@ -422,6 +423,8 @@ class StreamProcessor:
                    f"[{self.request_id}] needs_conversion=True 但 provider_format 为空，回退到透传模式"
                )
                needs_conversion = False
+                # 保持 ctx 与实际行为一致，避免 Usage 记录误标记为转换
+                ctx.needs_conversion = False

            def _mark_stream_started() -> None:
                nonlocal start_time, streaming_started