阿里云图像搜索完整对接指南：从开通到API/SDK深度集成

1. 图像搜索：是什么，能做什么

图像搜索（Image Search）是阿里云推出的一款以深度学习和机器视觉技术为核心的平台型产品。它的工作原理并不复杂：系统会对入库的每一张图片提取高维视觉特征向量，并建立高效的索引结构。当用户提交一张查询图片时，服务会实时计算该图片的特征向量，然后在索引库中快速检索出特征最相似的若干张图片，按相似度分数从高到低返回。

这一技术能够支撑的业务场景非常广泛。在电商领域，最常见的应用是“拍照购物”或“找同款”——用户随手拍下心仪的商品，系统即可在商品库中精准匹配同款或相似款。在版权保护领域，通过输入疑似侵权的图片，可以在图库中快速定位被盗用的原创内容。在媒体资产管理中，输入一张示例图片即可从海量素材库中检索出视觉风格相近的图片。此外，商品推荐、相似图片推荐等场景也是图像搜索的典型用武之地。

阿里云图像搜索目前主要提供两大服务类型：商品图片搜索和通用图片搜索。商品图片搜索专注于电商场景，针对商品主体进行特征提取和匹配，对每个商品类目进行更精细化的特征提取，使得召回更加准确；通用图片搜索则适用于版权保护、相似图片推荐等更广泛的场景，不需要关注具体的类目信息。需要特别注意的是，服务类型在创建实例时选定后不可更改，因此务必要根据实际业务需求做出正确的选择。

从产品能力来看，图像搜索具备搜索精度高、响应速度快（毫秒级）、支持百亿级数据规模、实时增删改查等突出优势。同时，阿里云对客户数据采用非对称加密策略，结合权限控制保障数据安全。

需要先登录阿里云控制台，点 击：阿里云控制台

2. 开通服务与创建实例

2.1 前提条件

在使用图像搜索服务之前，需要完成以下几个准备工作：

• 注册阿里云账号：如尚未注册，可通过阿里云官网完成注册流程。
• 完成实名认证：个人或企业实名认证均可。
• 获取AccessKey：AccessKey ID和AccessKey Secret是调用API和SDK时的身份凭证。建议通过RAM子账号创建AccessKey，避免使用主账号密钥带来的安全风险。

2.2 购买实例

完成上述准备后，即可进入图像搜索产品首页，单击“立即购买”进入实例购买页面。购买时需要配置以下关键参数：

• 地域：图像搜索服务所在的地理区域。目前国际站支持新加坡、中国（香港）、日本（东京）和德国（法兰克福）等地。地域一旦选定不可更改，建议选择与您的应用服务器（如ECS）相同的地域，以便后续使用内网VPC访问，获得更低的延迟和更好的稳定性。
• 服务类型：选择“商品图片搜索”或“通用图片搜索”。此选项一旦选定不可更换，请谨慎选择。
• 访问频次（QPS）：每秒允许向图像搜索服务发起的最大请求次数。例如购买QPS为5的实例，意味着每秒钟最多可以进行5次图片查询操作（删除图片操作的QPS固定为20）。QPS越高，并发处理能力越强，价格也相应更高。
• 最大容量：您可以索引的最大图片数量。对于商品图片搜索，此处指的是图片数量而非商品数量。可选规格包括10万、250万、500万、1000万、2000万、3000万、4000万、5000万。
• 实例名称：必填项，要求以小写字母开头，由小写字母和数字组成，长度4~20个字符。实例名称一旦确认不可修改。
• 购买时长：购买图像搜索服务的时长，可选择是否开启到期自动续费。

在支付页面确认订单信息后，单击“去支付”。支付成功后，服务一般需要1～5分钟的开通时间，请耐心等待。

3. 控制台核心操作

实例创建成功后，即可登录图像搜索管理控制台开始使用。

3.1 实例概览

进入控制台概览页面，页面会展示各服务类型（商品图片搜索、布料图片搜索、商标图片搜索、版权图片搜索、商品多模态搜索等）的实例总数及运行状态统计，右侧提供快速入门指引。

单击实例ID或操作进入实例详情页，默认显示概述页签，展示实例基本信息（实例名称、实例ID、地域、状态、到期时间等）及套餐使用情况（最大容量、已用图片数量等）。

3.2 图片新增

单击“图片新增”Tab，进入图片新增页面。需要填写以下字段：

