# file-chuck

**Repository Path**: hweiming/file-chuck

## Basic Information

- **Project Name**: file-chuck
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-07
- **Last Updated**: 2025-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文档处理服务

这是一个基于多引擎的文档处理服务，支持将各种格式的文档转换为 Markdown 格式，并提供图片处理功能。

## 功能特点

- 支持多种文档格式：PDF、Word、PPT 等
- 多引擎支持：基础引擎、高级引擎和 MinerU 引擎
- 图片处理：支持提取和上传图片到 OBS
- 灵活配置：可根据需求选择不同的处理引擎

## 系统要求

### 基础环境
- Python 3.10 或更高版本
- 操作系统：Windows/Linux/macOS
- 存储空间：至少 2GB 可用空间

### MinerU 引擎特殊要求
MinerU 引擎基于 OpenDataLab 的 MinerU 项目，提供更高质量的文档转换能力，但有以下特殊要求：

- 硬件要求：
  - CPU：至少 4 核心
  - 内存：至少 16GB RAM
  - GPU：推荐使用 NVIDIA GPU（6GB 或更大显存）
  - 存储：至少 20GB 可用空间（用于模型文件）

- 软件要求：
  - CUDA 11.7 或更高版本（如果使用 GPU）
  - 必要的系统库（详见安装说明）

## 安装

1. 克隆仓库：
```bash
git clone https://github.com/your-org/document-service.git
cd document-service
```

2. 创建虚拟环境：
```bash
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
```

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

4. 如果要使用 MinerU 引擎，还需要：
```bash
pip install "magic-pdf[full]"  # 安装 MinerU
```

## 配置

在 `config.yaml` 中配置服务：

```yaml
document:
  default_engine: "markitdown"  # 默认引擎
  supported_formats:  # 支持的文件格式
    - ".pdf"
    - ".doc"
    - ".docx"
    - ".ppt"
    - ".pptx"

storage:
  uploads_dir: "./uploads"    # 上传文件目录
  output_dir: "./output"      # 输出文件目录
  temp_dir: "./temp"         # 临时文件目录

mineru:  # MinerU 引擎配置
  model_path: "./models"     # 模型文件目录
  device: "cuda"            # 使用设备：cuda 或 cpu
```

## 使用方法

### API 示例

```python
from document_service import DocumentService

# 初始化服务
service = DocumentService(config)

# 使用基础引擎处理文档
result = await service.process_document(
    file,
    parser_option="default",
    image_option="obs"
)

# 使用 MinerU 引擎处理文档
result = await service.process_document(
    file,
    parser_option="mineru",
    image_option="obs"
)
```

### 引擎选择

1. 基础引擎 (default)：
   - 适用于简单文档
   - 资源占用少
   - 处理速度快

2. 高级引擎 (advanced)：
   - 支持更复杂的文档结构
   - 更好的表格和图片处理
   - 中等资源占用

3. MinerU 引擎 (mineru)：
   - 最佳的文档结构识别
   - 支持复杂布局和多语言
   - 高质量的图片和表格提取
   - 需要较多计算资源

## 注意事项

1. MinerU 引擎首次使用时会下载模型文件（约 10GB），请确保有足够的网络带宽和存储空间。

2. 为获得最佳性能，建议使用 GPU 运行 MinerU 引擎。如果使用 CPU：
   - 处理速度会显著降低
   - 内存占用会增加
   - 建议限制并发处理数量

3. 临时文件管理：
   - 文件会在处理后保留 30 分钟
   - 自动清理服务会定期删除过期文件
   - 请确保有足够的临时存储空间

## 故障排除

1. 如果遇到内存不足：
   - 检查是否有其他程序占用大量内存
   - 考虑增加系统交换空间
   - 使用较低资源占用的引擎

2. GPU 相关问题：
   - 确保 CUDA 正确安装
   - 检查 GPU 驱动版本
   - 监控 GPU 显存使用情况

3. 文件处理失败：
   - 检查文件格式是否支持
   - 查看日志获取详细错误信息
   - 确保文件未被损坏

## 许可证

本项目基于 MIT 许可证开源。

注意：MinerU 引擎基于 OpenDataLab 的 MinerU 项目，使用时请遵守其许可条款。