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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.9
+Version: 0.6.11
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -24,6 +24,7 @@ Requires-Dist: sqlalchemy~=2.0.54
 Requires-Dist: sqlmodel>=0.0.48
 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'
@@ -31,11 +32,11 @@ 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.21; extra == 'all'
+Requires-Dist: laya>=0.4.22; extra == 'all'
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
-Requires-Dist: marker-pdf>=2.0.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'
@@ -44,7 +45,7 @@ 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.1.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'
@@ -59,7 +60,7 @@ Provides-Extra: docx-parse
 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.21; 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
@@ -75,7 +76,7 @@ Provides-Extra: redis
 Requires-Dist: redis>=8.1.0; extra == 'redis'
 Provides-Extra: sqliteai
 Requires-Dist: numpy>=2.5.4; extra == 'sqliteai'
-Requires-Dist: sqliteai-vector>=1.1.2; extra == 'sqliteai'
+Requires-Dist: sqliteai-vector>=1.2.0; extra == 'sqliteai'
 Provides-Extra: web-article
 Requires-Dist: trafilatura>=2.3.1; extra == 'web-article'
 Description-Content-Type: text/markdown
@@ -131,17 +132,17 @@ uv add sdpy-kit
 | `mysql` | MySqlKit（MySQL 驱动；向量仅存储，需 MySQL 9.x） | `pip install "sdpy-kit[mysql]"` |
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
-| `ai` | AI 服务池（httpx + python-dotenv） | `pip install "sdpy-kit[ai]"` |
+| `ai` | AI 服务池（openai>=3.44 + httpx + python-dotenv；安装体积约 +10MB，SDK 自带 httpx2） | `pip install "sdpy-kit[ai]"` |
 | `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2，含图片） | `pip install "sdpy-kit[md2doc]"` |
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `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 + 图片，依赖体积大） | `pip install "sdpy-kit[marker]"` |
+| `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` | 全部能力 | `pip install "sdpy-kit[all]"` |
+| `all` | 常用能力集合，**不含 `marker`**（0.6.11 起，避免与 `[ai]` 的 openai 约束冲突）；需要 Marker 请单独装 `[marker]` | `pip install "sdpy-kit[all]"` |
 
 ## 配置（.env）
 
@@ -809,6 +810,14 @@ page = qb.paginate(page=1, per_page=20)            # {"items", "total", ...}
 ## kit.ai —— AI 多模型服务池
 
 安装：`pip install "sdpy-kit[ai]"`
+
+传输（0.6.11）：chat / embedding / image 走 `openai` SDK（`>=3.44,<4`，
+自带 `httpx2`），rerank 走 httpx 自研传输（SDK 无 `/rerank` 资源）。
+档案里的 `endpoint` **对前三类不再生效**——SDK 固定拼 `/chat/completions`、
+`/embeddings`、`/images/generations`，仅 rerank 与探活仍使用该字段。
+
+> 安装提示：`openai` 3.x 会引入 `httpx2`，与 rerank 用的 `httpx` 并存（两个包名不同，不冲突）。
+
 档案：项目根 `config/ai_models.json`（见文末「AI 档案文件」）
 
 ### 1. 同步门面 `AI`（推荐）
@@ -1600,7 +1609,8 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 
 | 层级 | 字段 | 说明 |
 |------|------|------|
-| 档案级 | `timeout` | 请求超时秒数（默认 60） |
+| 档案级 | `endpoint` | 请求路径。**0.6.10 起仅 rerank 生效**：chat / embedding / image 由 openai SDK 固定拼路径，本字段被忽略（保留仅为兼容旧配置，不报错） |
+| 档案级 | `timeout` | 请求超时秒数（默认 60）；SDK 侧为单次调用总超时 |
 | 档案级 | `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`）无法用它实现。逐调用 `thinking` 与之同键时**以逐调用为准**并打 `WARNING`。改文件后需 `reload_config(reload_file=True)` 生效 |

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

@@ -49,17 +49,17 @@ uv add sdpy-kit
 | `mysql` | MySqlKit（MySQL 驱动；向量仅存储，需 MySQL 9.x） | `pip install "sdpy-kit[mysql]"` |
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
-| `ai` | AI 服务池（httpx + python-dotenv） | `pip install "sdpy-kit[ai]"` |
+| `ai` | AI 服务池（openai>=3.44 + httpx + python-dotenv；安装体积约 +10MB，SDK 自带 httpx2） | `pip install "sdpy-kit[ai]"` |
 | `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2，含图片） | `pip install "sdpy-kit[md2doc]"` |
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `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 + 图片，依赖体积大） | `pip install "sdpy-kit[marker]"` |
+| `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` | 全部能力 | `pip install "sdpy-kit[all]"` |
+| `all` | 常用能力集合，**不含 `marker`**（0.6.11 起，避免与 `[ai]` 的 openai 约束冲突）；需要 Marker 请单独装 `[marker]` | `pip install "sdpy-kit[all]"` |
 
 ## 配置（.env）
 
@@ -727,6 +727,14 @@ page = qb.paginate(page=1, per_page=20)            # {"items", "total", ...}
 ## kit.ai —— AI 多模型服务池
 
 安装：`pip install "sdpy-kit[ai]"`
