maystar-facecompare2

前端人脸比对模块（简化版），基于 MediaPipe + ONNX Runtime Web + SFace，完全本地离线运行。

仅暴露一个 compare(image1, image2, threshold?) 方法，后续将逐步扩充更多 API。

特性

• 纯前端：全部 WASM 方案，零原生依赖（无 CGO / 无 Python / 无 DLL）
• 离线可商用：模型开源可商用（MediaPipe Apache-2.0、SFace Apache-2.0、ONNX Runtime MIT）
• 官方口径对齐：5 点相似变换 112x112、SFace RGB 0~255 不减均值
• 默认阈值：SFace 余弦相似度 0.363

安装

npm install maystar-facecompare2

安装完成后会自动执行 postinstall 脚本，将 WASM 文件准备到包内 wasm/ 目录。

快速开始

import { compare } from "maystar-facecompare2";

// 两张图片比对
const result = await compare(image1, image2);

console.log(result.similarity);  // 相似度 (0~1)
console.log(result.verdict.label); // "同一人（通过）" / "疑似（人工确认）" / "不同人（不通过）"

API

compare(image1, image2, threshold?, options?)

核心比对方法。

参数：

| 参数 | 类型 | 说明 | |---|---|---| | image1 | File \| Blob \| HTMLImageElement \| HTMLCanvasElement \| string | 第一张图片 | | image2 | File \| Blob \| HTMLImageElement \| HTMLCanvasElement \| string | 第二张图片 | | threshold | number（可选） | 相似度阈值，默认 0.363。≥阈值通过，0.30~0.363 疑似，<0.30 不通过 | | options | object（可选） | 初始化选项（仅首次调用时生效） |

返回值：

{
  similarity: number,           // 余弦相似度
  verdict: {
    pass: boolean,              // 是否通过
    gray: boolean,              // 是否疑似（灰区）
    label: string,              // 判定标签
  },
  a: { embedding, landmarks, quality, blur, width, height },  // 图片 A 特征信息
  b: { embedding, landmarks, quality, blur, width, height },  // 图片 B 特征信息
}

进阶用法

// 自定义阈值
const result = await compare(fileA, fileB, 0.5);

// 指定模型和 WASM 路径（Vite/Webpack 项目需要将资源拷贝到 public 目录）
const result = await compare(fileA, fileB, 0.363, {
  modelsDir: "/public/models",
  mediapipeWasmDir: "/public/wasm/mediapipe",
  ortWasmDir: "/public/wasm/onnx",
});

destroy()

释放引擎资源。

import { destroy } from "maystar-facecompare2";
await destroy();

Vite / Webpack 项目接入

由于 Vite/Webpack 默认不直接暴露 node_modules 中的文件，需要将包内的 models/ 和 wasm/ 拷贝到项目的 public/ 目录：

# 方式一：手动拷贝
cp -r node_modules/maystar-facecompare2/models public/face-models
cp -r node_modules/maystar-facecompare2/wasm public/face-wasm

# 方式二：在构建脚本中处理

然后初始化时指定路径：

const result = await compare(fileA, fileB, 0.363, {
  modelsDir: "/face-models",
  mediapipeWasmDir: "/face-wasm/mediapipe",
  ortWasmDir: "/face-wasm/onnx",
});

判定标准

| 相似度范围 | 结果 | |---|---| | ≥ 0.363 | ✅ 通过（同一人） | | 0.30 ~ 0.363 | ⚠️ 疑似（人工确认） | | < 0.30 | ❌ 不通过（不同人） |

浏览器要求

• 支持 WebAssembly 的现代浏览器
• HTTPS 或 localhost 环境（摄像头权限需要）
• 推荐 Chrome / Edge / Safari 最新版

License

MIT