# face-api.js 本地化依赖（h5/vendor/faceapi/）

测肤 H5 的人脸角度检测（yaw / pitch / roll）依赖 face-api.js 及其模型。
所有文件均已本地化，**运行时零外部请求**（不依赖任何 CDN），保证微信 webview /
iOS Safari 在弱网、内网部署或 CDN 不可达场景下仍可稳定加载。

## 来源与版本

| 文件 | 来源 | 版本 / 分支 |
| --- | --- | --- |
| `face-api.js` | https://cdn.jsdelivr.net/npm/face-api.js@0.22.2/dist/face-api.js | 0.22.2（UMD 未压缩构建，0.22.2 未提供 min 版） |
| `models/tiny_face_detector_model-*` | https://github.com/justadudewhohacks/face-api.js-models （`tiny_face_detector/` 目录，raw master） | master |
| `models/face_landmark_68_model-*` | 同上（`face_landmark_68/` 目录，raw master） | master |

下载时间：2026-09-26。

## 许可证

- **face-api.js**（库与模型均出自该项目）以 **MIT License** 发布，
  版权归 Vincent Mühler (justadudewhohacks) 所有。
  许可证全文见 https://github.com/justadudewhohacks/face-api.js/blob/master/LICENSE 。
- `face-api.js` UMD 构建内联打包了 TensorFlow.js（tfjs-core / tfjs-converter 等），
  该部分为 Apache License 2.0，Copyright 2020 Google LLC（见 `face-api.js` 文件头注释）。
  MIT 与 Apache-2.0 均允许商用及再分发，保留版权声明即可。

## 文件清单与体积

| 路径 | 体积 | 说明 |
| --- | --- | --- |
| `face-api.js` | 859,250 B（≈839 KB） | UMD 构建，浏览器全局变量 `faceapi` |
| `models/tiny_face_detector_model-weights_manifest.json` | 2,953 B | 轻量人脸检测器权重清单（19 个张量） |
| `models/tiny_face_detector_model-shard1` | 193,321 B（≈189 KB） | 检测器权重分片 |
| `models/face_landmark_68_model-weights_manifest.json` | 7,889 B | 68 点特征模型权重清单（49 个张量） |
| `models/face_landmark_68_model-shard1` | 356,840 B（≈349 KB） | 68 点特征模型权重分片 |

合计约 1.4 MB。已用 Node 校验：manifest JSON 可解析、`paths` 引用的 shard 均存在且非空。

## 用法

```html
<script src="vendor/faceapi/face-api.js"></script>
<script>
  const MODEL_URL = 'vendor/faceapi/models';
  await faceapi.nets.tinyFaceDetector.loadFromUri(MODEL_URL);
  await faceapi.nets.faceLandmark68Net.loadFromUri(MODEL_URL);
  // 检测 + 68 特征点：
  // const det = await faceapi
  //   .detectSingleFace(video, new faceapi.TinyFaceDetectorOptions({ inputSize: 320, scoreThreshold: 0.4 }))
  //   .withFaceLandmarks();
</script>
```

姿态估算（yaw/pitch/roll）由 `js/head-pose.js` 基于 68 特征点做纯几何计算，
不依赖 face-api 的内部 API，可独立单测。

## 为什么本地化

1. 主战场是 iOS Safari + 微信 webview，弱网/CDN 抖动会直接导致检测功能不可用；
2. 内网 / 私有化部署时外网 CDN 可能完全不可达；
3. 锁定 0.22.2 版本，避免上游变更引发回归。