人脸识别迁移到新版

人脸检测基于智能媒体管理（IMM）提供的AI算法，能够分析图片内容。用户可将图片上传至OSS（对象存储服务）随时随地对存储在OSS中的图片进行分析。您可以通过本文了解从OSS数据处理模块智能媒体迁移至人脸检测的相关步骤。

背景信息

智能媒体管理（IMM）后续新增功能及优化将以新版为主，旧版将逐步下线。由智能媒体管理（IMM）提供的媒体处理、文档处理、图片智能及文件处理等 x-oss-process 数据处理能力的所有接口均采用新版智能媒体管理。

前提条件

已开通智能媒体管理（IMM）服务。具体操作，请参见开通产品。
已绑定IMM项目。通过OSS控制台绑定的具体操作，请参见快速入门。通过API绑定的具体操作，请参见AttachOSSBucket - 绑定对象存储桶。
IMM Project需要跟Bucket在同一地域下。

注意事项

人脸检测功能仅支持同步处理（x-oss-process处理方式）。
不支持匿名访问。
必须拥有IMM处理所需的相关权限。更多信息，请参见权限。
新版本的人脸检测功能不支持归档直读。

使用场景

人脸识别：通过人脸检测和识别技术，检测人脸信息。然后将人脸与数据库中的人脸进行比对，实现身份验证、门禁控制等应用。
人脸认证：通过人脸检测和认证技术，验证用户的身份，如手机解锁、支付验证等。
人脸表情分析：通过人脸检测和表情识别技术，分析人脸表情，用于情感分析、人机交互、虚拟角色等应用。
说明
- 背景杂乱：复杂的背景可能会与面部特征混淆，影响检测结果。
- 多人脸遮挡：在图像中存在多个人脸时，相互之间可能会发生遮挡，检测算法的性能可能会下降。

如何迁移

您可以按照以下步骤进行迁移：

在控制台绑定新版本。
控制台解除旧版本的绑定。
使用人脸识别检测。

步骤一：在控制台绑定新版本

登录OSS管理控制台。
在左侧导航栏，单击Bucket列表，然后单击目标Bucket名称。
在左侧导航栏，选择数据处理。
单击图片智能，然后在弹出绑定页面单击Bucket绑定IMM project按钮。
在绑定智能媒体管理项目对话框的IMM配置区域，根据需要选择以下两种绑定方式中的一种：
- 创建新的Project：输入Project的名称，系统会自动在存储空间所在的地域创建对应的IMM项目，并将其与当前存储空间绑定。
- 绑定已有Project：在下拉列表中选择需要绑定至存储空间的IMM项目。
单击人体人脸模块，点击创建样式，输入样式名称，点击确定。关于样式的详细介绍，请参见样式。

步骤二：控制台解除旧版本的绑定

重要

新旧版本之间存在不兼容性。解绑后，旧版本IMM项目的人脸识别检测功能将无法继续使用，OSS控制台以及使用SDK调用人脸识别检测接口均会受到影响。因此，请务必谨慎执行解绑操作。
在解除旧版IMM Project的Bucket绑定时，请确保所选的Bucket准确无误，以防止误操作对IMM控制台和OSS控制台的正常使用产生影响。

登录OSS管理控制台。
在左侧导航栏，单击Bucket列表，然后单击目标Bucket名称。
在左侧导航栏，选择数据处理。
在智能媒体界面查看当前Bucket绑定的旧版IMM Project,点击图标，选择解绑，点击确定。

步骤三：使用人脸识别检测

使用SDK

以下仅列举常见SDK通过处理参数的方式使用人脸检测的代码示例。如需使用其他SDK完成人脸检测，请参见以下常见SDK自行调整。

Java

要求使用3.17.4及以上版本的Java SDK。

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.OSSObject;
import com.aliyun.oss.model.GetObjectRequest;
import com.aliyuncs.exceptions.ClientException;

import java.io.ByteArrayOutputStream;
import java.io.IOException;

