sdpy-kit 0.6.1__tar.gz → 0.6.3__tar.gz

{sdpy_kit-0.6.1 → sdpy_kit-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.1
+Version: 0.6.3
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -80,7 +80,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；内置审计字段自动填充（`created_*` / `updated_*` / `deleted`）与软删除查询过滤；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
-- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
 
 > 要求 Python 3.13+
 
@@ -94,6 +94,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
 | `kit.file_kit` | `FileKit` | 文件与目录读写、移动、遍历 | 无 |
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
+| `kit.license_kit` | `LicenseKit` / `LicenseVerifier` | Ed25519 离线授权：密钥对、机器码、签发、验签（签名 → 产品 → 机器码 → 有效期） | 无 |
 | `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
 | `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
@@ -187,7 +188,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.crawl.article_models`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.crawl.wx_article_kit`、`kit.crawl.web_article_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.crawl.article_models`、`kit.crawl.article_io`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.license_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -272,6 +273,21 @@ SQLITE_DB_PATH=./data/sqlite.db
 > `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
 > `LAYA_MODEL` / `LAYA_DEVICE` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
 
+**DeepSeek Search / Fetch** → `kit.crawl.deepseek_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `DEEPSEEK_API_KEY` | 无 | Search / Fetch 鉴权 Key（与模型对话共用同一套）；缺失时调用抛 `DeepSeekKitError` |
+| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API 基础地址 |
+| `DEEPSEEK_TIMEOUT` | `60`（1–600） | 单次 HTTP 请求超时（秒） |
+| `DEEPSEEK_MAX_RETRIES` | `2`（0–5） | 408 / 429 / 5xx 重试次数（不含首次请求）；其它 4xx 不重试 |
+
+**文章抓取长度自检** → `kit.crawl.wx_article_kit` / `web_article_kit` / `deepseek_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `CRAWL_MIN_CONTENT_CHARS` | `500`（≥0） | 正文短于该长度时写入 `warnings`（非致命，不改成功语义、不截断正文）；`0` 关闭该判据 |
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.docs.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -369,9 +385,9 @@ from kit import session_scope, transactional, DBError       # 等价
 | 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
 | 原生表 | `raw_insert(table_name, data, *, ignore_conflict=False) -> int` | 插入一行；`ignore_conflict=True` 幂等（PG/SQLite `ON CONFLICT DO NOTHING`、MySQL `INSERT IGNORE`） |
 | 原生表 | `raw_update(table_name, data, where, params=None) -> int` | 按 `where`（不含 `WHERE`）更新；启用审计填充时自动补 `updated_*` |
-| 原生表 | `raw_touch(table_name, where, params=None) -> int` | **0.6.0**：只刷新 `updated_*`（需先 `enable`；表无该列抛 `DBError`） |
-| 原生表 | `raw_delete(table_name, where, params=None) -> int` | **0.6.0**：条件删除（`where` 必填） |
-| 原生表 | `build_raw_insert / build_raw_update / build_raw_touch / build_raw_delete` | **0.6.0**：只拼装不执行，返回 `(语句, 参数)`，供**自有事务**内 `session.execute(*builder(...))` |
+| 原生表 | `raw_touch(table_name, where, params=None) -> int` | 只刷新 `updated_*`（需先 `enable`；表无该列抛 `DBError`） |
+| 原生表 | `raw_delete(table_name, where, params=None) -> int` | 条件删除（`where` 必填） |
+| 原生表 | `build_raw_insert / build_raw_update / build_raw_touch / build_raw_delete` | 只拼装不执行，返回 `(语句, 参数)`，供**自有事务**内 `session.execute(*builder(...))` |
 | 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
 | 事务 | `transaction()` | 事务上下文管理器，`with PgKit.transaction() as session:` |
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
@@ -435,6 +451,7 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 | `insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> int` | 批量插入向量（**自成一事务并提交**）；`ids=None` 时由 Kit 生成雪花 ID；接受 `list[list[float]]` 或二维 numpy 数组 |
 | `build_insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> list[tuple[str, list[dict]]]` | **只拼装、不执行、不管事务**：返回按列集分组的 `(SQL, 参数列表)`，供调用方在**自有事务**内写向量行（见「自有事务内写向量」） |
 | `search_vectors(table_name, query_vector, top_k=10, distance_type="L2", filter_sql=None, exact=True, id_col="id", column="embedding") -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；`exact=True`（默认）禁止近似加速；**MySQL 侧抛 `VectorNotSupportedError`** |
+| `vector_column_dimension(table_name, column="embedding") -> int \| None` | 查列**声明的维度**：PG 为精确维度（`vector(1024)`→1024）；MySQL 为**最大上限**（未指定维度落 `2048`）；SQLite 恒 `None`（无元数据）。列不存在 / 非向量列 / 无维度声明 → `None`，不抛异常。口径差异由 `VECTOR_CAPABILITIES["dimension_kind"]` 声明（`"exact"` / `"max"` / `None`） |
 | `vector_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
 
 **`id_col` / `column`（逃生口）**：让**自建 DDL 的向量表**也能读写/检索。需要复合主键、额外约束、
@@ -457,12 +474,17 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 | 默认 `distance_type` | `"L2"` | `"L2"`（三库统一，不按后端覆写） | `"L2"`（形参保留，调用即抛错） |
 | 非法取值 | 抛 `ValueError` | 抛 `ValueError` | `search_vectors` 抛 `VectorNotSupportedError` |
 | `distance` 口径 | `exact=True` 真值 L2 / `exact=False` 量化（×255） | 真实距离 | — |
-| 维度约束 | `CHECK`（仅新表；旧表靠方法内校验） | 强制（不匹配即报错；建表时回读比对） | 上限约束（超限报错） |
+| 维度约束 | `CHECK`（仅新表；旧表靠方法内校验） | 强制（不匹配即报错；建表时回读比对） | **上限**（`VECTOR(N)` 的 N 是最大维度，写入须 ≤ N，超限报 `1406 Data too long`） |
+| 维度查询 | 恒 `None`（无元数据） | 精确维度（`dimension_kind="exact"`） | 最大上限（`dimension_kind="max"`） |
 | `filter_sql` 与 `top_k` | **先过滤再取 top_k**（与 PG 一致） | **先过滤再取 top_k** | 不适用 |
 | 索引 | 无（精确路径为全表扫描） | kit 不建索引；**自建后须 `exact=False` 才会被使用** | 无法建（B-Tree 拒绝向量列） |
 
 > MySQL `DISTANCE()` / `VECTOR_DISTANCE()` 仅 HeatWave on OCI 与 MySQL AI 提供
 > （Community 实测报 `1305 FUNCTION ... does not exist`）；故 `MySqlKit` 只覆盖存储侧。
+>
+> 维度上限（插件侧实测 pgvector 0.8.7）：`vector` ≤ **16000** 维；hnsw / ivfflat 索引
+> ≤ **2000** 维；`halfvec` 表达式索引 ≤ **4000** 维。因此 **1024 维表可建 HNSW，
+> 2560 / 4096 维表建不了**。
 
 **主键与 id（三库统一）**：向量表主键均为 `BIGINT`（SQLite 用等价的 64 位 `INTEGER PRIMARY KEY`），
 **不使用数据库自增**；`ids=None` 时由 Kit 用 `CommonKit.generate_snowflake_id()` 生成雪花 ID
@@ -497,7 +519,11 @@ MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 PgKit.VECTOR_CAPABILITIES
 # {'store': True, 'search': True, 'exact': True,
 #  'distances': ('COSINE', 'L2', 'L1', 'DOT', 'SQUARED_L2'),
-#  'distance_kind': 'true', 'fast_distance_kind': 'true'}
+#  'distance_kind': 'true', 'fast_distance_kind': 'true',
+#  'dimension_kind': 'exact'}      # MySQL='max' / SQLite=None
+
+# 查询库列声明的维度（守卫「配置 vs 库列」用；查不到返回 None）
+PgKit.vector_column_dimension("images", "embedding")   # 384
 
 # 自建 DDL 的表：用 id_col / column 接入
 PgKit.execute("CREATE TABLE my_vec (vid BIGINT PRIMARY KEY, vec vector(384))")
@@ -505,57 +531,9 @@ PgKit.insert_vectors("my_vec", [[0.1] * 384], ids=[1], id_col="vid", column="vec
 PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 ```
 
-#### 0.2.2 行为变更（升级须知）
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B1 | `search_vectors` 新增 `exact: bool = True`，默认**精确** | SQLite 返回的 `distance` 由量化值（≈L2×255）变为**真值 L2**；需旧口径请显式 `exact=False` |
-| B2 | `filter_sql` 语义统一为**先过滤、再取 top_k** | 传 `filter_sql` 的调用返回值**变多/变全**（旧结果 ⊆ 新结果）；曾自行放大 `top_k` 兜底的调用可收紧 |
-| B3 | 默认 `distance_type` 由 `"COSINE"` 改为 `"L2"` | 依赖默认值的调用方请显式传 `distance_type="COSINE"` |
-| B4 | `create_vector_table` 的 `dims` **必填**，参数顺序为 `(table_name, dims, id_col, column, extra_cols)` | `create_vector_table("t")` 类调用需补维度；位置传 `id_col` 的调用改为关键字 |
-| B5 | MySQL 的 `search_vectors` 异常由 `NotImplementedError` 改为 `VectorNotSupportedError`（继承 `DBError`） | `except NotImplementedError` 需改为 `except VectorNotSupportedError`（或 `except DBError`） |
-
-> 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
-> `insert_vectors` 支持二维 numpy 数组与批量提交。
-
-#### 0.2.6 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| D1 | `prepare_statement` 的 `params` 支持**参数行列表**（`list[dict]`）：**原样返回该列表** → `session.execute(*prepare_statement(sql, params))` 即批量执行（executemany），与 `build_insert_vectors` 的返回形态直接对接；行键集不一致或行值含序列 → 本地可操作 `ValueError`（与 `execute` 批量形态**同一规则**） | 向后兼容：单字典 / `None` 形态行为不变；行列表形态**不做** `IN` 展开（与批量互斥） |
-| D1 | 文档：修正「自有事务」示例——0.2.5 的示例把 `build_insert_vectors` 返回的**行列表**传给了单字典形态，照抄会抛 `AttributeError: 'list' object has no attribute 'items'` | **纯文档缺陷修正**（0.2.5 示例照抄即崩） |
-| — | 文档：批量执行补充 `rowcount` 备注——忽略型写入（如 SQLite `INSERT OR IGNORE`）的冲突行不计入 `rowcount`（即 `rowcount` = 实际插入数；⚠ 仅 SQLite 实测） | 文档 |
-
-#### 0.2.5 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| — | 新增**模块级公共函数** `prepare_statement(sql, params=None) -> (语句, 归一化参数)`：供调用方在**自有事务**内执行原生 SQL（含 `IN :ids`），**调用方无须 import `sqlalchemy`**；与 `query` / `execute` 同一实现（单一事实源） | **纯新增**：`query` / `transaction` 的签名与行为**零变更**；共享方法数仍为 **24**（模块级函数不计入） |
-| — | `execute` 的 `params` 支持**字典列表**（executemany，同一语句 + N 行参数一次往返）；**空列表**不触库返回 `0` | 向后兼容：单字典 / `None` 形态行为不变；批量要求各行字典**键集一致**、行值为**标量**（与 `IN` 展开互斥），违规在本地抛可操作 `ValueError`（含行号），不触库 |
-| — | 文档：自有事务示例改用 `prepare_statement`（不再需要 `from sqlalchemy import text`）；补「批量执行」说明与约束 | 文档 |
-
-> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**（0.2.5 之前亦如此），
+> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**，
 > 请改用 `CAST(:name AS type)`。
 
-#### 0.2.4 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B4 | **入参自洽性校验**（`extra_data` 的键）：保留绑定名 `id` / `vec`、与 `id_col` / `column` 重复、不是合法标识符、`id_col == column` → 抛可操作的 `ValueError` | **唯一行为变更**：此前 SQLite 会**静默写坏数据**（如 `id` 列被覆盖）、PG/MySQL 报误导性错误；正常调用**零影响** |
-| — | 新增共享方法 `build_insert_vectors`（只拼装不执行，由 `BaseDbKit` 收敛 → 共享方法 23 → **24**） | 纯新增：可在**自有事务**内写向量行（见下） |
-| — | `create_vector_table` 的 `extra_cols` 支持 `{列名: 类型串}`（与 `create_raw_table` 同形） | 纯新增：既有 `[{"name","type"}]` 形态保留，两者产出 DDL 逐字一致 |
-| — | 后端差异收口：向量列占位符由 `VECTOR_PLACEHOLDER` 驱动（MySQL = `STRING_TO_VECTOR(:vec)`） | 内部整理：公开签名与行为不变 |
-| — | `SQLiteKit.insert_vectors` 的事务获取统一为 `transaction()`（与另两库同构） | 内部一致：行为等价（自成一事务并提交） |
-
-#### 0.2.3 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B6 | **`PgKit.get_table_info` 按数据库解析语义定位表**（`search_path` 解析到的那张表） | 多 schema 下同名表**不再混行**；单 schema / `public` 场景**无影响**；只接受非限定表名 |
-| — | `query` / `execute` 支持**列表参数**（`IN :ids`，三库通用） | 纯新增；`set`/`frozenset` 自动归一化为 `list` |
-| — | 新增 `SQLiteKit.encode_vector` / `decode_vector`（小端 float32） | 纯新增：可在自有事务内写向量表，见下 |
-| — | 导出面统一：`from kit.db import PgKit, MySqlKit, SQLiteKit, build_pg_url, …` | 纯新增；既有导出未删除/未改名 |
-
 **两段查询范式（推荐用法）**：`search_vectors` 只返回 `[{"id", "distance"}]`，载荷二次取回：
 
 ```python
@@ -670,7 +648,7 @@ AuditConfig.set_fields(None)  # 恢复默认
 - 写方法与 `query()` 手写 SQL 不追加过滤条件；`upsert` 的冲突回查跳过过滤。
 - `user_resolver` 返回 `None` / 空串或抛异常时跳过 `*_by` 填充，不影响写入。
 
-**原生写工具（0.6.0）**：`raw_insert` / `raw_update` / `raw_touch` / `raw_delete` 自带事务；
+**原生写工具**：`raw_insert` / `raw_update` / `raw_touch` / `raw_delete` 自带事务；
 `build_raw_*` 只拼装（返回 `(语句, 参数)`），供 `with Kit.transaction() as session:` 内使用：
 
 ```python
@@ -844,12 +822,27 @@ await service.close()
 | 类 | 方法 |
 |----|------|
 | `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ...) -> AsyncIterator[str]` |
-| `EmbeddingService` | `embed_text(text) -> list[float]`、`embed_texts(texts, *, batch_size=None, concurrency=4) -> list[list[float]]`、`dimension` 属性 |
+| `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` |
 | `ModelBuilder` | `build(model_type, model=None, *, api_key=None)` 及各类型专用 `build_chat / build_embedding / build_rerank / build_image` |
 | `BaseAIService` | `profile` 属性、`await close()`、支持 `async with` |
 
+**embedding 维度契约**：`ai_models.json` 里 embedding 档案的 `dimension` 是**目标向量维度**
+（不是模型原生维度），`EmbeddingService` 保证输出恒等于它：
+
+| 模型返回维 vs `dimension` | 行为 |
+|---|---|
+| 相等 | 原样返回（不归一化，逐字节不变） |
+| 更大 | **截断到该维度并做 L2 归一化**（依赖模型的 MRL 支持；非 MRL 模型截断后质量会退化） |
+| 更小 | 抛 `AIResponseError`（降维只能变小，不能放大） |
+
+用途：让「建表维度 = 配置维度 = 输出维度」共用一个数值——
+`create_vector_table(t, dims)` 与 `vector_column_dimension(t, col)` 都取该配置值，
+换用原生维度更大的模型时无需重构向量列（换模型后需全量重新入库）。
+
+> ⚠ 启用候选链时，**链内各档案的 `dimension` 必须一致**：故障切换后输出维度跟随被选中档案的配置。
+
 ### 3. 异常
 
 ```python
@@ -943,6 +936,61 @@ CommonKit.format_current_time("yyyy-MM-dd")
 
 ---
 
+## kit.license_kit —— 离线授权签发与校验
+
+零第三方依赖（`cryptography` 已在 base），按需 import。校验链：签名 → 产品 → 机器码 → 有效期。
+
+```python
+from datetime import datetime, timezone
+from pathlib import Path
+
+from kit.license_kit import LicenseKit, LicensePayload, LicenseVerifier
+
+# 1. 生成密钥对（一次性；私钥自行保管，不随包分发）
+private_pem, public_pem = LicenseKit.generate_keypair()
+
+# 2. 取机器码（16 位十六进制；仅 Windows 支持）
+machine = LicenseKit.get_machine_code()
+LicenseKit.export_fingerprint_file(Path("fingerprint.txt"))   # 或导出文件交给签发方
+machine = LicenseKit.parse_fingerprint_file(Path("fingerprint.txt"))
+
+# 3. 签发（离线）
+payload = LicensePayload(
+    product="thinktank",
+    machine_code=machine,
+    tier="pro",
+    customer_id="C-0001",
+    expires_at=datetime(2027, 12, 31, tzinfo=timezone.utc),
+)
+token = LicenseKit.sign(payload, private_pem)
+
+# 4. 校验（应用启动 / 请求时）
+verifier = LicenseVerifier(public_pem, Path("license.json"))
+claims = verifier.verify(product="thinktank", machine_code=machine)
+print(claims.tier, claims.expires_at)
+```
+
+| 符号 | 说明 |
+|------|------|
+| `LicenseKit.generate_keypair() -> (str, str)` | 生成 Ed25519（私钥 PEM, 公钥 PEM） |
+| `LicenseKit.get_machine_code() -> str` | 本机机器码（16 位十六进制；⚠ 仅 Windows 平台） |
+| `LicenseKit.export_fingerprint_file(path) -> Path` | 导出机器指纹文件 |
+| `LicenseKit.parse_fingerprint_file(path) -> str` | 从指纹文件读回机器码 |
+| `LicenseKit.sign(payload, private_key_pem) -> str` | 签发授权 token |
+| `LicenseVerifier(public_key_pem, license_path)` | 构造验签器（绑定公钥与 license 文件） |
+| `LicenseVerifier.verify(*, product, machine_code, now=None) -> LicensePayload` | 全量校验并返回载荷；`now=None` 取 aware UTC，naive 按 UTC 解释 |
+| `LicenseVerifier.reverify() -> LicensePayload` | 用最近一次成功 `verify` 的上下文重新校验（文件被换会失败） |
+| `LicenseVerifier.file_signature` | 当前 license 文件的签名（属性） |
+
+`LicensePayload` 字段：`version` / `product` / `machine_code` / `tier` / `customer_id` /
+`issued_at` / `expires_at`。
+
+异常：`LicenseError`（基类）、`LicenseFormatError`、`LicenseSignatureError`、
+`LicenseProductMismatchError`、`LicenseMachineMismatchError`、`LicenseExpiredError`、
+`LicenseUnsupportedPlatformError`（非 Windows 取机器码时抛）。
+
+---
+
 ## kit.docs.anydoc_kit —— 文档转 Markdown
 
 安装：`pip install "sdpy-kit[anydoc]"`（支持 `.doc .docx .ppt .pptx .xls .xlsx .csv .pdf`）

{sdpy_kit-0.6.1 → sdpy_kit-0.6.3}/README.md

@@ -4,7 +4,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；内置审计字段自动填充（`created_*` / `updated_*` / `deleted`）与软删除查询过滤；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
-- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
 
 > 要求 Python 3.13+
 
@@ -18,6 +18,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
 | `kit.file_kit` | `FileKit` | 文件与目录读写、移动、遍历 | 无 |
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
+| `kit.license_kit` | `LicenseKit` / `LicenseVerifier` | Ed25519 离线授权：密钥对、机器码、签发、验签（签名 → 产品 → 机器码 → 有效期） | 无 |
 | `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
 | `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
@@ -111,7 +112,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.crawl.article_models`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.crawl.wx_article_kit`、`kit.crawl.web_article_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.crawl.article_models`、`kit.crawl.article_io`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.license_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -196,6 +197,21 @@ SQLITE_DB_PATH=./data/sqlite.db
 > `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
 > `LAYA_MODEL` / `LAYA_DEVICE` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
 
+**DeepSeek Search / Fetch** → `kit.crawl.deepseek_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `DEEPSEEK_API_KEY` | 无 | Search / Fetch 鉴权 Key（与模型对话共用同一套）；缺失时调用抛 `DeepSeekKitError` |
+| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API 基础地址 |
+| `DEEPSEEK_TIMEOUT` | `60`（1–600） | 单次 HTTP 请求超时（秒） |
+| `DEEPSEEK_MAX_RETRIES` | `2`（0–5） | 408 / 429 / 5xx 重试次数（不含首次请求）；其它 4xx 不重试 |
+
+**文章抓取长度自检** → `kit.crawl.wx_article_kit` / `web_article_kit` / `deepseek_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `CRAWL_MIN_CONTENT_CHARS` | `500`（≥0） | 正文短于该长度时写入 `warnings`（非致命，不改成功语义、不截断正文）；`0` 关闭该判据 |
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.docs.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -293,9 +309,9 @@ from kit import session_scope, transactional, DBError       # 等价
 | 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
 | 原生表 | `raw_insert(table_name, data, *, ignore_conflict=False) -> int` | 插入一行；`ignore_conflict=True` 幂等（PG/SQLite `ON CONFLICT DO NOTHING`、MySQL `INSERT IGNORE`） |
 | 原生表 | `raw_update(table_name, data, where, params=None) -> int` | 按 `where`（不含 `WHERE`）更新；启用审计填充时自动补 `updated_*` |
-| 原生表 | `raw_touch(table_name, where, params=None) -> int` | **0.6.0**：只刷新 `updated_*`（需先 `enable`；表无该列抛 `DBError`） |
-| 原生表 | `raw_delete(table_name, where, params=None) -> int` | **0.6.0**：条件删除（`where` 必填） |
-| 原生表 | `build_raw_insert / build_raw_update / build_raw_touch / build_raw_delete` | **0.6.0**：只拼装不执行，返回 `(语句, 参数)`，供**自有事务**内 `session.execute(*builder(...))` |
+| 原生表 | `raw_touch(table_name, where, params=None) -> int` | 只刷新 `updated_*`（需先 `enable`；表无该列抛 `DBError`） |
+| 原生表 | `raw_delete(table_name, where, params=None) -> int` | 条件删除（`where` 必填） |
+| 原生表 | `build_raw_insert / build_raw_update / build_raw_touch / build_raw_delete` | 只拼装不执行，返回 `(语句, 参数)`，供**自有事务**内 `session.execute(*builder(...))` |
 | 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
 | 事务 | `transaction()` | 事务上下文管理器，`with PgKit.transaction() as session:` |
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
@@ -359,6 +375,7 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 | `insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> int` | 批量插入向量（**自成一事务并提交**）；`ids=None` 时由 Kit 生成雪花 ID；接受 `list[list[float]]` 或二维 numpy 数组 |
 | `build_insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> list[tuple[str, list[dict]]]` | **只拼装、不执行、不管事务**：返回按列集分组的 `(SQL, 参数列表)`，供调用方在**自有事务**内写向量行（见「自有事务内写向量」） |
 | `search_vectors(table_name, query_vector, top_k=10, distance_type="L2", filter_sql=None, exact=True, id_col="id", column="embedding") -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；`exact=True`（默认）禁止近似加速；**MySQL 侧抛 `VectorNotSupportedError`** |
+| `vector_column_dimension(table_name, column="embedding") -> int \| None` | 查列**声明的维度**：PG 为精确维度（`vector(1024)`→1024）；MySQL 为**最大上限**（未指定维度落 `2048`）；SQLite 恒 `None`（无元数据）。列不存在 / 非向量列 / 无维度声明 → `None`，不抛异常。口径差异由 `VECTOR_CAPABILITIES["dimension_kind"]` 声明（`"exact"` / `"max"` / `None`） |
 | `vector_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
 
 **`id_col` / `column`（逃生口）**：让**自建 DDL 的向量表**也能读写/检索。需要复合主键、额外约束、
@@ -381,12 +398,17 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 | 默认 `distance_type` | `"L2"` | `"L2"`（三库统一，不按后端覆写） | `"L2"`（形参保留，调用即抛错） |
 | 非法取值 | 抛 `ValueError` | 抛 `ValueError` | `search_vectors` 抛 `VectorNotSupportedError` |
 | `distance` 口径 | `exact=True` 真值 L2 / `exact=False` 量化（×255） | 真实距离 | — |
-| 维度约束 | `CHECK`（仅新表；旧表靠方法内校验） | 强制（不匹配即报错；建表时回读比对） | 上限约束（超限报错） |
+| 维度约束 | `CHECK`（仅新表；旧表靠方法内校验） | 强制（不匹配即报错；建表时回读比对） | **上限**（`VECTOR(N)` 的 N 是最大维度，写入须 ≤ N，超限报 `1406 Data too long`） |
+| 维度查询 | 恒 `None`（无元数据） | 精确维度（`dimension_kind="exact"`） | 最大上限（`dimension_kind="max"`） |
 | `filter_sql` 与 `top_k` | **先过滤再取 top_k**（与 PG 一致） | **先过滤再取 top_k** | 不适用 |
 | 索引 | 无（精确路径为全表扫描） | kit 不建索引；**自建后须 `exact=False` 才会被使用** | 无法建（B-Tree 拒绝向量列） |
 
 > MySQL `DISTANCE()` / `VECTOR_DISTANCE()` 仅 HeatWave on OCI 与 MySQL AI 提供
 > （Community 实测报 `1305 FUNCTION ... does not exist`）；故 `MySqlKit` 只覆盖存储侧。
+>
+> 维度上限（插件侧实测 pgvector 0.8.7）：`vector` ≤ **16000** 维；hnsw / ivfflat 索引
+> ≤ **2000** 维；`halfvec` 表达式索引 ≤ **4000** 维。因此 **1024 维表可建 HNSW，
+> 2560 / 4096 维表建不了**。
 
 **主键与 id（三库统一）**：向量表主键均为 `BIGINT`（SQLite 用等价的 64 位 `INTEGER PRIMARY KEY`），
 **不使用数据库自增**；`ids=None` 时由 Kit 用 `CommonKit.generate_snowflake_id()` 生成雪花 ID
@@ -421,7 +443,11 @@ MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 PgKit.VECTOR_CAPABILITIES
 # {'store': True, 'search': True, 'exact': True,
 #  'distances': ('COSINE', 'L2', 'L1', 'DOT', 'SQUARED_L2'),
-#  'distance_kind': 'true', 'fast_distance_kind': 'true'}
+#  'distance_kind': 'true', 'fast_distance_kind': 'true',
+#  'dimension_kind': 'exact'}      # MySQL='max' / SQLite=None
+
+# 查询库列声明的维度（守卫「配置 vs 库列」用；查不到返回 None）
+PgKit.vector_column_dimension("images", "embedding")   # 384
 
 # 自建 DDL 的表：用 id_col / column 接入
 PgKit.execute("CREATE TABLE my_vec (vid BIGINT PRIMARY KEY, vec vector(384))")
@@ -429,57 +455,9 @@ PgKit.insert_vectors("my_vec", [[0.1] * 384], ids=[1], id_col="vid", column="vec
 PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 ```
 
-#### 0.2.2 行为变更（升级须知）
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B1 | `search_vectors` 新增 `exact: bool = True`，默认**精确** | SQLite 返回的 `distance` 由量化值（≈L2×255）变为**真值 L2**；需旧口径请显式 `exact=False` |
-| B2 | `filter_sql` 语义统一为**先过滤、再取 top_k** | 传 `filter_sql` 的调用返回值**变多/变全**（旧结果 ⊆ 新结果）；曾自行放大 `top_k` 兜底的调用可收紧 |
-| B3 | 默认 `distance_type` 由 `"COSINE"` 改为 `"L2"` | 依赖默认值的调用方请显式传 `distance_type="COSINE"` |
-| B4 | `create_vector_table` 的 `dims` **必填**，参数顺序为 `(table_name, dims, id_col, column, extra_cols)` | `create_vector_table("t")` 类调用需补维度；位置传 `id_col` 的调用改为关键字 |
-| B5 | MySQL 的 `search_vectors` 异常由 `NotImplementedError` 改为 `VectorNotSupportedError`（继承 `DBError`） | `except NotImplementedError` 需改为 `except VectorNotSupportedError`（或 `except DBError`） |
-
-> 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
-> `insert_vectors` 支持二维 numpy 数组与批量提交。
-
-#### 0.2.6 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| D1 | `prepare_statement` 的 `params` 支持**参数行列表**（`list[dict]`）：**原样返回该列表** → `session.execute(*prepare_statement(sql, params))` 即批量执行（executemany），与 `build_insert_vectors` 的返回形态直接对接；行键集不一致或行值含序列 → 本地可操作 `ValueError`（与 `execute` 批量形态**同一规则**） | 向后兼容：单字典 / `None` 形态行为不变；行列表形态**不做** `IN` 展开（与批量互斥） |
-| D1 | 文档：修正「自有事务」示例——0.2.5 的示例把 `build_insert_vectors` 返回的**行列表**传给了单字典形态，照抄会抛 `AttributeError: 'list' object has no attribute 'items'` | **纯文档缺陷修正**（0.2.5 示例照抄即崩） |
-| — | 文档：批量执行补充 `rowcount` 备注——忽略型写入（如 SQLite `INSERT OR IGNORE`）的冲突行不计入 `rowcount`（即 `rowcount` = 实际插入数；⚠ 仅 SQLite 实测） | 文档 |
-
-#### 0.2.5 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| — | 新增**模块级公共函数** `prepare_statement(sql, params=None) -> (语句, 归一化参数)`：供调用方在**自有事务**内执行原生 SQL（含 `IN :ids`），**调用方无须 import `sqlalchemy`**；与 `query` / `execute` 同一实现（单一事实源） | **纯新增**：`query` / `transaction` 的签名与行为**零变更**；共享方法数仍为 **24**（模块级函数不计入） |
-| — | `execute` 的 `params` 支持**字典列表**（executemany，同一语句 + N 行参数一次往返）；**空列表**不触库返回 `0` | 向后兼容：单字典 / `None` 形态行为不变；批量要求各行字典**键集一致**、行值为**标量**（与 `IN` 展开互斥），违规在本地抛可操作 `ValueError`（含行号），不触库 |
-| — | 文档：自有事务示例改用 `prepare_statement`（不再需要 `from sqlalchemy import text`）；补「批量执行」说明与约束 | 文档 |
-
-> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**（0.2.5 之前亦如此），
+> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**，
 > 请改用 `CAST(:name AS type)`。
 
-#### 0.2.4 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B4 | **入参自洽性校验**（`extra_data` 的键）：保留绑定名 `id` / `vec`、与 `id_col` / `column` 重复、不是合法标识符、`id_col == column` → 抛可操作的 `ValueError` | **唯一行为变更**：此前 SQLite 会**静默写坏数据**（如 `id` 列被覆盖）、PG/MySQL 报误导性错误；正常调用**零影响** |
-| — | 新增共享方法 `build_insert_vectors`（只拼装不执行，由 `BaseDbKit` 收敛 → 共享方法 23 → **24**） | 纯新增：可在**自有事务**内写向量行（见下） |
-| — | `create_vector_table` 的 `extra_cols` 支持 `{列名: 类型串}`（与 `create_raw_table` 同形） | 纯新增：既有 `[{"name","type"}]` 形态保留，两者产出 DDL 逐字一致 |
-| — | 后端差异收口：向量列占位符由 `VECTOR_PLACEHOLDER` 驱动（MySQL = `STRING_TO_VECTOR(:vec)`） | 内部整理：公开签名与行为不变 |
-| — | `SQLiteKit.insert_vectors` 的事务获取统一为 `transaction()`（与另两库同构） | 内部一致：行为等价（自成一事务并提交） |
-
-#### 0.2.3 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B6 | **`PgKit.get_table_info` 按数据库解析语义定位表**（`search_path` 解析到的那张表） | 多 schema 下同名表**不再混行**；单 schema / `public` 场景**无影响**；只接受非限定表名 |
-| — | `query` / `execute` 支持**列表参数**（`IN :ids`，三库通用） | 纯新增；`set`/`frozenset` 自动归一化为 `list` |
-| — | 新增 `SQLiteKit.encode_vector` / `decode_vector`（小端 float32） | 纯新增：可在自有事务内写向量表，见下 |
-| — | 导出面统一：`from kit.db import PgKit, MySqlKit, SQLiteKit, build_pg_url, …` | 纯新增；既有导出未删除/未改名 |
-
 **两段查询范式（推荐用法）**：`search_vectors` 只返回 `[{"id", "distance"}]`，载荷二次取回：
 
 ```python
@@ -594,7 +572,7 @@ AuditConfig.set_fields(None)  # 恢复默认
 - 写方法与 `query()` 手写 SQL 不追加过滤条件；`upsert` 的冲突回查跳过过滤。
 - `user_resolver` 返回 `None` / 空串或抛异常时跳过 `*_by` 填充，不影响写入。
 
-**原生写工具（0.6.0）**：`raw_insert` / `raw_update` / `raw_touch` / `raw_delete` 自带事务；
+**原生写工具**：`raw_insert` / `raw_update` / `raw_touch` / `raw_delete` 自带事务；
 `build_raw_*` 只拼装（返回 `(语句, 参数)`），供 `with Kit.transaction() as session:` 内使用：
 
 ```python
@@ -768,12 +746,27 @@ await service.close()
 | 类 | 方法 |
 |----|------|
 | `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ...) -> AsyncIterator[str]` |
-| `EmbeddingService` | `embed_text(text) -> list[float]`、`embed_texts(texts, *, batch_size=None, concurrency=4) -> list[list[float]]`、`dimension` 属性 |
+| `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` |
 | `ModelBuilder` | `build(model_type, model=None, *, api_key=None)` 及各类型专用 `build_chat / build_embedding / build_rerank / build_image` |
 | `BaseAIService` | `profile` 属性、`await close()`、支持 `async with` |
 
+**embedding 维度契约**：`ai_models.json` 里 embedding 档案的 `dimension` 是**目标向量维度**
+（不是模型原生维度），`EmbeddingService` 保证输出恒等于它：
+
+| 模型返回维 vs `dimension` | 行为 |
+|---|---|
+| 相等 | 原样返回（不归一化，逐字节不变） |
+| 更大 | **截断到该维度并做 L2 归一化**（依赖模型的 MRL 支持；非 MRL 模型截断后质量会退化） |
+| 更小 | 抛 `AIResponseError`（降维只能变小，不能放大） |
+
+用途：让「建表维度 = 配置维度 = 输出维度」共用一个数值——
+`create_vector_table(t, dims)` 与 `vector_column_dimension(t, col)` 都取该配置值，
+换用原生维度更大的模型时无需重构向量列（换模型后需全量重新入库）。
+
+> ⚠ 启用候选链时，**链内各档案的 `dimension` 必须一致**：故障切换后输出维度跟随被选中档案的配置。
+
 ### 3. 异常
 
 ```python
@@ -867,6 +860,61 @@ CommonKit.format_current_time("yyyy-MM-dd")
 
 ---
 
+## kit.license_kit —— 离线授权签发与校验
+
+零第三方依赖（`cryptography` 已在 base），按需 import。校验链：签名 → 产品 → 机器码 → 有效期。
+
+```python
+from datetime import datetime, timezone
+from pathlib import Path
+
+from kit.license_kit import LicenseKit, LicensePayload, LicenseVerifier
+
+# 1. 生成密钥对（一次性；私钥自行保管，不随包分发）
+private_pem, public_pem = LicenseKit.generate_keypair()
+
+# 2. 取机器码（16 位十六进制；仅 Windows 支持）
+machine = LicenseKit.get_machine_code()
+LicenseKit.export_fingerprint_file(Path("fingerprint.txt"))   # 或导出文件交给签发方
+machine = LicenseKit.parse_fingerprint_file(Path("fingerprint.txt"))
+
+# 3. 签发（离线）
+payload = LicensePayload(
+    product="thinktank",
+    machine_code=machine,
+    tier="pro",
+    customer_id="C-0001",
+    expires_at=datetime(2027, 12, 31, tzinfo=timezone.utc),
+)
+token = LicenseKit.sign(payload, private_pem)
+
+# 4. 校验（应用启动 / 请求时）
+verifier = LicenseVerifier(public_pem, Path("license.json"))
+claims = verifier.verify(product="thinktank", machine_code=machine)
+print(claims.tier, claims.expires_at)
+```
+
+| 符号 | 说明 |
+|------|------|
+| `LicenseKit.generate_keypair() -> (str, str)` | 生成 Ed25519（私钥 PEM, 公钥 PEM） |
+| `LicenseKit.get_machine_code() -> str` | 本机机器码（16 位十六进制；⚠ 仅 Windows 平台） |
+| `LicenseKit.export_fingerprint_file(path) -> Path` | 导出机器指纹文件 |
+| `LicenseKit.parse_fingerprint_file(path) -> str` | 从指纹文件读回机器码 |
+| `LicenseKit.sign(payload, private_key_pem) -> str` | 签发授权 token |
+| `LicenseVerifier(public_key_pem, license_path)` | 构造验签器（绑定公钥与 license 文件） |
+| `LicenseVerifier.verify(*, product, machine_code, now=None) -> LicensePayload` | 全量校验并返回载荷；`now=None` 取 aware UTC，naive 按 UTC 解释 |
+| `LicenseVerifier.reverify() -> LicensePayload` | 用最近一次成功 `verify` 的上下文重新校验（文件被换会失败） |
+| `LicenseVerifier.file_signature` | 当前 license 文件的签名（属性） |
+
+`LicensePayload` 字段：`version` / `product` / `machine_code` / `tier` / `customer_id` /
+`issued_at` / `expires_at`。
+
+异常：`LicenseError`（基类）、`LicenseFormatError`、`LicenseSignatureError`、
+`LicenseProductMismatchError`、`LicenseMachineMismatchError`、`LicenseExpiredError`、
+`LicenseUnsupportedPlatformError`（非 Windows 取机器码时抛）。
+
+---
+
 ## kit.docs.anydoc_kit —— 文档转 Markdown
 
 安装：`pip install "sdpy-kit[anydoc]"`（支持 `.doc .docx .ppt .pptx .xls .xlsx .csv .pdf`）

{sdpy_kit-0.6.1 → sdpy_kit-0.6.3}/kit/__init__.py

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

{sdpy_kit-0.6.1 → sdpy_kit-0.6.3}/kit/ai/embedding_service.py

@@ -19,6 +19,7 @@ Author: Clark Chang
 
 import asyncio
 import itertools
+import math
 import time
 from dataclasses import dataclass
 from typing import cast, override
@@ -48,12 +49,28 @@ class EmbeddingService(BaseAIService[EmbeddingRequest, list[list[float]]]):
 
     公网 API 有限流限速前提，通过分批 + 可选并发（信号量）控制压力。
     信号量在运行中的事件循环内惰性创建，避免构造期绑定循环的隐患。
+
+    **维度契约**：``profile.dimension`` 是**目标向量维度**（不是「模型原生维度」），
+    本服务保证输出恒等于它：
+
+    - 模型返回维 == ``dimension`` → 原样返回（零计算，逐字节不变）；
+    - 模型返回维 > ``dimension`` → **截断到该维度并做 L2 归一化**（依赖模型的 MRL
+      支持；非 MRL 模型截断后质量会退化）；
+    - 模型返回维 < ``dimension`` → 抛 `AIResponseError`（降维只能变小，不能放大）。
+
+    这样「建表维度 = 配置维度 = 输出维度」可由同一个配置值统一，
+    换模型（原生维度更大）时无需重构向量列。
+
+    ⚠ 候选链内各档案的 ``dimension`` 必须一致：故障切换后输出维度跟随
+    被选中档案的配置，不一致会导致同一业务表写入不同维度的向量。
     """
 
     def __init__(self, profile: ModelProfile) -> None:
         super().__init__(profile)
         if profile.dimension is None:
             raise ValueError(f"模型 {profile.model} 未配置 dimension，无法用于向量化")
+        # 仅用于「截断只提示一次」，不参与任何行为分支
+        self._truncate_logged = False
 
     @property
     def dimension(self) -> int:
@@ -62,6 +79,45 @@ class EmbeddingService(BaseAIService[EmbeddingRequest, list[list[float]]]):
             raise AIResponseError("dimension 在构造期已校验非空，不应缺失")
         return dim
 
+    def _fit_dimension(self, vector: list[float]) -> list[float]:
+        """把模型输出对齐到配置的目标维度
+
+        Args:
+            vector: 模型原始输出的向量
+
+        Returns:
+            目标维度的向量：等长时原样返回；超长时截断并 L2 归一化
+
+        Raises:
+            AIResponseError: 输出维度**不足**配置维度（无法放大），
+                或截断后前 N 维全为 0（无法归一化）
+        """
+        target = self.dimension
+        if len(vector) == target:
+            return vector
+        if len(vector) < target:
+            raise AIResponseError(
+                f"向量维度不足：模型 {self._profile.model} 返回 {len(vector)} 维，"
+                f"配置 dimension={target}。降维只能变小不能放大，"
+                f"请改用原生维度 >= {target} 的模型，"
+                f"或调低 dimension 并重建向量表（表内既有向量需重新入库）。"
+            )
+
+        head = vector[:target]
+        norm = math.sqrt(sum(value * value for value in head))
+        if norm == 0.0:
+            raise AIResponseError(
+                f"模型 {self._profile.model} 返回向量的前 {target} 维全为 0，"
+                f"无法按配置 dimension={target} 归一化；请检查模型输出是否正常。"
+            )
+        if not self._truncate_logged:
+            logger.info(
+                f"向量已按配置截断：{len(vector)} → {target} 维（含 L2 归一化）。"
+                f"截断依赖模型的 MRL 支持，非 MRL 模型质量会退化"
+            )
+            self._truncate_logged = True
+        return [value / norm for value in head]
+
     @override
     def _build_payload(self, request: EmbeddingRequest) -> JSONObject:
         return cast(
@@ -92,7 +148,7 @@ class EmbeddingService(BaseAIService[EmbeddingRequest, list[list[float]]]):
                         f"向量化响应 embedding 元素非法: {str(item)[:200]}"
                     )
                 floats.append(float(value))
-            vectors.append(floats)
+            vectors.append(self._fit_dimension(floats))
         return vectors
 
     async def embed_text(self, text: str) -> list[float]:

{sdpy_kit-0.6.1 → sdpy_kit-0.6.3}/kit/ai/profiles.py

@@ -71,7 +71,9 @@ class ModelProfile:
         timeout: 请求超时秒数
         max_tokens: 单次请求输出上限（chat 用；None 表示由 provider 默认值决定）
         retries: 5xx 重试次数（超时不重试，候选链切换才是有效重试）
-        dimension: 向量维度（仅 embedding 有效）
+        dimension: **目标**向量维度（仅 embedding 有效）。`EmbeddingService`
+            保证输出恒等于该值：模型原生维度更大时截断（含 L2 归一化），
+            更小时报错；建表与维度守卫均应以它为唯一来源
         batch_size: 单次请求最大文本数（仅 embedding 有效）
     """
 

{sdpy_kit-0.6.1 → sdpy_kit-0.6.3}/kit/ai/runner.py

@@ -784,9 +784,11 @@ class ReloadResult:
     Attributes:
         types: 实际重建的模型类型（全量重载为 4 类型的排序列表）
         embedding_model_changed: embedding 默认档案的 ``model`` 或
-            ``dimension`` 是否变化。已建向量库的维度与存量向量不会随
-            重载迁移，变化时调用方应评估是否需要重新入库
-            （kit 只上报不拦截——新建库场景下更换 embedding 是合法操作）
+            ``dimension`` 是否变化。``dimension`` 是**目标向量维度**
+            （`EmbeddingService` 保证输出等于它），故它变化会直接改变
+            输出维度；已建向量库的维度与存量向量不会随重载迁移，
+            变化时调用方应评估是否需要重新入库（kit 只上报不拦截——
+            新建库场景下更换 embedding 是合法操作）
         previous_embedding_model: 重载前 embedding 默认档案的 model
         current_embedding_model: 重载后 embedding 默认档案的 model
     """

{sdpy_kit-0.6.1 → sdpy_kit-0.6.3}/kit/db/mysql_kit.py

@@ -59,6 +59,8 @@ from __future__ import annotations
 - ``VECTOR_CAPABILITIES`` 已声明上述能力，调用方可 feature-detect 而无需 try/except。
 """
 
+import re
+
 from sqlalchemy import text
 
 from kit.config.log_config import get_default_logger
@@ -96,6 +98,7 @@ class MySqlKit(BaseDbKit):
         "distances": (),
         "distance_kind": None,
         "fast_distance_kind": None,
+        "dimension_kind": "max",  # VECTOR(N) 的 N 是「最大维度上限」，非必须相等
     }
 
     @classmethod
