sdpy-kit 0.2.0__tar.gz → 0.2.2__tar.gz

{sdpy_kit-0.2.0 → sdpy_kit-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.0
+Version: 0.2.2
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -84,7 +84,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | 模块 | 类 / 入口 | 能力 | 需要 extra |
 |------|-----------|------|-----------|
 | `kit.config` | `get_settings` / `get_default_logger` | 配置单例与统一日志 | 无 |
-| `kit.db` | `SQLiteKit` / `PgKit` / `MySqlKit` / `CRUDBase` | 统一 CRUD、原生 SQL、事务、表管理 | `pg` / `mysql` / `sqliteai` |
+| `kit.db` | `SQLiteKit` / `PgKit` / `MySqlKit` / `CRUDBase` | 统一 CRUD、原生 SQL、原生表操作、事务、表管理 | `pg` / `mysql` / `sqliteai` |
 | `kit.ai` | `AI`（同步门面）/ 4 个原生异步 Service | 对话 / 向量化 / 重排序 / 文生图 | `ai` |
 | `kit.mcp_kit` | `McpKit` | MCP 工具发现与调用 | `mcp` |
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
@@ -110,8 +110,8 @@ uv add sdpy-kit
 
 | extra | 能力 | 安装 |
 |-------|------|------|
-| `pg` | PgKit（PostgreSQL 驱动） | `pip install "sdpy-kit[pg]"` |
-| `mysql` | MySqlKit（MySQL 驱动） | `pip install "sdpy-kit[mysql]"` |
+| `pg` | PgKit（PostgreSQL 驱动；向量方法另需服务端 pgvector） | `pip install "sdpy-kit[pg]"` |
+| `mysql` | MySqlKit（MySQL 驱动；向量仅存储，需 MySQL 9.x） | `pip install "sdpy-kit[mysql]"` |
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `zvec` | ZvecKit（zvec，阿里独立向量库） | `pip install "sdpy-kit[zvec]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
@@ -336,7 +336,7 @@ from kit.db import session_scope, transactional, DBError    # 推荐
 from kit import session_scope, transactional, DBError       # 等价
 ```
 
-### 1. 三个数据库 Kit（API 完全一致）
+### 1. 三个数据库 Kit（23 个共享方法 API 完全一致）
 
 | 类 | 导入 | 数据库 | extra |
 |----|------|--------|-------|
@@ -344,13 +344,14 @@ from kit import session_scope, transactional, DBError       # 等价
 | `PgKit` | `from kit.db.pg_kit import PgKit` | PostgreSQL | `pg` |
 | `MySqlKit` | `from kit.db.mysql_kit import MySqlKit` | MySQL | `mysql` |
 
-**共有方法（19 个，全部为 classmethod，内部自动提交）**
+**共有方法（23 个，全部为 classmethod，内部自动提交）**
 
 | 分组 | 方法 | 说明 |
 |------|------|------|
 | 连接 | `connect() -> bool` | 建引擎并验证连通 |
 | 连接 | `close() -> None` | 关闭引擎 |
 | 连接 | `is_connected() -> bool` | 探测当前是否可连 |
+| 连接 | `raw_connection()` | 取原生 DBAPI 连接（PG=psycopg2 / MySQL=pymysql / SQLite=sqlite3）；调用方负责 commit 与 close，psycopg2 / pymysql 默认不自动提交 |
 | ORM | `create(model, data) -> Model` | 插入单条 |
 | ORM | `create_multi(model, data_list) -> list[Model]` | 批量插入 |
 | ORM | `get(model, id) -> Model \| None` | 按主键查询 |
@@ -362,6 +363,9 @@ from kit import session_scope, transactional, DBError       # 等价
 | ORM | `count(model) -> int` | 记录总数 |
 | 原生 SQL | `query(sql, params=None) -> list[dict]` | 原生查询，返回字典列表 |
 | 原生 SQL | `execute(sql, params=None) -> int` | 原生写入，返回影响行数 |
+| 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
+| 原生表 | `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
+| 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
 | 事务 | `transaction()` | 事务上下文管理器，`with PgKit.transaction() as session:` |
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
 | 表 | `table_exists(table_name) -> bool` | 判断表是否存在 |
@@ -369,11 +373,15 @@ from kit import session_scope, transactional, DBError       # 等价
 | 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（三个 Kit 各自实现） |
 
 ```python
+from sqlalchemy import BigInteger
 from sqlmodel import SQLModel, Field
+from kit.common_kit import CommonKit
 from kit.db.sqlite_kit import SQLiteKit
 
 class User(SQLModel, table=True):
-    id: int | None = Field(default=None, primary_key=True)
+    # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
+    id: int = Field(default_factory=CommonKit.generate_snowflake_id,
+                    primary_key=True, sa_type=BigInteger)
     name: str
 
 SQLiteKit.connect()
@@ -392,33 +400,105 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
+> 注意三点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**（可由 `VECTOR_CAPABILITIES` feature-detect），尤其
+> **MySQL 侧检索不可用**；③ `create_vector_table` 的 `dims` 为**必填**参数。
 
-### 2. SQLiteKit 独有方法
-
-无需额外依赖：
-
-| 方法 | 说明 |
-|------|------|
-| `raw_connection()` | 取原生 DBAPI 连接（sqlite-vector 扩展已自动加载），调用方负责关闭 |
-| `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表 |
-| `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
-| `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
+### 2. 向量方法（三库同名同参，能力差异化）
 
-向量方法（需 `pip install "sdpy-kit[sqliteai]"`）：
+> 签名在 `SQLiteKit` / `PgKit` / `MySqlKit` 上完全一致；能力按后端不同（见下表）。
+> extra 前提：SQLite 需 `sdpy-kit[sqliteai]`；PG 需 `sdpy-kit[pg]` **且服务端已装 pgvector**
+> （`create_vector_table` 会自动尝试 `CREATE EXTENSION`）；MySQL 需 **9.x**（Community 即可存，
+> 但检索需 HeatWave on OCI / MySQL AI）——建表前会校验服务端版本，低于 9.x 抛 `DBError`。
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表 |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量 |
-| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance", ...}` |
-| `vector_version() -> str` | 向量扩展版本，不可用时返回 `"unavailable"` |
+| `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 侧为服务端版本号） |
+
+**`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` | **无（检索不可用）** |
+| 默认 `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` 只覆盖存储侧。
+
+**主键与 id（三库统一）**：向量表主键均为 `BIGINT`（SQLite 用等价的 64 位 `INTEGER PRIMARY KEY`），
+**不使用数据库自增**；`ids=None` 时由 Kit 用 `CommonKit.generate_snowflake_id()` 生成雪花 ID
+（18~19 位，int64）。
+⚠ 雪花 ID 超过 `2^53`，经 JSON 传给 JavaScript 会丢精度，需按字符串传输；
+多实例部署需各自 `CommonKit.configure(datacenter_id, machine_id)`（默认 `(1,1)` 会重复）。
 
 ```python
-SQLiteKit.create_vector_table("images", dims=384)
+# SQLite（默认精确：distance 为真值 L2）
+from kit.db.sqlite_kit import SQLiteKit
+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", 384)
+PgKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
+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 抛 VectorNotSupportedError）
+from kit.db.mysql_kit import MySqlKit
+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 数组与批量提交。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python
@@ -481,10 +561,16 @@ def transfer(session: Session, from_id: int, to_id: int, amount: float) -> None:
 ### 5. 模型混入类与查询构建器
 
 ```python
+from sqlalchemy import BigInteger
+from sqlmodel import Field, SQLModel
+
+from kit.common_kit import CommonKit
 from kit.db.models import TimestampMixin, SoftDeleteMixin, AuditMixin
 
-class Article(TimestampMixin, SoftDeleteMixin, table=True):
-    id: int | None = Field(default=None, primary_key=True)
+class Article(TimestampMixin, SoftDeleteMixin, SQLModel, table=True):
+    # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
+    id: int = Field(default_factory=CommonKit.generate_snowflake_id,
+                    primary_key=True, sa_type=BigInteger)
     title: str
 ```
 

{sdpy_kit-0.2.0 → sdpy_kit-0.2.2}/README.md

@@ -14,7 +14,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | 模块 | 类 / 入口 | 能力 | 需要 extra |
 |------|-----------|------|-----------|
 | `kit.config` | `get_settings` / `get_default_logger` | 配置单例与统一日志 | 无 |
-| `kit.db` | `SQLiteKit` / `PgKit` / `MySqlKit` / `CRUDBase` | 统一 CRUD、原生 SQL、事务、表管理 | `pg` / `mysql` / `sqliteai` |
+| `kit.db` | `SQLiteKit` / `PgKit` / `MySqlKit` / `CRUDBase` | 统一 CRUD、原生 SQL、原生表操作、事务、表管理 | `pg` / `mysql` / `sqliteai` |
 | `kit.ai` | `AI`（同步门面）/ 4 个原生异步 Service | 对话 / 向量化 / 重排序 / 文生图 | `ai` |
 | `kit.mcp_kit` | `McpKit` | MCP 工具发现与调用 | `mcp` |
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
@@ -40,8 +40,8 @@ uv add sdpy-kit
 
 | extra | 能力 | 安装 |
 |-------|------|------|
-| `pg` | PgKit（PostgreSQL 驱动） | `pip install "sdpy-kit[pg]"` |
-| `mysql` | MySqlKit（MySQL 驱动） | `pip install "sdpy-kit[mysql]"` |
+| `pg` | PgKit（PostgreSQL 驱动；向量方法另需服务端 pgvector） | `pip install "sdpy-kit[pg]"` |
+| `mysql` | MySqlKit（MySQL 驱动；向量仅存储，需 MySQL 9.x） | `pip install "sdpy-kit[mysql]"` |
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `zvec` | ZvecKit（zvec，阿里独立向量库） | `pip install "sdpy-kit[zvec]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
@@ -266,7 +266,7 @@ from kit.db import session_scope, transactional, DBError    # 推荐
 from kit import session_scope, transactional, DBError       # 等价
 ```
 
-### 1. 三个数据库 Kit（API 完全一致）
+### 1. 三个数据库 Kit（23 个共享方法 API 完全一致）
 
 | 类 | 导入 | 数据库 | extra |
 |----|------|--------|-------|
@@ -274,13 +274,14 @@ from kit import session_scope, transactional, DBError       # 等价
 | `PgKit` | `from kit.db.pg_kit import PgKit` | PostgreSQL | `pg` |
 | `MySqlKit` | `from kit.db.mysql_kit import MySqlKit` | MySQL | `mysql` |
 
-**共有方法（19 个，全部为 classmethod，内部自动提交）**
+**共有方法（23 个，全部为 classmethod，内部自动提交）**
 
 | 分组 | 方法 | 说明 |
 |------|------|------|
 | 连接 | `connect() -> bool` | 建引擎并验证连通 |
 | 连接 | `close() -> None` | 关闭引擎 |
 | 连接 | `is_connected() -> bool` | 探测当前是否可连 |
+| 连接 | `raw_connection()` | 取原生 DBAPI 连接（PG=psycopg2 / MySQL=pymysql / SQLite=sqlite3）；调用方负责 commit 与 close，psycopg2 / pymysql 默认不自动提交 |
 | ORM | `create(model, data) -> Model` | 插入单条 |
 | ORM | `create_multi(model, data_list) -> list[Model]` | 批量插入 |
 | ORM | `get(model, id) -> Model \| None` | 按主键查询 |
@@ -292,6 +293,9 @@ from kit import session_scope, transactional, DBError       # 等价
 | ORM | `count(model) -> int` | 记录总数 |
 | 原生 SQL | `query(sql, params=None) -> list[dict]` | 原生查询，返回字典列表 |
 | 原生 SQL | `execute(sql, params=None) -> int` | 原生写入，返回影响行数 |
+| 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
+| 原生表 | `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
+| 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
 | 事务 | `transaction()` | 事务上下文管理器，`with PgKit.transaction() as session:` |
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
 | 表 | `table_exists(table_name) -> bool` | 判断表是否存在 |
@@ -299,11 +303,15 @@ from kit import session_scope, transactional, DBError       # 等价
 | 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（三个 Kit 各自实现） |
 
 ```python
+from sqlalchemy import BigInteger
 from sqlmodel import SQLModel, Field
+from kit.common_kit import CommonKit
 from kit.db.sqlite_kit import SQLiteKit
 
 class User(SQLModel, table=True):
-    id: int | None = Field(default=None, primary_key=True)
+    # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
+    id: int = Field(default_factory=CommonKit.generate_snowflake_id,
+                    primary_key=True, sa_type=BigInteger)
     name: str
 
 SQLiteKit.connect()
@@ -322,33 +330,105 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
+> 注意三点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**（可由 `VECTOR_CAPABILITIES` feature-detect），尤其
+> **MySQL 侧检索不可用**；③ `create_vector_table` 的 `dims` 为**必填**参数。
 
-### 2. SQLiteKit 独有方法
-
-无需额外依赖：
-
-| 方法 | 说明 |
-|------|------|
-| `raw_connection()` | 取原生 DBAPI 连接（sqlite-vector 扩展已自动加载），调用方负责关闭 |
-| `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表 |
-| `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
-| `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
+### 2. 向量方法（三库同名同参，能力差异化）
 
-向量方法（需 `pip install "sdpy-kit[sqliteai]"`）：
+> 签名在 `SQLiteKit` / `PgKit` / `MySqlKit` 上完全一致；能力按后端不同（见下表）。
+> extra 前提：SQLite 需 `sdpy-kit[sqliteai]`；PG 需 `sdpy-kit[pg]` **且服务端已装 pgvector**
+> （`create_vector_table` 会自动尝试 `CREATE EXTENSION`）；MySQL 需 **9.x**（Community 即可存，
+> 但检索需 HeatWave on OCI / MySQL AI）——建表前会校验服务端版本，低于 9.x 抛 `DBError`。
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表 |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量 |
-| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance", ...}` |
-| `vector_version() -> str` | 向量扩展版本，不可用时返回 `"unavailable"` |
+| `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 侧为服务端版本号） |
+
+**`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` | **无（检索不可用）** |
+| 默认 `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` 只覆盖存储侧。
+
+**主键与 id（三库统一）**：向量表主键均为 `BIGINT`（SQLite 用等价的 64 位 `INTEGER PRIMARY KEY`），
+**不使用数据库自增**；`ids=None` 时由 Kit 用 `CommonKit.generate_snowflake_id()` 生成雪花 ID
+（18~19 位，int64）。
+⚠ 雪花 ID 超过 `2^53`，经 JSON 传给 JavaScript 会丢精度，需按字符串传输；
+多实例部署需各自 `CommonKit.configure(datacenter_id, machine_id)`（默认 `(1,1)` 会重复）。
 
 ```python
-SQLiteKit.create_vector_table("images", dims=384)
+# SQLite（默认精确：distance 为真值 L2）
+from kit.db.sqlite_kit import SQLiteKit
+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", 384)
+PgKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
+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 抛 VectorNotSupportedError）
+from kit.db.mysql_kit import MySqlKit
+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 数组与批量提交。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python
@@ -411,10 +491,16 @@ def transfer(session: Session, from_id: int, to_id: int, amount: float) -> None:
 ### 5. 模型混入类与查询构建器
 
 ```python
+from sqlalchemy import BigInteger
+from sqlmodel import Field, SQLModel
+
+from kit.common_kit import CommonKit
 from kit.db.models import TimestampMixin, SoftDeleteMixin, AuditMixin
 
-class Article(TimestampMixin, SoftDeleteMixin, table=True):
-    id: int | None = Field(default=None, primary_key=True)
+class Article(TimestampMixin, SoftDeleteMixin, SQLModel, table=True):
+    # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
+    id: int = Field(default_factory=CommonKit.generate_snowflake_id,
+                    primary_key=True, sa_type=BigInteger)
     title: str
 ```
 

{sdpy_kit-0.2.0 → sdpy_kit-0.2.2}/kit/__init__.py

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

{sdpy_kit-0.2.0 → sdpy_kit-0.2.2}/kit/db/__init__.py

@@ -41,7 +41,7 @@ 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.session import get_session, session_scope
 from kit.db.transaction import transactional
 
@@ -63,6 +63,7 @@ __all__ = [
     # 异常
     "DBError",
     "NotFoundError",
+    "VectorNotSupportedError",
     # CRUD
     "CRUDBase",
     # 事务

{sdpy_kit-0.2.0 → sdpy_kit-0.2.2}/kit/db/base_db_kit.py

@@ -23,9 +23,13 @@ from __future__ import annotations
 """数据库 Kit 共享基类（DRY 收敛）
 
 三个数据库 Kit（PgKit / MySqlKit / SQLiteKit）在重构前拥有约 400 行几乎
-逐行相同的代码（连接管理 / ORM / 原生 SQL / 事务 / 表操作），仅 DB_TYPE
-与 get_table_info 的 SQL 不同。本基类将全部共享实现收敛，子类只声明
-DB_TYPE 并覆写 get_table_info（SQLite 另含向量操作）。
+逐行相同的代码（连接管理 / ORM / 原生 SQL / 原生表操作 / 事务 / 表操作），
+仅 DB_TYPE 与 get_table_info 的 SQL 不同。本基类将全部共享实现收敛，子类
+只声明 DB_TYPE 并覆写 get_table_info（SQLite 另含向量操作）。
+
+2026-10-11：将原本仅 SQLiteKit 具备的 4 个方言无关方法（raw_connection /
+create_raw_table / raw_insert / raw_get_by）上移到本基类，使三个 Kit 在该层
+的能力与签名完全一致（共享方法 19 → 23）。
 
 设计要点：
 - 所有公开方法保留原签名与语义，外部调用零影响。
@@ -46,8 +50,10 @@ from contextlib import contextmanager
 from typing import cast
 
 from sqlalchemy import text
+from sqlalchemy.pool import PoolProxiedConnection
 from sqlmodel import Session, SQLModel
 
+from kit.common_kit import CommonKit
 from kit.config.log_config import get_default_logger
 from kit.db.crud import CRUDBase
 from kit.db.engine import (
@@ -64,6 +70,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]] = {}
@@ -83,6 +94,47 @@ def _get_crud[T: SQLModel](model: type[T]) -> CRUDBase[T, T, T]:
     return cast(CRUDBase[T, T, T], crud)
 
 
+def to_vector_literal(vector: builtins.list[float]) -> str:
+    """把 float 列表转换为向量文本字面量（如 [0.1, 0.2] → "[0.1,0.2]"）
+
+    供共享相同文本格式的数据库后端复用：PgKit（pgvector 的 vector 类型）与
+    MySqlKit（STRING_TO_VECTOR）。SQLiteKit 走 float32 bytes，不使用本函数。
+    """
+    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 位）
+
+    供三个数据库 Kit 的向量方法在调用方未提供 id（``ids=None``）时兜底使用：
+    id 由**应用侧（kit）生成**而非数据库自增，保证三库语义一致，同时避免
+    PostgreSQL 序列不随显式 id 推进的问题（BIGSERIAL → 纯 BIGINT 主键）。
+
+    ⚠ 雪花 ID 超过 2^53，经 JSON 传给 JavaScript 会丢精度，需按字符串传输。
+    """
+    return [CommonKit.generate_snowflake_id() for _ in range(count)]
+
+
 class BaseDbKit(ABC):
     """数据库工具类共享基类
 
@@ -129,6 +181,19 @@ class BaseDbKit(ABC):
         except Exception:
             return False
 
+    @classmethod
+    def raw_connection(cls) -> PoolProxiedConnection:
+        """获取原生 DBAPI 连接（引擎侧扩展加载已由 engine.py 自动完成）
+
+        PostgreSQL 返回 psycopg2 连接、MySQL 返回 pymysql 连接、SQLite 返回
+        sqlite3 连接（sqlite-vector 扩展已自动加载）。用于执行驱动特有函数与
+        静态 DDL。
+
+        ⚠ 调用方负责提交与关闭连接。psycopg2 / pymysql 默认**不开启自动提交**，
+        与 sqlite3 的使用习惯不同：需要落库时必须显式 commit。
+        """
+        return get_engine(cls.DB_TYPE).raw_connection()
+
     # ==================== ORM 操作（自动管理 session） ====================
 
     @classmethod
@@ -350,6 +415,71 @@ class BaseDbKit(ABC):
             logger.info(f"✅ 执行更新 → 影响 {affected} 行")
             return affected
 
+    # ==================== 原生表操作 ====================
+
+    @classmethod
+    def create_raw_table(
+        cls, table_name: str, columns: dict[str, str], if_not_exists: bool = True
+    ) -> None:
+        """根据「列名 → 列定义」字典创建普通表
+
+        Args:
+            table_name: 表名
+            columns: 列定义字典，如 {"id": "BIGSERIAL PRIMARY KEY", "name": "TEXT"}
+            if_not_exists: 是否附加 IF NOT EXISTS（默认 True）
+
+        ⚠ 列定义须按**目标数据库方言**书写，本方法只做字符串拼接与执行，
+        不做方言翻译：
+            PostgreSQL: {"id": "BIGSERIAL PRIMARY KEY", "name": "TEXT"}
+            MySQL:      {"id": "INT AUTO_INCREMENT PRIMARY KEY", "name": "VARCHAR(100)"}
+            SQLite:     {"id": "INTEGER PRIMARY KEY", "name": "TEXT"}
+        """
+        column_defs = ", ".join(
+            f"{name} {definition}" for name, definition in columns.items()
+        )
+        if_not_exists_sql = "IF NOT EXISTS " if if_not_exists else ""
+        sql = f"CREATE TABLE {if_not_exists_sql}{table_name} ({column_defs})"
+        with get_engine(cls.DB_TYPE).connect() as conn:
+            conn.execute(text(sql))
+            conn.commit()
+        logger.info(f"✅ 创建表 {table_name}")
+
+    @classmethod
+    def raw_insert(cls, table_name: str, data: dict[str, object]) -> int:
+        """向指定表插入一行数据（键为列名）
+
+        Args:
+            table_name: 表名
+            data: 列名 → 值 字典
+
+        Returns:
+            受影响的行数
+        """
+        columns = ", ".join(data.keys())
+        placeholders = ", ".join(f":{name}" for name in data)
+        sql = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders})"
+        return cls.execute(sql, dict(data))
+
+    @classmethod
+    def raw_get_by(
+        cls, table_name: str, column: str, value: object
+    ) -> dict[str, object] | None:
+        """按单列等值查询一行
+
+        Args:
+            table_name: 表名
+            column: 列名
+            value: 查询值
+
+        Returns:
+            匹配的第一行（字典）；无匹配返回 None
+        """
+        rows = cls.query(
+            f"SELECT * FROM {table_name} WHERE {column} = :value LIMIT 1",
+            {"value": value},
+        )
+        return rows[0] if rows else None
+
     # ==================== 事务管理 ====================
 
     @classmethod