public class Demo1 {
    public static void main(String[] args) throws ClientException, ClientException {
        // yourEndpoint填写Bucket所在地域对应的Endpoint。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 填写Endpoint对应的Region信息，例如cn-hangzhou。
        String region = "cn-hangzhou";
        // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 指定Bucket名称。
        String bucketName = "examplebucket";
        // 如果图片位于Bucket根目录，则直接填写图片名称。如果图片不在Bucket根目录，需携带图片完整路径，例如exampledir/example.jpg。
        String key = "example.jpg";

        // 创建OSSClient实例。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // 构建人脸检测的处理指令。
            GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
            getObjectRequest.setProcess("image/faces");

            // 使用getObject方法，并通过process参数传入处理指令。
            OSSObject ossObject = ossClient.getObject(getObjectRequest);

            // 读取并打印信息。
            ByteArrayOutputStream baos = new ByteArrayOutputStream();
            byte[] buffer = new byte[1024];
            int bytesRead;
            while ((bytesRead = ossObject.getObjectContent().read(buffer)) != -1) {
                baos.write(buffer, 0, bytesRead);
            }
            String imageFaces = baos.toString("UTF-8");
            System.out.println("Image Faces:");
            System.out.println(imageFaces);
        } catch (IOException e) {
            System.out.println("Error: " + e.getMessage());
        } finally {
            // 关闭OSSClient。
            ossClient.shutdown();
        }
    }
}

Python

要求使用Python SDK 2.18.4及以上版本。

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
# 填写阿里云通用Region ID。
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

# 如果图片位于Bucket根目录，则直接填写图片名称。如果图片不在Bucket根目录，需携带图片完整路径，例如exampledir/example.jpg。
key = 'example.jpg'

# 构建人脸检测的处理指令。
process = 'image/faces'

try:
    # 使用get_object方法，并通过process参数传入处理指令。
    result = bucket.get_object(key, process=process)

    # 读取并打印信息。
    image_faces = result.read().decode('utf-8')
    print("Image Faces:")
    print(image_faces)
except oss2.exceptions.OssError as e:
    print("Error:", e)

Go

要求使用Go SDK 3.0.2及以上版本。

package main

import (
	"fmt"
	"io"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// 从环境变量中获取临时访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// 创建OSSClient实例。
	// yourEndpoint填写Bucket对应的Endpoint，以华东1（杭州）为例，填写为https://oss-cn-hangzhou.aliyuncs.com。其他Region请按实际情况填写。
	// yourRegion指定阿里云通用Region ID，例如cn-hangzhou。
	client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// 指定Bucket名称，例如examplebucket。
	bucketName := "examplebucket"

	bucket, err := client.Bucket(bucketName)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// 如果图片位于Bucket根目录，则直接填写图片名称。如果图片不在Bucket根目录，需携带图片完整路径，例如exampledir/example.jpg。
	// 通过oss.Process方法构建人脸检测的处理指令。
	body, err := bucket.GetObject("example.jpg", oss.Process("image/faces"))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	defer body.Close()

	data, err := io.ReadAll(body)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	fmt.Println("data:", string(data))
}

PHP

要求使用PHP SDK 2.7.0及以上版本。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;

try {
    // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
    $provider = new EnvironmentVariableCredentialsProvider(); 
    // 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
    // 填写Bucket名称，例如examplebucket。
    $bucket = 'examplebucket';
    // 如果图片位于Bucket根目录，则直接填写图片名称。如果图片不在Bucket根目录，需携带图片完整路径，例如exampledir/example.jpg。
    $key = 'example.jpg'; 

    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,        
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        // 填写阿里云通用Region ID。
        "region" => "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
  // 构建人脸检测的处理指令。
  $options[$ossClient::OSS_PROCESS] = "image/faces";
  $result = $ossClient->getObject($bucket,$key,$options);
  var_dump($result);
} catch (OssException $e) {
  printf($e->getMessage() . "\n");
  return;
}