@@ -124,6 +127,45 @@ class MySqlKit(BaseDbKit):
 
     # ==================== 向量操作（MySQL 9.x 原生 VECTOR 类型） ====================
 
+    @classmethod
+    def vector_column_dimension(
+        cls, table_name: str, column: str = "embedding"
+    ) -> int | None:
+        """查询向量列的**声明维度上限**（MySQL 9.x 原生 ``VECTOR``）
+
+        Args:
+            table_name: 表名（当前连接的库内，即 ``DATABASE()``）
+            column: 向量列名（默认 ``embedding``）
+
+        Returns:
+            列声明的维度上限；列不存在或不是 ``VECTOR`` 类型时返回 ``None``
+
+        Note:
+            - MySQL 的 ``VECTOR(N)`` 是**上限语义**：写入维度 ≤ N 即可（实测 9.7.2：
+              ``VECTOR(1024)`` 写入 1024 维成功，写入 1025 维报 ``1406 Data too long``）。
+              故 ``VECTOR_CAPABILITIES["dimension_kind"] == "max"``，
+              **不能**用「配置维度 != 列值」判定不一致。
+            - 建表时未指定维度的 ``VECTOR`` 由服务端落为 ``vector(2048)``（实测 9.7.2），
+              因此本后端不存在「无维度」列，``None`` 只表示「列不是向量列」。
+            - 维度元数据只在 ``information_schema.COLUMNS.COLUMN_TYPE`` 里（形如
+              ``vector(1024)``），需按文本解析。
+        """
+        rows = cls.query(
+            "SELECT COLUMN_TYPE AS column_type "
+            "FROM information_schema.COLUMNS "
+            "WHERE TABLE_SCHEMA = DATABASE() "
+            "AND TABLE_NAME = :table_name "
+            "AND COLUMN_NAME = :column",
+            {"table_name": table_name, "column": column},
+        )
+        if not rows:
+            return None
+        value = rows[0]["column_type"]
+        if not isinstance(value, str):
+            return None
+        matched = re.fullmatch(r"vector\((\d+)\)", value.strip(), re.IGNORECASE)
+        return int(matched.group(1)) if matched else None
+
     @classmethod
     def _ensure_vector_supported(cls) -> None:
         """确保服务端支持 VECTOR 类型（需 MySQL 9.x）

{sdpy_kit-0.6.1 → sdpy_kit-0.6.3}/kit/db/pg_kit.py

@@ -27,7 +27,7 @@ from __future__ import annotations
 
 本类继承 BaseDbKit，复用全部共享实现（连接管理 / ORM / 原生 SQL / 原生表操作 /
 事务 / 表操作），并覆写 PostgreSQL 专属的 get_table_info，另提供基于 pgvector 的
-4 个向量方法（签名与 SQLiteKit / MySqlKit 完全一致）。
+5 个向量方法（签名与 SQLiteKit / MySqlKit 完全一致）。
 
 使用方式::
 
@@ -108,6 +108,7 @@ class PgKit(BaseDbKit):
         "distances": SUPPORTED_DISTANCE_TYPES,
         "distance_kind": "true",  # exact=True 与 False 下 distance 都是真值
         "fast_distance_kind": "true",  # 近似仅影响候选集（索引），数值仍是真值
+        "dimension_kind": "exact",  # vector_column_dimension 返回「必须相等」的精确维度
     }
 
     @classmethod
@@ -149,6 +150,48 @@ class PgKit(BaseDbKit):
 
     # ==================== 向量操作（pgvector） ====================
 
+    @classmethod
+    def vector_column_dimension(
+        cls, table_name: str, column: str = "embedding"
+    ) -> int | None:
+        """查询向量列的声明维度（pgvector 的 ``vector`` 类型）
+
+        Args:
+            table_name: 表名（**非限定名**，按 ``search_path`` 解析，与 `get_table_info` 同源）
+            column: 向量列名（默认 ``embedding``）
+
+        Returns:
+            列声明的维度；下列情况返回 ``None``：列不存在、不是 ``vector`` 类型、
+            建为**无维度**的 ``vector``
+
+        Note:
+            - pgvector 把维度存在 ``pg_attribute.atttypmod``，值**直接等于维度**
+              （实测 pgvector 0.8.7：``vector(1024)`` → 1024，无 varchar 那样的 +4 偏移）。
+            - 必须联 ``pg_type`` 校验类型名：``varchar(20)`` / ``numeric`` 等同样有
+              ``atttypmod``，不判类型会误报出维度。
+            - 本后端维度是**硬约束**（写入维度必须相等），故
+              ``VECTOR_CAPABILITIES["dimension_kind"] == "exact"``。
+            - 用 ``to_regclass()`` 定位（表不存在返回 NULL 而非报错）；
+              **不要**改用 ``CAST(:表名 AS regclass)``。
+        """
+        rows = cls.query(
+            "SELECT a.atttypmod AS typmod "
+            "FROM pg_attribute a "
+            "JOIN pg_type t ON t.oid = a.atttypid "
+            "WHERE a.attrelid = to_regclass(:table_name) "
+            "AND a.attname = :column "
+            "AND a.attnum > 0 "
+            "AND NOT a.attisdropped "
+            "AND t.typname = 'vector'",
+            {"table_name": table_name, "column": column},
+        )
+        if not rows:
+            return None
+        typmod = rows[0]["typmod"]
+        if not isinstance(typmod, int) or typmod <= 0:
+            return None
+        return typmod
+
     @classmethod
     def _ensure_vector_extension(cls) -> None:
         """确保 pgvector 扩展可用（缺失则尝试创建）