• 商品ID（ProductId）：必填，最多支持256个字符。一个商品可有多张图片。
• 图片名称（PicName）：必填，最多支持256个字符。ProductId + PicName唯一确定一张图片。如果多次添加图片具有相同的ProductId + PicName，以最后一次添加为准，前面添加的图片将被覆盖。
• 上传图片：支持PNG、JPG、JPEG、BMP、GIF、WEBP、TIFF、PPM格式，图片大小不超过4MB，长宽像素须大于等于100且小于等于4096。
• 图片主体识别：开启后选择主体识别方式（如系统自动识别）。为true时由系统进行主体识别，以识别的主体进行搜索；为false时则不进行主体识别，以整张图进行搜索。
• 图片类目（CategoryId）：选填。对于商品搜索，若设置类目则以设置的为准，若不设置类目将由系统进行类目预测。
• 自定义内容（CustomContent）：选填，最多支持4096个字符，查询时会返回该字段。
• 整数属性（IntAttr）：选填，可用于查询时过滤。
• 字符串属性（StrAttr）：选填，最多支持128个字符，可用于查询时过滤。

单击确认后，右侧返回结果中code为0、message为success表示图片新增成功。

3.3 图片搜索

单击“图片搜索”页签，进入图片搜索页面。搜索类型支持两种模式：

• SearchByPic：使用新图片搜索相似图片。上传待搜索的图片，开启图片主体识别开关，设置返回结果数和结果起始位置等参数。
• SearchByName：使用已入库的图片进行搜索。指定已存在的图片名称，系统在索引中查找相似图片。

右侧“原始返回结果”区域以JSON格式展示搜索响应，其中auctions数组包含匹配记录（含productId和score字段），head中返回docsFound（命中总数）、docsReturn（返回条数）和searchTime（搜索耗时）等信息。

4. 新增图片的四种方式

图像搜索服务提供四种新增图片的方式，适用于不同的业务场景：

• 控制台图片新增：适用于功能体验和小规模测试场景，操作直观，适合快速验证。
• API新增：通过直接调用API接口新增图片，适合需要灵活集成的场景。
• SDK新增：适用于小规模、实时的数据增量操作，代码简洁，易于维护。
• 批量操作：适用于较大规模（百万级）、离线数据操作，可通过批量导入功能从阿里云OSS中批量导入图片。

5. Java SDK对接详解

5.1 添加依赖

通过Maven引入图像搜索SDK依赖：

<dependency> <groupId>com.aliyun</groupId> <artifactId>imagesearch20201214</artifactId> <version>4.3.0</version> </dependency>

5.2 客户端初始化

创建Config对象并配置认证信息：

