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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.1.14
+Version: 0.2.0
 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+
 
@@ -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 + 图片转存 | 无 |
 
@@ -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)` |
@@ -810,6 +833,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.0}/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+
 
@@ -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 + 图片转存 | 无 |
 
@@ -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)` |
@@ -743,6 +763,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.0}/kit/__init__.py

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

{sdpy_kit-0.1.14 → sdpy_kit-0.2.0}/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"

sdpy_kit-0.2.0/kit/marker_kit.py

@@ -0,0 +1,548 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-10-09
+"""Marker 本地文档解析工具类，将 PDF 等文档转为 Markdown + Images
+
+本模块基于 marker-pdf（Marker v2.x，https://github.com/datalab-to/marker），
+在本地解析 PDF / 图片 / Office / HTML / EPUB，输出 GitHub-Flavored Markdown
+并提取图片，产物形态对齐 kit.mineru_kit 的「md + images」。
+
+与 kit.anydoc_kit 的分工：
+- AnyDocKit：轻量文本转换（firecrawl-anydoc），只产出 Markdown 文本；
+- MarkerKit：本地模型解析，产出 md + 图片，质量更高但依赖重（torch 等）。
+
+设计要点：
+- 按需加载：依赖 marker-pdf，缺失时导入报错并提示
+  `pip install sdpy-kit[marker]`（可选依赖，不进入基础安装）。
+- 模型进程内单例：create_model_dict 开销极大（首次还要下载权重），
+  由类级缓存 + 线程锁保护；转换过程串行化，避免并发不稳定。
+- 导入 marker 之前先应用 HuggingFace 环境（镜像入口、禁用 Xet），
+  否则国内网络下模型权重下载会超时或挂起。
+- 低层 convert_to_md / convert_to_dir 直接抛出异常（便于精确定位）；
+  高层 convert 返回 MarkerResult 结果对象，便于批量处理。
+- 产物只落盘 md + images，不写 marker 默认的 _meta.json。
+- 日志消息不使用 emoji：Windows 默认 GBK 控制台无法编码 emoji，
+  会使 logging 抛出 UnicodeEncodeError。
+
+使用前准备（非 NVIDIA 平台）：
+- 首次使用会自动下载模型权重（默认走 MARKER_HF_ENDPOINT 镜像）；
+- 完整 VLM 能力（公式/扫描页 OCR）需 llama.cpp 的 llama-server，
+  可通过 MARKER_LLAMA_CPP_BINARY 指定；否则用 disable_ocr=True 跳过 VLM。
+"""
+
+import os
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from kit.config.kit_config import get_settings
+from kit.config.log_config import get_default_logger
+
+logger = get_default_logger(__name__)
+
+_settings = get_settings()
+
+# HuggingFace 相关环境必须在导入 marker / huggingface_hub 之前设置，否则不生效。
+# 统一使用 setdefault：仅当用户未显式设置环境变量时生效，不覆盖显式配置。
+if _settings.MARKER_HF_ENDPOINT:
+    os.environ.setdefault("HF_ENDPOINT", _settings.MARKER_HF_ENDPOINT)
+if _settings.MARKER_HF_DISABLE_XET:
+    os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+if _settings.MARKER_LLAMA_CPP_BINARY:
+    os.environ.setdefault("LLAMA_CPP_BINARY", _settings.MARKER_LLAMA_CPP_BINARY)
+
+try:
+    from marker.converters.pdf import PdfConverter
+    from marker.models import create_model_dict, shutdown_models
+    from marker.output import text_from_rendered
+except ImportError as e:
+    raise ImportError(
+        "marker_kit 需要可选依赖，请安装：pip install sdpy-kit[marker]"
+    ) from e
+
+# kit 维护的扩展名白名单（本地快速校验与错误提示）。
+# 注意：这是 marker 实际支持面的常用子集；marker-pdf[full] 另覆盖 epub/html 等，
+# 未列入的扩展名请在确认 marker 支持后按需增补。
+_SUPPORTED_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        # PDF
+        ".pdf",
+        # 图片
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".webp",
+        ".gif",
+        ".bmp",
+        # Office（marker-pdf[full]：mammoth / python-pptx / openpyxl）
+        ".docx",
+        ".pptx",
+        ".xlsx",
+        # 网页 / 电子书（marker-pdf[full]：weasyprint / ebooklib）
+        ".html",
+        ".epub",
+    }
+)
+
+# 支持的解析模式（marker 仅接受这两个取值）
+_MODE_CHOICES: frozenset[str] = frozenset({"balanced", "fast"})
+
+# 类型别名：解析模式
+_ModeLiteral = Literal["balanced", "fast"]
+
+
+class MarkerError(Exception):
+    """Marker 解析异常（模型加载失败 / 文档转换失败 / 产物落盘失败）"""
+
+
+@dataclass(frozen=True, slots=True)
+class MarkerResult:
+    """文档解析结果对象
+
+    由 MarkerKit.convert 返回，将成功与失败信息统一封装，调用方无需 try/except。
+
+    Attributes:
+        success: 解析是否成功
+        markdown: 解析出的 Markdown 文本，失败时为空字符串
+        file_path: 源文件绝对路径
+        output_dir: 产物目录绝对路径；未落盘时为 None
+        md_path: 落盘的 Markdown 文件绝对路径；未落盘时为 None
+        image_paths: 落盘的图片文件绝对路径元组
+        page_count: 文档页数，未知为 None
+        error: 失败原因描述（异常类型与信息），成功时为 None
+    """
+
+    success: bool
+    markdown: str
+    file_path: str
+    output_dir: str | None = None
+    md_path: str | None = None
+    image_paths: tuple[str, ...] = ()
+    page_count: int | None = None
+    error: str | None = None
+
+
+class MarkerKit:
+    """Marker 本地文档解析工具类，将文档转为 Markdown + Images
+
+    支持 PDF、图片、Office（docx/pptx/xlsx）、HTML、EPUB，产物形态对齐
+    kit.mineru_kit（md + 图片落盘于同一目录，md 以相对路径引用图片）。
+
+    使用前安装可选依赖::
+
+        pip install sdpy-kit[marker]
+
+    使用方式::
+
+        # 1. 落盘 md + images（推荐，返回 Markdown 文件绝对路径）
+        md_path = MarkerKit.convert_to_dir("report.pdf")            # 同目录下 report/
+        md_path = MarkerKit.convert_to_dir("report.pdf", "out/doc") # 指定产物目录
+
+        # 2. 只取 Markdown 文本（图片不落盘）
+        md = MarkerKit.convert_to_md("report.pdf")
+
+        # 3. 安全转换（不抛异常，返回结果对象）
+        result = MarkerKit.convert("report.pdf", "out/doc")
+        if result.success:
+            print(result.md_path, result.image_paths)
+
+        # 4. 纯文本层抽取（跳过 VLM，无需 llama.cpp）
+        md = MarkerKit.convert_to_md("scan.pdf", disable_ocr=True)
+
+        # 5. 进程退出前释放模型
+        MarkerKit.shutdown()
+
+    注意：
+    - 默认模式由 MARKER_MODE 决定，未配置时不写 mode，交由 marker 按设备自动
+      选择（CUDA→balanced，CPU/MPS→fast）；可用 mode 参数显式覆盖。
+    - 非 NVIDIA 平台完整 VLM 能力需 llama.cpp 的 llama-server，缺失时可通过
+      disable_ocr=True 跳过（公式与扫描页不做 OCR）。
+    - 建议串行调用；模型与转换过程由内部锁保护，不做多线程并发转换。
+    """
+
+    SUPPORTED_EXTENSIONS: frozenset[str] = _SUPPORTED_EXTENSIONS
+
+    # 进程内模型/转换器单例（create_model_dict 开销极大，只建一次）
+    _lock: threading.Lock = threading.Lock()
+    _converter: PdfConverter | None = None
+    _model_dict: dict | None = None
+    _config_signature: tuple[str, ...] | None = None
+
+    # ------------------------------------------------------------------
+    # 校验与内部工具
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def is_supported(file_path: str | Path) -> bool:
+        """检查文件格式是否受支持（依据扩展名）
+
+        Args:
+            file_path: 文件路径或文件名
+
+        Returns:
+            bool: 扩展名在白名单内返回 True
+
+        Example:
+            >>> MarkerKit.is_supported("report.pdf")
+            True
+            >>> MarkerKit.is_supported("report.xyz")
+            False
+        """
+        return Path(file_path).suffix.lower() in MarkerKit.SUPPORTED_EXTENSIONS
+
+    @staticmethod
+    def _validate_path(file_path: str | Path) -> Path:
+        """校验待解析文件（存在 / 是文件 / 扩展名受支持），返回绝对路径
+
+        Raises:
+            FileNotFoundError: 文件不存在
+            ValueError: 路径不是常规文件，或扩展名不受支持
+        """
+        path = Path(file_path).resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"文件不存在: {path}")
+        if not path.is_file():
+            raise ValueError(f"路径不是有效文件: {path}")
+        if not MarkerKit.is_supported(path):
+            raise ValueError(
+                f"不支持的文件格式: {path.suffix or '<无扩展名>'}，"
+                f"支持的格式: {', '.join(sorted(MarkerKit.SUPPORTED_EXTENSIONS))}"
+            )
+        return path
+
+    @staticmethod
+    def _build_config(
+        *,
+        mode: _ModeLiteral | None,
+        force_ocr: bool | None,
+        disable_ocr: bool | None,
+        page_range: str | None,
+    ) -> dict[str, object]:
+        """组装 Marker 解析配置（仅保留显式指定的项）
+
+        Args:
+            mode: 解析模式；None 时回落到 MARKER_MODE 配置
+            force_ocr: 是否强制全页 OCR；None 表示不指定（用 marker 默认）
+            disable_ocr: 是否禁用全部 VLM 调用；None 表示不指定
+            page_range: 页码范围（marker parse_range_str 口径，如 "0-5,7"）
+
+        Returns:
+            dict[str, object]: 传给 PdfConverter 的 config 字典
+
+        Raises:
+            ValueError: force_ocr 与 disable_ocr 同时为真，或 mode 取值非法
+        """
+        if force_ocr and disable_ocr:
+            raise ValueError("force_ocr 与 disable_ocr 不能同时为真")
+        resolved_mode = mode if mode is not None else _settings.MARKER_MODE
+        if resolved_mode is not None and resolved_mode not in _MODE_CHOICES:
+            raise ValueError(
+                f"不支持的解析模式: {resolved_mode}，可选 "
+                f"{', '.join(sorted(_MODE_CHOICES))}"
+            )
+        config: dict[str, object] = {}
+        if resolved_mode is not None:
+            config["mode"] = resolved_mode
+        if force_ocr is not None:
+            config["force_ocr"] = force_ocr
+        if disable_ocr is not None:
+            config["disable_ocr"] = disable_ocr
+        if page_range is not None:
+            config["page_range"] = page_range
+        return config
+
+    @classmethod
+    def _ensure_converter(cls, config: dict[str, object]) -> PdfConverter:
+        """获取（必要时构建）进程内共享的 PdfConverter（调用方需持锁）
+
+        模型字典只加载一次；当 config 变化（如切换 mode）时仅重建转换器，
+        复用已加载的模型。
+        """
+        if cls._model_dict is None:
+            logger.info("首次加载 Marker 模型（首次会下载权重，耗时较长）...")
+            cls._model_dict = create_model_dict()
+            logger.info("Marker 模型加载完成")
+        signature = tuple(f"{k}={config[k]}" for k in sorted(config))
+        if cls._converter is None or cls._config_signature != signature:
+            cls._converter = PdfConverter(
+                artifact_dict=cls._model_dict, config=dict(config)
+            )
+            cls._config_signature = signature
+        return cls._converter
+
+    @classmethod
+    def _render(
+        cls, path: Path, config: dict[str, object]
+    ) -> tuple[str, dict, int | None]:
+        """在锁内执行一次解析，返回 (markdown, images, page_count)
+
+        Args:
+            path: 已校验的源文件绝对路径
+            config: 解析配置
+
+        Returns:
+            tuple[str, dict, int | None]: Markdown 文本、图片字典、页数
+
+        Raises:
+            MarkerError: 模型加载或解析过程失败
+        """
+        with cls._lock:
+            try:
+                converter = cls._ensure_converter(config)
+                rendered = converter(str(path))
+                text, _ext, images = text_from_rendered(rendered)
+                page_count = converter.page_count
+            except Exception as e:  # noqa: BLE001 - marker 无统一异常基类
+                raise MarkerError(f"Marker 解析失败: {type(e).__name__}: {e}") from e
+        return text, images, page_count
+
+    @staticmethod
+    def _resolve_out_dir(src: Path, output_dir: str | Path | None) -> Path:
+        """解析产物目录：缺省为源文件同目录下与文件名同名的子目录"""
+        if output_dir is None:
+            return (src.parent / src.stem).resolve()
+        return Path(output_dir).resolve()
+
+    @staticmethod
+    def _write_outputs(
+        src: Path,
+        out_dir: Path,
+        markdown: str,
+        images: dict,
+        *,
+        extract_images: bool,
+    ) -> tuple[str, tuple[str, ...]]:
+        """落盘 Markdown 与图片，返回 (md 路径, 图片路径元组)
+
+        图片名取 basename 防路径穿越；统一转 RGB 后再存（RGBA 存 JPEG 会失败）。
+        """
+        out_dir.mkdir(parents=True, exist_ok=True)
+        md_path = out_dir / f"{src.stem}.md"
+        md_path.write_text(markdown, encoding="utf-8")
+
+        image_paths: list[str] = []
+        if extract_images:
+            for name, image in images.items():
+                target = out_dir / Path(name).name
+                image.convert("RGB").save(target)
+                image_paths.append(str(target))
+        return str(md_path), tuple(image_paths)
+
+    # ------------------------------------------------------------------
+    # 公开 API
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def convert_to_md(
+        cls,
+        file_path: str | Path,
+        *,
+        mode: _ModeLiteral | None = None,
+        force_ocr: bool | None = None,
+        disable_ocr: bool | None = None,
+        page_range: str | None = None,
+    ) -> str:
+        """将文档解析为 Markdown 文本（图片不落盘）
+
+        仅返回 Markdown 字符串；由于图片未落盘，md 内的图片相对引用会失效。
+        需要完整产物请使用 convert_to_dir。
+
+        Args:
+            file_path: 文档文件路径（支持 str 或 Path）
+            mode: 解析模式，None 时用 MARKER_MODE 配置，再 None 则交给 marker 自动
+            force_ocr: 是否强制全页 OCR；None 表示不指定
+            disable_ocr: 是否禁用全部 VLM 调用（无需 llama.cpp）；None 表示不指定
+            page_range: 页码范围，如 "0-5,7"
+
+        Returns:
+            str: 解析出的 Markdown 文本
+
+        Raises:
+            FileNotFoundError: 文件不存在
+            ValueError: 路径非法 / 扩展名不受支持 / 参数冲突
+            MarkerError: 模型加载或解析失败
+
+        Example:
+            >>> md = MarkerKit.convert_to_md("report.pdf")
+            >>> md = MarkerKit.convert_to_md("scan.pdf", disable_ocr=True)
+        """
+        path = cls._validate_path(file_path)
+        config = cls._build_config(
+            mode=mode,
+            force_ocr=force_ocr,
+            disable_ocr=disable_ocr,
+            page_range=page_range,
+        )
+        logger.info(f"开始 Marker 解析: {path.name}")
+        text, _images, _pages = cls._render(path, config)
+        logger.info(f"Marker 解析成功: {path.name}（{len(text)} 字符）")
+        return text
+
+    @classmethod
+    def convert_to_dir(
+        cls,
+        src_path: str | Path,
+        output_dir: str | Path | None = None,
+        *,
+        mode: _ModeLiteral | None = None,
+        force_ocr: bool | None = None,
+        disable_ocr: bool | None = None,
+        page_range: str | None = None,
+        extract_images: bool = True,
+    ) -> str:
+        """解析文档并将 Markdown + 图片落盘到目录
+
+        产物写入 output_dir：`<源文件名>.md` 与若干图片文件（md 以相对路径引用）。
+        不生成 marker 默认的 `_meta.json`。
+
+        Args:
+            src_path: 源文档路径
+            output_dir: 产物目录；None 时使用源文件同目录下与文件名同名的子目录
+            mode: 解析模式，None 时用 MARKER_MODE 配置，再 None 则交给 marker 自动
+            force_ocr: 是否强制全页 OCR；None 表示不指定
+            disable_ocr: 是否禁用全部 VLM 调用（无需 llama.cpp）；None 表示不指定
+            page_range: 页码范围，如 "0-5,7"
+            extract_images: 是否落盘图片（False 时仅写 md）
+
+        Returns:
+            str: 落盘的 Markdown 文件绝对路径
+
+        Raises:
+            FileNotFoundError: 源文件不存在
+            ValueError: 路径非法 / 扩展名不受支持 / 参数冲突
+            MarkerError: 模型加载或解析失败
+            OSError: 产物写入失败
+
+        Example:
+            >>> MarkerKit.convert_to_dir("report.pdf")            # 同目录 report/
+            >>> MarkerKit.convert_to_dir("report.pdf", "out/doc") # 指定目录
+        """
+        src = cls._validate_path(src_path)
+        out_dir = cls._resolve_out_dir(src, output_dir)
+        config = cls._build_config(
+            mode=mode,
+            force_ocr=force_ocr,
+            disable_ocr=disable_ocr,
+            page_range=page_range,
+        )
+        if not extract_images:
+            config["extract_images"] = False
+
+        logger.info(f"开始 Marker 解析: {src.name} -> {out_dir}")
+        text, images, _pages = cls._render(src, config)
+        md_path, image_paths = cls._write_outputs(
+            src, out_dir, text, images, extract_images=extract_images
+        )
+        logger.info(
+            f"Marker 解析成功: {src.name}（{len(text)} 字符，"
+            f"{len(image_paths)} 图）-> {md_path}"
+        )
+        return md_path
+
+    @classmethod
+    def convert(
+        cls,
+        src_path: str | Path,
+        output_dir: str | Path | None = None,
+        *,
+        mode: _ModeLiteral | None = None,
+        force_ocr: bool | None = None,
+        disable_ocr: bool | None = None,
+        page_range: str | None = None,
+        extract_images: bool = True,
+    ) -> MarkerResult:
+        """安全转换文档为 Markdown + Images，返回包含状态的结果对象
+
+        与 convert_to_dir 不同，本方法不抛出转换异常，而是将成功/失败信息封装到
+        MarkerResult 中，便于批量处理或状态检查。产物落盘规则同 convert_to_dir。
+
+        Args:
+            src_path: 源文档路径
+            output_dir: 产物目录；None 时使用源文件同目录下与文件名同名的子目录
+            mode: 解析模式，None 时用 MARKER_MODE 配置，再 None 则交给 marker 自动
+            force_ocr: 是否强制全页 OCR；None 表示不指定
+            disable_ocr: 是否禁用全部 VLM 调用；None 表示不指定
+            page_range: 页码范围，如 "0-5,7"
+            extract_images: 是否落盘图片
+
+        Returns:
+            MarkerResult: 解析结果（含 markdown / md_path / image_paths / error）
+
+        Example:
+            >>> result = MarkerKit.convert("report.pdf", "out/doc")
+            >>> if result.success:
+            ...     print(result.md_path, len(result.image_paths))
+            ... else:
+            ...     print(f"解析失败: {result.error}")
+        """
+        src = Path(src_path).resolve()
+        out_dir = cls._resolve_out_dir(src, output_dir)
+        try:
+            config = cls._build_config(
+                mode=mode,
+                force_ocr=force_ocr,
+                disable_ocr=disable_ocr,
+                page_range=page_range,
+            )
+            path = cls._validate_path(src)
+            if not extract_images:
+                config["extract_images"] = False
+            text, images, page_count = cls._render(path, config)
+            md_path, image_paths = cls._write_outputs(
+                path, out_dir, text, images, extract_images=extract_images
+            )
+        except Exception as e:  # noqa: BLE001 - 安全版统一封装为结果对象
+            logger.warning(f"Marker 解析失败: {src.name}（{type(e).__name__}）: {e}")
+            return MarkerResult(
+                success=False,
+                markdown="",
+                file_path=str(src),
+                output_dir=str(out_dir),
+                error=f"{type(e).__name__}: {e}",
+            )
+
+        logger.info(
+            f"Marker 解析成功: {path.name}（{len(text)} 字符，"
+            f"{len(image_paths)} 图）-> {md_path}"
+        )
+        return MarkerResult(
+            success=True,
+            markdown=text,
+            file_path=str(path),
+            output_dir=str(out_dir),
+            md_path=md_path,
+            image_paths=image_paths,
+            page_count=page_count,
+        )
+
+    @classmethod
+    def shutdown(cls) -> None:
+        """释放 Marker 模型与共享推理服务（幂等，可重复调用）
+
+        仅在本进程实际加载过模型时才有实际动作；释放后再次调用解析方法会重新加载。
+        """
+        with cls._lock:
+            if cls._model_dict is not None:
+                shutdown_models(cls._model_dict)
+                cls._model_dict = None
+                cls._converter = None
+                cls._config_signature = None
+                logger.info("Marker 模型已释放")

