zleap_parser

zleap_parser 是 zleap 公司开源的文档解析 SDK：把本地文件或远程 HTML URL 解析为 markdown，经 sag 提取结构化产物后由 octx 打包为可传播的 .octx Package，供下游项目以 pip 方式集成使用。

阅读顺序

1. 计划总览（plan/PLAN.md）：项目定位与规划
2. SDK 导入手册（docs/sdk/install.md）：环境要求、安装、快速上手
3. 配置手册（docs/sdk/configuration.md）：模块级一次配置，Parser/Connector 复用
4. 文档解析 API 手册（docs/sdk/parse_api.md）：Parser 用法与异常表
5. 连接器 API 手册（docs/sdk/connector_api.md）：数据源同步
6. 公共服务手册（docs/service/）：部署与 HTTP API

快速上手

需要 Python 3.11 或更高版本：

# 从 PyPI 安装
python -m pip install zleap_parser

# 音频/视频转写另需 ASR extra 与系统 ffmpeg
python -m pip install "zleap_parser[media]"

# 数据库连接器（DbAdapter / BigDbAdapter）按协议组安装驱动
python -m pip install "zleap_parser[db]"       # db_connector：MySQL/PostgreSQL/Oracle/SQL Server
python -m pip install "zleap_parser[bigdb]"    # bigdb_connector：StarRocks/ClickHouse/Doris 等
python -m pip install "zleap_parser[db-all]"   # db + bigdb 全部常用驱动（不含厂商私有驱动）

# RTF 与 Parser.parse(XLSX) 需系统安装 LibreOffice；RTF 另需 pdf extra
python -m pip install "zleap_parser[pdf]"
# 如 soffice/libreoffice 不在 PATH，可设置 ZLEAP_LIBREOFFICE_BIN

# 源码开发安装（本地仓库）
pip install -r requirements.txt   # 上游依赖（octx / zleap-sag / uuid6 / pycryptodome + 开发工具链）
pip install -e .                  # 可编辑安装，便于开发调试

# 使用 uv 运行音视频解析时启用 media extra
uv run --extra media python src/main.py doc/1.m4a

# URL 采集首次运行前安装并检查 Camoufox 浏览器二进制
python -m camoufox fetch
python -m camoufox version

模块级配置一次（llm 与 embedding 必填），Parser 与 Connector 自动继承复用：

import zleap_parser
from zleap_parser import (
    EmbeddingConfig,
    ImageProcessingConfig,
    LLMConfig,
    Parser,
    SearchMode,
    VLMConfig,
)

zleap_parser.config(
    llm=LLMConfig(base_url="https://api.xxx.com/v1", api_key="sk-...", model="qwen3.6-flash"),
    embedding=EmbeddingConfig(model="Qwen/Qwen3-Embedding-0.6B"),
    vlm=VLMConfig(model="qwen-vl"),  # 可选；配置 VLM 即启用 Markdown 图片识别
    image_processing=ImageProcessingConfig(min_short_edge=32),  # 可选；只调参，不是开关
)

parser = Parser()

# 本地文件走 magic bytes、格式适配器和文件内容缓存链路
result = parser.parse(file="/path/to/document.pdf", data_source_id="kb-docs")

# URL 只支持 HTML，走同步 Camoufox 正文采集链路
url_result = parser.parse(
    url="https://example.com/article",
    data_source_id="kb-news",
)

# 搜索返回标题、摘要、URL 与统一 usage；当前不调用模型，因此 usage 全 0
search_response = parser.search(
    keyword="zleap_parser",
    limit=10,
    exclude_urls=[],
    mode=SearchMode.NORMAL,
)
search_results = search_response["results"]
search_usage = search_response["usage"]

# 解析入口返回 {result: *.octx 归档文件路径, usage: 模型调用审计账本}
print(result["result"], result["usage"])
# usage 保留 prompt_tokens/completion_tokens/total_tokens，并包含：
# request_count / missing_usage_requests / complete / by_model
print(url_result["result"], url_result["usage"])
print(search_results, search_usage)

本地冒烟测试（读取根目录 .env 初始化配置）：

cp .env.example .env      # 填入 LLM / Embedding 配置
python src/main.py --list                 # 打印生效配置
python src/main.py tests/fixtures/sample.txt   # 解析本地文件
python src/main.py                        # 默认解析 tests/fixtures/ 下全部样例

支持的文件格式

