# tmf_v1

**Repository Path**: WorldEating/tmf_v1

## Basic Information

- **Project Name**: tmf_v1
- **Description**: 国内IT教育头部企业著名文本分类项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 64
- **Created**: 2026-06-24
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TMF v2 — 中文文本分类服务

基于 **FastText** 的中文短文本分类项目，支持离线训练流水线和在线推理服务，附带 Streamlit 可视化交互界面。

**10 个分类类别**：财经 `finance` · 房产 `realty` · 股票 `stocks` · 教育 `education` · 科技 `science` · 社会 `society` · 政治 `politics` · 体育 `sports` · 游戏 `game` · 娱乐 `entertainment`

**性能指标**：测试集 F1 **91.18%** | 单条推理 p50 **0.04 ms** | QPS **27,496**

---

## 项目结构

```
tmf_v2/
├── wsgi.py                    # Flask 服务入口
├── run_pipeline.py            # 离线训练流水线编排
├── app/                       # Web 应用层
│   ├── __init__.py            # Flask 工厂函数 + 中间件（CORS / 异常兜底）
│   ├── config.py              # 环境配置（开发 / 生产）
│   ├── extensions.py          # 模型单例扩展（启动时加载一次）
│   └── v2/
│       ├── __init__.py
│       └── predict.py         # /api/v2/predict 推理接口（Top-3 支持）
├── src/                       # 机器学习层（不依赖 Flask）
│   ├── config.py              # 路径与常量集中管理
│   ├── data_pre.py            # 数据预处理（清洗 → jieba 分词 → 去停用词 → FastText 格式）
│   ├── model_train.py         # 模型训练 + 验证集评估（FastText 分类报告 + 混淆矩阵 + 错分分析）
│   ├── model_eval.py          # 测试集评估（全量 + 抽样压测）
│   └── utils.py               # 工具函数
├── front/
│   └── tmf_app.py             # Streamlit 用户交互界面
├── tests/
│   └── test_api.py            # API 接口测试（pytest + parametrize）
├── data/
│   ├── stopwords.txt          # 停用词表
│   ├── tmf_class.txt          # 类别标签
│   ├── raw/                   # 原始 TSV 数据
│   └── pre/                   # 预处理后数据（FastText 格式，Git 不纳管）
├── models/
│   └── text-clf-model.bin     # FastText 模型（Git 不纳管）
├── pytest.ini                 # pytest 标记注册（smoke / api）
├── tmf_v2_history.yml         # Conda 环境导出
└── README.md
```

---

## 快速开始

### 环境要求

- Python 3.12+
- Conda 环境 `tmf_v2`

```bash
# 方式 1：从 yml 还原环境
conda env create -f tmf_v2_history.yml

# 方式 2：手动安装
conda create -n tmf_v2 python=3.12 flask pandas requests pytest pip -y
conda activate tmf_v2
conda install -c conda-forge jieba "numpy<2" -y
pip install fasttext-wheel streamlit
```

### 离线训练

```bash
# 一键流水线（数据预处理 → 训练 → 评估）
python run_pipeline.py

# 或分步执行
python src/data_pre.py        # Step 1: 数据预处理 → FastText 格式
python src/model_train.py     # Step 2: 模型训练 + 验证集评估
python src/model_eval.py      # Step 3: 测试集评估 + 抽样压测
```

`run_pipeline.py` 顶部开关控制需要跳过的步骤：

```python
ENABLE_PREPROCESS = True
ENABLE_TRAIN      = True
ENABLE_EVALUATE   = True
```

### 启动在线服务

```bash
# 终端 1：启动 Flask API（端口 5000）
python wsgi.py

# 终端 2：启动 Streamlit 界面（端口 8501）
streamlit run front/tmf_app.py
```

### 调用 API

```bash
curl -X POST http://127.0.0.1:5000/api/v2/predict \
  -H "Content-Type: application/json" \
  -d '{"text": "NBA总决赛精彩绝伦湖人夺冠"}'
```

响应示例：

```json
{
  "label": "sports",
  "probability": 0.9512,
  "code": 0,
  "message": "ok",
  "top3": [
    {"label": "sports", "probability": 0.9512},
    {"label": "game", "probability": 0.0321},
    {"label": "entertainment", "probability": 0.0123}
  ]
}
```

支持 Top-K 参数：

```bash
curl -X POST http://127.0.0.1:5000/api/v2/predict \
  -H "Content-Type: application/json" \
  -d '{"text": "...", "top_k": 5}'
```

缺少文本时：

```json
{"code": -10, "message": "请提供要分类的文本内容"}
```

### 运行测试

```bash
# 先确保 Flask 服务已启动，然后：
pytest tests/ -v           # 全部
pytest -m smoke -v         # 仅冒烟（确认服务存活）
pytest -m api -v           # 仅接口用例
```

---

## 技术架构

```
离线训练流水线
  原始 TSV → data_pre.py → FastText 格式 → model_train.py → model_eval.py → 模型 .bin
                                                      │
在线推理服务                                              │
  wsgi.py → app/__init__.py → app/extensions.py ← 启动加载 ←───┘
               │                    │
               ▼                    ▼ (只加载一次)
         /api/v2/predict    model + stopwords + labels
               │                    │
               ▼                    ▼
  front/tmf_app.py        current_app.model / .stopwords
  (Streamlit 界面)        (应用级单例，启动时挂载)
```

| 层级 | 职责 | 说明 |
|------|------|------|
| `src/` | 机器学习 | 预处理、训练、评估，不依赖 Web 框架 |
| `app/` | Web 服务 | 工厂模式 Flask，蓝图版本化路由，中间件 |
| `front/` | 用户界面 | Streamlit 消费 `/api/v2/predict` |
| `tests/` | 测试 | pytest + parametrize，smoke / api 标签 |

---

## 模型参数

| 参数 | 值 | 说明 |
|------|-----|------|
| `lr` | 0.71 | 学习率 |
| `epoch` | 58 | 训练轮数 |
| `wordNgrams` | 5 | 词级 n-gram |
| `dim` | 440 | 词向量维度 |
| `minn` / `maxn` | 3 / 6 | 字符级 n-gram（处理 OOV） |
| `loss` | softmax | 多分类损失 |

> 以上参数由 FastText autotune 在 5 分钟内自动搜索得到。

---

## 版本历史

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| `v2.0.0` | 2026-06-25 | FastText 迁移：移除 sklearn/ONNX，autotune 自动调参，Top-3 预测，置信度可视化 |
| `v1.0.0` | 2026-06-25 | TF-IDF + RandomForest 基准版本 |

---

## License

仅供学习交流使用。