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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.1.14
+Version: 0.2.1
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -30,6 +30,7 @@ Requires-Dist: fastmcp>=4.0.5; extra == 'all'
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
 Requires-Dist: httpx>=0.28.1; extra == 'all'
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
+Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'all'
 Requires-Dist: numpy>=2.5.3; extra == 'all'
 Requires-Dist: pikepdf>=10.13.0; extra == 'all'
 Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'all'
@@ -45,6 +46,8 @@ Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
 Requires-Dist: pikepdf>=10.13.0; extra == 'anydoc'
 Provides-Extra: docx
 Requires-Dist: docxtpl>=0.20.2; extra == 'docx'
+Provides-Extra: marker
+Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'marker'
 Provides-Extra: mcp
 Requires-Dist: fastmcp>=4.0.5; extra == 'mcp'
 Provides-Extra: md2doc
@@ -72,7 +75,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
 - **MCP 客户端**：streamable-http / sse 双传输，档案驱动多服务器；
-- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / 向量库 / 微信公众号文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（md + images） / 向量库 / 微信公众号文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -81,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` |
@@ -91,6 +94,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
 | `kit.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
+| `kit.marker_kit` | `MarkerKit` | 本地文档解析（PDF / 图片 / Office → Markdown + Images） | `marker` |
 | `kit.zvec_kit` | `ZvecKit` | zvec 本地向量库 | `zvec` |
 | `kit.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
 
@@ -106,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]"` |
@@ -117,6 +121,7 @@ uv add sdpy-kit
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
+| `marker` | MarkerKit 本地文档解析（marker-pdf[full] → Markdown + Images，依赖体积大） | `pip install "sdpy-kit[marker]"` |
 | `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
 
 ## 配置（.env）
@@ -161,6 +166,12 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 # MinerU（仅精准解析需要 Key，Agent 轻量解析免登录）
 # MINERU_API_KEY=
+
+# Marker（本地解析，可选依赖 sdpy-kit[marker]）
+# MARKER_MODE=fast              # None=按设备自动（GPU→balanced / CPU、MPS→fast）
+# MARKER_HF_ENDPOINT=https://hf-mirror.com
+# MARKER_HF_DISABLE_XET=true
+# MARKER_LLAMA_CPP_BINARY=
 ```
 
 ### 环境变量 ↔ 能力对照表
@@ -247,6 +258,17 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `MINERU_POLL_INTERVAL` | `2.0`（≥0.5） | 任务轮询间隔 |
 | `MINERU_MAX_WAIT` | `600`（≥10） | 轮询总超时，超时抛 `MinerUError` |
 
+**Marker** → `kit.marker_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `MARKER_MODE` | 无（不写入 config） | 解析模式 `balanced` / `fast`；不配置则由 marker 按设备自动选择（GPU→balanced，CPU、MPS→fast） |
+| `MARKER_HF_ENDPOINT` | `https://hf-mirror.com` | 模型权重下载入口（国内镜像）；置空则用 HuggingFace 官方源 |
+| `MARKER_HF_DISABLE_XET` | `true` | 禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起） |
+| `MARKER_LLAMA_CPP_BINARY` | 无 | `llama-server` 路径（非 NVIDIA 平台完整 VLM 能力）；未设置时沿用系统 `LLAMA_CPP_BINARY` |
+
+> 这四项由 kit 在**导入 marker 之前**经 `os.environ.setdefault` 应用：仅当用户未显式设置对应环境变量时生效，不覆盖显式配置。
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -261,7 +283,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | ① Settings 变量 | 固定，kit 定义 | 上表中除 `KIT_AI_CHAIN_TIMEOUT` 与密钥类之外的全部 | pydantic-settings 读 `.env` 与真实环境变量（后者优先），带类型与范围校验，缺失用默认值 |
 | ② 直读变量 | 固定，kit 代码直接读 `os.environ` | `KIT_AI_CHAIN_TIMEOUT` | 无类型校验，非法值告警后回退 |
 | ③ 档案声明变量 | **动态**，名字写在 JSON 里 | AI 的 `api_key`、MCP 的 `token_env` | **名字进 JSON、值进 `.env`**——所以档案文件可以安全入库，密钥留在环境里 |