本地文件按 内容优先 判定（magic bytes / 内容特征，不依赖扩展名），支持：

URL 输入仅支持 HTML 正文采集（parse(url=)），远程 PDF / 图片 / 普通文件不接受。

支持的连接器

深度抓取通过连接器返回 OCTX 数组；depth=0/1 只抓入口页，depth=2 包含入口页和下一层链接：

from zleap_parser.connector import Connector, DeepCrawlAdapter

result = Connector().fetch(
    adapter=DeepCrawlAdapter(
        url="https://example.com/",
        depth=2,
        max_pages=20,
    )
)
octx_paths = result["results"]  # [".../*.octx", ".../*.octx", ...]

数据库驱动按协议组懒加载：DbAdapter / BigDbAdapter 的 MySQL 组依赖 pymysql、PostgreSQL 组依赖 psycopg2、Oracle 组依赖 oracledb、SQL Server 组依赖 pymssql、ClickHouse 依赖 clickhouse-connect；虚谷 / GBase 8a / 达梦 / 崖山使用厂商官方驱动（可能需私有源）。SQLite 开箱即用（仅测试/冒烟）。完整清单与安装命令见 docs/sdk/install.md §2.1。

自定义数据源经 entry-points 分组 zleap_parser.connector.sources 接入，详见 connector_api.md。

要点

• 产出物统一为 *.octx 归档文件：可读 markdown + 稳定身份、版本、完整性信息及可选的 chunks、events、entities、vectors。

• 文件类型以 内容优先 判定：PDF、图片、OOXML、HTML、XML 等二进制/结构化格式优先按 magic bytes 或内容特征识别；普通文本在确认没有 NUL/control bytes 后，源码类文件再按受控扩展名或 Python shebang 细分。

• 配置：模块级 zleap_parser.config(...) 一次配置，Parser/Connector 自动继承；实例级 *.config() 与全局合并，便于高度自定义。搜索代理可通过 http_proxy= 或环境变量 HTTP_PROXY 配置，非空时优先使用代理。

• 网页搜索：parser.search(...) 并发聚合 Bing、Baidu、Google，按 URL 去重、应用 exclude_urls 并根据标题/摘要关键词命中排序；返回 {"results": [{title, summary, url}, ...], "usage": {...}}，不采集搜索结果正文，也不依赖 LLM/VLM/Embedding，因此当前 usage 恒为全 0。

• 用量审计：调用 SAG 的解析入口会累计该次流水线内全部 LLM/VLM 请求；顶层保留 prompt_tokens / completion_tokens / total_tokens，并返回 request_count、missing_usage_requests、complete 与按 kind/source/model 拆分的 by_model。Connector 汇总成功、部分失败、最终失败及数据源自身模型调用；SDK 异常通过 exc.usage 携带失败前已发生的用量。缓存命中和免模型路径返回“0 请求、complete=true”，网关缺少 usage 则为“请求数 > 0、complete=false”，两者不再混淆。

• 缓存：本地文件解析使用 Redis 或本地二级缓存；直接调用 Parser.parse(url=...) 仍每次重新采集； Connector 的 URL 文档使用 SQLite WAL + 磁盘 OCTX 产物缓存，同 URL 并发构建通过租约合并，缓存命中直接返回已有归档。

• URL 采集：只校验 HTTP(S) URL 格式，不执行 DNS/IP 类型判定；每次调用独立创建并关闭 Browser、Context、Page，不使用进程级信号量，多个线程可并发调用。正文提取、正文图片筛选和 Markdown 转换沿用参考 webcrawler 的规则语义，正文质量不足严格抛 ConversionError。

• URL 附件：成功渲染的 page.html 与成功下载的正文图片随 markdown_to_octx(source_files=[...]) 以同一 document_id 写入 OCTX；远程 PDF/图片/普通文件不接受。

• pdf 兜底链路：用户自定义适配器 → Docling → markitdown（其他兜底可追加）。

