sdpy-kit 0.1.2__tar.gz → 0.1.4__tar.gz

{sdpy_kit-0.1.2 → sdpy_kit-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.1.2
+Version: 0.1.4
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -17,23 +17,34 @@ Classifier: Topic :: Database
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.13
-Requires-Dist: fastmcp>=4.0.3
 Requires-Dist: firecrawl-anydoc>=0.2.4
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: numpy>=2.0
 Requires-Dist: pimd[pdfa]>=2.2.5
-Requires-Dist: psycopg2-binary>=2.9.12
 Requires-Dist: pydantic-settings>=2.0
 Requires-Dist: pydantic>=2.0
-Requires-Dist: pymysql>=1.2.0
 Requires-Dist: python-dotenv>=1.2.3
-Requires-Dist: redis>=5.0.0
 Requires-Dist: requests>=2.34.0
 Requires-Dist: sqlalchemy~=2.0.51
 Requires-Dist: sqliteai-vector>=1.0.0
 Requires-Dist: sqlmodel>=0.0.39
-Requires-Dist: zvec>=0.6.0
+Provides-Extra: all
+Requires-Dist: fastmcp>=4.0.3; extra == 'all'
+Requires-Dist: psycopg2-binary>=2.9.12; extra == 'all'
+Requires-Dist: pymysql>=1.2.0; extra == 'all'
+Requires-Dist: redis>=5.0.0; extra == 'all'
+Requires-Dist: zvec>=0.6.0; extra == 'all'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=4.0.3; extra == 'mcp'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.2.0; extra == 'mysql'
+Provides-Extra: pg
+Requires-Dist: psycopg2-binary>=2.9.12; extra == 'pg'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Provides-Extra: zvec
+Requires-Dist: zvec>=0.6.0; extra == 'zvec'
 Description-Content-Type: text/markdown
 
 # sdpy-kit

{sdpy_kit-0.1.2 → sdpy_kit-0.1.4}/kit/__init__.py

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

{sdpy_kit-0.1.2 → sdpy_kit-0.1.4}/kit/ai/base_service.py

@@ -17,16 +17,25 @@ Project: sdpy
 Author: Clark Chang
 """
 
+import json
+import time
 from abc import ABC, abstractmethod
-from typing import Self, override
+from typing import ClassVar, Final, Self, override
 
-from kit.ai.exceptions import AIResponseError
+from kit.ai.exceptions import AIError, AIResponseError
 from kit.ai.model_client import ModelClient
 from kit.ai.profiles import ModelProfile
 from kit.ai.types import JSONObject, JSONValue
+from kit.config.log_config import get_default_logger
 
 __all__ = ["BaseAIService", "safe_get"]
 
+logger = get_default_logger(__name__)
+
+# 日志打印请求参数的截断上限：单字段字符数 / 参数总字符数
+_LOG_FIELD_LIMIT: Final[int] = 200
+_LOG_PAYLOAD_LIMIT: Final[int] = 2000
+
 
 def safe_get(data: JSONValue, *path: str | int) -> JSONValue:
     """按层级路径安全取值，支持 dict 键（str）与 list 索引（int）。
@@ -49,6 +58,26 @@ def safe_get(data: JSONValue, *path: str | int) -> JSONValue:
     return cur
 
 
+def _clip(value: JSONValue) -> JSONValue:
+    """递归裁剪过长字符串字段（日志打印参数用，单字段上限 _LOG_FIELD_LIMIT）。"""
+    if isinstance(value, str):
+        if len(value) > _LOG_FIELD_LIMIT:
+            return f"{value[:_LOG_FIELD_LIMIT]}…(截断)"
+        return value
+    if isinstance(value, list):
+        return [_clip(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _clip(item) for key, item in value.items()}
+    return value
+
+
+def _truncate(text: str, limit: int) -> str:
+    """超长文本按上限截断，尾部追加截断标记（日志打印参数总长用）。"""
+    if len(text) > limit:
+        return f"{text[:limit]}…(截断)"
+    return text
+
+
 class BaseAIService[RequestT, ResponseT](ABC):
     """AI 服务基类（模板方法 + 泛型）。
 
@@ -58,6 +87,9 @@ class BaseAIService[RequestT, ResponseT](ABC):
     类型 ``ResponseT`` 由泛型绑定，保证覆写签名一致、类型自洽。
     """
 
+    # 日志「模型及描述」中的服务中文名，子类覆写
+    _LABEL: ClassVar[str] = "模型"
+
     def __init__(self, profile: ModelProfile) -> None:
         self._profile: ModelProfile = profile
         self._client: ModelClient = ModelClient(profile)
@@ -66,6 +98,13 @@ class BaseAIService[RequestT, ResponseT](ABC):
     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}）"
+        )
+
     @abstractmethod
     def _build_payload(self, request: RequestT) -> JSONObject:
         """将请求模型构造为 JSON 请求体。"""
