Web 图片嵌入指南

借助 MediaPipe 图片嵌入任务，您可以将图片数据转换为数字表示法，以执行与机器学习相关的图片处理任务，例如比较两张图片的相似性。以下说明介绍了如何将图片嵌入器用于 Node 和 Web 应用。

如需详细了解此任务的功能、模型和配置选项，请参阅概览。

代码示例

图片嵌入程序的示例代码提供了此任务的完整 JavaScript 实现，供您参考。此代码可帮助您测试此任务，并开始构建自己的图片嵌入应用。您只需使用网络浏览器即可查看、运行和修改图片嵌入器示例代码。

设置

本部分介绍了专门针对使用图片嵌入工具设置开发环境和代码项目的关键步骤。如需了解如何设置开发环境以使用 MediaPipe 任务（包括平台版本要求）的一般信息，请参阅 适用于 Web 的设置指南。

JavaScript 软件包

您可以通过 MediaPipe @mediapipe/tasks-vision NPM 软件包获取图片嵌入代码。您可以通过平台设置指南中提供的链接找到并下载这些库。

您可以使用以下命令通过以下代码安装本地暂存区所需的软件包：

npm install @mediapipe/tasks-vision

如果您想通过内容分发网络 (CDN) 服务导入任务代码，请在 HTML 文件的 标记中添加以下代码：

<!-- You can replace jsDelivr with your preferred CDN -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
    crossorigin="anonymous"></script>
</head>

型号

MediaPipe 图片嵌入任务需要与此任务兼容的训练模型。如需详细了解适用于图片嵌入器的可用训练模型，请参阅任务概览中的“模型”部分。

选择并下载模型，然后将其存储在项目目录中：

<dev-project-root>/app/shared/models/

创建任务

指定模型路径

您可以使用 createFromModelPath() 方法创建具有默认选项的任务：

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
  const imageEmbedder = await ImageEmbedder.createFromOptions(vision, {
    baseOptions: {
      modelAssetPath: `https://storage.googleapis.com/mediapipe-models/image_embedder/mobilenet_v3_small/float32/1/mobilenet_v3_small.tflite`
    },
  });

指定模型缓冲区

如果您的模型已加载到内存中，您可以使用 createFromModelBuffer() 方法：

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const imageEmbedder = ImageEmbedder.createFromModelBuffer(
    vision, 
    new Uint8Array(...)
);

指定自定义选项

MediaPipe 图片嵌入器任务使用 createFromOptions 函数来设置任务。createFromOptions 函数接受配置选项的值。如需详细了解配置选项，请参阅配置选项。

以下代码演示了如何使用自定义选项构建和配置任务：

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const imageEmbedder = await ImageEmbedder.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "model.tflite"
      },
      quantize: true
    });

配置选项

此任务针对 Web 应用提供了以下配置选项：

选项名称 说明 值范围 默认值
running_mode 设置任务的运行模式。有两种模式：

IMAGE：适用于单张图片输入的模式。

视频：视频的解码帧或输入数据（例如来自摄像头）的直播的模式。		 {IMAGE, VIDEO} IMAGE
l2Normalize 是否使用 L2 范数对返回的特征向量进行归一化。 仅当模型尚不包含原生 L2_NORMALIZATION TFLite 运算时，才应使用此选项。在大多数情况下，已经是这种情况，因此 L2 归一化是通过 TFLite 推理实现的，而无需此选项。 Boolean False
quantize 是否应通过标量量化将返回的嵌入量化为字节。系统会隐式假定嵌入的范数为 1，因此任何维度的值都保证在 [-1.0, 1.0] 之间。如果不是这种情况，请使用 l2Normalize 选项。 Boolean False

准备数据

图片嵌入程序可以嵌入主机浏览器支持的任何格式的图片。该任务还会处理数据输入预处理，包括调整大小、旋转和值归一化。

对 Image Embedder embed() 和 embedForVideo() 方法的调用会同步运行并阻塞界面线程。如果您想从视频帧中提取特征向量，则每个嵌入都会阻塞主线程。您可以通过实现 Web Worker 来在其他线程上运行 embed() 和 embedForVideo() 方法，从而避免此问题。

运行任务

图片嵌入器使用 embed()（运行模式为 image）和 embedForVideo()（运行模式为 video）方法触发推理。Image Embedder API 将返回输入图片的嵌入向量。

以下代码演示了如何使用任务模型执行处理：

Image

const image = document.getElementById("image") as HTMLImageElement;
const imageEmbedderResult = imageEmbedder.embed(image);

视频

  const video = document.getElementById("webcam");

  const startTimeMs = performance.now();
  const embedderResult = await imageEmbedder.embedForVideo(video, startTimeMs);

处理和显示结果

运行推理后，图片嵌入器任务会返回一个 ImageEmbedderResult 对象，其中包含输入图片或帧的嵌入向量。

以下是此任务的输出数据示例：

ImageEmbedderResult:
  Embedding #0 (sole embedding head):
    float_embedding: {0.0, 0.0, ..., 0.0, 1.0, 0.0, 0.0, 2.0}
    head_index: 0

此结果是通过嵌入以下图片获得的：

异国猫的中景镜头

您可以使用 ImageEmbedder.cosineSimilarity 函数比较两个嵌入的语义相似性。如需查看示例，请参阅以下代码。

// Compute cosine similarity.
const similarity = ImageEmbedder.cosineSimilarity(
  imageEmbedderResult.embeddings[0],
  otherEmbedderResult.embeddings[0]);

图片嵌入器示例代码演示了如何显示从任务返回的嵌入器结果，如需了解详情，请参阅代码示例。