+
+传输（0.6.11）：chat / embedding / image 走 `openai` SDK（`>=3.44,<4`，
+自带 `httpx2`），rerank 走 httpx 自研传输（SDK 无 `/rerank` 资源）。
+档案里的 `endpoint` **对前三类不再生效**——SDK 固定拼 `/chat/completions`、
+`/embeddings`、`/images/generations`，仅 rerank 与探活仍使用该字段。
+
+> 安装提示：`openai` 3.x 会引入 `httpx2`，与 rerank 用的 `httpx` 并存（两个包名不同，不冲突）。
+
 档案：项目根 `config/ai_models.json`（见文末「AI 档案文件」）
 
 ### 1. 同步门面 `AI`（推荐）
@@ -1518,7 +1526,8 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 
 | 层级 | 字段 | 说明 |
 |------|------|------|
-| 档案级 | `timeout` | 请求超时秒数（默认 60） |
+| 档案级 | `endpoint` | 请求路径。**0.6.10 起仅 rerank 生效**：chat / embedding / image 由 openai SDK 固定拼路径，本字段被忽略（保留仅为兼容旧配置，不报错） |
+| 档案级 | `timeout` | 请求超时秒数（默认 60）；SDK 侧为单次调用总超时 |
 | 档案级 | `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`）无法用它实现。逐调用 `thinking` 与之同键时**以逐调用为准**并打 `WARNING`。改文件后需 `reload_config(reload_file=True)` 生效 |

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

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

sdpy_kit-0.6.11/kit/ai/_retry_after.py

@@ -0,0 +1,51 @@
+"""
+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
+"""
+
+"""``Retry-After`` 响应头解析（SDK 传输与 rerank 传输共用）。"""
+
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Final
+
+__all__ = ["parse_retry_after"]
+
+# 重试前剩余整链预算的最小门槛（秒）：不足则放弃重试直接抛出
+MIN_RETRY_BUDGET: Final[float] = 1.0
+
+
+def parse_retry_after(raw: str | None) -> float | None:
+    """解析 ``Retry-After`` 响应头为等待秒数。
+
+    支持 RFC 7231 两种格式：整数秒与 HTTP-date（按 UTC 计算剩余秒，
+    过去时刻钳为 0）；缺失或非法返回 None。
+    """
+    if not raw:
+        return None
+    raw = raw.strip()
+    if raw.isdigit():
+        return float(raw)
+    try:
+        dt = parsedate_to_datetime(raw)
+    except (TypeError, ValueError):
+        return None
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return max((dt - datetime.now(timezone.utc)).total_seconds(), 0.0)

sdpy_kit-0.6.11/kit/ai/_service_base.py

@@ -0,0 +1,115 @@
+"""
+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
+"""
+
+# date: 2026-11-04
+"""AI 服务公共基类：档案属性、生命周期与统一日志骨架。
+
+0.6.10 起不再包含 HTTP 传输与请求体编排：chat / embedding / image 由
+``SdkClient`` 承担，rerank 由 ``RerankTransport`` 承担。本模块只保留
+四类服务共用的日志与资源管理能力。
+"""
+
+import time
+from abc import ABC
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import ClassVar
+
+from kit.ai.exceptions import AIError, AIResponseError
+from kit.ai.profiles import ModelProfile
+from kit.ai.types import JSONValue
+from kit.config.log_config import get_default_logger
+
+__all__ = ["LoggingServiceBase", "safe_get"]
+
+logger = get_default_logger(__name__)
+
+
+def safe_get(data: JSONValue, *path: str | int) -> JSONValue:
+    """按层级路径安全取值，支持 dict 键（str）与 list 索引（int）。
+
+    Raises:
+        AIResponseError: 路径任一环节缺失或类型不符。
+    """
+    cur: JSONValue = data
+    for key in path:
+        if isinstance(key, int):
+            if not isinstance(cur, list) or key < 0 or key >= len(cur):
+                raise AIResponseError(f"响应缺少索引 {path}: {str(data)[:200]}")
+            cur = cur[key]
+        else:
+            if not isinstance(cur, dict) or key not in cur:
+                raise AIResponseError(
+                    f"响应缺少字段 {'.'.join(map(str, path))}: {str(data)[:200]}"
+                )
+            cur = cur[key]
+    return cur
+
+
+class LoggingServiceBase(ABC):
+    """四类模型服务共用的档案属性、日志骨架与异步上下文。"""
+
+    _LABEL: ClassVar[str] = "模型"
+
+    def __init__(self, profile: ModelProfile) -> None:
+        self._profile: ModelProfile = profile
+
+    @property
+    def profile(self) -> ModelProfile:
+        return self._profile
+
+    def _log_desc(self, *, suffix: str = "") -> str:
+        """日志中的「模型及描述」：服务中文名 + 模型标识 + 实例名。"""
+        return (
+            f"{self._LABEL} {self._profile.model}"
+            f"（实例 {self._profile.name}{suffix}）"
+        )
+
+    @contextmanager
+    def _log_call(self, *, log: bool = True) -> Iterator[None]:
+        """统一日志骨架：Start → 成功耗时 / 失败 ERROR。"""
+        desc = self._log_desc()
+        if log:
+            logger.info(f"********** {desc} ********** Start")
+        start = time.perf_counter()
+        try:
+            yield
+        except AIError as exc:
+            logger.error(
+                f"********** {desc} ********** "
+                f"耗时 {time.perf_counter() - start:.1f}秒（失败：{exc}）"
+            )
+            raise
+        if log:
+            logger.info(
+                f"********** {desc} ********** 耗时 {time.perf_counter() - start:.1f}秒"
+            )
+
+    async def close(self) -> None:
+        """释放底层资源（子类实现）。"""
+        raise NotImplementedError
+
+    async def __aenter__(self) -> "LoggingServiceBase":
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__}({self._profile.name})"