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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.1
+Version: 0.2.3
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -370,13 +370,23 @@ from kit import session_scope, transactional, DBError       # 等价
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
 | 表 | `table_exists(table_name) -> bool` | 判断表是否存在 |
 | 表 | `create_tables(models) -> None` | 按模型列表建表 |
-| 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（三个 Kit 各自实现） |
+| 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（按列序；公共键 4 个：`column_name`/`data_type`/`is_nullable`/`column_default`） |
+
+> **列表参数（`IN`）**：`query` / `execute` 的 `params` 中值为 `list`/`tuple`/`set`/`frozenset`
+> 时按 `IN` 展开，可直接写 `WHERE id IN :ids`（三库通用）。`IN` **不保证顺序**；参数列表过大
+> 应分批（PG 单语句上限 65535 参数）。
+>
+> **`LIKE` 的方言差异**：SQLite 对 ASCII 不区分大小写，PostgreSQL 区分（用 `ILIKE`）；
+> 跨库一致写法：`LOWER(col) LIKE LOWER(:pattern)`。
+>
+> **导出面**：`from kit.db import PgKit, SQLiteKit, build_pg_url, to_vector_literal, …`
+> （`kit` 顶层与 `kit.db` 导出同一套符号）。
 
 ```python
 from sqlalchemy import BigInteger
 from sqlmodel import SQLModel, Field
 from kit.common_kit import CommonKit
-from kit.db.sqlite_kit import SQLiteKit
+from kit.db import SQLiteKit          # 也可 from kit.db.sqlite_kit import SQLiteKit
 
 class User(SQLModel, table=True):
     # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
@@ -393,6 +403,7 @@ users = SQLiteKit.list(User, skip=0, limit=10, order_by="id", desc=True)
 
 rows = SQLiteKit.query("SELECT * FROM user WHERE name = :name", {"name": "李四"})
 affected = SQLiteKit.execute("UPDATE user SET name = '王五' WHERE id = :id", {"id": user.id})
+rows = SQLiteKit.query("SELECT * FROM user WHERE id IN :ids", {"ids": [1, 2, 3]})   # 列表参数
 
 with SQLiteKit.transaction() as session:                  # 多操作原子提交
     SQLiteKit.create(User, {"name": "批量一"})
@@ -400,8 +411,9 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
-> 注意两点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
-> **三库同名同参但能力不同**，尤其 **MySQL 侧检索不可用**（见下）。
+> 注意三点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**（可由 `VECTOR_CAPABILITIES` feature-detect），尤其
+> **MySQL 侧检索不可用**；③ `create_vector_table` 的 `dims` 为**必填**参数。
 
 ### 2. 向量方法（三库同名同参，能力差异化）
 
@@ -412,21 +424,34 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表（PG / MySQL 侧 `dims` 有约束） |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID |
-| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；**MySQL 侧抛 `NotImplementedError`** |
+| `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 数组 |
+| `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 侧为服务端版本号） |
 
-**能力差异（跨库不可比较 `distance` 数值）**：
+**`id_col` / `column`（逃生口）**：让**自建 DDL 的向量表**也能读写/检索。需要复合主键、额外约束、
+分区或与既有业务表合表时，用 `execute()` 自建 DDL 再用这两个参数接入；SQLite 侧要求 `id_col`
+为 rowid 别名（`INTEGER PRIMARY KEY`）。
+
+**`exact` 参数（默认 `True` = 禁止近似加速）**：
+
+| 后端 | `exact=True`（默认） | `exact=False` | 是否提速 |
+|------|---------------------|---------------|----------|
+| `PgKit` | 同事务 `SET LOCAL enable_indexscan = off`（有索引也精确；**代价：该查询不使用任何索引**，含过滤列索引） | 不干预查询计划（有索引即近似召回，`distance` 仍为真值） | ✅ 仅"大表 + 已建索引"时 |
+| `SQLiteKit` | `vector_full_scan`（**真值 L2**） | `vector_quantize_scan`（量化 L2 = 真值 × 255） | ❌ **不提速**（每次调用重建量化） |
+| `MySqlKit` | 不适用 | 同左 | — |
+
+**能力差异（仅 L2 可跨库比较数值；float32 vs float64，需带容差）**：
 
 | 项 | `SQLiteKit`（sqlite-vector） | `PgKit`（pgvector） | `MySqlKit`（9.x 原生） |
 |----|------------------------------|---------------------|------------------------|
-| 支持的 `distance_type` | **仅 L2**（该形参当前不生效，取任何值结果相同） | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
-| 非法取值 | 忽略 | 抛 `ValueError` | `search_vectors` 一律抛 `NotImplementedError` |
-| `distance` 口径 | int8 量化整数距离（= L2 × 255，非物理距离） | 真实距离 | — |
-| 维度约束 | 无 | 强制（不匹配即报错） | 上限约束（超限报错） |
-| `filter_sql` 与 `top_k` | **先取 top_k 再过滤**（可能少于 top_k） | **先过滤再取 top_k** | 不适用 |
-| 索引 | 每次检索 `vector_init` + `vector_quantize` | 默认无索引（可自建 hnsw/ivfflat） | 无法建（B-Tree 拒绝向量列） |
+| 支持的 `distance_type` | **仅 L2** | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
+| 默认 `distance_type` | `"L2"` | `"L2"`（三库统一，不按后端覆写） | `"L2"`（形参保留，调用即抛错） |
+| 非法取值 | 抛 `ValueError` | 抛 `ValueError` | `search_vectors` 抛 `VectorNotSupportedError` |
+| `distance` 口径 | `exact=True` 真值 L2 / `exact=False` 量化（×255） | 真实距离 | — |
+| 维度约束 | `CHECK`（仅新表；旧表靠方法内校验） | 强制（不匹配即报错；建表时回读比对） | 上限约束（超限报错） |
+| `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` 只覆盖存储侧。
@@ -438,24 +463,85 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 多实例部署需各自 `CommonKit.configure(datacenter_id, machine_id)`（默认 `(1,1)` 会重复）。
 
 ```python
