sdpy-kit 0.6.4__tar.gz → 0.6.5__tar.gz

{sdpy_kit-0.6.4 → sdpy_kit-0.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.4
+Version: 0.6.5
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -785,7 +785,7 @@ shutdown()                                                     # 应用退出前
 |------|------|------|
 | chat | `chat_complete(prompt, *, max_tokens=None) -> str` | 单轮对话（仅 user 消息） |
 | chat | `chat_ask(messages, *, max_tokens=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
-| chat | `chat_stream(messages, *, max_tokens=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用） |
+| chat | `chat_stream(messages, *, max_tokens=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
 | rerank | `rerank(query, documents, top_n=None) -> list[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
@@ -802,6 +802,32 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
         print(token, end="", flush=True)
 ```
 
+#### 流式收尾统计（思考型模型必备）
+
+迭代器在流结束后可读四个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
+`truncated`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
+token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」：
+
+```python
+with AI.chat_stream(messages, max_tokens=450) as stream:
+    body = "".join(stream)
+if not body and stream.truncated and stream.reasoning_chars:
+    raise ValueError(
+        f"输出预算被思考消耗（推理 {stream.reasoning_chars} 字符），"
+        "请调大 max_tokens 或改用关闭思考的档案"
+    )
+```
+
+- 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
+- 正文为空且（被截断或发生过思考）时 kit 自行打 `WARNING`，含模型与 `max_tokens`；
+- `truncated` 覆盖 `finish_reason` 为 `length` 或 `max_tokens` 两种口径；
+- **字符数 ≠ token 数**（实测中文约 2~2.5 字符/token，各家口径不一），不要用 `reasoning_chars` 反推还差多少预算；
+- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；
+- 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
+
+> 首帧等待语义：每候选 60 秒内**一帧都没有**（含推理帧）才切下一候选；思考阶段的
+> 推理帧算活动并重置窗口，不会误判健康模型失败、也不会重放整段 prompt。
+
 > 门面仅面向**同步上下文**；若调用点本身在 async 函数内，请直接 `await` 原生异步服务，避免阻塞事件循环线程。
 > 模块级另有 `kit.ai.runner.reload_config(...)`、`run_sync(coro_factory, *, timeout=120.0)`、`shutdown()`。
 
@@ -811,7 +837,7 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 from kit.ai import (
     ChatService, EmbeddingService, RerankService, ImageService,   # 服务类
     ChatRequest, EmbeddingRequest, RerankRequest, ImageRequest,   # 请求模型
-    RerankHit, ModelBuilder,                                      # 结果类型 / 构建器
+    RerankHit, StreamStats, ModelBuilder,                         # 结果类型 / 构建器
 )
 
 service = ModelBuilder.build_chat()                 # 老按类型构建：build_chat / build_embedding / build_rerank / build_image
@@ -821,7 +847,7 @@ await service.close()
 
 | 类 | 方法 |
 |----|------|
-| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ...) -> AsyncIterator[str]` |
+| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats | None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计） |
 | `EmbeddingService` | `embed_text(text) -> list[float]`、`embed_texts(texts, *, batch_size=None, concurrency=4) -> list[list[float]]`、`dimension` 属性（**目标维度**，见下） |
 | `RerankService` | `rerank(query, documents, *, top_n=None) -> list[RerankHit]`（已按 score 降序） |
 | `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> str` |
@@ -1354,6 +1380,7 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 | 档案级 | `timeout` | 请求超时秒数（默认 60） |
 | 档案级 | `max_tokens` | 输出上限（chat 用）；`AI.chat_ask/chat_complete/chat_stream` 也可按调用点传参，逐级回落：调用点 → 档案 → provider 默认 |
 | 档案级 | `retries` | 5xx 重试次数（默认 2；超时不重试，候选链切换才是有效重试） |
+| 档案级 | `extra_body` | 厂商专有请求体字段透传（如 GLM/Qwen 关闭思考的 `{"thinking": {"type": "disabled"}}`、`{"reasoning_effort": "low"}`）；与服务构造的同名键冲突时**以服务的值为准**，故 `model` / `messages` / `stream` 等保留键不可覆盖；改名类需求（如 OpenAI o 系列的 `max_completion_tokens`）无法用它实现。改文件后需 `reload_config(reload_file=True)` 生效 |
 | 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
 
 ### 候选链切换语义（两类，勿混淆）

{sdpy_kit-0.6.4 → sdpy_kit-0.6.5}/README.md

@@ -709,7 +709,7 @@ shutdown()                                                     # 应用退出前
 |------|------|------|
 | chat | `chat_complete(prompt, *, max_tokens=None) -> str` | 单轮对话（仅 user 消息） |
 | chat | `chat_ask(messages, *, max_tokens=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
-| chat | `chat_stream(messages, *, max_tokens=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用） |
+| chat | `chat_stream(messages, *, max_tokens=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
 | rerank | `rerank(query, documents, top_n=None) -> list[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
@@ -726,6 +726,32 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
         print(token, end="", flush=True)
 ```
 
+#### 流式收尾统计（思考型模型必备）
+
+迭代器在流结束后可读四个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
+`truncated`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
+token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」：
+
+```python
+with AI.chat_stream(messages, max_tokens=450) as stream:
+    body = "".join(stream)
+if not body and stream.truncated and stream.reasoning_chars:
+    raise ValueError(
+        f"输出预算被思考消耗（推理 {stream.reasoning_chars} 字符），"
+        "请调大 max_tokens 或改用关闭思考的档案"
+    )
+```
+
+- 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
+- 正文为空且（被截断或发生过思考）时 kit 自行打 `WARNING`，含模型与 `max_tokens`；
+- `truncated` 覆盖 `finish_reason` 为 `length` 或 `max_tokens` 两种口径；
+- **字符数 ≠ token 数**（实测中文约 2~2.5 字符/token，各家口径不一），不要用 `reasoning_chars` 反推还差多少预算；
+- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；
+- 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
+
+> 首帧等待语义：每候选 60 秒内**一帧都没有**（含推理帧）才切下一候选；思考阶段的
+> 推理帧算活动并重置窗口，不会误判健康模型失败、也不会重放整段 prompt。
+
 > 门面仅面向**同步上下文**；若调用点本身在 async 函数内，请直接 `await` 原生异步服务，避免阻塞事件循环线程。
 > 模块级另有 `kit.ai.runner.reload_config(...)`、`run_sync(coro_factory, *, timeout=120.0)`、`shutdown()`。
 
@@ -735,7 +761,7 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 from kit.ai import (
     ChatService, EmbeddingService, RerankService, ImageService,   # 服务类
     ChatRequest, EmbeddingRequest, RerankRequest, ImageRequest,   # 请求模型
-    RerankHit, ModelBuilder,                                      # 结果类型 / 构建器
+    RerankHit, StreamStats, ModelBuilder,                         # 结果类型 / 构建器
 )
 
 service = ModelBuilder.build_chat()                 # 老按类型构建：build_chat / build_embedding / build_rerank / build_image
@@ -745,7 +771,7 @@ await service.close()
 
 | 类 | 方法 |
 |----|------|
-| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ...) -> AsyncIterator[str]` |
+| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats | None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计） |
 | `EmbeddingService` | `embed_text(text) -> list[float]`、`embed_texts(texts, *, batch_size=None, concurrency=4) -> list[list[float]]`、`dimension` 属性（**目标维度**，见下） |
 | `RerankService` | `rerank(query, documents, *, top_n=None) -> list[RerankHit]`（已按 score 降序） |
 | `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> str` |
@@ -1278,6 +1304,7 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 | 档案级 | `timeout` | 请求超时秒数（默认 60） |
 | 档案级 | `max_tokens` | 输出上限（chat 用）；`AI.chat_ask/chat_complete/chat_stream` 也可按调用点传参，逐级回落：调用点 → 档案 → provider 默认 |
 | 档案级 | `retries` | 5xx 重试次数（默认 2；超时不重试，候选链切换才是有效重试） |
+| 档案级 | `extra_body` | 厂商专有请求体字段透传（如 GLM/Qwen 关闭思考的 `{"thinking": {"type": "disabled"}}`、`{"reasoning_effort": "low"}`）；与服务构造的同名键冲突时**以服务的值为准**，故 `model` / `messages` / `stream` 等保留键不可覆盖；改名类需求（如 OpenAI o 系列的 `max_completion_tokens`）无法用它实现。改文件后需 `reload_config(reload_file=True)` 生效 |
 | 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
 
 ### 候选链切换语义（两类，勿混淆）

{sdpy_kit-0.6.4 → sdpy_kit-0.6.5}/kit/__init__.py

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

{sdpy_kit-0.6.4 → sdpy_kit-0.6.5}/kit/ai/__init__.py

@@ -27,7 +27,7 @@ Author: Clark Chang
 - ImageService: 文生图
 """
 
-from kit.ai.chat_service import ChatRequest, ChatService
+from kit.ai.chat_service import ChatRequest, ChatService, StreamStats
 from kit.ai.embedding_service import EmbeddingRequest, EmbeddingService
 from kit.ai.image_service import ImageRequest, ImageService
 from kit.ai.model_builder import ModelBuilder
@@ -44,4 +44,5 @@ __all__ = [
     "RerankHit",
     "RerankRequest",
     "RerankService",
+    "StreamStats",
 ]

{sdpy_kit-0.6.4 → sdpy_kit-0.6.5}/kit/ai/base_service.py

@@ -20,7 +20,7 @@ Author: Clark Chang
 import json
 import time
 from abc import ABC, abstractmethod
-from typing import ClassVar, Final, Self, override
+from typing import ClassVar, Final, Self, cast, override
 
 from kit.ai.exceptions import AIError, AIResponseError
 from kit.ai.model_client import ModelClient
@@ -109,6 +109,19 @@ class BaseAIService[RequestT, ResponseT](ABC):
     def _build_payload(self, request: RequestT) -> JSONObject:
         """将请求模型构造为 JSON 请求体。"""
 
+    def _apply_extra_body(self, payload: JSONObject) -> JSONObject:
+        """合并档案级 ``extra_body``（厂商专有请求字段透传）。
+
+        同名键以服务构造的值为准——``model`` / ``messages`` / ``stream`` /
+        ``input`` / ``prompt`` 等保留键**不可被档案覆盖**，故无需白名单；
+        未配置时原样返回（请求体逐字节不变）。
+        """
+        extra = self._profile.extra_body
+        if not extra:
+            return payload
+        merged: dict[str, object] = {**extra, **payload}
+        return cast(JSONObject, merged)
+
     @abstractmethod
     def _parse_response(self, data: JSONObject) -> ResponseT:
         """将 JSON 响应体解析为业务结果。"""
@@ -124,7 +137,7 @@ class BaseAIService[RequestT, ResponseT](ABC):
                 ``post_json`` 的重试预算检查；None 表示不限制
         """
         desc = self._log_desc()
-        payload = self._build_payload(request)
+        payload = self._apply_extra_body(self._build_payload(request))
         params = _truncate(
             json.dumps(_clip(payload), ensure_ascii=False), _LOG_PAYLOAD_LIMIT
         )

sdpy_kit-0.6.5/kit/ai/chat_service.py

@@ -0,0 +1,266 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+import json
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import ClassVar, Final, cast, override
+
+from kit.ai.base_service import (
+    _LOG_PAYLOAD_LIMIT,
+    BaseAIService,
+    _clip,
+    _truncate,
+    safe_get,
+)
+from kit.ai.exceptions import AIError, AIResponseError
+from kit.ai.types import JSONObject
+from kit.config.log_config import get_default_logger
+
+__all__ = ["ChatRequest", "ChatService", "StreamStats"]
+
+logger = get_default_logger(__name__)
+
+Message = dict[str, str]
+
+# 推理（思考）内容可能的字段名：GLM / DeepSeek / Qwen 用 reasoning_content，
+# sensenova 用 reasoning（流式为 delta.*，非流式为 message.*）
+_REASONING_KEYS: Final[tuple[str, ...]] = ("reasoning_content", "reasoning")
+
+# 截断判定：OpenAI 系给 length，部分兼容端点给 max_tokens
+_TRUNCATED_REASONS: Final[frozenset[str]] = frozenset({"length", "max_tokens"})
+
+
+@dataclass
+class StreamStats:
+    """对话收尾统计（可变累加器：调用方传入，kit 累加）。
+
+    跨线程共享（后台事件循环写、业务线程读）：**流结束后为最终值**，
+    流式过程中读到的是尽力而为的中间值。
+
+    ``reasoning_chars`` / ``content_chars`` 均为**字符数**，与 ``max_tokens``
+    （token）不可换算（实测中文约 2~2.5 字符/token，且各 provider 口径不一），
+    仅用于「是否发生思考 / 是否被长度截断」的判定。
+
+    Attributes:
+        reasoning_chars: 推理（思考）内容字符数；非思考模型恒为 0
+        content_chars: 已产出正文字符数（等于调用方收到的字符数）
+        finish_reason: 结束原因（stop / length / content_filter / …）；
+            provider 未给出时为 None
+    """
+
+    reasoning_chars: int = 0
+    content_chars: int = 0
+    finish_reason: str | None = None
+
+    @property
+    def truncated(self) -> bool:
+        """是否因输出长度上限被截断。"""
+        return self.finish_reason in _TRUNCATED_REASONS
+
+    def reset(self) -> None:
+        """清零（候选链切换到下一个档案前调用）。"""
+        self.reasoning_chars = 0
+        self.content_chars = 0
+        self.finish_reason = None
+
+
+@dataclass(frozen=True)
+class ChatRequest:
+    """对话请求模型。"""
+
+    messages: list[Message]
+    temperature: float | None = None
+    max_tokens: int | None = None
+    stream: bool = False
+
+
+class ChatService(BaseAIService[ChatRequest, str]):
+    """对话类模型服务（全异步）。"""
+
+    _LABEL: ClassVar[str] = "对话模型"
+
+    @override
+    def _build_payload(self, request: ChatRequest) -> JSONObject:
+        payload: dict[str, object] = {
+            "model": self._profile.model,
+            "messages": request.messages,
+            "stream": request.stream,
+        }
+        if request.temperature is not None:
+            payload["temperature"] = request.temperature
+        # max_tokens 逐级回落：调用点显式传入 → 档案配置 → 不写（provider 默认）
+        max_tokens = (
+            request.max_tokens
+            if request.max_tokens is not None
+            else self._profile.max_tokens
+        )
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
+        return cast(JSONObject, payload)
+
+    @override
+    def _parse_response(self, data: JSONObject) -> str:
+        choice = safe_get(data, "choices", 0)
+        if not isinstance(choice, dict):
+            raise AIResponseError(f"choices[0] 类型异常: {type(choice).__name__}")
+        message = choice.get("message")
+        content = message.get("content") if isinstance(message, dict) else None
+        finish = choice.get("finish_reason")
+        reasoning = 0
+        if isinstance(message, dict):
+            for key in _REASONING_KEYS:
+                part = message.get(key)
+                if isinstance(part, str) and part:
+                    reasoning = len(part)
+                    break
+        if not isinstance(content, str):
+            if finish in _TRUNCATED_REASONS and reasoning:
+                # 思考型模型截断时可能完全不返回 content 键（实测 sensenova）
+                raise AIResponseError(
+                    f"输出预算被思考耗尽：finish_reason={finish}，"
+                    f"推理 {reasoning} 字符、正文为空"
+                    "（请调大 max_tokens 或在档案 extra_body 中关闭思考）"
+                )
+            raise AIResponseError(f"content 类型异常: {type(content).__name__}")
+        if finish in _TRUNCATED_REASONS and (reasoning or not content):
+            logger.warning(
+                f"{self._log_desc()} 输出被长度截断（finish_reason={finish}）："
+                f"推理 {reasoning} 字符 / 正文 {len(content)} 字符"
+                "（可调大 max_tokens 或在档案 extra_body 中关闭思考）"
+            )
+        return content
+
+    async def ask(
+        self,
+        messages: list[Message],
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        deadline: float | None = None,
+    ) -> str:
+        """多轮对话，返回模型回答文本。
+
+        Args:
+            deadline: 整链预算截止时刻（``time.monotonic()`` 秒），约束
+                5xx 重试预算；None 表示不限制
+        """
+        request = ChatRequest(messages, temperature=temperature, max_tokens=max_tokens)
+        return await self._call(request, deadline=deadline)
+
+    async def complete(
+        self,
+        prompt: str,
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        deadline: float | None = None,
+    ) -> str:
+        messages: list[Message] = [{"role": "user", "content": prompt}]
+        return await self.ask(
+            messages, temperature=temperature, max_tokens=max_tokens, deadline=deadline
+        )
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        stats: StreamStats | None = None,
+    ) -> AsyncIterator[str]:
+        """流式对话，逐 token 产出正文。
+
+        Args:
+            stats: 收尾统计累加器（可选）；None 时内部创建后丢弃——需要
+                ``reasoning_chars`` / ``finish_reason`` / ``truncated`` 时
+                由调用方传入一个实例
+
+        推理内容（``delta.reasoning_content`` / ``delta.reasoning``）只计数
+        不产出；正文为空且被截断（或发生过思考）时输出 warning。
+        """
+        request = ChatRequest(
+            messages, temperature=temperature, max_tokens=max_tokens, stream=True
+        )
+        payload = self._apply_extra_body(self._build_payload(request))
+        desc = self._log_desc()
+        params = _truncate(
+            json.dumps(_clip(payload), ensure_ascii=False), _LOG_PAYLOAD_LIMIT
+        )
+        stats = stats if stats is not None else StreamStats()
+        # 惰性 Start：异步生成器体在首次 __anext__ 前不执行，不消费不打日志
+        logger.info(f"********** {desc} ********** Start")
+        logger.info(f"请求参数: {params}")
+        start = time.perf_counter()
+        note = ""
+        failed = False
+        try:
+            async for parsed in self._client.stream_json(payload):
+                if parsed is None:
+                    continue
+                choices = parsed.get("choices")
+                if not isinstance(choices, list) or not choices:
+                    continue
+                choice = choices[0]
+                if not isinstance(choice, dict):
+                    continue
+                finish = choice.get("finish_reason")
+                if isinstance(finish, str) and finish:
+                    stats.finish_reason = finish
+                delta = choice.get("delta")
+                if not isinstance(delta, dict):
+                    continue
+                for key in _REASONING_KEYS:
+                    part = delta.get(key)
+                    if isinstance(part, str) and part:
+                        stats.reasoning_chars += len(part)
+                        break
+                content = delta.get("content")
+                if isinstance(content, str) and content:
+                    stats.content_chars += len(content)
+                    yield content
+        except AIError as exc:
+            note = f"（失败：{exc}）"
+            failed = True
+            raise
+        except BaseException:  # noqa: BLE001 - 中断路径（提前 break/取消）也需收尾日志
+            note = "（中断）"
+            raise
+        else:
+            self._warn_if_budget_eaten(stats, payload.get("max_tokens"))
+        finally:
+            log = logger.error if failed else logger.info
+            log(
+                f"********** {desc} ********** "
+                f"耗时 {time.perf_counter() - start:.1f}秒{note}"
+            )
+
+    def _warn_if_budget_eaten(
+        self, stats: StreamStats, max_tokens: object
+    ) -> None:
+        """正文为空且（被截断或有推理）时告警：讲清「预算被思考吃掉」。"""
+        if stats.content_chars or not (stats.truncated or stats.reasoning_chars):
+            return
+        logger.warning(
+            f"{self._log_desc()} 输出预算疑被思考耗尽：max_tokens={max_tokens}，"
+            f"finish_reason={stats.finish_reason}，"
+            f"推理 {stats.reasoning_chars} 字符 / 正文 0 字符"
+            "（可调大 max_tokens 或在档案 extra_body 中关闭思考）"
+        )

{sdpy_kit-0.6.4 → sdpy_kit-0.6.5}/kit/ai/failover.py

@@ -35,9 +35,9 @@ Author: Clark Chang
 import asyncio
 import time
 from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable
-from typing import TypeVar, cast
+from typing import Final, TypeVar, cast
 
-from kit.ai.chat_service import ChatService
+from kit.ai.chat_service import ChatService, StreamStats
 from kit.ai.embedding_service import EmbeddingService
 from kit.ai.exceptions import AIAggregateError, AIError, AIRequestError, AITimeoutError
 from kit.ai.image_service import ImageService
@@ -57,6 +57,10 @@ T = TypeVar("T")
 # 批量向量化默认并发（与 EmbeddingService 保持一致）
 _EMBED_CONCURRENCY = 4
 
+# 流式首帧等待的轮询粒度（秒）：只用于「有无任何帧」的续期判定，
+# 不改变超时时长语义（推理帧被吞掉，不轮询就看不到思考阶段的活动）
+_FIRST_FRAME_POLL: Final[float] = 1.0
+
 
 class _FailoverBase:
     """链式调用基类：候选迭代 + 失败冷却 + 整链预算 + 聚合异常。"""
@@ -202,48 +206,44 @@ class FailoverChatService(_FailoverBase):
         max_tokens: int | None = None,
         first_frame_timeout: float | None = None,
         deadline: float | None = None,
+        stats: StreamStats | None = None,
     ) -> AsyncIterator[str]:
         """流式对话：首帧前失败自动换档案重试；首帧后失败直接抛出。
 
         Args:
-            first_frame_timeout: 单候选首帧等待上限（秒）；超时按失败处理
-                切下一候选（补齐「首帧前允许切换」的时间兜底）；None 不限制
+            first_frame_timeout: 单候选首帧等待上限（秒）；窗口内**一帧都没有**
+                （含推理帧）才按失败处理切下一候选；None 不限制
             deadline: 整链预算截止时刻；每个候选发起前检查
+            stats: 收尾统计累加器；候选切换前清零，故只反映最终成功的候选
         """
         tried: list[str] = []
         errors: list[AIError] = []
         budget_exhausted = False
+        stats = stats if stats is not None else StreamStats()
         for name, service in self._pool.iter_services(self._model_type):
             if self._budget_exhausted(deadline):
                 budget_exhausted = True
                 break
             tried.append(name)
+            stats.reset()
             agen = cast(
                 AsyncGenerator[str, None],
                 cast(ChatService, service).stream(
-                    messages, temperature=temperature, max_tokens=max_tokens
+                    messages,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    stats=stats,
                 ),
             )
             try:
                 try:
-                    if first_frame_timeout is not None:
-                        first = await asyncio.wait_for(
-                            agen.__anext__(), timeout=first_frame_timeout
-                        )
-                    else:
-                        first = await agen.__anext__()
+                    first = await self._await_first_frame(
+                        agen, stats, first_frame_timeout
+                    )
                 except StopAsyncIteration:
                     # 空流（首帧即结束）视为正常完成
                     await agen.aclose()
                     return
-                except asyncio.TimeoutError:
-                    timeout_exc = AITimeoutError(
-                        f"流式首帧超过 {first_frame_timeout:g}s 未到达"
-                    )
-                    errors.append(timeout_exc)
-                    self._pool.mark_failure(self._model_type, name, timeout_exc)
-                    await agen.aclose()
-                    continue
                 except AIError as exc:
                     errors.append(exc)
                     self._pool.mark_failure(
@@ -270,6 +270,53 @@ class FailoverChatService(_FailoverBase):
             "流式对话", tried, errors, budget_exhausted=budget_exhausted
         )
 
+    async def _await_first_frame(
+        self,
+        agen: AsyncGenerator[str, None],
+        stats: StreamStats,
+        timeout: float | None,
+    ) -> str:
+        """等首个正文帧；期间任何帧（含推理帧）都算活动并重置窗口。
+
+        ``ChatService.stream`` 只产出正文、推理帧仅计数，故「首个 yield 到达」
+        会把整个思考阶段表现为静默——按窗口计时会误判健康的思考型模型失败
+        （并重放整段 prompt）。改为按 ``stats.reasoning_chars`` 的推进续期。
+
+        Raises:
+            AITimeoutError: 窗口内一帧都没有
+            StopAsyncIteration: 空流（首帧即结束）
+        """
+        if timeout is None:
+            return await agen.__anext__()
+        task = asyncio.ensure_future(agen.__anext__())
+        waited = 0.0
+        seen = stats.reasoning_chars
+        try:
+            while True:
+                remaining = timeout - waited
+                if remaining <= 0:
+                    raise AITimeoutError(f"流式首帧超过 {timeout:g}s 未到达")
+                step = min(_FIRST_FRAME_POLL, remaining)
+                done, _ = await asyncio.wait({task}, timeout=step)
+                if task in done:
+                    return task.result()
+                if stats.reasoning_chars != seen:
+                    # 推理帧在推进：思考阶段属于正常活动，窗口续期
+                    seen = stats.reasoning_chars
+                    waited = 0.0
+                    continue
+                waited += step
+        except BaseException:
+            if not task.done():
+                task.cancel()
+                # 等 __anext__ 真正退栈，否则调用方随后 aclose() 会撞
+                # 「asynchronous generator is already running」
+                try:
+                    await task
+                except BaseException:  # noqa: BLE001 - 取消后的收尾无需上抛
+                    pass
+            raise
+
 
 class FailoverEmbeddingService(_FailoverBase):
     """向量化服务链式调用（embed_text / embed_texts）。"""

{sdpy_kit-0.6.4 → sdpy_kit-0.6.5}/kit/ai/profiles.py

@@ -34,7 +34,7 @@ import os
 from dataclasses import dataclass, replace
 from functools import lru_cache
 from pathlib import Path
-from typing import Final
+from typing import Any, Final
 
 from dotenv import load_dotenv
 from pydantic import BaseModel, Field, ValidationError
@@ -75,6 +75,9 @@ class ModelProfile:
             保证输出恒等于该值：模型原生维度更大时截断（含 L2 归一化），
             更小时报错；建表与维度守卫均应以它为唯一来源
         batch_size: 单次请求最大文本数（仅 embedding 有效）
+        extra_body: 档案级额外请求体字段（厂商专有参数透传，如 GLM/Qwen 的
+            ``{"thinking": {"type": "disabled"}}``）；与服务构造的同名键
+            冲突时**以服务的值为准**（不可覆盖 model / messages / stream 等保留键）
     """
 
     name: str
@@ -89,6 +92,7 @@ class ModelProfile:
     retries: int = 2
     dimension: int | None = None
     batch_size: int = 32
+    extra_body: dict[str, Any] | None = None
 
     @property
     def url(self) -> str:
@@ -144,6 +148,9 @@ class ProfileConfig(BaseModel):
     retries: int = Field(default=2, ge=0)
     dimension: int | None = Field(default=None, gt=0)
     batch_size: int = Field(default=32, gt=0)
+    # 厂商专有请求字段透传（如 {"thinking": {"type": "disabled"}}）；
+    # 与服务构造的同名键冲突时以服务的值为准，故保留键无法被覆盖
+    extra_body: dict[str, Any] | None = None
 
 
 class TypeConfig(BaseModel):
@@ -277,6 +284,7 @@ class ModelRegistry:
             retries=config.retries,
             dimension=config.dimension,
             batch_size=config.batch_size,
+            extra_body=config.extra_body,
         )
 
     def get_profile(self, model_type: str, profile: str | None = None) -> ProfileConfig:

{sdpy_kit-0.6.4 → sdpy_kit-0.6.5}/kit/ai/runner.py

@@ -70,6 +70,7 @@ from collections.abc import Callable, Coroutine, Iterable, Iterator
 from dataclasses import dataclass
 from typing import Any, Final, TypeVar, cast
 
+from kit.ai.chat_service import StreamStats
 from kit.ai.exceptions import AIConfigError, AITimeoutError
 from kit.ai.failover import (
     FailoverChatService,
@@ -318,9 +319,13 @@ class _BackgroundLoop:
         q: queue.Queue[object],
         *,
         max_tokens: int | None = None,
+        stats: StreamStats,
     ) -> concurrent.futures.Future[None]:
         """投递流式收集任务：后台拉取链式 ``stream`` 帧写入线程安全队列。
 
+        Args:
+            stats: 收尾统计累加器（由同步侧持有并读取）
+
         返回的 future 可取消，用于同步侧中断时停止后台拉取。
         """
         loop = self._ensure_started()
@@ -334,6 +339,7 @@ class _BackgroundLoop:
                     messages,
                     max_tokens=max_tokens,
                     first_frame_timeout=_STREAM_FIRST_FRAME_TIMEOUT,
+                    stats=stats,
                 ):
                     q.put(delta)
             except BaseException as exc:  # noqa: BLE001 - 异常经队列回传给同步侧
@@ -666,8 +672,9 @@ class AI:
 
         在同步线程内逐帧消费，适合流式输出；内部在后台 loop 持续拉取
         并放入线程安全队列。超时保护：
-            - 首帧前：每候选 ``_STREAM_FIRST_FRAME_TIMEOUT``（60s）内未出
-              首帧则切下一候选，全部候选耗尽抛 ``AITimeoutError``；
+            - 首帧前：每候选 ``_STREAM_FIRST_FRAME_TIMEOUT``（60s）内**一帧
+              都没有**（含推理帧）则切下一候选，全部候选耗尽抛
+              ``AITimeoutError``；思考型模型的推理帧算活动、会重置窗口；
             - 首帧后：帧间隔超过 ``_STREAM_FRAME_INTERVAL_TIMEOUT``（120s）
               未收到新帧则中断并抛 ``AITimeoutError``（已产出 token 不可回滚）。
 
@@ -678,6 +685,14 @@ class AI:
                     yield token
                     if done:
                         break
+
+        流结束后可读 ``reasoning_chars`` / ``content_chars`` / ``finish_reason`` /
+        ``truncated``，用于区分「模型没返回内容」与「输出预算被思考吃光」::
+
+            with AI.chat_stream(messages, max_tokens=450) as stream:
+                body = "".join(stream)
+            if not body and stream.truncated and stream.reasoning_chars:
+                ...  # 推理吃光预算：调大 max_tokens 或关闭思考
         """
         return _StreamIterator(messages, max_tokens=max_tokens)
 
@@ -693,6 +708,10 @@ class _StreamIterator:
     支持 ``with`` 上下文（推荐）：退出时主动取消后台任务；即便调用方
     直接 ``for`` 中途 ``break`` 或迭代器被 GC，``close``/``__del__`` 也会
     兜底取消后台 producer，避免任务残留。
+
+    流结束后可读 ``reasoning_chars`` / ``content_chars`` / ``finish_reason`` /
+    ``truncated`` 四个只读属性（跨线程共享同一累加器：结束后为最终值，
+    流式过程中为尽力而为的中间值；提前 ``break`` 时为截至中断的累计值）。
     """
 
     def __init__(
@@ -701,6 +720,7 @@ class _StreamIterator:
         self._messages: list[dict[str, str]] = messages
         self._max_tokens: int | None = max_tokens
         self._q: queue.Queue[object] = queue.Queue()
+        self._stats: StreamStats = StreamStats()
         self._started = False
         self._closed = False
         self._got_first = False
@@ -713,7 +733,10 @@ class _StreamIterator:
         if not self._started:
             self._started = True
             self._task = _background.submit_stream(
-                self._messages, self._q, max_tokens=self._max_tokens
+                self._messages,
+                self._q,
+                max_tokens=self._max_tokens,
+                stats=self._stats,
             )
 
     def _cancel_task(self) -> None:
@@ -766,6 +789,28 @@ class _StreamIterator:
         self._got_first = True
         return str(item)
 
+    # ---------- 收尾统计（只读） ----------
+
+    @property
+    def reasoning_chars(self) -> int:
+        """推理（思考）内容字符数；非思考模型恒为 0。"""
+        return self._stats.reasoning_chars
+
+    @property
+    def content_chars(self) -> int:
+        """已产出正文字符数（与本迭代器产出的字符数严格相等）。"""
+        return self._stats.content_chars
+
+    @property
+    def finish_reason(self) -> str | None:
+        """结束原因：``stop`` / ``length`` / ``content_filter`` / …；未给出为 None。"""
+        return self._stats.finish_reason
+
+    @property
+    def truncated(self) -> bool:
+        """是否因输出长度上限被截断（``finish_reason`` 为 length / max_tokens）。"""
+        return self._stats.truncated
+
 
 async def _delayed_close(services: list[Service]) -> None:
     """延迟回收旧 service：给在途调用留宽限期，到期统一关闭（须在 loop 内）。"""

sdpy_kit-0.6.4/kit/ai/chat_service.py

@@ -1,160 +0,0 @@
-"""
-Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
-Project: sdpy
-Author: Clark Chang
-"""
-
-import json
-import time
-from collections.abc import AsyncIterator
-from dataclasses import dataclass
-from typing import ClassVar, cast, override
-
-from kit.ai.base_service import (
-    _LOG_PAYLOAD_LIMIT,
-    BaseAIService,
-    _clip,
-    _truncate,
-    safe_get,
-)
-from kit.ai.exceptions import AIError, AIResponseError
-from kit.ai.types import JSONObject
-from kit.config.log_config import get_default_logger
-
-__all__ = ["ChatRequest", "ChatService"]
-
-logger = get_default_logger(__name__)
-
-Message = dict[str, str]
-
-
-@dataclass(frozen=True)
-class ChatRequest:
-    """对话请求模型。"""
-
-    messages: list[Message]
-    temperature: float | None = None
-    max_tokens: int | None = None
-    stream: bool = False
-
-
-class ChatService(BaseAIService[ChatRequest, str]):
-    """对话类模型服务（全异步）。"""
-
-    _LABEL: ClassVar[str] = "对话模型"
-
-    @override
-    def _build_payload(self, request: ChatRequest) -> JSONObject:
-        payload: dict[str, object] = {
-            "model": self._profile.model,
-            "messages": request.messages,
-            "stream": request.stream,
-        }
-        if request.temperature is not None:
-            payload["temperature"] = request.temperature
-        # max_tokens 逐级回落：调用点显式传入 → 档案配置 → 不写（provider 默认）
-        max_tokens = (
-            request.max_tokens
-            if request.max_tokens is not None
-            else self._profile.max_tokens
-        )
-        if max_tokens is not None:
-            payload["max_tokens"] = max_tokens
-        return cast(JSONObject, payload)
-
-    @override
-    def _parse_response(self, data: JSONObject) -> str:
-        content = safe_get(data, "choices", 0, "message", "content")
-        if not isinstance(content, str):
-            raise AIResponseError(f"content 类型异常: {type(content).__name__}")
-        return content
-
-    async def ask(
-        self,
-        messages: list[Message],
-        *,
-        temperature: float | None = None,
-        max_tokens: int | None = None,
-        deadline: float | None = None,
-    ) -> str:
-        """多轮对话，返回模型回答文本。
-
-        Args:
-            deadline: 整链预算截止时刻（``time.monotonic()`` 秒），约束
-                5xx 重试预算；None 表示不限制
-        """
-        request = ChatRequest(messages, temperature=temperature, max_tokens=max_tokens)
-        return await self._call(request, deadline=deadline)
-
-    async def complete(
-        self,
-        prompt: str,
-        *,
-        temperature: float | None = None,
-        max_tokens: int | None = None,
-        deadline: float | None = None,
-    ) -> str:
-        messages: list[Message] = [{"role": "user", "content": prompt}]
-        return await self.ask(
-            messages, temperature=temperature, max_tokens=max_tokens, deadline=deadline
-        )
-
-    async def stream(
-        self,
-        messages: list[Message],
-        *,
-        temperature: float | None = None,
-        max_tokens: int | None = None,
-    ) -> AsyncIterator[str]:
-        request = ChatRequest(
-            messages, temperature=temperature, max_tokens=max_tokens, stream=True
-        )
-        payload = self._build_payload(request)
-        desc = self._log_desc()
-        params = _truncate(
-            json.dumps(_clip(payload), ensure_ascii=False), _LOG_PAYLOAD_LIMIT
-        )
-        # 惰性 Start：异步生成器体在首次 __anext__ 前不执行，不消费不打日志
-        logger.info(f"********** {desc} ********** Start")
-        logger.info(f"请求参数: {params}")
-        start = time.perf_counter()
-        note = ""
-        failed = False
-        try:
-            async for parsed in self._client.stream_json(payload):
-                if parsed is None:
-                    continue
-                try:
-                    delta = safe_get(parsed, "choices", 0, "delta", "content")
-                except AIResponseError:
-                    # 流式结束帧等无 delta 的正常帧，跳过
-                    logger.debug("流式帧缺少 delta.content，跳过")
-                    continue
-                if isinstance(delta, str) and delta:
-                    yield delta
-        except AIError as exc:
-            note = f"（失败：{exc}）"
-            failed = True
-            raise
-        except BaseException:  # noqa: BLE001 - 中断路径（提前 break/取消）也需收尾日志
-            note = "（中断）"
-            raise
-        finally:
-            log = logger.error if failed else logger.info
-            log(
-                f"********** {desc} ********** "
-                f"耗时 {time.perf_counter() - start:.1f}秒{note}"
-            )