# 评慧商城

**Repository Path**: Merlin5815/PHMall

## Basic Information

- **Project Name**: 评慧商城
- **Description**: 评慧商城，围绕电商商品评论，构建了一套多任务智能分析系统。系统采用模块化架构，将传统机器学习、快速文本分类与统一 Web 展示层有机结合，形成完整的端到端 Demo。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 电商评论智能分析系统

## 一、项目概述

本项目围绕**电商商品评论**，构建了一套多任务智能分析系统。系统采用模块化架构，将传统机器学习、快速文本分类与统一 Web 展示层有机结合，形成完整的端到端 Demo。

| 功能 | 技术 | 模块 | 说明 |
|------|------|------|------|
| ① 评论情感分类 | 随机森林 + TF-IDF | `02-rf` | 将评论分为：好评 / 中评 / 差评 |
| ② 评论细粒度意图分类 | FastText | `03-fasttext` | 将评论分为：物流 / 质量 / 服务 / 价格 / 默认好评 |
| ③ 统一 Web 展示 | Flask + 前端页面 | `04-unified-web` | 整合两个模型，提供统一的用户交互界面 |

### 架构亮点

- **模块化设计**：各模块独立运行，均遵循 `config → 预处理 → 训练 → 预测 → 部署` 链路
- **双模式接入**：统一 Web 层支持 **本地直调**（默认）和 **HTTP 代理** 两种模式
- **延迟加载**：模型仅在首次预测时加载，启动服务不阻塞
- **数据格式统一**：所有训练数据采用 `内容\t标签` Tab 分隔格式

---

## 二、项目结构

```
PHMall/
│
├── 01-data/                          # 公共数据目录
│   ├── sentiment/                    # 情感分类数据（positive/neutral/negative）
│   │   ├── sentiment_train.txt       # 训练集
│   │   ├── sentiment_test.txt        # 测试集
│   │   ├── sentiment_dev.txt         # 验证集
│   │   └── sentiment_class.txt       # 类别定义
│   ├── intent/                       # 意图分类数据（logistics/quality/service/price/default_praise）
│   │   ├── intent_train.txt          # 训练集
│   │   ├── intent_test.txt           # 测试集
│   │   ├── intent_dev.txt            # 验证集
│   │   └── intent_class.txt          # 类别定义
│   ├── generate_data.py              # 数据生成脚本
│   └── stopwords.txt                 # 停用词表
│
├── 02-rf/                            # 随机森林 —— 评论情感分类
│   ├── data/                         # 预处理后的 CSV 数据
│   ├── save_models/                  # 保存的模型文件
│   │   ├── rf_model.pkl              # 随机森林模型
│   │   └── tfidf_model.pkl           # TF-IDF 向量化器
│   ├── result/                       # 预测结果输出
│   ├── bj_config.py                  # 路径配置
│   ├── dataEDA_processing.py         # 数据预处理（jieba 分词 + 去停用词）
│   ├── rf_train.py                   # 模型训练 + 评估 + 保存
│   ├── rf_predict_fun.py             # 预测函数（供统一 Web 层直接调用）
│   └── api_flask_server.py           # 独立 Flask API 服务（可选）
│
├── 03-fasttext/                      # FastText —— 评论意图分类
│   ├── final_data/                   # 预处理后的数据（字符级 / 词级）
│   ├── save_models/                  # 保存的模型文件
│   │   ├── model_char_1_default_*.bin  # 字符级默认参数
│   │   ├── model_char_2_auto_*.bin     # 字符级自动调参
│   │   └── model_intent_word_default.bin # 词级默认参数
│   ├── config.py                     # 路径 + 类别映射词典
│   ├── data_preprocess.py            # 数据预处理（字符级 / 词级切割）
│   ├── fasttext_char_1_default.py    # 字符级 + 默认参数训练
│   ├── fasttext_char_2_auto.py       # 字符级 + 自动调参训练
│   ├── fasttext_word_1_default.py    # 词级 + 默认参数训练
│   ├── fasttext_word_2_auto.py       # 词级 + 自动调参训练
│   ├── ft_predict_fun.py             # 预测函数（供统一 Web 层直接调用）
│   └── api_flask_server.py           # 独立 Flask API 服务（可选）
│
└── 04-unified-web/                   # 统一 Web 展示层
    ├── static/                       # 前端静态资源
    │   ├── app.js                    # 前端交互逻辑
    │   └── styles.css                # 页面样式
    ├── templates/                    # HTML 模板
    │   ├── index.html                # 主页面
    │   └── components/               # 页面组件
    │       ├── hero.html             # 顶部横幅
    │       ├── analyzer.html         # 分析器区域
    │       ├── result_overview.html  # 结果概览
    │       ├── history.html          # 历史记录
    │       ├── sidebar.html          # 侧边栏
    │       └── top_header.html       # 顶部导航
    ├── tests/                        # 单元测试
    │   └── test_app.py
    ├── app.py                        # Flask 主服务（统一入口）
    ├── config.py                     # 配置管理（支持环境变量覆盖）
    ├── local_model_gateway.py        # 本地模型加载器（延迟加载 + 隔离导入）
    ├── requirements.txt              # 运行时依赖
    └── requirements-dev.txt          # 开发环境依赖
```

---

## 三、环境准备与运行

### 3.1 安装依赖

```bash
cd 04-unified-web
pip install -r requirements.txt
```

主要依赖：

| 包 | 用途 |
|----|------|
| Flask >= 3.0 | Web 服务框架 |
| requests >= 2.31 | HTTP 代理模式请求 |
| jieba >= 0.42 | 中文分词 |
| pandas >= 2.0 | 数据处理 |
| scikit-learn >= 1.4 | TF-IDF + 随机森林 |
| fasttext-wheel >= 0.9.2 | FastText 文本分类 |

### 3.2 启动统一 Web 服务（推荐）

默认采用**本地直调模式**，直接加载 `02-rf` 和 `03-fasttext` 的预测函数：

```bash
cd 04-unified-web
python app.py
```

服务启动后访问 `http://127.0.0.1:5002` 即可使用。

### 3.3 启动独立模型服务（可选）

如果需要以 HTTP 代理模式运行，先分别启动两个模型服务：

```bash
# 终端 1：随机森林情感分类服务（端口 5000）
cd 02-rf
python api_flask_server.py

# 终端 2：FastText 意图分类服务（端口 5001）
cd 03-fasttext
python api_flask_server.py

# 终端 3：统一 Web 服务（端口 5002，切换为 HTTP 模式）
cd 04-unified-web
set MODEL_ACCESS_MODE=http
python app.py
```

### 3.4 配置项

所有配置均可通过环境变量覆盖：

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `MODEL_ACCESS_MODE` | `local` | 模型接入模式：`local`（直调）/ `http`（代理） |
| `UNIFIED_WEB_HOST` | `127.0.0.1` | Web 服务监听地址 |
| `UNIFIED_WEB_PORT` | `5002` | Web 服务监听端口 |
| `RF_SERVICE_URL` | `http://127.0.0.1:5000` | 随机森林服务地址（HTTP 模式） |
| `FASTTEXT_SERVICE_URL` | `http://127.0.0.1:5001` | FastText 服务地址（HTTP 模式） |
| `UPSTREAM_TIMEOUT_SECONDS` | `8` | 上游服务超时时间（秒） |
| `MAX_COMMENT_LENGTH` | `5000` | 评论最大输入长度 |

---

## 四、数据说明

### 4.1 数据格式

所有训练数据采用 **Tab 分隔**格式：`评论内容\t标签`

| 内容 | 标签 | 所属任务 |
|------|------|----------|
| 这个手机拍照效果太好了，非常清晰 | positive | 情感分类 |
| 一般般吧，没什么特别的 | neutral | 情感分类 |
| 衣服质量太差了，穿一次就起球 | negative | 情感分类 |
| 快递三天就到了，速度还行 | logistics | 意图分类 |
| 买了个耳机，左耳没声音 | quality | 意图分类 |
| 客服态度非常好，耐心解答 | service | 意图分类 |
| 这个价格能买到这种品质，超值 | price | 意图分类 |