{sdpy_kit-0.6.1 → sdpy_kit-0.6.3}/kit/db/sqlite_kit.py

@@ -26,7 +26,7 @@ from __future__ import annotations
 业务代码无需管理 session/transaction，直接调用即可。
 
 本类继承 BaseDbKit，复用全部共享实现（连接管理 / ORM / 原生 SQL / 原生表操作 /
-事务 / 表操作），并额外提供基于 sqlite-vector 扩展的 4 个向量方法，以及 2 个
+事务 / 表操作），并额外提供基于 sqlite-vector 扩展的 5 个向量方法，以及 2 个
 **编码原语**（`encode_vector` / `decode_vector`，仅本后端具备）。
 
 使用方式::
@@ -98,6 +98,7 @@ class SQLiteKit(BaseDbKit):
         "distances": SUPPORTED_DISTANCE_TYPES,  # 支持的距离类型
         "distance_kind": "true",  # exact=True 时的 distance 口径
         "fast_distance_kind": "quantized_l2_x255",  # exact=False 时的 distance 口径
+        "dimension_kind": None,  # 无维度元数据，vector_column_dimension 恒返回 None
     }
 
     @classmethod
@@ -176,6 +177,33 @@ class SQLiteKit(BaseDbKit):
 
         return [float(x) for x in np.frombuffer(blob, dtype=_VECTOR_DTYPE)]
 
+    @classmethod
+    def vector_column_dimension(
+        cls, table_name: str, column: str = "embedding"
+    ) -> int | None:
+        """查询向量列的声明维度，**本后端恒返回 None**
+
+        Args:
+            table_name: 表名（未使用，仅为保持三库签名一致）
+            column: 向量列名（未使用，同上）
+
+        Returns:
+            恒为 ``None``
+
+        Note:
+            SQLite 没有向量类型，也没有维度元数据：`create_vector_table` 把维度落实为
+            ``CHECK (length(column) = dims * 4)``，写入时由数据库强制，但**查不出来**。
+
+            不解析 ``sqlite_master.sql`` 里的 CHECK 文本：列名转义、既有表无该约束、
+            文本格式都可能变形，反解不可靠。
+
+            守卫建议：维度约束已由 ``CHECK`` 承担（写入维度不符即报错），无需前置探测；
+            若确需提前校验，可读一行数据的 ``length(column) / 4`` 推断（空表无法推断）。
+
+            ``VECTOR_CAPABILITIES["dimension_kind"] is None`` 表明本后端不支持该查询。
+        """
+        return None
+
     @classmethod
     def create_vector_table(
         cls,