-# SQLite
+# SQLite（默认精确：distance 为真值 L2）
 from kit.db.sqlite_kit import SQLiteKit
-SQLiteKit.create_vector_table("images", dims=384)
+SQLiteKit.create_vector_table("images", 384)          # dims 必填
 SQLiteKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5)
+rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5, exact=False)  # 旧量化口径（不提速）
 
 # PostgreSQL（签名相同；可选 COSINE/L2/L1/DOT/SQUARED_L2）
 from kit.db.pg_kit import PgKit
-PgKit.create_vector_table("images", dims=384)
+PgKit.create_vector_table("images", 384)
 PgKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
-rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="L2")
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="COSINE")
+# 大表 + 自建索引时才用 exact=False（否则索引不被使用，见上表）
+PgKit.execute("CREATE INDEX ON images USING hnsw (embedding vector_cosine_ops)")
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5,
+                            distance_type="COSINE", exact=False)
 
-# MySQL（仅存储；search_vectors 会抛 NotImplementedError）
+# MySQL（仅存储；search_vectors 抛 VectorNotSupportedError）
 from kit.db.mysql_kit import MySqlKit
-MySqlKit.create_vector_table("images", dims=384)
+MySqlKit.create_vector_table("images", 384)
 MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
+
+# 能力自省（无需 try/except）
+PgKit.VECTOR_CAPABILITIES
+# {'store': True, 'search': True, 'exact': True,
+#  'distances': ('COSINE', 'L2', 'L1', 'DOT', 'SQUARED_L2'),
+#  'distance_kind': 'true', 'fast_distance_kind': 'true'}
+
+# 自建 DDL 的表：用 id_col / column 接入
+PgKit.execute("CREATE TABLE my_vec (vid BIGINT PRIMARY KEY, vec vector(384))")
+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.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
+hits = SQLiteKit.search_vectors("item_vectors", query_vector, top_k=5)
+rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
+                       {"ids": [h["id"] for h in hits]})   # IN 不保证顺序，需按 hits 重排
 ```
 
+**自有事务内写向量（SQLite）**：
+
+```python
+conn = SQLiteKit.raw_connection()          # DBAPI 连接：位置参数 ? + 手工 commit
+try:
+    conn.execute("INSERT INTO item_vectors (id, embedding) VALUES (?, ?)",
+                 (item_id, SQLiteKit.encode_vector(vec)))
+    conn.commit()
+finally:
+    conn.close()
+```
+
+> 相似度换算建议：SQLite 仅支持 L2，若向量入库前已**归一化**，则 `cos = 1 − L2²/2`；
+> PG 可直接用 `distance_type="COSINE"`。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python

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

@@ -300,13 +300,23 @@ from kit import session_scope, transactional, DBError       # 等价
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
 | 表 | `table_exists(table_name) -> bool` | 判断表是否存在 |
 | 表 | `create_tables(models) -> None` | 按模型列表建表 |
-| 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（三个 Kit 各自实现） |
+| 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（按列序；公共键 4 个：`column_name`/`data_type`/`is_nullable`/`column_default`） |
+
+> **列表参数（`IN`）**：`query` / `execute` 的 `params` 中值为 `list`/`tuple`/`set`/`frozenset`
+> 时按 `IN` 展开，可直接写 `WHERE id IN :ids`（三库通用）。`IN` **不保证顺序**；参数列表过大
+> 应分批（PG 单语句上限 65535 参数）。
+>
+> **`LIKE` 的方言差异**：SQLite 对 ASCII 不区分大小写，PostgreSQL 区分（用 `ILIKE`）；
+> 跨库一致写法：`LOWER(col) LIKE LOWER(:pattern)`。
+>
+> **导出面**：`from kit.db import PgKit, SQLiteKit, build_pg_url, to_vector_literal, …`
+> （`kit` 顶层与 `kit.db` 导出同一套符号）。
 
 ```python
 from sqlalchemy import BigInteger
 from sqlmodel import SQLModel, Field
 from kit.common_kit import CommonKit
