阿里云图像搜索完整对接指南:从开通到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越高,并发处理能力越强。
- 最大容量:您可以索引的最大图片数量。对于商品图片搜索,此处为图片数量,而不是商品数量。
- 实例名称:必填项,要求以小写字母开头,由小写字母和数字组成,长度不超过20个字符,创建后无法修改。
- 购买时长与自动续费:根据需要选择购买时长,可勾选到期自动续费(到期前9天开始自动续费)。
在支付页面确认订单信息后,单击去支付。支付成功后,服务开通一般需要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,图片中不能包含旋转信息。
- 图片主体识别(Crop):默认为true。为true时由系统进行主体识别,以识别的主体进行搜索;为false时不进行主体识别,以整张图进行搜索。
- 图片类目(CategoryId):选填。对于商品搜索,若设置类目则以设置的为准,若不设置类目将由系统进行类目预测;对于通用搜索,不论是否设置类目,系统都会将类目设置为88888888。
- 自定义内容(CustomContent):选填,最多支持4096个字符,查询时会返回该字段。
- 整数属性(IntAttr):选填,可用于查询时过滤。
- 字符串属性(StrAttr):选填,最多支持128个字符,可用于查询时过滤。
右侧返回结果中code为0、message为success表示图片新增成功。
3.3 图片搜索
在实例详情页选择“图片搜索”Tab,图像搜索服务支持通过API、SDK(推荐方式)和控制台(适用于功能体验场景)三种方式进行图片查询。控制台方式配置如下参数:
- 搜索类型(Type):SearchByPic(根据新图片搜索相似图片,默认选项)或SearchByName(根据已添加的图片名称搜索相似图片)。
- 上传图片:图片内容需进行Base64编码,规格要求同图片新增。
- 图片主体识别(Crop):可选择系统自动识别或自定义主体区域(格式为x1,x2,y1,y2)。
- 返回结果数(Num):返回相似结果的最大值,取值范围1~100,默认10。
- 结果起始位置(Start):取值范围0~499,默认0。
- 过滤条件(Filter):可设置int_attr和str_attr的过滤条件,支持>、>=、<、<=、=、in、not in等操作符,多个条件之间支持AND和OR连接。
- 相似度过滤(ScoreThreshold):只返回相似度分数大于等于阈值的图片,阈值范围0.00~1.00,默认0.00。
右侧“原始返回结果”区域以JSON格式展示搜索结果,包含score(相似度分数)、productId、picName等字段。
4. Python SDK对接实战
阿里云图像搜索提供了完整的Python SDK,支持Add(增加图片)、SearchImageByPic(使用图片搜索)、SearchImageByName(按名称搜索)、Delete(删除图片)、UpdateImage(修改图片)等核心接口。
4.1 环境准备
首先安装依赖包:
pip install alibabacloud_imagesearch202012144.2 新增图片(AddImage)
以下为完整的Python SDK新增图片示例:
from alibabacloud_imagesearch20201214.client import Client
from alibabacloud_imagesearch20201214.models import AddImageAdvanceRequest
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions
import os
def add_image():
# 配置认证信息
config = Config()
# 强烈建议将AccessKey配置在环境变量中,避免硬编码
config.access_key_id = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID')
config.access_key_secret = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
config.type = 'access_key'
# 请替换为您购买实例的地域
config.region_id = 'ap-southeast-1'
config.endpoint = 'imagesearch.ap-southeast-1.aliyuncs.com'
client = Client(config)
request = AddImageAdvanceRequest()
# 必填:实例名称(注意是实例名称,不是实例ID)
request.instance_name = 'your-instance-name'
# 必填:商品ID
request.product_id = 'product_001'
# 必填:图片名称
request.pic_name = 'image_001.jpg'
# 方式一:从本地文件读取图片
with open('/path/to/your/image.jpg', 'rb') as f:
request.pic_content_object = f
# 方式二:从URL下载图片(需注释掉方式一)
# import requests
# from io import BytesIO
# url = 'https://example.com/image.jpg'
# request.pic_content_object = BytesIO(requests.get(url).content)
# 选填:商品类目
request.category_id = 3
# 选填:自定义内容
request.custom_content = 'this is a test product'
# 选填:整数属性(可用于过滤)
request.int_attr = 56
# 选填:字符串属性(可用于过滤)
request.str_attr = 'test_category'
# 选填:是否进行主体识别
request.crop = True
runtime = RuntimeOptions()
try:
response = client.add_image_advance(request, runtime)
print(f'新增图片成功,RequestId: {response.request_id}')
print(f'响应信息: {response.body.message}')
except Exception as e:
print(f'新增图片失败: {e}')
if __name__ == '__main__':
add_image()4.3 以图搜图(SearchImageByPic)
以下为使用新图片进行相似图片搜索的示例:
from alibabacloud_imagesearch20201214.client import Client
from alibabacloud_imagesearch20201214.models import SearchImageByPicAdvanceRequest
from alibabacloud_tea_openapi.models import Config
import os
def search_by_pic():
config = Config()
config.access_key_id = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID')
config.access_key_secret = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
config.type = 'access_key'
config.region_id = 'ap-southeast-1'
config.endpoint = 'imagesearch.ap-southeast-1.aliyuncs.com'
client = Client(config)
request = SearchImageByPicAdvanceRequest()
request.instance_name = 'your-instance-name'
# 上传待搜索的图片
with open('/path/to/query/image.jpg', 'rb') as f:
request.pic_content_object = f
# 选填:返回结果数量,默认10
request.num = 10
# 选填:结果起始位置,默认0
request.start = 0
# 选填:过滤条件
# request.filter = 'int_attr=56'
# 选填:相似度阈值
request.score_threshold = 0.5
# 选填:是否进行主体识别
request.crop = True
runtime = RuntimeOptions()
try:
response = client.search_image_by_pic_advance(request, runtime)
print(f'搜索成功,RequestId: {response.request_id}')
if response.body.auctions:
for auction in response.body.auctions:
print(f'商品ID: {auction.product_id}, 图片名: {auction.pic_name}, 相似度: {auction.score}')
except Exception as e:
print(f'搜索失败: {e}')
if __name__ == '__main__':
search_by_pic()4.4 按名称搜索(SearchImageByName)
SearchImageByName接口使用已入库的图片进行相似图片搜索:
from alibabacloud_imagesearch20201214.client import Client
from alibabacloud_imagesearch20201214.models import SearchImageByNameRequest
from alibabacloud_tea_openapi.models import Config
import os
def search_by_name():
config = Config()
config.access_key_id = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID')
config.access_key_secret = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
config.type = 'access_key'
config.region_id = 'ap-southeast-1'
config.endpoint = 'imagesearch.ap-southeast-1.aliyuncs.com'
client = Client(config)
request = SearchImageByNameRequest()
request.instance_name = 'your-instance-name'
# 必填:已入库图片的商品ID
request.product_id = 'product_001'
# 必填:已入库图片的图片名称
request.pic_name = 'image_001.jpg'
# 选填:返回结果数量
request.num = 10
# 选填:过滤条件
# request.filter = 'str_attr="test_category"'
runtime = RuntimeOptions()
try:
response = client.search_image_by_name(request, runtime)
print(f'搜索成功,RequestId: {response.request_id}')
if response.body.auctions:
for auction in response.body.auctions:
print(f'相似商品: {auction.product_id}, 相似度: {auction.score}')
except Exception as e:
print(f'搜索失败: {e}')
if __name__ == '__main__':
search_by_name()4.5 删除图片(DeleteImage)
from alibabacloud_imagesearch20201214.client import Client
from alibabacloud_imagesearch20201214.models import DeleteImageRequest
from alibabacloud_tea_openapi.models import Config
import os
def delete_image():
config = Config()
config.access_key_id = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID')
config.access_key_secret = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
config.type = 'access_key'
config.region_id = 'ap-southeast-1'
config.endpoint = 'imagesearch.ap-southeast-1.aliyuncs.com'
client = Client(config)
request = DeleteImageRequest()
request.instance_name = 'your-instance-name'
# 必填:商品ID
request.product_id = 'product_001'
# 必填:图片名称
request.pic_name = 'image_001.jpg'
runtime = RuntimeOptions()
try:
response = client.delete_image(request, runtime)
print(f'删除成功,RequestId: {response.request_id}')
except Exception as e:
print(f'删除失败: {e}')
if __name__ == '__main__':
delete_image()5. Java SDK对接实战
阿里云图像搜索同样提供了完整的Java SDK。
5.1 Maven依赖
在pom.xml中添加以下依赖:
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>imagesearch20201214</artifactId>
<version>4.3.0</version>
</dependency>5.2 新增图片(AddImage)
以下为Java SDK新增图片的完整示例:
import com.aliyun.imagesearch20201214.Client;
import com.aliyun.imagesearch20201214.models.AddImageAdvanceRequest;
import com.aliyun.imagesearch20201214.models.AddImageResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
import java.io.FileInputStream;
public class AddImageExample {
public static void main(String[] args) throws Exception {
Config authConfig = new Config();
// 强烈建议将AccessKey配置在环境变量中
authConfig.accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
authConfig.accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
authConfig.type = "access_key";
// 请替换为您购买实例的地域
authConfig.regionId = "ap-southeast-1";
authConfig.endpoint = "imagesearch.ap-southeast-1.aliyuncs.com";
// 如需使用内网VPC访问,请取消以下注释
// authConfig.endpointType = "internal";
// authConfig.endpoint = "imagesearch-vpc.ap-southeast-1.aliyuncs.com";
Client client = new Client(authConfig);
AddImageAdvanceRequest request = new AddImageAdvanceRequest();
// 必填:实例名称
request.setInstanceName("your-instance-name");
// 必填:商品ID
request.setProductId("product_001");
// 必填:图片名称
request.setPicName("image_001.jpg");
// 从本地文件读取图片
FileInputStream fileStream = new FileInputStream("/path/to/your/image.jpg");
request.setPicContentObject(fileStream);
// 选填:商品类目
request.setCategoryId(3);
// 选填:自定义内容
request.setCustomContent("this is a test product");
// 选填:整数属性
request.setIntAttr(56);
// 选填:字符串属性
request.setStrAttr("test_category");
// 选填:是否进行主体识别
request.setCrop(true);
RuntimeOptions runtime = new RuntimeOptions();
try {
AddImageResponse response = client.addImageAdvance(request, runtime);
System.out.println("新增图片成功,RequestId: " + response.getRequestId());
System.out.println("响应信息: " + response.getBody().getMessage());
} catch (Exception e) {
System.err.println("新增图片失败: " + e.getMessage());
}
}
}5.3 以图搜图(SearchImageByPic)
import com.aliyun.imagesearch20201214.Client;
import com.aliyun.imagesearch20201214.models.SearchImageByPicAdvanceRequest;
import com.aliyun.imagesearch20201214.models.SearchImageByPicResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
import java.io.FileInputStream;
public class SearchByPicExample {
public static void main(String[] args) throws Exception {
Config authConfig = new Config();
authConfig.accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
authConfig.accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
authConfig.type = "access_key";
authConfig.regionId = "ap-southeast-1";
authConfig.endpoint = "imagesearch.ap-southeast-1.aliyuncs.com";
Client client = new Client(authConfig);
SearchImageByPicAdvanceRequest request = new SearchImageByPicAdvanceRequest();
request.setInstanceName("your-instance-name");
FileInputStream fileStream = new FileInputStream("/path/to/query/image.jpg");
request.setPicContentObject(fileStream);
request.setNum(10);
request.setStart(0);
request.setScoreThreshold(0.5f);
request.setCrop(true);
RuntimeOptions runtime = new RuntimeOptions();
try {
SearchImageByPicResponse response = client.searchImageByPicAdvance(request, runtime);
System.out.println("搜索成功,RequestId: " + response.getRequestId());
if (response.getBody().getAuctions() != null) {
for (SearchImageByPicResponse.SearchImageByPicResponseBodyAuctions auction :
response.getBody().getAuctions()) {
System.out.println("商品ID: " + auction.getProductId() +
", 相似度: " + auction.getScore());
}
}
} catch (Exception e) {
System.err.println("搜索失败: " + e.getMessage());
}
}
}6. API调用核心参数详解
6.1 图片规格要求
无论是图片新增还是图片搜索,上传的图片都需要满足以下规格:
- 大小:不超过4 MB
- 格式:PNG、JPG、JPEG、BMP、GIF、WEBP、TIFF、PPM
- 分辨率:长和宽像素要求大于等于100px且小于等于4096px
- 传输等待时间:不超过5秒
- 旋转信息:图片中不能包含旋转信息
6.2 Base64编码说明
在API调用中,图片内容需要通过Base64编码后传递。Python SDK和Java SDK的AdvanceRequest已经封装了Base64编码逻辑,开发者只需传递文件流或二进制数据即可。如果直接调用REST API,则需要自行进行Base64编码。
6.3 过滤条件(Filter)详解
搜索时可以通过Filter参数设置过滤条件,只返回符合过滤条件的图像结果:
- int_attr:支持的操作符有 >、>=、<、<=、=、in、not in
- str_attr:支持的操作符有 =、!=、in、not in
- 多条件组合:多个条件之间支持AND和OR进行连接,例如:
int_attr=1000 AND str_attr="value1"
6.4 相似度分数(Score)
搜索结果中的score字段表示查询图片与入库图片之间的相似度,取值范围为0.00~1.00,分数越高表示越相似。可以通过ScoreThreshold参数设置相似度过滤阈值,只返回分数大于等于该值的图片结果。
7. 批量操作:大规模图片导入与导出
对于百万级甚至更大规模的图片数据,逐张调用AddImage接口效率较低。图像搜索服务提供了与阿里云OSS对接的批量操作功能,通过简单操作即可将OSS中的图片批量导入到图像搜索服务中。
7.1 批量导入
批量导入适用于较大规模(百万级)、离线数据操作。基本流程如下:
- 将图片文件上传到阿里云OSS的某个Bucket中
- 在图像搜索控制台选择“批量操作”功能
- 配置OSS路径、图片映射关系等参数
- 提交批量导入任务,系统自动完成图片的向量化与索引构建
批量导入具有稳定性高、速度快、操作方便等优势,特别适合初次建库时的全量数据导入场景。
7.2 QPS限制说明
需要注意的是,图片新增接口有QPS限制。10万图片容量的实例默认并发量为1,即每秒钟最多处理1个图片新增请求。在进行批量导入时,系统会自动处理并发控制,但如果是自行编写脚本调用API进行批量新增,需要合理控制请求频率,避免触发限流。
8. VPC内网访问配置
如果您的应用部署在阿里云ECS上,且与图像搜索实例位于同一地域,建议使用VPC内网访问方式,可以获得更低的延迟和更好的稳定性。
8.1 Python SDK内网配置
config = Config()
config.access_key_id = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID')
config.access_key_secret = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
config.type = 'access_key'
config.region_id = 'ap-southeast-1'
# 内网访问的关键配置
config.endpoint_type = 'internal'
config.endpoint = 'imagesearch-vpc.ap-southeast-1.aliyuncs.com'8.2 Java SDK内网配置
Config authConfig = new Config();
authConfig.accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
authConfig.accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
authConfig.type = "access_key";
authConfig.regionId = "ap-southeast-1";
// 内网访问的关键配置
authConfig.endpointType = "internal";
authConfig.endpoint = "imagesearch-vpc.ap-southeast-1.aliyuncs.com";使用内网访问时,必须确保ECS或其它资源与图像搜索实例位于同一地域,否则会调用不通。
9. 最佳实践与注意事项
9.1 服务类型选择
服务类型在创建实例时选定后不可更改。如果图片主要是商品图片(如裙装、鞋包等),应选择“商品图片搜索”;如果是风景、人物、版权图片等,应选择“通用图片搜索”。选错服务类型会严重影响搜索效果。
9.2 图片质量优化
为了获得更好的搜索效果,建议:
- 上传清晰、主体突出的图片
- 对于商品图片,尽量保证商品主体占据图片的主要区域
- 开启主体识别(Crop=true),让系统自动聚焦于图片主体
- 避免上传带有大量水印、文字遮挡或复杂背景的图片
9.3 类目设置策略
对于商品图片搜索,如果明确知道图片所属类目,建议主动设置CategoryId,这样可以获得更精准的匹配结果。如果不确定类目,可以不设置,由系统自动进行类目预测。
9.4 安全与权限管理
强烈建议使用RAM子账号的AccessKey进行API调用,而非主账号的AccessKey。这样可以有效控制权限范围,降低密钥泄露带来的安全风险。RAM子账号应仅授予图像搜索相关的必要权限。
9.5 成本优化
图像搜索服务按量计费主要涉及以下维度:
- 实例费用(根据QPS和容量规格)
- API调用次数(图片新增、搜索、删除等)
- 如果使用内网VPC访问,可节省公网流量费用
建议根据实际业务量合理选择QPS和容量规格,避免过度配置造成浪费。
10. 常见问题(FAQ)
问题1:商品图片搜索和通用图片搜索有什么区别?
商品图片搜索主要针对商品类图片进行类目划分,针对每个类目进行更精细化的特征提取,使召回更加准确。通用图片搜索不进行类目划分,适用于版权保护、相似图片推荐等更广泛的场景。
问题2:新增图片时报错“实例名称不存在”怎么办?
请检查代码中使用的instance_name是否为实例名称而非实例ID。实例名称是在创建实例时自定义的,可以在控制台实例详情页查看。
问题3:搜索效果不准确,如何优化?
首先检查图片风格与服务类型是否匹配。其次,确保上传的图片清晰、主体突出,并开启主体识别功能(Crop=true)。此外,对于商品图片搜索,建议设置正确的CategoryId。
问题4:图片新增的QPS限制是多少?
10万图片容量的实例默认并发量为1,即每秒钟最多处理1个图片新增请求。更高容量的实例QPS限制会相应提升,具体可在控制台查看实例详情。
问题5:如何通过内网VPC访问图像搜索服务?
将SDK的endpointType设置为“internal”,并将endpoint修改为对应的VPC地址(如imagesearch-vpc.ap-southeast-1.aliyuncs.com)。同时,确保ECS或其它资源与图像搜索实例位于同一地域。
问题6:图片搜索支持哪些图片格式和大小?
支持PNG、JPG、JPEG、BMP、GIF、WEBP、TIFF、PPM格式,图片大小不超过4MB,长宽像素在100px到4096px之间,且不能包含旋转信息。




