From 5100ee4aa6f20066359446e98db2fa39c5581bd0 Mon Sep 17 00:00:00 2001 From: King guys <68528929+2404589803@users.noreply.github.com> Date: Wed, 20 Dec 2023 22:57:49 +0800 Subject: [PATCH] [i18n-CN] Translated some files to implified Chinese #1915 (#1916) * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * upfate file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file * update file --------- Co-authored-by: King guys <68528929+jimtom40395@users.noreply.github.com> Co-authored-by: Lucain --- .github/workflows/build_documentation.yaml | 2 +- README.md | 3 +- README_cn.md | 156 +++++++++++++ README_de.md | 3 +- README_hi.md | 3 +- README_ko.md | 3 +- docs/source/cn/_toctree.yml | 16 ++ docs/source/cn/concepts/git_vs_http.md | 40 ++++ docs/source/cn/guides/repository.md | 246 +++++++++++++++++++++ docs/source/cn/index.md | 44 ++++ docs/source/cn/installation.md | 142 ++++++++++++ docs/source/cn/quick-start.md | 128 +++++++++++ 12 files changed, 781 insertions(+), 5 deletions(-) create mode 100644 README_cn.md create mode 100644 docs/source/cn/_toctree.yml create mode 100644 docs/source/cn/concepts/git_vs_http.md create mode 100644 docs/source/cn/guides/repository.md create mode 100644 docs/source/cn/index.md create mode 100644 docs/source/cn/installation.md create mode 100644 docs/source/cn/quick-start.md diff --git a/.github/workflows/build_documentation.yaml b/.github/workflows/build_documentation.yaml index 775716b0e6..127431ac6f 100644 --- a/.github/workflows/build_documentation.yaml +++ b/.github/workflows/build_documentation.yaml @@ -13,6 +13,6 @@ jobs: with: commit_sha: ${{ github.sha }} package: huggingface_hub - languages: en de hi ko + languages: en de hi ko cn secrets: hf_token: ${{ secrets.HF_DOC_BUILD_PUSH }} diff --git a/README.md b/README.md index 9ae92db4c8..92d184ae1b 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,8 @@ English | Deutsch | हिंदी | - 한국어 + 한국어 | + 中文（简体）

--- diff --git a/README_cn.md b/README_cn.md new file mode 100644 index 0000000000..acbf406d89 --- /dev/null +++ b/README_cn.md @@ -0,0 +1,156 @@ +

+
+ huggingface_hub library logo +
+

+ +

+ Hugging Face Hub Python 客户端 +

+ +

+ Documentation + GitHub release + PyPi version + downloads + Code coverage +

+ +

+

+ English | + Deutsch | + हिंदी | + 한국어 | + 中文（简体） +

+

