适用于 Web 的文本嵌入指南

借助 MediaPipe Text Embedder 任务，您可以创建文本数据的数字表示形式，以捕获其语义含义。以下说明介绍了如何使用适用于 Web 应用和 JavaScript 应用的文本嵌入器。

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

代码示例

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

初始设置

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

JavaScript 软件包

文本嵌入器代码可通过 @mediapipe/tasks-text 软件包获取。您可以从平台设置指南中提供的链接查找和下载这些库。

您可以使用以下命令，通过以下代码为本地预演安装所需的软件包：

npm install @mediapipe/tasks-text

如果要部署到服务器，可以使用内容分发网络 (CDN) 服务（如 jsDelivr）直接向 HTML 页面添加代码，如下所示：

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

模型

MediaPipe Text Embedder 任务需要一个与此任务兼容的经过训练的模型。如需详细了解文本嵌入器可用的经过训练的模型，请参阅任务概览“模型”部分。

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

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

配置选项

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

选项名称	说明	值范围	默认值
`l2Normalize`	是否以 L2 范数归一化返回的特征向量。仅当模型尚未包含原生 L2_NORMALIZATION TFLite 运算时，才可使用此选项。在大多数情况下，情况都是如此，L2 归一化是通过 TFLite 推断实现的，因此无需使用此选项。	`Boolean`	`False`
`quantize`	是否应通过标量量化将返回的嵌入量化为字节。嵌入被隐式假定为单位范数，因此任何维度的值都必须在 [-1.0, 1.0] 之间。如果不属于这种情况，请使用 l2Normalize 选项。	`Boolean`	`False`

准备数据

文本嵌入器可处理文本 (string) 数据。该任务会处理数据输入预处理，包括标记化和张量预处理。所有预处理都在 embed 函数中处理。无需事先对输入文本进行额外的预处理。

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

运行任务

Text Embedder 使用 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]);

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