face-api.js

基于 tensorflow.js core（tensorflow/tfjs-core）实现的浏览器和 Node.js 的 JavaScript 人脸识别 API

点击这里查看实时演示！

教程

• face-api.js —— 使用 tensorflow.js 在浏览器中进行人脸识别的 JavaScript API
• 使用 face-api.js 的 MTCNN 人脸检测器进行实时 JavaScript 人脸跟踪和人脸识别
• 实时网络摄像头人脸检测与情绪识别 - 视频
• 使用 JavaScript 进行简单的人脸识别教程 - 视频
• 在 Vue.js 和 Electron 中使用 face-api.js
• 为人物添加面具 - Gant Laborde 在 Learn with Jason 上的分享

目录

• 功能特性
• 运行示例
• 适用于浏览器的 face-api.js
• 适用于 Node.js 的 face-api.js
• 使用方法
  • 加载模型
  • 高级 API
  • 显示检测结果
  • 人脸检测选项
  • 工具类
  • 其他实用工具
• 可用模型
  • 人脸检测
  • 人脸关键点检测
  • 人脸识别
  • 面部表情识别
  • 年龄估计与性别识别
• API 文档

功能特性

人脸识别

人脸关键点检测

面部表情识别

年龄估计与性别识别

运行示例

克隆仓库：

git clone https://github.com/justadudewhohacks/face-api.js.git

运行浏览器示例

cd face-api.js/examples/examples-browser
npm i
npm start

打开 http://localhost:3000/。

运行 Node.js 示例

cd face-api.js/examples/examples-nodejs
npm i

现在可以使用 ts-node 运行其中一个示例：

ts-node faceDetection.ts

或者直接编译并用 node 运行：

tsc faceDetection.ts
node faceDetection.js

适用于浏览器的 face-api.js

只需从 dist/face-api.js 引入最新脚本即可。

或者通过 npm 安装：

npm i face-api.js

适用于 Node.js 的 face-api.js

我们可以通过 polyfill 一些浏览器特有的对象，如 HTMLImageElement、HTMLCanvasElement 和 ImageData，在 Node.js 环境中使用等效的 API。最简单的方法是安装 node-canvas 包。

另外，你也可以直接从图像数据构造张量，并将张量作为输入传递给 API。

此外，建议安装 @tensorflow/tfjs-node（非必需，但强烈推荐），它通过编译并与原生 TensorFlow C++ 库绑定，可显著提升性能：

npm i face-api.js canvas @tensorflow/tfjs-node

接下来，我们只需对环境进行 monkey patch，以使用这些 polyfill：

// 导入 Node.js 绑定到原生 TensorFlow，
// 虽然不是必需的，但会极大地加速处理（需要 Python）
import '@tensorflow/tfjs-node';

// 实现 Node.js 对 HTMLCanvasElement、HTMLImageElement 和 ImageData 的封装
import * as canvas from 'canvas';

import * as faceapi from 'face-api.js';

// 对 Node.js 环境进行补丁，我们需要提供 HTMLCanvasElement 和 HTMLImageElement 的实现
const { Canvas, Image, ImageData } = canvas
faceapi.env.monkeyPatch({ Canvas, Image, ImageData })

开始使用

加载模型

所有全局神经网络实例都通过 faceapi.nets 导出：

console.log(faceapi.nets)
// ageGenderNet
// faceExpressionNet
// faceLandmark68Net
// faceLandmark68TinyNet
// faceRecognitionNet
// ssdMobilenetv1
// tinyFaceDetector
// tinyYolov2

要加载一个模型，你需要提供对应的 manifest.json 文件以及模型权重文件（分片）作为资源。只需将它们复制到你的 public 或 assets 文件夹中。模型的 manifest.json 和分片文件必须位于同一目录下，或可通过相同的路径访问。

假设模型存放在 public/models 目录中：

await faceapi.nets.ssdMobilenetv1.loadFromUri('/models')
// 对其他模型同样操作：
// await faceapi.nets.faceLandmark68Net.loadFromUri('/models')
// await faceapi.nets.faceRecognitionNet.loadFromUri('/models')
// ...

在 Node.js 环境中，你还可以直接从磁盘加载模型：

await faceapi.nets.ssdMobilenetv1.loadFromDisk('./models')

你也可以从 tf.NamedTensorMap 加载模型：

await faceapi.nets.ssdMobilenetv1.loadFromWeightMap(weightMap)

此外，你还可以创建自己的神经网络实例：

const net = new faceapi.SsdMobilenetv1()
await net.loadFromUri('/models')

你还可以将权重作为 Float32Array 加载（如果你希望使用未压缩的模型）：

// 使用 fetch
net.load(await faceapi.fetchNetWeights('/models/face_detection_model.weights'))

// 使用 axios
const res = await axios.get('/models/face_detection_model.weights', { responseType: 'arraybuffer' })
const weights = new Float32Array(res.data)
net.load(weights)

高级 API

以下示例中，input 可以是 HTML 的 <img>、<video> 或 <canvas> 元素，也可以是这些元素的 ID。

<img id="myImg" src="images/example.png" />
<video id="myVideo" src="media/example.mp4" />
<canvas id="myCanvas" />

const input = document.getElementById('myImg')
// const input = document.getElementById('myVideo')
// const input = document.getElementById('myCanvas')
// 或者直接：
// const input = 'myImg'

检测人脸

检测图像中的所有人脸。返回 Array<FaceDetection>：

const detections = await faceapi.detectAllFaces(input)

检测图像中置信度最高的单张人脸。返回 FaceDetection | undefined：

const detection = await faceapi.detectSingleFace(input)

默认情况下，detectAllFaces 和 detectSingleFace 使用 SSD MobileNet V1 人脸检测器。你可以通过传递相应的选项对象来指定使用的检测器：

const detections1 = await faceapi.detectAllFaces(input, new faceapi.SsdMobilenetv1Options())
const detections2 = await faceapi.detectAllFaces(input, new faceapi.TinyFaceDetectorOptions())

你可以根据 这里 所示调整每个检测器的选项。

检测 68 个面部关键点

在完成人脸检测后，我们还可以为每个检测到的人脸预测面部关键点，具体如下：

检测图像中的所有人脸，并为每个检测到的人脸计算 68 个关键点。返回 Array<WithFaceLandmarks<WithFaceDetection<{}>>>：

const detectionsWithLandmarks = await faceapi.detectAllFaces(input).withFaceLandmarks()

检测图像中置信度最高的单张人脸，并为其计算 68 个面部关键点。返回 WithFaceLandmarks<WithFaceDetection<{}>> | undefined：

const detectionWithLandmarks = await faceapi.detectSingleFace(input).withFaceLandmarks()

你也可以选择使用小型模型而不是默认模型：

const useTinyModel = true
const detectionsWithLandmarks = await faceapi.detectAllFaces(input).withFaceLandmarks(useTinyModel)

计算人脸描述符

在完成人脸检测和面部关键点预测后，可以为每个人脸计算描述符，具体如下：

检测图像中的所有人脸，并为每个检测到的人脸计算 68 个关键点。返回 Array<WithFaceDescriptor<WithFaceLandmarks<WithFaceDetection<{}>>>>：

const results = await faceapi.detectAllFaces(input).withFaceLandmarks().withFaceDescriptors()

检测图像中置信度最高的单张人脸，并为其计算 68 个关键点和人脸描述符。返回 WithFaceDescriptor<WithFaceLandmarks<WithFaceDetection<{}>>> | undefined：

const result = await faceapi.detectSingleFace(input).withFaceLandmarks().withFaceDescriptor()

识别面部表情

可以对检测到的人脸进行面部表情识别，具体如下：

检测图像中的所有人脸，并识别每个人脸的面部表情。返回 Array<WithFaceExpressions<WithFaceLandmarks<WithFaceDetection<{}>>>>：

const detectionsWithExpressions = await faceapi.detectAllFaces(input).withFaceLandmarks().withFaceExpressions()

检测图像中置信度最高的单张人脸，并识别该人脸的面部表情。返回 WithFaceExpressions<WithFaceLandmarks<WithFaceDetection<{}>>> | undefined：

const detectionWithExpressions = await faceapi.detectSingleFace(input).withFaceLandmarks().withFaceExpressions()

你也可以跳过 .withFaceLandmarks()，这样会跳过人脸对齐步骤（准确性可能会降低）：