• rtf 链路：内容头识别 {\rtf → LibreOffice headless 转为临时 PDF，复用 PDF 兜底链路；依赖系统命令 soffice / libreoffice（可用 ZLEAP_LIBREOFFICE_BIN 指定路径），原始 RTF、生成 PDF 与 PDF 提取附件一并写入 OCTX。

• docx 兜底链路：用户自定义适配器 → Docling → markitdown；DOCX 内嵌图片随原文件写入 OCTX 附件。

• ppt 兜底链路：用户自定义适配器 → Docling → markitdown；按 OOXML 内容识别 PPTX，即使扩展名为 .ppt 也可解析。

• xlsx 表格链路：Parser.parse(file=..., data_source_id=...) 按 OOXML 内容识别 XLSX，原始 XLSX 只进入一次 zleap-sag 0.9 表格事项提取；LibreOffice 生成的 PDF 只用于 OCTX 预览，归档附件同时包含原始 XLSX 与 PDF。该原文件通道为保留通道，不允许自定义 XLSX→Markdown 适配器覆盖；缺少 LibreOffice 时能力查询不声明 XLSX 可用。

• db_connector 产物消费：DB/BigDB 查询结果结构化为 CSV 后，Connector.load(..., data_source_id=...) 正式路由到 csv_to_octx。原始 CSV 只进入一次 SAG 0.9；另行生成的 Markdown 表格仅写入 OCTX knowledge，不参与提取。pack_csv_to_octx / pack_xlsx_to_octx 仍为免 SAG 的知识-only 打包。

• 多模态图片识别：配置 VLMConfig 才启用；ImageProcessingConfig 只调参。vlm.model 不回退到文本模型，detail=None 时不发送 detail 字段，单图失败由 SAG 降级为 [IMAGE] ... 内容: 未获取成功 [/IMAGE] 并把状态写入 metadata，不中断整条流水线。

• 音视频 ASR 链路：音频/视频先由 FFmpeg 统一抽取为 16 kHz、16-bit、单声道 WAV 并做 -23 LUFS 响度归一化，再由 Docling Whisper 转写并执行说话人分离；输出复用聊天数据源的会话 Markdown 结构，包含相对时间段与 speaker_1、speaker_2 等说话人标签。

• 源码文本链路：txt 保持原文直出；java / javascript / python / tft 包装为带语言标识的 Markdown 代码块，避免源码被当作 Markdown 语法解析。

• 异常：所有 API 失败均抛 ZleapParserError 及子类（ConfigError / AdapterNotFoundError / ConversionError / DownloadError / TimeoutError / ExtractError），不裸奔底层异常；URL 采集编排层保留已有 SDK 异常，并将其他内部异常包装为 ConversionError。

异步与线程模型兼容性

• 同步 API、零线程模型假设：全部公开 API（Parser / Connector 各入口）为同步阻塞调用，不要求下游使用任何特定线程模型；SDK 不安装信号处理器、不修改全局事件循环策略、不在导入期启动线程。
• asyncio 收敛于 SDK 私有后台线程：上游 zleap-sag 的提取引擎为纯异步 API，SDK 将其收敛到单一私有后台事件循环线程（懒创建、守护线程、fork 后自动重建，见 zleap_parser.utils.run_async）：
  • 不在调用方线程创建/运行/关闭任何事件循环（不使用 asyncio.run / set_event_loop），调用方线程已有运行中的事件循环时亦可安全调用；
  • 调用方 contextvars（如用量采集 capture_usage 绑定）随协程传播，跨线程边界语义与同线程执行一致；
  • 多线程并发调用复用同一后台循环，无循环创建/销毁 churn。
• gevent / eventlet / uvloop 等环境已验证：tests/test_async_compat.py 以子进程方式在 gevent.monkey.patch_all()、eventlet.monkey_patch()、uvloop 事件循环策略下验证 import、run_async（含 greenlet/线程/已有运行中循环三种调用形态）、用量采集、缓存读写与连接器构造均自包含运行，且不干扰宿主自身调度。
• 已知边界：URL 采集依赖 Camoufox（内部 Playwright 自带线程/事件循环），该链路不与 SDK 后台循环共享；若宿主 monkey-patch 与 Playwright 冲突，本地文件解析与 *.octx 打包链路不受影响。

边界

• 搜索 API 只负责搜索结果元数据聚合，不提供召回排序模型、结果正文采集或 Agent 协议。
• 核心解析框架与格式实现解耦：新增格式即新增适配器，不改核心代码。
• 上游参考实现：sag（markdown 结构化提取）与 octx（*.octx 打包）位于本地仓库 ../SAG 与 ../open-context。
• URL 正文规则直接复制 MinerU HTML webcrawler 的正文抽取器（本地命名为 article_extractor.py）；许可与归属见 THIRD_PARTY_NOTICES.md 及 LICENSES/。