# tmf_v5

**Repository Path**: WorldEating/tmf_v5

## Basic Information

- **Project Name**: tmf_v5
- **Description**: 综合新闻文本分类，包含sk-leran,fasttext,bert,llm等模型
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-06-29
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TMF v5 — 四引擎中文新闻分类平台

> Topic Model Framework v5：统一协议层，可插拔的四引擎中文短文本分类系统。

## 架构

```
┌──────────────────────────────────────────────┐
│          Streamlit 前端 (port 8501)           │
│    📊 新闻仪表盘  │  🔬 分类工作台             │
└──────────────────┬───────────────────────────┘
                   │ REST API
┌──────────────────▼───────────────────────────┐
│          Flask API (port 5001 / 8000)         │
│    /predict  /predict_batch  /articles        │
│    单条+批量预测 · 分类入库 · 按条件删除        │
└──────────────────┬───────────────────────────┘
                   │ Engine Protocol（接缝）
┌──────────────────▼───────────────────────────┐
│ 🧠 BERT      ⚡ FastText   🌲 Sklearn   🤖 LLM │
│ RoBERTa      监督分类      TF-IDF+RF    DeepSeek│
│ 94.75% F1    0.04ms        0.5ms        远程API │
│                                              │
│ 降级链: BERT → FastText → Sklearn → (LLM可选) │
└──────────────────────────────────────────────┘
```

## 快速开始

### Docker 部署（推荐）

```bash
git clone git@gitee.com:WorldEating/tmf_v5.git
cd tmf_v5

# 准备模型文件（一次性）
bash setup_models.sh

# 配置 LLM API Key（可选，不配也能用）
cp .env.example .env
# 编辑 .env → 填入 LLM_API_KEY

# 启动
docker-compose -f docker/docker-compose.yml up -d --build
```

浏览器访问 http://localhost

### 本地开发

```bash
# 1. 环境
conda create -n tmf_v5 python=3.12 && conda activate tmf_v5
pip install -r requirements.txt

# 2. 配置（可选）
cp .env.example .env

# 3. 启动后端
python wsgi.py

# 4. 启动前端（新终端）
streamlit run front/tmf_app.py
```

访问 http://localhost:8501

## 四引擎对比

| 引擎 | 原理 | 速度 | 准确率 | 需要 |
|------|------|------|--------|------|
| 🧠 **BERT** | RoBERTa 微调 | CPU 300ms / GPU 5ms | 94.75% F1 | PyTorch |
| ⚡ **FastText** | 监督文本分类 | 0.04ms | ~93% | fasttext 模型 |
| 🌲 **Sklearn** | TF-IDF + 随机森林 | 0.5ms | ~91% | joblib 模型 |
| 🤖 **LLM** | DeepSeek API | 2000-3000ms | ~95% | API Key（可选） |

**降级链**：引擎失败时自动沿链回退，前端透明。LLM 未配置 API Key 时自动跳过。

## API 文档

Base URL: `http://127.0.0.1:5001/api/v5`（本地）/ `http://localhost/api/v5`（Docker）

### 引擎信息
```
GET /engines
```

### 单条预测
```
POST /predict
Body: {"text": "今日股市大涨", "engine": "bert", "top_k": 3}
```

### 批量预测
```
POST /predict_batch
Form: file=<CSV/TXT>, engine=fasttext, top_k=1
```
上传 CSV（含 text/content/内容/文本 列）或 TXT（每行一条），最多 5000 条。

### 分类并入库
```
POST /articles/classify
Body: {"text": "...", "engine": "bert"}
```

### 批量分类并入库
```
POST /articles/classify_batch
Form: file=<CSV/TXT>, engine=fasttext, top_k=1
```

### 文章管理
```
GET    /articles?category=sports&page=1&per_page=6
GET    /stats
DELETE /articles/<id>                    # 删除单篇
DELETE /articles  Body: {"ids":[1,2,3]}  # 按 ID 批量删除
DELETE /articles  Body: {"category":"sports"}  # 按分类删除
DELETE /articles  Body: {"engine":"bert"}      # 按引擎删除
DELETE /articles  Body: {"all":true}           # 删除全部
```