import com.aliyun.imagesearch20201214.Client; import com.aliyun.teaopenapi.models.Config; public class ImageSearchClient { public static Client createClient() throws Exception { Config config = new Config(); // 从环境变量获取AccessKey，强烈建议不要硬编码到代码中 config.accessKeyId = System.getenv("CC_AK_ENV"); config.accessKeySecret = System.getenv("CC_SK_ENV"); config.type = "access_key"; // 替换为您购买实例的地域 config.regionId = "ap-southeast-1"; config.endpoint = "imagesearch.ap-southeast-1.aliyuncs.com"; return new Client(config); } }

5.3 内网VPC访问配置

如果您的ECS实例与图像搜索实例在同一地域，可以通过内网VPC访问以获得更低的延迟：

// 内网（VPC）访问配置 config.endpointType = "internal"; config.endpoint = "imagesearch-vpc.ap-southeast-1.aliyuncs.com";

5.4 新增图片（Add接口）

Add接口用于向图像搜索实例中添加图片：

import com.aliyun.imagesearch20201214.models.AddImageAdvanceRequest; import com.aliyun.imagesearch20201214.models.AddImageResponse; import com.aliyun.teautil.models.RuntimeOptions; import java.io.FileInputStream; public class AddImageExample { public static void main(String[] args) throws Exception { Client client = ImageSearchClient.createClient(); AddImageAdvanceRequest request = new AddImageAdvanceRequest(); // 必填：实例名称（注意是实例名称不是实例ID） request.instanceName = "myimagesearch"; // 必填：商品ID request.productId = "product_001"; // 必填：图片名称 request.picName = "image_001.jpg"; // 图片内容：通过文件流传入 FileInputStream fileStream = new FileInputStream("/path/to/image.jpg"); request.picContentObject = fileStream; // 选填：图片类目 request.categoryId = 3; // 选填：自定义内容 request.customContent = "夏季新款连衣裙"; // 选填：整数属性，可用于查询时过滤 request.intAttr = 100; // 选填：字符串属性 request.strAttr = "red"; // 选填：是否进行主体识别，默认为true request.crop = true; RuntimeOptions runtime = new RuntimeOptions(); AddImageResponse response = client.addImageAdvance(request, runtime); System.out.println("Response: " + response.getBody()); } }

5.5 图片搜索（SearchImageByPic接口）

SearchImageByPic接口用于根据图片搜索相似图片：

import com.aliyun.imagesearch20201214.models.SearchImageByPicAdvanceRequest; import com.aliyun.imagesearch20201214.models.SearchImageByPicResponse; import java.io.FileInputStream; public class SearchByPicExample { public static void main(String[] args) throws Exception { Client client = ImageSearchClient.createClient(); SearchImageByPicAdvanceRequest request = new SearchImageByPicAdvanceRequest(); request.instanceName = "myimagesearch"; FileInputStream fileStream = new FileInputStream("/path/to/query.jpg"); request.picContentObject = fileStream; // 返回结果数量 request.num = 10; // 结果起始位置 request.start = 0; // 是否进行主体识别 request.crop = true; // 可选：按字符串属性过滤 request.strAttr = "red"; // 可选：按整数属性过滤 request.intAttr = 100; RuntimeOptions runtime = new RuntimeOptions(); SearchImageByPicResponse response = client.searchImageByPicAdvance(request, runtime); System.out.println("Search results: " + response.getBody()); } }

5.6 按名称搜索（SearchImageByName接口）

SearchImageByName接口用于使用已入库的图片进行搜索：

import com.aliyun.imagesearch20201214.models.SearchImageByNameRequest; import com.aliyun.imagesearch20201214.models.SearchImageByNameResponse; public class SearchByNameExample { public static void main(String[] args) throws Exception { Client client = ImageSearchClient.createClient(); SearchImageByNameRequest request = new SearchImageByNameRequest(); request.instanceName = "myimagesearch"; // 已入库图片的商品ID和图片名称 request.productId = "product_001"; request.picName = "image_001.jpg"; request.num = 10; request.start = 0; SearchImageByNameResponse response = client.searchImageByName(request); System.out.println("Search results: " + response.getBody()); } }

5.7 删除图片（Delete接口）

import com.aliyun.imagesearch20201214.models.DeleteImageRequest; import com.aliyun.imagesearch20201214.models.DeleteImageResponse; public class DeleteImageExample { public static void main(String[] args) throws Exception { Client client = ImageSearchClient.createClient(); DeleteImageRequest request = new DeleteImageRequest(); request.instanceName = "myimagesearch"; request.productId = "product_001"; request.picName = "image_001.jpg"; DeleteImageResponse response = client.deleteImage(request); System.out.println("Delete result: " + response.getBody()); } }

6. Python SDK对接详解

6.1 安装SDK

通过pip安装图像搜索Python SDK：

pip install alibabacloud_imagesearch20201214

6.2 客户端初始化

from alibabacloud_imagesearch20201214.client import Client from alibabacloud_tea_openapi.models import Config config = Config() config.access_key_id = os.environ.get('CC_AK_ENV') config.access_key_secret = os.environ.get('CC_SK_ENV') config.type = 'access_key' config.region_id = 'ap-southeast-1' config.endpoint = 'imagesearch.ap-southeast-1.aliyuncs.com' client = Client(config)

6.3 新增图片（Add接口）

Python SDK的Add接口使用AddImageAdvanceRequest：

from alibabacloud_imagesearch20201214.models import AddImageAdvanceRequest from alibabacloud_tea_util.models import RuntimeOptions import os def add_image(): request = AddImageAdvanceRequest() # 必填：实例名称 request.instance_name = 'myimagesearch' # 必填：商品ID request.product_id = 'product_001' # 必填：图片名称 request.pic_name = 'image_001.jpg' # 图片内容：通过打开文件传入 with open('/path/to/image.jpg', 'rb') as f: request.pic_content_object = f # 选填：图片类目 request.category_id = 3 # 选填：自定义内容 request.custom_content = '夏季新款连衣裙' # 选填：整数属性 request.int_attr = 100 # 选填：字符串属性 request.str_attr = 'red' # 选填：是否进行主体识别 request.crop = True runtime = RuntimeOptions() response = client.add_image_advance(request, runtime) print(response.body) if __name__ == '__main__': add_image()

6.4 图片搜索（SearchImageByPic接口）

from alibabacloud_imagesearch20201214.models import SearchImageByPicAdvanceRequest def search_by_pic(): request = SearchImageByPicAdvanceRequest() request.instance_name = 'myimagesearch' with open('/path/to/query.jpg', 'rb') as f: request.pic_content_object = f request.num = 10 request.start = 0 request.crop = True request.str_attr = 'red' request.int_attr = 100 runtime = RuntimeOptions() response = client.search_image_by_pic_advance(request, runtime) print(response.body) if __name__ == '__main__': search_by_pic()

6.5 按名称搜索（SearchImageByName接口）

from alibabacloud_imagesearch20201214.models import SearchImageByNameRequest def search_by_name(): request = SearchImageByNameRequest() request.instance_name = 'myimagesearch' request.product_id = 'product_001' request.pic_name = 'image_001.jpg' request.num = 10 request.start = 0 response = client.search_image_by_name(request) print(response.body) if __name__ == '__main__': search_by_name()

7. 高级功能与应用场景

7.1 批量操作

图像搜索支持通过批量操作功能批量导入阿里云OSS中的图片，或批量删除已经入库的图片。使用批量操作时，需要确保图像搜索实例和OSS Bucket在同一地域。具体流程包括：先将图片上传到OSS，然后通过批量操作功能引用OSS上的JSONL文件进行批量导入。

7.2 条件过滤

在图片新增和搜索时，可以通过设置属性参数实现条件过滤。支持的属性字段包括IntAttr、IntAttr2、IntAttr3、IntAttr4（整数类型属性）以及StrAttr、StrAttr2、StrAttr3、StrAttr4（字符串类型属性）。例如，在电商场景中，可以为不同站点的图片设置不同的IntAttr，查询时通过过滤来实现数据隔离。

7.3 多模态搜索

图像搜索还提供了商品多模态搜索能力，这是一种结合了文本和图像进行多模态检索的技术。它通过融合不同模态的信息，提升图像搜索的准确性和灵活性，使用户能够通过自然语言描述或图片形式快速找到目标图像。

7.4 典型应用场景

• 电商“拍照购物”：用户上传商品照片，系统自动识别商品主体（如连衣裙、鞋子），在商品库中检索相似款式，并支持按颜色、尺码等标签进一步筛选。
• 版权保护：通过输入疑似侵权的图片，在图库中快速定位被盗用的原创内容。
• 内容推荐：输入一张示例图片，从海量素材库中检索出视觉风格相近的图片，用于相似内容推荐。

8. 计费说明与注意事项

8.1 计费模式

图像搜索服务采用按月（自然月）预付费资源包的计费方式。计费项只包括图片最大容量和访问频次（QPS），其余功能均免费使用。

• 图片最大容量：用户可以索引的最大图片数量。可选规格包括10万、250万、500万、1000万、2000万、3000万、4000万、5000万。
• 访问频次（QPS）：每秒能向图像搜索服务发起的最大请求次数。可选规格包括1QPS（仅限10万图片容量）、5QPS、10QPS。删除图片操作的QPS固定为20。

8.2 重要注意事项

• 地域不可更改：地域一旦选定不可更改，请谨慎选择。
• 服务类型不可更改：服务类型一旦选定不可更换，请根据实际业务需求选择。
• 实例名称不可修改：实例名称一旦确认不可修改。
• 内网访问：内网VPC访问仅限同区域ECS或资源的访问，如果遇到调用不通，请先检查您的ECS或资源与图像搜索是否在同一个区域。
• 图片格式要求：当前仅支持PNG、JPG、JPEG、BMP、GIF、WEBP、TIFF、PPM格式图片；图片长和宽的像素必须都大于等于100且小于等于4096；图像中不能带有旋转信息。

9. 常见问题解答

问1：商品图片搜索和通用图片搜索有什么区别？
答：商品图片搜索主要针对商品类的图片进行相关的类目划分，针对每个类目进行更精细化的特征提取，使得每个商品类目上的召回更加准确，适用的场景是电商类的应用。通用图片搜索不需要关注具体的类目信息，所有的图片均属于一个通用的类目，适用于版权保护、相似图片推荐等场景。

问2：图像搜索支持哪些图片格式？图片大小有什么限制？
答：支持PNG、JPG、JPEG、BMP、GIF、WEBP、TIFF、PPM格式图片。图片大小不超过4MB，长宽像素须大于等于100且小于等于4096，图像中不能带有旋转信息。

问3：如何通过内网VPC访问图像搜索服务？
答：需要确保您的ECS实例与图像搜索实例在同一地域。在SDK配置中，将endpointType设置为"internal"，并将endpoint设置为对应地域的VPC地址（如imagesearch-vpc.ap-southeast-1.aliyuncs.com）。

问4：图像搜索的计费方式是什么？
答：采用按月（自然月）预付费资源包的计费方式，计费项只包括图片最大容量和访问频次（QPS），其余功能均免费使用。图片最大容量可选10万至5000万共8个规格，QPS可选1、5、10三个规格。

问5：如果图片新增失败，可能的原因有哪些？
答：常见原因包括：图片格式不支持、图片大小超过4MB、图片像素不符合要求（小于100或大于4096）、图像中含有旋转信息、实例名称填写错误（注意是实例名称不是实例ID）、AccessKey权限不足等。

问6：如何批量导入大量图片？
答：可以通过批量操作功能实现。首先将图片上传到阿里云OSS（需与图像搜索实例在同一地域），然后通过批量操作功能引用OSS上的JSONL文件进行批量导入。如果图片没有存储在OSS，可使用OSSImport工具先将图片上传到OSS。