--- comments: true --- # 通用图像识别产线使用教程 ## 1. 通用图像识别产线介绍 通用图像识别产线旨在解决开放域目标定位及识别问题，目前 PaddleX 的通用图像识别产线支持 PP-ShiTuV2。 PP-ShiTuV2 是一个实用的通用图像识别系统，主要由主体检测、特征学习和向量检索三个模块组成。该系统从骨干网络选择和调整、损失函数的选择、数据增强、学习率变换策略、正则化参数选择、预训练模型使用以及模型裁剪量化多个方面，融合改进多种策略，对各个模块进行优化，最终在多个实际应用场景上的检索性能均有较好效果。 通用图像识别产线中包含了主体检测模块和图像特征模块，有若干模型可供选择，您可以根据下边的 benchmark 数据来选择使用的模型。如您更考虑模型精度，请选择精度较高的模型，如您更考虑模型推理速度，请选择推理速度较快的模型，如您更考虑模型存储大小，请选择存储大小较小的模型。 主体检测模块：
模型 mAP(0.5:0.95) mAP(0.5) GPU推理耗时（ms）
[常规模式 / 高性能模式]		 CPU推理耗时（ms）
[常规模式 / 高性能模式]		 模型存储大小（MB） 介绍
PP-ShiTuV2_det 41.5 62.0 11.81 / 4.53 43.03 / 25.31 27.54 基于PicoDet_LCNet_x2_5的主体检测模型，模型可能会同时检测出多个常见主体。
图像特征模块：
模型 recall@1 (%) GPU推理耗时（ms）
[常规模式 / 高性能模式]		 CPU推理耗时（ms）
[常规模式 / 高性能模式]		 模型存储大小（MB） 介绍
PP-ShiTuV2_rec 84.2 3.91 / 1.06 6.82 / 2.89 16.3 PP-ShiTuV2是一个通用图像特征系统，由主体检测、特征提取、向量检索三个模块构成，这些模型是其中的特征提取模块的模型之一，可以根据系统的情况选择不同的模型。
PP-ShiTuV2_rec_CLIP_vit_base 88.69 12.57 / 11.62 67.09 / 67.09 306.6
PP-ShiTuV2_rec_CLIP_vit_large 91.03 49.85 / 49.85 229.14 / 229.14 1050
测试环境说明:
模式 GPU配置 CPU配置 加速技术组合
常规模式 FP32精度 / 无TRT加速 FP32精度 / 8线程 PaddleInference
高性能模式 选择先验精度类型和加速策略的最优组合 FP32精度 / 8线程 选择先验最优后端（Paddle/OpenVINO/TRT等）
## 2. 快速开始 PaddleX 所提供的预训练的模型产线均可以快速体验效果，你可以在本地使用 Python 体验通用图像识别产线的效果。 ### 2.1 在线体验 暂不支持在线体验。 ### 2.2 本地体验 > ❗ 在本地使用通用图像识别产线前，请确保您已经按照[PaddleX安装教程](../../../installation/installation.md)完成了PaddleX的wheel包安装。如果您希望选择性安装依赖，请参考安装教程中的相关说明。该产线对应的依赖分组为 `cv`。 #### 2.2.1 命令行方式体验 该产线暂不支持命令行体验。 #### 2.2.2 Python脚本方式集成 * 在该产线的运行示例中需要预先构建索引库，您可以下载官方提供的饮料识别测试数据集[drink_dataset_v2.0](https://paddle-model-ecology.bj.bcebos.com/paddlex/data/drink_dataset_v2.0.tar) 构建索引库。若您希望用私有数据集，可以参考[2.3节 构建索引库的数据组织方式](#23-构建索引库的数据组织方式)。之后通过几行代码即可完成建立索引库和通用图像识别产线的快速推理。 ```python from paddlex import create_pipeline pipeline = create_pipeline(pipeline="PP-ShiTuV2") index_data = pipeline.build_index(gallery_imgs="drink_dataset_v2.0/", gallery_label="drink_dataset_v2.0/gallery.txt") index_data.save("drink_index") output = pipeline.predict("./drink_dataset_v2.0/test_images/001.jpeg", index=index_data) for res in output: res.print() res.save_to_img("./output/") res.save_to_json("./output/") ``` 在上述 Python 脚本中，执行了如下几个步骤： （1）调用 `create_pipeline` 实例化通用图像识别产线对象。具体参数说明如下：
参数 参数说明 参数类型 默认值
pipeline 产线名称或是产线配置文件路径。如为产线名称，则必须为 PaddleX 所支持的产线。 str 无
config 产线具体的配置信息（如果和pipeline同时设置，优先级高于pipeline，且要求产线名和pipeline一致）。 dict[str, Any] None
device 产线推理设备。支持指定GPU具体卡号，如“gpu:0”，其他硬件具体卡号，如“npu:0”，CPU如“cpu”。 str gpu:0
use_hpip 是否启用高性能推理插件。如果为 None，则使用配置文件或 config 中的配置。 bool | None 无 None
hpi_config 高性能推理配置 dict | None 无 None
（2）调用通用图像识别产线对象的 `build_index` 方法，构建索引库。具体参数为说明如下：
参数 参数说明 参数类型 可选项 默认值
gallery_imgs 要添加的底库图片，必需参数 str|list 无
gallery_label 底库图片的标注信息，必需参数 str|list 无
metric_type 特征度量方式，可选参数 str
  • "IP"：内积（Inner Product）
  • "L2"：欧几里得距离（Euclidean Distance）
 "IP"