## 项目结构

```
tmf_v5/
├── wsgi.py                   # Flask 入口
├── setup_models.sh           # 模型准备脚本
├── .env.example              # 环境变量模板
├── app/
│   ├── __init__.py           # Flask 工厂
│   ├── config.py             # Flask 配置
│   ├── extensions.py         # 引擎懒加载 + 预加载 + 降级
│   └── v5/predict.py         # API 蓝图（所有端点）
├── src/
│   ├── config.py             # 引擎配置（路径优先级：env > Docker > 本地）
│   ├── core_types.py         # Prediction / Inference / BatchResult
│   ├── errors.py             # 统一错误层级
│   ├── storage.py            # SQLite 文章存储 + 删除
│   └── engine/
│       ├── protocol.py       # Engine Protocol（接缝）
│       ├── registry.py       # 自注册引擎发现
│       ├── bert_engine.py    # RoBERTa 适配器
│       ├── fasttext_engine.py # FastText 适配器
│       ├── sklearn_engine.py  # Sklearn 适配器
│       └── llm_engine.py     # LLM API 适配器（DeepSeek）
├── front/
│   └── tmf_app.py            # Streamlit 前端
├── docker/                   # Docker 部署文件
│   ├── flask/Dockerfile      # Flask 镜像（双模式：COPY / git clone）
│   ├── streamlit/Dockerfile  # Streamlit 镜像
│   ├── nginx/nginx.conf      # 反向代理 + WebSocket
│   └── docker-compose.yml    # 三服务编排
├── docs/docker/
│   └── DOCKER_DEPLOY.md      # 容器化部署完整方案
├── tests/                    # 测试
└── data/                     # SQLite 数据库（运行时生成）
```

## 技术亮点

- **引擎协议**：新增引擎只需在 `src/engine/` 下添加 `*_engine.py` + `@register` 装饰器
- **自动降级**：引擎失败沿降级链回退，前端透明展示回退路径
- **预加载**：启动时后台线程加载所有模型，首次请求无需等待；Gunicorn `--preload` 下 worker 共享模型内存
- **分数稀疏设计**：`Prediction` 仅设置一个引擎专属分数字段，防止跨引擎无效比较
- **双模式构建**：`docker build --build-arg BUILD_MODE=local|remote`，本地开发用 COPY、发布用 git clone
- **镜像内置模型**：BERT/FastText/Sklearn 模型打入镜像，一条命令开箱即用；支持卷挂载覆盖
- **LLM 四级策略**：不启用 / 用户自带 Key / 管理员配置 / 本地 Ollama 替代

## Docker 部署详情

完整方案见 [`docs/docker/DOCKER_DEPLOY.md`](docs/docker/DOCKER_DEPLOY.md)，覆盖：

- 三容器编排（Flask + Streamlit + Nginx）
- 双模式 Dockerfile（本地 COPY / git clone 远程）
- 模型打入镜像 + 卷挂载覆盖
- LLM API Key 四级部署策略
- GPU 支持、健康检查、日志轮转
- 参考项目对比分析

### Registry 模式（预构建镜像部署）

服务端无需构建，直接拉取 Docker Hub 预构建镜像启动：

```bash
# 1. 在 .env 中配置
REGISTRY=wordeater2946
TAG=v1.0.0

# 2. 服务端启动（无需本地构建）
docker-compose -f docker/docker-compose.yml \
               -f docker/docker-compose.registry.yml \
               -f docker/docker-compose.prod.yml \
               up -d

# 3. 升级
docker-compose pull && docker-compose up -d
```

镜像已内置模型文件（Flask 12.4GB），一条命令开箱即用。如需覆盖模型，挂载卷即可（见 `docker-compose.yml` 注释）。