# deep_text_classifier

**Repository Path**: flyeer/deep_text_classifier

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-03
- **Last Updated**: 2025-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 Deep Text Classifier - 基于BERT的Excel文本分类系统（无GPU版）

> 项目路径：`/home/fly/Documents/deep_text_classifier`

本项目使用 Hugging Face 的 `transformers` 库，基于预训练中文 BERT 模型进行文本分类训练，支持在 **纯 CPU 环境** 下运行，适用于无 GPU 的服务器或本地机器。
模型支持从 Excel 文件中加载文本和标签，自动完成数据预处理、训练、评估与保存。
Python版本： 3.8 ~ 3.12

---

## 🧩 一、核心设计思想

本系统专为无GPU环境优化，采用轻量级BERT模型和ONNX推理，实现：

- ✅ **无需显卡**：全程使用CPU训练与预测
- ✅ **一次训练**：训练脚本仅运行一次，生成可复用模型
- ✅ **多次预测**：预测脚本可无限次调用，无需重新训练
- ✅ **模型可迁移**：`models/` 目录可复制到任意机器使用
- ✅ **轻量高效**：使用 DistilBERT 减少计算量，提升速度
- ✅ **高兼容性**：预测端使用 ONNX，兼容 Python 3.8.10+

| 目标                         | 实现方式                                                   |
|:---------------------------:|:---------------------------------------------------------|
| 🖥️ **无GPU支持**        | 使用 CPU 进行训练与推理                                     |
| 🔁 **一次训练**           | 使用 `train_bert_cpu.py` 训练并导出 ONNX 模型               |
| 🚀 **多次预测**           | 使用 `predict_onnx.py` 加载模型进行批量预测                 |
| 📦 **模型迁移**           | `models/` 和 `preprocessing/` 目录完整复制即可部署          |
| 🌐 **跨版本兼容**         | 预测使用 ONNX Runtime，支持 Python 3.8 ~ 3.12               |
| 🐢 **训练加速**           | 使用 `distilbert-base-chinese`（BERT的轻量版）减少计算时间 |

> 💡 **亮点总结**：
> - 本系统特别针对无GPU环境进行了优化，确保在仅有CPU的情况下也能顺利进行模型训练及预测。
> - 通过使用DistilBERT，不仅加快了训练速度，也保证了模型的性能。
> - 利用ONNX格式存储模型，增强了模型的移植性和兼容性，使得项目更容易部署和应用。
---

## 📂 二、项目结构

```bash
deep_text_classifier/
├── data/                       # 📥 训练数据目录（支持子目录）
├── new_data/                   # ✅ 待预测数据目录（支持子目录）
├── outputs/                    # ✅ 预测结果输出（自动创建），与 predict_onnx.py 逻辑匹配
├── models/                         # 🧠 模型统一存放
│   ├── bert_classifier/            # ✅ PyTorch 训练输出
│   │   ├── config.json
│   │   ├── model.safetensors      # ✔️ 安全格式（优于pytorch_model.bin）
│   │   ├── tokenizer.json
│   │   ├── tokenizer_config.json
│   │   ├── vocab.txt
│   │   └── special_tokens_map.json
│   │
│   └── bert_onnx/                  # ✅ ONNX 模型
│       └── model.onnx              # 由 export_onnx.py 生成
├── pretrained_models/          # 🌐 离线下载的预训练模型（可选）
│   ├── chinese-roberta-wwm-ext/
│   ├── chinese-bert-wwm/			#应用此模型
│   └── bert-base-chinese/
├── preprocessing/
│   └── label_encoder.joblib    # ✅ 标签编码器（joblib格式），必须与模型配套保存，用于推理
├── checkpoints/                # 🧩 训练过程中的 checkpoint
│   ├── checkpoint-50/
│   ├── checkpoint-100/
│   └── ...                         # 自动创建，用于恢复训练
├── logs/
│   ├── training.log            # ✅ 训练日志
│   └── predict.log             # ✅ 预测日志
├── src/                            # 🧱 源码，避免脚本散落在根目录，便于维护
│   ├── train_bert_cpu.py           # 🧠 主训练脚本
│   ├── export_onnx.py              # 将 PyTorch 模型转为 ONNX
│   ├── verify_models.py            # 离线模型检验脚本
│   └── predict_onnx.py             # 🔮 批量预测脚本（你当前的脚本）
├── requirements_cpu.txt        # 📦 CPU环境依赖（无GPU库）
├── README.md                   # 📝 本说明文件
├── REPORT.md                   # 📊 性能分析与准确率报告
└── .gitignore                  # 🚫 忽略大文件
```

