企业官网建设流程全解析

• 人工智能
• 大模型
• 低代码
• 计算机视觉
• 深度学习
• NLP
• 模型推理服务
• RAG

本篇指南以 docs/pipeline_deploy/serving.md 为核心骨架，结合 PaddleX 仓库中服务化部署的源码实现（CLI 入口、基础服务实现 与 各产线服务定义），系统讲解 PaddleX 产线的两类服务化部署方案：开发成本低、上手快的基础服务化部署，以及基于 NVIDIA Triton Inference Server、面向高稳定性与高性能生产场景的高稳定性服务化部署。读完本文，你将掌握插件的安装、服务器的启动与命令行参数调优、客户端调用方式，以及基于 Docker 的高稳定方案的全流程部署方法。

服务化部署概述

服务化部署是实际生产环境中常见的一种部署形式：将推理功能封装为网络服务，客户端通过 HTTP 等协议发起请求，即可远程获取推理结果。相比单机脚本式推理，服务化部署天然适合多客户端并发访问、负载隔离与运维监控，是模型从"跑通"走向"上线"的关键一步。

针对不同需求，PaddleX 提供两种产线服务化部署方案：

官方建议：首先使用基础服务化部署方案进行快速验证，确认产线功能符合预期后，再根据实际需要评估是否切换至高稳定方案。

注意：PaddleX 对产线（Pipeline）而不是单个模块进行服务化部署。换言之，服务化的最小单元是完整产线（如通用图像分类、通用 OCR），而非其中某一模型。

一、基础服务化部署

基础服务化部署是 PaddleX 内置的轻量级服务方案。从源码看，该方案基于FastAPI + Uvicorn构建：CLI 的serve入口位于 paddlex/paddlex_cli.py，通过load_pipeline_config加载产线配置、create_pipeline构建产线对象，再调用 basic_serving 中的create_pipeline_app生成 FastAPI 应用，最后由 _server.py 中的uvicorn.run拉起服务进程。

1.1 安装服务化部署插件

执行如下命令安装服务化部署插件：

paddlex --install serving

该命令会安装服务化运行所需的依赖包。从 setup.py 的serving依赖分组可以看到，插件会安装fastapi、uvicorn、starlette、aiohttp、filetype、bce-python-sdk、yarl等组件，用于支撑 Web 服务框架、异步文件下载与对象存储访问等能力。在 paddlex/paddlex_cli.py 中，_install_serving_deps会通过get_serving_dep_specs()读取该依赖分组并完成安装。

1.2 运行服务器

通过 PaddleX CLI 运行服务器：

paddlex --serve --pipeline {产线名称或产线配置文件路径} [{其他命令行选项}]

以通用图像分类产线为例：

paddlex --serve --pipeline image_classification

启动成功后，可以看到类似以下展示的信息：

INFO: Started server process [63108] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

其中--pipeline既可以指定为官方产线名称（如image_classification），也可以指定为本地产线配置文件路径（YAML 文件），PaddleX 会据此构建产线并部署为服务。如需调整配置（如模型路径、batch size、部署设备等），请参考 通用图像分类产线使用教程 中的"模型应用"部分，修改产线配置文件后再启动服务。

与服务化部署相关的命令行选项如下：

以上默认值与源码定义一致：在 paddlex/paddlex_cli.py 中，--host的默认值为0.0.0.0，--port的默认值为8080；serve()函数接收device、use_hpip、hpi_config并传递给create_pipeline，可见基础服务化部署与命令行推理共用同一套产线构建逻辑。

1.3 使用高性能推理插件加速

在服务响应时间要求较严格的应用场景中，可以使用 PaddleX 高性能推理插件对模型推理及前后处理进行加速，从而降低响应时间、提升吞吐量。详细说明请参考 PaddleX 高性能推理指南。

通过指定--use_hpip即可启用：

paddlex --serve --pipeline image_classification --use_hpip

注意：使用高性能推理插件前，需要先安装对应设备类型的插件（如paddlex --install hpi-gpu），安装逻辑同样由 paddlex/paddlex_cli.py 处理，支持cpu、gpu、npu三种设备类型。

1.4 调用服务

各产线使用教程中的"开发集成/部署"部分提供了服务的 API 参考与多语言调用示例，可在 pipeline_develop_guide 找到各产线的使用教程列表。

以通用图像分类产线为例，其服务端实现位于 image_classification.py，端点定义在 schemas/image_classification.py：

• 主要操作：infer（对图像进行分类）
• HTTP 端点：POST /image-classification
• 请求体字段：
  • image（string，必填）：服务器可访问的图像文件 URL，或图像文件内容的 Base64 编码结果；
  • topk（integer | null，选填）：返回 Top-K 个类别，对应产线predict方法的topk参数。

