# sales-report-parser

**Repository Path**: zhougewudi/sales-report-parser

## Basic Information

- **Project Name**: sales-report-parser
- **Description**: 一款基于 OCR + 大语言模型（LLM）的销售报表图片批量数据提取工具。它能够自动识别图片中的文字内容，并通过 AI 智能解析，将非结构化的图片数据转换为结构化的 JSON/Excel 格式。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sales-report-parser - 销售报表图片数据提取工具

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

一款基于 OCR + 大语言模型（LLM）的销售报表图片批量数据提取工具。它能够自动识别图片中的文字内容，并通过 AI 智能解析，将非结构化的图片数据转换为结构化的 JSON/Excel 格式。

## 功能特性

- 📷 **批量处理** - 自动扫描当前目录下的所有图片文件
- 🔤 **OCR 文字识别** - 使用 cnocr 进行中文文字识别
- 🤖 **AI 智能提取** - 结合大语言模型理解上下文，精准提取销售数据
- 🔄 **重试机制** - 智能重试确保数据提取的稳定性
- 📊 **多格式输出** - 支持导出 JSON 和 Excel 格式
- 📅 **日期自动排序** - Excel 输出按日期自动排序，横向展示

## 支持的图片格式

- JPG / JPEG
- PNG
- BMP

## 提取的数据字段

| 字段名 | 说明 |
|--------|------|
| 日期 | 销售日期 (YYYY-MM-DD) |
| 总销售 | 当日总销售额 |
| 产品净销售 | 产品净销售额 |
| 现烤面包 | 现烤面包销售额 |
| 袋装面包 | 袋装面包销售额 |
| 软点 | 软点销售额 |
| 西点 | 西点销售额 |
| 中点 | 中点销售额 |
| 蛋糕个数 | 蛋糕销售数量 |
| 蛋糕金额 | 蛋糕销售额 |
| 卡劵 | 卡券销售额 |
| 交易次数 | 当日交易笔数 |

## 技术栈

- **Python 3.10+**
- **cnocr** - 中文 OCR 文字识别
- **LangChain** - 大语言模型应用框架
- **MiniMax API** - 大语言模型（支持各类国产/国际大模型）
- **Pandas** - 数据处理与 Excel 导出
- **OpenPyXL** - Excel 文件操作

## 环境要求

- Python 3.10 或更高版本
- Windows / macOS / Linux

## 安装

### 1. 克隆项目

```bash
git clone https://github.com/yourusername/treaimages.git
cd treaimages
```

### 2. 创建虚拟环境（推荐）

```bash
python -m venv venv
```

**Windows 激活：**
```bash
venv\Scripts\activate
```

**macOS / Linux 激活：**
```bash
source venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置 API Key

编辑 `minimax_langchain.py` 文件，替换为你自己的 API Key：

```python
API_KEY = "your-api-key-here"
```

支持的模型配置：
- 可修改 `MODEL_NAME` 切换不同的模型
- 可修改 `BASE_URL` 切换不同的 API 端点

## 使用方法

### 1. 准备图片

将需要处理的销售报表图片放入项目根目录。支持的文件格式：`.jpg`, `.jpeg`, `.png`, `.bmp`。

### 2. 运行程序

```bash
python batch_extract.py
```

### 3. 查看结果

程序运行结束后，会在当前目录生成：
- `output.json` - JSON 格式的原始数据
- `output.xlsx` - Excel 格式的横向汇总表

## 项目结构

```
treaimages/
├── batch_extract.py      # 主程序 - 批量图片处理入口
├── minimax_langchain.py  # AI 模块 - OCR 与大模型交互
├── output.json          # 提取的 JSON 数据（自动生成）
├── output.xlsx          # 导出的 Excel 文件（自动生成）
├── 1,8.png              # 示例图片
├── 2,9.jpg              # 示例图片
└── README.md            # 项目说明文档
```

## 实现原理

### 整体架构

```
图片文件 → OCR 识别 → 文本处理 → 大模型解析 → JSON/Excel 输出
```

### 核心流程

1. **图片扫描**
   - 自动扫描当前目录下的所有图片文件
   - 按文件名排序后依次处理

2. **OCR 文字识别**
   - 使用 cnocr 对图片进行文字识别
   - 将图片中的文字逐行提取为文本

3. **AI 数据提取**
   - 将 OCR 识别的文本发送给大语言模型
   - 大模型根据预置的 prompt 理解销售报表结构
   - 提取 12 个关键字段的数据

4. **数据导出**
   - 原始数据保存为 JSON 格式
   - 按日期排序后转换为横向 Excel 表格

### 关键代码说明

#### OCR 识别（minimax_langchain.py）

```python
def ocr_recognize(image_path: str) -> List[str]:
    cn_ocr = CnOcr()
    result = cn_ocr.ocr(image_path)
    # 返回识别出的文字列表
```

#### 大模型 JSON 提取（batch_extract.py）

```python
def extract_data_with_retry(image_path, image_file, max_retries=3):
    # OCR 识别
    text_lines = ocr_recognize(image_path)
    ocr_text = "\n".join(text_lines)

    # 发送给大模型进行数据提取
    prompt = f"请从以下OCR识别的销售报表文本中提取数据...\n{ocr_text}"
    result = simple_chat_with_json(prompt)

    return result
```

#### Excel 导出

```python
def convert_to_excel(data, filename="output.xlsx"):
    df = pd.DataFrame(data)
    df['日期_排序'] = df['日期'].apply(parse_date)
    df = df.sort_values('日期_排序')

    # 横向展示：日期为列，字段为行
    df_transposed = df.set_index('日期').T
    df_transposed.to_excel(filename)
```

## 注意事项

1. **API Key 安全**
   - 代码中包含的 API Key 仅供测试使用
   - 正式使用时请替换为自己的 API Key
   - 建议使用环境变量管理敏感信息

2. **网络要求**
   - 程序需要联网调用 MiniMax API
   - 确保网络畅通，API 才能正常工作

3. **图片质量**
   - 图片越清晰，OCR 识别率越高
   - 建议使用 1024x1024 以上分辨率的图片

4. **重试机制**
   - 默认每张图片最多重试 3 次
   - 可根据需要调整 `max_retries` 参数

5. **依赖版本**
   - Python 3.10+
   - 确保所有依赖包版本兼容

## 常见问题

### Q: 运行报错 "ModuleNotFoundError"

A: 确保已正确安装所有依赖，运行 `pip install -r requirements.txt`

### Q: OCR 识别结果为空

A: 检查图片是否包含可识别的文字，或图片格式是否正确

### Q: 大模型返回格式错误

A: 检查 API Key 是否有效，或网络是否正常

### Q: Excel 导出失败

A: 确保已安装 openpyxl：`pip install openpyxl`

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/xxx`)
3. 提交更改 (`git commit -m 'Add xxx'`)
4. 推送到分支 (`git push origin feature/xxx`)
5. 创建 Pull Request

---

如果这个项目对你有帮助，欢迎 Star ⭐️

---

**广告**：如果有数据处理需求，请联系VX: **xiaozhouwd**