从复杂文档中提取干净数据 ⚡

thepi.pe 是一个能够从复杂文档中抓取干净的 Markdown、多模态媒体和结构化数据的工具包。它在底层使用视觉语言模型（VLM）以实现更高质量的输出，并且可以与任何 LLM、VLM 或向量数据库开箱即用。它可以从多种来源中提取格式良好的数据，包括 PDF、URL、Word 文档、PowerPoint 演示文稿、Python 笔记本、视频、音频等。

特性 🌟

• 从任何文档中抓取干净的 Markdown、表格和图片
• 从任何文件或 URL 中抓取文本、图片、视频和音频
• 可与视觉语言模型、向量数据库和 RAG 框架开箱即用
• 原生 AI 的文件类型检测、布局分析和结构化数据提取
• 支持广泛的输入源，包括 PDF、URL、Word 文档、PowerPoint 演示文稿、Python 笔记本、GitHub 仓库、视频、音频等

5 分钟快速入门 🚀

可以通过命令行安装 thepipe：

pip install thepipe-api

默认安装仅包含对 CPU 友好的依赖项，因此适用于资源受限的环境和 CI 系统。而像 PyTorch 和 Triton 这样的 GPU 加速库则作为可选依赖项提供。

可选依赖

该包提供了一系列可选依赖，允许用户按需选择更重的依赖：

选项	安装内容	适用场景
thepipe-api[audio]	openai-whisper	使用 Whisper 进行本地音频/视频转录。
thepipe-api[semantic]	sentence-transformers	使用 Transformer 嵌入进行语义分块。
thepipe-api[llama-index]	llama-index	将 Chunk 转换为 LlamaIndex 格式。
thepipe-api[gpu]	PyTorch + Whisper + Sentence Transformers	全面 GPU 加速，适用于 VLM 微调任务。

如果您使用的机器仅支持 CPU，但仍需要依赖 PyTorch 的功能，请先从 PyTorch 官方索引直接安装 CPU 版本的轮子，然后再添加相应的额外依赖。例如：

pip install torch==2.5.1+cpu torchvision==0.20.1+cpu torchaudio==2.5.1+cpu \
  --index-url https://download.pytorch.org/whl/cpu
pip install thepipe-api[semantic]

如果需要处理包含丰富媒体的来源，如网页、视频和音频，您可以选择安装以下系统依赖：

apt-get update && apt-get install -y git ffmpeg
python -m playwright install --with-deps chromium

然后使用全局安装方式通过 pip 安装：

pip install thepipe-api[all]

默认设置（OpenAI）

默认情况下，thepi.pe 使用 OpenAI API，因此只要传入 OpenAI 客户端，VLM 功能即可开箱即用。

自定义 VLM 服务器设置（OpenRouter、OpenLLM 等）

如果您希望使用本地视觉语言模型或其他云服务提供商，可以提供自定义的 OpenAI 客户端。例如，将基础 URL 设置为 https://openrouter.ai/api/v1 以使用 OpenRouter；或者设置为 http://localhost:3000/v1 来连接本地服务器，如 OpenLLM。请注意，您还需要将非 OpenAI 云服务提供商的 API 密钥传递给 OpenAI 客户端。模型名称可以通过 model 参数进行更改，默认为 gpt-4o。

抓取

from thepipe.scraper import scrape_file

# 从 PDF 中抓取文本和页面图片
chunks = scrape_file(filepath="paper.pdf")

若要使用视觉语言模型增强抓取效果，可以传入兼容 OpenAI 的客户端和模型名称。

from openai import OpenAI
from thepipe.scraper import scrape_file

# 创建一个兼容 OpenAI 的客户端
client = OpenAI()

# 从 PDF 中抓取干净的 Markdown 和页面图片
chunks = scrape_file(
  filepath="paper.pdf",
  openai_client=client,
  model="gpt-4o"
)

分块

为了满足 token 数量限制，提供了以下几种分块方法，可以将内容拆分为更小的片段：