-from kit.db.sqlite_kit import SQLiteKit
+from kit.db import SQLiteKit          # 也可 from kit.db.sqlite_kit import SQLiteKit
 
 class User(SQLModel, table=True):
     # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
@@ -323,6 +333,7 @@ users = SQLiteKit.list(User, skip=0, limit=10, order_by="id", desc=True)
 
 rows = SQLiteKit.query("SELECT * FROM user WHERE name = :name", {"name": "李四"})
 affected = SQLiteKit.execute("UPDATE user SET name = '王五' WHERE id = :id", {"id": user.id})
+rows = SQLiteKit.query("SELECT * FROM user WHERE id IN :ids", {"ids": [1, 2, 3]})   # 列表参数
 
 with SQLiteKit.transaction() as session:                  # 多操作原子提交
     SQLiteKit.create(User, {"name": "批量一"})
@@ -330,8 +341,9 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
-> 注意两点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
-> **三库同名同参但能力不同**，尤其 **MySQL 侧检索不可用**（见下）。
+> 注意三点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**（可由 `VECTOR_CAPABILITIES` feature-detect），尤其
+> **MySQL 侧检索不可用**；③ `create_vector_table` 的 `dims` 为**必填**参数。
 
 ### 2. 向量方法（三库同名同参，能力差异化）
 
@@ -342,21 +354,34 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表（PG / MySQL 侧 `dims` 有约束） |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID |
-| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；**MySQL 侧抛 `NotImplementedError`** |
+| `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 数组 |
+| `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 侧为服务端版本号） |
 
