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

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

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

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

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

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

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

2. 开通服务与创建实例

2.1 前提条件

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

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

2.2 购买实例

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

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

确认订单并完成支付后，系统会自动创建实例，一般需要1~5分钟。实例状态变为“运行中”后即可正常使用。

3. 控制台核心操作

图像搜索管理控制台是进行实例管理、图片新增和图片搜索的可视化操作界面。登录控制台后，左侧导航栏列出了资源概览和各类服务类型；右侧区域展示各服务类型的实例总数和运行状态统计。

3.1 进入实例详情

在实例列表中，单击实例ID或“操作”列中的入口，即可进入实例详情页。详情页默认展示“概述”页签，包含实例的基本信息（实例名称、实例ID、地域、状态、到期时间等）以及套餐使用情况（最大容量、已用图片数量等）。

3.2 图片新增

在实例详情页中，选择“图片新增”页签即可开始向图库中添加图片。新增图片时需要填写以下参数：

• 商品ID（ProductId）：图片所属商品的唯一标识，用于后续按商品维度进行管理和检索。
• 图片名称（PicName）：图片在实例中的唯一名称，与商品ID共同构成图片的唯一标识。
• 上传图片：支持从本地选择图片文件上传。
• 图片主体识别：可开启此开关并选择主体识别方式（如系统自动识别），服务会自动检测图片中的主体区域并进行针对性特征提取，从而提升搜索精度。
• 图片类目、自定义内容、整数型属性和字符串属性：这些是可选的扩展字段，用于为图片打标签，后续搜索时可通过这些标签进行过滤。

单击“确认”后，右侧的返回结果中如果code为0、message为success，表示图片新增成功。需要注意的是，图像搜索服务并不会存储图片原图，而是提取并存储图片的特征向量以及商品ID、图片名称等元信息。

3.3 相似图片搜索

在实例详情页中，选择“图片搜索”页签即可进行相似图片检索。图像搜索提供两种搜索模式：

• SearchByPic（以图搜图）：上传一张新图片作为查询条件，在图片库中检索视觉上相似的图片。
• SearchImageByName（按名称搜索）：指定已入库图片的名称（结合商品ID），使用已入库的图片作为查询条件进行相似图片检索。

以SearchByPic为例，配置搜索参数时需要设置：

• 待搜索的图片：上传用于查询的图片文件。
• 图片主体识别：可开启此开关，系统会自动识别查询图片的主体区域，只对主体部分进行特征提取和匹配。
• 返回结果数：指定本次搜索最多返回多少条匹配结果。
• 结果起始位置：用于分页，指定从第几条结果开始返回。
• 过滤条件：可基于图片类目、整数型属性、字符串属性等标签进行过滤，缩小搜索范围。

单击“确认”后，右侧的“原始返回结果”区域会以JSON格式展示搜索结果。其中auctions数组包含了每一条匹配记录，每条记录中包含productId（商品ID）和score（相似度分数）字段；head中则包含docsFound（命中总数）、docsReturn（返回条数）和searchTime（搜索耗时）等信息。

4. 使用Java SDK对接

对于需要将图像搜索能力集成到自有应用中的开发者，使用SDK是最高效的方式。阿里云图像搜索提供了Java、Python、Node.js等多种语言的SDK。本节以Java SDK为例，详细讲解对接步骤和代码实现。

4.1 添加Maven依赖

在项目的pom.xml文件中添加以下依赖：

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

4.2 初始化客户端

初始化客户端时需要配置认证信息、地域和Endpoint。强烈建议将AccessKey ID和AccessKey Secret保存在环境变量中，而不是硬编码在源代码里，以防止密钥泄露。

import com.aliyun.imagesearch20201214.Client;
import com.aliyun.teaopenapi.models.Config;

public class ImageSearchClient {
    public static Client createClient() throws Exception {
        Config authConfig = new Config();
        // 从环境变量读取AccessKey
        authConfig.accessKeyId = System.getenv("CC_AK_ENV");
        authConfig.accessKeySecret = System.getenv("CC_SK_ENV");
        authConfig.type = "access_key";
        // 替换为您购买实例的地域
        authConfig.regionId = "ap-southeast-1";
        // 替换为对应地域的Endpoint
        authConfig.endpoint = "imagesearch.ap-southeast-1.aliyuncs.com";
        return new Client(authConfig);
    }
}

关于Endpoint的说明：

• 如果您的图像搜索实例在新加坡地域，则regionId为ap-southeast-1，endpoint为imagesearch.ap-southeast-1.aliyuncs.com。
• 如果您希望通过内网VPC访问（仅限与图像搜索实例在同一地域的ECS或其他资源），需要额外设置endpointType = "internal"，并使用内网Endpoint。

