Excel转Markdown向量化服务

基于Docling + Celery + LlamaIndex的Excel文件转换和向量化检索服务，提供完整的Web界面。

功能特性

核心功能

• Excel转Markdown: 使用Docling将Excel文件转换为Markdown格式
• 向量化存储: 使用LlamaIndex将Markdown内容向量化并存储
• 智能检索: 基于语义相似度的文档搜索和问答
• 异步处理: 基于Celery的异步任务处理
• Web界面: 现代化的React前端应用

技术栈

• 后端: FastAPI + Celery + Redis
• 前端: React + TypeScript + Ant Design
• 文档转换: Docling
• 向量化: LlamaIndex + Sentence Transformers
• 实时通信: WebSocket
• 容器化: Docker + Docker Compose

快速开始

1. 环境要求

• Python 3.8+
• Node.js 16+
• Docker & Docker Compose
• Redis

环境管理选项

选项1: 使用conda环境 (推荐)

• Anaconda或Miniconda
• 自动环境隔离和依赖管理

选项2: 使用系统Python

• 系统Python 3.11+
• 需要手动管理依赖

2. 安装依赖

选项1: 使用conda环境 (推荐)

设置conda环境:

# 或手动设置
conda create -n doc_env python=3.11
conda activate doc_env
pip install -r requirements.txt

启动服务:

# 使用统一启动脚本
start.bat

选项2: 使用系统Python

后端依赖:

pip install -r requirements.txt

前端依赖:

cd frontend
npm install

3. 启动服务

方式一：Docker Compose

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f app
docker-compose logs -f celery-worker
docker-compose logs -f celery-flower

方式二：手动启动

# 1. 启动Redis
redis-server

# 2. 启动Celery Worker（新终端）
celery -A app.core.celery_app.app worker --loglevel=info --queues=excel_conversion,vectorization

# 3. 启动API服务（新终端）
python -m app.api.routes

# 4. 启动前端应用（新终端）
cd frontend
npm start

# 5. 启动Flower监控（可选，新终端）
celery -A app.core.celery_app.app flower --port=5555

服务访问地址

• 前端应用: http://localhost:3000
• 后端API: http://localhost:8000
• API文档: http://localhost:8000/docs
• Celery监控: http://localhost:5555
• Redis: localhost:6379

4. 测试服务

# 访问前端应用
# 浏览器打开: http://localhost:3000

# 访问API文档进行测试
# 浏览器打开: http://localhost:8000/docs

# 或使用curl测试健康检查
curl http://localhost:8000/health

前端功能

主要页面

• 文件上传 - 支持拖拽上传Excel文件，实时显示上传进度
• 任务管理 - 查看所有转换任务的状态和进度
• 文件浏览 - 管理已处理的文件，支持下载和删除
• 文档搜索 - 基于语义相似度的智能搜索
• 统计信息 - 系统运行状态和处理统计
• 系统设置 - 配置API连接和系统参数

实时功能

• WebSocket连接 - 实时更新任务状态
• 进度显示 - 实时显示转换进度
• 状态通知 - 任务完成或失败通知
• 自动刷新 - 定期更新数据状态

API接口

基础转换接口

• POST /upload-batch - 批量上传Excel文件
• GET /task/{task_id} - 查询任务状态
• GET /download/{filename} - 下载转换结果

向量化接口

• POST /search - 搜索相关文档
• GET /vector-stats - 获取向量数据库统计信息
• POST /convert-and-vectorize - 转换Excel并自动向量化

搜索参数

• query: 搜索查询文本
• top_k: 返回结果数量（默认5）
• similarity_threshold: 相似度阈值（默认0.7）
• vector_type: 向量数据库类型（milvus/elasticsearch）

使用示例

1. 批量转换Excel文件

curl -X POST "http://localhost:8000/upload-batch" \
  -F "files=@example1.xlsx" \
  -F "files=@example2.xlsx"

2. 转换并向量化文档

curl -X POST "http://localhost:8000/convert-and-vectorize?vector_type=milvus" \
  -F "file=@example.xlsx"

3. 搜索文档