检测所有人脸而不进行人脸对齐，并识别每个人脸的面部表情。返回 Array<WithFaceExpressions<WithFaceDetection<{}>>>：

const detectionsWithExpressions = await faceapi.detectAllFaces(input).withFaceExpressions()

检测置信度最高的单张人脸，不进行人脸对齐，并识别该人脸的面部表情。返回 WithFaceExpressions<WithFaceDetection<{}>> | undefined：

const detectionWithExpressions = await faceapi.detectSingleFace(input).withFaceExpressions()

年龄估计与性别识别

可以从检测到的人脸中进行年龄估计和性别识别，具体方法如下：

检测图像中的所有人脸 + 估计每个脸的年龄并识别性别。返回 Array<WithAge<WithGender<WithFaceLandmarks<WithFaceDetection<{}>>>>>：

const detectionsWithAgeAndGender = await faceapi.detectAllFaces(input).withFaceLandmarks().withAgeAndGender()

检测图像中置信度最高的那张人脸 + 估计该脸的年龄并识别性别。返回 WithAge<WithGender<WithFaceLandmarks<WithFaceDetection<{}>>>> | undefined：

const detectionWithAgeAndGender = await faceapi.detectSingleFace(input).withFaceLandmarks().withAgeAndGender()

你也可以跳过 .withFaceLandmarks()，这样就会跳过人脸对齐步骤（准确性会稍差）：

检测所有未进行人脸对齐的人脸 + 估计每个脸的年龄并识别性别。返回 Array<WithAge<WithGender<WithFaceDetection<{}>>>>：

const detectionsWithAgeAndGender = await faceapi.detectAllFaces(input).withAgeAndGender()

检测未进行人脸对齐的置信度最高的那张人脸 + 估计该脸的年龄并识别性别。返回 WithAge<WithGender<WithFaceDetection<{}>>> | undefined：

const detectionWithAgeAndGender = await faceapi.detectSingleFace(input).withAgeAndGender()

任务组合

任务可以按以下方式组合：

// 所有人脸
await faceapi.detectAllFaces(input)
await faceapi.detectAllFaces(input).withFaceExpressions()
await faceapi.detectAllFaces(input).withFaceLandmarks()
await faceapi.detectAllFaces(input).withFaceLandmarks().withFaceExpressions()
await faceapi.detectAllFaces(input).withFaceLandmarks().withFaceExpressions().withFaceDescriptors()
await faceapi.detectAllFaces(input).withFaceLandmarks().withAgeAndGender().withFaceDescriptors()
await faceapi.detectAllFaces(input).withFaceLandmarks().withFaceExpressions().withAgeAndGender().withFaceDescriptors()

// 单张人脸
await faceapi.detectSingleFace(input)
await faceapi.detectSingleFace(input).withFaceExpressions()
await faceapi.detectSingleFace(input).withFaceLandmarks()
await faceapi.detectSingleFace(input).withFaceLandmarks().withFaceExpressions()
await faceapi.detectSingleFace(input).withFaceLandmarks().withFaceExpressions().withFaceDescriptor()
await faceapi.detectSingleFace(input).withFaceLandmarks().withAgeAndGender().withFaceDescriptor()
await faceapi.detectSingleFace(input).withFaceLandmarks().withFaceExpressions().withAgeAndGender().withFaceDescriptor()

通过描述符匹配进行人脸识别

要进行人脸识别，可以使用 faceapi.FaceMatcher 将参考人脸描述符与查询人脸描述符进行比较。

首先，我们用参考数据初始化 FaceMatcher。例如，我们可以简单地在 referenceImage 中检测人脸，并将检测到的人脸描述符与后续图像中的人脸进行匹配：

const results = await faceapi
  .detectAllFaces(referenceImage)
  .withFaceLandmarks()
  .withFaceDescriptors()

if (!results.length) {
  return
}

// 使用参考图像的检测结果自动分配标签，创建 FaceMatcher
const faceMatcher = new faceapi.FaceMatcher(results)

现在我们可以识别 queryImage1 中出现的人脸：

const singleResult = await faceapi
  .detectSingleFace(queryImage1)
  .withFaceLandmarks()
  .withFaceDescriptor()

if (singleResult) {
  const bestMatch = faceMatcher.findBestMatch(singleResult.descriptor)
  console.log(bestMatch.toString())
}

或者我们可以识别 queryImage2 中出现的所有人脸：

const results = await faceapi
  .detectAllFaces(queryImage2)
  .withFaceLandmarks()
  .withFaceDescriptors()

results.forEach(fd => {
  const bestMatch = faceMatcher.findBestMatch(fd.descriptor)
  console.log(bestMatch.toString())
})

你也可以按照以下方式创建带标签的参考描述符：

const labeledDescriptors = [
  new faceapi.LabeledFaceDescriptors(
    'obama',
    [descriptorObama1, descriptorObama2]
  ),
  new faceapi.LabeledFaceDescriptors(
    'trump',
    [descriptorTrump]
  )
]

const faceMatcher = new faceapi.FaceMatcher(labeledDescriptors)

显示检测结果

准备叠加画布：

const displaySize = { width: input.width, height: input.height }
// 将叠加画布调整为输入图像的尺寸
const canvas = document.getElementById('overlay')
faceapi.matchDimensions(canvas, displaySize)

face-api.js 预定义了一些高级绘图函数，你可以直接使用：

/* 显示检测到的人脸边界框 */
const detections = await faceapi.detectAllFaces(input)
// 如果显示的图像尺寸与原始图像不同，则调整检测框的大小
const resizedDetections = faceapi.resizeResults(detections, displaySize)
// 将检测结果绘制到画布上
faceapi.draw.drawDetections(canvas, resizedDetections)

/* 显示人脸关键点 */
const detectionsWithLandmarks = await faceapi
  .detectAllFaces(input)
  .withFaceLandmarks()
// 如果显示的图像尺寸与原始图像不同，则调整检测框和关键点的大小
const resizedResults = faceapi.resizeResults(detectionsWithLandmarks, displaySize)
// 将检测结果绘制到画布上
faceapi.draw.drawDetections(canvas, resizedResults)
// 将关键点绘制到画布上
faceapi.draw.drawFaceLandmarks(canvas, resizedResults)


/* 显示面部表情结果 */
const detectionsWithExpressions = await faceapi
  .detectAllFaces(input)
  .withFaceLandmarks()
  .withFaceExpressions()
// 如果显示的图像尺寸与原始图像不同，则调整检测框和关键点的大小
const resizedResults = faceapi.resizeResults(detectionsWithExpressions, displaySize)
// 将检测结果绘制到画布上
faceapi.draw.drawDetections(canvas, resizedResults)
// 在画布上绘制一个显示最低置信度面部表情的文本框
const minProbability = 0.05
faceapi.draw.drawFaceExpressions(canvas, resizedResults, minProbability)

你还可以绘制带有自定义文本的矩形框（DrawBox）：

const box = { x: 50, y: 50, width: 100, height: 100 }
// 参见下方的 DrawBoxOptions
const drawOptions = {
  label: '你好，我是一个矩形框！',
  lineWidth: 2
}
const drawBox = new faceapi.draw.DrawBox(box, drawOptions)
drawBox.draw(document.getElementById('myCanvas'))

DrawBox 绘图选项：

export interface IDrawBoxOptions {
  boxColor?: string
  lineWidth?: number
  drawLabelOptions?: IDrawTextFieldOptions
  label?: string
}

最后，你还可以绘制自定义文本框（DrawTextField）：

const text = [
  '这是一行文字！',
  '这是另一行文字！'
]
const anchor = { x: 200, y: 200 }
// 参见下方的 DrawTextField
const drawOptions = {
  anchorPosition: 'TOP_LEFT',
  backgroundColor: 'rgba(0, 0, 0, 0.5)'
}
const drawBox = new faceapi.draw.DrawTextField(text, anchor, drawOptions)
drawBox.draw(document.getElementById('myCanvas'))

DrawTextField 绘图选项：

export interface IDrawTextFieldOptions {
  anchorPosition?: AnchorPosition
  backgroundColor?: string
  fontColor?: string
  fontSize?: number
  fontStyle?: string
  padding?: number
}

export enum AnchorPosition {
  TOP_LEFT = 'TOP_LEFT',
  TOP_RIGHT = 'TOP_RIGHT',
  BOTTOM_LEFT = 'BOTTOM_LEFT',
  BOTTOM_RIGHT = 'BOTTOM_RIGHT'
}

人脸检测选项

SsdMobilenetv1Options

export interface ISsdMobilenetv1Options {
  // 最小置信度阈值
  // 默认：0.5
  minConfidence?: number

  // 返回的最大人脸数量
  // 默认：100
  maxResults?: number
}

// 示例
const options = new faceapi.SsdMobilenetv1Options({ minConfidence: 0.8 })

TinyFaceDetectorOptions

export interface ITinyFaceDetectorOptions {
  // 图像处理时的尺寸，越小速度越快，
  // 但对较小人脸的检测精度较低，必须能被32整除，
  // 常用尺寸有128、160、224、320、416、512、608等。
  // 对于通过摄像头进行人脸跟踪，建议使用较小尺寸，
  // 比如128或160；而检测较小人脸时则应使用较大尺寸，
  // 比如512或608。
  // 默认：416
  inputSize?: number

  // 最小置信度阈值
  // 默认：0.5
  scoreThreshold?: number
}

// 示例
const options = new faceapi.TinyFaceDetectorOptions({ inputSize: 320 })

工具类

IBox

export interface IBox {
  x: number
  y: number
  width: number
  height: number
}

IFaceDetection

export interface IFaceDetection {
  score: number
  box: Box
}

IFaceLandmarks

export interface IFaceLandmarks {
  positions: Point[]
  shift: Point
}

WithFaceDetection

export type WithFaceDetection<TSource> = TSource & {
  detection: FaceDetection
}

WithFaceLandmarks

export type WithFaceLandmarks<TSource> = TSource & {
  unshiftedLandmarks: FaceLandmarks
  landmarks: FaceLandmarks
  alignedRect: FaceDetection
}

WithFaceDescriptor

export type WithFaceDescriptor<TSource> = TSource & {
  descriptor: Float32Array
}

WithFaceExpressions

export type WithFaceExpressions<TSource> = TSource & {
  expressions: FaceExpressions
}

WithAge

export type WithAge<TSource> = TSource & {
  age: number
}

WithGender

export type WithGender<TSource> = TSource & {
  gender: Gender
  genderProbability: number
}

export enum Gender {
  FEMALE = 'female',
  MALE = 'male'
}

其他实用工具

使用低级 API

除了使用高级 API 外，你还可以直接调用各个神经网络的前向方法：

const detections1 = await faceapi.ssdMobilenetv1(input, options)
const detections2 = await faceapi.tinyFaceDetector(input, options)
const landmarks1 = await faceapi.detectFaceLandmarks(faceImage)
const landmarks2 = await faceapi.detectFaceLandmarksTiny(faceImage)
const descriptor = await faceapi.computeFaceDescriptor(alignedFaceImage)

提取图像区域的画布

const regionsToExtract = [
  new faceapi.Rect(0, 0, 100, 100)
]
// extractFaces 实际上用于从边界框中提取人脸区域，
// 但你也可以用它来提取任何其他区域。
const canvases = await faceapi.extractFaces(input, regionsToExtract)

欧几里得距离

// 用于计算两个面部描述符之间的欧几里得距离
const dist = faceapi.euclideanDistance([0, 0], [0, 10])
console.log(dist) // 10

获取人脸关键点和轮廓

const landmarkPositions = landmarks.positions

// 或者获取单个轮廓的关键点位置，
// 仅适用于68点人脸关键点（FaceLandmarks68）
const 下颌轮廓 = landmarks.getJawOutline()
const 鼻子 = landmarks.getNose()
const 嘴巴 = landmarks.getMouth()
const 左眼 = landmarks.getLeftEye()
const 右眼 = landmarks.getRightEye()
const 左眉 = landmarks.getLeftEyeBrow()
const 右眉 = landmarks.getRightEyeBrow()

从 URL 获取并显示图片

<img id="myImg" src="">

const image = await faceapi.fetchImage('/images/example.png')

console.log(image instanceof HTMLImageElement) // 输出: true

// 显示获取到的图片内容
const myImg = document.getElementById('myImg')
myImg.src = image.src

获取 JSON 数据

const json = await faceapi.fetchJson('/files/example.json')

创建图片选择器

