图像上传 - 图像搜索

本文介绍如何将图像上传到图像搜索服务。

背景信息

图像搜索提供两种方式上传图片，一种是通过图像搜索产品API或者SDK，另一种方式是通过借助阿里云OSS通过批量操作进行上传。

如果您仅上传少量图片，建议您使用API或SDK方式。详情请参见新增图片。
如果您是企业级的用户，或者您需要批量上传图片，但图片没有存储在阿里云OSS，可使用OSSImport工具将图片存储在阿里云OSS上，然后进行批量上传。具体步骤请参见操作流程。
如果您是企业级的用户，或者您需要批量上传图片，且图片已经存储在阿里云OSS。请参见批量操作。
重要
使用图像搜索的批量操作功能，需保证图像搜索和阿里云OSS在同一区域。

OSSImport介绍

OSSImport是阿里云OSS提供的一款将数据迁移至OSS存储空间（Bucket）的工具。您可以将OSSImport部署在本地服务器或云上ECS实例内，轻松将您本地或其它云存储的数据迁移到OSS。

使用OSSImport上传图片具有以下优势：

保持图片快速更新到图像搜索引擎。
同一个OSS存储空间可供不同环境使用，像开发项目，线上项目等。
根据业务需要，更好地组织和管理多种图片的来源。
更好地管理复杂环境的项目，例如开发项目，UAT项目等。
优化使用网络带宽：一次上传，多次使用。
使用这个工具，您可以将图像搜索管理产业化。

图片限制

单张图片大小不超过4 MB。
图片的长和宽分辨率要求大于100px小于等于4096px。

步骤一：下载OSSImport工具

OSSImport有单机模式和分布式模式两种部署方式。

单机模式：当您需要迁移的数据小于30TB时，推荐部署单机模式。您可以将OSSImport部署在任意一台可以访问待迁移数据的机器上，且可以访问OSS的机器上。单击OSSImport下载。
分布式模式：当您需要迁移的数据大于30TB时，推荐使用分布式模式。您可以将OSSImport部署在任意多台可以访问您待迁移数据，且可以访问OSS的机器上。单击OSSImport下载。

说明

当您迁移的数据过大时，为了节约时间，您可以将OSSImport部署到与您OSS相同地域的ECS实例上，并通过专线将源数据存放的服务器挂载到阿里云VPC网络中。多台ECS实例将数据通过内网迁移至OSS，会极大的提升数据迁移效率。

步骤二：开通对象存储OSS

具体操作步骤请参见开通OSS服务进行开通。

步骤三：创建存储空间（bucket）

具体操作步骤请参见控制台创建存储空间。

说明

请确保开通的OSS服务以及创建的Bucket与已购买的图像搜索服务在同一个地域。

步骤四：导入increment.meta 数据

在OSS服务中存放图片的路径下，新建increment.meta文件，该文件用来存储批量操作任务相关内容。

说明

increment.meta文件中涉及的图片必须和increment.meta文件在同一Bucket下，否则批量操作会失败。
increment.meta文件名称是固定的，图像搜索将根据此文件名称读取批量操作相关内容，不要擅自修改文件名称，否则会操作失败。
图像搜索批量操作支持同一Bucket，不同路径（path）图片的批量操作，例如：Bucket为imagesearch，increment.meta文件在此Bucket的根目录下，path为girlCloth，图片在此path目录下，图片名称为girl_cloth8.jpg，则meta文件中PicName应写为“PicName":"girlCloth/girl_cloth8.jpg"，注意：必须写成"girlCloth/girl_cloth8.jpg"，在girlCloth前面和girl_cloth8.jpg后面都不能加正斜线(/)。如果有多级目录按照此逻辑依次类推。
在OSS中的图片名称后缀必须填写，例如图片名称为girl_cloth10.jpg，不能写为"PicName":"girl_cloth10"，必须写为"PicName":"girl_cloth10.jpg"，否则会处理失败。
increment.meta文件中，一行代表处理一张图片，处理另一张图片必须换行，不得将所有图片处理写到一行中，否则会处理失败。

文件参考示例如下：

{"OperationType": "ADD","ProductId": "1000","PicName": "girl_cloth1.jpg","CategoryId": 0,"IntAttr": 0,"StrAttr": "value1","CustomContent": "k1:v1,k2:v2,k3:v3","Region": "20,40,60,80"}
{"OperationType": "ADD","ProductId": "1000","PicName": "girl_cloth2.jpg","CategoryId": 0,"IntAttr": 0,"StrAttr": "value2","CustomContent": "k1:v1,k2:v2,k3:v3","Region": "20,40,60,80"}
{"OperationType": "ADD","ProductId": "1001","PicName": "girl_cloth3.jpg","CategoryId": 1,"CustomContent": "k1:v1,k2:v2,k3:v3"}
{"OperationType": "ADD","ProductId": "1002","PicName": "girl_cloth4.jpg","CategoryId": 0,"CustomContent": "k1:v1,k2:v2,k3:v3","Crop": false}
{"OperationType": "ADD","ProductId": "1003","PicName": "girl_cloth7.jpg","CustomContent": "https://www.aliyun.com/imagesearch/girl_cloth7.jpg"}
{"OperationType": "ADD","ProductId": "1003","PicName": "girl_cloth6.jpg","CustomContent": "k1:v1,k2:v2,k3:v3"}
{"OperationType": "ADD","ProductId": "1006","PicName": "girlCloth/girl_cloth10.jpg","CustomContent": "k1:v1,k2:v2,k3:v3"}
{"OperationType": "DELETE","ProductId": "1004","PicName": "fengyi.jpg"}
{"OperationType": "DELETE","ProductId": "1005"}