+--- + +**文档**: ``https://hf.co/docs/huggingface_hub `` + +**源代码**: ``https://github.com/huggingface/huggingface_hub `` + +--- + +## 欢迎使用 Hugging Face Hub 库 + +通过`huggingface_hub` 库，您可以与面向机器学习开发者和协作者的平台 [Hugging Face Hub](https://huggingface.co/)进行交互，找到适用于您所在项目的预训练模型和数据集，体验在平台托管的数百个机器学习应用，还可以创建或分享自己的模型和数据集并于社区共享。以上所有都可以用Python在`huggingface_hub` 库中轻松实现。 + +## 主要特点 + +- [从hugging face hub下载文件](https://huggingface.co/docs/huggingface_hub/en/guides/download) +- [上传文件到 hugging face hub](https://huggingface.co/docs/huggingface_hub/en/guides/upload) +- [管理您的存储库](https://huggingface.co/docs/huggingface_hub/en/guides/repository) +- [在部署的模型上运行推断](https://huggingface.co/docs/huggingface_hub/en/guides/inference) +- [搜索模型、数据集和空间](https://huggingface.co/docs/huggingface_hub/en/guides/search) +- [分享模型卡片](https://huggingface.co/docs/huggingface_hub/en/guides/model-cards) +- [社区互动](https://huggingface.co/docs/huggingface_hub/en/guides/community) + +## 安装 + +使用pip安装 `huggingface_hub` 包： + +```bash +pip install huggingface_hub +``` + +如果您更喜欢，也可以使用 conda 进行安装 + +为了默认保持包的最小化，huggingface_hub 带有一些可选的依赖项，适用于某些用例。例如，如果您想要完整的推断体验，请运行： + +```bash +pip install huggingface_hub[inference] +``` + +要了解更多安装和可选依赖项，请查看[安装指南](https://huggingface.co/docs/huggingface_hub/cn/安装) + +## 快速入门指南 + +### 下载文件 + +下载单个文件,请运行以下代码： + +```py +from huggingface_hub import hf_hub_download + +hf_hub_download(repo_id="tiiuae/falcon-7b-instruct", filename="config.json") +``` + +如果下载整个存储库，请运行以下代码： + +```py +from huggingface_hub import snapshot_download + +snapshot_download("stabilityai/stable-diffusion-2-1") +``` + +文件将被下载到本地缓存文件夹。更多详细信息请参阅此 [指南](https://huggingface.co/docs/huggingface_hub/en/guides/manage-cache). + +### 登录 + +Hugging Face Hub 使用令牌对应用进行身份验证(请参阅[文档](https://huggingface.co/docs/hub/security-tokens)). 要登录您的机器，请运行以下命令行： + +```bash +huggingface-cli login +# or using an environment variable +huggingface-cli login --token $HUGGINGFACE_TOKEN +``` + +### 创建一个存储库 + +要创建一个新存储库，请运行以下代码： + +```py +from huggingface_hub import create_repo + +create_repo(repo_id="super-cool-model") +``` + +### 上传文件 + +上传单个文件,请运行以下代码 + +```py +from huggingface_hub import upload_file + +upload_file( + path_or_fileobj="/home/lysandre/dummy-test/README.md", + path_in_repo="README.md", + repo_id="lysandre/test-model", +) +``` + +如果上传整个存储库，请运行以下代码： + +```py +from huggingface_hub import upload_folder + +upload_folder( + folder_path="/path/to/local/space", + repo_id="username/my-cool-space", + repo_type="space", +) +``` + +有关详细信息，请查看 [上传指南](https://huggingface.co/docs/huggingface_hub/en/guides/upload). + +## 集成到 Hub 中 + +我们正在与一些出色的开源机器学习库合作，提供免费的模型托管和版本控制。您可以在 [这里](https://huggingface.co/docs/hub/libraries)找到现有的集成 + +优势包括: + +- 为库及其用户提供免费的模型或数据集托管 +- 内置文件版本控制，即使对于非常大的文件也能实现，这得益于基于 Git 的方法 +- 为所有公开可用的模型提供托管的推断 API +- 在网页端可在线体验所有公开的模型 +- 任何人都可以上传新模型到您的库，他们只需为模型添加相应的标签，以便让其被发现 +- 快速下载！我们使用 Cloudfront（CDN）进行地理复制下载，因此无论在全球任何地方，下载速度都非常快。 +- 使用统计和更多功能即将推出 + +如果您想要集成您的库，请随时打开一个问题来开始讨论。我们编写了一份逐步指南，以❤️的方式展示如何进行这种集成。 + +## 欢迎各种贡献（功能请求、错误等） 💙💚💛💜🧡❤️ + +欢迎每个人来进行贡献，我们重视每个人的贡献。编写代码并非唯一的帮助社区的方式。回答问题、帮助他人、积极互动并改善文档对社区来说都是极其有价值的。为此我们编写了一份 [贡献指南](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) 以进行总结，即如何开始为这个存储库做贡献 diff --git a/README_de.md b/README_de.md index 1a98cb16c3..1bcc680277 100644 --- a/README_de.md +++ b/README_de.md @@ -21,7 +21,8 @@ English | Deutsch | हिंदी | - 한국인 + 한국인 | + 中文（简体）

--- diff --git a/README_hi.md b/README_hi.md index 00a089b4c7..c14c187c20 100644 --- a/README_hi.md +++ b/README_hi.md @@ -21,7 +21,8 @@ English | Deutsch | हिंदी | - 한국어 + 한국어 | + 中文（简体）

diff --git a/README_ko.md b/README_ko.md index ba64cfcb37..a5c1e358ac 100644 --- a/README_ko.md +++ b/README_ko.md @@ -21,7 +21,8 @@ English | Deutsch | हिंदी | - 한국어 + 한국어| + 中文（简体）

