API¶

运行管道 API¶

只要模型在我们的模型中心，您就可以直接使用 Transformer.js 的 pipeline API 执行推理。

Transformers.js 文档提供了许多示例，您可以在 Firefox 中运行时稍微调整一下。

在下面的示例中，使用 summarization 任务执行文本摘要任务

const { createEngine } = ChromeUtils.importESModule("chrome://global/content/ml/EngineProcess.sys.mjs");
const options = {
  taskName: "summarization",
  modelId: "mozilla/text_summarization",
  modelRevision: "main"
};

const engine = await createEngine(options);

const text = 'The tower is 324 metres (1,063 ft) tall, about the same height as an 81-storey building, ' +
'and the tallest structure in Paris. Its base is square, measuring 125 metres (410 ft) on each side. ' +
'During its construction, the Eiffel Tower surpassed the Washington Monument to become the tallest ' +
'man-made structure in the world, a title it held for 41 years until the Chrysler Building in New ' +
'York City was finished in 1930. It was the first structure to reach a height of 300 metres. Due to ' +
'the addition of a broadcasting aerial at the top of the tower in 1957, it is now taller than the ' +
'Chrysler Building by 5.2 metres (17 ft). Excluding transmitters, the Eiffel Tower is the second ' +
'tallest free-standing structure in France after the Millau Viaduct.';

const request = { args:  [text], options: { max_new_tokens: 100 } };
const res = await engine.run(request);
console.log(res[0]["summary_text"]);

您可以使用浏览器控制台或工具箱来运行此示例。要启用浏览器控制台，请在 about:config 中切换以下选项：devtools.chrome.enabled。要访问完整的工具箱，请设置 devtools.debugger.remote-enabled 选项。我们建议使用工具箱来访问更多工具。当工具箱连接到浏览器时，您将在启动时收到安全警告。

运行此代码时，Firefox 将在位于 https://model-hub.mozilla.org 的 Mozilla 模型中心中查找模型，该中心包含一个精选的模型列表。

可用选项¶

传递给 createEngine 函数的选项将被验证并转换为 PipelineOptions 对象。

以下是可用的选项

taskName：管道配置的任务名称。
featureId：管道将使用的功能的标识符。
engineId：管道将使用的引擎的标识符。
timeoutMS：工作程序运行的最大时间（以毫秒为单位）（-1 表示永不过期）。
modelHub：要使用的模型中心，可以是 huggingface 或 mozilla。使用时，将忽略 modelHubRootUrl 和 modelHubUrlTemplate。
modelHubRootUrl：托管模型的模型中心的根 URL。
modelHubUrlTemplate：用于构建模型完整 URL 的模板 URL。
modelId：管道将使用的特定模型的标识符。
modelRevision：管道将使用的特定模型的修订版本。
tokenizerId：与模型关联的分词器的标识符，用于预处理输入。
tokenizerRevision：与模型关联的分词器的修订版本，用于预处理输入。
processorId：模型所需的任何处理器的标识符，用于额外的输入处理。
processorRevision：模型所需的任何处理器的修订版本，用于额外的输入处理。
logLevel：工作程序中使用的日志级别
runtimeFilename：运行时 wasm 文件的名称。

taskName 和 modelId 是必需的，其他选项是可选的，并在识别任务 ID 时使用从远程设置中提取的值自动填充。

要了解不同的推理任务，请参阅此 Hugging Face 文档：任务

featureId 用于唯一标识管道将使用的功能并在远程设置中存储相应的选项 - 请参阅 ml-inference-options 集合。

engineId 用于管理引擎的生命周期。如果未提供，则默认为 default-engine。每次使用 createEngine 创建新引擎时，API 都会确保只有一个具有给定 ID 的引擎。如果现有引擎的选项没有不同，则会重用该实例。如果它们不同，则引擎将使用新选项重新初始化。这确保我们不会同时运行太多引擎，因为这需要大量资源。要确保您的引擎不会在其他地方被销毁或重用，请使用与您的组件匹配的唯一 ID 设置该值。

创建引擎时，如果推理进程尚不存在，则会创建一个推理进程，并为该引擎启动一个新的工作程序。推理进程是唯一的，并由所有引擎共享。

某些值也从首选项（在 about:config 中设置）中设置

browser.ml.logLevel：设置为“All”以查看所有日志，这些日志对调试很有用。
browser.ml.modelHubRootUrl：用于下载模型的模型中心根 URL
browser.ml.modelHubUrlTemplate：模型 URL 模板
browser.ml.modelCacheTimeout：工作程序超时时间（以毫秒为单位）。用于 timeoutMS 的默认值
browser.ml.modelCacheMaxSize：ML 模型缓存的最大磁盘大小（以 GiB 为单位）

URL 允许和拒绝列表¶