## 🌐 三、项目整体流程图
```mermaid
graph TD
    A[开始] --> B[数据准备]
    
    subgraph 训练数据准备
        B1[训练数据] -->|放入| B1a[data/ 目录]
        B1a -->|支持子目录结构| B1b[.xlsx 文件]
        B1b -->|C列: 文本数据, G列: 标签| B2[模型训练]
    end
    
    subgraph 预测数据准备
        B3[待预测数据] -->|放入| B3a[new_data/ 目录]
        B3a -->|支持子目录结构| B3b[.xlsx 文件]
        B3b -->|C列: 文本数据, G列: 可为空| C[执行预测]
    end
    
    B2 -.->|生成模型文件| D
    
    C --> D{加载资源}
    D --> D1[ONNX模型: models/bert_onnx/]
    D --> D2[标签编码器: preprocessing/label_encoder.joblib]
    
    D --> E[数据预处理]
    E --> E1[递归扫描 new_data/ 子目录]
    E --> E2[跳过临时文件 ~$.xlsx, .tmp]
    E --> E3[提取C列文本内容]
    E --> E4[使用Tokenizer编码文本]
    
    E --> F[模型推理]
    F --> F1[CPU推理]
    F --> F2[获取预测类别ID]
    F --> F3[通过LabelEncoder解码为原始标签]
    
    F --> G[结果输出]
    G --> G1[填充Excel的G列]
    G --> G2[保持原有文件格式]
    G --> G3[输出到 outputs/ 目录]
    G3 --> G4[保持原始目录结构]
    
    G --> H[结束]
    
    style A fill:#4CAF50,stroke:#388E3C,color:white
    style H fill:#F44336,stroke:#D32F2F,color:white
    style B2 fill:#2196F3,stroke:#1976D2,color:white
    style C fill:#FF9800,stroke:#F57C00,color:white
    style D fill:#9C27B0,stroke:#7B1FA2,color:white
    style F fill:#FF5722,stroke:#D84315,color:white
    style G fill:#009688,stroke:#00796B,color:white
```
## 📂 四、 使用步骤

#### 1. 创建（首次）
```bash
cd /home/fly/Documents/deep_text_classifier
python3 -m venv venv
```
#### 2. 激活（每次使用）
```bash
source venv/bin/activate        # Linux/macOS
venv\Scripts\activate           # Windows
```
#### 3. 安装依赖
```bash
# 安装CPU依赖（使用清华源）
pip install --upgrade pip
pip install -r requirements_cpu.txt
```
#### 4. 设置 Hugging Face 镜像（国内推荐，容易污染；Hugging Face官网离线下载再检验更可靠）
```bash
# 避免从原始 Hugging Face 下载缓慢或失败
export HF_ENDPOINT=https://hf-mirror.com
```
#### 5. 运行脚本
```bash
# 开始训练（自动保存模型到 models/bert_onnx/）
(venv)python3 src/train_bert_cpu.py
# 导出为 ONNX
(venv)python3 src/export_onnx.py
# 多次预测
(venv)python3 src/predict_onnx.py
```
#### 6. 退出
```bash
deactivate
```
## ⚠️ 五、注意事项
#### 模型训练完成的保存位置
- **模型保存路径**: `models/bert_classifier/`
- **标签编码器路径**: `preprocessing/label_encoder.joblib`
- **训练日志路径**: `./logs/`
#### 支持的模型
默认使用 `chinese-bert-wwm`（可通过 [hf-mirror.com](https://hf-mirror.com) 访问）：
```python
MODEL_NAME = "chinese-bert-wwm"
```

以下模型可供替换（需确保镜像站支持）：

- `hfl/chinese-roberta-wwm-ext`
- `bert-base-chinese`

> ⚠️ **注意**: `hfl/chinese-distilbert-base` 在 hf-mirror.com 上**暂未同步**，不推荐使用。