# homework_word_parser

**Repository Path**: qytang/homework_word_parser

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-23
- **Last Updated**: 2025-11-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 DOCX → Markdown (Vision-LLM Powered)

> **全球首款** 真正理解“所见即所得”的文档转换引擎 —— 让 AI 读懂你的 Word 文档！

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue)](https://www.docker.com/)
[![FastAPI](https://img.shields.io/badge/FastAPI-Powered-green)](https://fastapi.tiangolo.com/)
[![React](https://img.shields.io/badge/Frontend-React-61dafb)](https://reactjs.org/)

传统的文档转换工具（如 Pandoc）只能死板地转换文本，遇到图片就变成了无意义的 `![image](path)`。
**本项目彻底颠覆了这一现状！** 我们引入了前沿的 **多模态大模型（Vision-LLM）** 技术，赋予程序“视觉”，让它像人类专家一样审视每一张配图、每一行代码、每一个表格。

无论是 Python 作业截图、复杂的架构图，还是手写的笔记，本工具都能将其**完美转译**为语义清晰、格式优雅的 Markdown。

---

## ✨ 核心黑科技 (Features)

### 1. 🧠 真正的“视觉理解” (Vision-Aware)
- **拒绝占位符**：程序会自动扫描文档中的每一张图片。
- **并发视觉引擎**：采用 `asyncio` 高并发架构，同时调度多个视觉模型实例（支持 OpenAI 兼容接口，如 GPT-4o, Qwen-VL 等），瞬间“看懂”数十张图片。
- **智能描述**：
  - 遇到 **代码截图**？直接 OCR 并提取为可运行的 Python/Java/C++ 代码块。
  - 遇到 **运行结果**？精确描述控制台输出。
  - 遇到 **架构图**？详细解说组件关系与数据流向。
- **结果回填**：图片不再是冷冰冰的附件，而是变成了上下文连贯的 `> 图像内容：...` 引用，让纯文本的大模型也能理解图片含义！

### 2. 🎨 AI 驱动的格式重绘 (LLM Post-Processing)
- **全文重构**：不是简单的正则替换，而是将整个文档投喂给大语言模型进行“二次创作”。
- **智能纠错**：自动修复 Word 中常见的乱码、奇怪的缩进、断裂的列表。
- **代码块合并**：智能识别被分页符打断的代码段，将其完美缝合为一个完整的 ` ```python ` 块。
- **语义保留**：在美化格式的同时，严格恪守原文语义，绝不篡改任何实质内容。

### 3. ⚡ 极致性能与体验
- **SSE 实时流式响应**：毫秒级进度推送，实时看到“正在解析第 5 张图片...”、“正在整理文档...”，拒绝焦虑等待。
- **超长文本支持**：后端精心调优的超时机制（支持 1 小时+处理时长），配合 Nginx 长连接配置，轻松应对数百页的超大文档。
- **双模预览**：
  - **Raw Mode**：查看原汁原味的转换结果。
  - **Polished Mode**：查看经过 AI 精修后的完美 Markdown。
- **一键导出**：支持一键复制、下载 `.md` 文件，直接用于 Hexo/Hugo 博客或 GitBook。

### 4. 🛡️ 灵活且强大的配置
- **模型无关性**：图像解析和文本整理可分别指定不同的模型（例如：用 Qwen-VL 看图，用 DeepSeek 整理文本）。
- **完全隐私化**：支持接入本地部署的 vLLM/Ollama，数据完全掌握在自己手中。
- **Prompts 自定义**：你甚至可以修改系统提示词，让它变成你的专属“作业批改助手”或“论文润色专家”。

---

## 🛠️ 极速部署 (Quick Start)

基于 Docker Compose 的一键部署，无需繁琐的环境配置。

### 前置要求
- Docker & Docker Compose
- 一个兼容 OpenAI 接口的 LLM 服务（本地 vLLM 或远程 API）

### 启动服务

```bash
# 1. 启动服务 (自动构建前后端)
docker compose up -d --build
```

- **前端 UI**: `http://localhost:8088`
- **后端 API**: `http://localhost:8000`

### 使用指南
1. 打开浏览器访问 `http://localhost:8088`。
2. 在右上角配置你的 **Base URL** 和 **API Key**（支持本地无 Key 模式）。
3. 拖入一个 `.docx` 文件。
4. 点击 **“开始转换”**，见证奇迹！

---

## 🏗️ 技术架构 (Architecture)

```mermaid
graph LR
    User[用户] -->|Upload .docx| Web[React 前端]
    Web -->|POST /convert| API[FastAPI 后端]
    API -->|1. 解析文档结构| DocParser[python-docx]
    API -->|2. 提取图片| ImgQueue[内存队列]
    
    subgraph "并发视觉引擎"
        ImgQueue -->|Async| Worker1[Vision LLM 1]
        ImgQueue -->|Async| Worker2[Vision LLM 2]
        ImgQueue -->|Async| Worker3[Vision LLM 3]
    end
    
    Worker1 & Worker2 & Worker3 -->|图像描述| Context[图文混合上下文]
    Context -->|3. 全文重整| PostLLM[整理型 LLM]
    PostLLM -->|4. 完美 Markdown| Web
```

- **Frontend**: React + Vite + Marked (Async Rendering)
- **Backend**: FastAPI + Asyncio + SSE (Server-Sent Events)
- **Processing**: 
  - **Stage 1**: Docx 结构化解析 + 并发图片理解
  - **Stage 2**: 基于 Context 的全文 Markdown 规范化

---

## 📝 环境变量 (Environment Variables)

| 变量名 | 默认值 | 说明 |
|:---|:---|:---|
| `OPENAI_BASE_URL` | `http://localhost:9090/v1` | 默认 LLM 接口地址 |
| `OPENAI_API_KEY` | `EMPTY` | 默认 API Key |
| `VISION_MODEL` | `qwen2-vl-7b-instruct` | 默认视觉模型 |
| `REQUEST_TIMEOUT` | `300` | 图像解析超时 (秒) |
| `POSTPROCESS_TIMEOUT` | `3600` | 全文整理超时 (秒) |

---

## 🤝 贡献与支持

本项目由 **乾颐堂（现任明教教主）** 倾力打造，旨在解决技术文档编写中的痛点。

如果你觉得这个项目帮你节省了时间，请给一个 ⭐️ Star！

---

**License**: MIT