# 配置图像搜索连接器
图像搜索连接器用于对接华为云图像搜索云服务。
图像搜索（ImageSearch）基于深度学习与图像识别技术，结合不同应用业务和行业场景，利用特征向量化与搜索能力，帮助客户从指定图库中搜索相同或相似的图片。
#### 创建图像搜索连接
1. 登录[ROMA Connect控制台](https://console.huaweicloud.com/roma3)。

2. 在左侧导航栏选择"连接器"，在连接器页面单击"新建连接"。
3. 选择"图像搜索"连接器。
4. 在弹窗中配置连接信息，完成后单击"确定"。
   
   | 参数     | 说明                                                                                                                                                         |
   |:---|:---|
   | 连接名称   | 填写连接器实例名称。                                                                                                                                                 |
   | 访问密钥ID | 当前账号的AK（Access Key ID）。请参考[访问密钥](https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html)获取AK，如果已生成过AK/SK，找到原来已下载的AK/SK文件，文件名一般为：credentials.csv。    |
   | 秘密访问密钥 | 当前账号的SK（Secret Access Key）。请参考[访问密钥](https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html)获取SK，如果已生成过AK/SK，找到原来已下载的AK/SK文件，文件名一般为credentials.csv。 |
   | 描述     | 填写连接器的描述信息，用于识别不同的连接器。                                                                                                                                     |
      
   
 
#### 支持的动作
- 删除数据
- 更新数据
- 检查数据
- 搜索
- 添加数据
 
#### 配置参数
表1删除数据 
| 参数              | 说明                                                                                                                                                                                                                                                                                                                                                                                            |
|:---|:---|
| project_id      | 项目ID。                                                                                                                                                                                                                                                                                                                                                                                         |
| service_name    | 服务实例的名称，用户创建服务实例时指定。                                                                                                                                                                                                                                                                                                                                                                          |
| region_id       | 区域ID。                                                                                                                                                                                                                                                                                                                                                                                         |
| force           | 是否幂等删除数据，默认为false。仅对指定ID删除生效。 - false：数据不存在时返回错误信息。  - true：数据不存在时返回成功，用于幂等删除场景。                                                                                                        |
| item_id         | 数据的服务实例级唯一标识，字符长度范围为\[1, 256\]。 item_id/custom_tags/custom_num_tags中必须给定至少一个参数，以支持对服务实例中的数据进行指定ID删除或条件删除。 如给定item_id参数，则进行指定ID删除，否则进行条件删除。                                                                                                                                                                                    |
| custom_tags     | 自定义字符标签，用于对服务实例中的数据进行条件删除。格式为键值对{key:value}。 - key：必须为服务实例custom_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。  - value：标签值列表，列表内多个标签值为"或"关系，即满足一个即可。列表长度范围为\[1, 32\]，标签值类型为字符串，字符长度范围为\[1, 64\]。   |
| custom_num_tags | 自定义数值标签，用于对服务实例中的数据进行custom_num_tags条件删除。格式为键值对{key:value}。 - key：必须为服务实例custom_num_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。针对没有设置该数值标签的数据，会直接过滤。  - value：标签值的取值范围，标签值在给定的取值范围内即视为符合条件。               |
| from            | 数值下界，默认包含该下界。                                                                                                                                                                                                                                                                                                                                                                                 |
| to              | 数值上界，默认包含该上界。                                                                                                                                                                                                                                                                                                                                                                                 |
   
表2更新数据 
| 参数              | 说明                                                                                                                                                                                                                                                                                                                                     |
|:---|:---|
| project_id      | 项目ID。                                                                                                                                                                                                                                                                                                                                  |
| service_name    | 服务实例的名称，用户创建服务实例时指定。                                                                                                                                                                                                                                                                                                                   |
| region_id       | 区域ID。                                                                                                                                                                                                                                                                                                                                  |
| item_id         | 数据的服务实例级唯一标识，字符长度范围为\[1, 256\]。                                                                                                                                                                                                                                                                                                        |
| decs            | 数据的描述信息，字符长度范围为\[1, 2048\]。                                                                                                                                                                                                                                                                                                            |
| custom_tags     | 数据的自定义字符标签，用于进行条件过滤。格式为键值对{key:value}。 - key：必须为服务实例custom_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。  - value：类型为字符串，字符长度范围为\[1, 64\]。                               |
| custom_num_tags | 数据的自定义数值标签，用于进行条件过滤。格式为键值对{key:value}。 - key：必须为服务实例custom_num_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。  - value：类型为数值，格式为double。   |
   
表3检查数据 
| 参数              | 说明                                                                                                                                                                                                                                                                                                                                                                                                |
|:---|:---|
| project_id      | 项目ID。                                                                                                                                                                                                                                                                                                                                                                                             |
| service_name    | 服务实例的名称，用户创建服务实例时指定。                                                                                                                                                                                                                                                                                                                                                                              |
| region_id       | 区域ID。                                                                                                                                                                                                                                                                                                                                                                                             |
| item_id         | 数据的服务实例级唯一标识，字符长度范围为\[1, 256\]。 item_id/custom_tags/custom_num_tags中必须给定至少一个参数，以支持对服务实例中的数据进行指定ID删除或条件删除。 如给定item_id参数，则进行指定ID删除，否则进行条件删除。                                                                                                                                                                                          |
| limit           | 返回检查结果的数量，默认为10，取值范围为\[1, 100\]。仅对条件检查生效。                                                                                                                                                                                                                                                                                                                                                         |
| last_item       | 前一次检查的最后一个检查结果的排序信息。仅对条件检查生效，可将上一次检查返回结果中的last_item字段直接用于此处。                                                                                                                                                                                                                                                                                                                                      |
| score           | 结果的得分。                                                                                                                                                                                                                                                                                                                                                                                            |
| id              | 结果的唯一ID。                                                                                                                                                                                                                                                                                                                                                                                          |
| custom_tags     | 自定义字符标签，用于对服务实例中的数据进行条件查找。格式为键值对{key:value}。 - key：必须为服务实例custom_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。  - value：标签值列表，列表内多个标签值为"或"关系，即满足一个即可。列表长度范围为\[1, 32\]，标签值类型为字符串，字符长度范围为\[1, 64\]。   |
| custom_num_tags | 自定义数值标签，用于对服务实例中的数据进行条件查找。格式为键值对{key:value}。 - key：必须为服务实例custom_num_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。针对没有设置该数值标签的数据，会直接过滤。  - value：标签值的取值范围，标签值在给定的取值范围内即视为符合条件。                       |
| from            | 数值下界，默认包含该下界。                                                                                                                                                                                                                                                                                                                                                                                     |
| to              | 数值上界，默认包含该上界。                                                                                                                                                                                                                                                                                                                                                                                     |
   
表4搜索 
| 参数              | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
|:---|:---|
| project_id      | 项目ID。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| service_name    | 服务实例的名称，用户创建服务实例时指定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| region_id       | 区域ID。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| search_type     | 搜索类型，必须为服务实例支持的搜索类型。服务实例的搜索类型列表可在创建服务实例时进行配置。 可以使用枚举名或者枚举值（例如IMAGE/0），枚举值可能会变动，建议使用枚举名。                                                                                                                                                                                                                                                                                                                                                                                   |
| limit           | 返回搜索结果的数量，默认为10，取值范围为\[1, 100\]。                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| offset          | 返回搜索结果的偏移量，即返回序号在\[offset, offset+limit\]内的搜索结果。默认为0，取值范围为\[0, N\]。 默认情况下，搜索要求offset+limit \<= 1000。 针对支持全量召回的场景，使用全量召回时，要求offset必须为0。                                                                                                                                                                                                                                                                                                      |
| last_item       | 前一次搜索的最后一个搜索结果的排序信息。仅对全量召回场景生效，可将上一次搜索返回结果中的last_item字段直接用于此处。 目前仅有KEYWORD支持全量召回。 使用全量召回时，offset必须为0。                                                                                                                                                                                                                                                                                                                                   |
| score           | 结果的得分。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| id              | 结果的唯一ID。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| min_score       | 返回搜索结果的最小得分，用于对搜索结果进行score过滤，取值范围为\[0, 1\]。 目前仅对IMAGE/CATEGORY搜索类型生效。                                                                                                                                                                                                                                                                                                                                                                                                     |
| custom_tags     | 自定义字符标签，用于对搜索结果进行条件过滤。格式为键值对{key:value}。 - key：必须为服务实例custom_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。  - value：标签值列表，列表内多个标签值为"或"关系，即满足一个即可。列表长度范围为\[1, 32\]，标签值类型为字符串，字符长度范围为\[1, 64\]。                                                                                                                   |
| custom_num_tags | 自定义数值标签，用于对搜索结果进行条件过滤。格式为键值对{key:value}。 - key：必须为服务实例custom_num_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。针对没有设置该数值标签的数据，会直接过滤。  - value：标签值的取值范围，标签值在给定的取值范围内即视为符合条件。                                                                                                                                                                                |
| from            | 数值下界，默认包含该下界。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| to              | 数值上界，默认包含该上界。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| image_base64    | 图像文件的base64字符串，基于图像搜索时，与image_url参数二选一。要求如下： - 格式：目前仅支持JPEG/JPG/PNG/BMP/WEBP格式的图像。  - 大小：图像文件大小要求不超过5M。  - 尺寸：默认情况下，要求图像的最短边大于64px，最长边小于4096px。部分服务类型有特殊要求，可参见服务类型说明。  - 其他：图片中不能包含旋转信息。   |
| image_url       | 图像文件的服务可访问URL，字符长度范围为\[1, 4096\]。基于图像搜索时，与image_base64参数二选一。                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| keywords        | 关键词列表，搜索时关键词数量范围为\[1, 10\]，关键词字符长度范围为\[1, 64\]。使用KEYWORD搜索类型进行搜索时，必须提供该参数。                                                                                                                                                                                                                                                                                                                                                                                                                             |
| optional_params | 可选参数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| do_det          | 是否进行目标检测，默认为true。 - true：进行目标检测。  - false：不进行目标检测。                                                                                                                                                                                                                                                             |
| box             | 目标矩形框坐标，如给定则不进行目标检测，直接使用该box作为目标。格式为"x1,y1,x2,y2"（无空格），x1/y1为目标左上角坐标，x2/y2为目标右下角坐标，具体要求如下： - 0 \<= x1 \< x2 \<= width，默认要求x2-x1 \>= 15，具体可参考服务类型说明。  - 0 \<= y1 \< y2 \<= height，默认要求y2-y1 \>= 15，具体可参考服务类型说明。                                                                                                   |
| do_cls          | 是否进行对象分类，默认为true。 - true：进行对象分类。  - false：不进行对象分类。                                                                                                                                                                                                                                                          |
| category        | 对象类目，如给定则不进行对象分类，直接使用该category作为类目。具体类目信息可参见对应的服务类型说明。                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| collapse_key    | 去重标签名，必须为服务实例custom_tags中已存在的key。 - 如给定则会对该key下相同value的数据进行去重，仅保留得分最高的数据。  - 针对没有设置该标签的数据，会直接过滤。                                                                                                                                                                                                            |
| max_scan_num    | 扫描节点上限。值越大精度越高，查询速度变慢。默认值为10000。                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| nprobe          | 查询考察中心点的数目。值越大精度越高，查询速度变慢。默认值为100。                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
   
表5添加数据 
| 参数              | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|:---|:---|
| project_id      | 项目ID。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| service_name    | 服务实例的名称，用户创建服务实例时指定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| region_id       | 区域ID。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| force           | 是否强制添加数据，默认为false。 - false：数据已存在则不进行添加。  - true：数据已存在仍然覆盖添加。                                                                                                                                                                                                                                              |
| item_id         | 数据的服务实例级唯一标识，字符长度范围为\[1, 256\]。                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| desc            | 数据的描述信息，字符长度范围为\[1, 2048\]。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| custom_tags     | 数据的自定义字符标签，用于进行条件过滤。格式为键值对{key:value} - key：必须为服务实例custom_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。  - value：类型为字符串，字符长度范围为\[1, 64\]。                                                                                                                                                                                                          |
| custom_num_tags | 数据的自定义数值标签，用于进行条件过滤。格式为键值对{key:value}。 - key：必须为服务实例custom_num_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。  - value：类型为数值，格式为double。                                                                                                                                                                          |
| image_base64    | 图像文件的base64字符串，图像入库时，与image_url参数二选一。要求如下： - 格式：目前仅支持JPEG/JPG/PNG/BMP/WEBP格式的图像。  - 大小：图像文件大小要求不超过5M。  - 尺寸：默认情况下，要求图像的最短边大于64px，最长边小于4096px。部分服务类型有特殊要求，可参见服务类型说明。  - 其他：图片中不能包含旋转信息。   |
| image_url       | 图像文件的服务可访问URL，字符长度范围为\[1, 4096\]。图像入库时，与image_base64参数二选一。                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| keywords        | 关键词列表，关键词数量范围为\[1, 100\]，关键词字符长度范围为\[1, 64\]。支持关键词搜索的服务实例添加数据时，如给定此参数，则直接使用给定的keywords作为关键词，否则会自动生成对应的keywords。                                                                                                                                                                                                                                                                                                                                                                                               |
| optional_params | 可选参数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| do_det          | 是否进行目标检测，默认为true。 - true：进行目标检测。  - false：不进行目标检测。                                                                                                                                                                                                                                                                  |
| box             | 目标矩形框坐标，如给定则不进行目标检测，直接使用该box作为目标。格式为"x1,y1,x2,y2"（无空格），x1/y1为目标左上角坐标，x2/y2为目标右下角坐标，具体要求如下： - 0 \<= x1 \< x2 \<= width，默认要求x2-x1 \>= 15，具体可参考服务类型说明。  - 0 \<= y1 \< y2 \<= height，默认要求y2-y1 \>= 15，具体可参考服务类型说明。                                                                                                   |
| do_cls          | 是否进行对象分类，默认为true。 - true：进行对象分类。  - false：不进行对象分类。                                                                                                                                                                                                                                                          |
| category        | 对象类目，如给定则不进行对象分类，直接使用该category作为类目。具体类目信息可参见对应的服务类型说明。                                                                                                                                                                                                                                                                                                                                                                                                                                                        |