使用REST API

如果您的程序自定义要求较高，您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。关于公共请求头Authorization的计算方法请参见签名版本4（推荐）。

您可以通过在GetObject接口中添加x-oss-process参数的方式来处理图片。更多信息请参见GetObject。

处理示例

GET /example.jpg?x-oss-process=image/faces HTTP/1.1
Host: image-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 21 Jul 2023 08:57:30 GMT
Authorization: SignatureValue

返回示例

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Fri, 21 Jul 2023 08:57:30 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 161
Connection: keep-alive
x-oss-request-id: 628E2481184E20F26C000009
x-oss-transfer-acc-type: acc-none
x-oss-data-location: oss-cn-hangzhou-a
ETag: "D0F162350DA037F4DC2A142B2E116BD0"
Last-Modified: Wed, 25 May 2022 12:20:34 GMT
x-oss-object-type: Normal
x-oss-hash-crc64ecma: 2040549661341440100
x-oss-storage-class: Standard
x-oss-server-time: 12437

{
    "RequestId": "5F2389FE-A5E3-076F-B071-43A33DB0D716",
    "Figures": [{
        "Beard": "none",
        "MaskConfidence": 0.7509999871253967,
        "Gender": "male",
        "Boundary": {
            "Left": 280,
            "Top": 36,
            "Height": 87,
            "Width": 70
        },
        "BeardConfidence": 0.9980000257492065,
        "FigureId": "d39651db-9dc4-469f-8834-d2fcf30e179e",
        "Mouth": "open",
        "Emotion": "none",
        "Age": 12,
        "MouthConfidence": 0.5669999718666077,
        "FigureType": "face",
        "GenderConfidence": 0.9509999752044678,
        "HeadPose": {
            "Pitch": -12.309000015258789,
            "Roll": -11.362000465393066,
            "Yaw": 3.443000078201294
        },
        "Mask": "none",
        "EmotionConfidence": 0.9950000047683716,
        "HatConfidence": 0.9879999756813049,
        "GlassesConfidence": 1,
        "Sharpness": 0.8870000243186951,
        "FigureClusterId": "figure-cluster-id-unavailable",
        "FaceQuality": 0.8289999961853027,
        "Attractive": 0.12099999934434891,
        "AgeSD": 5,
        "Glasses": "none",
        "FigureConfidence": 0.9990000128746033,
        "Hat": "hat"
    }
    ]
}

权限说明

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限，需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。

系统权限：AliyunOSSReadOnlyAccess和AliyunIMMFullAccess
关于为RAM用户授权的具体操作，请参见为RAM用户授权。
自定义权限：oss:ProcessImm和ram:GetRole
为RAM用户授予自定义权限时，您需要先创建对应的自定义权限，然后为RAM用户授权。具体操作，请参见为RAM用户授予自定义的权限策略。

计费说明

在文档预览过程中，由于调用了 IMM 服务，会同时在 OSS 和 IMM 两侧产生计费项。具体说明如下：

OSS 侧：将产生以下计费项，详细定价请参见OSS产品定价：

API	计费项	说明
GetObject	GET 类型请求	根据成功的请求次数计算请求费用。
	外网流出流量费用	如果是通过外网Endpoint（示例值oss-cn-hangzhou.aliyuncs.com）或者传输加速Endpoint（示例值oss-accelerate.aliyuncs.com）调用GetObject接口时，会产生外网流出流量费用，根据数据容量大小计费。
	低频访问数据取回容量	如果取回的数据是低频访问数据，会产生低频访问数据取回容量的费用，按数据取回量计费。
	传输加速	如果开启了传输加速功能且使用传输加速域名访问您的Bucket会产生传输加速费用，根据数据容量大小计费。

IMM 侧：将产生以下计费项，详细定价请参见IMM计费项：
API
计费项
说明
DetectImageFaces
人脸检测
人脸识别会产生人脸检测费用。