我们保留了一个名为 ml-model-allow-deny-list 的远程设置集合，其中包含允许或拒绝的 URL 前缀。

每个记录包含以下字段

urlPrefix：要允许或拒绝的 URL 前缀
filter：设置为 ALLOW 以允许，设置为 DENY 以拒绝
description：可选描述

当 API 即将获取文件时，其 URL 会在允许/拒绝列表中进行控制。

模式示例

Hugging Face 上 mozilla 组织中的所有模型的所有版本：https://hugging-face.cn/Mozilla/
我们中心的所有模型的所有版本：https://model-hub.mozilla.org/
特定模型的所有版本 https://hugging-face.cn/typeform/distilbert-base-uncased-mnli/
特定模型和特定版本 https://hugging-face.cn/Mozilla/distilvit/blob/v0.5.0/

每个 URL 都经过测试，需要包含在允许列表中，并且不能包含在拒绝列表中

要绕过此检查并允许 Firefox 下载任何文件以运行模型，您需要使用 MOZ_ALLOW_EXTERNAL_ML_HUB 环境变量。

如果您想添加新的中心、组织或特定模型，请通过提交工单告知我们。

使用 Hugging Face 模型中心¶

默认情况下，引擎将使用 Mozilla 模型中心。您需要将 huggingface 作为 modelHub 传递。

然后，推理引擎将在 Hugging Face 模型中心中查找模型。如果 URL 不被允许（请参阅上一节），并且您仍想尝试使用该模型，请使用 MOZ_ALLOW_EXTERNAL_ML_HUB。

要针对 Hugging Face 模型运行，请访问此页面并在左上角选择 tasks。您可以选择一个任务，然后选择一个模型。

例如，与我们的推理引擎兼容的 summarization 任务的模型列在此处。

假设您要选择 Xenova/distilbart-cnn-6-6 模型。您只需在调用我们的 createEngine 管道时使用 ID 即可

const { createEngine } = ChromeUtils.importESModule("chrome://global/content/ml/EngineProcess.sys.mjs");

const options = {
  taskName: "summarization",
  modelId: "Xenova/distilbart-cnn-6-6",
  modelHub: "huggingface"
};

const engine = await createEngine(options);

const text = 'The tower is 324 metres (1,063 ft) tall, about the same height as an 81-storey building, ' +
'and the tallest structure in Paris. Its base is square, measuring 125 metres (410 ft) on each side. ' +
'During its construction, the Eiffel Tower surpassed the Washington Monument to become the tallest ' +
'man-made structure in the world, a title it held for 41 years until the Chrysler Building in New ' +
'York City was finished in 1930. It was the first structure to reach a height of 300 metres. Due to ' +
'the addition of a broadcasting aerial at the top of the tower in 1957, it is now taller than the ' +
'Chrysler Building by 5.2 metres (17 ft). Excluding transmitters, the Eiffel Tower is the second ' +
'tallest free-standing structure in France after the Millau Viaduct.';

const request = { args:  [text], options: { max_new_tokens: 100 } };
const res = await engine.run(request);
console.log(res[0]["summary_text"]);

运行内部 API¶

一些推理任务在引擎中执行更复杂的操作，例如图像处理。对于这些任务，您可以使用内部 API 来运行推理。这些任务以 moz 为前缀。

在下面的示例中，使用 moz-image-to-text 任务将图像转换为文本。

const { createEngine } = ChromeUtils.importESModule("chrome://global/content/ml/EngineProcess.sys.mjs");

// options needed for the task
const options = {taskName: "moz-image-to-text" };

// We create the engine object, using the options
const engine = await createEngine(options);

// Preparing a request
const request = {url: "https://hugging-face.cn/datasets/mishig/sample_images/resolve/main/football-match.jpg"};

// At this point we are ready to do some inference.
const res = await engine.run(request);

// The result is a string containing the text extracted from the image
console.log(res);

机器学习引擎支持以下内部任务

imageToText(request, model, tokenizer, processor, _config)¶

使用机器学习模型将图像转换为文本。

参数：

request (object) – 包含图像数据的请求对象。
request.url (string) – 要处理的图像的 URL。如果未提供 url，则使用其他字段。
request.data (ArrayBuffer) – 要处理的原始图像数据。如果提供了 url，则忽略。
request.width (number) – 图像宽度。如果提供了 url，则忽略。
request.height (number) – 图像高度。如果提供了 url，则忽略。
request.channels (number) – 图像通道。可以是 1、2、3 或 4。默认为 4。如果提供了 url，则忽略。
model (object) – 用于推理的模型。
tokenizer (object) – 用于解码的分词器。
processor (object) – 用于准备图像数据的处理器。
_config (object) – 配置

返回值：

Promise.<object> – 包含已处理文本的结果对象。