Huggingface.js 文档

🤗 Hugging Face Hub API

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

🤗 Hugging Face Hub API

用于使用 Hugging Face Hub API 的官方工具。

安装

pnpm add @huggingface/hub

npm add @huggingface/hub

yarn add @huggingface/hub

Deno

// esm.sh
import { uploadFiles, listModels } from "https://esm.sh/@huggingface/hub"
// or npm:
import { uploadFiles, listModels } from "npm:@huggingface/hub"

用法

对于某些调用,您需要创建一个帐户并生成访问令牌

通过此互动教程了解如何使用 hub 包查找免费模型。

import * as hub from "@huggingface/hub";
import type { RepoDesignation } from "@huggingface/hub";

const repo: RepoDesignation = { type: "model", name: "myname/some-model" };

const {name: username} = await hub.whoAmI({accessToken: "hf_..."});

for await (const model of hub.listModels({search: {owner: username}, accessToken: "hf_..."})) {
  console.log("My model:", model);
}

const specificModel = await hub.modelInfo({name: "openai-community/gpt2"});
await hub.checkRepoAccess({repo, accessToken: "hf_..."});

await hub.createRepo({ repo, accessToken: "hf_...", license: "mit" });

await hub.uploadFiles({
  repo,
  accessToken: "hf_...",
  files: [
    // path + blob content
    {
      path: "file.txt",
      content: new Blob(["Hello World"]),
    },
    // Local file URL
    pathToFileURL("./pytorch-model.bin"),
    // Local folder URL
    pathToFileURL("./models"),
    // Web URL
    new URL("https://huggingface.co/xlm-roberta-base/resolve/main/tokenizer.json"),
    // Path + Web URL
    {
      path: "myfile.bin",
      content: new URL("https://huggingface.co/bert-base-uncased/resolve/main/pytorch_model.bin")
    }
    // Can also work with native File in browsers
  ],
});

// or

for await (const progressEvent of await hub.uploadFilesWithProgress({
  repo,
  accessToken: "hf_...",
  files: [
    ...
  ],
})) {
  console.log(progressEvent);
}

await hub.deleteFile({repo, accessToken: "hf_...", path: "myfile.bin"});

await (await hub.downloadFile({ repo, path: "README.md" })).text();

for await (const fileInfo of hub.listFiles({repo})) {
  console.log(fileInfo);
}

await hub.deleteRepo({ repo, accessToken: "hf_..." });

CLI 用法

您可以在 CLI 模式下使用 `huggingface/hub` 将文件和文件夹上传到您的仓库。

npx @huggingface/hub upload coyotte508/test-model .
npx @huggingface/hub upload datasets/coyotte508/test-dataset .
# Same thing
npx @huggingface/hub upload --repo-type dataset coyotte508/test-dataset .
# Upload new data with 0 history in a separate branch
npx @huggingface/hub branch create coyotte508/test-model release --empty
npx @huggingface/hub upload coyotte508/test-model . --revision release

npx @huggingface/hub --help
npx @huggingface/hub upload --help

您也可以使用 `npm install -g @huggingface/hub` 全局安装。然后您可以执行:

hfjs upload coyotte508/test-model .

hfjs branch create --repo-type dataset coyotte508/test-dataset release --empty
hfjs upload --repo-type dataset coyotte508/test-dataset . --revision release

hfjs --help
hfjs  upload --help

OAuth 登录

可以使用 OAuth(“通过 HF 登录”)进行登录。

这将允许您获取访问令牌以使用部分 API,具体取决于 Space 或 OAuth App 中设置的范围。

import { oauthLoginUrl, oauthHandleRedirectIfPresent } from "@huggingface/hub";

const oauthResult = await oauthHandleRedirectIfPresent();

if (!oauthResult) {
  // If the user is not logged in, redirect to the login page
  window.location.href = await oauthLoginUrl();
}

// You can use oauthResult.accessToken, oauthResult.accessTokenExpiresAt and oauthResult.userInfo
console.log(oauthResult);

查看演示:https://huggingface.co/spaces/huggingfacejs/client-side-oauth

Hugging Face 缓存

`@huggingface/hub` 包提供了扫描缓存目录的基本功能。了解更多关于管理 huggingface_hub 缓存系统

scanCacheDir

您可以使用 `scanCacheDir` 函数获取缓存的仓库列表。

import { scanCacheDir } from "@huggingface/hub";

const result = await scanCacheDir();

console.log(result);

注意:这在浏览器中不起作用。

downloadFileToCacheDir

您可以使用 `downloadFileToCacheDir` 函数缓存仓库文件。

import { downloadFileToCacheDir } from "@huggingface/hub";

const file = await downloadFileToCacheDir({
  repo: 'foo/bar',
  path: 'README.md'
});

console.log(file);

注意:这在浏览器中不起作用。

snapshotDownload

您可以使用 `snapshotDownload` 函数在缓存目录中下载给定修订版的整个仓库。

import { snapshotDownload } from "@huggingface/hub";

const directory = await snapshotDownload({
  repo: 'foo/bar',
});

console.log(directory);

该代码内部使用 `downloadFileToCacheDir` 函数。

注意:这在浏览器中不起作用。

性能考量

上传大型文件时,您可能希望在 worker 中运行 `commit` 调用,以卸载 sha256 计算。

远程资源和本地文件应尽可能以 `URL` 形式传递,以便它们可以分块延迟加载以减少 RAM 使用。在浏览器上下文中传递 `File` 是可以的,因为它本身就表现为 `Blob`。

在底层,`@huggingface/hub` 使用惰性 Blob 实现来加载文件。

依赖

  • @huggingface/tasks:仅类型定义
  • @huggingface/lz4:URL 连接工具
< > 在 GitHub 上更新