sdpy-kit 0.2.3__tar.gz → 0.2.4__tar.gz

{sdpy_kit-0.2.3 → sdpy_kit-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.3
+Version: 0.2.4
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -336,7 +336,7 @@ from kit.db import session_scope, transactional, DBError    # 推荐
 from kit import session_scope, transactional, DBError       # 等价
 ```
 
-### 1. 三个数据库 Kit（23 个共享方法 API 完全一致）
+### 1. 三个数据库 Kit（24 个共享方法 API 完全一致）
 
 | 类 | 导入 | 数据库 | extra |
 |----|------|--------|-------|
@@ -424,8 +424,9 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, dims, id_col="id", column="embedding", extra_cols=None) -> None` | 建含向量列的表；**`dims` 必填**（SQLite 用 `CHECK` 落实为数据库层约束；PG 硬约束并回读校验已存在表；MySQL 为上限语义） |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID；接受 `list[list[float]]` 或二维 numpy 数组 |
+| `create_vector_table(table_name, dims, id_col="id", column="embedding", extra_cols=None) -> None` | 建含向量列的表；**`dims` 必填**（SQLite 用 `CHECK` 落实为数据库层约束；PG 硬约束并回读校验已存在表；MySQL 为上限语义）。`extra_cols` 支持 `{列名: 类型串}`（推荐，与 `create_raw_table` 同形）与 `[{"name","type"}]` 两种形态 |
+| `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_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
 
@@ -510,6 +511,16 @@ PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 > 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
 > `insert_vectors` 支持二维 numpy 数组与批量提交。
 
+#### 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 变更
 
 | 编号 | 变更 | 影响 |
@@ -527,18 +538,40 @@ rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
                        {"ids": [h["id"] for h in hits]})   # IN 不保证顺序，需按 hits 重排
 ```
 
-**自有事务内写向量（SQLite）**：
+**自有事务内写向量（推荐：`build_insert_vectors` + `transaction()`）**：
 
 ```python
-conn = SQLiteKit.raw_connection()          # DBAPI 连接：位置参数 ? + 手工 commit
+from sqlalchemy import text
+
+with SQLiteKit.transaction() as session:          # 换成 PgKit / MySqlKit 写法相同
+    session.execute(text("INSERT INTO docs_item (id, title) VALUES (:id, :t)"),
+                    {"id": doc_id, "t": title})
+    for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas,
+                                                      id_col="rowid"):
+        session.execute(text(sql), params)
+# 正常退出统一提交；异常自动回滚（多处写入保持同一事务）
+```
+
+**SQLite 的 DBAPI 变体**（`raw_connection()` 支持 `:name` 命名参数）：
+
+```python
+conn = SQLiteKit.raw_connection()          # 调用方负责 commit / close
 try:
-    conn.execute("INSERT INTO item_vectors (id, embedding) VALUES (?, ?)",
-                 (item_id, SQLiteKit.encode_vector(vec)))
+    for sql, params in SQLiteKit.build_insert_vectors("item_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas):
+        conn.executemany(sql, params)
     conn.commit()
 finally:
     conn.close()
 ```
 
+> ⚠ 两点约束：① `build_insert_vectors` 输出为 `:name` 风格，**PG / MySQL 的原生 DBAPI 不支持**
+> （psycopg2 / pymysql 需 `%(name)s`），只能经 `transaction()` 的 session 执行；
+> ② SQLite 上**持有未提交写事务**时再调 kit 的**自提交**方法（如 `insert_vectors`）会因另一个连接
+> 拿不到写锁而失败（`OperationalError: database is locked`，约 **6.4s** 后才报错）——
+> 把写入并入**同一个** `transaction()`（如上）即可避免。
+
 > 相似度换算建议：SQLite 仅支持 L2，若向量入库前已**归一化**，则 `cos = 1 − L2²/2`；
 > PG 可直接用 `distance_type="COSINE"`。
 

{sdpy_kit-0.2.3 → sdpy_kit-0.2.4}/README.md

@@ -266,7 +266,7 @@ from kit.db import session_scope, transactional, DBError    # 推荐
 from kit import session_scope, transactional, DBError       # 等价
 ```
 
-### 1. 三个数据库 Kit（23 个共享方法 API 完全一致）
+### 1. 三个数据库 Kit（24 个共享方法 API 完全一致）
 
 | 类 | 导入 | 数据库 | extra |
 |----|------|--------|-------|
@@ -354,8 +354,9 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, dims, id_col="id", column="embedding", extra_cols=None) -> None` | 建含向量列的表；**`dims` 必填**（SQLite 用 `CHECK` 落实为数据库层约束；PG 硬约束并回读校验已存在表；MySQL 为上限语义） |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID；接受 `list[list[float]]` 或二维 numpy 数组 |
+| `create_vector_table(table_name, dims, id_col="id", column="embedding", extra_cols=None) -> None` | 建含向量列的表；**`dims` 必填**（SQLite 用 `CHECK` 落实为数据库层约束；PG 硬约束并回读校验已存在表；MySQL 为上限语义）。`extra_cols` 支持 `{列名: 类型串}`（推荐，与 `create_raw_table` 同形）与 `[{"name","type"}]` 两种形态 |
+| `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_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
 
@@ -440,6 +441,16 @@ PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 > 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
 > `insert_vectors` 支持二维 numpy 数组与批量提交。
 
+#### 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 变更
 
 | 编号 | 变更 | 影响 |
@@ -457,18 +468,40 @@ rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
                        {"ids": [h["id"] for h in hits]})   # IN 不保证顺序，需按 hits 重排
 ```
 
-**自有事务内写向量（SQLite）**：
+**自有事务内写向量（推荐：`build_insert_vectors` + `transaction()`）**：
 
 ```python
-conn = SQLiteKit.raw_connection()          # DBAPI 连接：位置参数 ? + 手工 commit
+from sqlalchemy import text
+
+with SQLiteKit.transaction() as session:          # 换成 PgKit / MySqlKit 写法相同
+    session.execute(text("INSERT INTO docs_item (id, title) VALUES (:id, :t)"),
+                    {"id": doc_id, "t": title})
+    for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas,
+                                                      id_col="rowid"):
+        session.execute(text(sql), params)
+# 正常退出统一提交；异常自动回滚（多处写入保持同一事务）
+```
+
+**SQLite 的 DBAPI 变体**（`raw_connection()` 支持 `:name` 命名参数）：
+
+```python
+conn = SQLiteKit.raw_connection()          # 调用方负责 commit / close
 try:
-    conn.execute("INSERT INTO item_vectors (id, embedding) VALUES (?, ?)",
-                 (item_id, SQLiteKit.encode_vector(vec)))
+    for sql, params in SQLiteKit.build_insert_vectors("item_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas):
+        conn.executemany(sql, params)
     conn.commit()
 finally:
     conn.close()
 ```
 
+> ⚠ 两点约束：① `build_insert_vectors` 输出为 `:name` 风格，**PG / MySQL 的原生 DBAPI 不支持**
+> （psycopg2 / pymysql 需 `%(name)s`），只能经 `transaction()` 的 session 执行；
+> ② SQLite 上**持有未提交写事务**时再调 kit 的**自提交**方法（如 `insert_vectors`）会因另一个连接
+> 拿不到写锁而失败（`OperationalError: database is locked`，约 **6.4s** 后才报错）——
+> 把写入并入**同一个** `transaction()`（如上）即可避免。
+
 > 相似度换算建议：SQLite 仅支持 L2，若向量入库前已**归一化**，则 `cos = 1 − L2²/2`；
 > PG 可直接用 `distance_type="COSINE"`。
 

{sdpy_kit-0.2.3 → sdpy_kit-0.2.4}/kit/__init__.py

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

{sdpy_kit-0.2.3 → sdpy_kit-0.2.4}/kit/db/base_db_kit.py

@@ -105,18 +105,30 @@ def to_vector_literal(vector: builtins.list[float]) -> str:
 
 
 def vector_insert_placeholders(
-    columns: builtins.list[str], id_col: str, column: str
+    columns: builtins.list[str],
+    id_col: str,
+    column: str,
+    vector_placeholder: str = ":vec",
 ) -> str:
-    """生成向量表 INSERT 的占位符串（供三个数据库 Kit 的 insert_vectors 共用）
+    """生成向量表 INSERT 的占位符串（供三个数据库 Kit 的 build_insert_vectors 共用）
 
-    绑定参数名与列名**解耦**：id 列固定为 ``:id``、向量列固定为 ``:vec``、
+    绑定参数名与列名**解耦**：id 列固定为 ``:id``、向量列固定为 ``vector_placeholder``、
     其余列用 ``:列名``。这样调用方覆写 ``id_col`` / ``column``（自建 DDL 场景）时，
     参数字典的键不受列名影响。
+
+    Args:
+        columns: 列名列表（按 INSERT 顺序）
+        id_col: id 列名 → ``:id``
+        column: 向量列名 → ``vector_placeholder``
+        vector_placeholder: 向量列的占位符文本（MySQL 传 ``"STRING_TO_VECTOR(:vec)"``）
+
+    ⚠ 内部符号（不在 ``kit.db.__all__``）：调用方请用
+    `BaseDbKit.build_insert_vectors`，无需关心绑定名。
     """
 
     def _one(name: str) -> str:
         if name == column:
-            return ":vec"
+            return vector_placeholder
         if name == id_col:
             return ":id"
         return f":{name}"
@@ -124,6 +136,54 @@ def vector_insert_placeholders(
     return ", ".join(_one(name) for name in columns)
 
 
+# 向量插入的内部保留绑定名（与 vector_insert_placeholders 的映射一一对应）
+_RESERVED_BIND_NAMES = frozenset({"id", "vec"})
+
+# 绑定参数名须为标识符：否则 SQLAlchemy 无法解析 `:name`（列名含空格等会得到
+# "A value is required for bind parameter" 这类无法定位的报错）
+_BIND_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _check_extra_key(key: str, id_col: str, column: str) -> None:
+    """校验 ``extra_data`` 的键可作为绑定参数名（拼装前抛出可操作的 ``ValueError``）
+
+    三类问题（均实测）：
+    ① 保留绑定名 ``id`` / ``vec`` → ``params`` 被覆盖，SQLite 静默写坏数据；
+    ② 与 ``id_col`` / ``column`` 重复 → SQLite 接受重复列名并丢弃调用方给的值；
+    ③ 不是合法标识符 → 报错无法定位（"A value is required for bind parameter"）。
+    """
+    if key in _RESERVED_BIND_NAMES:
+        raise ValueError(
+            f"extra_data 含保留绑定名 {key!r}：向量插入的内部绑定名固定为 "
+            f"'id'（id 列）与 'vec'（向量列），同名业务列会覆盖它们；"
+            f"请重命名该键，或改用自定义 SQL（配合 Kit.transaction()）"
+        )
+    if key in (id_col, column):
+        raise ValueError(
+            f"extra_data 含重复列 {key!r}：该列已由 id_col / column 覆盖"
+        )
+    if not _BIND_NAME_RE.match(key):
+        raise ValueError(
+            f"extra_data 的键 {key!r} 不是合法标识符，无法生成绑定参数名"
+        )
+
+
+def normalize_extra_cols(
+    extra_cols: dict[str, str] | builtins.list[dict[str, str]] | None,
+) -> builtins.list[tuple[str, str]]:
+    """归一化 ``create_vector_table`` 的额外列定义（两种入参形态）
+
+    接受 ``{列名: 方言类型串}``（推荐，与 `create_raw_table` 同形，**键序即 DDL 列序**）
+    或既有 ``[{"name": ..., "type": ...}]``；空值返回空列表。
+    两种形态产出**逐字一致**的 DDL。
+    """
+    if not extra_cols:
+        return []
+    if isinstance(extra_cols, dict):
+        return [(name, col_type) for name, col_type in extra_cols.items()]
+    return [(col["name"], col["type"]) for col in extra_cols]
+
+
 def generate_snowflake_ids(count: int) -> builtins.list[int]:
     """生成 count 个雪花 ID（int64；当前 18 位，上限 19 位）
 
@@ -190,6 +250,112 @@ class BaseDbKit(ABC):
     # 数据库类型标识（postgresql / mysql / sqlite），由子类覆写
     DB_TYPE: str
 
+    # 向量列的占位符（后端覆写点）：MySQL 需经 STRING_TO_VECTOR 转换
+    VECTOR_PLACEHOLDER: str = ":vec"
+
+    # ==================== 向量写入的共享构造（只拼装，不执行） ====================
+
+    @classmethod
+    def _vector_param(cls, vector: builtins.list[float]) -> object:
+        """向量 → 绑定参数值（**私有钩子**，子类覆写；基类=文本字面量）
+
+        PostgreSQL（pgvector）与 MySQL（``STRING_TO_VECTOR``）共用文本字面量；
+        `SQLiteKit` 覆写为 float32 小端字节。
+        """
+        return to_vector_literal(vector)
+
+    @classmethod
+    def build_insert_vectors(
+        cls,
+        table_name: str,
+        vectors: builtins.list[builtins.list[float]],
+        ids: builtins.list[int] | None = None,
+        extra_data: builtins.list[dict[str, object]] | None = None,
+        id_col: str = "id",
+        column: str = "embedding",
+    ) -> builtins.list[tuple[str, builtins.list[dict[str, object]]]]:
+        """构造向量表 INSERT 语句（**只拼装、不执行、不管事务**）
+
+        供调用方在**自己的事务**内写入向量行（与其它表行同事务提交）::
+
+            with SQLiteKit.transaction() as session:
+                session.execute(text("INSERT INTO docs_item (...) VALUES (...)"), {...})
+                for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors",
+                                                                  vectors, ids=[...],
+                                                                  id_col="rowid"):
+                    session.execute(text(sql), params)
+
+        Args:
+            table_name: 表名
+            vectors: 向量列表，每个向量为 float 列表（也接受二维 numpy 数组）
+            ids: 可选的 ID 列表（长度需与 vectors 一致）；None 时由 Kit 生成雪花 ID
+                （生成值可从返回的参数列表读取）
+            extra_data: 额外列数据列表（长度需与 vectors 一致）
+            id_col: 主键列名（默认 ``id``，供自建 DDL 的表使用）
+            column: 向量列名（默认 ``embedding``，供自建 DDL 的表使用）
+
+        Returns:
+            按**列集分组**的 ``[(SQL, 参数列表), ...]``：同列集的行合并为一条可
+            ``executemany`` 的语句（常规同构 ``extra_data`` 只返回 1 条）。SQL 为
+            SQLAlchemy ``text()`` 风格（``:id`` / ``:vec`` / ``:列名``）。
+
+        Raises:
+            ValueError: 入参自洽性校验失败——长度/维度不一致、``extra_data`` 键为保留绑定名
+                （``id`` / ``vec``）或与 ``id_col`` / ``column`` 重复、键不是合法标识符、
+                ``id_col == column``
+
+        Note:
+            - **无副作用**：不建连接、不接触数据库、不改任何状态；对**不存在的表**也正常返回。
+            - **执行载体**：SQLite 可直接在 ``raw_connection()``（DBAPI 支持 ``:name``）或
+              ``transaction()`` 上执行；**PG / MySQL 的原生 DBAPI 不支持 ``:name``**
+              （psycopg2 / pymysql 需 ``%(name)s``），须经 ``Kit.transaction()`` 的 session 执行。
+            - ``insert_vectors`` 的执行语义即"本方法 + 自带事务"，两者共用同一份拼装逻辑。
+        """
+        if id_col == column:
+            raise ValueError(f"id_col 与 column 不能同名（当前均为 {id_col!r}）")
+        # 用 len() 而非真值判断：入参可为 list 或二维 numpy 数组
+        if len(vectors) == 0:
+            return []
+        if ids is None:
+            ids = generate_snowflake_ids(len(vectors))
+        if len(ids) != len(vectors):
+            raise ValueError("ids 长度必须与 vectors 一致")
+        if extra_data is not None and len(extra_data) != len(vectors):
+            raise ValueError("extra_data 长度必须与 vectors 一致")
+
+        dims = len(vectors[0])
+        if any(len(vec) != dims for vec in vectors):
+            raise ValueError(
+                f"同一批次的向量长度必须一致（首个向量 {dims} 维，存在其它维度的向量）"
+            )
+
+        # 按「列集合」分组：executemany 要求同一语句的参数列表**键集一致**
+        groups: dict[tuple[str, ...], builtins.list[dict[str, object]]] = {}
+        for i, vector in enumerate(vectors):
+            columns: builtins.list[str] = [id_col, column]
+            params: dict[str, object] = {"id": ids[i], "vec": cls._vector_param(vector)}
+            if extra_data is not None:
+                for key, value in extra_data[i].items():
+                    _check_extra_key(key, id_col, column)
+                    columns.append(key)
+                    params[key] = value
+            groups.setdefault(tuple(columns), []).append(params)
+
+        statements: builtins.list[tuple[str, builtins.list[dict[str, object]]]] = []
+        for columns_tuple, params_list in groups.items():
+            columns_list = list(columns_tuple)
+            placeholders = vector_insert_placeholders(
+                columns_list, id_col, column, cls.VECTOR_PLACEHOLDER
+            )
+            statements.append(
+                (
+                    f"INSERT INTO {table_name} ({', '.join(columns_list)}) "
+                    f"VALUES ({placeholders})",
+                    params_list,
+                )
+            )
+        return statements
+
     # ==================== 连接管理 ====================
 
     @classmethod

{sdpy_kit-0.2.3 → sdpy_kit-0.2.4}/kit/db/mysql_kit.py

@@ -65,8 +65,7 @@ from kit.config.log_config import get_default_logger
 from kit.db.base_db_kit import (
     DEFAULT_DISTANCE_TYPE,
     BaseDbKit,
-    generate_snowflake_ids,
-    to_vector_literal,
+    normalize_extra_cols,
 )
 from kit.db.engine import MYSQL
 from kit.db.exceptions import DBError, VectorNotSupportedError
@@ -86,6 +85,9 @@ class MySqlKit(BaseDbKit):
 
     DB_TYPE = MYSQL
 
+    # 向量列占位符：本后端 VECTOR 列需经 STRING_TO_VECTOR 转换（覆写基类的 ":vec"）
+    VECTOR_PLACEHOLDER = "STRING_TO_VECTOR(:vec)"
+
     # 向量能力声明（供调用方 feature-detect，详见 docs/agents/modules/kit-db.md）
     VECTOR_CAPABILITIES: dict[str, object] = {
         "store": True,  # 可建表 / 可写入
@@ -151,7 +153,7 @@ class MySqlKit(BaseDbKit):
         dims: int,
         id_col: str = "id",
         column: str = "embedding",
-        extra_cols: list[dict[str, str]] | None = None,
+        extra_cols: dict[str, str] | list[dict[str, str]] | None = None,
     ) -> None:
         """创建包含向量列的表（MySQL 9.x 原生 VECTOR 类型）
 
@@ -161,8 +163,10 @@ class MySqlKit(BaseDbKit):
             id_col: 主键列名（``BIGINT PRIMARY KEY``，**不自增**，id 由调用方提供
                 或由 `insert_vectors` 兜底生成雪花 ID）
             column: 向量列名（默认 ``embedding``）
-            extra_cols: 额外列定义，每项为 {"name": str, "type": str}，
-                type 按 MySQL 方言书写，如 [{"name": "label", "type": "VARCHAR(32)"}]
+            extra_cols: 额外列定义，**两种形态**（产出 DDL 逐字一致）：
+                ``{列名: 方言类型串}``（**推荐**，与 `create_raw_table` 同形，键序即列序）
+                或既有 ``[{"name": str, "type": str}]``；
+                type 按 MySQL 方言书写，如 ``{"label": "VARCHAR(32)"}``
 
         表结构示例::
 
@@ -187,11 +191,10 @@ class MySqlKit(BaseDbKit):
 
         cls._ensure_vector_supported()
 
-        extra_defs = ""
-        if extra_cols:
-            extra_defs = ", " + ", ".join(
-                f"{col['name']} {col['type']}" for col in extra_cols
-            )
+        extra_defs = "".join(
+            f", {name} {col_type}"
+            for name, col_type in normalize_extra_cols(extra_cols)
+        )
 
         sql = (
             f"CREATE TABLE IF NOT EXISTS {table_name} ("
@@ -227,63 +230,28 @@ class MySqlKit(BaseDbKit):
             插入的行数
 
         Raises:
-            ValueError: ids / extra_data 长度与 vectors 不一致，或批内向量长度不一致
+            ValueError: 入参自洽性校验失败——ids / extra_data 长度与 vectors 不一致、
+                批内向量长度不一致、``extra_data`` 键为保留绑定名（``id`` / ``vec``）、
+                键与 ``id_col`` / ``column`` 重复、键不是合法标识符、``id_col == column``
 
         Note:
-            单次事务内批量写入（与 SQLiteKit / PgKit 同语义：整体提交）；
-            ``extra_data=None`` 时走批量提交（pymysql 会合并为多值 INSERT）。
+            单次事务内批量写入（``cls.transaction()``，与 SQLiteKit / PgKit 同语义：整体提交）；
+            语句由 `build_insert_vectors` 构造（**单一事实源**，本后端经 ``VECTOR_PLACEHOLDER``
+            输出 ``STRING_TO_VECTOR(:vec)``）。需要把向量行写入**调用方自己的事务**时，
+            请改用 `build_insert_vectors` + `transaction()`。
         """
-        # 用 len() 而非真值判断：入参可为 list 或二维 numpy 数组
-        if len(vectors) == 0:
-            return 0
-        if ids is None:
-            ids = generate_snowflake_ids(len(vectors))
-        if len(ids) != len(vectors):
-            raise ValueError("ids 长度必须与 vectors 一致")
-        if extra_data is not None and len(extra_data) != len(vectors):
-            raise ValueError("extra_data 长度必须与 vectors 一致")
-
-        dims = len(vectors[0])
-        if any(len(vec) != dims for vec in vectors):
-            raise ValueError(
-                f"同一批次的向量长度必须一致（首个向量 {dims} 维，存在其它维度的向量）"
-            )
-
-        def _placeholder(name: str) -> str:
-            """列名 → 占位符：向量列需经 STRING_TO_VECTOR 转换（本后端特有）"""
-            if name == column:
-                return "STRING_TO_VECTOR(:vec)"
-            if name == id_col:
-                return ":id"
-            return f":{name}"
-
-        # 按「列集合」分组：键集相同的行才能共用同一条批量语句（executemany）
-        groups: dict[tuple[str, ...], list[dict[str, object]]] = {}
-        for i, vector in enumerate(vectors):
-            columns: list[str] = [id_col, column]
-            params: dict[str, object] = {
-                "id": ids[i],
-                "vec": to_vector_literal(vector),
-            }
-
-            if extra_data is not None:
-                for key, value in extra_data[i].items():
-                    columns.append(key)
-                    params[key] = value
-
-            groups.setdefault(tuple(columns), []).append(params)
-
         with cls.transaction() as session:
-            for columns, params_list in groups.items():
-                placeholders = ", ".join(_placeholder(name) for name in columns)
-                sql = (
-                    f"INSERT INTO {table_name} ({', '.join(columns)}) "
-                    f"VALUES ({placeholders})"
-                )
-                session.execute(text(sql), params_list)
-
-            logger.info(f"✅ 插入 {len(vectors)} 条向量到 {table_name}")
-            return len(vectors)
+            for sql, params in cls.build_insert_vectors(
+                table_name,
+                vectors,
+                ids=ids,
+                extra_data=extra_data,
+                id_col=id_col,
+                column=column,
+            ):
+                session.execute(text(sql), params)
+        logger.info(f"✅ 插入 {len(vectors)} 条向量到 {table_name}")
+        return len(vectors)
 
     @classmethod
     def search_vectors(

{sdpy_kit-0.2.3 → sdpy_kit-0.2.4}/kit/db/pg_kit.py

@@ -67,9 +67,8 @@ from kit.config.log_config import get_default_logger
 from kit.db.base_db_kit import (
     DEFAULT_DISTANCE_TYPE,
     BaseDbKit,
-    generate_snowflake_ids,
+    normalize_extra_cols,
     to_vector_literal,
-    vector_insert_placeholders,
 )
 from kit.db.engine import POSTGRESQL, get_engine
 from kit.db.exceptions import DBError
@@ -177,7 +176,7 @@ class PgKit(BaseDbKit):
         dims: int,
         id_col: str = "id",
         column: str = "embedding",
-        extra_cols: list[dict[str, str]] | None = None,
+        extra_cols: dict[str, str] | list[dict[str, str]] | None = None,
     ) -> None:
         """创建包含向量列的表（pgvector）
 
@@ -187,8 +186,10 @@ class PgKit(BaseDbKit):
             id_col: 主键列名（``BIGINT PRIMARY KEY``，**不自增**，id 由调用方提供
                 或由 `insert_vectors` 兜底生成雪花 ID）
             column: 向量列名（默认 ``embedding``）
-            extra_cols: 额外列定义，每项为 {"name": str, "type": str}，
-                type 按 PostgreSQL 方言书写，如 [{"name": "label", "type": "TEXT"}]
+            extra_cols: 额外列定义，**两种形态**（产出 DDL 逐字一致）：
+                ``{列名: 方言类型串}``（**推荐**，与 `create_raw_table` 同形，键序即列序）
+                或既有 ``[{"name": str, "type": str}]``；
+                type 按 PostgreSQL 方言书写，如 ``{"label": "TEXT"}``
 
         内部自动执行 ``CREATE EXTENSION IF NOT EXISTS vector``（需相应权限）。
 
@@ -214,11 +215,10 @@ class PgKit(BaseDbKit):
 
         cls._ensure_vector_extension()
 
-        extra_defs = ""
-        if extra_cols:
-            extra_defs = ", " + ", ".join(
-                f"{col['name']} {col['type']}" for col in extra_cols
-            )
+        extra_defs = "".join(
+            f", {name} {col_type}"
+            for name, col_type in normalize_extra_cols(extra_cols)
+        )
 
         sql = (
             f"CREATE TABLE IF NOT EXISTS {table_name} ("
@@ -271,55 +271,27 @@ class PgKit(BaseDbKit):
             插入的行数
 
         Raises:
-            ValueError: ids / extra_data 长度与 vectors 不一致，或批内向量长度不一致
+            ValueError: 入参自洽性校验失败——ids / extra_data 长度与 vectors 不一致、
+                批内向量长度不一致、``extra_data`` 键为保留绑定名（``id`` / ``vec``）、
+                键与 ``id_col`` / ``column`` 重复、键不是合法标识符、``id_col == column``
 
         Note:
-            单次事务内批量写入（与 SQLiteKit / MySqlKit 同语义：整体提交）；
-            ``extra_data=None`` 时走驱动级批量提交（executemany）。
+            单次事务内批量写入（``cls.transaction()``，与 SQLiteKit / MySqlKit 同语义：整体提交）；
+            语句由 `build_insert_vectors` 构造（**单一事实源**）。需要把向量行写入**调用方自己的事务**时，
+            请改用 `build_insert_vectors` + `transaction()`。
         """
-        # 用 len() 而非真值判断：入参可为 list 或二维 numpy 数组
-        if len(vectors) == 0:
-            return 0
-        if ids is None:
-            ids = generate_snowflake_ids(len(vectors))
-        if len(ids) != len(vectors):
-            raise ValueError("ids 长度必须与 vectors 一致")
-        if extra_data is not None and len(extra_data) != len(vectors):
-            raise ValueError("extra_data 长度必须与 vectors 一致")
-
-        dims = len(vectors[0])
-        if any(len(vec) != dims for vec in vectors):
-            raise ValueError(
-                f"同一批次的向量长度必须一致（首个向量 {dims} 维，存在其它维度的向量）"
-            )
-
-        # 按「列集合」分组：键集相同的行才能共用同一条批量语句（executemany）
-        groups: dict[tuple[str, ...], list[dict[str, object]]] = {}
-        for i, vector in enumerate(vectors):
-            columns: list[str] = [id_col, column]
-            params: dict[str, object] = {
-                "id": ids[i],
-                "vec": to_vector_literal(vector),
-            }
-
-            if extra_data is not None:
-                for key, value in extra_data[i].items():
-                    columns.append(key)
-                    params[key] = value
-
-            groups.setdefault(tuple(columns), []).append(params)
-
         with cls.transaction() as session:
-            for columns, params_list in groups.items():
-                placeholders = vector_insert_placeholders(list(columns), id_col, column)
-                sql = (
-                    f"INSERT INTO {table_name} ({', '.join(columns)}) "
-                    f"VALUES ({placeholders})"
-                )
-                session.execute(text(sql), params_list)
-
-            logger.info(f"✅ 插入 {len(vectors)} 条向量到 {table_name}")
-            return len(vectors)
+            for sql, params in cls.build_insert_vectors(
+                table_name,
+                vectors,
+                ids=ids,
+                extra_data=extra_data,
+                id_col=id_col,
+                column=column,
+            ):
+                session.execute(text(sql), params)
+        logger.info(f"✅ 插入 {len(vectors)} 条向量到 {table_name}")
+        return len(vectors)
 
     @classmethod
     def search_vectors(

{sdpy_kit-0.2.3 → sdpy_kit-0.2.4}/kit/db/sqlite_kit.py

@@ -59,8 +59,7 @@ from kit.config.log_config import get_default_logger
 from kit.db.base_db_kit import (
     DEFAULT_DISTANCE_TYPE,
     BaseDbKit,
-    generate_snowflake_ids,
-    vector_insert_placeholders,
+    normalize_extra_cols,
 )
 from kit.db.engine import SQLITE, get_engine
 from kit.db.exceptions import DBError
@@ -124,6 +123,11 @@ class SQLiteKit(BaseDbKit):
 
     # ==================== 向量操作 ====================
 
+    @classmethod
+    def _vector_param(cls, vector: list[float]) -> object:
+        """向量 → BLOB（小端 float32）；覆写基类的文本字面量实现"""
+        return cls.encode_vector(vector)
+
     @classmethod
     def encode_vector(cls, vector: list[float]) -> bytes:
         """把向量编码为 sqlite-vector 使用的 float32 **小端** BLOB（4 字节/维）
@@ -179,7 +183,7 @@ class SQLiteKit(BaseDbKit):
         dims: int,
         id_col: str = "id",
         column: str = "embedding",
-        extra_cols: list[dict[str, str]] | None = None,
+        extra_cols: dict[str, str] | list[dict[str, str]] | None = None,
     ) -> None:
         """创建包含向量列的表
 
@@ -190,8 +194,10 @@ class SQLiteKit(BaseDbKit):
                 等价于另两库的 ``BIGINT``；id 由调用方提供或由 `insert_vectors`
                 兜底生成雪花 ID）。须为 rowid 别名，见 `search_vectors` 的 Note
             column: 向量列名（默认 ``embedding``）
-            extra_cols: 额外列定义，每项为 {"name": str, "type": str}，
-                如 [{"name": "label", "type": "TEXT"}]
+            extra_cols: 额外列定义，**两种形态**（产出 DDL 逐字一致）：
+                ``{列名: 方言类型串}``（**推荐**，与 `create_raw_table` 同形，键序即列序）
+                或既有 ``[{"name": str, "type": str}]``；
+                如 ``{"label": "TEXT"}``
 
         表结构示例::
 
@@ -212,11 +218,10 @@ class SQLiteKit(BaseDbKit):
         if dims < 1:
             raise ValueError(f"dims 必须为正整数，当前为 {dims}")
 
-        extra_defs = ""
-        if extra_cols:
-            extra_defs = ", " + ", ".join(
-                f"{c['name']} {c['type']}" for c in extra_cols
-            )
+        extra_defs = "".join(
+            f", {name} {col_type}"
+            for name, col_type in normalize_extra_cols(extra_cols)
+        )
 
         sql = f"""
         CREATE TABLE IF NOT EXISTS {table_name} (
@@ -253,56 +258,29 @@ class SQLiteKit(BaseDbKit):
             插入的行数
 
         Raises:
-            ValueError: ids / extra_data 长度与 vectors 不一致，或批内向量长度不一致
+            ValueError: 入参自洽性校验失败——ids / extra_data 长度与 vectors 不一致、
+                批内向量长度不一致、``extra_data`` 键为保留绑定名（``id`` / ``vec``）、
+                键与 ``id_col`` / ``column`` 重复、键不是合法标识符、``id_col == column``
 
         Note:
             - `ids=None` 时**不使用 SQLite rowid 自增**，改由 Kit 生成雪花 ID
               （64 位，18~19 位数字），与 PgKit / MySqlKit 语义一致。
-            - 单次事务内批量写入；``extra_data=None`` 时走驱动级批量提交（executemany）。
+            - 单次事务内批量写入（``cls.transaction()``）；语句由 `build_insert_vectors`
+              构造（**单一事实源**）。需要把向量行写入**调用方自己的事务**时，请改用
+              `build_insert_vectors` + `transaction()`，或 `raw_connection()`（见文档 cookbook）。
         """
-        # 用 len() 而非真值判断：入参可为 list 或二维 numpy 数组
-        if len(vectors) == 0:
-            return 0
-        if ids is None:
-            ids = generate_snowflake_ids(len(vectors))
-        if len(ids) != len(vectors):
-            raise ValueError("ids 长度必须与 vectors 一致")
-        if extra_data is not None and len(extra_data) != len(vectors):
-            raise ValueError("extra_data 长度必须与 vectors 一致")
-
-        dims = len(vectors[0])
-        if any(len(vec) != dims for vec in vectors):
-            raise ValueError(
-                f"同一批次的向量长度必须一致（首个向量 {dims} 维，存在其它维度的向量）"
-            )
-
-        engine = get_engine(cls.DB_TYPE)
-
-        # 按「列集合」分组：键集相同的行才能共用同一条批量语句（executemany）
-        groups: dict[tuple[str, ...], list[dict[str, object]]] = {}
-        for i, vec in enumerate(vectors):
-            vec_bytes = cls.encode_vector(vec)
-            columns: list[str] = [id_col, column]
-            params: dict[str, object] = {"id": ids[i], "vec": vec_bytes}
-
-            if extra_data is not None:
-                for key, value in extra_data[i].items():
-                    columns.append(key)
-                    params[key] = value
-
-            groups.setdefault(tuple(columns), []).append(params)
-
-        with engine.connect() as conn:
-            for columns, params_list in groups.items():
-                placeholders = vector_insert_placeholders(list(columns), id_col, column)
-                sql = (
-                    f"INSERT INTO {table_name} ({', '.join(columns)}) "
-                    f"VALUES ({placeholders})"
-                )
-                conn.execute(text(sql), params_list)
-            conn.commit()
-            logger.info(f"✅ 插入 {len(vectors)} 条向量到 {table_name}")
-            return len(vectors)
+        with cls.transaction() as session:
+            for sql, params in cls.build_insert_vectors(
+                table_name,
+                vectors,
+                ids=ids,
+                extra_data=extra_data,
+                id_col=id_col,
+                column=column,
+            ):
+                session.execute(text(sql), params)
+        logger.info(f"✅ 插入 {len(vectors)} 条向量到 {table_name}")
+        return len(vectors)
 
     @classmethod
     def _vector_dims(cls, table_name: str, column: str, conn: Connection) -> int | None: