sdpy-kit 0.6.11__tar.gz → 0.7.0__tar.gz

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.11
+Version: 0.7.0
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -26,27 +26,6 @@ Provides-Extra: ai
 Requires-Dist: httpx>=0.28.1; extra == 'ai'
 Requires-Dist: openai<4,>=3.44; extra == 'ai'
 Requires-Dist: python-dotenv>=1.2.4; extra == 'ai'
-Provides-Extra: all
-Requires-Dist: decima-ai>=2.5.1; extra == 'all'
-Requires-Dist: docxtpl>=0.20.2; extra == 'all'
-Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
-Requires-Dist: httpx>=0.28.1; extra == 'all'
-Requires-Dist: huggingface-hub<2,>=1.5; extra == 'all'
-Requires-Dist: laya>=0.4.22; extra == 'all'
-Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
-Requires-Dist: numpy>=2.5.4; extra == 'all'
-Requires-Dist: onnxruntime>=1.18; extra == 'all'
-Requires-Dist: openai<4,>=3.44; extra == 'all'
-Requires-Dist: pikepdf>=10.17.0; extra == 'all'
-Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'all'
-Requires-Dist: psycopg2-binary>=2.9.13; extra == 'all'
-Requires-Dist: pymysql>=1.2.3; extra == 'all'
-Requires-Dist: python-dotenv>=1.2.4; extra == 'all'
-Requires-Dist: rc-docparser>=0.2.2; extra == 'all'
-Requires-Dist: redis>=8.1.0; extra == 'all'
-Requires-Dist: requests>=2.34.2; extra == 'all'
-Requires-Dist: sqliteai-vector>=1.2.0; extra == 'all'
-Requires-Dist: trafilatura>=2.3.1; extra == 'all'
 Provides-Extra: anydoc
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
 Requires-Dist: pikepdf>=10.17.0; extra == 'anydoc'
@@ -61,10 +40,9 @@ Requires-Dist: rc-docparser>=0.2.2; extra == 'docx-parse'
 Provides-Extra: laya
 Requires-Dist: huggingface-hub<2,>=1.5; extra == 'laya'
 Requires-Dist: laya>=0.4.22; extra == 'laya'
-Provides-Extra: marker
-Requires-Dist: marker-pdf>=2.0.0; extra == 'marker'
 Provides-Extra: md2doc
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'md2doc'
+Requires-Dist: pillow>=13.0.0; extra == 'md2doc'
 Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'md2doc'
 Provides-Extra: mineru
 Requires-Dist: requests>=2.34.2; extra == 'mineru'
@@ -72,6 +50,27 @@ Provides-Extra: mysql
 Requires-Dist: pymysql>=1.2.3; extra == 'mysql'
 Provides-Extra: pg
 Requires-Dist: psycopg2-binary>=2.9.13; extra == 'pg'
+Provides-Extra: recommended
+Requires-Dist: decima-ai>=2.5.1; extra == 'recommended'
+Requires-Dist: docxtpl>=0.20.2; extra == 'recommended'
+Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'recommended'
+Requires-Dist: httpx>=0.28.1; extra == 'recommended'
+Requires-Dist: huggingface-hub<2,>=1.5; extra == 'recommended'
+Requires-Dist: laya>=0.4.22; extra == 'recommended'
+Requires-Dist: markdown-it-py>=4.2.0; extra == 'recommended'
+Requires-Dist: numpy>=2.5.4; extra == 'recommended'
+Requires-Dist: onnxruntime>=1.18; extra == 'recommended'
+Requires-Dist: openai<4,>=3.44; extra == 'recommended'
+Requires-Dist: pikepdf>=10.17.0; extra == 'recommended'
+Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'recommended'
+Requires-Dist: psycopg2-binary>=2.9.13; extra == 'recommended'
+Requires-Dist: pymysql>=1.2.3; extra == 'recommended'
+Requires-Dist: python-dotenv>=1.2.4; extra == 'recommended'
+Requires-Dist: rc-docparser>=0.2.2; extra == 'recommended'
+Requires-Dist: redis>=8.1.0; extra == 'recommended'
+Requires-Dist: requests>=2.34.2; extra == 'recommended'
+Requires-Dist: sqliteai-vector>=1.2.0; extra == 'recommended'
+Requires-Dist: trafilatura>=2.3.1; extra == 'recommended'
 Provides-Extra: redis
 Requires-Dist: redis>=8.1.0; extra == 'redis'
 Provides-Extra: sqliteai
@@ -107,7 +106,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
 | `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML（含图片） | `md2doc` |
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
-| `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
+| `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images）；**0.7.0 起暂停发布**，需要请用 `sdpy-kit==0.6.10` | — |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / multi_choice 多选 / score / noul，另含 decide 多字段 / decide_batch 批量 / predict_long 长文本 | `laya` |
 | `kit.decima_kit` | `DecimaKit` | 决策模型：choice / score / noul / multi_choice（原生 rank）；选项乱序不变、置信度可门控；另含 predict / predict_long / brief / choice_batch（方法名与 `LayaKit` 对齐） | `decima` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（三个 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
@@ -138,11 +137,10 @@ uv add sdpy-kit
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
-| `marker` | MarkerKit 本地解析（marker-pdf → Markdown + Images；PDF + 图片，依赖体积大）。**与 `[ai]` 互斥**：marker-pdf 锁 `openai<3`，不能与 `openai>=3.44` 同环境安装 | `pip install "sdpy-kit[marker]"` |
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / multi_choice / score / noul；支持多字段 / 批量 / 长文本） | `pip install "sdpy-kit[laya]"` |
 | `decima` | DecimaKit 决策模型（decima-ai + onnxruntime，**无 torch**；选项乱序不变、置信度可门控；磁盘约 137 MB） | `pip install "sdpy-kit[decima]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
-| `all` | 常用能力集合，**不含 `marker`**（0.6.11 起，避免与 `[ai]` 的 openai 约束冲突）；需要 Marker 请单独装 `[marker]` | `pip install "sdpy-kit[all]"` |
+| `recommended` | 常用能力集合（DB / 缓存 / AI / 文档 / 抓取）；不含重依赖（laya / decima）与 Marker（0.7.0 起暂停发布） | `pip install "sdpy-kit[recommended]"` |
 
 ## 配置（.env）
 
@@ -840,8 +838,8 @@ shutdown()                                                     # 应用退出前
 | 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` / `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[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
-| image | `generate_image(prompt, *, size=None, n=1) -> str` | 文生图，返回图片 URL |
+| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表 |
+| image | `generate_image(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` | 文生图，返回 `ImageResult`（`url` / `b64` 至少一个非空） |
 | 管理 | `use(model_type, profile) -> None` | 切换该类型当前档案（`chat` / `embedding` / `rerank` / `image`） |
 | 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置与被剔除者） |
 | 管理 | `reload_config(*, model_type=None, reload_file=False, probe=True, immediate=False) -> ReloadResult` | 配置热重载，改密钥 / 档案后无需重启 |
@@ -965,7 +963,7 @@ if stats.truncated:          # finish_reason 为 length / max_tokens
 from kit.ai import (
     ChatService, EmbeddingService, RerankService, ImageService,   # 服务类
     ChatRequest, EmbeddingRequest, RerankRequest, ImageRequest,   # 请求模型
-    RerankHit, StreamStats, ModelBuilder,                         # 结果类型 / 构建器
+    RerankHit, ImageResult, StreamStats, ModelBuilder,            # 结果类型 / 构建器
 )
 
 service = ModelBuilder.build_chat()                 # 老按类型构建：build_chat / build_embedding / build_rerank / build_image
@@ -978,7 +976,7 @@ await service.close()
 | `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats: StreamStats \| None = None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats \| None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计）；`thinking` / `json_mode` / `response_format` 语义与门面一致 |
 | `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` |
+| `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` |
 | `ModelBuilder` | `build(model_type, model=None, *, api_key=None)` 及各类型专用 `build_chat / build_embedding / build_rerank / build_image` |
 | `BaseAIService` | `profile` 属性、`await close()`、支持 `async with` |
 
@@ -1278,7 +1276,11 @@ if r.state == "done":
 
 ## kit.docs.marker_kit —— 本地解析：PDF + 图片 → Markdown + Images
 
-安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大；不含 `[full]`）
+> ⚠ **0.7.0 起暂停发布**：`marker-pdf` 仍锁 `openai<3`，与 `ai` extra 冲突。本包**不包含**该模块，
+> 也不提供 `marker` extra。需要此能力请用 `pip install "sdpy-kit[marker]==0.6.10"`。
+> 以下接口说明仅作参考。
+
+0.6.10 的安装方式：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大）
 
 支持面：`.pdf`、`.png`、`.jpg`、`.jpeg`、`.webp`、`.gif`、`.bmp`。docx/pptx/xlsx/html/epub 不在支持面
 （marker 侧实现依赖 weasyprint/GTK），传入会抛 `ValueError`。

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/README.md

@@ -24,7 +24,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
 | `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML（含图片） | `md2doc` |
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
-| `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
+| `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images）；**0.7.0 起暂停发布**，需要请用 `sdpy-kit==0.6.10` | — |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / multi_choice 多选 / score / noul，另含 decide 多字段 / decide_batch 批量 / predict_long 长文本 | `laya` |
 | `kit.decima_kit` | `DecimaKit` | 决策模型：choice / score / noul / multi_choice（原生 rank）；选项乱序不变、置信度可门控；另含 predict / predict_long / brief / choice_batch（方法名与 `LayaKit` 对齐） | `decima` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（三个 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
@@ -55,11 +55,10 @@ uv add sdpy-kit
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
-| `marker` | MarkerKit 本地解析（marker-pdf → Markdown + Images；PDF + 图片，依赖体积大）。**与 `[ai]` 互斥**：marker-pdf 锁 `openai<3`，不能与 `openai>=3.44` 同环境安装 | `pip install "sdpy-kit[marker]"` |
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / multi_choice / score / noul；支持多字段 / 批量 / 长文本） | `pip install "sdpy-kit[laya]"` |
 | `decima` | DecimaKit 决策模型（decima-ai + onnxruntime，**无 torch**；选项乱序不变、置信度可门控；磁盘约 137 MB） | `pip install "sdpy-kit[decima]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
-| `all` | 常用能力集合，**不含 `marker`**（0.6.11 起，避免与 `[ai]` 的 openai 约束冲突）；需要 Marker 请单独装 `[marker]` | `pip install "sdpy-kit[all]"` |
+| `recommended` | 常用能力集合（DB / 缓存 / AI / 文档 / 抓取）；不含重依赖（laya / decima）与 Marker（0.7.0 起暂停发布） | `pip install "sdpy-kit[recommended]"` |
 
 ## 配置（.env）
 
@@ -757,8 +756,8 @@ shutdown()                                                     # 应用退出前
 | 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` / `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[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
-| image | `generate_image(prompt, *, size=None, n=1) -> str` | 文生图，返回图片 URL |
+| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表 |
+| image | `generate_image(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` | 文生图，返回 `ImageResult`（`url` / `b64` 至少一个非空） |
 | 管理 | `use(model_type, profile) -> None` | 切换该类型当前档案（`chat` / `embedding` / `rerank` / `image`） |
 | 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置与被剔除者） |
 | 管理 | `reload_config(*, model_type=None, reload_file=False, probe=True, immediate=False) -> ReloadResult` | 配置热重载，改密钥 / 档案后无需重启 |
@@ -882,7 +881,7 @@ if stats.truncated:          # finish_reason 为 length / max_tokens
 from kit.ai import (
     ChatService, EmbeddingService, RerankService, ImageService,   # 服务类
     ChatRequest, EmbeddingRequest, RerankRequest, ImageRequest,   # 请求模型
-    RerankHit, StreamStats, ModelBuilder,                         # 结果类型 / 构建器
+    RerankHit, ImageResult, StreamStats, ModelBuilder,            # 结果类型 / 构建器
 )
 
 service = ModelBuilder.build_chat()                 # 老按类型构建：build_chat / build_embedding / build_rerank / build_image
@@ -895,7 +894,7 @@ await service.close()
 | `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats: StreamStats \| None = None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats \| None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计）；`thinking` / `json_mode` / `response_format` 语义与门面一致 |
 | `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` |
+| `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` |
 | `ModelBuilder` | `build(model_type, model=None, *, api_key=None)` 及各类型专用 `build_chat / build_embedding / build_rerank / build_image` |
 | `BaseAIService` | `profile` 属性、`await close()`、支持 `async with` |
 
@@ -1195,7 +1194,11 @@ if r.state == "done":
 
 ## kit.docs.marker_kit —— 本地解析：PDF + 图片 → Markdown + Images
 
-安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大；不含 `[full]`）
+> ⚠ **0.7.0 起暂停发布**：`marker-pdf` 仍锁 `openai<3`，与 `ai` extra 冲突。本包**不包含**该模块，
+> 也不提供 `marker` extra。需要此能力请用 `pip install "sdpy-kit[marker]==0.6.10"`。
+> 以下接口说明仅作参考。
+
+0.6.10 的安装方式：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大）
 
 支持面：`.pdf`、`.png`、`.jpg`、`.jpeg`、`.webp`、`.gif`、`.bmp`。docx/pptx/xlsx/html/epub 不在支持面
 （marker 侧实现依赖 weasyprint/GTK），传入会抛 `ValueError`。

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/__init__.py

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

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/ai/__init__.py

@@ -29,7 +29,7 @@ Author: Clark Chang
 
 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.image_service import ImageRequest, ImageResult, ImageService
 from kit.ai.model_builder import ModelBuilder
 from kit.ai.rerank_service import RerankHit, RerankRequest, RerankService
 
@@ -39,6 +39,7 @@ __all__ = [
     "EmbeddingRequest",
     "EmbeddingService",
     "ImageRequest",
+    "ImageResult",
     "ImageService",
     "ModelBuilder",
     "RerankHit",

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/ai/chat_service.py

@@ -55,37 +55,51 @@ _WARNED: set[tuple[str, str]] = set()
 _WARNED_LOCK: Final[threading.Lock] = threading.Lock()
 
 
-def _warn_once(profile_name: str, reason: str, *, kind: str = "思考开关") -> None:
-    """线程安全的告警去重：``(档案名, 原因)`` 只报一次。"""
+def _warn_once(
+    profile_name: str,
+    reason: str,
+    *,
+    kind: str = "思考开关",
+    level: int = logging.WARNING,
+) -> None:
+    """线程安全的告警去重：``(档案名, 原因)`` 只报一次（可指定级别）。"""
     key = (profile_name, reason)
     with _WARNED_LOCK:
         if key in _WARNED:
             return
         _WARNED.add(key)
-    logger.warning(f"{kind}：{reason}（档案 {profile_name}）")
+    logger.log(level, f"{kind}：{reason}（档案 {profile_name}）")
 
 
 def _resolve_thinking(
     profile: ModelProfile, thinking: bool | None
-) -> tuple[object, bool | None, str | None]:
+) -> tuple[object, bool | None, str | None, int]:
     """解析本次调用的思考开关。
 
     逐调用 ``thinking`` 优先，未传时回落档案 ``thinking.default``（三态）。
 
     Returns:
-        ``(注入值 | _UNSET, 是否生效, 告警原因)``。是否生效为 None 表示
-        本次未要求干预（请求体不变）；False 表示要求了但档案不支持
-        （不注入、不报错、不影响候选链冷却）。
+        ``(注入值 | _UNSET, 是否生效, 提示语, 日志级别)``。
+        是否生效为 None 表示本次未对请求体做思考相关注入（未要求，或档案
+        只声明了 ``off`` 而没声明 ``on``——按厂商默认处理）；False 表示
+        要求了但档案完全没有 ``thinking`` 声明（不支持、不注入、不报错、
+        不影响候选链冷却）。
     """
     spec = profile.thinking
     mode = thinking if thinking is not None else (spec.default if spec else None)
     if mode is None:
-        return _UNSET, None, None
+        return _UNSET, None, None, logging.WARNING
     if spec is None:
-        return _UNSET, False, "档案未声明思考开关，本次请求被忽略"
+        return _UNSET, False, "档案未声明思考开关，本次请求被忽略", logging.WARNING
     if mode and spec.on is None:
-        return _UNSET, False, "档案未声明开启取值，本次请求被忽略"
-    return (spec.off if mode is False else spec.on), True, None
+        # 只声明 off：开启只能走厂商默认（主流模型默认开启），不算「未生效」
+        return (
+            _UNSET,
+            None,
+            "档案未声明开启取值，按厂商默认处理",
+            logging.INFO,
+        )
+    return (spec.off if mode is False else spec.on), True, None, logging.WARNING
 
 
 @dataclass
@@ -106,8 +120,9 @@ class StreamStats:
         content_chars: 已产出正文字符数（等于调用方收到的字符数）
         finish_reason: 结束原因（stop / length / content_filter / …）；
             provider 未给出时为 None
-        thinking_applied: 思考开关是否生效——None 本次未要求干预 /
-            True 已按档案声明注入 / False 要求了但档案不支持（已忽略）
+        thinking_applied: 思考开关是否生效——None 本次未对请求体做思考注入
+            （未要求，或档案只声明 off 未声明 on，按厂商默认处理）/
+            True 已按档案声明注入 / False 要求了但档案完全没有 thinking 声明
         json_mode_applied: 结构化输出是否生效——None 本次未要求注入 /
             True 已注入 / False 要求了但档案声明不支持（已忽略）
     """
@@ -206,11 +221,13 @@ class ChatService(SdkServiceBase):
             if key not in _RESERVED_PAYLOAD_KEYS
         }
 
-        thinking_value, thinking_applied, thinking_reason = _resolve_thinking(
-            self._profile, request.thinking
+        thinking_value, thinking_applied, thinking_reason, thinking_level = (
+            _resolve_thinking(self._profile, request.thinking)
         )
         if thinking_reason is not None:
-            _warn_once(self._profile.name, thinking_reason)
+            _warn_once(
+                self._profile.name, thinking_reason, level=thinking_level
+            )
         if thinking_value is not _UNSET:
             spec = self._profile.thinking
             if spec is None:  # 类型收窄：applied 为 True 时 spec 必非 None

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/ai/failover.py

@@ -40,7 +40,7 @@ from typing import Any, Final, TypeVar, cast
 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
+from kit.ai.image_service import ImageResult, ImageService
 from kit.ai.model_builder import Service
 from kit.ai.pool import AIServicePool
 from kit.ai.rerank_service import RerankHit, RerankService
@@ -422,11 +422,19 @@ class FailoverImageService(_FailoverBase):
         *,
         size: str | None = None,
         n: int = 1,
+        return_base64: bool = False,
+        ratio: str | None = None,
         deadline: float | None = None,
-    ) -> str:
-        """文生图，返回图片 URL（链式故障切换）。"""
+    ) -> ImageResult:
+        """文生图，返回 :class:`ImageResult`（链式故障切换）。"""
 
-        async def _run(service: Service) -> str:
-            return await cast(ImageService, service).generate(prompt, size=size, n=n)
+        async def _run(service: Service) -> ImageResult:
+            return await cast(ImageService, service).generate(
+                prompt,
+                size=size,
+                n=n,
+                return_base64=return_base64,
+                ratio=ratio,
+            )
 
         return await self._attempt("图像生成", _run, deadline=deadline)

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/ai/image_service.py

@@ -26,7 +26,19 @@ from typing import ClassVar
 
 from kit.ai.sdk_client import SdkServiceBase
 
-__all__ = ["ImageRequest", "ImageService"]
+__all__ = ["ImageRequest", "ImageResult", "ImageService"]
+
+
+@dataclass(frozen=True)
+class ImageResult:
+    """图像生成结果。
+
+    ``url`` 与 ``b64`` 至少一个非空；两者都有时都填充（不同厂商回退行为不同）。
+    需要二进制时：有 ``b64`` 直接解码，否则下载 ``url``。
+    """
+
+    url: str | None
+    b64: str | None
 
 
 @dataclass(frozen=True)
@@ -50,8 +62,7 @@ class ImageService(SdkServiceBase):
     """图像生成服务（全异步）。
 
     ``n > 1`` 时仅返回第一张图片，调用方如需多图请自行扩展。
-    返回 ``str`` 语义：默认返回图片 URL；``return_base64=True`` 时
-    返回 Base64 数据，调用方按返回值是否以 ``http`` 开头区分形式。
+    返回 :class:`ImageResult`（``url`` / ``b64`` 至少一个非空）。
     """
 
     _LABEL: ClassVar[str] = "图像生成模型"
@@ -64,8 +75,8 @@ class ImageService(SdkServiceBase):
         n: int = 1,
         return_base64: bool = False,
         ratio: str | None = None,
-    ) -> str:
-        """文生图，返回图片 URL 或 Base64 数据。"""
+    ) -> ImageResult:
+        """文生图，返回 :class:`ImageResult`。"""
         extra: dict[str, object] = {}
         if return_base64:
             extra["return_base64"] = True
@@ -81,9 +92,10 @@ class ImageService(SdkServiceBase):
             }
         )
         with self._log_call():
-            return await self._client.image(
+            url, b64 = await self._client.image(
                 prompt,
                 size=size,
                 n=n,
                 extra_body=extra or None,
             )
+        return ImageResult(url=url, b64=b64)

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/ai/model_client.py

@@ -18,23 +18,31 @@ Author: Clark Chang
 """
 
 # date: 2026-11-04
-"""模型档案轻探测客户端（0.6.10 起仅保留探活能力）。
+"""模型档案轻探测客户端（0.7.0 起更名 ``ProbeClient``）。
 
 破坏性变更：``post_json`` / ``stream_json`` 已删除——请求发送改由
 :class:`kit.ai.sdk_client.SdkClient` 承担，rerank 走
 :class:`kit.ai.rerank_transport.RerankTransport`。本类只保留
 ``list_models()`` / ``close()``，供业务侧做「密钥是否有效」的连通性测试。
+
+``ModelClient`` 作为弃用别名保留一个版本（访问时触发 ``DeprecationWarning``）。
 """
 
-from kit.ai.sdk_client import SdkClient
+import warnings
+
 from kit.ai.profiles import ModelProfile
+from kit.ai.sdk_client import SdkClient
 from kit.ai.types import JSONObject
 
-__all__ = ["ModelClient"]
+__all__ = ["ProbeClient"]
 
 
-class ModelClient:
-    """单档案连通性探测客户端（全异步）。"""
+class ProbeClient:
+    """单档案连通性探测客户端（全异步）。
+
+    0.7.0 起由 ``ModelClient`` 改名：它只做 ``list_models`` 探活，
+    真正的传输在 :class:`kit.ai.sdk_client.SdkClient`。
+    """
 
     def __init__(self, profile: ModelProfile) -> None:
         self._profile: ModelProfile = profile
@@ -57,3 +65,15 @@ class ModelClient:
 
     async def close(self) -> None:
         await self._client.close()
+
+
+def __getattr__(name: str) -> object:
+    """0.7.0 起 ``ModelClient`` 更名为 ``ProbeClient``：保留别名并告警。"""
+    if name == "ModelClient":
+        warnings.warn(
+            "ModelClient 已更名为 ProbeClient（0.7.0），请改用 ProbeClient",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return ProbeClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/ai/pool.py

@@ -45,7 +45,7 @@ from kit.ai.embedding_service import EmbeddingService
 from kit.ai.exceptions import AIConfigError, AIError, AIRequestError
 from kit.ai.image_service import ImageService
 from kit.ai.model_builder import Service
-from kit.ai.model_client import ModelClient
+from kit.ai.model_client import ProbeClient
 from kit.ai.profiles import (
     ModelProfile,
     ModelRegistry,
@@ -85,7 +85,7 @@ async def _probe_profile(profile: ModelProfile) -> None:
 
     独立模块级函数便于测试替换。探测客户端用毕即关。
     """
-    client = ModelClient(profile)
+    client = ProbeClient(profile)
     try:
         await client.list_models()
     finally:

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/ai/rerank_service.py

@@ -43,10 +43,15 @@ class RerankRequest:
 
 @dataclass(frozen=True)
 class RerankHit:
-    """重排序单条命中结果。"""
+    """重排序单条命中结果。
+
+    ``index`` 保留是为了让调用方映射回自己的原始对象（如 dict 列表）；
+    ``document`` 是命中原文，只要文本时免去二次索引。
+    """
 
     index: int
     score: float
+    document: str
 
 
 class RerankService(LoggingServiceBase):
@@ -68,7 +73,9 @@ class RerankService(LoggingServiceBase):
             payload["top_n"] = request.top_n
         return cast(JSONObject, payload)
 
-    def _parse_response(self, data: JSONObject) -> list[RerankHit]:
+    def _parse_response(
+        self, data: JSONObject, documents: list[str]
+    ) -> list[RerankHit]:
         items = safe_get(data, "results")
         if not isinstance(items, list):
             raise AIResponseError(f"重排序响应 results 必须是数组: {str(data)[:200]}")
@@ -80,7 +87,18 @@ class RerankService(LoggingServiceBase):
             score = item.get("relevance_score")
             if not isinstance(index, int) or not isinstance(score, (int, float)):
                 raise AIResponseError(f"重排序响应字段异常: {str(item)[:200]}")
-            hits.append(RerankHit(index=index, score=float(score)))
+            # 先校验越界再构造：否则 documents[index] 会抛 IndexError
+            if index < 0 or index >= len(documents):
+                raise AIResponseError(
+                    f"重排序 index 越界: {index} (文档数 {len(documents)})"
+                )
+            hits.append(
+                RerankHit(
+                    index=index,
+                    score=float(score),
+                    document=documents[index],
+                )
+            )
         hits.sort(key=lambda h: h.score, reverse=True)
         return hits
 
@@ -103,13 +121,7 @@ class RerankService(LoggingServiceBase):
         payload = self._build_payload(RerankRequest(query, documents, top_n=top_n))
         with self._log_call():
             data = await self._client.post_json(payload, deadline=deadline)
-        hits = self._parse_response(data)
-        for hit in hits:
-            if hit.index < 0 or hit.index >= len(documents):
-                raise AIResponseError(
-                    f"重排序 index 越界: {hit.index} (文档数 {len(documents)})"
-                )
-        return hits
+        return self._parse_response(data, documents)
 
     async def close(self) -> None:
         await self._client.close()

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/ai/runner.py

@@ -57,7 +57,7 @@ from __future__ import annotations
   而非经本门面阻塞事件循环线程。
 - ``chat_stream`` 提供同步流式迭代（每次取下一帧），适合同步线程内逐 token 消费。
 - ``AI.use`` / ``AI.available`` 为进程内内存态（不持久化），进程重启后
-  回到 env（``AI_{TYPE}_PROFILES``）/ JSON 声明顺序。
+  回到 JSON 声明顺序。
 """
 
 import asyncio
@@ -81,6 +81,7 @@ from kit.ai.failover import (
 from kit.ai.model_builder import Service
 from kit.ai.pool import AIServicePool
 from kit.ai.profiles import ProfileStatus, get_model_registry
+from kit.ai.image_service import ImageResult
 from kit.ai.rerank_service import RerankHit
 from kit.config.kit_config import get_settings
 from kit.config.log_config import get_default_logger
@@ -545,27 +546,38 @@ async def _rerank(
     top_n: int | None,
     *,
     deadline: float | None = None,
-) -> list[tuple[int, float]]:
+) -> list[RerankHit]:
+    """对候选文档重排序，返回 ``RerankHit`` 降序列表。"""
     if not documents:
         return []
     service: FailoverRerankService = cast(
         FailoverRerankService,
         await _background._get_service(_RERANK),  # noqa: SLF001
     )
-    hits: list[RerankHit] = await service.rerank(
-        query, documents, top_n=top_n, deadline=deadline
-    )
-    return [(hit.index, hit.score) for hit in hits]
+    return await service.rerank(query, documents, top_n=top_n, deadline=deadline)
 
 
 async def _generate_image(
-    prompt: str, *, size: str | None, n: int, deadline: float | None = None
-) -> str:
+    prompt: str,
+    *,
+    size: str | None,
+    n: int,
+    return_base64: bool = False,
+    ratio: str | None = None,
+    deadline: float | None = None,
+) -> ImageResult:
     service: FailoverImageService = cast(
         FailoverImageService,
         await _background._get_service(_IMAGE),  # noqa: SLF001
     )
-    return await service.generate(prompt, size=size, n=n, deadline=deadline)
+    return await service.generate(
+        prompt,
+        size=size,
+        n=n,
+        return_base64=return_base64,
+        ratio=ratio,
+        deadline=deadline,
+    )
 
 
 class AI:
@@ -668,8 +680,8 @@ class AI:
     @staticmethod
     def rerank(
         query: str, documents: list[str], top_n: int | None = None
-    ) -> list[tuple[int, float]]:
-        """对候选文档重排序，返回 [(原索引, 相关分)] 降序列表。"""
+    ) -> list[RerankHit]:
+        """对候选文档重排序，返回 ``RerankHit`` 降序列表（原索引、分数、原文）。"""
         timeout = _facade_timeout(_RERANK)
         deadline = time.monotonic() + timeout
         return _background.run(
@@ -678,12 +690,26 @@ class AI:
         )
 
     @staticmethod
-    def generate_image(prompt: str, *, size: str | None = None, n: int = 1) -> str:
-        """文生图，返回生成的图片 URL。"""
+    def generate_image(
+        prompt: str,
+        *,
+        size: str | None = None,
+        n: int = 1,
+        return_base64: bool = False,
+        ratio: str | None = None,
+    ) -> ImageResult:
+        """文生图，返回 :class:`ImageResult`（``url`` / ``b64`` 至少一个非空）。"""
         timeout = _facade_timeout(_IMAGE)
         deadline = time.monotonic() + timeout
         return _background.run(
-            lambda: _generate_image(prompt, size=size, n=n, deadline=deadline),
+            lambda: _generate_image(
+                prompt,
+                size=size,
+                n=n,
+                return_base64=return_base64,
+                ratio=ratio,
+                deadline=deadline,
+            ),
             timeout=timeout,
         )
 

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/ai/sdk_client.py

@@ -262,21 +262,26 @@ class SdkClient:
         except openai.OpenAIError as exc:
             raise self._map_error(exc) from exc
         try:
-            async for chunk in stream:
-                choices = getattr(chunk, "choices", None)
-                if not choices:
-                    continue
-                choice = choices[0]
-                delta = getattr(choice, "delta", None)
-                content = getattr(delta, "content", None) if delta is not None else None
-                reasoning = _reasoning_of(delta) if delta is not None else ""
-                finish = getattr(choice, "finish_reason", None)
-                if content or reasoning or finish:
-                    yield (
-                        content if isinstance(content, str) else None,
-                        reasoning or None,
-                        finish if isinstance(finish, str) and finish else None,
+            # 用 async with 托管流：业务侧提前 break/取消时也能关闭连接，
+            # 否则只能等 GC，长跑进程会堆积半开连接
+            async with stream:
+                async for chunk in stream:
+                    choices = getattr(chunk, "choices", None)
+                    if not choices:
+                        continue
+                    choice = choices[0]
+                    delta = getattr(choice, "delta", None)
+                    content = (
+                        getattr(delta, "content", None) if delta is not None else None
                     )
+                    reasoning = _reasoning_of(delta) if delta is not None else ""
+                    finish = getattr(choice, "finish_reason", None)
+                    if content or reasoning or finish:
+                        yield (
+                            content if isinstance(content, str) else None,
+                            reasoning or None,
+                            finish if isinstance(finish, str) and finish else None,
+                        )
         except openai.OpenAIError as exc:
             raise self._map_error(exc) from exc
 
@@ -312,8 +317,8 @@ class SdkClient:
         n: int = 1,
         extra_body: JSONObject | None = None,
         deadline: float | None = None,
-    ) -> str:
-        """文生图，返回 URL 或 Base64（按返回值是否以 http 开头区分）。"""
+    ) -> tuple[str | None, str | None]:
+        """文生图，返回 ``(url, b64)``：两者可能同时有值，至少一个非空。"""
         params: dict[str, Any] = {
             "model": self._profile.model,
             "prompt": prompt,
@@ -333,23 +338,24 @@ class SdkClient:
         if not items:
             raise AIResponseError("图像生成响应缺少 data")
         first = items[0]
-        url = getattr(first, "url", None)
-        if isinstance(url, str) and url:
-            return url
-        b64 = getattr(first, "b64_json", None)
-        if isinstance(b64, str) and b64:
-            return b64
-        raise AIResponseError("图像生成响应缺少 url/b64_json")
+        raw_url = getattr(first, "url", None)
+        raw_b64 = getattr(first, "b64_json", None)
+        url = raw_url if isinstance(raw_url, str) and raw_url else None
+        b64 = raw_b64 if isinstance(raw_b64, str) and raw_b64 else None
+        if url is None and b64 is None:
+            raise AIResponseError("图像生成响应缺少 url/b64_json")
+        return url, b64
 
     async def list_models(self) -> JSONObject:
         """轻探测 ``GET {base_url}/models``：仅验证密钥有效性。
 
         独立 10 秒超时；返回值只表达成功（失败抛异常），统一返回空对象。
         """
-        await self._request(
-            lambda: self._client.models.list(timeout=_LIST_MODELS_TIMEOUT),
-            deadline=None,
-        )
+        # 探活不重试：失败即返回，避免「10s 超时 × (retries+1)」把配置页拖住
+        try:
+            await self._client.models.list(timeout=_LIST_MODELS_TIMEOUT)
+        except openai.OpenAIError as exc:
+            raise self._map_error(exc) from exc
         return {}
 
     async def close(self) -> None:

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/kit/docs/__init__.py

@@ -26,6 +26,7 @@ Author: Clark Chang
 - docx_kit:    DocxKit     Word 模板动态填充（docxtpl，extra: docx）
 - mineru_kit:  MinerUKit   MinerU 文档解析 API（requests，extra: mineru）
 - marker_kit:  MarkerKit   PDF + 图片本地解析（marker-pdf，extra: marker）
+                ⚠ 0.7.0 起**暂停发布**：不进 wheel、不可安装；需要请用 sdpy-kit==0.6.10
 - rc_docparser_kit: RcDocParserKit  离线 docx 解析（rc-docparser，extra: docx-parse）
 
 本 __init__ 不导入任何成员：五个模块均携带重型可选依赖，保持

{sdpy_kit-0.6.11 → sdpy_kit-0.7.0}/pyproject.toml

@@ -74,6 +74,8 @@ ai = [
 md2doc = [
     "pimd[pdfa]>=2.2.5",
     "markdown-it-py>=4.2.0",
+    # 0.7.0 起 marker 摘除后解除 <11 封顶，显式抬到最新
+    "pillow>=13.0.0",
 ]
 anydoc = [
     "firecrawl-anydoc>=0.2.4",
@@ -82,7 +84,6 @@ anydoc = [
 docx = ["docxtpl>=0.20.2"]
 docx-parse = ["rc-docparser>=0.2.2"]
 mineru = ["requests>=2.34.2"]
-marker = ["marker-pdf>=2.0.0"]
 laya = [
     "laya>=0.4.22",
     "huggingface-hub>=1.5,<2",
@@ -95,7 +96,9 @@ decima = [
     "huggingface-hub>=1.5,<2",
 ]
 web-article = ["trafilatura>=2.3.1"]
-all = [
+# 0.7.0 起 all 更名为 recommended：只含「轻量、互不冲突、覆盖主场景」的 extras。
+# 重依赖（laya / decima）与暂停发布的 marker 单独声明。
+recommended = [
     "psycopg2-binary>=2.9.13",
     "pymysql>=1.2.3",
     "numpy>=2.5.4",
@@ -122,6 +125,9 @@ path = "kit/__init__.py"
 
 [tool.hatch.build.targets.wheel]
 packages = ["kit"]
+# 0.7.0 起暂停发布 MarkerKit（marker-pdf 仍锁 openai<3）：源码保留在仓库，
+# 但不进 wheel。恢复时删除本行并恢复 marker extra。
+exclude = ["kit/docs/marker_kit.py"]
 
 [tool.hatch.build.targets.sdist]
 only-include = ["kit"]