sdpy-kit 0.6.2__tar.gz → 0.6.4__tar.gz

{sdpy_kit-0.6.2 → sdpy_kit-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.2
+Version: 0.6.4
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -98,7 +98,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `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` |
-| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
+| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML（含图片） | `md2doc` |
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
@@ -125,7 +125,7 @@ uv add sdpy-kit
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
 | `ai` | AI 服务池（httpx + python-dotenv） | `pip install "sdpy-kit[ai]"` |
-| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2） | `pip install "sdpy-kit[md2doc]"` |
+| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2，含图片） | `pip install "sdpy-kit[md2doc]"` |
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
@@ -451,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 的向量表**也能读写/检索。需要复合主键、额外约束、
@@ -473,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
@@ -513,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))")
@@ -812,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
@@ -1051,12 +1076,18 @@ Md2DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
 
 | 方法 | 说明 |
 |------|------|
-| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体） |
-| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件 |
-| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用） |
+| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体、图片内嵌） |
+| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件（图片输出 `<figure><img>`） |
+| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用；图片等比限宽居中） |
 
 > `dest_path=None` 时输出到源文件同目录；同一源文件不支持并发转换。
 
+**图片**：`![alt](相对路径)` 以 Markdown 源文件所在目录为基准解析，宽度等比限幅
+（96dpi 还原自然尺寸、不放大），超高先分页/按版心收紧；缺图、越界路径、非图片
+格式一律回落 `alt` 文本，不抛异常。远程地址在 PDF / Word 中不下载（回落 alt），
+在 HTML 中直出 `<img src="https://…">` 交给浏览器。HTML 输出保留相对路径，需与
+`images/` 目录保持同层级才能在浏览器中显示。
+
 ---
 
 ## kit.docs.mineru_kit —— MinerU 文档解析

{sdpy_kit-0.6.2 → sdpy_kit-0.6.4}/README.md

@@ -22,7 +22,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `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` |
-| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
+| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML（含图片） | `md2doc` |
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
@@ -49,7 +49,7 @@ uv add sdpy-kit
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
 | `ai` | AI 服务池（httpx + python-dotenv） | `pip install "sdpy-kit[ai]"` |
-| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2） | `pip install "sdpy-kit[md2doc]"` |
+| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2，含图片） | `pip install "sdpy-kit[md2doc]"` |
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
@@ -375,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 的向量表**也能读写/检索。需要复合主键、额外约束、
@@ -397,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
@@ -437,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))")
@@ -736,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
@@ -975,12 +1000,18 @@ Md2DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
 
 | 方法 | 说明 |
 |------|------|
-| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体） |
-| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件 |
-| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用） |
+| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体、图片内嵌） |
+| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件（图片输出 `<figure><img>`） |
+| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用；图片等比限宽居中） |
 
 > `dest_path=None` 时输出到源文件同目录；同一源文件不支持并发转换。
 
+**图片**：`![alt](相对路径)` 以 Markdown 源文件所在目录为基准解析，宽度等比限幅
+（96dpi 还原自然尺寸、不放大），超高先分页/按版心收紧；缺图、越界路径、非图片
+格式一律回落 `alt` 文本，不抛异常。远程地址在 PDF / Word 中不下载（回落 alt），
+在 HTML 中直出 `<img src="https://…">` 交给浏览器。HTML 输出保留相对路径，需与
+`images/` 目录保持同层级才能在浏览器中显示。
+
 ---
 
 ## kit.docs.mineru_kit —— MinerU 文档解析

{sdpy_kit-0.6.2 → sdpy_kit-0.6.4}/kit/__init__.py

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

{sdpy_kit-0.6.2 → sdpy_kit-0.6.4}/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.2 → sdpy_kit-0.6.4}/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.2 → sdpy_kit-0.6.4}/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.2 → sdpy_kit-0.6.4}/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.2 → sdpy_kit-0.6.4}/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.2 → sdpy_kit-0.6.4}/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,