<img id="myImg" src="">
<input id="myFileUpload" type="file" onchange="uploadImage()" accept=".jpg, .jpeg, .png">

async function uploadImage() {
  const imgFile = document.getElementById('myFileUpload').files[0]
  // 从 Blob 对象创建 HTMLImageElement
  const img = await faceapi.bufferToImage(imgFile)
  document.getElementById('myImg').src = img.src
}

从图片或视频元素创建 Canvas 元素

<img id="myImg" src="images/example.png" />
<video id="myVideo" src="media/example.mp4" />

const canvas1 = faceapi.createCanvasFromMedia(document.getElementById('myImg'))
const canvas2 = faceapi.createCanvasFromMedia(document.getElementById('myVideo'))

可用模型

人脸检测模型

SSD MobileNet V1

本项目实现了一个基于 MobileNetV1 的 SSD（单次多框检测器）用于人脸检测。该神经网络会计算图像中每张人脸的位置，并返回包含置信度分数的边界框。此检测器旨在高精度地定位人脸边界框，而非追求极低的推理时间。量化后的模型大小约为 5.4 MB（ssd_mobilenetv1_model）。

该人脸检测模型在 WIDERFACE 数据集 上训练，权重由 yeephycho 在 此仓库 中提供。

Tiny 人脸检测器

Tiny 人脸检测器是一种性能优异、实时性很强的人脸检测器，相比 SSD MobileNet V1 检测器速度更快、体积更小、资源消耗更低，但对小人脸的检测效果稍逊一筹。该模型非常适合移动设备和资源受限的客户端使用，因此在这些场景下应优先选择它。量化后的模型大小仅为 190 KB（tiny_face_detector_model）。

该检测器基于一个约 1.4 万张带边界框标注的自定义数据集进行训练。此外，该模型被优化为预测能够完全覆盖面部特征点的边界框，因此与后续的人脸关键点检测结合使用时，通常能获得比 SSD MobileNet V1 更好的结果。

该模型本质上是 Tiny YOLO V2 的更小型版本，用深度可分离卷积替换了 YOLO 中的常规卷积。YOLO 是全卷积网络，因此可以轻松适应不同输入图像尺寸，在准确性和性能（推理时间）之间进行权衡。

68 点人脸关键点检测模型

本包实现了一种轻量级、快速且准确的 68 点人脸关键点检测器。默认模型大小仅为 350 KB（face_landmark_68_model），而小型模型仅为 80 KB（face_landmark_68_tiny_model）。这两个模型均采用了深度可分离卷积和密集连接块的设计思想。它们是在包含约 3.5 万张标注了 68 个关键点的人脸图像的数据集上训练而成的。

人脸识别模型

对于人脸识别任务，本项目实现了一个类似 ResNet-34 的架构，可以从任意一张人脸图像中计算出一个包含 128 个值的特征向量（即人脸描述符），用于表征一个人的面部特征。该模型并不局限于训练数据集中的人脸，因此可用于识别任何人，例如您自己。通过比较两张人脸的描述符，例如计算欧几里得距离或其他分类器，即可判断两人的相似程度。

该神经网络等同于 face-recognition.js 中使用的 FaceRecognizerNet，以及 dlib 人脸识别示例中所用的网络。权重由 davisking 训练，该模型在 LFW（Labeled Faces in the Wild）人脸识别基准测试中的预测准确率达到 99.38%。

量化后的模型大小约为 6.2 MB（face_recognition_model）。

人脸表情识别模型

该表情识别模型轻量、快速，且具有合理的准确性。模型大小约为 310 KB，采用深度可分离卷积和密集连接块结构。它基于公开数据集中的多种图像以及从网上抓取的图像进行训练。需要注意的是，佩戴眼镜可能会影响预测结果的准确性。

年龄和性别识别模型

年龄和性别识别模型是一个多任务网络，包含特征提取层、年龄回归层和性别分类器。该模型大小约为 420 KB，其特征提取部分采用了与 Xception 极为相似的小型架构。

该模型分别在以下数据库上进行了训练和测试，每次采用 80/20 的训练/测试划分：UTK、FGNET、Chalearn、Wiki、IMDB*、CACD*、MegaAge、MegaAge-Asian。其中“*”表示这些数据库经过算法清理，因为原始数据集噪声较大。

