简介面向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 要求把裁剪图缩放成 150x150FaceExpressionNet 是 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 titleface-api.js 模型加载最小示例/title /head body video idinputVideo width640 height480 autoplay muted/video script srchttps://cdn.jsdelivr.net/npm/face-api.js0.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追求速度用 224128 只适合纯人脸计数类需求。如果你做的是离屏一次性检测而非实时视频流直接用 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 目录快照记录权重文件名和库版本号的对应关系部署时一起发布省得线上环境模型和代码版本对不上。希望这些经验能帮到你少走两趟弯路。本文还有配套的精品资源点击获取