-**能力差异（跨库不可比较 `distance` 数值）**：
+**`id_col` / `column`（逃生口）**：让**自建 DDL 的向量表**也能读写/检索。需要复合主键、额外约束、
+分区或与既有业务表合表时，用 `execute()` 自建 DDL 再用这两个参数接入；SQLite 侧要求 `id_col`
+为 rowid 别名（`INTEGER PRIMARY KEY`）。
+
+**`exact` 参数（默认 `True` = 禁止近似加速）**：
+
+| 后端 | `exact=True`（默认） | `exact=False` | 是否提速 |
+|------|---------------------|---------------|----------|
+| `PgKit` | 同事务 `SET LOCAL enable_indexscan = off`（有索引也精确；**代价：该查询不使用任何索引**，含过滤列索引） | 不干预查询计划（有索引即近似召回，`distance` 仍为真值） | ✅ 仅"大表 + 已建索引"时 |
+| `SQLiteKit` | `vector_full_scan`（**真值 L2**） | `vector_quantize_scan`（量化 L2 = 真值 × 255） | ❌ **不提速**（每次调用重建量化） |
+| `MySqlKit` | 不适用 | 同左 | — |
+
+**能力差异（仅 L2 可跨库比较数值；float32 vs float64，需带容差）**：
 
 | 项 | `SQLiteKit`（sqlite-vector） | `PgKit`（pgvector） | `MySqlKit`（9.x 原生） |
 |----|------------------------------|---------------------|------------------------|
-| 支持的 `distance_type` | **仅 L2**（该形参当前不生效，取任何值结果相同） | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
-| 非法取值 | 忽略 | 抛 `ValueError` | `search_vectors` 一律抛 `NotImplementedError` |
-| `distance` 口径 | int8 量化整数距离（= L2 × 255，非物理距离） | 真实距离 | — |
-| 维度约束 | 无 | 强制（不匹配即报错） | 上限约束（超限报错） |
-| `filter_sql` 与 `top_k` | **先取 top_k 再过滤**（可能少于 top_k） | **先过滤再取 top_k** | 不适用 |
-| 索引 | 每次检索 `vector_init` + `vector_quantize` | 默认无索引（可自建 hnsw/ivfflat） | 无法建（B-Tree 拒绝向量列） |
+| 支持的 `distance_type` | **仅 L2** | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
+| 默认 `distance_type` | `"L2"` | `"L2"`（三库统一，不按后端覆写） | `"L2"`（形参保留，调用即抛错） |
+| 非法取值 | 抛 `ValueError` | 抛 `ValueError` | `search_vectors` 抛 `VectorNotSupportedError` |
+| `distance` 口径 | `exact=True` 真值 L2 / `exact=False` 量化（×255） | 真实距离 | — |
+| 维度约束 | `CHECK`（仅新表；旧表靠方法内校验） | 强制（不匹配即报错；建表时回读比对） | 上限约束（超限报错） |
+| `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` 只覆盖存储侧。
@@ -368,24 +393,85 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 多实例部署需各自 `CommonKit.configure(datacenter_id, machine_id)`（默认 `(1,1)` 会重复）。
 
 ```python
-# SQLite
+# SQLite（默认精确：distance 为真值 L2）
 from kit.db.sqlite_kit import SQLiteKit
-SQLiteKit.create_vector_table("images", dims=384)
+SQLiteKit.create_vector_table("images", 384)          # dims 必填
 SQLiteKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5)
+rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5, exact=False)  # 旧量化口径（不提速）
 
 # PostgreSQL（签名相同；可选 COSINE/L2/L1/DOT/SQUARED_L2）
 from kit.db.pg_kit import PgKit
-PgKit.create_vector_table("images", dims=384)
+PgKit.create_vector_table("images", 384)
 PgKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
-rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="L2")
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="COSINE")
+# 大表 + 自建索引时才用 exact=False（否则索引不被使用，见上表）
+PgKit.execute("CREATE INDEX ON images USING hnsw (embedding vector_cosine_ops)")
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5,
+                            distance_type="COSINE", exact=False)
 
-# MySQL（仅存储；search_vectors 会抛 NotImplementedError）
+# MySQL（仅存储；search_vectors 抛 VectorNotSupportedError）
 from kit.db.mysql_kit import MySqlKit
-MySqlKit.create_vector_table("images", dims=384)
+MySqlKit.create_vector_table("images", 384)
 MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
+
+# 能力自省（无需 try/except）
+PgKit.VECTOR_CAPABILITIES
+# {'store': True, 'search': True, 'exact': True,
+#  'distances': ('COSINE', 'L2', 'L1', 'DOT', 'SQUARED_L2'),
+#  'distance_kind': 'true', 'fast_distance_kind': 'true'}
+
+# 自建 DDL 的表：用 id_col / column 接入
+PgKit.execute("CREATE TABLE my_vec (vid BIGINT PRIMARY KEY, vec vector(384))")
+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.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
+hits = SQLiteKit.search_vectors("item_vectors", query_vector, top_k=5)
+rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
+                       {"ids": [h["id"] for h in hits]})   # IN 不保证顺序，需按 hits 重排
 ```
 