-| ④ 第三方库变量 | 由依赖库定义 | `FIRECRAWL_API_KEY`、`FIRECRAWL_API_URL` | kit 只透传 `None`，由 anydoc 自己回落读取 |
+| ④ 第三方库变量 | 由依赖库定义 | `FIRECRAWL_API_KEY`、`FIRECRAWL_API_URL`（anydoc）；`HF_ENDPOINT` / `HF_HUB_DISABLE_XET` / `LLAMA_CPP_BINARY`（marker） | anydoc：kit 只透传 `None`，由其自行回落；marker：kit 在导入前按 `MARKER_*` 配置做 `os.environ.setdefault`（不覆盖显式设置） |
 
 ### 密钥解析优先级
 
@@ -277,7 +299,8 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 | 改动内容 | 生效时机 |
 |----------|----------|
-| `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`ZVEC_*`、`MINERU_*` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
+| `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`ZVEC_*`、`MINERU_*`、`MARKER_MODE` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
+| `MARKER_HF_ENDPOINT` / `MARKER_HF_DISABLE_XET` / `MARKER_LLAMA_CPP_BINARY` | 仅在 `import kit.marker_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | AI 密钥写在 `.env` 里 | `.env` 只在加载档案时注入一次 → 重启，或 `AI.reload_config(reload_file=True)` |
 | AI 密钥由自己写入 `os.environ` | `AI.reload_config()`（默认 `reload_file=False`，只重读 `os.environ`） |
 | `ai_models.json`（增删档案、换 model） | `AI.reload_config(reload_file=True)` |
@@ -313,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 |
 |----|------|--------|-------|
@@ -321,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` | 按主键查询 |
@@ -339,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` | 判断表是否存在 |
@@ -346,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()
@@ -369,31 +400,60 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
+> 注意两点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**，尤其 **MySQL 侧检索不可用**（见下）。
 
-### 2. SQLiteKit 独有方法
-
-无需额外依赖：
+### 2. 向量方法（三库同名同参，能力差异化）
 
-| 方法 | 说明 |
-|------|------|
-| `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` | 按单列等值取首行 |
-
-向量方法（需 `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, 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`** |
+| `vector_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
+
+**能力差异（跨库不可比较 `distance` 数值）**：
+
+| 项 | `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 拒绝向量列） |
+
+> 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
+# SQLite
+from kit.db.sqlite_kit import SQLiteKit
 SQLiteKit.create_vector_table("images", dims=384)
 SQLiteKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5)
+
+# PostgreSQL（签名相同；可选 COSINE/L2/L1/DOT/SQUARED_L2）
+from kit.db.pg_kit import PgKit
+PgKit.create_vector_table("images", dims=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")
+
+# MySQL（仅存储；search_vectors 会抛 NotImplementedError）
+from kit.db.mysql_kit import MySqlKit
+MySqlKit.create_vector_table("images", dims=384)
+MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 ```
 
 ### 3. CRUDBase（配合 session_scope，不自动提交）
@@ -458,10 +518,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
 ```
 
@@ -810,6 +876,46 @@ if r.state == "done":
 
 ---
 
+## kit.marker_kit —— 本地文档解析（Markdown + Images）
+
+安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf[full]`，含 torch 等 80+ 包，体积较大）
+
+```python
+from kit.marker_kit import MarkerKit
+
+# 落盘 md + images（推荐）：源文件同目录下建同名子目录
+md_path = MarkerKit.convert_to_dir("report.pdf")              # -> report/report.md + 图片
+md_path = MarkerKit.convert_to_dir("report.pdf", "out/doc")   # 指定产物目录
+
+# 只取 Markdown 文本（图片不落盘）
+md = MarkerKit.convert_to_md("report.pdf")
+
+# 安全转换（不抛异常，返回结果对象）
+result = MarkerKit.convert("report.pdf", "out/doc")
+if result.success:
+    print(result.md_path, len(result.image_paths), result.page_count)
+
+# 跳过 VLM（无需 llama.cpp）
+md = MarkerKit.convert_to_md("scan.pdf", disable_ocr=True)
+
+MarkerKit.shutdown()   # 释放模型与推理服务（幂等）
+```
+
+| 方法 | 说明 |
+|------|------|
+| `is_supported(file_path) -> bool` | 扩展名白名单（pdf / 图片 / docx / pptx / xlsx / html / epub） |
+| `convert_to_md(file_path, *, mode=None, force_ocr=None, disable_ocr=None, page_range=None) -> str` | 解析并返回 Markdown 文本（图片不落盘） |
+| `convert_to_dir(src_path, output_dir=None, *, mode=None, force_ocr=None, disable_ocr=None, page_range=None, extract_images=True) -> str` | 解析并落盘 md + images，返回 md 绝对路径 |
+| `convert(src_path, output_dir=None, *, ...) -> MarkerResult` | 安全版：失败封装为 `MarkerResult`，不抛异常 |
+| `shutdown() -> None` | 释放模型与共享推理服务（幂等） |
+
+> 产物：`<output_dir>/<源文件名>.md` + 图片文件（md 内相对路径引用），**不生成** `_meta.json`。
+> 结果类型：`MarkerResult`（`success` / `markdown` / `file_path` / `output_dir` / `md_path` / `image_paths` / `page_count` / `error`）；异常：`MarkerError`。
+> `mode` 缺省时不写入配置，交由 marker 按设备自动选择；首次使用会下载模型权重（默认走 `MARKER_HF_ENDPOINT` 镜像）。
+> 非 NVIDIA 平台完整 VLM 能力（公式 / 扫描页 OCR）需 llama.cpp 的 `llama-server`，否则用 `disable_ocr=True` 跳过。
+
+---
+
 ## kit.zvec_kit —— 本地向量库
 
 安装：`pip install "sdpy-kit[zvec]"`

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

@@ -5,7 +5,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
 - **MCP 客户端**：streamable-http / sse 双传输，档案驱动多服务器；
-- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / 向量库 / 微信公众号文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（md + images） / 向量库 / 微信公众号文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -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` |
@@ -24,6 +24,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
 | `kit.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
+| `kit.marker_kit` | `MarkerKit` | 本地文档解析（PDF / 图片 / Office → Markdown + Images） | `marker` |
 | `kit.zvec_kit` | `ZvecKit` | zvec 本地向量库 | `zvec` |
 | `kit.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
 
@@ -39,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]"` |
@@ -50,6 +51,7 @@ uv add sdpy-kit
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
+| `marker` | MarkerKit 本地文档解析（marker-pdf[full] → Markdown + Images，依赖体积大） | `pip install "sdpy-kit[marker]"` |
 | `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
 
 ## 配置（.env）
@@ -94,6 +96,12 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 # MinerU（仅精准解析需要 Key，Agent 轻量解析免登录）
 # MINERU_API_KEY=
+
+# Marker（本地解析，可选依赖 sdpy-kit[marker]）
+# MARKER_MODE=fast              # None=按设备自动（GPU→balanced / CPU、MPS→fast）
+# MARKER_HF_ENDPOINT=https://hf-mirror.com
+# MARKER_HF_DISABLE_XET=true
+# MARKER_LLAMA_CPP_BINARY=
 ```
 
 ### 环境变量 ↔ 能力对照表
@@ -180,6 +188,17 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `MINERU_POLL_INTERVAL` | `2.0`（≥0.5） | 任务轮询间隔 |
 | `MINERU_MAX_WAIT` | `600`（≥10） | 轮询总超时，超时抛 `MinerUError` |
 