diff --git a/docs/source/cn/_toctree.yml b/docs/source/cn/_toctree.yml new file mode 100644 index 0000000000..1b070b1544 --- /dev/null +++ b/docs/source/cn/_toctree.yml @@ -0,0 +1,16 @@ +- title: "Starten" + sections: + - local: index + title: 索引 + - local: quick-start + title: 快速入门指南 + - local: installation + title: 安装 +- title: "guides" + sections: + - local: guides/repository + title: 储存库 +- title: "concepts" + sections: + - local: concepts/git_vs_http + title: Git vs HTTP 范式 \ No newline at end of file diff --git a/docs/source/cn/concepts/git_vs_http.md b/docs/source/cn/concepts/git_vs_http.md new file mode 100644 index 0000000000..8509309b76 --- /dev/null +++ b/docs/source/cn/concepts/git_vs_http.md @@ -0,0 +1,40 @@ + + +# Git 与 HTTP 范式 + +`huggingface_hub`库是用于与Hugging Face Hub进行交互的库，Hugging Face Hub是一组基于Git的存储库（模型、数据集或Spaces）。使用 `huggingface_hub`有两种主要方式来访问Hub。 + +第一种方法，即所谓的“基于git”的方法，由[`Repository`]类驱动。这种方法使用了一个包装器，它在 `git`命令的基础上增加了专门与Hub交互的额外函数。第二种选择，称为“基于HTTP”的方法，涉及使用[`HfApi`]客户端进行HTTP请求。让我们来看一看每种方法的优缺点。 + +## 存储库：基于历史的 Git 方法 + +最初，`huggingface_hub`主要围绕 [`Repository`] 类构建。它为常见的 `git` 命令（如 `"git add"`、`"git commit"`、`"git push"`、`"git tag"`、`"git checkout"` 等）提供了 Python 包装器 + +该库还可以帮助设置凭据和跟踪大型文件，这些文件通常在机器学习存储库中使用。此外，该库允许您在后台执行其方法，使其在训练期间上传数据很有用。 + +使用 [`Repository`] 的最大优点是它允许你在本地机器上维护整个存储库的本地副本。这也可能是一个缺点，因为它需要你不断更新和维护这个本地副本。这类似于传统软件开发中，每个开发人员都维护自己的本地副本，并在开发功能时推送更改。但是，在机器学习的上下文中，这可能并不总是必要的，因为用户可能只需要下载推理所需的权重，或将权重从一种格式转换为另一种格式，而无需克隆整个存储库。 + +## HfApi: 一个功能强大且方便的HTTP客户端 + +`HfApi` 被开发为本地 git 存储库的替代方案，因为本地 git 存储库在处理大型模型或数据集时可能会很麻烦。`HfApi` 提供与基于 git 的方法相同的功能，例如下载和推送文件以及创建分支和标签，但无需本地文件夹来保持同步。 + +`HfApi`除了提供 `git` 已经提供的功能外，还提供其他功能，例如： + +* 管理存储库 +* 使用缓存下载文件以进行有效的重复使用 +* 在 Hub 中搜索存储库和元数据 +* 访问社区功能，如讨论、PR和评论 +* 配置Spaces + +## 我应该使用什么？以及何时使用？ + +总的来说，在大多数情况下，`HTTP 方法`是使用 huggingface_hub 的推荐方法。但是，在以下几种情况下，维护本地 git 克隆（使用 `Repository`）可能更有益： + +如果您在本地机器上训练模型，使用传统的 git 工作流程并定期推送更新可能更有效。`Repository` 被优化为此类情况，因为它能够在后台运行。 +如果您需要手动编辑大型文件，`git `是最佳选择，因为它只会将文件的差异发送到服务器。使用 `HfAPI` 客户端，每次编辑都会上传整个文件。请记住，大多数大型文件是二进制文件，因此无法从 git 差异中受益。 + +并非所有 git 命令都通过 [`HfApi`] 提供。有些可能永远不会被实现，但我们一直在努力改进并缩小差距。如果您没有看到您的用例被覆盖。 + +请在[Github](https://github.com/huggingface/huggingface_hub)打开一个 issue！我们欢迎反馈，以帮助我们与我们的用户一起构建 🤗 生态系统。 diff --git a/docs/source/cn/guides/repository.md b/docs/source/cn/guides/repository.md new file mode 100644 index 0000000000..aa1f3b3dff --- /dev/null +++ b/docs/source/cn/guides/repository.md @@ -0,0 +1,246 @@ + + +# 创建和管理存储库 + +Hugging Face Hub是一组 Git 存储库。[Git](https://git-scm.com/)是软件开发中广泛使用的工具，可以在协作工作时轻松对项目进行版本控制。本指南将向您展示如何与 Hub 上的存储库进行交互，特别关注以下内容： + +- 创建和删除存储库 +- 管理分支和标签 +- 重命名您的存储库 +- 更新您的存储库可见性 +- 管理存储库的本地副本 + + + +如果您习惯于使用类似于GitLab/GitHub/Bitbucket等平台，您可能首先想到使用 `git`命令行工具来克隆存储库（`git clone`）、提交更改（`git add` , ` git commit`）并推送它们（`git push`）。在使用 Hugging Face Hub 时，这是有效的。然而，软件工程和机器学习并不具有相同的要求和工作流程。模型存储库可能会维护大量模型权重文件以适应不同的框架和工具，因此克隆存储库会导致您维护大量占用空间的本地文件夹。因此，使用我们的自定义HTTP方法可能更有效。您可以阅读我们的[git与HTTP相比较](../concepts/git_vs_http)解释页面以获取更多详细信息 + + + +如果你想在Hub上创建和管理一个仓库，你的计算机必须处于登录状态。如果尚未登录，请参考[此部分](../quick-start#login)。在本指南的其余部分，我们将假设你的计算机已登录 + +## 仓库创建和删除 + +第一步是了解如何创建和删除仓库。你只能管理你拥有的仓库（在你的用户名命名空间下）或者你具有写入权限的组织中的仓库 + +### 创建一个仓库 + +使用 [`create_repo`] 创建一个空仓库，并通过 `repo_id`参数为其命名 `repo_id`是你的命名空间，后面跟着仓库名称：`username_or_org/repo_name` + +运行以下代码，以创建仓库： + +```py +>>> from huggingface_hub import create_repo +>>> create_repo("lysandre/test-model") +'https://huggingface.co/lysandre/test-model' +``` + +默认情况下，[`create_repo`] 会创建一个模型仓库。但是你可以使用 `repo_type`参数来指定其他仓库类型。例如，如果你想创建一个数据集仓库 + +请运行以下代码： + +```py +>>> from huggingface_hub import create_repo +>>> create_repo("lysandre/test-dataset", repo_type="dataset") +'https://huggingface.co/datasets/lysandre/test-dataset' +``` + +创建仓库时，你可以使用 `private`参数设置仓库的可见性 + +请运行以下代码 + +```py +>>> from huggingface_hub import create_repo +>>> create_repo("lysandre/test-private", private=True) +``` + +如果你想在以后更改仓库的可见性，你可以使用[`update_repo_visibility`] 函数 + +### 删除一个仓库 + +使用 [`delete_repo`] 删除一个仓库。确保你确实想要删除仓库，因为这是一个不可逆转的过程！做完上述过程后，指定你想要删除的仓库的 `repo_id` + +请运行以下代码： + +```py +>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset") +``` + +### 克隆一个仓库（仅适用于 Spaces） + +在某些情况下，你可能想要复制别人的仓库并根据自己的用例进行调整。对于 Spaces，你可以使用 [`duplicate_space`] 方法来实现。它将复制整个仓库。 + +你仍然需要配置自己的设置（硬件和密钥）。查看我们的[管理你的Space指南](./manage-spaces)以获取更多详细信息。 + +请运行以下代码： + +```py +>>> from huggingface_hub import duplicate_space +>>> duplicate_space("multimodalart/dreambooth-training", private=False) +RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...) +``` + +## 上传和下载文件 + +既然您已经创建了您的存储库，您现在也可以推送更改至其中并从中下载文件 + +这两个主题有它们自己的指南。请[上传指南](./upload) 和[下载指南](./download)来学习如何使用您的存储库。 + +## 分支和标签 + +Git存储库通常使用分支来存储同一存储库的不同版本。标签也可以用于标记存储库的特定状态，例如，在发布版本这个情况下。更一般地说，分支和标签被称为[git引用](https://git-scm.com/book/en/v2/Git-Internals-Git-References). + +### 创建分支和标签 + +你可以使用[`create_branch`]和[`create_tag`]来创建新的分支和标签: + +请运行以下代码： + +```py +>>> from huggingface_hub import create_branch, create_tag + +# Create a branch on a Space repo from `main` branch +>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker") + +# Create a tag on a Dataset repo from `v0.1-release` branch +>>> create_branch("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.") +``` + +同时,你可以以相同的方式使用 [`delete_branch`] 和 [`delete_tag`] 函数来删除分支或标签 + +### 列出所有的分支和标签 + +你还可以使用 [`list_repo_refs`] 列出存储库中的现有 Git 引用 +请运行以下代码： + +```py +>>> from huggingface_hub import list_repo_refs +>>> api.list_repo_refs("bigcode/the-stack", repo_type="dataset") +GitRefs( + branches=[ + GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'), + GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714') + ], + converts=[], + tags=[ + GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da') + ] +) +``` + +## 修改存储库设置 + +存储库具有一些可配置的设置。大多数情况下，您通常会在浏览器中的存储库设置页面上手动配置这些设置。要配置存储库，您必须具有对其的写访问权限（拥有它或属于组织）。在本节中，我们将看到您还可以使用 `huggingface_hub` 在编程方式上配置的设置。 + +一些设置是特定于 Spaces（硬件、环境变量等）的。要配置这些设置，请参考我们的[管理Spaces](../guides/manage-spaces)指南。 + +### 更新可见性 + +一个存储库可以是公共的或私有的。私有存储库仅对您或存储库所在组织的成员可见。 + +请运行以下代码将存储库更改为私有： + +```py +>>> from huggingface_hub import update_repo_visibility +>>> update_repo_visibility(repo_id=repo_id, private=True) +``` + +### 重命名您的存储库 + +您可以使用 [`move_repo`] 在 Hub 上重命名您的存储库。使用这种方法，您还可以将存储库从一个用户移动到一个组织。在这样做时，有一些[限制](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo)需要注意。例如，您不能将存储库转移到另一个用户。 + +请运行以下代码： + +```py +>>> from huggingface_hub import move_repo +>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model") +``` + +## 管理存储库的本地副本 + +上述所有操作都可以通过HTTP请求完成。然而，在某些情况下，您可能希望在本地拥有存储库的副本，并使用您熟悉的Git命令与之交互。 + +[`Repository`] 类允许您使用类似于Git命令的函数与Hub上的文件和存储库进行交互。它是对Git和Git-LFS方法的包装，以使用您已经了解和喜爱的Git命令。在开始之前，请确保已安装Git-LFS（请参阅[此处](https://git-lfs.github.com/)获取安装说明）。 + +### 使用本地存储库 + +使用本地存储库路径实例化一个 [`Repository`] 对象： + +请运行以下代码： + +```py +>>> from huggingface_hub import Repository +>>> repo = Repository(local_dir="//") +``` + +### 克隆 + +`clone_from`参数将一个存储库从Hugging Face存储库ID克隆到由 `local_dir`参数指定的本地目录： + +请运行以下代码： + +```py +>>> from huggingface_hub import Repository +>>> repo = Repository(local_dir="w2v2", clone_from="facebook/wav2vec2-large-960h-lv60") +``` +`clone_from`还可以使用URL克隆存储库： + +请运行以下代码： + +```py +>>> repo = Repository(local_dir="huggingface-hub", clone_from="https://huggingface.co/facebook/wav2vec2-large-960h-lv60") +``` + +你可以将`clone_from`参数与[`create_repo`]结合使用，以创建并克隆一个存储库： + +请运行以下代码： + +```py +>>> repo_url = create_repo(repo_id="repo_name") +>>> repo = Repository(local_dir="repo_local_path", clone_from=repo_url) +``` + +当你克隆一个存储库时，通过在克隆时指定`git_user`和`git_email`参数，你还可以为克隆的存储库配置Git用户名和电子邮件。当用户提交到该存储库时，Git将知道提交的作者是谁。 + +请运行以下代码： + +```py +>>> repo = Repository( +... "my-dataset", +... clone_from="/", +... token=True, +... repo_type="dataset", +... git_user="MyName", +... git_email="me@cool.mail" +... ) +``` + +### 分支 + +分支对于协作和实验而不影响当前文件和代码非常重要。使用[`~Repository.git_checkout`]来在不同的分支之间切换。例如，如果你想从 `branch1`切换到 `branch2`： + +请运行以下代码： + +```py +>>> from huggingface_hub import Repository +>>> repo = Repository(local_dir="huggingface-hub", clone_from="/", revision='branch1') +>>> repo.git_checkout("branch2") +``` + +### 拉取 + +[`~Repository.git_pull`] 允许你使用远程存储库的更改更新当前本地分支： + +请运行以下代码： + +```py +>>> from huggingface_hub import Repository +>>> repo.git_pull() +``` + +如果你希望本地的提交发生在你的分支被远程的新提交更新之后，请设置`rebase=True`： + +```py +>>> repo.git_pull(rebase=True) +``` diff --git a/docs/source/cn/index.md b/docs/source/cn/index.md new file mode 100644 index 0000000000..942f520577 --- /dev/null +++ b/docs/source/cn/index.md @@ -0,0 +1,44 @@ + + +# 🤗 Hub 客户端库 + +通过`huggingface_hub` 库，您可以与面向机器学习开发者和协作者的平台 [Hugging Face Hub](https://huggingface.co/)进行交互，找到适用于您所在项目的预训练模型和数据集，体验在平台托管的数百个机器学习应用，还可以创建或分享自己的模型和数据集并于社区共享。以上所有都可以用Python在`huggingface_hub` 库中轻松实现。 + +阅读[快速入门指南](快速入门指南)以开始使用huggingface_hub库。您将学习如何从Hub下载文件,创建存储库以及将文件上传到Hub。继续阅读以了解更多关于如何在🤗Hub上管理您的存储库,如何参与讨论或者甚至如何访问推理API的信息。 + +

