llm-engine-kitty 0.1.0.dev0__py3-none-any.whl

llm_engine/kitty/client.py

@@ -0,0 +1,550 @@
+# llm_engine/kitty/client.py
+
+"""
+KittyClient：用户面向的客户端。
+
+两种部署模式：
+  1. embedded（默认）：传入 kwargs，内部 spawn 一个子进程启动 KittyServer，自动连接。
+     适合单机单租户使用，生命周期与用户进程绑定。
+  2. remote：KittyClient.connect(endpoint=..., **overrides) 连接到已经单独启动的
+     KittyServer（通过 `python -m llm_engine.kitty -c config.yaml` 启动）。
+
+用户无需接触 KittyEngineConfig / KittyEngineOverrides 类，所有参数以 kwargs 形式传入。
+"""
+
+import json
+import os
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from typing import IO, Any, Optional, TypeAlias
+
+import kitty_logger
+from tqdm import tqdm
+
+from ..schemas import (
+    InferenceParameters,
+    InferenceRequest,
+    InferenceRequestResult,
+    Message,
+    MessageRole,
+    PreparedRequest,
+    TaskStatus,
+)
+from ..utils import gen_unique_id
+from .config import KittyEngineConfig, KittyEngineOverrides
+from .protocol import MsgType, connect_endpoint, encode_frame, recv_frame
+from .schemas import MockRequest, TaskSnapshot, WireResult
+
+logger = kitty_logger.getLogger(__name__)
+
+
+@dataclass
+class ClientTaskHandle:
+    """客户端侧的任务句柄。request 由客户端缓存（WireResult 不含 request）。"""
+
+    task_id: str
+    request: InferenceRequest
+    snapshot: TaskSnapshot
+
+    @property
+    def status(self) -> TaskStatus:
+        return self.snapshot.status
+
+    def is_finished(self) -> bool:
+        return self.snapshot.is_finished()
+
+
+Key: TypeAlias = "str | ClientTaskHandle"
+
+
+# ---------------------------------------------------------------------------
+# subprocess 入口（embedded 模式）已移至 __main__.py --embedded 分支
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# KittyClient
+# ---------------------------------------------------------------------------
+
+
+class KittyClient:
+    """
+    KittyClient 客户端。直接构造为 embedded 模式；KittyClient.connect() 为 remote 模式。
+
+    线程安全 / 并发使用约束（重要）:
+        本实现仅按**单线程顺序使用**设计。`_request` 用一把全局 `self._lock`
+        把 send + recv 整段串行化，因此一旦某个调用阻塞（典型如 `wait()`：
+        server 端 `wait_task` 会一直 await `done_event` 到任务终态），**该
+        连接上所有其它 RPC（含 `submit/poll/stats/cancel/clear_done`）都会
+        排队**，并发使用会退化为完全串行。
+
+        如需并发使用：
+            - 推荐：每个使用线程持有自己的 `KittyClient`（embedded 不可，否则
+              每条都会拉一个 worker 子进程；用 `KittyClient.connect(endpoint=...)`
+              连同一个 server 即可）。
+            - 不推荐：在多个线程间共享一个实例并自己加锁——等价于退化为单线程。
+
+        协议层目前未做帧多路复用；未来若改造，本约束可放宽。
+    """
+
+    def __init__(
+        self,
+        *,
+        # —— 必填（embedded 模式） ——
+        registry_path: str,
+        default_model: Optional[str] = None,
+        # —— 引擎默认 ——
+        default_api_key: Optional[str] = None,
+        default_inference_parameters: Optional[InferenceParameters] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+        extra_payload: Optional[dict[str, Any]] = None,
+        # —— 并发/重试 ——
+        max_global_concurrency: int = 64,
+        default_timeout: Optional[float] = None,
+        default_max_retries: int = 5,
+        default_base_delay: int = 2,
+        # —— server 专属 ——
+        listen: Optional[str] = None,
+        log_level: str = "INFO",
+        # —— 连接调优 ——
+        http_client_connect_timeout: float = 10.0,
+        http_client_read_timeout: float = 3600.0,
+    ) -> None:
+        logger.debug("初始化KittyClient...")
+        self._init_common_state()
+
+        # embedded 模式：构造完整 config 并 spawn worker
+        if listen is None:
+            # 默认随机 UDS 路径，避免多实例冲突
+            tmpdir = tempfile.gettempdir()
+            listen = f"unix://{tmpdir}/kitty_{os.getpid()}_{int(time.time()*1000)}.sock"
+
+        config = KittyEngineConfig(
+            registry_path=registry_path,
+            default_model=default_model,
+            default_api_key=default_api_key,
+            default_inference_parameters=default_inference_parameters,
+            extra_headers=extra_headers or {},
+            extra_payload=extra_payload or {},
+            max_global_concurrency=max_global_concurrency,
+            default_timeout=default_timeout,
+            default_max_retries=default_max_retries,
+            default_base_delay=default_base_delay,
+            listen=listen,
+            log_level=log_level,
+            http_client_connect_timeout=http_client_connect_timeout,
+            http_client_read_timeout=http_client_read_timeout,
+        )
+        self._endpoint = listen
+        self._spawn_and_connect(config)
+        logger.debug("KittyClient初始化完成")
+
+    def _init_common_state(self) -> None:
+        """初始化跨两种部署模式共用的实例状态。"""
+        self._lock = threading.Lock()
+        self._sock: Optional[socket.socket] = None
+        self._proc: Optional[subprocess.Popen] = None
+        self._owns_process: bool = False
+        self._endpoint: str = ""
+        self._handles: dict[str, ClientTaskHandle] = {}
+        self._handles_lock = threading.Lock()
+        self._connected: bool = False
+
+    # ------------------------------------------------------------------
+    # 连接/启动
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def connect(
+        cls,
+        endpoint: str,
+        *,
+        default_model: Optional[str] = None,
+        default_api_key: Optional[str] = None,
+        default_inference_parameters: Optional[InferenceParameters] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+        extra_payload: Optional[dict[str, Any]] = None,
+        default_timeout: Optional[float] = None,
+        default_max_retries: Optional[int] = None,
+        default_base_delay: Optional[int] = None,
+    ) -> "KittyClient":
+        """连接到一个已运行的 KittyServer。kwargs 为连接级覆盖。"""
+        overrides = KittyEngineOverrides(
+            default_model=default_model,
+            default_api_key=default_api_key,
+            default_inference_parameters=default_inference_parameters,
+            extra_headers=extra_headers or {},
+            extra_payload=extra_payload or {},
+            default_timeout=default_timeout,
+            default_max_retries=default_max_retries,
+            default_base_delay=default_base_delay,
+        )
+        # remote 模式不走 embedded __init__（其需要 registry_path 且会 spawn worker）
+        self = cls.__new__(cls)
+        self._init_common_state()
+        self._endpoint = endpoint
+        self._connect_remote(endpoint, overrides)
+        return self
+
+    def _spawn_and_connect(self, config: KittyEngineConfig) -> None:
+        # 把父进程 sys.path 合并进 PYTHONPATH，兼容未 pip install 而通过 sys.path.insert 加载的场景
+        env = os.environ.copy()
+        extra_paths = os.pathsep.join(p for p in sys.path if p)
+        existing = env.get("PYTHONPATH", "")
+        env["PYTHONPATH"] = extra_paths + (os.pathsep + existing if existing else "")
+
+        proc = subprocess.Popen(
+            [sys.executable, "-m", "llm_engine.kitty", "--embedded"],
+            stdin=subprocess.PIPE,
+            env=env,
+        )
+        # 把 config 作为第一行 JSON 写入 stdin；保持 stdin 不关闭，EOF = 父进程退出
+        assert proc.stdin is not None
+        proc.stdin.write((json.dumps(config.model_dump()) + "\n").encode("utf-8"))
+        proc.stdin.flush()
+
+        self._proc = proc
+        self._owns_process = True
+        logger.info("KittyClient spawn worker pid=%d endpoint=%s", proc.pid, self._endpoint)
+
+        try:
+            sock = connect_endpoint(self._endpoint, connect_timeout=30.0)
+        except Exception:
+            if proc.poll() is None:
+                proc.terminate()
+                proc.wait(timeout=5.0)
+            raise
+        self._sock = sock
+        self._hello(overrides=None)
+        self._connected = True
+
+    def _connect_remote(self, endpoint: str, overrides: Optional[KittyEngineOverrides]) -> None:
+        sock = connect_endpoint(endpoint, connect_timeout=10.0)
+        self._sock = sock
+        self._hello(overrides=overrides)
+        self._connected = True
+        logger.info("KittyClient 已连接到 %s", endpoint)
+
+    def _hello(self, overrides: Optional[KittyEngineOverrides]) -> None:
+        payload: dict[str, Any] = {}
+        if overrides is not None and overrides.has_any():
+            payload["overrides"] = overrides.model_dump(exclude_none=True)
+        msg_type, resp = self._request(MsgType.CMD_HELLO, payload)
+        if msg_type != MsgType.MSG_WELCOME:
+            raise RuntimeError(f"HELLO 失败: msg_type={msg_type}, resp={resp}")
+
+    # ------------------------------------------------------------------
+    # 关闭
+    # ------------------------------------------------------------------
+
+    def close(self, *, shutdown_remote: bool = False, timeout: float = 10.0) -> None:
+        """关闭客户端。embedded 模式会同时停止 worker 进程。
+
+        所有网络 I/O 使用 socket timeout 保护，避免 close 阻塞在死连接上。
+        """
+        if not self._connected:
+            return
+        sock = self._sock
+        try:
+            if sock is not None:
+                # 给后续 sendall/recv 设上超时，避免 close 永久阻塞
+                try:
+                    sock.settimeout(max(0.1, timeout))
+                except OSError:
+                    pass
+                if self._owns_process or shutdown_remote:
+                    try:
+                        self._request(MsgType.CMD_SHUTDOWN, {})
+                    except Exception as e:
+                        logger.debug("CMD_SHUTDOWN 失败（忽略）: %r", e)
+                else:
+                    try:
+                        with self._lock:
+                            self._send(MsgType.CMD_BYE, {})
+                    except Exception as e:
+                        logger.debug("CMD_BYE 失败（忽略）: %r", e)
+                try:
+                    sock.close()
+                except Exception:
+                    pass
+                self._sock = None
+        finally:
+            if self._owns_process and self._proc is not None:
+                # 关闭 stdin 触发 server 端 EOF 自动退出（embedded 模式）
+                if self._proc.stdin is not None:
+                    try:
+                        self._proc.stdin.close()
+                    except Exception:
+                        pass
+                try:
+                    self._proc.wait(timeout=timeout)
+                except subprocess.TimeoutExpired:
+                    pass
+                if self._proc.poll() is None:
+                    self._proc.terminate()
+                    try:
+                        self._proc.wait(timeout=5.0)
+                    except subprocess.TimeoutExpired:
+                        pass
+                if self._proc.poll() is None:
+                    self._proc.kill()
+                    try:
+                        self._proc.wait(timeout=2.0)
+                    except subprocess.TimeoutExpired:
+                        pass
+                self._proc = None
+            self._connected = False
+
+    def __enter__(self) -> "KittyClient":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        # __del__ 中不做网络 I/O：解释器关闭阶段 socket/threading 可能已不可用。
+        # 只尽力回收 worker 子进程，避免孤儿。
+        try:
+            if getattr(self, "_sock", None) is not None:
+                try:
+                    self._sock.close()  # type: ignore[union-attr]
+                except Exception:
+                    pass
+                self._sock = None
+            proc = getattr(self, "_proc", None)
+            if getattr(self, "_owns_process", False) and proc is not None:
+                try:
+                    if proc.poll() is None:
+                        proc.terminate()
+                        proc.wait(timeout=2.0)
+                        if proc.poll() is None:
+                            proc.kill()
+                except Exception:
+                    pass
+                self._proc = None
+            self._connected = False
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------------
+    # 协议 I/O（全部加锁串行）
+    # ------------------------------------------------------------------
+
+    def _send(self, msg_type: int, payload: dict[str, Any]) -> None:
+        assert self._sock is not None
+        self._sock.sendall(encode_frame(msg_type, payload))
+
+    def _request(self, msg_type: int, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]:
+        with self._lock:
+            assert self._sock is not None
+            self._sock.sendall(encode_frame(msg_type, payload))
+            resp_type, resp = recv_frame(self._sock)
+            if resp_type == MsgType.MSG_ERROR:
+                raise RuntimeError(f"server 返回错误: {resp.get('error')}")
+            return resp_type, resp
+
+    # ------------------------------------------------------------------
+    # 任务 API
+    # ------------------------------------------------------------------
+
+    def _resolve_key(self, key: Key) -> ClientTaskHandle:
+        if isinstance(key, ClientTaskHandle):
+            return key
+        if isinstance(key, str):
+            with self._handles_lock:
+                h = self._handles.get(key)
+            if h is None:
+                raise KeyError(f"未找到 task_id='{key}' 的本地句柄")
+            return h
+        raise TypeError(f"key 必须是 str 或 ClientTaskHandle，实际: {type(key).__name__}")
+
+    def submit(
+        self,
+        request: InferenceRequest,
+        *,
+        persist: bool = False,
+        timeout: Optional[float] = None,
+    ) -> ClientTaskHandle:
+        task_id = gen_unique_id(prefix="task")
+        _, resp = self._request(
+            MsgType.CMD_SUBMIT,
+            {
+                "task_id": task_id,
+                "request": request.model_dump(),
+                "persist": persist,
+                "timeout": timeout,
+            },
+        )
+        snap = TaskSnapshot.model_validate(resp["snapshot"])
+        handle = ClientTaskHandle(task_id=task_id, request=request, snapshot=snap)
+        with self._handles_lock:
+            self._handles[task_id] = handle
+        return handle
+
+    def poll(self, key: Key) -> ClientTaskHandle:
+        h = self._resolve_key(key)
+        _, resp = self._request(MsgType.CMD_POLL, {"task_id": h.task_id})
+        snap_dict = resp.get("snapshot")
+        if snap_dict is None:
+            # server 端已不存在（可能被 pop）
+            return h
+        h.snapshot = TaskSnapshot.model_validate(snap_dict)
+        return h
+
+    def get(self, key: Key) -> Optional[InferenceRequestResult]:
+        """非阻塞消费：未完成返回 None。"""
+        h = self._resolve_key(key)
+        _, resp = self._request(MsgType.CMD_POP, {"task_id": h.task_id})
+        if not resp.get("found"):
+            return None
+        return self._consume_result(h, WireResult.model_validate(resp["result"]))
+
+    def wait(self, key: Key, timeout: Optional[float] = None) -> InferenceRequestResult:
+        """阻塞到终态。超时抛 TimeoutError（server 端任务仍在跑）。"""
+        h = self._resolve_key(key)
+        _, resp = self._request(MsgType.CMD_WAIT, {"task_id": h.task_id, "timeout": timeout})
+        if resp.get("timed_out"):
+            raise TimeoutError(f"等待任务 {h.task_id} 超时（{timeout}s）")
+        if not resp.get("found"):
+            raise RuntimeError(f"任务 {h.task_id} 在 server 端不存在")
+        return self._consume_result(h, WireResult.model_validate(resp["result"]))
+
+    def cancel(self, key: Key, force: bool = False) -> bool:
+        h = self._resolve_key(key)
+        _, resp = self._request(MsgType.CMD_CANCEL, {"task_id": h.task_id, "force": force})
+        return bool(resp.get("cancelled"))
+
+    def clear_done(self) -> int:
+        _, resp = self._request(MsgType.CMD_CLEAR_DONE, {})
+        # 必须按 server 回传的 cleared_ids 同步本地句柄，而不是凭本地
+        # `is_finished()` 判断：用户可能 submit 之后从未 poll/wait，本地
+        # snapshot.status 仍是 RUNNING/PENDING，但 server 已经把它清理掉了。
+        # 早期实现按本地状态删，会导致句柄永久残留 → 后续 wait/get 拿不到结果。
+        cleared_ids = resp.get("cleared_ids") or []
+        with self._handles_lock:
+            for tid in cleared_ids:
+                self._handles.pop(tid, None)
+        return int(resp.get("count", 0))
+
+    def mock_request_infer(self, query: str) -> MockRequest:
+        """mock_request 的字符串便捷封装，对应 infer 的调用形式。
+
+        Args:
+            query (str): 用户输入的字符串，将封装为单轮 USER 消息。
+
+        Returns:
+            MockRequest: 包含 URLs、模型名、请求头和负载的模拟请求。
+        """
+        return self.mock_request(InferenceRequest(messages=[Message(role=MessageRole.USER, content=query)]))
+
+    def mock_request(self, request: InferenceRequest) -> MockRequest:
+        """组装最终发给大模型服务商的请求，不发出任何网络调用。
+
+        用于调试：验证 URL、Headers、Payload 是否符合预期。
+
+        Args:
+            request (InferenceRequest): 推理请求对象。
+
+        Returns:
+            MockRequest: 包含 URLs、模型名、请求头和负载的模拟请求。
+        """
+        _, resp = self._request(MsgType.CMD_MOCK_REQUEST, {"request": request.model_dump()})
+        return MockRequest(urls=resp["urls"], model=resp["model"], headers=resp["headers"], payload=resp["payload"])
+
+    def ping(self) -> None:
+        self._request(MsgType.CMD_PING, {})
+
+    def stats(self) -> dict[str, Any]:
+        """查询本连接的任务状态分布，适合驱动 `finished/total` 进度条。
+
+        Returns:
+            形如::
+
+                {
+                    "total": <int, Σ counts.values()>,
+                    "finished": <int, SUCCESS + FAILED + TIMEOUT + CANCELLED + REJECTED>,
+                    "counts": {"SUBMITTED": int, "ACCEPTED": int, ..., "REJECTED": int},
+                }
+
+        计数口径说明（重要）:
+            - 非终态（SUBMITTED/ACCEPTED/PENDING/RUNNING）维护的是**当前处于该
+              状态的任务数**，会随状态前进而回落到 0。
+            - 终态（SUCCESS/FAILED/TIMEOUT/CANCELLED/REJECTED）只会累加，且 POP/WAIT
+              消费结果、CLEAR_DONE 从 server 侧摘除条目都不会使其回退（这些操作不
+              触发状态转移）。
+            - 因此对一个只管 submit / wait 的连接而言，`total` 等于累计 submit
+              的任务数，`finished` 等于累计完成数，可直接当进度条的 `n/total` 用。
+        """
+        _, resp = self._request(MsgType.CMD_STATS, {})
+        return {
+            "total": int(resp.get("total", 0)),
+            "finished": int(resp.get("finished", 0)),
+            "counts": dict(resp.get("counts") or {}),
+        }
+
+    # ------------------------------------------------------------------
+    # 结果拼装
+    # ------------------------------------------------------------------
+
+    def _consume_result(self, handle: ClientTaskHandle, wr: WireResult) -> InferenceRequestResult:
+        # 同步终态到本地 snapshot：使用 WireResult 携带的 status，以区分 FAILED / REJECTED / CANCELLED
+        handle.snapshot.status = wr.status
+        with self._handles_lock:
+            self._handles.pop(handle.task_id, None)
+        return InferenceRequestResult(
+            success=wr.success,
+            task_id=wr.task_id,
+            request=handle.request,
+            model_output=wr.model_output,
+            error_message=wr.error_message,
+            duration=wr.duration,
+        )
+
+    # ------------------------------------------------------------------
+    # 同步便捷接口
+    # ------------------------------------------------------------------
+
+    def inference(self, request: InferenceRequest) -> InferenceRequestResult:
+        return self.wait(self.submit(request))
+
+    def infer(self, query: str) -> str:
+        result = self.inference(InferenceRequest(messages=[Message(role=MessageRole.USER, content=query)]))
+        if result.success and result.model_output is not None:
+            return result.model_output.content
+        return ""
+
+    def batch_inference(
+        self,
+        requests: list[InferenceRequest],
+        output_file: Optional[str] = None,
+        silent_mode: bool = False,
+    ) -> list[InferenceRequestResult]:
+        handles = [self.submit(req) for req in requests]
+        pbar: Optional[tqdm] = tqdm(total=len(requests), desc="Batch: Kitty") if not silent_mode else None
+        f: Optional[IO[str]] = open(output_file, "w", encoding="utf-8") if output_file else None
+        results: list[InferenceRequestResult] = []
+        try:
+            for h in handles:
+                result = self.wait(h)
+                results.append(result)
+                if f is not None:
+                    f.write(result.model_dump_json() + "\n")
+                    f.flush()
+                if pbar is not None:
+                    pbar.update(1)
+        finally:
+            if pbar is not None:
+                pbar.close()
+            if f is not None:
+                f.close()
+        return results
+
+    def batch_infer(self, queries: list[str], **kwargs: Any) -> list[str]:
+        reqs = [InferenceRequest(messages=[Message(role=MessageRole.USER, content=q)]) for q in queries]
+        results = self.batch_inference(reqs, **kwargs)
+        return [r.model_output.content if r.success and r.model_output else "" for r in results]

