face-sdk-extractor

Vue 3 人脸特征提取组件。组件只负责选图、裁剪、人脸检测、SDK 标准 5 点对齐和 512 维特征提取；人员 ID、分组、入库和接口提交由业务层处理。

安装

pnpm add face-sdk-extractor

使用

<script setup>
import { ref } from 'vue'
import FaceSdkExtractor from 'face-sdk-extractor'

const extractor = ref(null)

function handleReady(info) {
  // { modelVersion, embeddingDim }
}

function handleSuccess(result) {
  // { feature, featureBase64, modelVersion, embeddingDim }
}

function handleError(error) {
  // { code, message }
}
</script>

<template>
  <FaceSdkExtractor
    ref="extractor"
    @ready="handleReady"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

清空当前图片：

extractor.value?.reset()

替换模型文件

默认使用包内置 mobileface.onnx 和 mobileface.json。如需使用项目文件：

<script setup>
import modelUrl from './models/mobileface.onnx?url'
import manifestUrl from './models/mobileface.json?url'

const modelAssets = { modelUrl, manifestUrl }
</script>

<template>
  <FaceSdkExtractor :model-assets="modelAssets" />
</template>

mobileface.json 需包含 modelVersion、inputSize、embeddingDim。

结果格式

success 返回：

{
  feature: Float32Array,        // 512 维 L2 归一化特征
  featureBase64: string,        // Float32 little-endian Base64
  modelVersion: 'face_mbf_512',
  embeddingDim: 512,
}

业务侧导入 iOS / App 时建议组装：

{
  personId,
  name,
  modelVersion: result.modelVersion,
  embeddingDim: result.embeddingDim,
  featureFormat: 'float32-le-base64',
  normalized: true,
  metric: 'COSINE',
  featureBase64: result.featureBase64,
  ...(groupId ? { groupId } : {}),
}

不要传空字符串 groupId；无分组时省略该字段。

错误码

常见错误：

• INVALID_FILE_TYPE
• FILE_TOO_LARGE
• MODEL_LOAD_FAILED
• FACE_NOT_FOUND
• MULTIPLE_FACES
• LANDMARK_MISSING
• FACE_INCOMPLETE
• ALIGNMENT_FAILED
• EXTRACTION_FAILED

业务判断使用 code，message 可直接展示。

构建交付

本地构建：

pnpm --filter face-sdk-extractor build

产物在 packages/face-sdk-extractor/dist/。npm 包只交付 dist/ 和 README.md，不交付 src/ 和构建配置。

模型和运行时随包内置，不访问 CDN。固定二进制依赖：

@mediapipe/[email protected] [email protected]

mobileface.onnx 构建后保持固定文件名，便于后续替换。