通用响应格式：请求处理成功时，HTTP 状态码为200，响应体 JSON 包含logId（请求 UUID）、errorCode（固定为0）、errorMsg（固定为"Success"）与result（操作结果）四个属性；处理失败时，errorCode与 HTTP 状态码一致，errorMsg为错误说明。从 _app.py 的源码可以看到，服务还提供了/health健康检查端点，并对请求校验错误（422）、HTTP 异常与未捕获异常（500）做了统一的 JSON 响应封装。

图像分类result示例如下：

{ "categories": [ { "id": 5, "name": "兔子", "score": 0.93 } ], "image": "xxxxxx" }

其中categories为类别信息数组，每个元素包含id（类别 ID）、name（类别名称）、score（类别得分）；image为 JPEG 格式的分类结果图，使用 Base64 编码。

Python 调用示例：

import base64 import requests API_URL = "http://localhost:8080/image-classification" # 服务URL image_path = "./demo.jpg" output_image_path = "./out.jpg" # 对本地图像进行Base64编码 with open(image_path, "rb") as file: image_bytes = file.read() image_data = base64.b64encode(image_bytes).decode("ascii") payload = {"image": image_data} # Base64编码的文件内容或者图像URL # 调用API response = requests.post(API_URL, json=payload) # 处理接口返回数据 assert response.status_code == 200 result = response.json()["result"] with open(output_image_path, "wb") as file: file.write(base64.b64decode(result["image"])) print(f"Output image saved at {output_image_path}") print("\nCategories:") print(result["categories"])

各产线的服务端点与请求/响应字段有所不同（如目标检测的POST /object-detection、OCR 类产线的POST /ocr等），均可在对应产线教程的"开发集成/部署"一节中查到完整 API 参考与 Python、C++、Java、Go、C# 等多语言调用示例。

1.5 服务端实现原理浅析

理解底层实现有助于在生产中排查问题。基础服务的核心封装在 paddlex/inference/serving/basic_serving/_app.py：

• create_app创建一个 FastAPI 应用，并通过 lifespan 机制管理产线对象的生命周期；
• PipelineWrapper是关键的并发适配层：由于 Paddle Inference 存在线程安全问题，源码特意将所有推理任务放到同一个独立线程中执行（self._thread = Thread(target=self._worker)），请求通过queue.Queue排队提交，异步接口infer通过asyncioFuture 获取结果，从而在保证推理正确性的前提下支持并发请求；
• 每个产线对应一个独立的 FastAPI 应用模块，位于 _pipeline_apps 目录（覆盖图像分类、目标检测、OCR、时序、视频、文档理解等全部产线），通过primary_operation注册POST端点；
• 服务运行由 _server.py 中的uvicorn.run(app, host=host, port=port, log_level="info")完成，并对/health访问日志做了过滤处理。

二、高稳定性服务化部署

请注意：高稳定性服务化部署方案目前仅支持 Linux 系统。

高稳定性服务化部署基于 NVIDIA Triton Inference Server 打造，相比基础方案提供更高的稳定性，并允许用户通过调整 Triton 配置优化性能（如执行实例数量、GPU 分配等）。

2.1 下载高稳定性服务化部署 SDK

在下表中找到产线对应的 SDK 并下载（SDK 文件为.tar.gz压缩包，名称格式为paddlex_hps_{产线名}_sdk.tar.gz）：

SDK 文件托管在 PaddleX 官方的模型生态对象存储上，具体下载地址可在 docs/pipeline_deploy/serving.md 的 SDK 表格中查看对应链接。

下载解压后，SDK 目录通常包含server（服务器端配置与脚本）与client（客户端调用脚本）两个子目录。

2.2 调整配置

高稳定性服务化部署 SDK 的server/pipeline_config.yaml文件为产线配置文件，用户可以修改该文件以设置要使用的模型目录等。

此外，由于该方案基于 NVIDIA Triton Inference Server 打造，用户还可以直接修改 Triton 的配置文件：

• 在 SDK 的server/model_repo/{端点名称}目录中，可以找到一个或多个config*.pbtxt文件；
• 如果目录中存在config_{设备类型}.pbtxt文件，请修改期望使用的设备类型对应的配置文件；否则，请修改config.pbtxt。

一个常见的需求是调整执行实例数量。为此，需要修改配置文件中的instance_group配置：

• 使用count指定每一设备上放置的实例数量；
• 使用kind指定设备类型（如KIND_GPU）；
• 使用gpus指定 GPU 编号。

示例 1：在 GPU 0 上放置 4 个实例

