sdpy-kit 0.7.1__tar.gz → 0.7.2__tar.gz

{sdpy_kit-0.7.1 → sdpy_kit-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.7.1
+Version: 0.7.2
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -835,7 +835,7 @@ shutdown()                                                     # 应用退出前
 |------|------|------|
 | chat | `chat_complete(prompt, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 单轮对话（仅 user 消息） |
 | chat | `chat_ask(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
-| chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied` |
+| chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
 | rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表；**`top_n` 是返回条数上限，由 kit 本地裁剪**（服务端返回超量也按分数截断），`top_n=None` 返回全部命中 |
@@ -869,39 +869,44 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 
 #### 流式收尾统计（思考型模型必备）
 
-迭代器在流结束后可读七个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
-`truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
-token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」（同一套字段也可用于非流式 `ask` / `complete`，
-见下文「结构化输出」）。
+迭代器在流结束后可读八个字段（`reasoning_chars` / `content_chars` / `finish_reason` /
+`requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied`），
+其中 `truncated` 与 `empty_kind` 是只读派生属性。用于区分「模型真的没返回」与「输出预算被思考吃光」——
+思考型模型的推理 token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」
+（同一套字段也可用于非流式 `ask` / `complete`，见下文「结构化输出」）。
 
-`empty_kind` 把「正文为空」分成四类，不再一律归因为预算耗尽：
+`empty_kind` 把「正文为空」分成五类，不再一律归因为预算耗尽：
 
 | 取值 | 判定 | 建议处置 |
 |---|---|---|
 | `budget_exhausted` | 被长度截断且有推理 | 调大 `max_tokens`，或对该调用传 `thinking=False` |
+| `truncated_empty` | 被长度截断且无推理 | 调大 `max_tokens`；若模型支持独立推理预算，确认推理是否计入输出配额 |
 | `reasoning_only` | 有推理、`finish_reason=stop`、正文 0 | 提高预算或换模型 |
-| `no_finish` | 有推理但没收到结束原因（链路中断 / 端点未收尾） | 优先重试，连续出现检查端点/代理超时 |
+| `no_finish` | 结束原因缺失或非 `stop`（端点未发送 `finish_reason`） | 可原样重试；连续出现检查端点 |
 | `stopped_empty` | 无推理、`finish_reason=stop`、正文 0 | 检查提示词与模型输出 |
 
-正文非空时 `empty_kind is None`。判定只用「是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）：
+正文非空时 `empty_kind is None`。判定只用「是否截断 + 是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）：
 
 ```python
 with AI.chat_stream(messages, max_tokens=450) as stream:
     body = "".join(stream)
 if not body:
     match stream.empty_kind:
-        case "budget_exhausted":
-            ...  # 调大 max_tokens 或 thinking=False
+        case "budget_exhausted" | "truncated_empty":
+            ...  # 调大 max_tokens（或配独立推理预算）
         case "no_finish":
-            ...  # 优先重试
+            ...  # 原样重试
 ```
 
+`requested_max_tokens` 是本次**实际下发**的输出上限（调用方传值优先，否则取档案 `max_tokens`；都没有为 `None`），
+在发请求前写入，失败/中断时也可读——业务可据此判断「预算是否真的设够了」。
+
 - 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
 - 推理字段名是 kit 内部白名单（当前就是上面两种）：新 provider 若用别的字段名，`reasoning_chars` 会恒为 0——此时仍可用 `truncated` / `empty_kind` 判定；
 - 正文为空时 kit 按 `empty_kind` 分级打 `WARNING`（含模型、`max_tokens`、`finish_reason` 与推荐处置），不再统一归因「预算被思考耗尽」；
 - `truncated` 覆盖 `finish_reason` 为 `length` 或 `max_tokens` 两种口径；
 - **字符数 ≠ token 数**（实测中文约 2~2.5 字符/token，各家口径不一），不要用 `reasoning_chars` 反推还差多少预算；
-- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；
+- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；正文为空则归为 `no_finish`（可原样重试）；
 - 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
 
 #### 逐调用思考开关

{sdpy_kit-0.7.1 → sdpy_kit-0.7.2}/README.md

@@ -753,7 +753,7 @@ shutdown()                                                     # 应用退出前
 |------|------|------|
 | chat | `chat_complete(prompt, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 单轮对话（仅 user 消息） |
 | chat | `chat_ask(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
-| chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied` |
+| chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
 | rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表；**`top_n` 是返回条数上限，由 kit 本地裁剪**（服务端返回超量也按分数截断），`top_n=None` 返回全部命中 |
@@ -787,39 +787,44 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 
 #### 流式收尾统计（思考型模型必备）
 
-迭代器在流结束后可读七个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
-`truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
-token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」（同一套字段也可用于非流式 `ask` / `complete`，
-见下文「结构化输出」）。
+迭代器在流结束后可读八个字段（`reasoning_chars` / `content_chars` / `finish_reason` /
+`requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied`），
+其中 `truncated` 与 `empty_kind` 是只读派生属性。用于区分「模型真的没返回」与「输出预算被思考吃光」——
+思考型模型的推理 token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」
+（同一套字段也可用于非流式 `ask` / `complete`，见下文「结构化输出」）。
 
-`empty_kind` 把「正文为空」分成四类，不再一律归因为预算耗尽：
+`empty_kind` 把「正文为空」分成五类，不再一律归因为预算耗尽：
 
 | 取值 | 判定 | 建议处置 |
 |---|---|---|
 | `budget_exhausted` | 被长度截断且有推理 | 调大 `max_tokens`，或对该调用传 `thinking=False` |
+| `truncated_empty` | 被长度截断且无推理 | 调大 `max_tokens`；若模型支持独立推理预算，确认推理是否计入输出配额 |
 | `reasoning_only` | 有推理、`finish_reason=stop`、正文 0 | 提高预算或换模型 |
-| `no_finish` | 有推理但没收到结束原因（链路中断 / 端点未收尾） | 优先重试，连续出现检查端点/代理超时 |
+| `no_finish` | 结束原因缺失或非 `stop`（端点未发送 `finish_reason`） | 可原样重试；连续出现检查端点 |
 | `stopped_empty` | 无推理、`finish_reason=stop`、正文 0 | 检查提示词与模型输出 |
 
-正文非空时 `empty_kind is None`。判定只用「是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）：
+正文非空时 `empty_kind is None`。判定只用「是否截断 + 是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）：
 
 ```python
 with AI.chat_stream(messages, max_tokens=450) as stream:
     body = "".join(stream)
 if not body:
     match stream.empty_kind:
-        case "budget_exhausted":
-            ...  # 调大 max_tokens 或 thinking=False
+        case "budget_exhausted" | "truncated_empty":
+            ...  # 调大 max_tokens（或配独立推理预算）
         case "no_finish":
-            ...  # 优先重试
+            ...  # 原样重试
 ```
 
+`requested_max_tokens` 是本次**实际下发**的输出上限（调用方传值优先，否则取档案 `max_tokens`；都没有为 `None`），
+在发请求前写入，失败/中断时也可读——业务可据此判断「预算是否真的设够了」。
+
 - 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
 - 推理字段名是 kit 内部白名单（当前就是上面两种）：新 provider 若用别的字段名，`reasoning_chars` 会恒为 0——此时仍可用 `truncated` / `empty_kind` 判定；
 - 正文为空时 kit 按 `empty_kind` 分级打 `WARNING`（含模型、`max_tokens`、`finish_reason` 与推荐处置），不再统一归因「预算被思考耗尽」；
 - `truncated` 覆盖 `finish_reason` 为 `length` 或 `max_tokens` 两种口径；
 - **字符数 ≠ token 数**（实测中文约 2~2.5 字符/token，各家口径不一），不要用 `reasoning_chars` 反推还差多少预算；
-- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；
+- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；正文为空则归为 `no_finish`（可原样重试）；
 - 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
 
 #### 逐调用思考开关

{sdpy_kit-0.7.1 → sdpy_kit-0.7.2}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.7.1 → sdpy_kit-0.7.2}/kit/ai/chat_service.py

@@ -29,7 +29,11 @@ from dataclasses import dataclass
 from typing import Any, ClassVar, Final, cast
 
 from kit.ai.exceptions import AIError, AIResponseError
-from kit.ai.profiles import _RESERVED_PAYLOAD_KEYS, ModelProfile
+from kit.ai.profiles import (
+    _RESERVED_PAYLOAD_KEYS,
+    ModelProfile,
+    resolve_max_tokens,
+)
 from kit.ai.sdk_client import SdkServiceBase
 from kit.ai.types import JSONObject
 from kit.config.log_config import get_default_logger
@@ -50,15 +54,17 @@ _TRUNCATED_REASONS: Final[frozenset[str]] = frozenset({"length", "max_tokens"})
 # 空正文诊断分级 → 告警文案（正文为 0 时才有分级，见 _classify_empty）
 _EMPTY_HINTS: Final[dict[str, str]] = {
     "budget_exhausted": "输出预算疑被思考耗尽（长度截断）",
+    "truncated_empty": "输出被长度截断、正文为空（无推理）",
     "reasoning_only": "只产出推理、正文为空（finish=stop）",
-    "no_finish": "只产出推理、未收到结束原因（链路中断或端点未收尾）",
+    "no_finish": "正文为空且未收到正常结束原因",
     "stopped_empty": "无正文输出（finish=stop）",
 }
 
 _EMPTY_ACTIONS: Final[dict[str, str]] = {
     "budget_exhausted": "（可调大 max_tokens，或对该调用传 thinking=False 关闭思考）",
+    "truncated_empty": "（调大 max_tokens；若模型支持独立推理预算，确认推理是否计入输出配额）",
     "reasoning_only": "（推理未触顶但正文为空，可提高预算或换模型）",
-    "no_finish": "（优先重试；连续出现请检查端点/代理超时）",
+    "no_finish": "（端点未发送 finish_reason 或异常结束，可原样重试）",
     "stopped_empty": "（检查提示词与模型输出）",
 }
 
@@ -70,20 +76,24 @@ def _classify_empty(
     finish_reason: str | None,
     truncated: bool,
 ) -> str | None:
-    """空正文诊断分级；正文非空或无法归因时返回 None。
+    """空正文诊断分级；正文非空返回 None。
 
     - ``budget_exhausted``：被截断且有推理（预算被思考吃满）
+    - ``truncated_empty``：被截断且无推理（一个正文字符都没出）
     - ``reasoning_only``：有推理、``finish_reason=stop``
-    - ``no_finish``：有推理但结束原因缺失或非 stop
+    - ``no_finish``：结束原因缺失或非 stop（无论有无推理）
     - ``stopped_empty``：无推理、``finish_reason=stop``
     """
     if content_chars:
         return None
-    if truncated and reasoning_chars:
-        return "budget_exhausted"
+    if truncated:
+        return "budget_exhausted" if reasoning_chars else "truncated_empty"
     if reasoning_chars:
         return "reasoning_only" if finish_reason == "stop" else "no_finish"
-    return "stopped_empty" if finish_reason == "stop" else None
+    if finish_reason == "stop":
+        return "stopped_empty"
+    return "no_finish"
+
 
 # 「无注入值」哨兵：区分「不注入」与「注入值为 None」
 _UNSET: Final[object] = object()
@@ -172,10 +182,13 @@ class StreamStats:
             True 已按档案声明注入 / False 要求了但档案完全没有 thinking 声明
         json_mode_applied: 结构化输出是否生效——None 本次未要求注入 /
             True 已注入 / False 要求了但档案声明不支持（已忽略）
+        requested_max_tokens: 本次实际下发的输出上限（调用方 → 档案回落）；
+            None 表示未下发、由 provider 默认值决定。在发出请求前写入，
+            失败/中断时也可读
 
     只读派生属性：``truncated``（是否截断）、``empty_kind``（正文为空时的
-    诊断分级：``budget_exhausted`` / ``reasoning_only`` / ``no_finish`` /
-    ``stopped_empty``；正文非空为 None）。
+    诊断分级：``budget_exhausted`` / ``truncated_empty`` / ``reasoning_only`` /
+    ``no_finish`` / ``stopped_empty``；正文非空为 None）。
     """
 
     reasoning_chars: int = 0
@@ -183,6 +196,7 @@ class StreamStats:
     finish_reason: str | None = None
     thinking_applied: bool | None = None
     json_mode_applied: bool | None = None
+    requested_max_tokens: int | None = None
 
     @property
     def truncated(self) -> bool:
@@ -193,9 +207,10 @@ class StreamStats:
     def empty_kind(self) -> str | None:
         """正文为空时的诊断分级；正文非空返回 None。
 
-        取值：``budget_exhausted`` / ``reasoning_only`` / ``no_finish`` /
-        ``stopped_empty``。不依赖 token 数量，用「是否有推理 + 结束原因」
-        区分「预算吃满」「只推理」「链路未收尾」「正常停住」。
+        取值：``budget_exhausted`` / ``truncated_empty`` / ``reasoning_only`` /
+        ``no_finish`` / ``stopped_empty``。不依赖 token 数量，用「是否截断 +
+        是否有推理 + 结束原因」区分「预算吃满」「截断且无正文」「只推理」
+        「未正常收尾」「正常停住」。
         """
         return _classify_empty(
             content_chars=self.content_chars,
@@ -211,6 +226,7 @@ class StreamStats:
         self.finish_reason = None
         self.thinking_applied = None
         self.json_mode_applied = None
+        self.requested_max_tokens = None
 
 
 @dataclass(frozen=True)
@@ -383,7 +399,8 @@ class ChatService(SdkServiceBase):
             response_format: 协议级原样透传（含 ``json_schema`` 严格模式）；
                 与 ``json_mode`` 互斥，schema 由调用方负责
             stats: 收尾统计累加器（可选）；传入后可读 ``finish_reason`` /
-                ``truncated`` / ``reasoning_chars`` / ``json_mode_applied``
+                ``truncated`` / ``empty_kind`` / ``requested_max_tokens`` /
+                ``reasoning_chars`` / ``json_mode_applied``
             deadline: 整链预算截止时刻（``time.monotonic()`` 秒），约束
                 5xx 重试预算；None 表示不限制
         """
@@ -397,6 +414,9 @@ class ChatService(SdkServiceBase):
             stats=stats,
         )
         extra_body, response_format_arg = self._build_injection(request)
+        effective_max_tokens = resolve_max_tokens(self._profile, request.max_tokens)
+        if stats is not None:
+            stats.requested_max_tokens = effective_max_tokens
         self._debug_payload(
             {
                 "model": self._profile.model,
@@ -434,11 +454,6 @@ class ChatService(SdkServiceBase):
             finish_reason=finish,
             truncated=truncated,
         )
-        effective_max_tokens = (
-            request.max_tokens
-            if request.max_tokens is not None
-            else self._profile.max_tokens
-        )
         if kind is not None:
             self._log_empty(
                 kind=kind,
@@ -505,11 +520,12 @@ class ChatService(SdkServiceBase):
                 kit 不做增量解析
             response_format: 协议级原样透传（与 ``json_mode`` 互斥）
             stats: 收尾统计累加器（可选）；None 时内部创建后丢弃——需要
-                ``reasoning_chars`` / ``finish_reason`` / ``truncated`` 时
-                由调用方传入一个实例
+                ``reasoning_chars`` / ``finish_reason`` / ``truncated`` /
+                ``empty_kind`` / ``requested_max_tokens`` 时由调用方传入
 
         推理内容（``delta.reasoning_content`` / ``delta.reasoning``）只计数
-        不产出；正文为空且被截断（或发生过思考）时输出 warning。
+        不产出；正文为空时按 ``empty_kind`` 分级输出 warning（不依赖是否有
+        推理或是否截断）。
         """
         stats = stats if stats is not None else StreamStats()
         request = ChatRequest(
@@ -523,6 +539,8 @@ class ChatService(SdkServiceBase):
             stats=stats,
         )
         extra_body, response_format_arg = self._build_injection(request)
+        effective_max_tokens = resolve_max_tokens(self._profile, request.max_tokens)
+        stats.requested_max_tokens = effective_max_tokens
         desc = self._log_desc()
         # 惰性 Start：异步生成器体在首次 __anext__ 前不执行，不消费不打日志
         logger.info(f"********** {desc} ********** Start")
@@ -561,11 +579,6 @@ class ChatService(SdkServiceBase):
             note = "（中断）"
             raise
         else:
-            effective_max_tokens = (
-                request.max_tokens
-                if request.max_tokens is not None
-                else self._profile.max_tokens
-            )
             self._warn_if_empty(stats, effective_max_tokens)
         finally:
             log = logger.error if failed else logger.info
@@ -574,7 +587,7 @@ class ChatService(SdkServiceBase):
                 f"耗时 {time.perf_counter() - start:.1f}秒{note}"
             )
 
-    def _warn_if_empty(self, stats: StreamStats, max_tokens: object) -> None:
+    def _warn_if_empty(self, stats: StreamStats, max_tokens: int | None) -> None:
         """正文为空时按诊断分级告警（不再一律归因为「预算被思考耗尽」）。"""
         kind = stats.empty_kind
         if kind is None:
@@ -590,7 +603,7 @@ class ChatService(SdkServiceBase):
         self,
         *,
         kind: str,
-        max_tokens: object,
+        max_tokens: int | None,
         finish: str | None,
         reasoning_chars: int,
     ) -> None:

{sdpy_kit-0.7.1 → sdpy_kit-0.7.2}/kit/ai/profiles.py

@@ -536,6 +536,15 @@ def with_api_key(profile: ModelProfile, api_key: str) -> ModelProfile:
     return replace(profile, api_key=api_key)
 
 
+def resolve_max_tokens(profile: ModelProfile, max_tokens: int | None) -> int | None:
+    """解析本次实际下发的输出上限：调用方 → 档案 → ``None``（provider 默认）。
+
+    单一数据源：``ChatService``（写入 ``StreamStats`` 与日志）与
+    ``SdkClient._chat_params``（构造请求体）共用，避免两处回落逻辑漂移。
+    """
+    return max_tokens if max_tokens is not None else profile.max_tokens
+
+
 @lru_cache(maxsize=1)
 def get_model_registry() -> ModelRegistry:
     """获取全局单例 ModelRegistry（首次调用自动 load 默认档案文件）。"""

{sdpy_kit-0.7.1 → sdpy_kit-0.7.2}/kit/ai/sdk_client.py

@@ -54,7 +54,7 @@ from kit.ai.exceptions import (
     AIResponseError,
     AITimeoutError,
 )
-from kit.ai.profiles import ModelProfile
+from kit.ai.profiles import ModelProfile, resolve_max_tokens
 from kit.ai.types import JSONObject
 from kit.config.log_config import get_default_logger
 
@@ -193,9 +193,7 @@ class SdkClient:
         }
         if temperature is not None:
             params["temperature"] = temperature
-        effective_max_tokens = (
-            max_tokens if max_tokens is not None else self._profile.max_tokens
-        )
+        effective_max_tokens = resolve_max_tokens(self._profile, max_tokens)
         if effective_max_tokens is not None:
             params["max_tokens"] = effective_max_tokens
         if response_format is not None: