Huggingface.js 文档
🤗 Hugging Face Hub API
并获得增强的文档体验
开始使用
🤗 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 连接工具