instance_group [ { count: 4 kind: KIND_GPU gpus: [ 0 ] } ]

示例 2：在 GPU 1 上放置 2 个实例，在 GPU 2 和 3 上分别放置 1 个实例

instance_group [ { count: 2 kind: KIND_GPU gpus: [ 1 ] }, { count: 1 kind: KIND_GPU gpus: [ 2, 3 ] } ]

更多 Triton 模型配置细节（如动态批处理、模型并发策略等），可查阅 Triton Inference Server 官方模型配置文档。

2.3 运行服务器

用于部署的机器上需要安装19.03 或更高版本的 Docker Engine。

首先，根据需要拉取 Docker 镜像：

• GPU 部署镜像（机器上需要安装有支持 CUDA 11.8 的 NVIDIA 驱动）：

docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlex/hps:paddlex3.0.3-gpu

• CPU-only 镜像：

docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlex/hps:paddlex3.0.3-cpu

准备好镜像后，切换到server目录，执行如下命令运行服务器：

docker run \ -it \ -e PADDLEX_HPS_DEVICE_TYPE={部署设备类型} \ -v "$(pwd)":/app \ -w /app \ --rm \ --gpus all \ --init \ --network host \ --shm-size 8g \ {镜像名称} \ /bin/bash server.sh

各参数说明如下：

• PADDLEX_HPS_DEVICE_TYPE即部署设备类型，可取cpu或gpu；CPU-only 镜像仅支持cpu；
• 如果希望使用 CPU 部署，则不需要指定--gpus；
• 如果需要进入容器内部调试，可以将命令中的/bin/bash server.sh替换为/bin/bash，然后在容器中手动执行/bin/bash server.sh；
• 如果希望服务器在后台运行，可以将-it替换为-d，容器启动后通过docker logs -f {容器 ID}查看容器日志；
• 在命令中添加-e PADDLEX_HPS_USE_HPIP=1可以使用 PaddleX 高性能推理插件加速产线推理过程，更多信息请参考 PaddleX 高性能推理指南。

启动成功后，可观察到类似下面的 Triton 服务输出：

I1216 11:37:21.601943 35 grpc_server.cc:4117] Started GRPCInferenceService at 0.0.0.0:8001 I1216 11:37:21.602333 35 http_server.cc:2815] Started HTTPService at 0.0.0.0:8000 I1216 11:37:21.643494 35 http_server.cc:167] Started Metrics Service at 0.0.0.0:8002

可以看到 Triton 同时启动了三个服务端口：gRPC 服务（8001）、HTTP 服务（8000）以及指标监控服务（8002）。

2.4 调用服务

目前，高稳定性服务化部署仅支持使用 Python 客户端调用服务，支持的 Python 版本为3.8 至 3.12。

切换到 SDK 的client目录，执行如下命令安装依赖：

# 建议在虚拟环境中安装 python -m pip install -r requirements.txt python -m pip install paddlex_hps_client-*.whl

client目录下的client.py脚本包含服务的调用示例，并提供命令行接口，可以直接基于它进行二次开发或快速验证。

需要特别说明的是：使用高稳定性服务化部署方案部署的服务，提供与基础服务化部署方案相匹配的主要操作。对于每个主要操作，端点名称以及请求、响应的数据字段都与基础服务化部署方案保持一致。因此，你可以复用基础服务化部署场景下的 API 约定来调用高稳定服务，各产线教程中的"开发集成/部署"部分同样适用，可前往 pipeline_develop_guide 查看各产线的使用教程。

三、方案选型建议

实践路径建议：先在本地用基础服务化部署快速跑通产线、验证 API 与业务对接，确认无误后，若对稳定性或吞吐有更高要求，再切换到高稳定性方案——两者在 API 语义上保持对齐，切换成本主要集中在服务端环境搭建上。

相关资源

• 服务化部署指南原文：docs/pipeline_deploy/serving.md
• CLI 服务入口与参数解析：paddlex/paddlex_cli.py
• 基础服务应用与端点注册：paddlex/inference/serving/basic_serving/_app.py
• 各产线 FastAPI 端点实现：paddlex/inference/serving/basic_serving/_pipeline_apps/
• 请求/响应 Schema 定义：paddlex/inference/serving/schemas/
• 服务化依赖声明：setup.py
• 高性能推理指南：docs/pipeline_deploy/high_performance_inference.md
• 各产线"开发集成/部署"API 参考示例：docs/pipeline_usage/tutorials/cv_pipelines/image_classification.md
• 产线使用教程索引：docs/pipeline_usage/pipeline_develop_guide.md

• 人工智能
• 大模型
• 低代码
• 计算机视觉
• 深度学习
• NLP
• 模型推理服务
• RAG