简介face-api.js是浏览器端实现人脸识别的主流JavaScript库这份资源为其配套的预训练模型包面向Web前端开发者用于快速落地人脸检测、关键点定位、表情识别、年龄性别判断与人脸比对等任务。资源共18个文件主要由各模型的weights_manifest.json配置与shard权重分片组成涵盖ssd_mobilenetv1、tiny_face_detector、face_landmark_68及tiny版、face_expression、age_gender、face_recognition、mtcnn等模型压缩包整体10.33MB可直接在项目中加载调用。已有2124人学习下载。有了这套模型文件开发者无需从零训练便可依托face-api.js封装好的加载函数完成模型装配进而实现完整的人脸识别流程其中tiny版本模型为实时应用提供了轻量选择便于在性能与精度之间取舍同时也有助于满足隐私合规方面的部署需求。1. 浏览器里的人脸识别face-api.js 的模型家族到底能干什么在浏览器里做实时人脸检测、人脸识别、表情和年龄判断目前最顺手的方案仍然是 face-api.js。很多第一次接触这个库的人会误以为难点在识别逻辑实际动手才发现最容易被卡住的是模型本身权重文件放哪、用哪个模型、参数怎么设、为什么本地能跑线上动作就失灵。这篇文章把 face-api.js 的模型使用拆开讲从选型、加载、调用再到避坑覆盖检测、关键点、识别、表情和年龄性别这几项常用能力。适合想在前端项目里快速接入人脸能力、又不想碰 Python 推理服务的开发者也适合已经被 404 和误检折腾过一轮的人。先说结论face-api.js 只是包装层真正的效果由你选的权重文件和调用参数决定。模型用对了几十行代码就能出活模型没配对写再多逻辑也只会得到一堆乱跳的框和认错的人。2. 模型全景与选型五个模型各自的定位、精度和代价face-api.js 的官方模型家族里按用途可以分成四类检测、关键点、识别、属性推断。检测负责“脸在哪”关键点负责“脸的形状”识别负责“这是谁”表情和年龄性别负责“这个人什么状态”。这四个能力是层层依赖的识别必须依赖检测和关键点而表情、年龄这类附属模型则可以直接挂在检测结果上。2.1 TinyFaceDetector 与 SSD Mobilenet检测模型的精度与速度怎么选检测是整个链路的入口也是两个最容易让人选择困难的地方tinyFaceDetector 和 ssdMobilenetv1。tinyFaceDetector 是一个轻量网络权重体积小、推理速度快适合视频流这种需要每秒钟跑很多次的场景。它有一个关键限制输入尺寸必须能被 32 整除而且范围一般在 64 到 512 之间。我常用的值是 320兼顾速度和召回想要更稳就提到 416代价是每帧耗时明显增加。ssdMobilenetv1 是更早的 MobileNet SSD 模型精度更高对远距离小脸的召回比 tiny 好但模型重、推理慢。它适合单张图片或服务端批处理不适合在低端手机上做实时视频。模型速度精度适合场景tinyFaceDetector快中等实时视频、移动端ssdMobilenetv1慢较高单张图片、精度优先选型时我一般按设备能力走桌面端和移动端用不同的检测器。可以封装一个选择函数const isMobile /Mobi|Android/i.test(navigator.userAgent); const detectorOptions isMobile ? new faceapi.TinyFaceDetectorOptions({ inputSize: 320, scoreThreshold: 0.5 }) : new faceapi.SSDMobilenetv1Options({ minConfidence: 0.5, maxResults: 10, iouThreshold: 0.4 });TinyFaceDetectorOptions 的两个核心参数是 inputSize 和 scoreThreshold。inputSize 决定模型看到的输入图分辨率越小越快但太小会让远处的小脸直接丢失。scoreThreshold 是置信度门槛默认 0.5降到 0.3 能捞回很多低置信度的脸代价是误检变多。SSDMobilenetv1Options 里的 minConfidence 等价于 scoreThresholdmaxResults 限制最多输出几个框iouThreshold 控制重叠框的合并力度。一个常见的错误是两端都用同一套参数手机端把 inputSize 设成 416帧率掉到没法看桌面端又把 threshold 降到 0.2满屏都是假框。正确做法是让参数跟着场景走而不是跟着代码模板走。2.2 FaceLandmark68关键点模型是识别和表情的地基关键点模型有两个faceLandmark68Net 和 faceLandmark68TinyNet。前者输出 68 个关键点坐标覆盖脸轮廓、眉毛、眼睛、鼻子和嘴巴后者是轻量版速度快但点位的精度略差在侧脸和遮挡多的时候会有偏移。关键点模型单独使用价值有限但它决定了识别和表情的上限。face-api.js 的 withFaceDescriptor 会先根据关键点把脸区域对齐到标准姿态再送入识别网络提取特征。这一步如果关键点偏了后面识别出来的特征向量就会带上“歪头”的信息导致同一个人在两张角度不同的照片里距离被拉大。实际项目中我基本固定用完整版 faceLandmark68Net只有需要极致帧率的时候才换 tiny 版。加载和调用方式如下await faceapi.nets.faceLandmark68Net.loadFromUri(/weights); const result await faceapi .detectSingleFace(input, detectorOptions) .withFaceLandmarks(); // 输出 68 个点的坐标数组 console.log(result.landmarks.positions.length); // 直接取下巴轮廓用于脸部裁剪 const jaw result.landmarks.getJawOutline();landmarks.positions 返回的是包含 x、y 的对象数组顺序固定下颌、右眉、左眉、鼻梁、鼻子下方、右眼、左眼、嘴巴外圈、嘴巴内圈。做美颜或贴纸时可以直接从 positions 里按下标取点不需要自己做坐标变换。2.3 FaceRecognitionNet 与表情、年龄模型特征向量与附属能力的取舍faceRecognitionNet 把一张对齐后的脸编码成 512 维特征向量。face-api.js 里比较两个人的方式不是余弦相似度而是欧氏距离距离越小越可能是同一个人。这个模型体积最大加载最慢必须按需加载。faceExpressionNet 输出 7 种表情的概率中性、开心、悲伤、愤怒、恐惧、厌恶、惊讶。ageGenderNet 输出两个东西一个 age 数值和一个 gender 概率。这两个模型可以共享已经检测出来的 face 区域不需要单独再跑一次检测。模型输出用途加载成本faceRecognitionNet512 维特征向量人脸识别、比对最高faceExpressionNet7 种表情概率表情判断中ageGenderNet年龄数值、性别概率年龄性别推断中这四个模型没有必要一次性全部加载。常见的做法是进页面只加载检测和关键点等用户真正触发识别或者属性分析时再补加载对应的模型。这样首屏权重体积能省下一大截。// 按需加载而不是启动时全量加载 async function loadRecognitionIfNeeded() { if (!faceapi.nets.faceRecognitionNet.isLoaded) { await faceapi.nets.faceRecognitionNet.loadFromUri(/weights); } }isLoaded 是每个网络实例自带的属性加载成功后会变成 true。用这个属性做幂等控制能避免在组件重复挂载时把模型浏览器加载两遍。3. 模型加载与配置本地静态资源、跨域与加载完成判定模型文件本身是静态资源加载方式就那么几种但恰恰是这一环节出的问题最多。我见过不少项目代码逻辑全对最后卡在权重文件加载不上页面看起来没报错实际上啥都跑不动。3.1 模型文件放哪官方权重目录与自己的静态资源目录face-api.js 的权重不是单个文件而是以“一个 manifest 加多个 shard 文件”的方式分发的。manifest 是 JSON里面记录了模型的网络结构信息、文件分块方式和每块的权重路径shard 是真正的二进制权重数据。浏览器加载时会先请求 manifest再按里面的记录逐个拉 shard 文件。所以模型文件放目录时文件名不能随意改动。我的做法是建一个专门的模型目录把从发布包 weights 目录里拿到的文件原样拷进去然后用相对路径引用public/ weights/ tiny_face_detector_model-weights_manifest.json tiny_face_detector_model-shard1 face_landmark_68_model-weights_manifest.json face_landmark_68_model-shard1 face_recognition_model-weights_manifest.json face_recognition_model-shard1这里有个很多人踩过的坑为了“看起来整洁”把 shard 文件改名成 model.bin结果加载模型时 manifest 里记录的还是 shard 原名fetch 全部 404。shard 文件名必须和 manifest 里保持一致要么都不改要么连 manifest 里的路径一起改。不建议直接依赖远程链接加载权重。远端静态服务器一旦没开跨域或响应类型不对整个模型就废了。模型文件应当和你的页面同域部署这是最省心、最可控的方式。3.2 loadFromUri 与 loadFromDisk浏览器与 Node.js 的加载路径选择模型加载有三个入口loadFromUri、loadFromDisk、loadFromWeightMap。日常项目里用前两个就够第三个是底层接口留给自定义加载流程。loadFromUri 接收一个 URL 前缀浏览器里常用传入的是模型文件所在目录。它内部会拼接文件名发起 fetch 请求适合页面渲染时调用。const MODEL_URL /weights; async function loadAllModels() { const loadings [ faceapi.nets.tinyFaceDetector.loadFromUri(MODEL_URL), faceapi.nets.faceLandmark68Net.loadFromUri(MODEL_URL), ]; await Promise.all(loadings); }loadFromDisk 是 Node.js 环境下用的接收本地磁盘路径。常见做法是配合 node-canvas 提供 canvas polyfill用于服务端批量处理图片。前端项目里用到它的场景不多我在做服务端测试脚本时会用这套const faceapi require(face-api.js); const { Canvas, Image, ImageData } require(canvas); // Node 环境下需要 polyfill 三个全局对象否则图像解码失败 faceapi.env.monkeyPatch({ Canvas, Image, ImageData }); await faceapi.nets.tinyFaceDetector.loadFromDisk(./weights);loadFromWeightMap 是更底层的方式需要你自己先拿到 WeightMap 数据。实际项目中很少直接用了解即可。3.3 加载完成判定与跨域配置别在模型没 ready 时就去检测模型的加载是异步的如果没等加载完就调用 detectAllFaces会抛“model is not loaded”之类的异常。很多新手把 load 和 detect 写在同一个同步函数里然后发现时好时坏本质上是竞态问题。我建议把模型初始化抽成一个独立的异步函数并且用 isLoaded 做幂等保护防止重复调用时把模型重新拉一遍let initPromise null; async function ensureModelsLoaded() { if (faceapi.nets.tinyFaceDetector.isLoaded faceapi.nets.faceLandmark68Net.isLoaded) { return; } if (!initPromise) { initPromise Promise.all([ faceapi.nets.tinyFaceDetector.loadFromUri(/weights), faceapi.nets.faceLandmark68Net.loadFromUri(/weights), ]).finally(() { initPromise null; }); } return initPromise; }initPromise 在这里承担了“加载锁”的角色。多组件同时触发初始化时只有一个真正去拉权重其余的都复用同一个 Promise既省带宽又避免重复加载。加载失败时 initPromise 会被置空下次调用还能重试不会锁死。跨域是一个容易忽略的隐藏问题。如果模型文件放在另一个域名下且服务器没有返回 Access-Control-Allow-Origin 头浏览器会在 fetch 阶段拦截manifest 都读不到。这种问题在本地开发时暴露不出来一旦部署到生产环境就立刻翻车。我的做法是模型文件和页面同源这是底线实在要放 CDN先确认 CDN 返回了正确的跨域头再上线。4. 让模型跑起来检测、识别、表情与属性的最小可用 Demo模型加载完了接下来就要让它们干活。这一章给的是可以直接复制到项目里的最小可用链路从视频流检测开始一路走到识别和属性分析。4.1 视频流人脸检测getUserMedia TinyFaceDetector 组合的最小命令最基础的视频检测只需要三样东西一个 video 元素、一路摄像头流、一个定时检测循环。代码结构如下const video document.getElementById(video); // 获取摄像头画面 const stream await navigator.mediaDevices.getUserMedia({ video: { width: 640, height: 480 } }); video.srcObject stream; await video.play(); // 检测参数inputSize 320置信度阈值 0.5 const options new faceapi.TinyFaceDetectorOptions({ inputSize: 320, scoreThreshold: 0.5 }); // 每 100ms 跑一次检测而不是每帧都跑 const detectInterval setInterval(async () { const detections await faceapi.detectAllFaces(video, options); // detections[i].detection.box 是检测框 // detections[i].detection.score 是置信度 }, 100);inputSize 这里设成 320是实时视频场景下速度和精度的平衡点。如果你的检测目标是“远距离小脸”建议降到 256 并同时把 scoreThreshold 调低到 0.3否则小脸映射到 320 的输入图里只剩几个像素模型根本看不出来。detectAllFaces 的第一个参数可以是 video 元素也可以传 img 或 canvas。传 video 的好处是模型内部会直接读取当前帧省去截图步骤。为什么用 setInterval 而不是 requestAnimationFrame 逐帧跑因为 60fps 的视频逐帧推理CPU 会持续满载风扇狂转页面卡顿而且实际业务里 10fps 已经足够跟手。我的替代方案是把间隔设成 100ms既保流畅又控负载。如果想要更灵敏的框跟踪可以缩短到 50ms但不要低于 30ms否则就是拿性能换那几十毫秒的响应。4.2 人脸识别比对从提取描述符到欧氏距离阈值人脸识别需要两步先给已知的人脸注册特征再拿实时帧的特征去匹配。注册特征时需要针对每个已知身份从照片里检测人脸、提取关键点、生成描述符然后封装成 LabeledFaceDescriptorsasync function registerFaces() { const names [alice, bob]; const labeledDescriptors await Promise.all( names.map(async (name) { // 读取本地注册照片 const img await faceapi.fetchImage(/faces/${name}.jpg); // 检测、定位关键点、生成 512 维描述符 const detection await faceapi .detectSingleFace(img, new faceapi.TinyFaceDetectorOptions()) .withFaceLandmarks() .withFaceDescriptor(); // 每个身份可以注册多张照片对应多个描述符 return new faceapi.LabeledFaceDescriptors(name, [detection.descriptor]); }) ); return new faceapi.FaceMatcher(labeledDescriptors, 0.6); }FaceMatcher 的第二个参数是欧氏距离阈值。当实时描述符和某个已注册描述符的距离小于这个值时判定为同一人。0.6 是官方示例用的宽松值实战里我建议 0.45 到 0.5 之间。阈值设得越低误认越少但漏认越多设得越高越容易把不同的人认成同一个。注册照片的质量直接决定识别准确率。模糊、暗光、大角度侧脸的照片生成的描述符会在一开始就带偏之后阈值怎么调都救不回来。我处理时会给每个身份留 2 到 3 张不同角度的正面照让 LabeledFaceDescriptors 支持多描述符匹配。匹配时用 findBestMatch 返回最佳结果const result await faceapi .detectSingleFace(video, options) .withFaceLandmarks() .withFaceDescriptor(); if (result) { const bestMatch faceMatcher.findBestMatch(result.descriptor); console.log(bestMatch.label, bestMatch.distance); }bestMatch.distance 是实时特征与库中最相似特征的欧氏距离。当距离接近阈值时不要轻信 label建议业务上把“低于阈值的 70%”作为“确定”阈值附近统一返回“不确定”让 UI 层提示用户靠近一点或换个角度。4.3 表情、年龄与性别的输出解析一份典型返回结构表情、年龄和性别这三个模型可以串在检测结果上它们都复用已经检测到的人脸区域不需要额外做一次完整的检测const info await faceapi .detectSingleFace(video, options) .withFaceLandmarks() .withFaceExpressions() .withFaceAgeAndGender(); if (info) { // 年龄是回归值 console.log(age:, info.age); // 性别是二分类概率 console.log(gender:, info.gender, probability:, info.genderProbability); // 表情输出为一个对象asSortedArray() 转成降序数组 const top info.expressions.asSortedArray()[0]; console.log(top expression:, top.expression, top.probability); }expressions 字段的值是一个形如 { neutral: 0.82, happy: 0.03, ... } 的对象asSortedArray() 会返回按概率降序排列的数组数组第一项就是最可能的情绪。info.age 是一个直接的数值预测在儿童和中老年人上偏差很大。如果项目需要把这个值展示给用户我建议把它作为“参考龄”而不是精确年龄。性别同理genderProbability 不高时比如低于 0.7与其硬给一个判断不如让 UI 显示“无法确定”。注意这组模型如果同时调用推理耗时是逐层叠加的。在移动端上检测 关键点 表情 年龄性别四条链路串起来可能一帧要 200ms 以上。我会把属性分析藏在一个“需要时才触发”的按钮或手势后面而不是做成常驻实时分析。5. 模型使用的避坑指南加载失败、误检与内存失控模型使用中的坑一半来自权重资源一半来自参数和生命周期管理。这里挑五条最有代表性的每一条都是我在真实项目里踩过的。5.1 模型加载失败但页面不报错先查静态目录大小写与响应头现象页面打开后没有任何人脸框控制台里有几条 404 或 fetch failed 日志页面本身不抛错。原因权重目录的路径大小写不一致、manifest 引用相对路径错误、静态服务器把 JSON 文件的 Content-Type 返回成了 text/plain、远程 CDN 没有开启跨域。这些都属于“浏览器不主动打断但模型根本没加载上”的静默失败。解决打开浏览器 Network 面板找到 model 相关请求看状态码和响应头。能用 curl 确认的就先 curl 一下curl -I https://example.com/weights/tiny_face_detector_model-weights_manifest.json重点看返回状态是否为 200以及响应头里有没有 Access-Control-Allow-Origin。如果 manifest 能打开但 shard 404检查一下是不是改过文件名。我一般直接把整个 weights 目录原样拷进 static 目录不重命名任何文件。5.2 小图脸一直检测不到输入尺寸与最小置信度的取舍现象镜头前的人稍微离远一点检测框就消失凑很近的时候又正常。原因scoreThreshold 设得太高或者 inputSize 设得太大导致远处的小脸在输入图里只有十几个像素。检测模型在极小目标上的响应非常弱置信度输出低于阈值就被过滤掉了。解决把 scoreThreshold 降到 0.3 到 0.4同时把 inputSize 降到 256 或 320。inputSize 不是越大越好它是模型输入的分辨率上限不是“看得更远”的工具。在输入分辨率固定的前提下靠打分阈值捞回小脸是更有效的手段const options new faceapi.TinyFaceDetectorOptions({ inputSize: 256, scoreThreshold: 0.3 });这个组合适合监控视角、课堂环境这类人脸占比小但数量多的场景。误检会变多但漏检率明显下降。如果人脸实在太小先做局部放大再检测而不是盲目把所有画面塞进模型。5.3 多人同屏检测框乱跳IOU 阈值和帧率控制的配合现象多人一起出现在画面里时某个人的检测框时有时无框的位置还在几秒内来回抖动。原因检测频率太高把低置信度的帧也输出成了检测框人挨得近时两个框重叠检测模型在不同帧里对同一张脸返回了不同位置inputSize 和原图分辨率差距过大时坐标映射误差会被放大框会跟着抖。解决第一把检测间隔从每帧改成 100ms避免高频抖动第二scoreThreshold 抬回 0.5过滤掉不稳定的弱置信度框第三在画框前做位置平滑。平滑逻辑是对连续几帧的框坐标做加权平均let lastBox null; function smoothBox(newBox, weight 0.6) { if (!lastBox) { lastBox newBox; return newBox; } const smoothed { x: lastBox.x * (1 - weight) newBox.x * weight, y: lastBox.y * (1 - weight) newBox.y * weight, width: lastBox.width * (1 - weight) newBox.width * weight, height: lastBox.height * (1 - weight) newBox.height * weight }; lastBox smoothed; return smoothed; }weight 越大跟随越慢越小越容易原地抖动。对快速动作场景比如手势互动weight 别超过 0.6否则手势已经变了框还留在原地。5.4 识别时 A 被认成 B特征匹配阈值不是越低越好现象A 的脸匹配到了 B 的名字distance 显示在 0.5 左右看起来“没问题”但结果就是错的。原因阈值设得太宽。0.6 的阈值意味着只要距离小于 0.6 就认为同一个人这在人脸姿态差异大的场景里太冒险。另外注册照片和实时画面如果分辨率、亮度、角度差别大同一个人自己的距离也可能被拉到 0.5 以上。解决先把自己的阈值降到 0.45再用实际数据验证。不要凭感觉调而是收集一组“同一个人在不同帧”的距离样本再留一点余量// 同一个人 20 帧距离的最大值大约在这些值附近 const samePersonDists [0.31, 0.28, 0.33, 0.35]; const margin 0.1; // 同人最大距离再加 10% 余量作为阈值 const threshold Math.max(...samePersonDists) margin;margin 建议取 0.05 到 0.1 之间。如果算出来阈值本身就超过 0.5说明注册照片质量有问题的可能性大过阈值问题先回去重拍注册照不要硬调阈值。5.5 内存越跑越高重复 new 模型实例与未清理的定时器现象页面长时间运行后内存持续上涨最终卡顿甚至白屏。切换路由再回来内存也不回落。原因最常见的两个一是检测定时器没有被清理组件卸载后还在后台跑推理对象无法被回收二是每次初始化都重新 load 模型浏览器为同一个模型保留了多份权重副本。加上 detectAllFaces 每次调用都会在内部创建新的 tensor 对象内存自然只涨不降。解决组件卸载或页面关闭时清理定时器并停掉摄像头流同时用 isLoaded 或 initPromise 保证模型只加载一次window.addEventListener(beforeunload, () { clearInterval(detectInterval); stream.getTracks().forEach((track) track.stop()); });另外检测循环里不要每次 new 一个 options复用一个实例。canvas 画框时复用同一个 2d context避免不断创建新的画布对象。Node 环境跑批处理时处理完记得手动调用 global.gc()开启 --expose-gc否则批处理场景也能把内存吃到报警。6. 验证模型效果的一套基准自检别让权重玄学毁掉精度模型参数调来调去如果靠肉眼判断“好像变好了”那基本等于把上线质量交给运气。我自己每换一次模型权重或者参数都会跑一遍固定的样本集验证这是最笨但最可靠的方法。准备三组图片单人正面近脸、多人远场景、暗光或逆光场景。每张图人工标注期望检测出的人脸数量。然后写一个脚本循环检测输出“期望数量”和“实际数量”const testCases [ { file: /bench/near.jpg, expected: 1 }, { file: /bench/group.jpg, expected: 4 }, { file: /bench/dark.jpg, expected: 2 } ]; for (const c of testCases) { const img await faceapi.fetchImage(c.file); const detections await faceapi.detectAllFaces(img, options); console.log( c.file, expect ${c.expected}, got ${detections.length} ); }漏检率 少检数量 / 期望数量误检率 多检数量 / 期望数量。调参之前跑一遍调完之后再跑一遍你就知道自己改的 threshold 到底是把漏检换成了误检还是真的提升了整体质量。识别模型也建议做距离自检找一个志愿者让他站在摄像头前面录 20 帧不同角度的正脸算这 20 帧和注册描述符之间的距离。如果同一个人 20 帧的距离最大值已经大过 0.5那先别纠结阈值了回去检查注册照片的光线、姿态和分辨率这个权重版本下它的特征空间分布本身可能就不适合你的数据。这套基准脚本是我每接一个人脸需求都会先铺的底子。有一次演示现场光线一变识别率掉到五成回来看录制帧才发现是注册照和现场照的亮度差异太大参数怎么调都救不回来最后重新拍注册照才过关。那以后我凡是动模型参数或者换权重都先重跑这三组样本再决定要不要上线。希望帮到你。本文还有配套的精品资源点击获取