@@ -75,10 +114,28 @@ class BaseAIService[RequestT, ResponseT](ABC):
         """将 JSON 响应体解析为业务结果。"""
 
     async def _call(self, request: RequestT) -> ResponseT:
-        """统一编排：构造请求体 → 发送 → 解析响应。"""
+        """统一编排：构造请求体 → 发送 → 解析响应（含中文 info 日志）。"""
+        desc = self._log_desc()
         payload = self._build_payload(request)
-        data = await self._client.post_json(payload)
-        return self._parse_response(data)
+        params = _truncate(
+            json.dumps(_clip(payload), ensure_ascii=False), _LOG_PAYLOAD_LIMIT
+        )
+        logger.info(f"********** {desc} ********** Start")
+        logger.info(f"请求参数: {params}")
+        start = time.perf_counter()
+        try:
+            data = await self._client.post_json(payload)
+            result = self._parse_response(data)
+        except AIError as exc:
+            logger.error(
+                f"********** {desc} ********** "
+                f"耗时 {time.perf_counter() - start:.1f}秒（失败：{exc}）"
+            )
+            raise
+        logger.info(
+            f"********** {desc} ********** 耗时 {time.perf_counter() - start:.1f}秒"
+        )
+        return result
 
     async def close(self) -> None:
         await self._client.close()

{sdpy_kit-0.1.2 → sdpy_kit-0.1.4}/kit/ai/chat_service.py

@@ -17,12 +17,20 @@ Project: sdpy
 Author: Clark Chang
 """
 
+import json
+import time
 from collections.abc import AsyncIterator
 from dataclasses import dataclass
-from typing import cast, override
-
-from kit.ai.base_service import BaseAIService, safe_get
-from kit.ai.exceptions import AIResponseError
+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
 
@@ -46,6 +54,8 @@ class ChatRequest:
 class ChatService(BaseAIService[ChatRequest, str]):
     """对话类模型服务（全异步）。"""
 
+    _LABEL: ClassVar[str] = "对话模型"
+
     @override
     def _build_payload(self, request: ChatRequest) -> JSONObject:
         payload: dict[str, object] = {
@@ -97,14 +107,38 @@ class ChatService(BaseAIService[ChatRequest, str]):
             messages, temperature=temperature, max_tokens=max_tokens, stream=True
         )
         payload = self._build_payload(request)
-        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
+        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}"
+            )

{sdpy_kit-0.1.2 → sdpy_kit-0.1.4}/kit/ai/embedding_service.py

@@ -19,6 +19,7 @@ Author: Clark Chang
 
 import asyncio
 import itertools
+import time
 from dataclasses import dataclass
 from typing import cast, override
 
@@ -26,9 +27,12 @@ from kit.ai.base_service import BaseAIService, safe_get
 from kit.ai.exceptions import AIError, AIRequestError, AIResponseError
 from kit.ai.profiles import ModelProfile
 from kit.ai.types import JSONObject
+from kit.config.log_config import get_default_logger
 
 __all__ = ["EmbeddingRequest", "EmbeddingService"]
 
+logger = get_default_logger(__name__)
+
 _DEFAULT_CONCURRENCY = 4
 
 
@@ -106,28 +110,44 @@ class EmbeddingService(BaseAIService[EmbeddingRequest, list[list[float]]]):
             return []
 
         batch = batch_size or self._profile.batch_size
-        semaphore = asyncio.Semaphore(concurrency)
-        results: list[list[float] | None] = [None] * len(texts)
-        failures: list[str] = []
-
-        async def _one(batch_index: int, chunk: tuple[str, ...]) -> None:
-            async with semaphore:
-                try:
-                    vectors = await self._call(EmbeddingRequest(list(chunk)))
-                except AIError as exc:
-                    failures.append(f"批次 {batch_index}: {exc}")
-                    return
-                start = batch_index * batch
-                for offset, vec in enumerate(vectors):
-                    results[start + offset] = vec
-
         batches = list(itertools.batched(texts, batch, strict=False))
-        await asyncio.gather(*(_one(i, chunk) for i, chunk in enumerate(batches)))
-
-        if failures:
-            raise AIRequestError(
-                f"有 {len(failures)}/{len(batches)} 批向量化失败: "
-                + " | ".join(failures)
+        desc = self._log_desc(suffix="，整批汇总")
+        logger.info(f"********** {desc} ********** Start")
+        logger.info(
+            f"请求参数: 共 {len(texts)} 条文本，分 {len(batches)} 批"
+            f"（批大小 {batch}，并发 {concurrency}）"
+        )
+        start = time.perf_counter()
+        note = ""
+        try:
+            semaphore = asyncio.Semaphore(concurrency)
+            results: list[list[float] | None] = [None] * len(texts)
+            failures: list[str] = []
+
+            async def _one(batch_index: int, chunk: tuple[str, ...]) -> None:
+                async with semaphore:
+                    try:
+                        vectors = await self._call(EmbeddingRequest(list(chunk)))
+                    except AIError as exc:
+                        failures.append(f"批次 {batch_index}: {exc}")
+                        return
+                    start = batch_index * batch
+                    for offset, vec in enumerate(vectors):
+                        results[start + offset] = vec
+
+            await asyncio.gather(*(_one(i, chunk) for i, chunk in enumerate(batches)))
+
+            if failures:
+                note = f"（失败：{len(failures)}/{len(batches)} 批）"
+                raise AIRequestError(
+                    f"有 {len(failures)}/{len(batches)} 批向量化失败: "
+                    + " | ".join(failures)
+                )
+
+            return [vec for vec in results if vec is not None]
+        finally:
+            log = logger.error if failures else logger.info
+            log(
+                f"********** {desc} ********** "
+                f"耗时 {time.perf_counter() - start:.1f}秒{note}"
             )
-
-        return [vec for vec in results if vec is not None]

{sdpy_kit-0.1.2 → sdpy_kit-0.1.4}/kit/ai/image_service.py

@@ -18,7 +18,7 @@ Author: Clark Chang
 """
 
 from dataclasses import dataclass