{sdpy_kit-0.1.14 → sdpy_kit-0.2.0}/pyproject.toml

@@ -51,6 +51,7 @@ dynamic = ["version"]
 #   anydoc → anydoc_kit（firecrawl-anydoc + pikepdf，显式声明）
 #   docx   → docx_kit（docxtpl + python-docx，模板动态填充）
 #   mineru → mineru_kit（requests）
+#   marker → marker_kit（marker-pdf[full]，本地模型解析 PDF→Markdown+Images）
 # 基础版 = config/log + kit.db 核心，SQLite 常规操作用标准库 sqlite3，零额外依赖。
 [project.optional-dependencies]
 pg = ["psycopg2-binary>=2.9.13"]
@@ -76,6 +77,7 @@ anydoc = [
 ]
 docx = ["docxtpl>=0.20.2"]
 mineru = ["requests>=2.34.2"]
+marker = ["marker-pdf[full]>=2.0.0"]
 all = [
     "psycopg2-binary>=2.9.13",
     "pymysql>=1.2.3",
@@ -92,6 +94,7 @@ all = [
     "pikepdf>=10.13.0",
     "docxtpl>=0.20.2",
     "requests>=2.34.2",
+    "marker-pdf[full]>=2.0.0",
 ]
 [tool.hatch.version]
 path = "kit/__init__.py"