入门 8 分钟Hugging Face

Hugging Face Spaces：是什么，如何使用 ?

Hugging Face Spaces 托管着数以千计的 AI 演示，可以直接在浏览器中试用：转录模型、图像生成器、基于前一天刚发布的 LLM 的聊天机器人。这是在下载模型之前评估它的最快方式。本指南将介绍什么是 Space、如何使用它、如何复制它或在您自己的机器上运行它，以及在什么情况下本地运行成为更好的选择。

作者： Clara M.·更新于 2026-10-26·已在 Windows、macOS 和 Linux 上测试

#Hugging Face Spaces：究竟是什么？

Space 是由 Hugging Face 托管的小型 Web 应用。从技术上讲，它是一个 git 仓库，与 Hub 上的模型和数据集仓库一样：其中包含应用代码、一个依赖文件，以及一个 README，其 YAML 头部描述了配置。每当有提交推送到该仓库，Hugging Face 就会重新构建并重启应用。而访问者看到的只是一个带有输入框、按钮和结果的页面。

如果您刚接触 Hugging Face，请记住它与模型页面的区别：模型页面包含供您下载的文件（权重、tokenizer、配置）；而 Space 则在服务器上运行代码，向您展示模型的能力。指南《Hugging Face：是什么，如何使用？》介绍了 Hub 的整体情况；本文只讨论 Spaces。

官方文档提供三种 Space 类型（称为 SDK），在创建时选择：

Gradio
这是最常见的情况。Gradio 是一个 Python 库，可根据一个函数生成 Web 界面：输入为文本框、输出为图像等。大多数 LLM 和图像模型的演示都是 Gradio Space。
Docker
该 Space 基于 Dockerfile 构建，因此可以运行任何 Web 应用：完整的聊天界面、API 服务器，或用 Python 以外的语言编写的工具。
静态 HTML
一个简单的 HTML、CSS 和 JavaScript 页面，没有计算服务器。适用于完全在浏览器中运行的文档、可视化或演示。

每个 Space 在 Hub 上都有一个地址，形如 huggingface.co/spaces/所有者/名称，还有一个应用的直接地址，形如 所有者-名称.hf.space。Space 可以是公开的（代码和应用对所有人可见）、受保护的（代码私有，应用可访问）或私有的（仅限所有者及其协作者）。

#第 1 步：在浏览器中使用演示

打造专属 AI 助手的完整套件。

借助我们的经验和引导式路径，打造你的本地助手，在日常中使用你的 AI。

  • 在线空间，终身可用
  • PDF + 文件
  • 30 天内退款
了解本地 AI 套件：24 €或 全部套件终身拥有：49 € →

试用 Space 在大多数情况下无需账户。Spaces 首页（huggingface.co/spaces）支持按关键词或任务搜索，并可按热度或“点赞”数排序。许多模型页面的右侧栏也会列出使用该模型的 Spaces。

  1. 01
    找到合适的 Space
    优先选择由模型发布方（该组织的官方账号）发布或关注度很高的 Space。来自陌生账号的新 Space 也可能运行良好，但您无法知道其代码会如何处理您发送的数据。
  2. 02
    查看显示的状态
    页面顶部的徽章会显示状态：运行中（Running）、构建中（Building）、休眠（Sleeping）、已暂停或出错。休眠的 Space 会在被访问时唤醒，应用重启可能需要一些时间。
  3. 03
    发起请求
    填写各字段后提交。如果 Space 的 GPU 由所有访客共享，处理前可能会先显示排队队列。
  4. 04
    核实您正在测试的内容
    打开 Files 标签页，阅读主文件（通常是 app.py）和 README。您可以从中看到加载的是哪个模型、采用何种精度（FP16、4 位量化……）以及哪些参数。演示并不总是所宣传模型的完整版本。
→
ZeroGPU 徽章
许多 LLM 演示运行在 ZeroGPU 上，这是一种共享基础设施，会按需在单次请求期间分配一块 GPU。使用是免费的，但受每日 GPU 时间配额限制：根据 2026 年 10 月 26 日查阅的文档，未登录每天 2 分钟，免费账户 5 分钟，PRO 账户 40 分钟。因此，只需登录即可将可用时间提升到两倍半。

#第 2 步：通过 API 调用 Gradio Space

Gradio Space 不只是一个网页：它还提供 API。应用底部的“Use via API”链接会显示可用的端点和代码示例。在 Python 中，官方的 gradio_client 库可以像调用函数一样调用 Space，便于在一系列示例上测试模型，而无需手动点击。

终端
pip install gradio_client
Python
from gradio_client import Client

# Remplacez par l'identifiant du Space (propriétaire/nom)
client = Client("proprietaire/nom-du-space")

# Affiche les points d'entrée et leurs paramètres
client.view_api()

确定参数后，client.predict() 方法会使用所需的参数以及 view_api() 给出的 api_name 发送请求。这些调用与在浏览器中访问一样，同样受该 Space 的配额和排队队列限制：它并不适合处理大批量任务。如需访问私有 Space，或以已登录身份调用（从而使用你账户的 ZeroGPU 配额），请将 Hugging Face 访问令牌传给 Client()。