+
+ + `` + `
`How-to guides`
` + `

`Practical guides to help you achieve a specific goal. Take a look at these guides to learn how to use huggingface_hub to solve real-world problems.`

` + `` + + `` + `
`Reference`
` + `

`Exhaustive and technical description of huggingface_hub classes and methods.`

` + `` + + `` + `
`Conceptual guides`
` + `

`High-level explanations for building a better understanding of huggingface_hub philosophy.`

` + `` + +
+
+ +通过 `huggingface_hub`库，您可以与面向机器学习开发者和协作者的平台 [Hugging Face Hub](https://huggingface.co/)进行交互，找到适用于您所在项目的预训练模型和数据集，体验在平台托管的数百个机器学习应用，还可以创建或分享自己的模型和数据集并于社区共享。以上所有都可以用Python在 `huggingface_hub`库中轻松实现。 + + + +## 贡献 + +所有对 huggingface_hub 的贡献都受到欢迎和同等重视！🤗 除了在代码中添加或修复现有问题外，您还可以通过确保其准确且最新来帮助改进文档，在问题上帮助回答问题，并请求您认为可以改进库的新功能。请查看[贡献指南](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) 了解有关如何提交新问题或功能请求、如何提交拉取请求以及如何测试您的贡献以确保一切正常运行的更多信息。 + +当然，贡献者也应该尊重我们的[行为准则](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md)，以便为每个人创建一个包容和欢迎的协作空间。 diff --git a/docs/source/cn/installation.md b/docs/source/cn/installation.md new file mode 100644 index 0000000000..9ee40251b0 --- /dev/null +++ b/docs/source/cn/installation.md @@ -0,0 +1,142 @@ + + +# 安装 + +在开始之前，您需要通过安装适当的软件包来设置您的环境 + +huggingface_hub 在 Python 3.8 或更高版本上进行了测试，可以保证在这些版本上正常运行。如果您使用的是 Python 3.7 或更低版本，可能会出现兼容性问题 + +## 使用 pip 安装 + +我们建议将huggingface_hub安装在[虚拟环境](https://docs.python.org/3/library/venv.html)中. +如果你不熟悉 Python虚拟环境,可以看看这个[指南](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). + +虚拟环境可以更容易地管理不同的项目,避免依赖项之间的兼容性问题 + +首先在你的项目目录中创建一个虚拟环境,请运行以下代码: + +```bash +python -m venv .env +``` + +在Linux和macOS上,请运行以下代码激活虚拟环境: + +```bash +source .env/bin/activate +``` + +在 Windows 上，请运行以下代码激活虚拟环境: + +```bash +.env/Scripts/activate +``` + +现在您可以从[PyPi注册表](https://pypi.org/project/huggingface-hub/)安装 `huggingface_hub`： + +```bash +pip install --upgrade huggingface_hub +``` + +完成后,[检查安装](#check-installation)是否正常工作 + +### 安装可选依赖项 + +`huggingface_hub`的某些依赖项是 [可选](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) 的，因为它们不是运行`huggingface_hub`的核心功能所必需的.但是，如果没有安装可选依赖项， `huggingface_hub` 的某些功能可能会无法使用 + +您可以通过`pip`安装可选依赖项,请运行以下代码： + +```bash +# 安装 TensorFlow 特定功能的依赖项 +# /!\ 注意：这不等同于 `pip install tensorflow` +pip install 'huggingface_hub[tensorflow]' + +# 安装 TensorFlow 特定功能和 CLI 特定功能的依赖项 +pip install 'huggingface_hub[cli,torch]' +``` + +这里列出了 `huggingface_hub` 的可选依赖项： + +- `cli`：为 `huggingface_hub` 提供更方便的命令行界面 + +- `fastai`,` torch`, `tensorflow`: 运行框架特定功能所需的依赖项 + +- `dev`：用于为库做贡献的依赖项。包括 `testing`（用于运行测试）、`typing`（用于运行类型检查器）和 `quality`（用于运行 linter） + +### 从源代码安装 + +在某些情况下，直接从源代码安装`huggingface_hub`会更有趣。因为您可以使用最新的主版本`main`而非最新的稳定版本 + +`main`版本更有利于跟进平台的最新开发进度，例如，在最近一次官方发布之后和最新的官方发布之前所修复的某个错误 + +但是，这意味着`main`版本可能不总是稳定的。我们会尽力让其正常运行，大多数问题通常会在几小时或一天内解决。如果您遇到问题，请创建一个 Issue ，以便我们可以更快地解决！ + +```bash +pip install git+https://github.com/huggingface/huggingface_hub # 使用pip从GitHub仓库安装Hugging Face Hub库 +``` + +从源代码安装时，您还可以指定特定的分支。如果您想测试尚未合并的新功能或新错误修复，这很有用 + +```bash +pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch # 使用pip从指定的GitHub分支（my-feature-branch）安装Hugging Face Hub库 +``` + +完成安装后，请[检查安装](#check-installation)是否正常工作 + +### 可编辑安装 + +从源代码安装允许您设置[可编辑安装](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs).如果您计划为`huggingface_hub`做出贡献并需要测试代码更改，这是一个更高级的安装方式。您需要在本机上克隆一个`huggingface_hub`的本地副本 + +```bash +# 第一，使用以下命令克隆代码库 +git clone https://github.com/huggingface/huggingface_hub.git + +# 然后，使用以下命令启动虚拟环境 +cd huggingface_hub +pip install -e . +``` + +这些命令将你克隆存储库的文件夹与你的 Python 库路径链接起来。Python 现在将除了正常的库路径之外，还会在你克隆到的文件夹中查找。例如，如果你的 Python 包通常安装在`./.venv/lib/python3.11/site-packages/`中，Python 还会搜索你克隆的文件夹`./huggingface_hub/` + +## 通过 conda 安装 + +如果你更熟悉它，你可以使用[conda-forge channel](https://anaconda.org/conda-forge/huggingface_hub)渠道来安装 `huggingface_hub` + +请运行以下代码： + +```bash +conda install -c conda-forge huggingface_hub +``` +完成安装后，请[检查安装](#check-installation)是否正常工作 + +## 验证安装 + +安装完成后，通过运行以下命令检查`huggingface_hub`是否正常工作: + +```bash +python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" +``` + +这个命令将从 Hub 获取有关 [gpt2](https://huggingface.co/gpt2) 模型的信息。 + +输出应如下所示： + +```text +Model Name: gpt2 模型名称 +Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space'] 标签 +Task: text-generation 任务：文本生成 +``` + +## Windows局限性 + +为了实现让每个人都能使用机器学习的目标，我们构建了 `huggingface_hub`库，使其成为一个跨平台的库，尤其可以在 Unix 和 Windows 系统上正常工作。但是，在某些情况下，`huggingface_hub`在Windows上运行时会有一些限制。以下是一些已知问题的完整列表。如果您遇到任何未记录的问题，请打开 [Github上的issue](https://github.com/huggingface/huggingface_hub/issues/new/choose).让我们知道 + +- `huggingface_hub`的缓存系统依赖于符号链接来高效地缓存从Hub下载的文件。在Windows上，您必须激活开发者模式或以管理员身份运行您的脚本才能启用符号链接。如果它们没有被激活，缓存系统仍然可以工作，但效率较低。有关更多详细信息，请阅读[缓存限制](./guides/manage-cache#limitations)部分。 + +- Hub上的文件路径可能包含特殊字符（例如:`path/to?/my/file`）。Windows对[特殊字符](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names)更加严格，这使得在Windows上下载这些文件变得不可能。希望这是罕见的情况。如果您认为这是一个错误，请联系存储库所有者或我们，以找出解决方案。 + + +## 后记 + +一旦您在机器上正确安装了`huggingface_hub`，您可能需要[配置环境变量](package_reference/environment_variables)或者[查看我们的指南之一](guides/overview)以开始使用。 \ No newline at end of file diff --git a/docs/source/cn/quick-start.md b/docs/source/cn/quick-start.md new file mode 100644 index 0000000000..f24f49bac7 --- /dev/null +++ b/docs/source/cn/quick-start.md @@ -0,0 +1,128 @@ + + +# 快速入门 + +[Hugging Face Hub](https://huggingface.co/)是分享机器学习模型、演示、数据集和指标的首选平台`huggingface_hub`库帮助你在不离开开发环境的情况下与 Hub 进行交互。你可以轻松地创建和管理仓库,下载和上传文件,并从 Hub 获取有用的模型和数据集元数据 + +## 安装 + +要开始使用,请安装`huggingface_hub`库: + +```bash +pip install --upgrade huggingface_hub +``` + +更多详细信息,请查看[安装指南](installation) + +## 下载文件 + +Hugging Face 平台上的存储库是使用 git 版本控制的，用户可以下载单个文件或整个存储库。您可以使用 [`hf_hub_download`] 函数下载文件。该函数将下载并将文件缓存在您的本地磁盘上。下次您需要该文件时，它将从您的缓存中加载，因此您无需重新下载它 + +您将需要填写存储库 ID 和您要下载的文件的文件名。例如，要下载[Pegasus](https://huggingface.co/google/pegasus-xsum)模型配置文件，请运行以下代码： + +```py +>>> from huggingface_hub import hf_hub_download +>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") +repo_id: 仓库的 ID 或路径，这里使用了 "google/pegasus-xsum" +filename: 要下载的文件名，这里是 "config.json" +``` + +要下载文件的特定版本，请使用`revision`参数指定分支名称、标签或提交哈希。如果您选择使用提交哈希，它必须是完整长度的哈希，而不是较短的7个字符的提交哈希： + +```py +>>> from huggingface_hub import hf_hub_download +>>> hf_hub_download( +... repo_id="google/pegasus-xsum", +... filename="config.json", +... revision="4d33b01d79672f27f001f6abade33f22d993b151" +... ) +``` + +有关更多详细信息和选项，请参阅 [`hf_hub_download`] 的 API 参考文档 + +## 登录 + +在许多情况下，您必须使用 Hugging Face 帐户进行登录后才能与 Hugging Face 模型库进行交互，例如下载私有存储库、上传文件、创建 PR 等。如果您还没有帐户，请[创建一个](https://huggingface.co/join),然后登录以获取您的 [用户访问令牌](https://huggingface.co/docs/hub/security-tokens),security-tokens从您的[设置页面](https://huggingface.co/settings/tokens)进入设置,用户访问令牌用于向模型库进行身份验证 + +运行以下代码，这将使用您的用户访问令牌登录到Hugging Face模型库 + +```bash +huggingface-cli login + +huggingface-cli login --token $HUGGINGFACE_TOKEN +``` + +或者，你可以在笔记本电脑或脚本中使用 [`login`] 来进行程序化登录,请运行以下代码: + +```py +>>> from huggingface_hub import login +>>> login() +``` + +您还可以直接将令牌传递给 [`login`]，如下所示：`login(token="hf_xxx")`。这将使用您的用户访问令牌登录到 Hugging Face 模型库，而无需您输入任何内容。但是，如果您这样做，请在共享源代码时要小心。最好从安全保管库中加载令牌，而不是在代码库/笔记本中显式保存它 + +您一次只能登录一个帐户。如果您使用另一个帐户登录您的机器，您将会从之前的帐户注销。请确保使用命令 `huggingface-cli whoami`来检查您当前使用的是哪个帐户。如果您想在同一个脚本中处理多个帐户，您可以在调用每个方法时提供您的令牌。这对于您不想在您的机器上存储任何令牌也很有用 + + + +一旦您登录了，所有对模型库的请求（即使是不需要认证的方法）都将默认使用您的访问令牌。如果您想禁用对令牌的隐式使用，您应该设置`HF_HUB_DISABLE_IMPLICIT_TOKEN`环境变量 + + + +## 创建存储库 + +一旦您注册并登录，请使用 [`create_repo`] 函数创建存储库： + +```py +>>> from huggingface_hub import HfApi +>>> api = HfApi() +>>> api.create_repo(repo_id="super-cool-model") +``` +如果您想将存储库设置为私有，请按照以下步骤操作： + +```py +>>> from huggingface_hub import HfApi +>>> api = HfApi() +>>> api.create_repo(repo_id="super-cool-model", private=True) +``` +私有存储库将不会对任何人可见，除了您自己 + + + +创建存储库或将内容推送到 Hub 时，必须提供具有`写入`权限的用户访问令牌。您可以在创建令牌时在您的[设置页面](https://huggingface.co/settings/tokens)中选择权限 + + + +## 上传文件 + +您可以使用 [`upload_file`] 函数将文件添加到您新创建的存储库。您需要指定： + +1. 要上传的文件的路径 + +2. 文件在存储库中的位置 + +3. 您要将文件添加到的存储库的 ID + +```py +>>> from huggingface_hub import HfApi +>>> api = HfApi() +>>> api.upload_file( +... path_or_fileobj="/home/lysandre/dummy-test/README.md" +... path_in_repo="README.md" +... repo_id="lysandre/test-model" +... ) +``` + +要一次上传多个文件，请查看[上传指南](./guides/upload) ,该指南将向您介绍几种上传文件的方法（有或没有 git）。 + +## 下一步 + +`huggingface_hub`库为用户提供了一种使用Python与Hub 进行交互的简单方法。要了解有关如何在Hub上管理文件和存储库的更多信息，我们建议您阅读我们的[操作方法指南](./guides/overview)： + +- [管理您的存储库](./guides/repository) +- [从Hub下载文件](./guides/download) +- [将文件上传到Hub](./guides/upload) +- [在Hub中搜索您的所需模型或数据集](./guides/search) +- [了解如何使用 Inference API 进行快速推理](./guides/inference)