12 智能商品发布 — BERT 文本分类全栈项目

学习理念：这是课程中第一个"零淘汰技术"的纯实战项目。它不教新理论，而是演示"第 10 章的工程模式升级到 HuggingFace 时代应该怎么写"。不需要在 VS Code 里跟敲，通过本文档的对比图 + 架构图 + 核心代码，30 分钟就能吃透这个"乐高块"。遇到疑问时用 AI 插件问答式解惑，效率最高。
它在整体课程中的位置：第 10 章（从零训练）→ 第 11 章（NLP 理论）→ 第 12 章（预训练微调实战） → 第 19 章（大型项目）它是从"新手村"到"大型项目"之间的桥梁。

本节 AI 替代率：~75% | 人工干预率：~25%

角色	能力范围
🤖 AI 擅长	生成 Trainer 类代码、HF Datasets 管道、FastAPI 路由、Mermaid 类图
👤 人类需理解	预训练微调 vs 从零训练的区别、Trainer 的设计模式、AMP 的作用

技术栈健康度速览（OPC 7.4）

🟢🟡🟠🔴 = 学习优先级 | 🔥🟢⏳⚠️💀 = 技术健康度

技术	健康度
HuggingFace Transformers	🔥 巅峰
FastAPI + Pydantic	🔥 巅峰
HF Datasets	🔥 巅峰
AMP 混合精度训练	🟢 稳定
Early Stopping + Checkpoint	🟢 稳定
sklearn 评估指标	🟢 稳定

一、项目全景（3 分钟看懂）

解决什么问题

电商平台每天有海量商品上架，标题五花八门。需要自动把标题归类到正确品类：

输入："北欧欧慕料理机手持料理棒家用多功能手持式搅拌机..."
输出："家电"

输入："樱之歌蓝色之恋5件套日式釉下彩纯手绘家用餐具套装..."
输出："家居"

数据规模

数据集	条数	用途
train.txt	~70,000	训练
valid.txt	~9,000	验证 + 早停
test.txt	~9,000	最终评估

12 个分类

家居、家电、健康、服饰内衣、玩具、鞋靴箱包、香烟、粮油速食、美妆个护、食品、运动户外、酒

项目流程

二、🔥 从第 10 章到第 12 章：生产线升级

这是本文档最有价值的部分——理解"升级了什么"，而不是"写了什么代码"。

对比维度	第 10 章（智图寻宝）	第 12 章（智能商品发布）	为什么升级
模型来源	从零训练 `nn.Module`	`AutoModel.from_pretrained()`	预训练模型自带语言理解能力，微调几轮就够，不需要从零学起
训练封装	手写 `train_epoch()` 函数	`Trainer` 类封装	类封装可复用、可扩展，附带早停/检查点/AMP
Web 框架	Flask	FastAPI + Pydantic	FastAPI 原生异步、自动文档、类型校验
数据加载	`os.listdir` + 手写 Dataset	HF `load_dataset` + `DataCollatorWithPadding`	一行代码加载 CSV，动态 padding 省显存
训练加速	无	AMP 混合精度	训练速度提升 1.5-2x，显存降低 30%
容错	无	检查点保存/恢复	训练中断可从断点续训
超参管理	config.py 常量	`dataclass`	更 Pythonic，可序列化

三、🔥 核心类设计：Trainer

这是整个项目最值得看的部分。它本质上是一个"可复用的 BERT 微调引擎"。

类图

核心代码骨架（看懂这 20 行就够了）

python

class Trainer:
    def __init__(self, device, model, train_dataset, valid_dataset, 
                 collate_fn, compute_metrics, training_config):
        self.model = model.to(device)
        self.optimizer = torch.optim.Adam(model.parameters(), lr=training_config.learning_rate)
        self.scaler = torch.amp.GradScaler('cuda', enabled=training_config.use_amp)
        self.step = 1
        self.early_stop_best_score = -float('inf')
        self.early_stop_counter = 0

    def train_one_step(self, inputs):
        self.model.train()
        inputs = {k: v.to(self.device) for k, v in inputs.items()}
        with torch.autocast(device_type=self.device.type, dtype=torch.float16,
                            enabled=self.training_config.use_amp):
            outputs = self.model(**inputs)
            loss = outputs.loss
        self.scaler.scale(loss).backward()
        self.scaler.step(self.optimizer)
        self.scaler.update()
        self.optimizer.zero_grad()
        return loss.item()

    def train(self):
        for epoch in range(1, 1 + self.training_config.epochs):
            for inputs in dataloader:
                loss = self.train_one_step(inputs)
                if self.step % self.training_config.save_steps == 0:
                    metrics = self.evaluate()
                    if self._should_stop(metrics):
                        return  # 早停
                    self._save_checkpoint()
                self.step += 1