#第 3 步：复制 Space

复制（Duplicate）一个 Space 会在您的账户中创建一份完整副本。这适用于以现有演示为基础进行修改，或拥有自己的实例而无需与所有访客共用排队队列。操作方法：点击页面右上角的三点菜单，选择“Duplicate this Space”选项。

  1. 01
    选择所有者和名称
    副本可以放在你的个人账户中，也可以放在你拥有写入权限的组织中。
  2. 02
    设置可见性
    副本默认是私有的。如果您打算用它处理自己的数据，请保持私有。
  3. 03
    选择硬件
    默认情况下，副本运行在 CPU Basic 上。您可以在此时或之后在设置（Settings）中选择付费 GPU。
  4. 04
    填写密钥
    原 Space 的公开变量会自动复制。机密信息（令牌、API 密钥）则永远不会被复制：如需提供，界面会提醒您。缺少这些信息时，应用可能能够启动，但会在第一个请求时失败。
!
复制并不总是免费的
根据 2026 年 10 月 26 日查阅的文档，创建或复制 Gradio 或 Docker Space 需要付费订阅（个人账户需 PRO，组织需 Team 或 Enterprise）。只有静态 Spaces 对所有人免费。例外情况：状态正常的免费个人账户（已验证电子邮件地址、账户注册超过 30 天）可在 ZeroGPU 上托管最多 2 个 Gradio Spaces。如果您不属于上述任何情况，仍可在本地执行第 4 步。

超出 CPU Basic 的硬件按小时计费。例如，截至 2026年10月26日，文档给出的 NVIDIA T4 small 价格为每小时 0.40 美元；完整的最新价目表见 Hugging Face 的定价页面。付费 Space 可以在其设置中暂停：暂停期间不计费。

#第 4 步：在本地运行 Hugging Face Space

由于公开 Space 的代码可以查看和克隆，您可以在自己的机器上运行它。有两种方法：拉取 Hugging Face 构建好的 Docker 镜像，或者克隆仓库后自行启动应用。

#方法 A：使用 Space 的 Docker 镜像

文档指出，大多数 Space 都可以用 Docker 运行。Space 页面右上角菜单中的“Run with Docker”按钮会显示可直接复制的确切命令。其形式通常如下，镜像托管在 registry.hf.space 镜像仓库上：

终端
docker run -it -p 7860:7860 --platform=linux/amd64 \
  registry.hf.space/proprietaire-nom-du-space:latest python app.py

请始终复制按钮提供的命令，而不要自行拼写：镜像名称、启动命令以及可能需要的变量（-e 选项，例如用于 HF_TOKEN 令牌）都取决于具体的 Space。某些 Space 要求使用您的 Hugging Face 用户名登录镜像仓库，并以访问令牌作为密码：

终端
docker login registry.hf.space

要让容器使用 NVIDIA 显卡，Docker 需要在宿主机上安装 NVIDIA Container Toolkit，并且必须在 docker run 命令中加上 --gpus all 选项。这些镜像是为 x86_64 架构（linux/amd64）构建的：在 Apple Silicon Mac 上，它们需通过模拟运行，无法访问 Mac 的 GPU。这种情况下，方法 B 通常更合适。

#方法 B：克隆仓库并启动应用

Space 菜单中还提供“Clone repository”，可通过 HTTPS 或 SSH 克隆。对于 Gradio Space，常规流程是：克隆仓库，创建独立的 Python 环境，安装 requirements.txt 中列出的依赖，然后运行主文件：

终端
git clone https://huggingface.co/spaces/proprietaire/nom-du-space
cd nom-du-space
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install gradio
python app.py

随后 Gradio 会显示界面的本地地址，默认为 http://127.0.0.1:7860。启动前需要确认以下几点：

README 头部
sdk_version、app_file 以及有时出现的 python_version 键，分别指明线上使用的 Gradio 版本、要启动的文件和 Python 版本。安装相同版本的 Gradio（pip install "gradio==X.Y.Z"）可以避免许多界面错误。
大文件
Space 中可能包含通过 Hub 存储系统保存的大文件。如果克隆后某些文件显示为很小的文本指针，请安装 Hugging Face 推荐的 git 扩展（git-xet 或 Git LFS），然后重新下载。
@spaces.GPU 装饰器
ZeroGPU Spaces 会导入 spaces 模块，并用 @spaces.GPU 装饰其函数。文档明确指出，该装饰器在 ZeroGPU 之外不起任何作用：只需安装 spaces 包（pip install spaces），代码即可在您自己的 GPU 上运行。
Secrets
如果代码会读取环境变量（os.getenv），请在启动 app.py 之前在终端中设置好这些变量。受访问条件限制的模型需要一个 Hugging Face 令牌，且该令牌所属账号须已接受许可协议。