### 4.2 类别定义

**情感分类**（`sentiment_class.txt`）：`positive`、`neutral`、`negative`

**意图分类**（`intent_class.txt`）：`logistics`、`quality`、`service`、`price`、`default_praise`

---

## 五、模块说明

### 5.1 随机森林模块（02-rf）

| 文件 | 作用 |
|------|------|
| `bj_config.py` | 配置数据路径、模型保存路径、停用词路径等 |
| `dataEDA_processing.py` | 读取原始数据 → jieba 分词 → 去停用词 → 保存为 CSV |
| `rf_train.py` | TF-IDF 向量化 → 训练随机森林 → 评估（准确率/精确率/召回率/F1）→ 保存模型 |
| `rf_predict_fun.py` | 加载 pkl 模型 → 分词 → 向量化 → 预测 → 返回类别和置信度 |
| `api_flask_server.py` | 独立 Flask 服务，暴露 `/predict` 接口 |

### 5.2 FastText 模块（03-fasttext）

| 文件 | 作用 |
|------|------|
| `config.py` | 配置路径 + 构建类别映射词典 |
| `data_preprocess.py` | 字符级（逐字切割）和词级（jieba 分词）两种预处理 |
| `fasttext_char_1_default.py` | 字符级 + 默认超参数训练 |
| `fasttext_char_2_auto.py` | 字符级 + 自动调参训练 |
| `fasttext_word_1_default.py` | 词级 + 默认超参数训练 |
| `fasttext_word_2_auto.py` | 词级 + 自动调参训练 |
| `ft_predict_fun.py` | 加载最优模型 → 预处理 → 预测 → 返回意图类别 |
| `api_flask_server.py` | 独立 Flask 服务，暴露 `/predict` 接口 |

### 5.3 统一 Web 展示模块（04-unified-web）

| 文件 | 作用 |
|------|------|
| `app.py` | Flask 主服务，提供 `/api/predict/<task>` 统一预测接口 + 页面路由 |
| `config.py` | 配置管理，支持环境变量覆盖所有参数 |
| `local_model_gateway.py` | 本地模型加载器，按路径动态导入 `predict_fun`，延迟加载 + 线程安全 |
| `templates/` | 基于组件化设计的 HTML 模板 |
| `static/app.js` | 前端交互逻辑，调用分析接口并展示结果 |
| `static/styles.css` | 页面样式 |

---

## 六、调用链路

### 本地直调模式（默认）

```
浏览器 → 04-unified-web (app.py)
            → LocalModelGateway 加载 predict_fun
                → 02-rf/rf_predict_fun.py（情感分类）
                → 03-fasttext/ft_predict_fun.py（意图分类）
            ← 统一响应格式
        ← 页面展示结果
```

### HTTP 代理模式（可选）

```
浏览器 → 04-unified-web (app.py)
            → HTTP POST → 02-rf (port 5000) /predict
            → HTTP POST → 03-fasttext (port 5001) /predict
            ← 统一响应格式
        ← 页面展示结果
```

---

## 七、关键设计要点

1. **数据格式统一**：所有模块复用 `内容\t标签` 的 Tab 分隔格式，便于数据共享与扩展
2. **代码结构一致**：每个模块均遵循 `config → 预处理 → 训练 → 预测 → 部署` 链路
3. **模块间解耦**：`02-rf` 和 `03-fasttext` 各自独立，互不干扰；`04-unified-web` 作为展示层聚合结果
4. **双模式接入**：本地模式免去启动多个服务，HTTP 模式兼容分布式部署场景
5. **延迟加载 + 隔离导入**：模型仅在首次预测时加载，且通过命名空间隔离避免配置冲突
6. **技术递进**：随机森林（传统 ML）→ FastText（快速文本分类），体现从简单到复杂的技术演进