三个值得一提的工程细节

① AMP 混合精度

传统训练：所有计算用 float32 → 慢，但精度高
AMP 训练：大部分用 float16 → 快 1.5-2x，显存省 30%
         关键操作（如 loss 累加）保留 float32

代码体现：
    self.scaler = GradScaler('cuda', enabled=True)
    ...
    with torch.autocast(device_type='cuda', dtype=torch.float16):
        outputs = self.model(**inputs)

② 检查点机制

python

# 保存：模型权重 + 优化器状态 + scaler + step 计数
checkpoint = {
    'model_stata_dict': self.model.state_dict(),
    'optimizer_state_dict': self.optimizer.state_dict(),
    'scaler_state_dict': self.scaler.state_dict(),
    'step': self.step,
    'early_stop_best_score': ...,
    'early_stop_counter': ...
}
# 加载：检测到检查点存在 → 恢复训练

③ 与 HF 兼容的模型保存

python

# 保存为 HF 格式，可直接用 AutoModel.from_pretrained 加载
self.model.save_pretrained(str(Path(output_dir) / 'best'))
# 加载时
model = AutoModelForSequenceClassification.from_pretrained('models/best')

四、🟢 数据管道 + CLI 工作流

HF Datasets 数据预处理

python

# 一行代码加载 CSV
dataset_dict = load_dataset('csv', data_files={
    'train': 'data/raw/train.txt',
    'valid': 'data/raw/valid.txt',
    'test':  'data/raw/test.txt',
}, delimiter='\t')

# 分词 + 保存
dataset_dict = dataset_dict.map(tokenize, batched=True)
dataset_dict.save_to_disk('data/processed')

CLI 入口

python

# python main.py process
# python main.py train
# python main.py predict
# python main.py evaluate
# python main.py service

def main():
    parse = argparse.ArgumentParser()
    parse.add_argument('action', choices=['process','train','predict','evaluate','service'])
    args = parse.parse_args()
    # 分发到对应函数

FastAPI 部署

python

from fastapi import FastAPI
from pydantic import BaseModel

class Title(BaseModel):
    name: str | list

class Category(BaseModel):
    name: str | list

app = FastAPI()

@app.post('/predict')
def predict(title: Title) -> Category:
    category = predictor.predict(title.name)
    return Category(name=category)

API 调用时序（补 §18 标准）

技术栈深度评估

编号	技术	健康度	说明
T1	HuggingFace Transformers	🔥 巅峰	现代 NLP 的事实标准
T2	FastAPI + Pydantic	🔥 巅峰	替代 Flask 的现代框架
T3	HF Datasets	🔥 巅峰	数据处理标准库
T4	AMP 混合精度	🟢 稳定	训练加速标配
T5	Early Stopping + Checkpoint	🟢 稳定	工程最佳实践
T6	sklearn 评估指标	🟢 稳定	分类评估标准
T7	自定义 Trainer 类	🟢 稳定	HF 已有 Trainer，但手写理解原理也有价值
T8	TensorBoard	🟠 衰退	趋势是转向 WandB/MLflow

海外对标

企业	应用场景	技术方案
Amazon	商品分类	BERT-based 多模态分类
Shopify	商品元数据自动填充	RoBERTa 微调
阿里巴巴	商品标题分类	BERT + 知识蒸馏

学习路径

优先级	内容	时间	说明
🔥	理解"第 10 章 → 第 12 章"的升级对比	5 min	核心价值，看懂表格和图就够了
🔥	Trainer 类设计 + 三张 Mermaid 图	10 min	理解类结构、数据流、训练流
🟢	AMP / 检查点 / 早停	5 min	记住"有什么技术"即可，用到时查
🟢	FastAPI + CLI 工作流	5 min	和第 10 章的 Flask 对比理解
🟡	完整跑一遍（可选）	30 min	好奇的话 `python main.py process && python main.py train`

AI 协作指南

本文档看完后，如果你有以下疑问，直接问 AI 插件：

Q: "Trainer 类里的 scaler 是干什么的？"
Q: "为什么微调要设 learning_rate=5e-5，而从零训练要设 1e-3？"
Q: "AutoModelForSequenceClassification 和 AutoModel 有什么区别？"
Q: "DataCollatorWithPadding 动态 padding 和固定长度 padding 有什么区别？"

