--- comments: true --- # 开放词汇检测产线使用教程 ## 1. 开放词汇检测产线介绍 开放词汇目标检测是当前一种先进的目标检测技术，旨在突破传统目标检测的局限性。传统方法仅能识别预定义类别的物体，而开放词汇目标检测允许模型识别未在训练中出现的物体。通过结合自然语言处理技术，利用文本描述来定义新的类别，模型能够识别和定位这些新物体。这使得目标检测更具灵活性和泛化能力，具有重要的应用前景。本产线同时提供了灵活的服务化部署方式，支持在多种硬件上使用多种编程语言调用。本产线目前不支持对模型的二次开发，计划在后续支持。 通用开放词汇检测产线中包含了开放词汇检测模块，您可以根据下方的基准测试数据选择使用的模型。 如果您更注重模型的精度，请选择精度较高的模型；如果您更在意模型的推理速度，请选择推理速度较快的模型；如果您关注模型的存储大小，请选择存储体积较小的模型。

通用图像开放词汇检测模块（可选）：

模型模型下载链接 mAP(0.5:0.95) mAP(0.5) GPU推理耗时（ms） CPU推理耗时 (ms) 模型存储大小（M） 介绍
GroundingDINO-T推理模型 49.4 64.4 253.72 1807.4 658.3 基于O365,GoldG,Cap4M三个数据集训练的开放词汇目标目标检测模型。文本编码器采用Bert，视觉模型部份整体采用DINO，额外设计了一些跨模态融合模块，在开放词汇目标检测领域取得了较好的效果。
测试环境说明:
模式 GPU配置 CPU配置 加速技术组合
常规模式 FP32精度 / 无TRT加速 FP32精度 / 8线程 PaddleInference
高性能模式 选择先验精度类型和加速策略的最优组合 FP32精度 / 8线程 选择先验最优后端（Paddle/OpenVINO/TRT等）
## 2. 快速开始 ### 2.1 本地体验 > ❗ 在本地使用通用开放词汇检测产线前，请确保您已经按照[PaddleX本地安装教程](../../../installation/installation.md)完成了PaddleX的wheel包安装。 #### 2.1.1 命令行方式体验 * 一行命令即可快速体验开放词汇检测产线效果，使用 [测试文件](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/open_vocabulary_detection.jpg)，并将 `--input` 替换为本地路径，进行预测 ```bash paddlex --pipeline open_vocabulary_detection \ --input open_vocabulary_detection.jpg \ --prompt "bus . walking man . rearview mirror ." \ --thresholds "{'text_threshold': 0.25, 'box_threshold': 0.3}" \ --save_path ./output \ --device gpu:0 ``` 相关的参数说明可以参考[2.1.2 Python脚本方式集成](#212-python脚本方式集成)中的参数说明。 运行后，会将结果打印到终端上，结果如下： ```bash {'res': {'input_path': 'open_vocabulary_detection.jpg', 'page_index': None, 'boxes': [{'coordinate': [112.10542297363281, 117.93667602539062, 514.35693359375, 382.10150146484375], 'label': 'bus', 'score': 0.9348853230476379}, {'coordinate': [264.1828918457031, 162.6674346923828, 286.8844909667969, 201.86187744140625], 'label': 'rearview mirror', 'score': 0.6022508144378662}, {'coordinate': [606.1133422851562, 254.4973907470703, 622.56982421875, 293.7867126464844], 'label': 'walking man', 'score': 0.4384709894657135}, {'coordinate': [591.8192138671875, 260.2451171875, 607.3953247070312, 294.2210388183594], 'label': 'man', 'score': 0.3573091924190521}]}} ``` 运行结果参数说明可以参考[2.1.2 Python脚本方式集成](#212-python脚本方式集成)中的结果解释。 可视化结果保存在`save_path`下，其中开放词汇检测的可视化结果如下： #### 2.1.2 Python脚本方式集成 * 上述命令行是为了快速体验查看效果，一般来说，在项目中，往往需要通过代码集成，您可以通过几行代码即可完成产线的快速推理，推理代码如下： ```python from paddlex import create_pipeline pipeline = create_pipeline(pipeline="open_vocabulary_detection") output = pipeline.predict(input="open_vocabulary_detection.jpg", prompt="bus . walking man . rearview mirror .") for res in output: res.print() res.save_to_img(save_path="./output/") res.save_to_json(save_path="./output/") ``` 在上述 Python 脚本中，执行了如下几个步骤： （1）通过 `create_pipeline()` 实例化 开放词汇检测 产线对象，具体参数说明如下：
参数 参数说明 参数类型 默认值
pipeline 产线名称或是产线配置文件路径。如为产线名称，则必须为 PaddleX 所支持的产线。 str None
config 产线具体的配置信息（如果和pipeline同时设置，优先级高于pipeline，且要求产线名和pipeline一致）。 dict[str, Any] None
device 产线推理设备。支持指定GPU具体卡号，如“gpu:0”，其他硬件具体卡号，如“npu:0”，CPU如“cpu”。 str None
use_hpip 是否启用高性能推理，仅当该产线支持高性能推理时可用。 bool False
（2）调用 开放词汇检测 产线对象的 `predict()` 方法进行推理预测。该方法将返回一个 `generator`。以下是 `predict()` 方法的参数及其说明：
参数 参数说明 参数类型 可选项 默认值
input 待预测数据，支持多种输入类型，必填 Python Var|str|list
  • Python Var：如 numpy.ndarray 表示的图像数据
  • str：如图像文件或者PDF文件的本地路径：/root/data/img.jpg；如URL链接，如图像文件或PDF文件的网络URL：示例；如本地目录，该目录下需包含待预测图像，如本地路径：/root/data/(当前不支持目录中包含PDF文件的预测，PDF文件需要指定到具体文件路径)
  • List：列表元素需为上述类型数据，如[numpy.ndarray, numpy.ndarray]，[\"/root/data/img1.jpg\", \"/root/data/img2.jpg\"]，[\"/root/data1\", \"/root/data2\"]
 None
device 产线推理设备 str|None
  • CPU：如 cpu 表示使用 CPU 进行推理；
  • GPU：如 gpu:0 表示使用第 1 块 GPU 进行推理；
  • NPU：如 npu:0 表示使用第 1 块 NPU 进行推理；
  • XPU：如 xpu:0 表示使用第 1 块 XPU 进行推理；
  • MLU：如 mlu:0 表示使用第 1 块 MLU 进行推理；
  • DCU：如 dcu:0 表示使用第 1 块 DCU 进行推理；
  • None：如果设置为 None, 将默认使用产线初始化的该参数值，初始化时，会优先使用本地的 GPU 0号设备，如果没有，则使用 CPU 设备；
 None
thresholds 模型推理时使用的阈值 dict[str, float]
  • dict[str, float]：key为str, 代表阈值名, value为0到1之间的浮点数，代表阈值大小。如GroundingDINO对应的设置为{"text_threshold": 0.25, "box_threshold": 0.3}, 表示GroundingDINO的文本阈值设置为0.25，物体检测框阈值设置为0.3
 无
prompt 模型推理时使用的提示词 str
  • str：需要结合具体的模型设定。如GroundingDINO对应的提示词为"{类别1} . {类别2} . {类别3} ."
无
（3）对预测结果进行处理，每个样本的预测结果均为对应的Result对象，且支持打印、保存为图片、保存为`json`文件的操作:
方法 方法说明 参数 参数类型 参数说明 默认值
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()` 方法会将结果打印到终端，打印到终端的内容解释如下： - `input_path`: `(str)` 待预测图像的输入路径 - `page_index`: `(Union[int, None])` 如果输入是PDF文件，则表示当前是PDF的第几页，否则为 `None` - `boxes`: `(list)` 检测框信息，每个元素为一个字典，包含以下字段 - `label`: `(str)` 类别名称 - `score`: `(float)` 置信度 - `coordinates`: `(list)` 检测框坐标，格式为`[xmin, ymin, xmax, ymax]` - 调用`save_to_json()` 方法会将上述内容保存到指定的`save_path`中，如果指定为目录，则保存的路径为`save_path/{your_img_basename}_res.json`，如果指定为文件，则直接保存到该文件中。由于json文件不支持保存numpy数组，因此会将其中的`numpy.array`类型转换为列表形式。 - 调用`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` 对象：一个用于显示 开放词汇检测 的预测结果。 此外，您可以获取 开放词汇检测 产线配置文件，并加载配置文件进行预测。可执行如下命令将结果保存在 `my_path` 中： ``` paddlex --get_pipeline_config open_vocabulary_detection --save_path ./my_path ``` 若您获取了配置文件，即可对开放词汇检测产线各项配置进行自定义，只需要修改 `create_pipeline` 方法中的 `pipeline` 参数值为产线配置文件路径即可。示例如下： ```python from paddlex import create_pipeline pipeline = create_pipeline(pipeline="./my_path/open_vocabulary_detection.yaml") output = pipeline.predict( input="./open_vocabulary_detection.jpg", thresholds={"text_threshold": 0.25, "box_threshold": 0.3}, prompt="cat . dog . bird ." ) for res in output: res.print() res.save_to_img("./output/") res.save_to_json("./output/") ``` 注： 配置文件中的参数为产线初始化参数，如果希望更改通用开放词汇检测产线初始化参数，可以直接修改配置文件中的参数，并加载配置文件进行预测。同时，CLI 预测也支持传入配置文件，`--pipeline` 指定配置文件的路径即可。 ## 3. 开发集成/部署 如果产线可以达到您对产线推理速度和精度的要求，您可以直接进行开发集成/部署。 若您需要将产线直接应用在您的Python项目中，可以参考 [2.1.2 Python脚本方式](#212-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 /open-vocabulary-detection

名称 类型 含义 是否必填
image string 服务器可访问的图像文件的URL或图像文件内容的Base64编码结果。 是
prompt string 预测使用的文本提示词。 是
thresholds object | null 模型预测使用的阈值。 否
名称 类型 含义
detectedObjects array 目标的位置、类别等信息。
image string 目标检测结果图。图像为JPEG格式，使用Base64编码。

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

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

result示例如下：

{
"detectedObjects": [
{
"bbox": [
404.4967956542969,
90.15770721435547,
506.2465515136719,
285.4187316894531
],
"categoryName": "bird",
"score": 0.7418514490127563
},
{
"bbox": [
155.33145141601562,
81.10954284667969,
199.71136474609375,
167.4235382080078
],
"categoryName": "dog",
"score": 0.7328268885612488
}
],
"image": "xxxxxx"
}
多语言调用服务示例
Python 
import base64
import requests

API_URL = "http://localhost:8080/open-vocabulary-detection" # 服务URL
image_path = "./open_vocabulary_detection.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, "prompt": "walking man . bus ."}  # Base64编码的文件内容或者图像URL

# 调用API
response = requests.post(API_URL, json=payload)

# 处理接口返回数据
assert response.status_code == 200, f"{response.status_code}"
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("\nDetected objects:")
print(result["detectedObjects"])

📱 端侧部署：端侧部署是一种将计算和数据处理功能放在用户设备本身上的方式，设备可以直接处理数据，而不需要依赖远程的服务器。PaddleX 支持将模型部署在 Android 等端侧设备上，详细的端侧部署流程请参考[PaddleX端侧部署指南](../../../pipeline_deploy/edge_deploy.md)。 您可以根据需要选择合适的方式部署模型产线，进而进行后续的 AI 应用集成。 ## 4. 二次开发 当前产线暂时不支持微调训练，仅支持推理集成。关于该产线的微调训练，计划在未来支持。 ## 5. 多硬件支持 当前产线暂时仅支持GPU和CPU推理。关于该产线对于更多硬件的适配，计划在未来支持。