• chunk_by_document: 返回包含整个文件内容的一个块。
• chunk_by_page: 按每页返回一个块（例如：每个网页、PDF 页面或 PowerPoint 幻灯片）。
• chunk_by_length: 按长度分割块。
• chunk_by_section: 按 Markdown 段落分割块。
• chunk_by_keyword: 在关键词处分割块。
• chunk_semantic（实验性功能，需安装 sentence-transformers）：根据语义变化的突变点分割块，可配置阈值。
• chunk_agentic（实验性功能，需安装 OpenAI）：由 LLM 代理尝试找到语义上有意义的部分来分割块。

例如：

from thepipe.scraper import scrape_file
from thepipe.chunker import chunk_by_document, chunk_by_page

# 可选地指定分块方法
# chunk_by_document 返回整个文档的一个块
chunks = scrape_file(
  filepath="paper.pdf",
  chunking_method=chunk_by_document
)

# 也可以稍后再重新分块。
# chunk_by_page 每页返回一个块（例如：每个网页、PDF 页面或 PowerPoint 幻灯片）。
chunks = chunk_by_page(chunks)

OpenAI 聊天集成 🤖

from openai import OpenAI
from thepipe.core import chunks_to_messages

# 初始化 OpenAI 客户端
client = OpenAI()

# 使用 OpenAI 格式的聊天消息
messages = [{
  "role": "user",
  "content": [{
      "type": "text",
      "text": "这篇论文讲的是什么？"
    }]
}]

# 直接将抓取到的块添加到消息中
messages += chunks_to_messages(chunks)

# 调用大语言模型
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
)

chunks_to_messages 接受一个可选的 text_only 参数，用于仅输出源文档中的文本内容。这对于下游使用缺乏多模态能力的大语言模型非常有用。

⚠️ 务必注意模型的令牌限制。 请确保您的提示词在模型的令牌限制范围内。您可以通过分块将消息拆分为更小的片段。

LLamaIndex 集成 🦙

安装可选的额外依赖项，然后调用 .to_llamaindex：

pip install thepipe-api[llama-index]

安装完成后，可以使用 .to_llamaindex 将分块转换为 LlamaIndex 的 Document 或 ImageDocument。如果没有安装该额外依赖，系统会抛出一条友好的错误信息，而不是在导入时直接失败。

结构化提取 🗂️

请注意，结构化提取功能即将弃用，并将在未来的版本中移除。当前的实现只是对 OpenAI 聊天 API 的简单封装，这并不适合用于结构化数据的提取。我们建议使用 OpenAI 的 结构化输出 功能来进行结构化数据提取，或者使用 Trellis AI 来构建基于结构化数据的自动化工作流。

from thepipe.extract import extract
from openai import OpenAI

client = OpenAI()

schema = {
  "description": "string",
  "amount_usd": "float"
}

results, tokens_used = extract(
    chunks=chunks,
    schema=schema,
    multiple_extractions=True,  # 每个分块提取多行数据
    openai_client=client
)

运行测试套件 🧪

安装基础依赖以及您所依赖的任何额外依赖，然后执行以下命令：

pip install -r requirements.txt
python -m unittest discover

依赖于可选额外组件（如 Whisper、Sentence Transformers、LlamaIndex）或 OpenAI API 密钥的测试，在相应依赖不可用时会自动跳过。

赞助商

请考虑通过 成为赞助商 来支持 thepipe。您的支持不仅有助于我维护和改进该项目，还能帮助开源社区发现您的工作成果。

访问 Cal.com，这是一款开源的日程安排工具，可帮助您轻松预约会议。对于希望简化日程安排流程的繁忙专业人士来说，它是一个理想的解决方案。

如果您正在寻找企业级的文档处理和智能自动化解决方案，请了解 Trellis AI 如何优化您的工作流程并提升生产力。

工作原理 🛠️