-from typing import override
+from typing import ClassVar, override
 
 from kit.ai.base_service import BaseAIService, safe_get
 from kit.ai.exceptions import AIResponseError
@@ -52,6 +52,8 @@ class ImageService(BaseAIService[ImageRequest, str]):
     返回 Base64 数据，调用方按返回值是否以 ``http`` 开头区分形式。
     """
 
+    _LABEL: ClassVar[str] = "图像生成模型"
+
     @override
     def _build_payload(self, request: ImageRequest) -> JSONObject:
         payload: JSONObject = {

{sdpy_kit-0.1.2 → sdpy_kit-0.1.4}/kit/ai/rerank_service.py

@@ -18,7 +18,7 @@ Author: Clark Chang
 """
 
 from dataclasses import dataclass
-from typing import cast, override
+from typing import ClassVar, cast, override
 
 from kit.ai.base_service import BaseAIService, safe_get
 from kit.ai.exceptions import AIResponseError
@@ -47,6 +47,8 @@ class RerankHit:
 class RerankService(BaseAIService[RerankRequest, list[RerankHit]]):
     """重排序服务（全异步）。"""
 
+    _LABEL: ClassVar[str] = "重排序模型"
+
     @override
     def _build_payload(self, request: RerankRequest) -> JSONObject:
         payload: dict[str, object] = {

{sdpy_kit-0.1.2 → sdpy_kit-0.1.4}/pyproject.toml

@@ -34,21 +34,34 @@ dependencies = [
     "numpy>=2.0",
     "sqlalchemy~=2.0.51",
     "sqlmodel>=0.0.39",
-    "pymysql>=1.2.0",
-    "psycopg2-binary>=2.9.12",
-    "redis>=5.0.0",
-    "zvec>=0.6.0",
     "sqliteai-vector>=1.0.0",
     "firecrawl-anydoc>=0.2.4",
     "pimd[pdfa]>=2.2.5",
     "markdown-it-py>=3.0",
-    "fastmcp>=4.0.3",
     "httpx>=0.28.1",
     "requests>=2.34.0",
     "python-dotenv>=1.2.3",
 ]
 dynamic = ["version"]
 
+# 关键节点：可选后端按 extras 拆分（0.1.4）。fastmcp/zvec/redis/psycopg2/pymysql
+# 仅在对应 Kit（mcp_kit/zvec_kit/redis_kit/pg_kit/mysql_kit）被实际使用时才需
+# 安装，且均为延迟导入——不装 extras 时 import kit 与基础 Kit 全部可用。
+# 单机 SQLite 场景安装基础版即可，避免拖入重依赖（原全量安装多占约 60MB）。
+[project.optional-dependencies]
+pg = ["psycopg2-binary>=2.9.12"]
+mysql = ["pymysql>=1.2.0"]
+redis = ["redis>=5.0.0"]
+zvec = ["zvec>=0.6.0"]
+mcp = ["fastmcp>=4.0.3"]
+all = [
+    "psycopg2-binary>=2.9.12",
+    "pymysql>=1.2.0",
+    "redis>=5.0.0",
+    "zvec>=0.6.0",
+    "fastmcp>=4.0.3",
+]
+
 [tool.hatch.version]
 path = "kit/__init__.py"