每个图片由JSON格式表示，具体字段含义如下表所示：

参数	类型	是否必选	说明
OperationType	String	是	操作类型。 ADD：新增图片。 DELETE：删除图片。
ProductId	String	是	图片唯一标识符，最多支持512个字符。
PicName	String	是	图片名称。OSS的Bucket中图片名称。最多支持512个字符。重要每行最多只允许填写1个图片名称。若同一个ProductId，对应多个PicName则需要填写多行。图片名称必须填写后缀，例如：girl_cloth.jpg，不能写为girl_cloth，必须写为girl_cloth.jpg，否则会处理失败。如果图片具有相同的商品ID+图片名称，则以最后一次添加为准。即如果图片具有相同的商品ID+图片名称，则不管图片本身是否相同，后一张图片都会覆盖前一张图片。新增图片具体要求如下图片大小要求不超过4 MB。图片格式：PNG、JPG、JPEG、BMP、GIF、WEBP、TIFF、PPM。传输等待时间不超过5秒。服务类型为商品图片搜索、通用图片搜索、家具家居图片搜索、工业五金图片搜索时，图片长和宽像素要求大于等于100且小于等于4096px。图片中不能包含旋转信息。
CategoryId	Integer	否	更多说明，请参见类目参考。对于商品搜索，如果设置类目，则以设置的为准，并且设置的类目必须在类目参考的范围之内，否则会入库失败。如果不设置类目，将由系统进行类目预测，预测的类目结果可在Response中获取。对于通用搜索、版权图片搜索、工业五金、家具家居图片搜索，不论是否设置类目，系统会将类目设置为88888888。
CustomContent	String	是	用户自定义内容。最多支持4096个字符。说明图片的CustomContent会在搜索结果中自动关联出来。通过CustomContent字段，您可以填写图片的URL地址，图片额外附加信息等，以便与您的业务关联。
IntAttr	Integer	否	整数类型属性。用于查询时设置过滤。说明整型类型属性与图片查询时的过滤条件组合使用，以起到过滤查询的功能。请参考条件过滤。
StrAttr	String	否	字符串类型属性。最多支持128字符。用于查询时设置过滤。说明字符串类型属性与图片查询时的过滤条件组合使用，以起到过滤查询的功能。请参考条件过滤。
Crop	Boolean	否	是否进行主体识别。默认为true。 true：系统自动进行主体识别，以识别的主体进行搜索。 false：不进行主体识别，以整张图进行搜索。
Region	String	否	图片的主体区域。格式为`x1,x2,y1,y2`，其中x1和y1是左上角的点，x2和y2是右下角的点。说明若设置了该参数，则Crop参数不生效，以该设置为准。

步骤五：授予图像搜索服务访问OSS的权限

图像搜索服务通过OSS来实现数据批量操作，首次使用需完成账号一键授权。如已完成授权，可跳过此步骤。

步骤六：上传图片

登录图像搜索控制台。
选择目标服务类型和目标实例。
单击批量操作页签。
单击新建批量任务。

设置批量任务参数。

所属区域
实例所在区域。
Bucket名称
OSS上创建的相应的Bucket名称。
重要
请确保开通的OSS服务与已购买的图像搜索服务在同一个地域。
数据路径
需要上传的图片和increment.meta文件的存储路径。
meta文件
需要处理图片的列表文件，支持检测是否存在，文件名为increment.meta。

完成后信息回调

输入回调地址，仅支持HTTP或者HTTPS开头。

{
  "finishTime": "2021-05-19 17:50:00",
  "instanceId": "imagesearch-cn-xxxx",
  "instanceName": "instanceName",
  "message": "success",
  "processResultUrl": "https://image-search-task-info.oss-cn-shanghai.aliyuncs.com/yyyyyyyyyy",
  "status": "NORMAL",
  "taskId": 111
}

字段名	描述
finishTime	完成时间，精确到秒。
instanceName	图像搜索实例名称。
instanceId	图像搜索实例ID。
status	任务执行结果，NORMAL为正常，FAIL为执行失败。
taskId	任务ID。
message	信息描述；success为成功。
processResultUrl	错误结果下载。

执行结果

任务运行完之后，您可以单击实例ID查看任务运行的状态。

如果运行失败，单击查看增量历史获得详细信息。更多信息请参见增量任务提交失败的原因都有哪些？
图片上传成功之后，您可以单击实例ID，然后单击图片搜索进行测试。