# Pangu-CV-视觉交互检测-V3 #### 功能介绍 盘古视觉交互检测大模型，支持通过文本或者视觉提示来找出目标图像中所有感兴趣的目标，确定它们的位置和类别。 视觉交互检测推理分为"开集模型推理"和"闭集模型推理"，其中： - **开集模型推理：** 该模式下用户可以给出想要检测的目标少量的视觉提示和文本提示（单一视觉提示或文本提示亦可），即可在待检测图像上检测用户指定目标类目。该过程整体分为提示特征获取和提示特征推理两个步骤： 1. 提示特征获取 : 这一步的目的是根据用户给出的视觉提示或者文本提示生成对应的提示特征编码用于后续的特征推理，由于用户无法一次确定给出的提示能否达到符合预期的检测效果，因此该过程通常是交互式进行，用户通过尝试不同的提示然后观察在待检测图上的效果，选择符合预期效果的提示得到提示特征编码用户后续的特征推理。 2. 提示特征推理：基于上一步得到的提示特征编码，然后即可在待检测目标图像上进行快速的目标检测。 ![](https://support.huaweicloud.com/api-pangulm/public_sys-resources/note_3.0-zh-cn.png) 需要注意的是： 1. 第二步基于特征进行推理而不直接基于用户提示直接端到端进行目标检测的原因是提示特征提取比较耗费时间，期间开集检测大模型会进行多次视觉或者文本推理非常耗时。对于已经确定的用户提示，这些提示对应的提示特征是一样的，无需重复提取。因此在实际大规模进行目标检测时，需要先获取提示特征，再基于这些提示特征进行快速推理。 2. 对于使用自己的数据集重新预训练或者微调的数据集进行检测，可以直接仅使用文本提示，将训练类目名称的部分或者全部类目名称使用"."进行拼接，可以达到训练时验证集的检测精度。 - **闭集模型推理：** 该模式下和常规目标检测推理方式一致，用户仅需上传待检测的图片即可直接进行目标检测推理。该模式下不具备开集检测能力只能检测训练数据集中的类目，模型会自动加载闭集训练时得到的类目提示特征，无需用户主动进行提示特征获取。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/productdesc-pangulm/pangulm_01_0020.html)。 #### URI POST / 获取URI方式请参见[请求URI](https://support.huaweicloud.com/api-pangulm/pangulm_05_0004.html)。 #### 请求参数 表1请求Header参数（Token认证） | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是（云上部署模型填写） | String | **参数解释：** 用户Token。 用于获取操作API的权限。如[图4](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__fig10797003103)中响应消息头中X-Subject-Token的值即为Token。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | Content-Type | 是 | String | **参数解释：** 发送的实体的MIME类型。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** application/json | 表2请求Header参数（API Key认证） | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Apig-AppCode | 是（云上部署模型填写、边缘部署模型仅在监控网关访问模式下填写） | String | **参数解释：** API Key值。 用于获取操作API的权限。[API Key认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section148602501261)响应消息头中X-Apig-AppCode的值即为API Key。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | Content-Type | 是 | String | **参数解释：** 发送的实体的MIME类型。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** application/json | 表3请求Body参数 --开集推理-提示特征获取 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | mode | 是，值为 prompt_feature_gen | String | **参数解释：** 推理模式为"开集检测特征生成"。 **约束限制：** 不涉及 **取值范围：** 提示特征获取模式，值为固定值"prompt_feature_gen" **默认取值：** 无 | | confidence | 否，默认值0.5 | String | **参数解释：** 设置目标检测结果的阈值过滤，支持对所有类别设置统一阈值或者按类别分别设置阈值。如果该参数传入float值则对所有类别按该值进行过滤，如果该参数传入dict字典，对字典中的类别采用该类别指定阈值过滤，否则使用默认阈值0.5过滤。选填，如果该参数不填则使用默认值0.5。该参数用法示例： 1. 设置所有类别统一阈值：confidence=0.5 2. 按类别设置阈值：confidence={"cat":0.4,"dog":0.6} 3. 不设置阈值，所有类别走默认阈值0.5：confidence=None **约束限制：** 不涉及 **取值范围：** （0，1） **默认取值：** 0.5 | | text_prompt | 否，默认值None | String | **参数解释：** 文本提示 ('.'分隔类别，例如'cat.dog.'表示提示 cat和dog两个类别)，仅适用于prompt_feature_gen模式，**建议提示类别不超过50个。**该模式下该参数为选填，但是text_prompt和visual_prompt两个参数至少填其中一个，也可以两个参数同时都填,。当2个参数都同时设置时，会检测文本提示和视觉提示里包含的所有类别，对于均在文本提示和视觉提示里出现的类别，该类别会利用文本提示和视觉提示共同提取特征并检测，否则使用单一提示进行该类别特征提取和检测。 说明： 建议提示类别不超过50个。 **约束限制：** 不涉及 **取值范围：** 无 **默认取值：** None | | visual_prompt | 否，默认值None | String | **参数解释：** 视觉提示，list类型，其中每张提示图像是一个dict类型，包含两个key: img（image的base64编码）和prompt（该图像的视觉提示）。prompt是一个list类型，包含2个两个key: label（目标类目名）和bbox（标注框信息，其格式为\[x,y,w,h\]）。建议提示图像最多10个。该模式下该参数为选填，但是text_prompt和visual_prompt两个参数至少填其中一个，也可以两个参数同时都填。当2个参数都同时设置时，会检测文本提示和视觉提示里包含的所有类别，对于均在文本提示和视觉提示里出现的类别，该类别会利用文本提示和视觉提示共同提取特征并检测，否则使用单一提示进行该类别特征提取和检测。 **约束限制：** 不涉及 **取值范围：** 无 **默认取值：** None | | target_image | 是 | String | **参数解释：** 待检测图像的base64编码，必填。 **约束限制：** 不涉及 **取值范围：** 无 **默认取值：** 无 | | show_detected_image | 否，默认值false | String | **参数解释：** 是否返回目标图像叠加预测信息可视化结果，true返回，false不返回。 **约束限制：** 不涉及 **取值范围：** true,false **默认取值：** false | **表4** 请求Body参数 --开集推理-提示特征推理 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | mode | 是，值为 prompt_feature_inference | String | **参数解释：** 推理模式为"开集检测-基于提示特征推理"。 **约束限制：** 不涉及 **取值范围：** 基于提示特征推理，值为固定值"prompt_feature_inference" **默认取值：** 无 | | confidence | 否,默认值0.5 | String | **参数解释：** 设置目标检测结果的阈值过滤，支持对所有类别设置统一阈值或者按类别分别设置阈值。如果该参数传入float值则对所有类别按该值进行过滤，如果该参数传入dict字典，对字典中的类别采用该类别指定阈值过滤，否则使用默认阈值0.5过滤。选填，如果该参数不填则使用默认值0.5。该参数用法示例： 1. 设置所有类别统一阈值：confidence=0.5 2. 按类别设置阈值：confidence={"cat":0.4,"dog":0.6} 3. 不设置阈值，所有类别走默认阈值0.5：confidence=None **约束限制：** 不涉及 **取值范围：** （0，1） **默认取值：** 0.5 | | prompt_feature | 是，默认值None | dict | **参数解释：** 提示特征编码，dict类型，key是类别名称，val是该类的特征base64编码，prompt_feature_gen模式下的返回结果可以得到，仅适用于prompt_feature_inference模式。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | target_image | 是 | String | **参数解释：** 待检测图像的base64编码，必填。 **约束限制：** 不涉及 **取值范围：** 无 **默认取值：** 无 | **表5** 请求Body参数 --闭集推理 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | confidence | 否,各个类别最佳阈值 | String | **参数解释：** 设置目标检测结果的阈值过滤，支持对所有类别设置统一阈值或者按类别分别设置阈值。如果该参数传入float值则对所有类别按该值进行过滤，如果该参数传入dict字典，对字典中的类别采用该类别指定阈值过滤，否则使用默认阈值0.5过滤。选填，如果该参数不填则使用默认值0.5。该参数用法示例： 1. 设置所有类别统一阈值：confidence=0.5 2. 按类别设置阈值：confidence={"cat":0.4,"dog":0.6} 3. 不设置阈值，所有类别走默认阈值0.5：confidence=None **约束限制：** 不涉及 **取值范围：** （0，1） **默认取值：** 无 | | target_image | 是 | String | **参数解释：** 待检测图像的base64编码，必填。 **约束限制：** 不涉及 **取值范围：** 无 **默认取值：** 无 | #### 响应参数 **表6** 响应Body--开集推理-提示特征获取 | 参数 | 参数类型 | 说明 | |:---|:---|:---| | results | List | **参数解释：** 物体检测的识别结果。格式为\[{'label': 'xxx', 'score': xxx, 'bbox': \[x,y,w,h\]}, {{'label': 'xxx', 'score': xxx, 'bbox': \[x,y,w,h\]}...}\]。 label：预测类别。 score：置信度。 bbox：目标主体信息，分别为\[x1,y1,w,h\]，其中x1,y1代表左上角坐标，w是宽度，h是高度。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | dataset_id | String | **参数解释：** 数据集ID。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | prompt_feature | dict | **参数解释：** 返回值为dict，其中key为预测类别，value为类别特征base64编码。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | **表7** 响应Body--开集推理-提示特征推理 | 参数 | 参数类型 | 说明 | |:---|:---|:---| | results | List | **参数解释：** 物体检测的识别结果。格式为\[{'label': 'xxx', 'score': xxx, 'bbox': \[x,y,w,h\]}, {{'label': 'xxx', 'score': xxx, 'bbox': \[x,y,w,h\]}...}\]。 label：预测类别。 score：置信度。 bbox：目标主体信息，分别为\[x1,y1,w,h\]，其中x1,y1代表左上角坐标，w是宽度，h是高度。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | dataset_id | String | **参数解释：** 数据集ID。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | **表8** 请求Body参数 --闭集推理 | 参数 | 参数类型 | 说明 | |:---|:---|:---| | results | List | **参数解释：** 物体检测的识别结果。格式为\[{'label': 'xxx', 'score': xxx, 'bbox': \[x,y,w,h\]}, {{'label': 'xxx', 'score': xxx, 'bbox': \[x,y,w,h\]}...}\]。 label：预测类别。 score：置信度。 bbox：目标主体信息,分别为\[x1,y1,w,h\]，其中x1,y1代表左上角坐标，w是宽度，h是高度。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | dataset_id | String | **参数解释：** 数据集ID。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | #### 请求示例 1. 开集推理-提示特征获取 ``` { "mode": "prompt_feature_gen", "confidence": 0.5, "target_image": "target_image_base64_str", "text_prompt": "cat. dog", "visual_prompt": [ { "img": "visual_image_1_base64_str", "prompt": [ { "label": "cat", "bbox": [ 100, 100, 50, 50 ] }, { "label": "cat", "bbox": [ 150, 150, 50, 50 ] } ] }, { "img": "visual_image_2_base64_str", "prompt": [ { "label": "dog", "bbox": [ 30, 30, 60, 60 ] }, { "label": "dog", "bbox": [ 80, 80, 60, 50 ] } ] } ], "show_detected_image": true } ``` 2. 开集推理-提示特征推理 ``` { "mode": "prompt_feature_inference", "confidence": 0.5, "target_image": "target_image_base64_str", "prompt_feature": { "cat": "cat_feature_base64_str", "dog": "dog_feature_base64_str" } } ``` 3. 闭集推理 ``` { "confidence": 0.5, "target_image": "target_image_base64_str" } ``` #### 响应示例 1. 开集推理-提示特征获取 ``` { "dataset_id":"", "results": [ { "label": "cat", "bbox": { "X":10, "Y":10, "Width":50, "Height":50, "Angle":0 }, "score": 0.6784 } ], "result_vis": "target_image_result_vis_base64_str", "prompt_feature": { "cat": "cat_feature_base64_str", "dog": "dog_feature_base64_str" } } ``` 2. 开集推理-提示特征推理 ``` { "dataset_id":"", "results": [ { "label": "cat", "bbox": { "X":10, "Y":10, "Width":50, "Height":50, "Angle":0 }, "score": 0.6784 } ], } ``` 3. 闭集推理 ``` { "dataset_id":"", "results": [ { "label": "cat", "bbox": { "X":10, "Y":10, "Width":50, "Height":50, "Angle":0 }, "score": 0.6784 } ], } ``` #### 状态码 请参见[状态码](https://support.huaweicloud.com/api-pangulm/pangulm_05_0019.html)。 #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-pangulm/pangulm_05_0020.html)。