+**Marker** → `kit.marker_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `MARKER_MODE` | 无（不写入 config） | 解析模式 `balanced` / `fast`；不配置则由 marker 按设备自动选择（GPU→balanced，CPU、MPS→fast） |
+| `MARKER_HF_ENDPOINT` | `https://hf-mirror.com` | 模型权重下载入口（国内镜像）；置空则用 HuggingFace 官方源 |
+| `MARKER_HF_DISABLE_XET` | `true` | 禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起） |
+| `MARKER_LLAMA_CPP_BINARY` | 无 | `llama-server` 路径（非 NVIDIA 平台完整 VLM 能力）；未设置时沿用系统 `LLAMA_CPP_BINARY` |
+
+> 这四项由 kit 在**导入 marker 之前**经 `os.environ.setdefault` 应用：仅当用户未显式设置对应环境变量时生效，不覆盖显式配置。
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -194,7 +213,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | ① Settings 变量 | 固定，kit 定义 | 上表中除 `KIT_AI_CHAIN_TIMEOUT` 与密钥类之外的全部 | pydantic-settings 读 `.env` 与真实环境变量（后者优先），带类型与范围校验，缺失用默认值 |
 | ② 直读变量 | 固定，kit 代码直接读 `os.environ` | `KIT_AI_CHAIN_TIMEOUT` | 无类型校验，非法值告警后回退 |
 | ③ 档案声明变量 | **动态**，名字写在 JSON 里 | AI 的 `api_key`、MCP 的 `token_env` | **名字进 JSON、值进 `.env`**——所以档案文件可以安全入库，密钥留在环境里 |
-| ④ 第三方库变量 | 由依赖库定义 | `FIRECRAWL_API_KEY`、`FIRECRAWL_API_URL` | kit 只透传 `None`，由 anydoc 自己回落读取 |
+| ④ 第三方库变量 | 由依赖库定义 | `FIRECRAWL_API_KEY`、`FIRECRAWL_API_URL`（anydoc）；`HF_ENDPOINT` / `HF_HUB_DISABLE_XET` / `LLAMA_CPP_BINARY`（marker） | anydoc：kit 只透传 `None`，由其自行回落；marker：kit 在导入前按 `MARKER_*` 配置做 `os.environ.setdefault`（不覆盖显式设置） |
 
 ### 密钥解析优先级
 
@@ -210,7 +229,8 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 | 改动内容 | 生效时机 |
 |----------|----------|
-| `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`ZVEC_*`、`MINERU_*` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
+| `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`ZVEC_*`、`MINERU_*`、`MARKER_MODE` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
+| `MARKER_HF_ENDPOINT` / `MARKER_HF_DISABLE_XET` / `MARKER_LLAMA_CPP_BINARY` | 仅在 `import kit.marker_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | AI 密钥写在 `.env` 里 | `.env` 只在加载档案时注入一次 → 重启，或 `AI.reload_config(reload_file=True)` |
 | AI 密钥由自己写入 `os.environ` | `AI.reload_config()`（默认 `reload_file=False`，只重读 `os.environ`） |
 | `ai_models.json`（增删档案、换 model） | `AI.reload_config(reload_file=True)` |
@@ -246,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 |
 |----|------|--------|-------|
@@ -254,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` | 按主键查询 |
@@ -272,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` | 判断表是否存在 |
@@ -279,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()
@@ -302,31 +330,60 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
+> 注意两点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**，尤其 **MySQL 侧检索不可用**（见下）。
 
-### 2. SQLiteKit 独有方法
-
-无需额外依赖：
+### 2. 向量方法（三库同名同参，能力差异化）
 
-| 方法 | 说明 |
-|------|------|
-| `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` | 按单列等值取首行 |
-
-向量方法（需 `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, 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`** |
+| `vector_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
+
+**能力差异（跨库不可比较 `distance` 数值）**：
+
+| 项 | `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 拒绝向量列） |
+
+> 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
+# SQLite
+from kit.db.sqlite_kit import SQLiteKit
 SQLiteKit.create_vector_table("images", dims=384)
 SQLiteKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5)
+
+# PostgreSQL（签名相同；可选 COSINE/L2/L1/DOT/SQUARED_L2）
+from kit.db.pg_kit import PgKit
+PgKit.create_vector_table("images", dims=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")
+
+# MySQL（仅存储；search_vectors 会抛 NotImplementedError）
+from kit.db.mysql_kit import MySqlKit
+MySqlKit.create_vector_table("images", dims=384)
+MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 ```
 
 ### 3. CRUDBase（配合 session_scope，不自动提交）