+**自有事务内写向量（SQLite）**：
+
+```python
+conn = SQLiteKit.raw_connection()          # DBAPI 连接：位置参数 ? + 手工 commit
+try:
+    conn.execute("INSERT INTO item_vectors (id, embedding) VALUES (?, ?)",
+                 (item_id, SQLiteKit.encode_vector(vec)))
+    conn.commit()
+finally:
+    conn.close()
+```
+
+> 相似度换算建议：SQLite 仅支持 L2，若向量入库前已**归一化**，则 `cos = 1 − L2²/2`；
+> PG 可直接用 `distance_type="COSINE"`。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python

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

@@ -23,26 +23,37 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"
 
 from kit.db import (
     MYSQL,
     POSTGRESQL,
     SQLITE,
     CRUDBase,
+    DEFAULT_DISTANCE_TYPE,
     DBError,
+    MySqlKit,
     NotFoundError,
+    PgKit,
+    SQLiteKit,
+    VectorNotSupportedError,
+    build_mysql_url,
+    build_pg_url,
+    build_sqlite_url,
     close_all_engines,
     close_engine,
     create_tables,
+    generate_snowflake_ids,
     get_engine,
     get_session,
     list_tables,
     session_scope,
     table_exists,
+    to_vector_literal,
     transactional,
 )
 
