你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

调用检测 API

项目
02/14/2024

注意

为了支持我们负责任的 AI 原则，基于资格和使用标准对人脸服务访问进行限制。人脸服务仅适用于 Microsoft 托管客户和合作伙伴。使用人脸识别引入表单来申请访问。有关详细信息，请参阅人脸受限访问页面。

注意

Microsoft 已停用面部识别功能，这些功能可用于尝试推断情绪状态和身份属性，如果滥用，可能会使人们遭受刻板印象、歧视或受到不公平的拒绝服务攻击。这些包括预测情绪、性别、年龄、微笑、面部毛发、头发和化妆的能力。在此处阅读有关此决定的更多信息。

本指南演示如何使用人脸检测 API 从给定图像中提取属性。你将了解配置此 API 的行为以满足你的需求的不同方法。

本指南中的代码片段是使用 Azure AI 人脸客户端库以 C# 编写的。同样的功能通过 REST API 提供。

设置

本指南假设你已使用人脸密钥和终结点 URL 构造了名为 faceClient 的 FaceClient 对象。有关如何设置此功能的说明，请按照其中一个快速入门操作。

提交服务数据

要找到人脸并获得它们在图像中的位置，请调用 DetectWithUrlAsync 或 DetectWithStreamAsync 方法。 DetectWithUrlAsync 接受 URL 字符串作为输入，DetectWithStreamAsync 接受图像的原始字节流作为输入。

IList<DetectedFace> faces = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, detectionModel: DetectionModel.Detection03);

该服务会返回一个 DetectedFace 对象，你可以查询下面指定的不同类型的信息。

有关如何分析人脸位置和维度的信息，请参阅 FaceRectangle。通常情况下，此矩形包含眼睛、眉毛、鼻子和嘴巴，不一定包括头顶、耳朵和下巴。若要使用人脸矩形来裁剪整个头部或获取中景肖像，应朝每个方向拉伸矩形。

确定如何处理数据

本指南重点介绍有关检测调用的具体信息，例如，可以传递哪些参数，以及可对返回的数据执行哪些操作。建议仅查询所需功能。每个操作需要更多时间才能完成。

获取人脸 ID

如果你将 returnFaceId 参数设置为 true（仅限已批准的客户），则你可以获取每张人脸的唯一 ID，你可以在稍后的人脸识别任务中使用该 ID。

foreach (var face in faces)
{
    string id = face.FaceId.ToString();
    FaceRectangle rect = face.FaceRectangle;
}

可选的 faceIdTimeToLive 参数指定人脸 ID 在服务器上应存储的时长（以秒为单位）。此时间到期后，将删除人脸 ID。默认值为 86400（24 小时）。

获取人脸特征点

人脸特征点是人脸上的一组易于查找的点，例如瞳孔或鼻尖。将 detectionModel 参数设置为 DetectionModel.Detection01，并将 returnFaceLandmarks 参数设置为 true，可获取人脸特征点数据。

// Note DetectionModel.Detection02 cannot be used with returnFaceLandmarks.
IList<DetectedFace> faces2 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, returnFaceLandmarks: true, detectionModel: DetectionModel.Detection01);

获取人脸特性

除了人脸矩形和特征点以外，人脸检测 API 还可以分析人脸的几个概念特性。如需完整列表，请参阅人脸属性概念部分。

要分析人脸特性，可将 detectionModel 参数设置为 DetectionModel.Detection01，并将 returnFaceAttributes 参数设置为 FaceAttributeType Enum 值列表。

var requiredFaceAttributes = new FaceAttributeType[] {
    FaceAttributeType.HeadPose,
    FaceAttributeType.Glasses,
    FaceAttributeType.QualityForRecognition
};
// Note DetectionModel.Detection02 cannot be used with returnFaceAttributes.
var faces3 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, returnFaceAttributes: requiredFaceAttributes, detectionModel: DetectionModel.Detection01, recognitionModel: RecognitionModel.Recognition04);

获取服务结果

人脸特征点结果

以下代码演示如何检索鼻子和瞳孔的位置：

foreach (var face in faces2)
{
    var landmarks = face.FaceLandmarks;

    double noseX = landmarks.NoseTip.X;
    double noseY = landmarks.NoseTip.Y;

    double leftPupilX = landmarks.PupilLeft.X;
    double leftPupilY = landmarks.PupilLeft.Y;

    double rightPupilX = landmarks.PupilRight.X;
    double rightPupilY = landmarks.PupilRight.Y;

人脸特征点数据还可用于准确计算人脸的方向。例如，可以将人脸的旋转角定义为从嘴巴中心到眼睛中心的矢量。以下代码计算此矢量：

    var upperLipBottom = landmarks.UpperLipBottom;
    var underLipTop = landmarks.UnderLipTop;

    var centerOfMouth = new Point(
        (upperLipBottom.X + underLipTop.X) / 2,
        (upperLipBottom.Y + underLipTop.Y) / 2);

    var eyeLeftInner = landmarks.EyeLeftInner;
    var eyeRightInner = landmarks.EyeRightInner;

    var centerOfTwoEyes = new Point(
        (eyeLeftInner.X + eyeRightInner.X) / 2,
        (eyeLeftInner.Y + eyeRightInner.Y) / 2);

    Vector faceDirection = new Vector(
        centerOfTwoEyes.X - centerOfMouth.X,
        centerOfTwoEyes.Y - centerOfMouth.Y);
}

知道人脸的方向后，可以旋转矩形人脸框，使人脸更适当地对齐。若要裁剪图像中的人脸，可以通过编程方式旋转图像，使人脸始终正面显示。

人脸特性结果

下面的代码演示如何检索在原始调用中请求的人脸特性数据。

foreach (var face in faces3)
{
    var attributes = face.FaceAttributes;
    var headPose = attributes.HeadPose;
    var glasses = attributes.Glasses;
    var qualityForRecognition = attributes.QualityForRecognition;
}

若要详细了解每个属性，请参阅人脸检测和属性概念指南。

后续步骤

本指南介绍了如何使用人脸检测和分析的各项功能。接下来，将这些功能集成到应用中，以添加用户的人脸数据。

教程：向人脸服务添加用户