@@ -391,10 +448,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
 ```
 
@@ -743,6 +806,46 @@ if r.state == "done":
 
 ---
 
+## kit.marker_kit —— 本地文档解析（Markdown + Images）
+
+安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf[full]`，含 torch 等 80+ 包，体积较大）
+
+```python
+from kit.marker_kit import MarkerKit
+
+# 落盘 md + images（推荐）：源文件同目录下建同名子目录
+md_path = MarkerKit.convert_to_dir("report.pdf")              # -> report/report.md + 图片
+md_path = MarkerKit.convert_to_dir("report.pdf", "out/doc")   # 指定产物目录
+
+# 只取 Markdown 文本（图片不落盘）
+md = MarkerKit.convert_to_md("report.pdf")
+
+# 安全转换（不抛异常，返回结果对象）
+result = MarkerKit.convert("report.pdf", "out/doc")
+if result.success:
+    print(result.md_path, len(result.image_paths), result.page_count)
+
+# 跳过 VLM（无需 llama.cpp）
+md = MarkerKit.convert_to_md("scan.pdf", disable_ocr=True)
+
+MarkerKit.shutdown()   # 释放模型与推理服务（幂等）
+```
+
+| 方法 | 说明 |
+|------|------|
+| `is_supported(file_path) -> bool` | 扩展名白名单（pdf / 图片 / docx / pptx / xlsx / html / epub） |
+| `convert_to_md(file_path, *, mode=None, force_ocr=None, disable_ocr=None, page_range=None) -> str` | 解析并返回 Markdown 文本（图片不落盘） |
+| `convert_to_dir(src_path, output_dir=None, *, mode=None, force_ocr=None, disable_ocr=None, page_range=None, extract_images=True) -> str` | 解析并落盘 md + images，返回 md 绝对路径 |
+| `convert(src_path, output_dir=None, *, ...) -> MarkerResult` | 安全版：失败封装为 `MarkerResult`，不抛异常 |
+| `shutdown() -> None` | 释放模型与共享推理服务（幂等） |
+
+> 产物：`<output_dir>/<源文件名>.md` + 图片文件（md 内相对路径引用），**不生成** `_meta.json`。
+> 结果类型：`MarkerResult`（`success` / `markdown` / `file_path` / `output_dir` / `md_path` / `image_paths` / `page_count` / `error`）；异常：`MarkerError`。
+> `mode` 缺省时不写入配置，交由 marker 按设备自动选择；首次使用会下载模型权重（默认走 `MARKER_HF_ENDPOINT` 镜像）。
+> 非 NVIDIA 平台完整 VLM 能力（公式 / 扫描页 OCR）需 llama.cpp 的 `llama-server`，否则用 `disable_ocr=True` 跳过。
+
+---
+
 ## kit.zvec_kit —— 本地向量库
 
 安装：`pip install "sdpy-kit[zvec]"`

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

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

{sdpy_kit-0.1.14 → sdpy_kit-0.2.1}/kit/config/kit_config.py

@@ -121,6 +121,27 @@ class Settings(BaseSettings):
         default=600, ge=10, description="任务轮询总超时（秒），超时抛 MinerUError"
     )
 
+    # Marker 本地文档解析配置（marker-pdf，PDF→Markdown+Images，模型本地运行）
+    MARKER_MODE: str | None = Field(
+        default=None,
+        description=(
+            "解析模式：None=按设备自动（GPU→balanced，CPU/MPS→fast），"
+            "可设 balanced/fast"
+        ),
+    )
+    MARKER_HF_ENDPOINT: str = Field(
+        default="https://hf-mirror.com",
+        description="模型权重下载入口（默认国内镜像），置空则使用 HuggingFace 官方源",
+    )
+    MARKER_HF_DISABLE_XET: bool = Field(
+        default=True,
+        description="禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起）",
+    )
+    MARKER_LLAMA_CPP_BINARY: str | None = Field(
+        default=None,
+        description="llama-server 可执行文件路径（None 时沿用系统 LLAMA_CPP_BINARY）",
+    )
+
     class Config:
         env_file = ".env"
         env_file_encoding = "utf-8"