基于 PaddleNLP SimpleServing 的多标签文本分类服务化部署实战指南

• 人工智能
• 大模型
• 预训练
• 微调
• LoRA
• RLHF
• 强化学习
• 分布式训练

多标签文本分类模型（如基于 ERNIE 3.0 / ERNIE-M 微调的分类模型）训练并导出静态图后，可通过 PaddleNLP 内置的SimpleServing能力，用寥寥几行代码启动一个基于 FastAPI + uvicorn 的高性能 HTTP 推理服务，并配套一个可配置max_seq_len、batch_size、prob_limit的 Python 客户端。本文将以此仓库中multi_label/deploy/simple_serving目录为骨架，完整讲解从环境准备、Server 启动、客户端调用到核心参数语义的端到端部署流程，并结合 PaddleNLP 服务端源码剖析其底层实现原理。

目录

• 一、部署前置条件与环境准备
• 二、simple_serving 目录结构与关键文件
• 三、启动多标签分类 Server 服务
• 四、分类任务客户端请求与响应
• 五、核心参数 max_seq_len / batch_size / prob_limit 详解
• 六、SimpleServing 的注册与底层处理链路
• 七、部署注意事项与完整流程回顾

一、部署前置条件与环境准备

SimpleServing 是 PaddleNLP 内置的服务化部署组件，其核心依赖位于仓库的 paddlenlp/server 目录。使用前需要确保环境中安装了带 SimpleServing 功能的 PaddleNLP 版本，官方推荐的安装方式是直接升级到最新版：

pip install paddlenlp --upgrade

除此之外，多标签分类服务的输入是文本、输出是标签列表，因此环境中还需要具备可用的paddlepaddle/paddlepaddle-gpu（推理后端）以及requests（客户端 HTTP 请求库）。参考 多标签分类指南 中给出的运行环境基线：python >= 3.6、paddlepaddle >= 2.3、paddlenlp >= 2.4.8。

注意：SimpleServing 通过paddlenlp server命令启动，其内部实际是调用 uvicorn 运行 FastAPI 应用（见 paddlenlp/cli/server.py 中的uvicorn.run(app, **kwargs)），因此部署机器上需要保证该命令可正常解析server.py/ernie_m_server.py中定义的 FastAPI 应用对象。

服务化部署的前置步骤：训练与静态图导出

SimpleServing 部署的是静态图推理模型，因此在启动服务之前，需要先用训练好的动态图 checkpoint 导出静态图。以 export_model.py 为例：

# 普通中文预训练模型（如 ernie-3.0-medium-zh） python export_model.py --params_path ./checkpoint/ --output_path ./export # 多语言模型 ERNIE-M 需要加 --multilingual 参数 python export_model.py --params_path ./checkpoint/ --output_path ./export --multilingual

导出产物保存在output_path（默认./export）中，结构如下：

export/ ├── float32.pdiparams ├── float32.pdiparams.info └── float32.json(PIR enabled)/float32.pdmodel(PIR disabled)

注意server.py与ernie_m_server.py中注册服务时使用的model_path="../../export"是相对于simple_serving目录的相对路径（即slm/applications/text_classification/multi_label/deploy/simple_serving/../../export，等价于multi_label/export），所以启动服务前请确认静态图模型确实导出了该目录。

二、simple_serving 目录结构与关键文件

部署相关文件位于仓库 slm/applications/text_classification/multi_label/deploy/simple_serving 目录：

simple_serving/ ├── README.md # 部署说明（本文所依托的原始文档） ├── client.py # HTTP 客户端，发送待预测文本与推理参数 ├── server.py # 标准中文分类模型的 SimpleServer 服务 └── ernie_m_server.py # 多语言 ERNIE-M 模型的 SimpleServer 服务

三个 Python 文件各司其职：

• server.py：面向 ERNIE 3.0 等中文预训练模型，注册路由models/cls_multi_label，模型路径../../export，分词器ernie-3.0-medium-zh，使用CustomModelHandler+MultiLabelClassificationPostHandler。
• ernie_m_server.py：面向多语言预训练模型 ERNIE-M，分词器改为ernie-m-base，模型处理器替换为ERNIEMHandler，其余注册方式一致。
• client.py：构造 JSON 请求体，通过requests.post将文本与参数提交给服务端。

三、启动多标签分类 Server 服务

3.1 标准分类任务启动

在simple_serving目录下执行：

paddlenlp server server:app --host 0.0.0.0 --port 8189