AI 能为你做的：
  - 解释 AMP 的原理和适用场景
  - 把 Trainer 类翻译成其他框架的版本（如 PyTorch Lightning）
  - 给出这个项目在生产环境中的改进建议（如分布式训练、模型量化）

🛠️ 从"看代码"到"跑起来"

本文档定位是理解项目架构。如果要在本地跑起来：

1️⃣ 环境检测

把下面的提示词发给 AI，让它根据你的电脑环境生成 requirements.txt：

text

我的环境是 [Windows/CUDA 12.x/Python 3.12]，
这个项目的依赖有 torch、transformers、datasets、fastapi、scikit-learn、pydantic、uvicorn，
帮我生成兼容的 requirements.txt，torch 版本要和 CUDA 版本匹配，检测是否有版本冲突。

2️⃣ 一键部署

发给 AI：

text

根据这个项目的代码入口 python main.py [process|train|predict|evaluate|service]，
帮我生成 Dockerfile + docker-compose.yml + .dockerignore，
基础镜像用 pytorch/pytorch:2.2-cuda12.1，
service 命令暴露 8000 端口。

3️⃣ 跑通验证

按顺序执行以下命令：

bash

python main.py process      # 预处理数据（约 1 分钟）
python main.py train        # 训练（如果显存不够，把 batch_size 改为 8）
python main.py evaluate     # 评估测试集
python main.py service      # 启动 FastAPI（浏览器访问 localhost:8000/docs）

4️⃣ 代码审查

跑完后如果想深入了解代码质量，发给 AI：

text

帮我审查这个项目的 runner/train.py 中的 Trainer 类：
1. AMP 的 scaler 使用是否正确？
2. 早停逻辑有没有 bug？
3. 检查点保存是否完整（中断后能否完全恢复训练）？
4. DataLoader 的 num_workers 设置是否合理？

附录：原始资料处理说明

原始文件	处理方式
`智能商品发布1.0.0.docx`	内容已整合到本文档，以图表为主
`3.代码/day2/`	核心代码骨架已提取展示
`bert-base-chinese` 预训练模型	路径保留，可直接用于微调练习
视频（day01 + day02）	跳过

修复情况：

✅ 技术栈健康度标签（OPC 7.4）
✅ 🟢🟡🟠🔴 优先级颜色
✅ Mermaid 架构图 / 类图 / 流程图 / 对比图
✅ 第 10 章 vs 第 12 章逐项对比表
✅ 核心代码骨架（20 行看懂 Trainer）
✅ 技术栈评估 + 海外对标
✅ AI 问答指引（替代 VS Code 实战的答疑渠道）
✅ 学习路径表（最短 25 分钟读完）

12 智能商品发布 — BERT 文本分类全栈项目 ​

一、项目全景（3 分钟看懂） ​

解决什么问题 ​

数据规模 ​

12 个分类 ​

项目流程 ​

二、🔥 从第 10 章到第 12 章：生产线升级 ​

三、🔥 核心类设计：Trainer ​

类图 ​

核心代码骨架（看懂这 20 行就够了） ​

三个值得一提的工程细节 ​

四、🟢 数据管道 + CLI 工作流 ​

HF Datasets 数据预处理 ​

CLI 入口 ​

FastAPI 部署 ​

API 调用时序（补 §18 标准） ​

技术栈深度评估 ​

海外对标 ​

学习路径 ​

AI 协作指南 ​

🛠️ 从"看代码"到"跑起来" ​

1️⃣ 环境检测 ​

2️⃣ 一键部署 ​

3️⃣ 跑通验证 ​

4️⃣ 代码审查 ​

附录：原始资料处理说明 ​

12 智能商品发布 — BERT 文本分类全栈项目

一、项目全景（3 分钟看懂）

解决什么问题

数据规模

12 个分类

项目流程

二、🔥 从第 10 章到第 12 章：生产线升级

三、🔥 核心类设计：Trainer

类图

核心代码骨架（看懂这 20 行就够了）

三个值得一提的工程细节

四、🟢 数据管道 + CLI 工作流

HF Datasets 数据预处理

CLI 入口

FastAPI 部署

API 调用时序（补 §18 标准）

技术栈深度评估

海外对标

学习路径

AI 协作指南

🛠️ 从"看代码"到"跑起来"

1️⃣ 环境检测

2️⃣ 一键部署

3️⃣ 跑通验证

4️⃣ 代码审查

附录：原始资料处理说明