+# 顶层公共面与 kit.db 保持一致（同一套符号，避免两处入口漂移）
 __all__ = [
     # 引擎管理
     "get_engine",
@@ -51,18 +62,31 @@ __all__ = [
     "table_exists",
     "close_all_engines",
     "close_engine",
+    # 连接串构造（单一来源）
+    "build_pg_url",
+    "build_mysql_url",
+    "build_sqlite_url",
     # 常量
     "POSTGRESQL",
     "MYSQL",
     "SQLITE",
+    # 数据库 Kit
+    "PgKit",
+    "MySqlKit",
+    "SQLiteKit",
     # 会话
     "session_scope",
     "get_session",
     # 异常
     "DBError",
     "NotFoundError",
+    "VectorNotSupportedError",
     # CRUD
     "CRUDBase",
     # 事务
     "transactional",
+    # 向量工具（公共）
+    "to_vector_literal",
+    "generate_snowflake_ids",
+    "DEFAULT_DISTANCE_TYPE",
 ]

{sdpy_kit-0.2.1 → sdpy_kit-0.2.3}/kit/db/__init__.py

@@ -29,11 +29,19 @@ Author: Clark Chang
 - SQLModel 混入类（models/base.py）
 """
 
+from kit.db.base_db_kit import (
+    DEFAULT_DISTANCE_TYPE,
+    generate_snowflake_ids,
+    to_vector_literal,
+)
 from kit.db.crud import CRUDBase
 from kit.db.engine import (
     MYSQL,
     POSTGRESQL,
     SQLITE,
+    build_mysql_url,
+    build_pg_url,
+    build_sqlite_url,
     close_all_engines,
     close_engine,
     create_tables,
@@ -41,8 +49,11 @@ from kit.db.engine import (
     list_tables,
     table_exists,
 )
-from kit.db.exceptions import DBError, NotFoundError
+from kit.db.exceptions import DBError, NotFoundError, VectorNotSupportedError
+from kit.db.mysql_kit import MySqlKit
+from kit.db.pg_kit import PgKit
 from kit.db.session import get_session, session_scope
+from kit.db.sqlite_kit import SQLiteKit
 from kit.db.transaction import transactional
 
 __all__ = [
@@ -53,18 +64,31 @@ __all__ = [
     "table_exists",
     "close_all_engines",
     "close_engine",
+    # 连接串构造（单一来源，测试/工具可复用）
+    "build_pg_url",
+    "build_mysql_url",
+    "build_sqlite_url",
     # 常量
     "POSTGRESQL",
     "MYSQL",
     "SQLITE",
+    # 数据库 Kit
+    "PgKit",
+    "MySqlKit",
+    "SQLiteKit",
     # 会话
     "session_scope",
     "get_session",
     # 异常
     "DBError",
     "NotFoundError",
+    "VectorNotSupportedError",
     # CRUD
     "CRUDBase",
     # 事务
     "transactional",
+    # 向量工具（公共）
+    "to_vector_literal",
+    "generate_snowflake_ids",
+    "DEFAULT_DISTANCE_TYPE",
 ]

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

@@ -43,13 +43,14 @@ create_raw_table / raw_insert / raw_get_by）上移到本基类，使三个 Kit
 """
 
 import builtins
+import re
 import threading
 from abc import ABC, abstractmethod
 from collections.abc import Generator
 from contextlib import contextmanager
 from typing import cast
 
-from sqlalchemy import text
+from sqlalchemy import TextClause, bindparam, text
 from sqlalchemy.pool import PoolProxiedConnection
 from sqlmodel import Session, SQLModel
 
@@ -70,6 +71,11 @@ logger = get_default_logger(__name__)
 # 字段数据：列名到值的映射（object 覆盖全部 SQLModel 支持类型）
 type FieldData = dict[str, object]
 
+# 向量检索的默认距离类型：三库能力集的交集（SQLite 仅支持 L2），
+# 由三个数据库 Kit 的 search_vectors 共用，避免各 Kit 默认值漂移。
+# 默认值不得按后端覆写——否则同一份代码换 import 后会在静默中改变度量语义。
+DEFAULT_DISTANCE_TYPE = "L2"
+
 # CRUD 实例缓存：CRUDBase 无状态（仅存 model），按 model 复用避免重复实例化
 # 值类型取宽基类 SQLModel，规避 PEP 695 类型参数上界约束
 _crud_cache: dict[type, CRUDBase[SQLModel, SQLModel, SQLModel]] = {}
@@ -98,6 +104,26 @@ def to_vector_literal(vector: builtins.list[float]) -> str:
     return "[" + ",".join(repr(float(value)) for value in vector) + "]"
 
 
+def vector_insert_placeholders(
+    columns: builtins.list[str], id_col: str, column: str
+) -> str:
+    """生成向量表 INSERT 的占位符串（供三个数据库 Kit 的 insert_vectors 共用）
+
+    绑定参数名与列名**解耦**：id 列固定为 ``:id``、向量列固定为 ``:vec``、
+    其余列用 ``:列名``。这样调用方覆写 ``id_col`` / ``column``（自建 DDL 场景）时，
+    参数字典的键不受列名影响。
+    """
+
+    def _one(name: str) -> str:
+        if name == column:
+            return ":vec"
+        if name == id_col:
+            return ":id"
+        return f":{name}"
+
+    return ", ".join(_one(name) for name in columns)
+
+
 def generate_snowflake_ids(count: int) -> builtins.list[int]:
     """生成 count 个雪花 ID（int64；当前 18 位，上限 19 位）
 
@@ -110,6 +136,50 @@ def generate_snowflake_ids(count: int) -> builtins.list[int]:
     return [CommonKit.generate_snowflake_id() for _ in range(count)]
 
 
+# 可参与 IN 展开的参数类型（按类型白名单判断，绝不用 Iterable：
+# 否则字符串会被逐字符展开）
+_EXPANDING_TYPES = (list, tuple, set, frozenset)
+
+
+def _prepare_statement(
+    sql: str, params: FieldData | None
+) -> tuple[TextClause, FieldData | None]:
+    """把 SQL 文本 + 参数字典转为（可执行语句, 归一化后的参数）
+
+    `params` 中值为**序列类型**（list / tuple / set / frozenset）的键按 SQLAlchemy
+    **expanding** 语义绑定，使 ``WHERE id IN :ids`` 可直接书写（三库通用）。
+
+    三条实现约束：
+
+    1. 按类型白名单判断（见 `_EXPANDING_TYPES`），字符串不会被当作列表；
+    2. 只对**确实出现在 SQL 中**的参数名做 expanding —— 否则传入"未使用的序列参数"
+       会触发 SQLAlchemy 的 ``ArgumentError: This text() construct doesn't define
+       a bound parameter …``，该报错对使用方没有意义；
+    3. `set` / `frozenset` 归一化为 `list` —— SQLAlchemy 的 expanding 只接受
+       **可下标序列**（直接传 set 会抛 ``TypeError: 'set' object is not subscriptable``）；
+       ``IN`` 与顺序无关，故归一化不改变语义。
+    """
+    statement = text(sql)
+    if not params:
+        return statement, params
+
+    normalized: FieldData = {}
+    expanding: list[object] = []
+    for name, value in params.items():
+        if isinstance(value, _EXPANDING_TYPES):
+            if isinstance(value, (set, frozenset)):
+                value = list(value)
+            normalized[name] = value
+            if re.search(rf":{re.escape(name)}\b", sql):
+                expanding.append(bindparam(name, expanding=True))
+        else:
+            normalized[name] = value
+
+    if expanding:
+        statement = statement.bindparams(*expanding)  # type: ignore[arg-type]
+    return statement, normalized
+
+
 class BaseDbKit(ABC):
     """数据库工具类共享基类
 
@@ -360,13 +430,19 @@ class BaseDbKit(ABC):
 
         Args:
             sql: SQL 查询语句（使用命名参数 :param）
-            params: 参数字典
+            params: 参数字典。值为 list / tuple / set / frozenset 的参数按 ``IN`` 展开，
+                可直接书写 ``WHERE id IN :ids``（三库通用）
 
         Returns:
             查询结果列表，每行为一个字典
+
+        Note:
+            ``IN`` **不保证返回顺序**，需要顺序请自行按 id 重排；参数列表过大时
+            （如 PG 单语句参数上限 65535）应分批查询。
         """
+        statement, bound = _prepare_statement(sql, params)
         with session_scope(cls.DB_TYPE, autocommit=False) as session:
-            result = session.execute(text(sql), params or {})
+            result = session.execute(statement, bound or {})
             rows = result.fetchall()
             columns = result.keys()
             data = [dict(zip(columns, row)) for row in rows]
@@ -379,13 +455,15 @@ class BaseDbKit(ABC):
 
         Args:
             sql: SQL 语句（使用命名参数 :param）
-            params: 参数字典
+            params: 参数字典。值为 list / tuple / set / frozenset 的参数按 ``IN`` 展开
+                （如 ``DELETE FROM t WHERE id IN :ids``，三库通用）
 
         Returns:
             受影响的行数
         """
+        statement, bound = _prepare_statement(sql, params)
         with session_scope(cls.DB_TYPE) as session:
-            result = session.execute(text(sql), params or {})
+            result = session.execute(statement, bound or {})
             affected = getattr(result, "rowcount", 0) or 0
             logger.info(f"✅ 执行更新 → 影响 {affected} 行")
             return affected