curl -X POST "http://localhost:8000/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "销售数据", "top_k": 5, "similarity_threshold": 0.7, "vector_type": "milvus"}'

4. 获取文件状态

curl "http://localhost:8000/file/{file_id}"

配置说明

环境变量

# Celery配置
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

向量化配置

• 嵌入模型: sentence-transformers/all-MiniLM-L6-v2
• 文档分块: 1000字符，200字符重叠
• 向量维度: 384

Docker Compose服务架构

服务组件

• app: FastAPI主应用服务
• celery-worker: Celery异步任务处理
• celery-flower: Celery任务监控界面
• redis: 消息代理和结果后端

数据持久化

• redis_data: Redis数据持久化

网络配置

• 所有服务运行在doc_network网络中
• 服务间通过服务名进行通信
• 外部通过端口映射访问服务

项目结构

doc/
├── app/                    # 应用核心代码
│   ├── api/               # API路由
│   ├── core/              # 核心配置
│   ├── models/            # 数据模型
│   ├── services/          # 业务服务
│   └── utils/             # 工具函数
├── config/                # 配置文件
├── tests/                 # 测试文件
├── docs/                  # 文档
├── docker-compose.yaml    # Docker编排文件
├── Dockerfile            # Docker镜像构建
├── env.example           # 环境变量示例
├── requirements.txt      # Python依赖
└── README.md            # 项目文档

性能优化

1. 向量索引优化

• 调整分块大小和重叠度
• 选择合适的嵌入模型
• 配置合适的相似度阈值

2. 系统优化

• 增加Celery Worker数量
• 配置Redis内存大小
• 调整向量数据库参数

3. 查询优化

• 使用合适的top_k值
• 调整相似度阈值
• 添加查询缓存

故障排除

常见问题

1. 向量化失败: 检查向量数据库连接
2. 搜索无结果: 调整相似度阈值
3. 内存不足: 增加系统内存或调整分块大小
4. 连接超时: 检查网络和防火墙设置

日志查看

# 查看API日志
tail -f api.log

# 查看Celery日志
tail -f celery_worker.log

# 查看Docker日志
docker-compose logs -f

开发指南

自定义嵌入模型

1. 修改VectorConfig中的embed_model参数
2. 更新requirements.txt添加新模型依赖
3. 调整向量维度配置

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

---

更新日志

2024-12-19 - Docker Compose重构

本次会话主要目的

重新生成完整的docker-compose.yaml文件，为Excel转Markdown向量化服务提供完整的容器化部署方案。

完成的工作

1. 分析项目架构: 深入分析了项目的技术栈和依赖关系
2. 创建Docker Compose配置: 生成了包含所有必要服务的完整docker-compose.yaml文件
3. 配置支持服务: 添加了Redis等支持服务
4. 创建辅助文件: 生成了nginx.conf、启动脚本、环境变量示例等配置文件
5. 更新项目文档: 完善了README.md中的Docker Compose使用说明

关键决策和解决方案

• 服务架构设计: 采用微服务架构，将应用、任务处理、数据库等分离
• 数据持久化: 为所有数据库服务配置了数据卷持久化
• 健康检查: 为关键服务添加了健康检查机制
• 网络配置: 使用自定义网络确保服务间通信安全
• 监控支持: 集成Celery Flower提供任务监控界面

主要修改内容

1. 新增文件:

   • docker-compose.yaml: 完整的Docker编排配置
   • env.example: 环境变量配置示例

2. 更新文件:

   • README.md: 添加Docker Compose使用说明和服务架构介绍

服务组件说明

• app: FastAPI主应用，提供API接口
• celery-worker: 异步任务处理，支持Excel转换
• celery-flower: 任务监控界面，端口5555
• redis: 消息代理，支持Celery任务队列

使用方式

# 快速启动
docker-compose up -d

# 访问服务
# 主应用: http://localhost:8000
# API文档: http://localhost:8000/docs
# 任务监控: http://localhost:5555

这次重构为项目提供了完整的容器化部署方案，支持一键启动所有服务，大大简化了部署和运维工作。