網頁版文字嵌入指南

MediaPipe 文字嵌入工具工作可讓您建立文字資料的數值表示法，以擷取其語意含義。以下操作說明將說明如何針對網頁和 JavaScript 應用程式使用文字嵌入工具。

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

程式碼範例

文字嵌入程式的範例程式碼提供此工作在 JavaScript 中的完整實作，供您參考。這段程式碼可協助您測試這項工作，並開始建構自己的文字嵌入應用程式。您只能透過網路瀏覽器查看、執行及編輯文字嵌入程式程式碼範例。

設定

本節說明設定開發環境的重要步驟，以及專門用於使用文字嵌入工具的程式碼專案。如需瞭解如何設定開發環境以使用 MediaPipe 工作 (包括平台版本需求)，請參閱「網頁版設定指南」。

JavaScript 套件

您可以透過 @mediapipe/tasks-text 套件取得文字嵌入程式程式碼。您可以從平台設定指南中提供的連結尋找及下載這些程式庫。

您可以使用下列指令，安裝具有以下程式碼的必要套件，以執行本機暫存：

npm install @mediapipe/tasks-text

如要將程式碼部署至伺服器，您可以使用 jsDelivr 等內容傳遞網路 (CDN) 服務，將程式碼直接新增至 HTML 網頁，如下所示：

<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-text@latest/index.js"
    crossorigin="anonymous"></script>
</head>

型號

MediaPipe 文字嵌入程式工作需要與這項工作相容的已訓練模型。如要進一步瞭解文字嵌入工具的可用已訓練模型，請參閱工作總覽「模型」一節。

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

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

建立工作

使用其中一個文字嵌入工具 createFrom...() 函式，準備執行推論的工作。您可以使用 createFromModelPath() 函式，搭配已訓練模型檔案的相對或絕對路徑。以下程式碼範例示範如何使用 createFromOptions() 函式。如要進一步瞭解可用的設定選項，請參閱設定選項一文。

以下程式碼示範如何建構及設定這項工作：

async function createEmbedder() {
  const textFiles = await FilesetResolver.forTextTasks("https://cdn.jsdelivr.net/npm/@mediapipe/tasks-text@latest/wasm/");
  textEmbedder = await TextEmbedder.createFromOptions(
    textFiles,
    {
      baseOptions: {
        modelAssetPath: `https://storage.googleapis.com/mediapipe-tasks/text_embedder/universal_sentence_encoder.tflite`
      },
      quantize: true
    }
  );
}
createEmbedder();

設定選項

這項工作有以下網頁和 JavaScript 應用程式的設定選項：

選項名稱	說明	值範圍	預設值
`l2Normalize`	是否使用 L2 正規化傳回的特徵向量。只有在模型不含原生 L2_NORMALIZATION TFLite Op 的情況下，才能使用這個選項。在大多數情況下，已經是此情況，L2 正規化是透過 TFLite 推論達成，不需要使用這個選項。	`Boolean`	`False`
`quantize`	是否應透過純量量化，將傳回的嵌入量化為位元組。以隱含方式假設嵌入為單位標準，因此任何維度保證在 [-1.0, 1.0] 中都有一個值。如果並非如此，請使用 l2 正規化選項。	`Boolean`	`False`

準備資料

文字嵌入程式適用於文字 (string) 資料。工作會處理資料輸入的預先處理作業，包括代碼化和張量預先處理。所有預先處理作業都會在 embed 函式中處理。不需要事先對輸入文字進行額外的預先處理。

const inputText = "The input text to be embedded.";

執行工作

文字嵌入程式使用 embed 函式觸發推論。如果是嵌入文字，這代表傳回輸入文字的嵌入向量。

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

// Wait to run the function until inner text is set
const embeddingResult = textEmbedder.embed(
  inputText
);

處理並顯示結果

文字嵌入程式會輸出 TextEmbedderResult，其中包含輸入文字的嵌入清單 (浮點或量化量化)。

以下為這項工作的輸出資料範例：

TextEmbedderResult:
  Embedding #0 (sole embedding head):
    float_embedding: {0.2345f, 0.1234f, ..., 0.6789f}
    head_index: 0

您可以使用 TextEmbedder.cosineSimilarity 函式比較兩個嵌入的語意相似度。相關範例請看以下程式碼。

// Compute cosine similarity.
const similarity = TextEmbedder.cosineSimilarity(
  embeddingResult.embeddings[0],
  otherEmbeddingResult.embeddings[0]);

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