Skip to main content

Spaces 配置参考

Spaces 的所有配置都写在仓库根目录 README.md 文件顶部的 YAML 区块里。下面列出了当前支持的全部参数。

title : string
Space 展示用标题。

emoji : string
Space 使用的 emoji（只能填写单个 emoji 字符）。

colorFrom : string
缩略图渐变的起始颜色，可选值：red / yellow / green / blue / indigo / purple / pink / gray。

colorTo : string
缩略图渐变的结束颜色，取值范围与 colorFrom 相同。

sdk : string
可选 gradio、docker 或 static。

python_version : string
指定 Python 版本，填任意合法的 3.x 或 3.x.x。默认 3.10。

sdk_version : string
指定要使用的 Gradio 版本。所有 Gradio 版本都支持。

suggested_hardware : string
建议用于运行该 Space 的 硬件规格。主要用于那些希望被他人复制的 Space。
设置后不会自动给 Space 分配硬件，值必须是有效的硬件 flavor：

  • CPU："cpu-basic"、"cpu-upgrade"
  • GPU："t4-small"、"t4-medium"、"l4x1"、"l4x4"、"a10g-small"、"a10g-large"、"a10g-largex2"、"a10g-largex4"、"a100-large"
  • TPU："v5e-1x1"、"v5e-2x2"、"v5e-2x4"

suggested_storage : string
建议使用的 持久化存储 档位，同样面向希望被复制的 Space。
设置后不会自动分配存储，取值必须是 "small"、"medium" 或 "large"。

app_file : string
主应用文件的相对路径（可以是包含 Gradio 代码的 Python 文件，也可以是静态 HTML）。

app_build_command : string
针对 static Spaces 的构建命令，例如 npm run build。通常与 app_file 搭配使用，指向构建产物（如 app_file: dist/index.html）。
每次 Space 更新都会触发一次 Job 执行该构建命令，产物存放在 refs/convert/build，由 Space 对外提供。例如：https://huggingface.co/spaces/coyotte508/static-vite

app_port : int
应用监听的端口，仅在 sdk 为 docker 时生效，默认 7860。

base_path : string
针对非 static Space，指定初始渲染的 URL，必须以 / 开头；static Space 请使用 app_file。

fullWidth : boolean
控制 Space 在 iframe 中以全宽（true）还是固定宽度容器渲染，默认 true。

header : string
可选 mini 或 default。当设为 mini 时，Space 会全屏显示，并在右上角悬浮一个迷你头部。

short_description : string
Space 的简短描述，展示在缩略图上。

models : List[string]
Space 中使用到的 HF 模型 ID（例如 openai-community/gpt2、deepset/roberta-base-squad2）。如果不填，系统会尝试从代码里自动解析。

datasets : List[string]
Space 中使用到的 HF 数据集 ID（例如 mozilla-foundation/common_voice_13_0、oscar-corpus/OSCAR-2109）。若不填，同样会自动解析。

tags : List[string]
描述 Space 任务或范围的标签列表。

thumbnail : string
自定义缩略图 URL，用于社交分享。

pinned : boolean
将该 Space 固定在个人主页顶部，便于自己或他人快速找到重点 Space。

hf_oauth : boolean
是否为 Space 关联了 OAuth 应用。详见 为 Space 添加「Sign-In with HF」按钮。

hf_oauth_scopes : List[string]
OAuth 应用的授权 scope。openid 和 profile 默认已包含，无需在此声明。更多说明参见 OAuth 文档。

hf_oauth_expiration_minutes : int
OAuth token 的有效期（分钟），默认 480 分钟（8 小时），上限 43200 分钟（30 天）。

hf_oauth_authorized_org : string 或 List[string]
限制只有指定组织成员可以通过 OAuth 访问该 Space。

disable_embedding : boolean
是否禁止将 Space iframe 嵌入到其他网站。默认 false（允许嵌入）。

startup_duration_timeout : string
自定义 Space 的启动超时时长，这是 Space 获准启动的最长时间，超过会被标记为 unhealthy。默认 30 分钟，可设置任意合法时长（如 1h、30m）。

custom_headers : Dict[string, string]
为 Space 的所有 HTTP 响应添加自定义 Header。
目前仅支持设置 COEP、COOP、CORP，这些 Header 可以让 Space 运行在跨域隔离环境，启用 SharedArrayBuffer 等高级特性，例如：

custom_headers:
  cross-origin-embedder-policy: require-corp
  cross-origin-opener-policy: same-origin
  cross-origin-resource-policy: cross-origin

注意： 键名与键值都必须是小写。

preload_from_hub : List[string]
在 Space 构建阶段预先下载一组 Hugging Face Hub 模型或大文件，以缩短启动时间。适用于依赖大模型或大数据集的 Space，避免每次启动时临时下载。

每一项的格式可以是：

  • "repository_name"：拉取整个仓库；
  • "repository_name file1,file2"：只下载仓库内指定文件；
  • "repository_name file1,file2 commit_sha256"：从指定 commit 下载特定文件。

示例：

preload_from_hub:
  - warp-ai/wuerstchen-prior text_encoder/model.safetensors,prior/diffusion_pytorch_model.safetensors
  - coqui/XTTS-v1
  - openai-community/gpt2 config.json 11c5a3d5811f50298f278a704980280950aedb10

上述配置会在构建阶段预先下载：warp-ai/wuerstchen-prior 中的若干 .safetensors、完整的 coqui/XTTS-v1 仓库、以及 openai-community/gpt2 的特定版本 config.json。

warning

这些文件都会保存到默认的 huggingface_hub 缓存目录 ~/.cache/huggingface/hub。如果你的应用期望它们出现在其它路径，或修改过 HF_HOME，目前预加载功能不会跟随这些改动。

Last updated on