thepipe 结合计算机视觉模型和启发式规则，从源文档中提取干净的内容，并将其处理以供下游使用，例如大型语言模型（LLM）或视觉-语言模型（VLM）。您可以将这些消息直接输入到模型中，也可以先对其进行分块，然后存储到向量数据库中，比如 ChromaDB、LLamaIndex 或其他类似的 RAG 框架。

支持的文件类型 📚

来源	输入类型	多模态	备注
网页	以 http、https、ftp 开头的 URL	✔️	从网页中抓取 Markdown、图片和表格。通过传递 OpenAI 客户端进行截图分析，可实现 AI 提取功能
PDF	.pdf	✔️	提取页面的 Markdown 和页面图片。在处理复杂或扫描文档时，若提供 OpenAI 客户端，则可进行 AI 提取
Word 文档	.docx	✔️	提取文本、表格和图片
PowerPoint	.pptx	✔️	提取幻灯片中的文本和图片
视频	.mp4、.mov、.wmv	✔️	使用 Whisper 进行转录，并提取视频帧
音频	.mp3、.wav	✔️	使用 Whisper 进行转录
Jupyter Notebook	.ipynb	✔️	提取 Markdown、代码、输出和图片
电子表格	.csv、.xls、.xlsx	❌	将每一行转换为 JSON 格式，包括每行的索引号
纯文本	.txt、.md、.rtf 等	❌	简单的文本提取
图片	.jpg、.jpeg、.png	✔️	在纯文本模式下使用 VLM 进行 OCR
ZIP 文件	.zip	✔️	解压并处理其中的文件
目录	任何 path/to/folder	✔️	递归处理目录中的所有文件。可选地使用 inclusion_pattern 传入正则表达式字符串，以指定包含文件的规则。
YouTube 视频（已知问题）	以 https://youtube.com 或 https://www.youtube.com 开头的 YouTube 视频 URL	✔️	使用 pytube 下载视频，并使用 Whisper 进行转录。为确保提取的一致性，可能需要修改 pytube 的安装，以发送有效的用户代理头（参见 此问题）。
推文	以 https://twitter.com 或 https://x.com 开头的 URL	✔️	使用非官方 API，可能会意外中断
GitHub 仓库	以 https://github.com 或 https://www.github.com 开头的 GitHub 仓库 URL	✔️	需要设置 GITHUB_TOKEN 环境变量

配置与环境

通过设置以下环境变量来控制 API 密钥、托管服务和模型默认值：

# 如果希望长期存储和托管图片（保存到 ./images 并通过 HOST_URL 提供服务）
export HOST_IMAGES=true

# 用于通过 `scrape_url` 抓取私有/公共仓库的 GitHub Token
export GITHUB_TOKEN=ghp_...

# 控制抓取的默认设置
export DEFAULT_AI_MODEL=gpt-4o
export DEFAULT_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
export FILESIZE_LIMIT_MB=50

# 音频转录的最大时长（单位：秒）
export MAX_WHISPER_DURATION=600

# 网页文件大小限制（单位：MB）
export FILESIZE_LIMIT_MB = 50

# 用于爬取仓库的凭据
export GITHUB_TOKEN=...

CLI 使用方法

thepipe <source> [options]

AI 爬取选项

--openai-api-key=KEY 要启用 VLM 爬取，请传入您的 OpenAI API 密钥。

--openai-model=MODEL 用于爬取的模型（默认为 DEFAULT_AI_MODEL，当前为 gpt-4o）。

--openai-base-url=URL 自定义 LLM 端点，适用于本地 LLM 或像 OpenRouter 这样的托管 API（默认：https://api.openai.com/v1）。

--ai_extraction ⚠️ 已弃用；将从 OPENAI_API_KEY 环境变量中获取 API 密钥。

通用爬取选项

--text_only 仅输出文本（禁用图片）

--inclusion_pattern=REGEX 只包含其_完整路径*匹配正则表达式的文件（适用于目录/压缩包）。

--verbose 打印详细的进度信息。

贡献说明