4.3 新增图片（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();
        // 必填：实例名称
        request.setInstanceName("your-instance-name");
        // 必填：商品ID
        request.setProductId("product_001");
        // 必填：图片名称
        request.setPicName("image_001.jpg");
        // 必填：图片内容，通过FileInputStream读取本地图片
        request.setPicContentObject(new FileInputStream("/path/to/image.jpg"));
        // 可选：是否开启主体识别，默认true
        request.setCrop(true);
        // 可选：主体识别方式，支持"auto"（自动识别）和"single"（单主体）
        request.setRegion("auto");
        // 可选：图片类目
        request.setCategoryId(1);
        
        RuntimeOptions runtime = new RuntimeOptions();
        AddImageResponse response = client.addImageAdvance(request, runtime);
        
        System.out.println("RequestId: " + response.getRequestId());
        System.out.println("Code: " + response.getCode());
        System.out.println("Message: " + response.getMessage());
        // code为0表示成功
        if (response.getCode() == 0) {
            System.out.println("图片新增成功！");
        }
    }
}

4.4 搜索图片（SearchImageByPic接口）

SearchImageByPic接口用于以图搜图。以下是一个完整的代码示例：

import com.aliyun.imagesearch20201214.models.SearchImageByPicAdvanceRequest;
import com.aliyun.imagesearch20201214.models.SearchImageByPicResponse;
import java.io.FileInputStream;

public class SearchImageExample {
    public static void main(String[] args) throws Exception {
        Client client = ImageSearchClient.createClient();
        
        SearchImageByPicAdvanceRequest request = new SearchImageByPicAdvanceRequest();
        // 必填：实例名称
        request.setInstanceName("your-instance-name");
        // 必填：查询图片内容
        request.setPicContentObject(new FileInputStream("/path/to/query.jpg"));
        // 可选：是否开启主体识别
        request.setCrop(true);
        // 可选：主体识别方式
        request.setRegion("auto");
        // 可选：返回结果数量，默认10
        request.setNum(10);
        // 可选：结果起始位置，用于分页
        request.setStart(0);
        // 可选：过滤条件，例如只返回特定类目的图片
        // request.setFilter("category_id=1");
        
        RuntimeOptions runtime = new RuntimeOptions();
        SearchImageByPicResponse response = client.searchImageByPicAdvance(request, runtime);
        
        System.out.println("RequestId: " + response.getRequestId());
        System.out.println("Code: " + response.getCode());
        System.out.println("命中总数: " + response.getHead().getDocsFound());
        System.out.println("返回条数: " + response.getHead().getDocsReturn());
        System.out.println("搜索耗时: " + response.getHead().getSearchTime() + "ms");
        
        // 遍历搜索结果
        if (response.getAuctions() != null) {
            for (SearchImageByPicResponse.SearchImageByPicResponseAuctions auction : response.getAuctions()) {
                System.out.println("商品ID: " + auction.getProductId());
                System.out.println("图片名称: " + auction.getPicName());
                System.out.println("相似度分数: " + auction.getScore());
                System.out.println("---");
            }
        }
    }
}

4.5 删除图片（Delete接口）

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.setInstanceName("your-instance-name");
        // 必填：商品ID
        request.setProductId("product_001");
        // 可选：图片名称，如果不指定则删除该商品ID下的所有图片
        request.setPicName("image_001.jpg");
        
        DeleteImageResponse response = client.deleteImage(request);
        System.out.println("Code: " + response.getCode());
        System.out.println("Message: " + response.getMessage());
    }
}

5. 使用Python SDK对接

Python SDK的使用方法与Java SDK类似，同样需要先安装SDK包并配置认证信息。

5.1 安装SDK

使用pip安装图像搜索Python SDK：

pip install alibabacloud_imagesearch20201214

5.2 初始化客户端与新增图片

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 create_client():
    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'
    return Client(config)

def add_image():
    client = create_client()
    request = AddImageAdvanceRequest()
    request.instance_name = 'your-instance-name'
    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.crop = True
    request.region = 'auto'
    
    runtime = RuntimeOptions()
    response = client.add_image_advance(request, runtime)
    print(f'RequestId: {response.request_id}')
    print(f'Code: {response.code}')
    print(f'Message: {response.message}')

if __name__ == '__main__':
    add_image()

5.3 搜索图片

from alibabacloud_imagesearch20201214.models import SearchImageByPicAdvanceRequest

