# docs_parser

**Repository Path**: leaveWhite9088/docs_parser

## Basic Information

- **Project Name**: docs_parser
- **Description**: 一个简单的文档解析器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-19
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文档结构化解析器 (Document Structure Parser)

一个专业的文档解析工具，专门用于将Word和PDF文档转换为结构化的JSON格式，为RAG (Retrieval-Augmented Generation) 应用提供高质量的数据源。

## 🎯 项目概述

本项目旨在开发一个自动化工具，用于解析Word (.docx) 和PDF (.pdf) 文档。工具的核心功能是识别并提取文档的逻辑结构，包括文档标题、层级化的章节标题、正文段落、表格、列表和图注，并将这些结构化信息转换成一个标准的、嵌套的JSON格式。

## ✨ 核心特性

### 📄 文档解析能力
- **Word文档解析**: 支持.docx格式，基于python-docx库
- **PDF文档解析**: 支持文字版PDF，基于pdfplumber库
- **智能标题识别**: 支持多种标题格式和层级识别
- **内容结构化**: 自动识别段落、列表、表格等元素

### 🎨 标题识别规则
- **中文标号**: `一、二、三` → 1级标题
- **数字标号**: `1. 2. 3.` → 需要字号判断
- **多级数字**: `1.1 1.1.1 1.1.1.1` → 直接识别为对应层级
- **章节标题**: `第一章 第二章` → 1级标题
- **空格分隔**: `1 引言 2 概述` → 1级标题

### 🚀 使用方式
- **命令行界面**: 交互式单文件或批量处理
- **FastAPI服务**: RESTful API接口，支持集成
- **灵活配置**: 支持自定义输出目录和参数

### 📊 输出格式
- **标准JSON**: 嵌套结构，便于RAG应用处理
- **层级清晰**: 支持最多6级标题层级
- **内容完整**: 保留原始文档的所有文本内容

## 🚀 快速开始

### 环境要求
- Python 3.8+
- Windows/Linux/macOS

### 安装依赖
```bash
# 克隆项目
git clone git@gitee.com:leaveWhite9088/docs_parser.git
cd docs_parser

# 安装依赖
pip install -r requirements.txt
```

### 基本使用

#### 1. 命令行模式

运行主程序：
```bash
python main.py
```

程序提供三种模式：
- **单文件处理模式**: 交互式选择单个文件进行解析
- **批量文件处理模式**: 批量处理docs目录下的所有文档
- **退出**: 退出程序

#### 2. 文件准备
将待解析的文档放入 `docs` 目录：
```
docs/
├── 文档1.docx
├── 文档2.pdf
└── ...
```

#### 3. 查看结果
解析结果将保存在 `result` 目录中：
```
result/
├── 文档1.json
├── 文档2.json
└── ...
```

## 🌐 API服务

### 启动服务
```bash
python server.py
```

服务将在 `http://localhost:8000` 启动

### API接口

#### 1. 文档解析接口
- **URL**: `POST /parse-document`
- **功能**: 上传文档进行解析
- **参数**:
  - `file`: 上传的文档文件 (必需)
  - `output_dir`: 输出目录 (可选，默认为'result')

#### 2. 健康检查接口
- **URL**: `GET /health`
- **功能**: 检查服务状态

### API调用示例

#### 使用curl
```bash
curl -X POST "http://localhost:8000/parse-document" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@example.docx" \
  -F "output_dir=result"
```

#### 使用Python requests
```python
import requests

url = "http://localhost:8000/parse-document"
files = {"file": open("example.docx", "rb")}
data = {"output_dir": "result"}

response = requests.post(url, files=files, data=data)
print(response.json())
```

## 📋 输出格式

### JSON结构示例
```json
{
  "title": "文档标题",
  "sections": [
    {
      "title": "1 引言",
      "level": 1,
      "paragraph": [
        "这是引言的内容...",
        "更多内容..."
      ],
      "sections": [
        {
          "title": "1.1 编写目的",
          "level": 2,
          "paragraph": [
            "编写目的的内容..."
          ],
          "sections": []
        }
      ]
    }
  ],
  "metadata": {
    "source_filename": "原始文件名.docx",
    "page_count": 10,
    "processing_time_seconds": 2.5
  }
}
```

### 字段说明
- `title`: 文档标题
- `sections`: 章节列表，支持嵌套结构
- `level`: 标题层级 (1-6)
- `paragraph`: 段落内容列表
- `metadata`: 元数据信息

## 📁 支持的文件格式

| 格式 | 扩展名 | 解析库 | 支持特性 |
|------|--------|--------|----------|
| Word文档 | .docx | python-docx | 完整支持，包括样式识别 |
| PDF文档 | .pdf | pdfplumber | 文字版PDF，支持格式提取 |

## 🛠️ 技术架构

### 核心组件
- **DocParser**: Word文档解析器
- **PdfParser**: PDF文档解析器
- **DocsParser**: 统一解析接口
- **FastAPI Server**: Web服务接口

### 解析流程
1. **文档加载**: 根据文件类型选择对应解析器
2. **结构识别**: 智能识别标题层级和内容类型
3. **内容提取**: 提取文本、表格、列表等元素
4. **结构构建**: 构建嵌套的JSON结构
5. **结果输出**: 保存为标准JSON格式

## 📦 依赖管理

### 核心依赖
```txt
python-docx>=0.8.11    # Word文档解析
pdfplumber>=0.7.0      # PDF文档解析
fastapi>=0.68.0        # Web框架
uvicorn>=0.15.0        # ASGI服务器
```

### 安装依赖
```bash
pip install -r requirements.txt
```

## 🔧 配置说明

### 环境变量
- `LOG_LEVEL`: 日志级别 (默认: INFO)
- `OUTPUT_DIR`: 默认输出目录 (默认: result)

### 配置文件
项目支持通过配置文件自定义解析参数，详见各解析器模块的文档。

## 🚨 注意事项

### 使用限制
- **PDF文档**: 仅支持文字版PDF，不支持扫描版
- **文件大小**: 建议单个文件不超过100MB
- **编码格式**: 支持UTF-8编码的文档