free-short-video 5.1.2

package/core/api/error_collector.py

@@ -0,0 +1,215 @@
+"""core.api.error_collector — 模型接口报错收集模块
+
+    收集 Agnes 文本/图片/视频模型 API 调用失败时的报错信息，
+    包含 prompt、错误类型、错误详情等，存储在工作目录下的 error_logs/ 中。
+
+    使用方式：
+        from core.api.error_collector import collect_error, collect_error_from_exception
+
+        # 方式一：手动构造
+        collect_error(model_type="image", api_method="generate_single_image",
+                      prompt="一只猫", error_type="ConnectionError",
+                      error_message="Connection timed out", retry_count=3)
+
+        # 方式二：从异常对象收集（自动提取 HTTPError 响应体中的 API 错误详情）
+        collect_error_from_exception("chat", "chat", exc, prompt="你好")
+"""
+
+import json
+import logging
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import requests as _requests_lib
+
+logger = logging.getLogger(__name__)
+
+_WORKSPACE_ROOT: Optional[Path] = None
+
+
+def set_workspace_root(path: str) -> None:
+    """设置错误日志存储的根目录（通常为激活的工作空间路径）。
+
+    应在服务启动时调用一次。如果不设置，则回退到 server.py 所在目录。
+    """
+    global _WORKSPACE_ROOT
+    _WORKSPACE_ROOT = Path(path).resolve()
+    logger.info(f"[ErrorCollector] Workspace root set to {_WORKSPACE_ROOT}")
+
+
+def _get_workspace_root() -> Path:
+    """获取存储根目录。
+
+    优先级：
+    1. set_workspace_root() 显式设置
+    2. 自动检测 server.py 所在目录
+    """
+    global _WORKSPACE_ROOT
+    if _WORKSPACE_ROOT is not None:
+        return _WORKSPACE_ROOT
+    current = Path(os.getcwd()).resolve()
+    for parent in [current] + list(current.parents):
+        if (parent / "server.py").exists():
+            _WORKSPACE_ROOT = parent
+            break
+    if _WORKSPACE_ROOT is None:
+        _WORKSPACE_ROOT = current
+    return _WORKSPACE_ROOT
+
+
+def _get_log_dir() -> Path:
+    """获取 error_logs 目录路径，不存在则创建。"""
+    log_dir = _get_workspace_root() / "error_logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir
+
+
+def _extract_from_http_error(exc: Exception) -> tuple[Optional[int], str, str]:
+    """从 HTTPError 异常中提取状态码、响应体、以及 API 级错误详情。
+
+    返回 (status_code, response_body, enhanced_message)。
+    如果 exc 不是 HTTPError 或提取失败，返回 (None, "", str(exc))。
+    """
+    try:
+        if isinstance(exc, _requests_lib.exceptions.HTTPError):
+            resp = getattr(exc, "response", None)
+            if resp is not None:
+                sc = resp.status_code
+                body = resp.text or ""
+                enhanced = str(exc)
+
+                # 尝试从 JSON 响应体中提取 API 级错误详情
+                if body.strip():
+                    try:
+                        data = json.loads(body)
+                        err = data.get("error", {})
+                        api_msg = err.get("message", "") if isinstance(err, dict) else str(err)
+                        api_type = err.get("type", "") if isinstance(err, dict) else ""
+                        if api_msg:
+                            # 优先使用 API 级错误消息，避免重复拼接 type
+                            if api_type and api_msg.startswith(api_type):
+                                # message 已含 type 前缀，不再重复
+                                enhanced = f"{api_msg} (HTTP {sc})"
+                            elif api_type:
+                                enhanced = f"{api_type}: {api_msg} (HTTP {sc})"
+                            else:
+                                enhanced = f"{api_msg} (HTTP {sc})"
+                        else:
+                            enhanced = enhanced + " | body=" + body[:500]
+                    except (json.JSONDecodeError, ValueError):
+                        enhanced = enhanced + " | body=" + body[:500]
+
+                return sc, body, enhanced
+    except Exception:
+        pass
+    return None, "", str(exc)
+
+
+def collect_error(
+    model_type: str,
+    api_method: str,
+    prompt: str = "",
+    system_prompt: str = "",
+    error_type: str = "",
+    error_message: str = "",
+    status_code: Optional[int] = None,
+    response_body: str = "",
+    retry_count: int = 0,
+    extra: Optional[dict] = None,
+) -> Optional[str]:
+    """收集一次 API 调用错误并写入 error_logs/ 目录。
+
+    返回保存的文件路径，如果收集过程自身出错则返回 None（不影响主流程）。
+
+    Args:
+        model_type: 模型类型，如 "chat", "image", "video"。
+        api_method: 调用的方法名，如 "chat", "generate_single_image", "submit_video"。
+        prompt: 发送给模型的 prompt（超长自动截断至 5000 字符）。
+        system_prompt: system 提示词（仅 chat 类，截断至 2000 字符）。
+        error_type: 错误类型名称，如 "ConnectionError", "HTTPError", "RuntimeError"。
+        error_message: 错误消息原文。
+        status_code: HTTP 状态码（如有）。
+        response_body: 响应体原文（截断至 5000 字符）。
+        retry_count: 失败前已尝试的重试次数。
+        extra: 额外结构化信息（如 video_id, mode 等）。
+    """
+    try:
+        log_dir = _get_log_dir()
+        now = datetime.now()
+        filename = (
+            now.strftime("%Y-%m-%d_%H-%M-%S-%f")
+            + f"_{model_type}_{api_method}.json"
+        )
+        filepath = log_dir / filename
+
+        # 限制字段长度，避免日志文件过大
+        error_data = {
+            "timestamp": now.isoformat(),
+            "model_type": model_type,
+            "api_method": api_method,
+            "prompt": prompt[:5000] if prompt else "",
+            "system_prompt": system_prompt[:2000] if system_prompt else "",
+            "error_type": error_type,
+            "error_message": error_message[:3000] if error_message else "",
+            "status_code": status_code,
+            "response_body": response_body[:5000] if response_body else "",
+            "retry_count": retry_count,
+        }
+        if extra:
+            error_data["extra"] = extra
+
+        with open(filepath, "w", encoding="utf-8") as f:
+            json.dump(error_data, f, ensure_ascii=False, indent=2)
+
+        logger.info(f"[ErrorCollector] Error saved → {filepath}")
+        return str(filepath)
+
+    except Exception as e:
+        logger.error(f"[ErrorCollector] Failed to collect error: {e}")
+        return None
+
+
+def collect_error_from_exception(
+    model_type: str,
+    api_method: str,
+    exc: Exception,
+    prompt: str = "",
+    system_prompt: str = "",
+    status_code: Optional[int] = None,
+    response_body: str = "",
+    retry_count: int = 0,
+    extra: Optional[dict] = None,
+) -> Optional[str]:
+    """便捷包装：从异常对象自动提取 error_type 和 error_message。
+
+    对于 requests.HTTPError，会自动从 exc.response 中提取状态码和响应体，
+    并尝试解析 JSON 获取 API 级错误详情（如 content_policy_violation）。
+    如果调用方已传入 status_code / response_body，则优先使用传入值。
+    """
+    error_type = type(exc).__name__
+    error_msg = str(exc)
+
+    # 自动提取 HTTPError 的响应信息（仅在未显式传入时填充）
+    extracted_sc, extracted_body, extracted_msg = _extract_from_http_error(exc)
+    if status_code is None:
+        status_code = extracted_sc
+    if not response_body:
+        response_body = extracted_body
+    # 如果有 API 级错误详情，优先使用
+    if extracted_msg != str(exc):
+        error_msg = extracted_msg
+
+    return collect_error(
+        model_type=model_type,
+        api_method=api_method,
+        prompt=prompt,
+        system_prompt=system_prompt,
+        error_type=error_type,
+        error_message=error_msg,
+        status_code=status_code,
+        response_body=response_body,
+        retry_count=retry_count,
+        extra=extra,
+    )

