简介：面向JavaScript/Web前端开发者，这份资源整理了face-api.js在浏览器中执行人脸识别任务所需的完整模型集合，覆盖人脸检测、68点关键点定位、表情识别、年龄性别估计与人脸识别等核心功能。压缩包内共18个文件，包含ssd_mobilenetv1、tiny_face_detector、mtcnn等人脸检测模型，face_landmark_68及tiny版本关键点模型，face_expression表情模型，age_gender年龄性别模型，以及face_recognition识别模型；各模型均以权重分片（shard）与weights_manifest.json配置清单形式提供，方便前端按需加载，整体压缩包仅10.33MB。对使用者而言，无需自行训练或转换模型，解压后配合face-api.js的加载API即可快速接入，尤其适合需要在Web端快速验证人脸检测、表情分析或人脸比对能力的中高级前端开发者和AI应用爱好者。目前已有2124人学习下载，按任务模块组织文件，既可直接用于项目集成，也可作为理解face-api.js预训练模型结构与加载机制的参考资料。
1. 打开 face-api.js 的模型文件之前，先搞清楚它到底在帮你算什么
face-api.js使用模型这个标题，背后其实是一连串实际诉求：模型文件放在哪、怎么加载、用哪个网络、输出哪些张量、精度和速度怎么取舍。face-api.js 并不是一个“接上摄像头就能认人”的黑匣子，它本质上把六类深度学习任务塞进浏览器里，通过 TensorFlow.js 跑推理。你所谓“使用模型”，第一步是理解它内置的 TinyFaceDetector、SSD MobileNet V1、FaceLandmark68Net、FaceRecognitionNet、FaceExpressionNet 这些网络分别承担什么角色。
这套库最大的价值在于：你不需要自己训练人脸检测或特征提取模型，模型权重文件和网络结构都打包发布，加载即用。但它同样有一堆让你翻车的设计——模型文件路径搞错、跨域读取失败、输入尺寸不对、tiny 模型漏检严重。这篇文章按我实际踩过的顺序来写：先讲模型家族和选型逻辑，再给完整加载流程，然后是必踩的坑，最后聊怎么在真实项目里调参数。适合正在做浏览器端人脸签到、表情分析、人脸比对或前端 UI 增强的开发者，也适合想把模型换成自定义权重但还没理清 API 边界的人。
2. 模型家族与选型：先认识 six 类网络各自管什么，再决定组合方案
2.1 检测模型对比：TinyFaceDetector 与 SSD MobileNet V1 的取舍逻辑
face-api.js 里负责“找到人脸在哪”的模型有两个实现分支。TinyFaceDetector 是基于 RetinaFace 思路裁剪的轻量级检测器，输入尺寸通常建议 416x416，计算量小、加载体积约 190KB，在普通笔记本上能做到接近实时帧率。但它对侧面、小尺寸、遮挡人脸的召回率明显偏低，如果你做的是会议摄像头画面分析，人物距离三米开外，TinyFaceDetector 经常直接漏掉整张脸。SSD MobileNet V1 的权重体积在 5.5MB 上下，输入尺寸可以调到 640，检测框更稳，对半身、多角度、大场景的鲁棒性明显更好，代价是每次推理耗时大概是 Tiny 的两到三倍。
选哪个不取决于“哪个更强”，取决于你算力余量和误检容忍度。我在实际项目里常用的判断标准是：如果是单人近景、运行在移动端 WebView 里，无脑 TinyFaceDetector；如果是多人大场景、需要框稳定不跳变，用 SSD MobileNet V1 并把 scoreThreshold 调到 0.5 以上。两者加载代码完全一样，切换成本只是改一行模型加载路径和输入尺寸，所以建议两个都下载到本地，线上做 AB 对比再定。
2.2 特征点、识别、表情网络：输出张量形状与它们能干什么
检测框只是第一步，后续三个网络才是 face-api.js 的核心竞争力。FaceLandmark68Net 输出 68 个面部关键点的坐标信息，模型体积约 350KB，作用是给你眼睛、鼻子、嘴、轮廓的空间位置；FaceRecognitionNet 把一张对齐后的人脸编码成一个 128 维特征向量，体积约 6.2MB，这个向量就是做 1:1 比对或 1:N 检索的“指纹”；FaceExpressionNet 输出 7 类表情概率，happy、sad、angry、fearful、disgusted、surprised、neutral，模型很小，只有 30KB 左右，适合做实时情绪检测。
需要特别注意的是这三个网络的输入大小是固定的，FaceLandmark68Net 会接收检测到的 face 区域裁剪，FaceRecognitionNet 要求把裁剪图缩放成 150x150，FaceExpressionNet 是 112x112。face-api.js 内部已经封装好了这套流程，你用detectAllFaces(input, model)时它会自动将检测框结果传给后置模型，但如果你手动调用faceapi.computeFaceDescriptor(singleRect)这种底层次 API，就得自己保证输入尺寸和参数对齐，否则很容易踩形状不一致的报错。
2.3 模型加载顺序与内存占用：先建认知再贴代码
浏览器端加载模型不是一把梭。每加载一个模型，TensorFlow.js 就会为你创建独立的 inference 上下，同时占据一份内存。如果不做手动清理，一个页面里加载完所有模型，内存峰值轻松超过 150MB，在低端安卓机上直接白屏。我一般按需加载：只做人脸框显示就只加载 TinyFaceDetector；做表情分析再加 FaceExpressionNet；非要 1:1 人脸比对才加载 FaceRecognitionNet。加载顺序建议是检测模型先加载，因为后续地标和识别模型依赖检测框输出，但如果你希望首屏更快，先加载检测模型并完成一帧推理，再异步加载后续模型也行。
另一个常见认知错位是模型权重文件类型。face-api.js 的预训练权重分manifest.json和多个.shard分片文件，它们必须放在同一个目录下，并且加载时传的是目录路径而不是某个文件路径。很多人以为await faceapi.nets.tinyFaceDetector.loadFromUri('/models')会自动解析目录里的 manifest，但实际它需要你能通过 HTTP 访问那个目录，本地file://协议直接跑不通。下面一章我用最小可跑代码把整个链路走一遍。
3. 用模型的最小可跑链路：本地目录、跨域处理与加载状态机
3.1 最小加载代码：把 TinyFaceDetector 与 FaceLandmark68Net 用起来
先给一套最简化代码，所有逻辑都写在一个 HTML 文件里，模型文件放在项目目录下的models文件夹。这里我用的是 CDN 方式加载 face-api.js 主库，模型文件必须本地化，这样也方便你在断网环境下复现。
<!DOCTYPE html> <html> <head> <title>face-api.js 模型加载最小示例</title> </head> <body> <video id="inputVideo" width="640" height="480" autoplay muted></video> <script src="https://cdn.jsdelivr.net/npm/face-api.js@0.22.2/dist/face-api.min.js"></script> <script> const video = document.getElementById('inputVideo'); async function init() { // 1. 依次加载 TinyFaceDetector 和 68 点关键点模型 await faceapi.nets.tinyFaceDetector.loadFromUri('/models'); await faceapi.nets.faceLandmark68Net.loadFromUri('/models'); // 2. 打开摄像头 const stream = await navigator.mediaDevices.getUserMedia({ video: {} }); video.srcObject = stream; // 3. 等待视频帧就绪后开始循环检测 video.onloadeddata = () => { detectLoop(); }; } async function detectLoop() { // 4. 关键参数：inputSize 和 scoreThreshold const options = new faceapi.TinyFaceDetectorOptions({ inputSize: 416, scoreThreshold: 0.5 }); // 5. 同时返回检测框和 68 个关键点 const results = await faceapi .detectAllFaces(video, options) .withFaceLandmarks(); // 6. 在 canvas 上绘制结果 const canvas = document.getElementById('overlay'); faceapi.matchDimensions(canvas, video); const resizedResults = faceapi.resizeResults(results, video); faceapi.draw.drawDetections(canvas, resizedResults); faceapi.draw.drawFaceLandmarks(canvas, resizedResults); requestAnimationFrame(detectLoop); } init().catch(err => console.error('初始化失败:', err)); </script> </body> </html>注意第 1 步里的loadFromUri('/models')，这个路径是相对于当前网页根路径的 URL。如果你的页面在http://localhost:8080/，它就会请求http://localhost:8080/models/tiny_face_detector_model-weights_manifest.json。第 4 步的inputSize: 416是推理输入尺寸，它影响计算量和检测框精度，不是最终显示尺寸；scoreThreshold: 0.5表示置信度低于 50% 的候选框会被丢弃。
3.2 模型加载路径的层叠规则：绝对路径、相对路径与 public 目录
我通常会遇到一个经典场景：本地开发用 Vite 或 Webpack，模型文件放public/models/，然后写loadFromUri('/models')，打包到服务器后部署在二级路径下，例如https://your.site/app/，这下绝对路径/models就请求不到了。这里有两种解法：一种是用import.meta.env.BASE_URL拼接相对路径，让路由器自动加前缀；另一种是干脆把模型目录放在和页面同级的静态资源路径下，用相对路径./models。
// Vite 环境下的动态路径拼接 const modelBasePath = import.meta.env.BASE_URL + 'models'; await faceapi.nets.tinyFaceDetector.loadFromUri(modelBasePath);这里有个更隐蔽的坑：loadFromUri内部使用fetch拉取 JSON 与二进制分片，如果你的静态服务器没有正确配置Content-Type，部分浏览器会拒绝读取 shard 文件。常见表现是模型加载偶尔失败、刷新后成功，因为浏览器缓存了 JSON 响应但 shard 一直报错。解决方式是在服务器端为.shard后缀配置application/octet-streamMIME 类型。Nginx 里加一行types { application/octet-stream shard; }即可。
3.3 模型加载状态与 UI 反馈：不要用 setTimeout 猜
模型加载是异步操作，而且模型越大耗时越久，FaceRecognitionNet 在弱网下可能需要十几秒。如果界面没有任何加载状态，用户会误以为页面卡死。face-api.js 没有内置 ready 回调，但你可以自己封一个 Promise.all 把多个模型加载串并行处理。
async function loadAllModels(basePath) { const tasks = [ faceapi.nets.tinyFaceDetector.loadFromUri(basePath), faceapi.nets.faceLandmark68Net.loadFromUri(basePath), faceapi.nets.faceRecognitionNet.loadFromUri(basePath), faceapi.nets.faceExpressionNet.loadFromUri(basePath), ]; await Promise.all(tasks); console.log('所有模型加载完成'); } // 使用时配合 loading 组件 loadAllModels('/models') .then(() => showUI()) .catch(err => showError(err.message));加载完成后再执行人脸检测，这是必须保证的顺序。有人为了抢首屏，video 开始播放就调用detectAllFaces，结果模型权重还在下载中，TensorFlow.js 会直接抛异常或返回空数组。稳妥的做法是一开始就显示加载遮罩，模型全部就绪后再隐藏，检测循环与此同时再启动。也可以用faceapi.tf.ready()等 TensorFlow.js 后端就绪，不过普通场景不用它。
4. 模型使用避坑指南：加载失败、参数玄学与内存泄漏的典型现场
4.1 现象：加载模型一直报 404，但文件确实在项目里
这是我见过最多的问题。开发者把模型文件下载好放进项目的assets/models目录，然后写loadFromUri('/assets/models')，结果控制台 404，文件明明在仓库里。原因有两个层次：一是前端构建工具不会自动把assets目录里的.json和.shard文件当作静态资源复制到输出目录，尤其是 Webpack 5 默认只处理 JS 和 CSS。二是loadFromUri走的是 HTTP 请求，不是本地文件读取，所以必须把文件放在服务器能直接访问的静态目录。
解决方式：如果是 Vite，放进public/models；如果是 Webpack，在copy-webpack-plugin里配置把models目录复制到dist根目录。然后把加载路径改为loadFromUri('/models')。检查路径是否有效的捷径是直接在浏览器地址栏输入http://localhost:8080/models/tiny_face_detector_model-weights_manifest.json，能打开 JSON 就说明路径通。
4.2 现象：TinyFaceDetector 漏检严重，中远距离人脸识别不到
TinyFaceDetector 在室内近景表现不错，但一旦人脸在画面里占比小于 5%，漏检率直线上升。原因是它的输入尺寸 416x416，经过多层卷积后小目标特征已经衰减得差不多了。这不是 bug，是模型容量决定的。解决方向有两个：第一，改输入尺寸为 320 或 224，尺寸更小推理更快，但小脸检测能力会更弱，所以这个方法只适合近景场景提速；第二，换成 SSD MobileNet V1，用new faceapi.SsdMobilenetv1Options({ minConfidence: 0.5, maxResults: 10 })并调大输入尺寸到 640。
另外，我查过一个反直觉的参数：scoreThreshold调太低不会让小脸检测得更准，反而带来大量误检框。它只是后处理阈值，模型本身的召回瓶颈不受这个参数影响。想要增强小脸召回，唯一可靠方式是换模型和提升输入分辨率。如果换模型后依然漏检，拍照或视频帧本身模糊、运动物体拖影也是常见原因，这时候需要对输入帧做人脸区域放大预处理，而不是继续调模型参数。
4.3 现象：摄像头推理 FPS 慢慢下降，最后页面卡死
这个现象的元凶通常是内存泄漏。face-api.js 在循环里反复调用detectAllFaces并绘制 canvas，如果不做控制，浏览器内存随着时间不断上涨。一个隐藏得很深的点是requestAnimationFrame(detectLoop)如果上一帧检测还没跑完就触发下一帧，会产生任务堆积，异步排队越来越多。
解决方式是加执行锁，保证同一时刻只有一个检测任务在跑：
let isProcessing = false; async function detectLoop() { if (isProcessing) return; isProcessing = true; try { const results = await faceapi.detectAllFaces(video, options); drawResults(results); } finally { isProcessing = false; } requestAnimationFrame(detectLoop); }另一个内存问题是 canvas 尺寸过大。每次绘制时如果matchDimensions把 canvas 设置为视频原始分辨率 1920x1080，绘制操作会消耗大量显存。我一般把内部绘制 canvas 固定为 640x480，绘制完再通过 CSS 拉伸到实际显示尺寸，这能显著降低内存和合成压力。
4.4 现象：加载模型时 CORS 报错，模型文件在另一台服务器
模型文件在 CDN 或另一个域名的对象存储上，直接loadFromUri会被跨域策略拦截。face-api.js 用的fetch默认请求不带crossorigin属性，所以浏览器拦截了。解决方式是给服务器响应头加Access-Control-Allow-Origin: *，如果对象存储支持自定义响应头就配置上。如果你控制不了服务器，就改成同源部署，把模型文件放到当前应用域下。
另外一个偏门的跨域情况：Chrome 扩展内加载模型，web_accessible_resources配置不正确也会导致模型读取失败。这种情况建议直接把模型打包进扩展目录，再用chrome.runtime.getURL('models/xxx')拼出完整路径。
4.5 现象：FaceRecognitionNet 提取的特征比对结果不准，同一人相似度低于 0.5
这个问题的根源通常不是模型坏了，而是你喂给识别网络的检测框不对齐。FaceRecognitionNet 的输入要求人脸居中、大致正脸、眼睛在同一水平线上，但 face-api.js 默认的detectSingleFace只给一个矩形框，如果人脸是侧面的，框里的内容偏离训练分布，提取的 128 维特征自然不可靠。
解决方式：先做 FaceLandmark68Net 检测，根据眼睛坐标做仿射变换，把脸对齐后再传给computeFaceDescriptor。face-api.js 没有内置对齐 API，但你可以用 canvas 手写对齐逻辑，或者直接用detectSingleFace(video, options).withFaceLandmarks().withFaceDescriptor()链式调用，让它内部按默认方式处理。实测下来，正脸角度偏转在 30 度以内时，直接链式调用完全够用；超过 45 度侧脸，识别向量相似度通常在 0.3 以下，基本无法挽回，只能换帧。
5. 模型调参与性能边界：把 TinyFaceDetector 的参数配到最适合你的项目
5.1 inputSize 与 scoreThreshold 对推理耗时的真实影响
用 100 张不同分辨率的测试图，在 CPU 机器上跑一轮测算，结果很有代表性：TinyFaceDetector 在 inputSize 为 128、224、416、608 时的平均耗时分别约为 8ms、20ms、60ms、120ms，而 scoreThreshold 从 0.1 调到 0.8 对耗时几乎没有影响，它只改变输出框的数量。这说明如果你觉得卡顿，优先降inputSize而不是动阈值。
inputSize 也不宜太低。我试过inputSize: 128，近景人脸确实能检测，但检测框抖动非常明显，相邻帧框的 IoU 不到 0.6，导致关键点跟着抖。做 UI 特效时这种抖动很难看，所以我的建议是：追求稳定性用 416，追求速度用 224，128 只适合纯人脸计数类需求。如果你做的是离屏一次性检测而非实时视频流，直接用 608，精度最好。
5.2 模型加载时间优化：分片并行与 lazy load
多模型的场景下，加载时间是用户体感的重要指标。FaceRecognitionNet 单文件 6.2MB，还会被切成 4 个 shard 分片，默认串行下载。要提速可以自己写并行加载：先加载 TinyFaceDetector，不到 1 秒就能开始画框，然后后台再加载 FaceRecognitionNet。这种渐进式加载在用户看来就是“页面秒开、功能逐步就绪”。
async function progressiveLoad() { await faceapi.nets.tinyFaceDetector.loadFromUri('/models'); startDetection(); // 不阻塞 UI，异步加载重模型 faceapi.nets.faceRecognitionNet.loadFromUri('/models') .then(() => enableFaceMatch()) .catch(e => console.warn('识别模型加载失败，仅显示检测框', e)); }另外，如果你用 Web Worker 做推理，模型加载和推理都在 worker 线程，主线程完全不卡。face-api.js 在 worker 里运行需要额外导入 TensorFlow.js 的 worker 后端，配置略繁琐，但在多核手机上性能收益明显，值得为生产环境投入。
5.3 模型输出可视化与调试：画框之外还要看置信度和特征距离
调试模型时，最有效的工具是把模型的中间输出画到 canvas 上。检测框的置信度、关键点的序号、识别向量的余弦距离，这些信息打印在 console 里不如直接覆盖到画面上直观。我常在项目里加一个 debug 开关，把当前帧所有检测框的 score 显示在框顶部，然后微调阈值，观察漏检和误检的平衡点。
人脸比对的场景还有一个容易被忽略的细节：computeFaceDescriptor返回的是 Float32Array 类型的 128 维向量，不是普通数组。做比对时直接用faceapi.euclideanDistance(feat1, feat2)，数值越小越相似；如果自己写函数，记得用 Float32Array 的reduce，避免隐式转成普通数组带来的精度问题。阈值经验值：欧氏距离小于 0.6 基本可以判定同一人，0.6–0.8 之间属于模糊区，需要结合场景二次确认，大于 0.8 基本是不同人。
最后一件事，模型文件它不是一次下载永久适用的，face-api.js 版本更新时，老模型的 manifest 结构可能变了。升级库版本后如果加载老模型报 Shape mismatch，去对照版本号重新下载对应模型权重。这个玄学问题我遇到过两次，最后都是靠回滚库版本或重新下载权重解决的。现在我的习惯是：本地固定一个 models 目录快照，记录权重文件名和库版本号的对应关系，部署时一起发布，省得线上环境模型和代码版本对不上。希望这些经验能帮到你少走两趟弯路。
本文还有配套的精品资源，点击获取