• server:app表示从 server.py 中加载名为app的 FastAPI 应用对象（即SimpleServer实例）；
• --host 0.0.0.0使服务监听所有网络接口，便于局域网或跨机调用；
• --port 8189指定 HTTP 服务端口。

服务启动后，会注册一个名为models/cls_multi_label的推理路由。server.py中的注册逻辑如下：

from paddlenlp import SimpleServer from paddlenlp.server import CustomModelHandler, MultiLabelClassificationPostHandler app = SimpleServer() app.register( "models/cls_multi_label", model_path="../../export", tokenizer_name="ernie-3.0-medium-zh", model_handler=CustomModelHandler, post_handler=MultiLabelClassificationPostHandler, )

register的参数包括：路由名称task_name、静态图模型路径model_path、分词器名称tokenizer_name（会自动通过AutoTokenizer.from_pretrained加载）、负责「文本 → logits」的model_handler，以及负责「logits → 标签/置信度」的post_handler。此外，register还支持precision="fp32"与device_id=0两个可选参数（见 paddlenlp/server/server.py）。

3.2 ERNIE-M 多语言模型启动

如果部署的是多语言预训练模型 ERNIE-M（例如面向法语、日语、韩语等多语种的多标签任务），则改用ernie_m_server.py：

paddlenlp server ernie_m_server:app --host 0.0.0.0 --port 8189

其注册逻辑在 ernie_m_server.py 中，唯一的路由名仍是models/cls_multi_label，但分词器换为ernie-m-base、模型处理器换为ERNIEMHandler。ERNIE-M 的 tokenizer 与标准 ERNIE 不同（不依赖token_type_ids的分词产物结构存在差异），因此必须使用专用 Handler 才能正确喂入推理引擎。

四、分类任务客户端请求与响应

4.1 客户端脚本使用

服务启动后，在另一个终端执行：

python client.py

client.py 内置了三条例文类文本作为示例（与 multi_label/README.md 中的data.txt样例保持一致），并支持三个命令行参数：

python client.py --max_seq_len 128 --batch_size 1 --prob_limit 0.5

4.2 请求体结构

客户端构造的 JSON 请求体分为data与parameters两个字段：

