Transformers pipeline快速完成文本分类

用 Transformers 完成文本分类，最短路径是加载一个已经针对分类任务微调好的模型，再把它交给 pipeline。下面的示例以 Hugging Face 官方文档中的英文情感分类模型为例：输入文本后，pipeline 负责分词、调用 SequenceClassification 模型，并把结果整理成包含 label 和 score 的对象。

官方文档：https://huggingface.co/docs/transformers/main_classes/pipelines

这个例子解决的是“怎样快速接通文本分类推理”，不是训练新模型。换成中文分类、新闻分类或业务标签时，应把模型替换为与目标语言、标签集合和任务定义匹配的 checkpoint；不能因为接口名相同，就把英文情感模型直接当成中文业务分类器。

先选对模型，再谈 pipeline 参数。pipeline 能简化推理接线，但不会替你修正训练数据、标签含义或模型适用范围。

准备环境与分类模型

Transformers 需要配合 PyTorch 或 TensorFlow 等后端。为了让示例的运行环境更直观，可以在虚拟环境中安装 Transformers 和 PyTorch，再用一个已经微调好的文本分类模型做最小实验。安装命令只负责准备依赖，模型权重会在第一次加载时按模型配置获取。

# 创建隔离环境，避免把实验依赖混入系统 Python
python -m venv .venv
source .venv/bin/activate

# 安装文本分类接口和 PyTorch 后端
python -m pip install -U transformers torch

本文使用的演示模型是 distilbert/distilbert-base-uncased-finetuned-sst-2-english，它适合展示英文正负面情感分类接口。实际项目应先阅读模型卡，确认标签、语言、输入长度和许可证，再把模型标识写进应用配置，而不是散落在多个脚本中。

用 pipeline 建立最小文本分类组件

pipeline 把 tokenizer、模型和任务适配层组合起来。明确写出任务和模型，便于读者看清“这是什么任务”和“由哪个模型负责预测”；device=-1 表示把推理放在 CPU 上，适合先验证流程。

from transformers import pipeline

# 使用已经微调好的英文二分类模型，先固定在 CPU 上跑通接口
classifier = pipeline(
    task="text-classification",
    model="distilbert/distilbert-base-uncased-finetuned-sst-2-english",
    device=-1,  # -1 表示 CPU；有可用 CUDA 设备时再按部署环境调整
)

# 输入一条文本，结果通常包含预测标签和对应分数
result = classifier("The documentation is clear and easy to follow.")
print(result)

返回值通常是一个列表，列表中的字典包含 label 与 score。这里的 score 是模型在当前标签空间上的输出分数，不能直接当成业务概率、人工审核结论或跨模型可比较的置信度。对于多标签或回归任务，还要按模型任务定义理解输出。

从图中的三个边界看，输入层只负责提供文本，推理组件负责 tokenizer 与模型，分类结果负责解释标签和分数。这样拆分后，替换模型时重点检查输出标签是否仍符合调用方约定，而不是只看 Python 调用是否还能返回对象。

把多条文本交给同一个 pipeline

当待分类内容已经在内存中，可以把字符串列表直接传给同一个 pipeline。batch_size 是推理批大小的提示，是否更快取决于模型、后端、文本长度和设备；它不是“越大越好”的固定性能开关。教学示例把输入控制在一个小列表，避免把大文件一次性读入内存。

from transformers import pipeline

# 多条文本共享同一个模型和 tokenizer，避免重复初始化组件
classifier = pipeline(
    task="text-classification",
    model="distilbert/distilbert-base-uncased-finetuned-sst-2-english",
    device=-1,  # 没有 GPU 时使用 CPU；生产环境按可用设备配置
)

texts = [
    "The support team answered quickly.",
    "The setup guide is confusing.",
    "The example is short but useful.",
]

# batch_size 只控制一次送入后端的分组提示，不改变标签定义
results = classifier(texts, batch_size=2)
for text, result in zip(texts, results):
    # 保留原文与结果的对应关系，便于后续写入业务记录
    print({"text": text, "prediction": result})

如果文本来自文件、消息队列或数据库，不要先无上限地构造一个超大列表。可以分块读取、分块调用，再把结果写入下游存储。这样能把“输入集合的规模”和“单次推理的批大小”分成两个可调参数。

用 top_k 查看多个候选标签

默认结果通常只给出一个预测标签。如果业务需要同时查看多个候选，可以在调用时使用 top_k。这适合做人工复核、候选标签展示或后续阈值决策，但它不等于模型突然拥有了更多正确答案；候选仍来自模型已经训练好的标签集合。

# 请求每条文本的多个候选标签，用于人工复核或阈值判断
top_results = classifier(
    "The documentation is clear and easy to follow.",
    top_k=2,  # 只展示前两个候选，不改变模型训练出来的标签集合
)

for item in top_results:
    # 标签和分数一起保留，避免只记录一个难以解释的数字
    print(item["label"], item["score"])

不同 Transformers 版本和参数组合可能让单条输入、批量输入以及 top_k 的返回嵌套层级有所区别。接入 API 时，建议在自己的适配层里统一成固定结构，例如把每条输入归一化为 {text, predictions}，而不是让前端直接依赖 pipeline 的原始嵌套形状。

CPU、GPU 与模型替换的边界

先用 CPU 跑通单条文本，再决定是否切换设备，通常更容易区分“模型或标签配置错误”和“运行资源不足”。在有兼容 CUDA 环境时可以把 device 改为对应设备编号，但必须同时确认 PyTorch 安装方式、显存和模型规模。不要只把参数改成 device=0 就假定环境已经具备 GPU。

模型替换时至少对照四项：任务类型是否是 sequence classification；标签名是否被正确写入配置；输入语言和领域是否匹配；模型许可是否满足项目要求。pipeline 的统一入口让替换变简单，也更容易把不兼容的模型“接上却用错”，因此模型卡和配置仍是必要的事实来源。

常见问题

pipeline 能不能直接完成中文文本分类？

接口可以处理中文字符串，但分类效果取决于所选模型是否用目标语言和目标标签训练。应选择中文或多语言、且任务定义匹配的 sequence classification 模型，不能把英文情感模型的输出解释成中文业务类别。

为什么返回的 label 看起来不是自己的业务标签？

label 来自模型配置和训练标签映射。若想得到“售后”“物流”“退款”等业务类别，模型本身必须按这些标签训练或提供对应映射；仅在 pipeline 外层改一个显示字符串不会改变模型预测。

batch_size 调大后一定更快吗？

不一定。批大小会受到文本长度、设备吞吐、内存或显存以及后端实现影响。应按输入分块，并在目标环境中观察资源和延迟；不要用一个机器上的经验值替代部署环境的测量。

score 能直接作为业务阈值吗？

可以把 score 作为模型输出的一部分参与规则设计，但阈值需要结合任务、误报漏报成本和独立评估数据确定。不能只因为数值看起来接近1，就把它当成经过校准的概率或人工确认结果。

完成最小实验后，推荐把模型标识、设备、批大小和标签归一化逻辑放进一个明确的配置层。这样 pipeline 负责稳定的推理接线，业务代码负责输入分块、结果结构和阈值策略，后续替换模型时也更容易定位差异。

Transformers pipeline 文档：https://huggingface.co/docs/transformers/main_classes/pipelines

模型目录：https://huggingface.co/models