总体测试结果

总平均年龄误差（MAE）：4.54

性别识别准确率：95%

各数据库的测试结果

“-”表示这些数据库中没有性别标签。

数据库	UTK	FGNET	Chalearn	Wiki	IMDB*	CACD*	MegaAge	MegaAge-Asian
MAE	5.25	4.23	6.24	6.54	3.63	3.20	6.23	4.21
性别准确率	0.93	-	0.94	0.95	-	0.97	-	-

不同年龄类别组别的测试结果

年龄范围	0 - 3	4 - 8	9 - 18	19 - 28	29 - 40	41 - 60	60 - 80	80+
MAE	1.52	3.06	4.82	4.99	5.43	4.94	6.17	9.91
性别准确率	0.69	0.80	0.88	0.96	0.97	0.97	0.96	0.9

face-api.js 快速上手指南

face-api.js 是一个基于 tensorflow.js 构建的 JavaScript 人脸识别 API，适用于浏览器和 Node.js 环境。它支持人脸检测、关键点定位、人脸识别、表情识别以及年龄和性别预测。

环境准备

系统要求

• 浏览器端：现代浏览器（Chrome, Firefox, Edge 等），需支持 WebGL。
• Node.js 端：Node.js v12+，推荐 v14 或更高版本。
• 依赖项：
  • 浏览器端：无需额外系统依赖。
  • Node.js 端：需安装 canvas 包以模拟浏览器图像对象；强烈建议安装 @tensorflow/tfjs-node 以提升性能（需要 Python 环境用于编译原生模块）。

模型文件

使用前需下载预训练模型文件（包含 .json 清单文件和 .weights 权重分片文件）。你可以从官方示例仓库的 models 目录获取，或自行训练。

安装步骤

1. 初始化项目

npm init -y

2. 安装核心依赖

npm i face-api.js

3. Node.js 环境额外依赖（仅服务端使用）

为了在 Node.js 中运行，需要 polyfill 浏览器对象并加速计算：

# 推荐使用淘宝镜像加速安装
npm i canvas @tensorflow/tfjs-node --registry=https://registry.npmmirror.com

基本使用

以下示例展示如何在浏览器中最简单地加载模型并检测人脸。

1. 引入库

如果你通过 npm 安装并使用打包工具（如 Webpack/Vite）：

import * as faceapi from 'face-api.js';

或者直接在 HTML 中通过 CDN 引入：

<script src="https://cdn.jsdelivr.net/npm/face-api.js@0.22.2/dist/face-api.min.js"></script>

2. 加载模型

将下载的模型文件放置在项目的 public/models 目录下。

// 加载人脸检测模型（其他模型同理）
await faceapi.nets.ssdMobilenetv1.loadFromUri('/models');
// await faceapi.nets.faceLandmark68Net.loadFromUri('/models');
// await faceapi.nets.faceRecognitionNet.loadFromUri('/models');

注：在 Node.js 环境中，请使用 loadFromDisk('./models')。

3. 执行检测

假设你有一个 ID 为 myImg 的图片元素：

<img id="myImg" src="images/example.png" />

执行以下代码进行检测：

const input = document.getElementById('myImg');

// 检测所有人脸
const detections = await faceapi.detectAllFaces(input);

// 检测置信度最高的一张人脸
const detection = await faceapi.detectSingleFace(input);

console.log(detections);

4. 进阶：链式调用（检测 + 关键点 + 描述子）

face-api.js 支持流畅的链式 API，可一次性获取人脸位置、68 个关键点坐标及人脸特征向量：

const results = await faceapi
  .detectAllFaces(input)
  .withFaceLandmarks()
  .withFaceDescriptors();

console.log(results);

Node.js 特殊配置

如果在 Node.js 环境下运行，必须在代码开头进行环境补丁（Monkey Patch）：

import '@tensorflow/tfjs-node';
import * as canvas from 'canvas';
import * as faceapi from 'face-api.js';

// 补丁环境，提供 HTMLCanvasElement 等实现
const { Canvas, Image, ImageData } = canvas;
faceapi.env.monkeyPatch({ Canvas, Image, ImageData });

// 之后即可正常使用 loadFromDisk 和检测 API