data = { "data": { "text": texts, # 待预测文本，可以是字符串或字符串列表 }, "parameters": { "max_seq_len": args.max_seq_len, "batch_size": args.batch_size, "prob_limit": args.prob_limit, }, } r = requests.post(url=url, headers=headers, data=json.dumps(data)) print(json.loads(r.text))

请求地址为http://0.0.0.0:8189/models/cls_multi_label，请求头为{"Content-Type": "application/json"}。data.text支持单条字符串，也支持多条文本组成的列表（服务端会在 Handler 内自动包装成列表并逐条分词、分批推理）。data字段还可选传入text_pair，用于句子对（text pair）分类场景。

4.3 响应格式

多标签分类的响应由MultiLabelClassificationPostHandler生成，格式为：

{ "label": [[0, 2], [1]], "confidence": [[0.93, 0.87], [0.72]] }

其中label中的每个元素是通过概率阈值的标签下标列表（下标对应label.txt中标签的顺序），confidence是对应下标位置的 sigmoid 概率值。

五、核心参数 max_seq_len / batch_size / prob_limit 详解

这三个参数在客户端parameters字段中透传给服务端，其取值直接影响推理的精度与吞吐。

5.1 服务端如何处理这三个参数

在 custom_model_handler.py 的CustomModelHandler.process中：

• 从parameters中读取max_seq_len与batch_size（未传则使用默认值 128 / 1）；
• 使用tokenizer(text=..., max_length=max_seq_len)对每条文本分词，取input_ids与token_type_ids；
• 按batch_size将样本切成多个 batch，用Pad补齐后逐个 batch 调用 Paddle Inference 预测引擎；
• 输出{"logits": ..., "data": ...}交给后处理 Handler。

在 cls_post_handler.py 的MultiLabelClassificationPostHandler.process中：

• 读取parameters["prob_limit"]（未传默认0.5）；
• 对 logits 施加sigmoid 激活：logits = 1 / (1 + np.exp(-logits))，将原始 logits 映射到 (0,1) 概率区间；
• 遍历每条样本的每个标签位，仅保留p > prob_limit的标签下标及其概率。

与单标签分类MultiClassificationPostHandler使用 softmax + argmax 不同，多标签分类类别互不排斥，因此必须使用逐位 sigmoid 加阈值筛选的方式，prob_limit正是控制「一个样本最终输出几个标签」的关键旋钮。调高阈值可减少误报标签，调低阈值可提升召回。

5.2 参数取值范围建议

• max_seq_len：参考训练阶段的设置（multi_label/README.md 建议 128/256/512，ERNIE 系列不超过 2048）。若显存不足应适当调低；过短会导致长文本信息丢失、影响精度。
• batch_size：结合 GPU 显存或 CPU 内存调整，一般建议与服务端推理设备算力匹配，越大吞吐越高。
• prob_limit：0～1 之间的浮点数，具体最优值可在验证集上按 Micro F1 / Macro F1 扫描确定；默认 0.5 是一个中性起点。

六、SimpleServing 的注册与底层处理链路

6.1 SimpleServer 与路由注册

SimpleServer继承自 FastAPI（paddlenlp/server/server.py），内部组合了HttpRouterManager、ModelManager等组件：

• register()创建ModelManager（负责加载静态图模型与 tokenizer）并调用HttpRouterManager.register_models_router(task_name)注册 HTTP 路由；
• 同一服务可注册多个模型路由（每个register对应一个task_name），路由名在客户端 URL 中以/models/{task_name}形式访问。

6.2 模型加载与设备选择

在 model_manager.py 中：

• precision默认"fp32"，可传入如"fp16"等精度配置；
• device_id默认0；当device_id == -1时回退到 CPU 推理，传入整数则使用对应编号的 GPU（gpu:{device_id}），传入列表可同时初始化多张卡。

因此如果部署机器只有 CPU，除了在register中调整device_id=-1，也可以改造server.py的注册参数来指定推理后端。

6.3 完整的请求处理链路

一次完整的 HTTP 推理请求经过如下链路：

客户端 POST /models/cls_multi_label ↓ HttpRouterManager（FastAPI 路由） ↓ CustomModelHandler.process（分词 → 分批 → Paddle Inference 推理 → logits） ↓ MultiLabelClassificationPostHandler.process（sigmoid → 阈值筛选 → label + confidence） ↓ JSON 响应返回客户端

其中模型 Handler 直接驱动 Paddle Inference 预测器（Predictor），支持paddle_inference与通用两种执行路径，逐 batch 将input_ids/token_type_ids拷贝进输入句柄并取回输出（见 custom_model_handler.py）。

七、部署注意事项与完整流程回顾

7.1 常见问题与注意事项

• 模型路径对齐：server.py中的model_path="../../export"是相对simple_serving目录的路径，务必先执行export_model.py导出静态图到multi_label/export，否则服务启动时会因找不到模型而失败。
• ERNIE-M 必须用对应文件：多语言模型的分词产物与推理输入不同，必须用ernie_m_server.py启动，否则输入张量不匹配。
• 端口与防火墙：服务监听0.0.0.0:8189，跨机调用时需放通该端口的入站流量。
• 参数一致性：max_seq_len建议与训练阶段一致；prob_limit按业务对精度/召回的要求调节。
• 服务安全：SimpleServing 默认不设鉴权，生产环境建议置于网关或内网之后。

7.2 从训练到上线的完整流程

将 multi_label/README.md 中的全流程与本文衔接，即可得到一条完整的部署链路：

1. 数据准备：train.txt / dev.txt / label.txt（tab 分隔、多标签用逗号分隔） 2. 模型训练：python train.py --model_name ernie-3.0-medium-zh ... 3. 静态图导出：python export_model.py --params_path ./checkpoint/ --output_path ./export 4. 启动服务：paddlenlp server server:app --host 0.0.0.0 --port 8189 5. 客户端调用：python client.py --max_seq_len 128 --batch_size 1 --prob_limit 0.5

其中每一步的配套脚本与文档均已收录在仓库 slm/applications/text_classification/multi_label 目录下，包括训练脚本 train.py、导出脚本 export_model.py，以及离线部署 deploy/predictor/README.md、Paddle Serving deploy/paddle_serving、Triton deploy/triton_serving/README.md 等多种部署方案，供不同场景按需选用。

综上，PaddleNLP SimpleServing 以「注册式」配置将「分词 → 推理 → 后处理」封装为可复用的处理链路，配合paddlenlp server命令即可在分钟级内完成多标签分类模型的 HTTP 服务化部署，是快速落地文本分类推理服务的低成本方案。

• 人工智能
• 大模型
• 预训练
• 微调
• LoRA
• RLHF
• 强化学习
• 分布式训练