llm_engine/kitty/config.py

@@ -0,0 +1,83 @@
+# llm_engine/kitty/config.py
+
+"""
+KittyEngine 配置数据结构。
+
+- KittyEngineConfig：引擎完整配置。由 server 启动时从 YAML 加载；embedded 模式下
+  由 KittyEngine.__init__ 根据 kwargs 内部构造后 pickle 给 worker 子进程。
+- KittyEngineOverrides：client 连接时可选的覆盖集。每个字段均 Optional，不包含
+  server 全局资源字段（registry_path / max_global_concurrency / listen）。
+
+两者均为内部数据结构，不通过顶层 __init__.py 导出给用户。
+"""
+
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..schemas import InferenceParameters
+
+
+class KittyEngineConfig(BaseModel):
+    """KittyEngine 完整运行时配置。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # —— 模型注册表 ——
+    registry_path: str = Field(description="ModelConfigRegistry 的 JSON 配置路径")
+
+    # —— 引擎默认 ——
+    default_model: Optional[str] = None
+    default_api_key: Optional[str] = None
+    default_inference_parameters: Optional[InferenceParameters] = None
+    extra_headers: dict[str, str] = Field(default_factory=dict)
+    extra_payload: dict[str, Any] = Field(default_factory=dict)
+
+    # —— 并发与重试（server 全局，不可被 client 覆盖） ——
+    max_global_concurrency: int = Field(default=64, ge=1)
+    default_timeout: Optional[float] = None
+    # max_retries 语义为"包含首次的总尝试次数"，因此最小值是 1（即不重试，只跑一次）。
+    # 若传 0，会让 _send_request 的 for-range 循环不执行而落入 "Unexpected end of retry loop" 死代码。
+    default_max_retries: int = Field(default=5, ge=1)
+    default_base_delay: int = Field(default=2, ge=1)
+
+    # —— server 专属 ——
+    listen: str = "unix:///tmp/kitty.sock"
+    log_level: str = "INFO"
+
+    # —— 连接调优 ——
+    http_client_connect_timeout: float = 10.0
+    http_client_read_timeout: float = 3600.0
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> "KittyEngineConfig":
+        path = Path(path)
+        with open(path, mode="r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+        if not isinstance(data, dict):
+            raise ValueError(f"YAML 根节点必须是映射: {path}")
+        return cls.model_validate(data)
+
+
+class KittyEngineOverrides(BaseModel):
+    """Client 连接时可携带的覆盖项。不含 server 全局资源字段。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    default_model: Optional[str] = None
+    default_api_key: Optional[str] = None
+    default_inference_parameters: Optional[InferenceParameters] = None
+    extra_headers: dict[str, str] = Field(default_factory=dict)
+    extra_payload: dict[str, Any] = Field(default_factory=dict)
+    default_timeout: Optional[float] = None
+    # 同 KittyEngineConfig：>=1，None 表示"不覆盖、用 server 默认"。
+    default_max_retries: Optional[int] = Field(default=None, ge=1)
+    default_base_delay: Optional[int] = Field(default=None, ge=1)
+
+    def has_any(self) -> bool:
+        """是否包含任何非默认值。空 overrides 可免发 HELLO。"""
+        dumped = self.model_dump(exclude_none=True)
+        # extra_headers / extra_payload 的默认值是空 dict，dump 会保留；过滤掉
+        return any(v for v in dumped.values())