index_type 索引类型，可选参数 str
  • "HNSW32"：检索速度较快且精度较高，但不支持 remove_index() 操作
  • "IVF"：检索速度较快但精度相对较低，支持 append_index() 和 remove_index() 操作
  • "Flat"：检索速度较低精度较高，支持 append_index() 和 remove_index() 操作
 "HNSW32"
索引库对象 `index` 支持 `save` 方法，用于将索引库保存到磁盘：
参数 参数说明 参数类型 默认值
save_path 索引库文件的保存目录，如drink_index。 str 无
（3）调用通用图像识别产线对象的 `predict` 方法进行推理预测：`predict` 方法参数为 `input`，用于输入待预测数据，支持多种输入方式，具体示例如下：
参数 参数说明 参数类型 可选项 默认值
input 待预测数据，支持多种输入类型，必需参数 Python Var|str|list
  • Python Var：如 numpy.ndarray 表示的图像数据
  • str：如图像文件的本地路径：/root/data/img.jpg；如URL链接，如图像文件的网络URL：示例；如本地目录，该目录下需包含待预测图像，如本地路径：/root/data/
  • List：列表元素需为上述类型数据，如[numpy.ndarray, numpy.ndarray]，[\"/root/data/img1.jpg\", \"/root/data/img2.jpg\"]，[\"/root/data1\", \"/root/data2\"]
 无
index 产线推理预测所用的特征库，可选参数。如不传入该参数，则默认使用产线配置文件中指定的索引库。 str|paddlex.inference.components.retrieval.faiss.IndexData|None
  • str类型表示的目录（该目录下需要包含特征库文件，包括vector.index和index_info.yaml）
  • build_index方法创建的IndexData对象
 None
（4）对预测结果进行处理：每个样本的预测结果均为对应的Result对象，且支持打印，或保存为文件，支持保存的类型与具体产线相关，如：
方法 方法说明 参数 参数类型 参数说明 默认值
print() 打印结果到终端 format_json bool 是否对输出内容进行使用 JSON 缩进格式化 True
indent int 指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效 4
ensure_ascii bool 控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效 False
save_to_json() 将结果保存为json格式的文件 save_path str 保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致 无
indent int 指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效 4
ensure_ascii bool 控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效 False
save_to_img() 将结果保存为图像格式的文件 save_path str 保存的文件路径，支持目录或文件路径 无
- 调用 `print()` 方法会将如下结果打印到终端： ```bash {'res': {'input_path': './drink_dataset_v2.0/test_images/001.jpeg', 'boxes': [{'labels': ['红牛-强化型', '红牛-强化型', '红牛-强化型', '红牛-强化型', '红牛-强化型'], 'rec_scores': [0.720183789730072, 0.7044230699539185, 0.6812724471092224, 0.6583285927772522, 0.6578206419944763], 'det_score': 0.6135568618774414, 'coordinate': [343.8184, 98.96374, 528.0366, 593.3813]}]}} ``` - 输出结果参数含义如下： - `input_path`：表示输入图像的路径 - `boxes`：检测到的物体信息，一个字典列表，每个字典包含以下信息： - `labels`：识别标签列表，按照分数从高到低排序 - `rec_scores`：识别分数列表，其中元素与`labels`一一对应 - `det_score`：检测得分 - `coordinate`：目标框坐标，格式为[xmin, ymin, xmax, ymax] - 调用`save_to_json()` 方法会将上述内容保存到指定的`save_path`中，如果指定为目录，则保存的路径为`save_path/{your_img_basename}.json`，如果指定为文件，则直接保存到该文件中。 - 调用`save_to_img()` 方法会将可视化结果保存到指定的`save_path`中，如果指定为目录，则保存的路径为`save_path/{your_img_basename}_res.{your_img_extension}`，如果指定为文件，则直接保存到该文件中。(产线通常包含较多结果图片，不建议直接指定为具体的文件路径，否则多张图会被覆盖，仅保留最后一张图)，上述示例中，可视化结果如下所示： * 此外，也支持通过属性获取带结果的可视化图像和预测结果，具体如下：
属性 属性说明
json 获取预测的 json 格式的结果
img 获取格式为 dict 的可视化图像
- `json` 属性获取的预测结果为dict类型的数据，相关内容与调用 `save_to_json()` 方法保存的内容一致。 - `img` 属性返回的预测结果是一个字典类型的数据。键为 `res` ，对应的值是一个用于可视化通用图像识别结果的 `Image.Image` 对象。 上述Python脚本集成方式默认使用 PaddleX 官方配置文件中的参数设置，若您需要自定义配置文件，可先执行如下命令获取官方配置文件，并保存在 `my_path` 中： ```bash paddlex --get_pipeline_config PP-ShiTuV2 --save_path ./my_path ``` 若您获取了配置文件，即可对通用图像识别产线各项配置进行自定义。只需要修改 `create_pipeline` 方法中的 `pipeline` 参数值为自定义产线配置文件路径即可。 例如，若您的自定义配置文件保存在 `./my_path/PP-ShiTuV2.yaml` ，则只需执行： ```python from paddlex import create_pipeline pipeline = create_pipeline(pipeline="./my_path/PP-ShiTuV2.yaml") output = pipeline.predict("./drink_dataset_v2.0/test_images/001.jpeg", index="drink_index") for res in output: res.print() res.save_to_json("./output/") res.save_to_img("./output/") ``` 注： 配置文件中的参数为产线初始化参数，如果希望更改通用图像识别产线初始化参数，可以直接修改配置文件中的参数，并加载配置文件进行预测。 #### 2.2.3 索引库的添加和删除操作 若您希望将更多的图像添加到索引库中，则可以调用 `append_index` 方法；删除图像特征，则可以调用 `remove_index` 方法。 ```python from paddlex import create_pipeline pipeline = create_pipeline("PP-ShiTuV2") index_data = pipeline.build_index(gallery_imgs="drink_dataset_v2.0/", gallery_label="drink_dataset_v2.0/gallery.txt", index_type="IVF", metric_type="IP") index_data = pipeline.append_index(gallery_imgs="drink_dataset_v2.0/", gallery_label="drink_dataset_v2.0/gallery.txt", index=index_data) index_data = pipeline.remove_index(remove_ids="drink_dataset_v2.0/remove_ids.txt", index=index_data) index_data.save("drink_index") ``` 上述方法参数说明如下：
参数 参数说明 参数类型 可选项 默认值
gallery_imgs 要添加的底库图片，必需参数 str|list 无
gallery_label 底库图片的标注信息，必需参数 str|list 无
metric_type 特征度量方式，可选参数 str
  • "IP"：内积（Inner Product）
  • "L2"：欧几里得距离（Euclidean Distance）
 "IP"
index_type 索引类型，可选参数 str
  • "HNSW32"：检索速度较快且精度较高，但不支持 remove_index() 操作
  • "IVF"：检索速度较快但精度相对较低，支持 append_index() 和 remove_index() 操作
  • "Flat"：检索速度较低精度较高，支持 append_index() 和 remove_index() 操作
 "HNSW32"
remove_ids 待删除的索引序号， str|list
  • str：表示的txt文件的路径，内容为待删除的索引id，每行一个“id”；
  • List[int]：表示的待删除的索引序号。仅在 remove_index 中有效。
 无
index 产线推理预测所用的特征库 str|paddlex.inference.components.retrieval.faiss.IndexData
  • str类型表示的目录（该目录下需要包含特征库文件，包括vector.index和index_info.yaml）
  • build_index方法创建的IndexData对象
 无
注意：HNSW32在windows平台存在兼容性问题，可能导致索引库无法构建、加载。 ### 2.3 构建索引库的数据组织方式 PaddleX 的通用图像识别产线示例需要使用预先构建好的索引库进行特征检索。如果您希望用私有数据构建索引库，则需要按照如下方式组织数据： ```bash data_root # 数据集根目录，目录名称可以改变 ├── images # 图像的保存目录，目录名称可以改变 │ │ ... └── gallery.txt # 索引库数据集标注文件，文件名称可以改变。每行给出待检索图像路径和图像标签，使用空格分隔，内容举例： “0/0.jpg 脉动” ``` ## 3. 开发集成/部署 如果通用图像识别产线可以达到您对产线推理速度和精度的要求，您可以直接进行开发集成/部署。 若您需要将通用图像识别产线直接应用在您的Python项目中，可以参考 [2.2.2 Python脚本方式](#222-python脚本方式集成)中的示例代码。 此外，PaddleX 也提供了其他三种部署方式，详细说明如下： 🚀 高性能推理：在实际生产环境中，许多应用对部署策略的性能指标（尤其是响应速度）有着较严苛的标准，以确保系统的高效运行与用户体验的流畅性。为此，PaddleX 提供高性能推理插件，旨在对模型推理及前后处理进行深度性能优化，实现端到端流程的显著提速，详细的高性能推理流程请参考[PaddleX高性能推理指南](../../../pipeline_deploy/high_performance_inference.md)。 ☁️ 服务化部署：服务化部署是实际生产环境中常见的一种部署形式。通过将推理功能封装为服务，客户端可以通过网络请求来访问这些服务，以获取推理结果。PaddleX 支持多种产线服务化部署方案，详细的产线服务化部署流程请参考[PaddleX服务化部署指南](../../../pipeline_deploy/serving.md)。 以下是基础服务化部署的API参考与多语言服务调用示例：
API参考

对于服务提供的主要操作：

名称 类型 含义
logId string 请求的UUID。
errorCode integer 错误码。固定为0。
errorMsg string 错误说明。固定为"Success"。
result object 操作结果。
名称 类型 含义
logId string 请求的UUID。
errorCode integer 错误码。与响应状态码相同。
errorMsg string 错误说明。

服务提供的主要操作如下：

构建特征向量索引。

POST /shitu-index-build

名称 类型 含义 是否必填
imageLabelPairs array 用于构建索引的图像-标签对。 是

imageLabelPairs中的每个元素为一个object，具有如下属性：

名称 类型 含义
image string 服务器可访问的图像文件的URL或图像文件内容的Base64编码结果。
label string 标签。
名称 类型 含义
indexKey string 索引对应的键，用于标识建立的索引。可用作其他操作的输入。
imageCount integer 索引的图像数量。

将图像（对应的特征向量）加入索引。

POST /shitu-index-add

名称 类型 含义 是否必填
imageLabelPairs array 用于构建索引的图像-标签对。 是
indexKey string 索引对应的键。由buildIndex操作提供。 是

imageLabelPairs中的每个元素为一个object，具有如下属性：

名称 类型 含义
image string 服务器可访问的图像文件的URL或图像文件内容的Base64编码结果。
label string 标签。
名称 类型 含义
imageCount integer 索引的图像数量。

从索引中移除图像（对应的特征向量）。

POST /shitu-index-remove

名称 类型 含义 是否必填
ids array 需要从索引中移除的向量的ID。 是
indexKey string 索引对应的键。由buildIndex操作提供。 是
名称 类型 含义
imageCount integer 索引的图像数量。

进行图像识别。

POST /shitu-infer

名称 类型 含义 是否必填
image string 服务器可访问的图像文件的URL或图像文件内容的Base64编码结果。 是
indexKey string 索引对应的键。由buildIndex操作提供。 否
detThreshold number | null 请参阅产线对象中 predict 方法的 det_threshold 参数相关说明。 否
recThreshold number | null 请参阅产线对象中 predict 方法的 rec_threshold 参数相关说明。 否
hammingRadius number | null 请参阅产线对象中 predict 方法的 hamming_radius 参数相关说明。 否
topk integer | null 请参阅产线对象中 predict 方法的 topk 参数相关说明。 否
visualize boolean | null 是否返回可视化结果图以及处理过程中的中间图像等。
  • 传入 true：返回图像。
  • 传入 false：不返回图像。
  • 若请求体中未提供该参数或传入 null：遵循产线配置文件Serving.visualize 的设置。

例如，在产线配置文件中添加如下字段：
Serving:
  visualize: False
将默认不返回图像，通过请求体中的visualize参数可以覆盖默认行为。如果请求体和配置文件中均未设置（或请求体传入null、配置文件中未设置），则默认返回图像。 		否
名称 类型 含义
detectedObjects array 检测到的目标的信息。
image string | null 识别结果图。图像为JPEG格式，使用Base64编码。

detectedObjects中的每个元素为一个object，具有如下属性：

名称 类型 含义
bbox array 目标位置。数组中元素依次为边界框左上角x坐标、左上角y坐标、右下角x坐标以及右下角y坐标。
recResults array 识别结果。
score number 检测得分。

recResults中的每个元素为一个object，具有如下属性：

名称 类型 含义
label string 标签。
score number 识别得分。
多语言调用服务示例
Python 
import base64
import pprint
import sys

import requests

API_BASE_URL = "http://127.0.0.1:8080"

base_image_label_pairs = [
    {"image": "./demo0.jpg", "label": "兔子"},
    {"image": "./demo1.jpg", "label": "兔子"},
    {"image": "./demo2.jpg", "label": "小狗"},
]
image_label_pairs_to_add = [
    {"image": "./demo3.jpg", "label": "小狗"},
]
ids_to_remove = [1]
infer_image_path = "./demo4.jpg"
output_image_path = "./out.jpg"

for pair in base_image_label_pairs:
    with open(pair["image"], "rb") as file:
        image_bytes = file.read()
        image_data = base64.b64encode(image_bytes).decode("ascii")
    pair["image"] = image_data

payload = {"imageLabelPairs": base_image_label_pairs}
resp_index_build = requests.post(f"{API_BASE_URL}/shitu-index-build", json=payload)
if resp_index_build.status_code != 200:
    print(f"Request to shitu-index-build failed with status code {resp_index_build}.")
    pprint.pp(resp_index_build.json())
    sys.exit(1)
result_index_build = resp_index_build.json()["result"]
print(f"Number of images indexed: {result_index_build['imageCount']}")

for pair in image_label_pairs_to_add:
    with open(pair["image"], "rb") as file:
        image_bytes = file.read()
        image_data = base64.b64encode(image_bytes).decode("ascii")
    pair["image"] = image_data

payload = {"imageLabelPairs": image_label_pairs_to_add, "indexKey": result_index_build["indexKey"]}
resp_index_add = requests.post(f"{API_BASE_URL}/shitu-index-add", json=payload)
if resp_index_add.status_code != 200:
    print(f"Request to shitu-index-add failed with status code {resp_index_add}.")
    pprint.pp(resp_index_add.json())
    sys.exit(1)
result_index_add = resp_index_add.json()["result"]
print(f"Number of images indexed: {result_index_add['imageCount']}")

payload = {"ids": ids_to_remove, "indexKey": result_index_build["indexKey"]}
resp_index_remove = requests.post(f"{API_BASE_URL}/shitu-index-remove", json=payload)
if resp_index_remove.status_code != 200:
    print(f"Request to shitu-index-remove failed with status code {resp_index_remove}.")
    pprint.pp(resp_index_remove.json())
    sys.exit(1)
result_index_remove = resp_index_remove.json()["result"]
print(f"Number of images indexed: {result_index_remove['imageCount']}")

with open(infer_image_path, "rb") as file:
    image_bytes = file.read()
    image_data = base64.b64encode(image_bytes).decode("ascii")

payload = {"image": image_data, "indexKey": result_index_build["indexKey"]}
resp_infer = requests.post(f"{API_BASE_URL}/shitu-infer", json=payload)
if resp_infer.status_code != 200:
    print(f"Request to shitu-infer failed with status code {resp_infer}.")
    pprint.pp(resp_infer.json())
    sys.exit(1)
result_infer = resp_infer.json()["result"]

with open(output_image_path, "wb") as file:
    file.write(base64.b64decode(result_infer["image"]))
print(f"Output image saved at {output_image_path}")
print("\nDetected objects:")
pprint.pp(result_infer["detectedObjects"])

📱 端侧部署：端侧部署是一种将计算和数据处理功能放在用户设备本身上的方式，设备可以直接处理数据，而不需要依赖远程的服务器。PaddleX 支持将模型部署在 Android 等端侧设备上，详细的端侧部署流程请参考[PaddleX端侧部署指南](../../../pipeline_deploy/on_device_deployment.md)。 您可以根据需要选择合适的方式部署模型产线，进而进行后续的 AI 应用集成。 ## 4. 二次开发 如果通用图像识别产线提供的默认模型权重在您的场景中，精度或速度不满意，您可以尝试利用您自己拥有的特定领域或应用场景的数据对现有模型进行进一步的微调，以提升通用该产线的在您的场景中的识别效果。 ### 4.1 模型微调 由于通用图像识别产线包含两个模块（主体检测模块和图像特征模块），模型产线的效果不及预期可能来自于其中任何一个模块。 您可以对识别效果差的图片进行分析，如果在分析过程中发现有较多的主体目标未被检测出来，那么可能是主体检测模型存在不足，您需要参考[主体检测模块开发教程](https://paddlepaddle.github.io/PaddleX/latest/module_usage/tutorials/cv_modules/mainbody_detection.html)中的二次开发章节，使用您的私有数据集对主体检测模型进行微调；如果在已检测到的主体出现匹配错误，这表明图像特征模型需要进一步改进，您需要参考[图像特征模块开发教程](https://paddlepaddle.github.io/PaddleX/latest/module_usage/tutorials/cv_modules/image_feature.html)中的二次开发章节,对图像特征模型进行微调。 ### 4.2 模型应用 当您使用私有数据集完成微调训练后，可获得本地模型权重文件。 若您需要使用微调后的模型权重，只需对产线配置文件做修改，将微调后模型权重的本地路径替换至产线配置文件中的对应位置即可： ```yaml ... SubModules: Detection: module_name: text_detection model_name: PP-ShiTuV2_det model_dir: null #可修改为微调后主体检测模型的本地路径 batch_size: 1 Recognition: module_name: text_recognition model_name: PP-ShiTuV2_rec model_dir: null #可修改为微调后图像特征模型的本地路径 batch_size: 1 ``` 随后， 参考[2.2 本地体验](#22-本地体验)中的命令行方式或Python脚本方式，加载修改后的产线配置文件即可。 ## 5. 多硬件支持 PaddleX 支持英伟达 GPU、昆仑芯 XPU、昇腾 NPU 和寒武纪 MLU 等多种主流硬件设备，仅需修改 `--device`参数即可完成不同硬件之间的无缝切换。 例如，使用Python运行通用图像识别产线时，将运行设备从英伟达 GPU 更改为昇腾 NPU，仅需将脚本中的 `device` 修改为 npu 即可： ```python from paddlex import create_pipeline pipeline = create_pipeline( pipeline="PP-ShiTuV2", device="npu:0" # gpu:0 --> npu:0 ) ``` 若您想在更多种类的硬件上使用通用图像识别产线，请参考[PaddleX多硬件使用指南](../../../other_devices_support/multi_devices_use_guide.md)。