本包在设计和实现上具有较强的主观性。部分模块与整体架构紧密耦合，而另一些模块则被设计为可灵活修改的。

在贡献代码之前，请先在 GitHub 上创建一个议题，讨论您的想法以及最佳实现方式。未遵循此流程的拉取请求将被关闭。

thepipe 快速上手指南

thepipe 是一个能够从复杂文档（如 PDF、URL、Word、PPT、视频等）中提取干净 Markdown、多模态媒体和结构化数据的 Python 库。它底层利用视觉语言模型（VLM）确保输出质量，并原生支持各类 LLM、VLM 及向量数据库。

环境准备

系统要求

• Python: 建议 Python 3.8+
• 操作系统: Linux, macOS, Windows
• 硬件: 默认安装仅依赖 CPU，适合受限环境。若需 GPU 加速或处理多媒体，需额外配置。

前置依赖

若需完整功能（特别是处理网页、视频和音频），建议在安装前配置以下系统级依赖：

Linux (Debian/Ubuntu):

apt-get update && apt-get install -y git ffmpeg
python -m playwright install --with-deps chromium

注意: 国内用户若遇到 playwright 下载慢的问题，可配置国内镜像或使用代理。

安装步骤

1. 基础安装（推荐）

默认安装仅包含 CPU 友好的依赖，适合大多数场景：

pip install thepipe-api

国内加速建议:

pip install thepipe-api -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 可选扩展安装

根据需求按需安装重型依赖：

扩展名称	命令	用途
音频处理	pip install thepipe-api[audio]	本地音视频转录 (Whisper)
语义分块	pip install thepipe-api[semantic]	基于 Transformer 的语义分块
LlamaIndex	pip install thepipe-api[llama-index]	转换为 LlamaIndex 格式
全套功能	pip install thepipe-api[all]	包含所有上述功能及 GPU 支持

GPU 环境特别说明: 若在纯 CPU 机器上需要 PyTorch 相关功能，请先安装 CPU 版 PyTorch：

pip install torch==2.5.1+cpu torchvision==0.20.1+cpu torchaudio==2.5.1+cpu --index-url https://download.pytorch.org/whl/cpu
pip install thepipe-api[semantic]

基本使用

1. 配置 API Key

thepipe 默认使用 OpenAI 兼容接口。请确保环境变量中已设置 OPENAI_API_KEY，或在代码中传入客户端。若使用国内大模型或其他兼容接口（如 OpenRouter），可自定义 base_url。

2. 提取文档内容

以下示例展示如何从 PDF 中提取干净的 Markdown 和图片块：

from openai import OpenAI
from thepipe.scraper import scrape_file

# 初始化 OpenAI 兼容客户端
# 若使用非 OpenAI 服务，可指定 base_url，例如: base_url="https://api.moonshot.cn/v1"
client = OpenAI()

# 提取内容
chunks = scrape_file(
    filepath="paper.pdf",       # 支持 pdf, docx, url, mp4 等
    openai_client=client,       # 传入客户端以启用 VLM 增强提取
    model="gpt-4o"              # 指定模型，默认为 gpt-4o
)

# 打印提取结果
for chunk in chunks:
    print(chunk.text)
    if chunk.images:
        print(f"Found {len(chunk.images)} images")

3. 对接 LLM 进行问答

将提取的内容直接转换为 Chat 消息格式，发送给大模型：

from openai import OpenAI
from thepipe.core import chunks_to_messages

client = OpenAI()

# 构建提示词
messages = [{
    "role": "user",
    "content": [{"type": "text", "text": "这篇论文主要讲了什么？"}]
}]

# 将提取的块转换为消息格式并追加
messages += chunks_to_messages(chunks)

# 调用大模型
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
)

print(response.choices[0].message.content)

4. 内容分块 (Chunking)

为避免超出 Token 限制，可使用内置方法对内容进行分块：

from thepipe.chunker import chunk_by_page

# 按页分块（适用于 PDF、PPT 或网页）
paginated_chunks = chunk_by_page(chunks)