对于 Docker Space，克隆下来的仓库中包含 Dockerfile：执行 docker build 再执行 docker run 即可，并发布 README 中 app_port 声明的端口（默认 7860）。

#Hugging Face Spaces 的局限：算力与隐私

Space 非常适合获得初步印象。但若要经常使用，其限制很快就会显现。以下限制来自 2026年10月26日查阅的官方文档。

免费硬件配置有限
默认硬件 CPU Basic 提供 2 个 vCPU、16 GB 内存和 50 GB 磁盘，没有 GPU。数十亿参数级别的 LLM 即便能装进内存，在上面运行也很慢。
磁盘非持久化
50 GB 磁盘空间会在重启时清空。上传或生成的文件不会保留，除非所有者配置了持久化存储。
休眠
在免费硬件上，闲置的 Space 会在一段时间后进入休眠，下次访问时需要重新启动。所有者也可以将其暂停，甚至删除：今天可用的演示，明天可能就消失了。
ZeroGPU 配额
每日 GPU 时间按账号限制（见上文），且单次请求默认限制为 60 秒 GPU 时间，除非作者设置了更长的时长。配额在首次使用 24 小时后重置。
受限网络
Space 只能通过 80、443 和 8080 端口对外连接。需要访问其他端口上服务的应用无法直接照常运行。

在隐私方面，规则很简单：您在 Space 中输入的所有内容都会发送到一台运行他人代码的服务器。这些代码可能会记录请求、将其转发给第三方 API，或在会话期间保留上传的文件。对于公开的 Space，您可以通过阅读 app.py 来核实；对于受保护的 Space，代码不可见。因此，切勿在演示中粘贴客户文档、个人数据、专有代码或登录凭据。

!
密钥不会外传，但你的数据会
Space 的密钥（secrets）仅对其所有者保密，但这保护的是所有者的令牌，而不是您输入的内容。对于敏感文档，请使用私有副本、本地运行，或通过 Ollama 使用本地模型。

#何时更适合本地运行

正确的做法是先用 Spaces 做决策，再转到本地开展工作。以下几种情况下，本地部署明显更胜一筹：

敏感数据
合同、病历、企业代码：使用本地模型，任何数据都不会离开你的机器。
日常使用或大批量使用
ZeroGPU 配额和排队机制使 Space 不适合持续高强度使用。在本地运行时，唯一的限制是您的硬件。
需要稳定性
Space 可能会更换模型或版本，甚至消失。下载并固定版本的模型能提供可复现的结果。
集成到您的工具中
Ollama 在 http://localhost:11434 上提供本地 API，可供 Open WebUI、脚本或自动化流程使用，无需依赖远程服务。

此外，对于 LLM，转到本地运行并不一定要克隆 Space。许多演示以 safetensors 格式、FP16 精度加载完整模型：此时一个 7B 模型的权重约占 14 GB，超出了大多数消费级显卡的容量。同一模型的 GGUF 格式 Q4_K_M 量化版本大约需要 5 GB 显存，可在 RTX 3060 12 GB 上运行。最简单的做法通常是记下 Space 所用模型的名称，然后在 Hub 上查找其 GGUF 版本，并导入 Ollama。

Q4 量化的 3B 模型
约 2 GB 显存
7B 使用 Q4
约 5 GB
14B，Q4 量化
约 9 GB（RTX 4070 12 GB）
Q4 下的 32B
约 19 GB（RTX 4090 24 GB，或配备 24 至 48 GB 统一内存的 Mac M4 Pro）
Q4 量化的 70B 模型
约 40 GB
i
将 Space 留给非 LLM 模型
对于尚无 GGUF 版本、也未进入 Ollama 的最新图像、音频或视觉模型，克隆 Space（方法 B）往往是在本地运行它的最直接方式，因为其加载代码已经写好。

#故障排除

页面上出现“Runtime error”
该 Space 在启动时崩溃。如果 Logs 选项卡可以访问，可在其中查看原因。如果这是别人的 Space，您只能等待、另找一个 Space，或在 Community 选项卡中报告问题。
GPU 配额超限提示
您今天的 ZeroGPU 配额已用完。如果尚未登录，请先登录，然后等待配额重置，或在本地运行模型。
import après pip install 错误
Gradio 或某个依赖项的版本与 Space 中的不同。请在全新的虚拟环境中，按照 README 中的 sdk_version 和 python_version 保持一致。
本地找不到 CUDA
代码需要 NVIDIA GPU。请确认安装的 PyTorch 支持 CUDA，或修改代码改用 CPU（Mac 上可用 mps），代价是运行速度变慢。
Docker 镜像被拒绝或找不到
使用 docker login registry.hf.space 登录镜像仓库，然后确认镜像名称与“Run with Docker”按钮给出的名称一致。

#深入了解

本指南介绍的是 Space。如需全面了解 Hub、区分各种文件格式，或从演示过渡到在自己机器上运行模型，请参阅以下指南。

这份指南对您有帮助吗？

有反馈、发现了错误，或想补充说明？请告诉我们，让这份指南对每个人都更有帮助。