doc7：利用视觉理解将任何文档转换为AI就绪的Markdown
doc7使用您自己的多模态模型，将PDF、Office文件、扫描件和图表转换为AI就绪的Markdown，消除了OCR堆栈和按页收费。
doc7：利用视觉理解将任何文档转换为AI就绪的Markdown
如果您曾尝试将PDF或扫描文档输入AI管道，您会知道其中的痛苦。传统的提取工具依赖OCR和布局解析器，这些工具常常会破坏表格、丢失公式，并且完全无法理解图表的意义。doc7采用了不同的方法：它不是逐字符解析文档，而是将每一页渲染为图像，并让视觉语言模型（VLM）读取整个页面，理解布局、关系和上下文。结果是干净、可搜索的Markdown，您的AI可以真正基于它进行推理。
为什么视觉理解优于传统提取
大多数文档转Markdown工具可分为三类：
- 格式和文本提取（如MarkItDown的默认路径）：这些工具使用特定于文件的解析器来提取文本和基本结构。它们适用于简单的文本文件，但在复杂布局、扫描页面或任何具有视觉意义的内容上会失败。
- 视觉模型OCR包装器（如Zerox）：这些工具将页面转换为图像并发送到视觉API，但它们通常绑定到特定提供商，并且需要额外的依赖项，如GraphicsMagick。
- 专用文档AI堆栈（如MinerU或Docling）：这些工具运行OCR、布局、表格和公式模型的管道。它们功能强大但重量级——您需要管理多个模型权重和基础设施。
doc7跳过了所有这些。它将每一页渲染为图像，并发送给您选择的任何兼容OpenAI的多模态模型。模型看到整个页面——文本、表格、图表、图示，甚至元素之间的空间关系——并直接输出Markdown。这意味着没有OCR堆栈，没有按页收费，也没有对文档处理服务的锁定。
快速开始：从零到Markdown只需几分钟
开始使用非常简单。使用一行命令安装doc7，将其指向本地视觉模型（例如在LM Studio或Ollama中运行的模型），然后转换您的第一个文档：
# macOS或Linux
curl -fsSL https://raw.githubusercontent.com/magicrew/doc7/main/scripts/install.sh | bash
# Windows PowerShell
irm https://raw.githubusercontent.com/magicrew/doc7/main/scripts/install.ps1 | iex
# 转换文档
doc7 report.pdf
首次运行会自动发现本地模型端点（LM Studio和Ollama），如果有多个模型可用，让您选择一个，并在保存选择之前验证图像理解。本地端点无需API密钥。
真实基准测试：doc7 vs. MarkItDown vs. Docling
该项目包含一个开放的基准测试，展示了为什么视觉理解很重要。他们取了两份仅栅格化的PDF（无文本层），并检查了15个机器可验证的视觉事实。使用相同的qwen3.5-9b模型通过相同的本地端点，doc7恢复了15/15个事实，而MarkItDown及其OCR插件获得了9/15，Docling的标准管道仅获得了3/15。
以下是详细情况：
| 系统 | 注意力论文 | 视觉报告 | 合计 | 原始Markdown |
|---|---|---|---|---|
| doc7 + qwen3.5-9b | 7/7 | 8/8 | 15/15 | 5,293字节 |
| MarkItDown 0.1.6 + OCR 0.1.0 + qwen3.5-9b | 3/7 | 6/8 | 9/15 | 13,142字节 |
| Docling 2.113.0标准 | 1/7 | 2/8 | 3/15 | 2,571,445字节 |
| MarkItDown 0.1.6默认 | 不适用 | 不适用 | 不适用 | 0字节 |
MarkItDown的默认路径对两个仅栅格化输入返回空文件，因此标记为不适用。Docling的原始Markdown很大，因为它将页面图像嵌入为Base64——这不是质量分数，只是诊断信息。
该基准测试完全可复现：每个原始输出、SHA-256摘要、评分规则和机器可读结果都提交到仓库中。您可以自己运行并验证结果。
一个管道适用于所有格式
doc7的优势之一是其格式覆盖范围。无论您处理的是PDF、Office文档、扫描件、截图、图表、公式还是图示，它们都通过相同的视觉理解管道。输出是单个Markdown文档，保留：
- 标题、段落、列表、引用和代码 → 原生Markdown结构
- 表格和电子表格 → 带值和单位的Markdown或HTML表格
- 数学符号 → 内联或显示LaTeX
- 图表 → 标签、值、趋势和结论作为可搜索文本
- 图示和工作流 → 节点、顺序、分组和关系
- 截图和应用状态 → 可见状态、错误、控件和操作
- 电子邮件 → 标题、HTML或文本正文、内联图像和附件清单
- Jupyter笔记本 → Markdown单元格、源代码、执行计数、文本输出、回溯和视觉输出
支持的输入格式包括PDF、DOCX、PPTX、XLSX、EPUB、EML、MHTML、MSG、IPYNB、图像（PNG、JPEG、GIF、WebP、BMP、TIFF、SVG），甚至原生文本/数据格式如Markdown、CSV、JSON、XML和YAML。Office和OpenDocument文件需要LibreOffice；PDF渲染在可用时使用MuPDF；HTML、SVG、EPUB和电子邮件格式需要Chrome、Chromium或Edge。
围绕CLI构建
命令行界面是doc7的核心。它提供了从简单转换到高级功能（如页面选择、恢复和批处理）的一切。
页面选择和恢复
长文档可以分块处理，失败页面可以重试而无需从头开始：
# 仅处理第5页和第7页
doc7 read report.pdf -o report-pages-5-7 --pages 5,7
# 恢复之前的运行，重试失败的页面
doc7 read report.pdf -o report-doc7 --resume
清单记录源页面计数和页面选择，成功的页面保持逐字节不变。如果没有失败的页面，--resume会验证工件并重建合并的Markdown，而无需调用模型。
管道和标准输入
您可以将合并的Markdown直接管道到另一个工具：
doc7 read report.pdf --stdout > report.md
# 或从标准输入读取
cat report.pdf | doc7 read - --stdin-name report.pdf --stdout > report.md
远程文档和目录
# 递归读取目录
doc7 read ./documents -o ./knowledge
# 读取远程文档
doc7 read https://example.com/report.pdf -o ./report-doc7
作为服务运行
为了集成到更大的系统中，doc7可以作为异步HTTP服务运行：
doc7 serve --addr 127.0.0.1:8787 --data-dir ./doc7-server
提交文档或ZIP存档：
curl -F [email protected] http://127.0.0.1:8787/v1/jobs
响应包含作业ID。轮询状态URL，然后下载合并的Markdown或完整的工件ZIP：
curl http://127.0.0.1:8787/v1/jobs/<job-id>
curl -o report.md http://127.0.0.1:8787/v1/jobs/<job-id>/markdown
curl -o report-artifacts.zip http://127.0.0.1:8787/v1/jobs/<job-id>/artifacts
您甚至可以在作业中恢复失败的页面：
curl -X POST -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:8787/v1/jobs/<job-id>/resume
安全性内置：服务默认绑定localhost，对于非本地绑定地址需要bearer令牌，限制上传大小，并隔离每个作业目录。
从AI工具使用：MCP服务器
doc7包含一个带有类型化convert_to_markdown工具的MCP服务器。配置您的MCP客户端通过stdio启动二进制文件：
{
"mcpServers": {
"doc7": {
"command": "/absolute/path/to/doc7",
"args": ["mcp"],
"env": {
"DOC7_BASE_URL": "http://127.0.0.1:1234/v1",
"DOC7_MODEL": "qwen3.5-0.8b",
"DOC7_CREDENTIAL_STORE": "env"
}
}
}
}
该工具接受本地路径、目录、HTTP(S) URL或ZIP存档，并返回Markdown以及结构化转换元数据。
在Go中嵌入
公共Go包暴露了相同的转换引擎。以下是一个最小示例：
package main
import (
"context"
"log"
"github.com/magicrew/doc7"
)
func main() {
options := doc7.DefaultReadOptions()
options.OutputDir = "report-doc7"
options.BaseURL = "http://127.0.0.1:1234/v1"
options.Model = "qwen3.5-4b"
result, err := doc7.Read(context.Background(), "report.pdf", options)
if err != nil {
log.Fatal(err)
}
if result.Document != nil {
log.Println(result.Document.MergedMarkdown)
}
}
您还可以使用Convert和ConvertBatch进行显式的单文档或仅目录API。
成本和隐私：您的模型，您的基础设施
doc7不销售文档积分或按页收费。您自带多模态模型——本地或私有——并处理您的硬件可以处理的任意数量的文档。另一个文档的边际成本只是电力和运行时间。
这与云文档API的成本结构根本不同：
| 选项 | 典型计费单位 | 文档量增长时的成本 | 文档位置 |
|---|---|---|---|
| doc7 + 本地量化VLM | 无doc7按页费用 | 主要是现有硬件、电力和运维 | 本地或私有基础设施 |
| AWS Textract | 按页，按API和分析功能定价 | 使用量随页面和功能增长 | 云API |
| Google Document AI | 按页，通常按处理器和容量层级定价 | 使用量随页面和处理器类型增长 | 云API |
| Azure Document Intelligence | 按页、模型和定价层级 | 使用量随页面和所选能力增长 | 云API |
| 阿里云OCR | 按量付费或预付费套餐 | 持续处理消耗调用或配额 | 云API |
| 腾讯云OCR | 通过预付费或后付费计费的API调用 | 持续处理消耗调用或配额 | 云API |
| 百度AI云OCR | API调用，免费配额和付费使用 | 持续处理消耗调用或配额 | 云API |
当您想要托管容量并且不想操作模型时，云API仍然有用。但如果您想消除经常性的文档解析器账单并保持文档私有，doc7是可行的方法。
高级功能
文本接地
对于具有嵌入文本层的PDF和Office文件，您可以启用可选的精确值检查：
doc7 read report.pdf --text-grounding
这不会用提取的文本替换视觉结果。相反，它检查嵌入文本层中的精确数字、代码和标识符，并要求视觉模型确认候选更正。默认关闭，可能会产生额外的模型请求。
上下文回退
如果模型的上下文窗口对于页面来说太小，doc7会自动使用较低分辨率的图像重试。您可以使用--context-fallbacks和--min-image-dimension进行配置。如果所有回退都用尽，页面将被标记为失败，而不是写入截断的Markdown。
自定义提示
您可以使用特定领域的转换提示，而无需修改doc7：
doc7 read ./reports --prompt-file ./prompt.md
Docker
Docker镜像包含LibreOffice、MuPDF、Chromium和CJK字体。它以非root用户运行HTTP服务，并将配置和作业持久化在命名卷中：
export DOC7_MODEL=qwen3.5-0.8b
export DOC7_SERVER_TOKEN=replace-me
docker compose pull
docker compose up --no-build
发布的镜像是ghcr.io/magicrew/doc7:latest，支持linux/amd64和linux/arm64。
安全注意事项
doc7以当前用户的权限运行本地渲染器，如LibreOffice和Chrome。将不受信任的Office文件、HTML、SVG、EML、MSG、IPYNB和存档视为活动输入——对不受信任的工作负载使用隔离账户或容器。电子邮件和笔记本HTML经过清理，远程资源被移除，嵌入的BMP/TIFF图像在渲染前被规范化。API密钥作为bearer凭据发送到配置的端点，因此在处理敏感文件之前验证端点。
结论
doc7是对文档转换的一种令人耳目一新的方法。通过利用视觉理解，它处理了传统解析器难以处理的复杂文档，并且通过简单统一的管道实现了这一点。无论您是在构建RAG系统、代理知识库，还是只需要使文档可搜索，doc7都值得认真考虑。开放的基准测试和可复现的结果让您对其能力充满信心，MIT许可证意味着您可以自由集成。
在您自己的文档上尝试一下，看看视觉理解带来的不同。