# document-parse

**Repository Path**: qfmx/document-parse

## Basic Information

- **Project Name**: document-parse
- **Description**: word、pdf 转markdown工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-01-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Document to Markdown Converter

这是一个基于 **FastAPI** 构建的高性能文档转换服务，专为 LLM（大语言模型）和 RAG（检索增强生成）场景优化。它能够将 **PDF** 和 **Word (Docx)** 文档转换为干净、结构化的 Markdown 格式，并完美保留表格、图片和排版信息。

## ✨ 核心特性

- **PDF 智能转换**:
  - 使用 `pymupdf4llm` 引擎，专门针对 LLM 优化。
  - 完美保留**表格结构**和**多栏排版**。
  - 自动提取 PDF 中的图片并生成 Markdown 图片链接。

- **Word 深度解析**:
  - 使用 `mammoth` 提取语义内容，避免混乱的样式代码。
  - **图片自动提取**: 支持将 Word 中的图片（包括 EMF/WMF 等矢量图）提取并转换为 Web 友好的 PNG 格式。
  - 智能标题识别：将加粗的短文本自动识别为 Markdown 标题。

- **图像处理增强**:
  - 所有提取的图片自动保存到本地静态目录。
  - 生成标准的 HTTP 图片链接（如 `![] (http://.../image.png)`），确保在任何 Markdown 阅读器中都能正常显示。
  - 自动处理不支持的图片格式（如 Windows 的 EMF/WMF），通过 `Pillow` 转换为 PNG。

- **现代 Web 界面**:
  - 内置基于 Tailwind CSS 的响应式前端页面。
  - 支持文件拖拽上传。
  - 实时 Markdown 预览（支持渲染 HTML 和图片）。
  - 一键复制 Markdown 源码。

- **现代化依赖管理**:
  - 使用 **uv** 进行极速依赖管理和虚拟环境构建。

## 🚀 快速开始

### 前置要求

- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (推荐)

### 安装与运行

1.  **克隆项目**

    ```bash
    git clone <your-repo-url>
    cd document-parse
    ```

2.  **安装依赖并运行**

    本项目使用 `uv` 管理依赖。直接运行以下命令，`uv` 会自动创建虚拟环境并安装所有依赖：

    ```bash
    # 启动服务 (自动处理依赖)
    uv run python main.py
    ```

    或者手动同步依赖：

    ```bash
    uv sync
    source .venv/bin/activate  # Linux/macOS
    # .venv\Scripts\activate   # Windows
    python main.py
    ```

3.  **访问服务**

    服务启动后，打开浏览器访问：**http://127.0.0.1:8000**

## 📖 API 文档

### 转换接口

- **URL**: `/convert`
- **Method**: `POST`
- **Content-Type**: `multipart/form-data`

**参数**:

| 参数名 | 类型 | 必选 | 说明 |
| :--- | :--- | :--- | :--- |
| `file` | File | 是 | PDF 或 DOCX 文件 |

**响应示例**:

```json
{
    "filename": "example.docx",
    "markdown": "# 标题\n\n正文内容...",
    "status": "success",
    "request_id": "54662f2b-d42a-438a-8c23-21e9343e9e6e"
}
```

### 命令行测试

你也可以使用 `curl` 进行测试：

```bash
curl -X POST "http://127.0.0.1:8000/convert" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/your/document.pdf"
```

## 🛠️ 技术栈

- **Web 框架**: [FastAPI](https://fastapi.tiangolo.com/)
- **PDF 处理**: [PyMuPDF4LLM](https://pymupdf.readthedocs.io/en/latest/pymupdf4llm/)
- **Word 处理**: [Mammoth](https://github.com/mwilliamson/python-mammoth) + [Markdownify](https://github.com/matthewwithanm/python-markdownify)
- **图像处理**: [Pillow](https://python-pillow.org/)
- **依赖管理**: [uv](https://github.com/astral-sh/uv)

## 📂 项目结构

```
document-parse/
├── main.py              # 核心应用代码
├── pyproject.toml       # uv 依赖配置文件
├── uv.lock              # 依赖锁定文件
├── static/              # 静态资源目录
│   ├── index.html       # 前端页面
│   └── images/          # 提取的图片存储目录 (按 request_id 隔离)
└── README.md            # 项目文档
```