package/core/api/rate_limiter.py

@@ -0,0 +1,142 @@
+"""core.api.rate_limiter — Agnes API 全局限速器（令牌桶算法）
+
+所有 Agnes API 调用（Chat / Image / Video，含轮询）共享同一个令牌桶，
+确保总调用频率不超过 Agnes API 的 20 次/分钟限制。
+
+用法::
+
+    from core.api.rate_limiter import get_rate_limiter
+
+    # 在发起 HTTP 请求前获取令牌（同步，可能阻塞）
+    limiter = get_rate_limiter()
+    limiter.acquire()
+    resp = requests.post(url, ...)
+
+    # 异步版本（内部用 to_thread 包装）
+    await limiter.acquire_async()
+
+环境变量:
+    AGNES_RATE_LIMIT: 每分钟最大调用次数，默认 20
+"""
+
+import asyncio
+import logging
+import os
+import threading
+import time
+
+logger = logging.getLogger(__name__)
+
+# Agnes API 所有接口共享的每分钟调用上限
+_AGNES_RATE_LIMIT = int(os.environ.get("AGNES_RATE_LIMIT", "20"))
+# 预留 20% 余量：实际允许 80% 的配额，即 16 次/分钟（3.75 秒/次）
+_SAFETY_FACTOR = 0.8
+_EFFECTIVE_RATE = _AGNES_RATE_LIMIT * _SAFETY_FACTOR  # 16 次/分钟
+
+
+class AgnesRateLimiter:
+    """令牌桶限速器（线程安全）。
+
+    在多线程 / asyncio.to_thread / 纯同步场景下均可安全使用。
+    当令牌不足时，``acquire()`` 会阻塞当前线程直到令牌可用。
+
+    Attributes:
+        max_tokens: 桶容量（突发上限）。
+        refill_rate: 每秒补充的令牌数。
+    """
+
+    def __init__(self, rate_per_minute: float = _EFFECTIVE_RATE,
+                 max_burst: int = 4):
+        """初始化限速器。
+
+        Args:
+            rate_per_minute: 每分钟允许的调用次数。
+            max_burst: 令牌桶最大容量（允许短时突发）。
+        """
+        self.max_tokens = min(max_burst, rate_per_minute)
+        self.refill_rate = rate_per_minute / 60.0  # tokens per second
+        self.tokens = float(self.max_tokens)
+        self.last_refill = time.monotonic()
+        self._lock = threading.Lock()
+        self._total_waits = 0
+        self._total_wait_seconds = 0.0
+
+    def acquire(self) -> None:
+        """阻塞式获取一个令牌。
+
+        如果桶中有令牌，立即消耗并返回。
+        否则计算等待时间并 ``time.sleep()`` 直到令牌可用。
+        """
+        with self._lock:
+            now = time.monotonic()
+            elapsed = now - self.last_refill
+            self.tokens = min(
+                self.max_tokens,
+                self.tokens + elapsed * self.refill_rate,
+            )
+            self.last_refill = now
+
+            if self.tokens >= 1.0:
+                self.tokens -= 1.0
+                return
+
+            # 需要等待的时间
+            wait_time = (1.0 - self.tokens) / self.refill_rate
+            self.tokens = 0.0
+            # 更新 refill 时间基准，防止 sleep 期间令牌被其他线程"偷走"
+            self.last_refill = now + wait_time
+
+        # sleep 在锁外执行，避免阻塞其他线程的 refill 计算
+        if wait_time > 0.05:
+            self._total_waits += 1
+            self._total_wait_seconds += wait_time
+            logger.info(
+                f"[RateLimiter] 限速等待 {wait_time:.1f}s "
+                f"(累计等待 {self._total_waits} 次, "
+                f"{self._total_wait_seconds:.0f}s)"
+            )
+            time.sleep(wait_time)
+
+    async def acquire_async(self) -> None:
+        """异步获取令牌（内部使用 ``asyncio.to_thread``）。"""
+        await asyncio.to_thread(self.acquire)
+
+    @property
+    def stats(self) -> dict:
+        """返回限速器统计信息。"""
+        return {
+            "total_waits": self._total_waits,
+            "total_wait_seconds": round(self._total_wait_seconds, 1),
+            "effective_rate_per_min": round(_EFFECTIVE_RATE, 1),
+            "max_burst": self.max_tokens,
+        }
+
+
+# ═══════════════════════════════════════════════════
+# 全局单例
+# ═══════════════════════════════════════════════════
+
+_instance: AgnesRateLimiter | None = None
+_instance_lock = threading.Lock()
+
+
+def get_rate_limiter() -> AgnesRateLimiter:
+    """获取全局速率限制器实例（线程安全单例）。"""
+    global _instance
+    if _instance is None:
+        with _instance_lock:
+            if _instance is None:
+                _instance = AgnesRateLimiter()
+                logger.info(
+                    f"[RateLimiter] 初始化: {_EFFECTIVE_RATE:.0f} 次/分钟 "
+                    f"(原始限制 {_AGNES_RATE_LIMIT}, 安全系数 {_SAFETY_FACTOR}), "
+                    f"突发上限 {_instance.max_tokens}"
+                )
+    return _instance
+
+
+def reset_rate_limiter() -> None:
+    """重置全局限速器（仅用于测试）。"""
+    global _instance
+    with _instance_lock:
+        _instance = None