def search_image():
    client = create_client()
    request = SearchImageByPicAdvanceRequest()
    request.instance_name = 'your-instance-name'
    with open('/path/to/query.jpg', 'rb') as f:
        request.pic_content_object = f
    request.crop = True
    request.region = 'auto'
    request.num = 10
    request.start = 0
    
    runtime = RuntimeOptions()
    response = client.search_image_by_pic_advance(request, runtime)
    
    print(f'命中总数: {response.head.docs_found}')
    print(f'返回条数: {response.head.docs_return}')
    print(f'搜索耗时: {response.head.search_time}ms')
    
    if response.auctions:
        for auction in response.auctions:
            print(f'商品ID: {auction.product_id}, 相似度: {auction.score}')

if __name__ == '__main__':
    search_image()

6. 批量操作：对接OSS实现百万级图片导入

对于需要处理大规模图片数据的场景（如百万级图片库的初始化构建），逐张调用API或SDK显然效率太低且不经济。图像搜索服务提供了批量操作功能，通过与阿里云对象存储OSS对接，实现高效的大规模图片导入和删除。

批量操作的核心流程如下：

• 将待导入的图片文件提前上传到OSS的某个Bucket中。
• 在图像搜索控制台的批量操作页面，配置OSS路径、实例名称、图片映射规则等参数。
• 系统会自动从OSS读取图片文件，批量导入到图像搜索实例中。

批量操作具有稳定性高、速度快、操作方便的特点，特别适合较大规模的离线数据操作。同样，批量删除功能也支持通过指定OSS路径或商品ID列表，批量删除已入库的图片。

需要注意的是，图片新增接口（Add）本身也有QPS限制：10万图片容量的实例默认并发量为1（即每秒最多处理1个新增请求），其他容量实例默认并发量为5。对于大规模导入场景，建议优先使用批量操作功能。

7. 图片管理：更新与删除

除了新增和搜索，图像搜索还提供了图片更新和删除的能力。

• 更新图片（UpdateImage）：可根据商品ID和图片名称修改图片信息，如更新图片内容、调整类目或属性标签等。
• 删除图片（Delete）：支持四种删除方式——通过API删除、通过SDK删除（适用于小规模实时操作）、批量操作删除（适用于大规模离线操作）、以及在控制台一键清空实例中的所有图片。

Delete接口的调用方式与Add类似，只需传入instanceName和productId（可选picName）即可。如果不指定picName，则会删除该商品ID下的所有图片。

8. 计费模式与成本优化

阿里云图像搜索的计费主要包含以下几个维度：

• 索引构建费：图片入库时进行特征提取和索引构建所产生的费用。
• 检索调用费：每次调用搜索接口所产生的费用，按调用次数计费。
• 存储费：索引数据在云端存储所产生的费用。

目前图像搜索提供两种主要的计费模式：

• 按量付费：按实际使用的API调用次数和存储容量付费，适合业务量波动较大或处于测试阶段的场景。
• 资源包（包年包月）：预先购买一定量的调用次数或存储容量，适合日均请求量稳定、可预估的大规模生产环境。

关于具体的调用价格，根据调用量采用阶梯计价——调用量越大，单次调用单价越低。建议中小规模应用优先选择按量付费，大型应用则通过预购资源包来降低单次调用成本。

9. 常见问题解答

问1：图像搜索实例创建后，服务类型还能修改吗？

不能。服务类型（商品图片搜索或通用图片搜索）在创建实例时选定后不可更改。同样，地域在购买后也不能更换。因此建议在创建实例前充分评估业务需求。

问2：新增图片后多久可以进行搜索？

图片新增后，图像搜索服务会自动对图片进行特征提取和索引构建，这个过程通常在秒级到分钟级完成。索引构建完成后，新增加的图片即可被搜索到。

问3：图像搜索服务会存储我的原始图片吗？

不会。图像搜索服务只存储图片的特征向量以及商品ID、图片名称等元信息，并不会存储图片原图。原始图片需要您自行在本地或OSS等存储服务中保存。

问4：如何提高图像搜索的准确率？

建议在图片新增和搜索时都开启“图片主体识别”功能。系统会自动检测图片中的主体区域并进行针对性特征提取，避免背景等无关信息的干扰，从而显著提升搜索精度。

问5：内网VPC访问和公网访问有什么区别？

内网VPC访问仅限与图像搜索实例在同一地域的ECS或其他云资源使用。相比公网访问，内网访问延迟更低、稳定性更好，且不会产生外网流量费用。如果您的应用部署在阿里云ECS上且与图像搜索实例在同一地域，强烈建议使用内网VPC访问。

问6：批量操作最多支持多少张图片？

批量操作适用于较大规模（百万级）的离线图片数据操作。具体容量上限取决于您购买的图像搜索实例的最大容量配置。