網頁圖片嵌入指南

MediaPipe 圖片嵌入器工作可將圖片資料轉換為數值表示法，以便完成機器學習相關的圖片處理工作，例如比較兩張圖片的相似度。本操作說明說明如何在 Node 和網頁應用程式中使用圖片嵌入工具。

如要進一步瞭解這項工作的功能、模型和設定選項，請參閱總覽。

程式碼範例

圖片嵌入工具的程式碼範例會在 JavaScript 中提供此工作的完整實作，供您參考。這個程式碼可協助您測試此工作，並開始建構自己的圖片嵌入應用程式。您只需使用網路瀏覽器，即可查看、執行及編輯圖片嵌入器範例程式碼。

設定

本節將說明如何設定開發環境和程式碼專案，以便使用 Image Embedder。如要進一步瞭解如何設定開發環境以使用 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 圖片嵌入器工作需要訓練的模型與此工作相容。如要進一步瞭解可供 Image Embedder 使用的訓練模型，請參閱工作總覽的「模型」一節。

選取並下載模型，然後將模型儲存在專案目錄中：

<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
    });

設定選項

此工作包含下列網頁應用程式設定選項：

選項名稱 說明 值範圍 預設值
running_mode 設定工作執行模式。有兩種模式：

IMAGE：單張圖片輸入模式。

影片：解碼影片影格或輸入資料 (例如來自攝影機) 直播的模式。		 {IMAGE, VIDEO} IMAGE
l2Normalize 是否要使用 L2 正規化，將傳回的特徵向量正規化。只有在模型未包含原生 L2_NORMALIZATION TFLite 運算時，才使用這個選項。在大多數情況下，模型都已包含這個運算，因此可透過 TFLite 推論達成 L2 規格化，而不需要使用這個選項。 Boolean False
quantize 是否應透過純量量化，將傳回的嵌入值量化為位元組。系統會隱含假設嵌入項目為單位規範，因此任何維度都保證會具有 [-1.0, 1.0] 的值。如果不是這種情況，請使用 l2Normalize 選項。 Boolean False

準備資料

圖片嵌入器可嵌入主機瀏覽器支援的任何格式圖片。此工作也會處理資料輸入預先處理作業，包括調整大小、旋轉和值正規化。

對圖片嵌入器 embed() 和 embedForVideo() 方法的呼叫會同步執行，並封鎖使用者介面執行緒。如果您想從影片影格中擷取特徵向量，每個嵌入項目都會阻斷主執行緒。如要避免這種情況，您可以實作網路 worker，在另一個執行緒上執行 embed() 和 embedForVideo() 方法。

執行工作

圖片嵌入器會使用 embed() (搭配執行模式 image) 和 embedForVideo() (搭配執行模式 video) 方法觸發推論。Image Embedder API 會傳回輸入圖片的嵌入向量。

以下程式碼示範如何使用工作模型執行處理作業：

圖片

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]);

圖片嵌入器範例程式碼示範如何顯示工作傳回的嵌入器結果，詳情請參閱程式碼範例。