Spaces 구성 레퍼런스

Spaces 구성 레퍼런스

Spaces는 리포지토리 루트의 README.md 파일 맨 위 YAML 블록을 통해 구성돼요. 허용되는 모든 파라미터를 아래에 정리했어요.

title, sdk, python_version, app_file 같은 핵심 파라미터로 Space의 동작·외관을 제어할 수 있어요.

출처: 문서

본문

title : string Space의 표시 제목.

emoji : string Space 이모지 (이모지만 허용되는 문자).

colorFrom : string 썸네일 그라데이션 색상 (red, yellow, green, blue, indigo, purple, pink, gray).

colorTo : string 썸네일 그라데이션 색상 (red, yellow, green, blue, indigo, purple, pink, gray).

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가 실행되어야 할 권장 하드웨어 지정. 다른 사용자가 복제(duplicate)하도록 의도된 Spaces에 유용해요. 이 값을 설정해도 Space에 하드웨어가 자동 할당되진 않아요. 값은 유효한 하드웨어 플레이버여야 해요. 현재 유효한 하드웨어 플레이버:

  • CPU: "cpu-basic", "cpu-upgrade"
  • GPU: "t4-small", "t4-medium", "l4x1", "l4x4", "l40sx1", "l40sx4", "l40sx8", "a10g-small", "a10g-large", "a10g-largex2", "a10g-largex4", "a100-large", "a100x4", "a100x8"

suggested_storage : string 이 Space가 실행되어야 할 권장 영구 스토리지 지정. 다른 사용자가 복제하도록 의도된 Spaces에 유용해요. 이 값을 설정해도 Space에 영구 스토리지가 자동 할당되진 않아요. 값은 "small", "medium" 또는 "large" 중 하나여야 해요.

[!NOTE] 영구 스토리지 기능은 더 이상 제공되지 않으므로 이 설정은 무시돼요.

app_file : string 메인 애플리케이션 파일 경로 (gradio Python 코드 또는 static html 코드 포함). 경로는 리포지토리 루트 기준 상대 경로예요.

app_build_command : string static Spaces의 경우 렌더링할 HTML을 생성하기 위해 먼저 실행할 명령. 예: npm run build.

이것은 빌드된 인덱스 파일을 가리키는 app_file과 함께 사용돼요: 예: app_file: dist/index.html.

업데이트할 때마다 빌드 명령이 Job에서 실행되고 빌드 출력은 refs/convert/build에 저장되며, Space가 이를 서빙해요. 예: https://huggingface.co/spaces/coyotte508/static-vite

app_port : int 애플리케이션이 실행 중인 포트. sdk가 docker일 때만 사용돼요. 기본 포트는 7860.

base_path: string 비정적(non-static) Spaces의 경우 렌더링할 초기 URL. /로 시작해야 해요. static Spaces는 대신 app_file을 사용해요.

fullWidth: boolean iframe 안에서 Space를 전체 너비(true) 또는 고정 너비 컬럼(즉 "container" CSS)으로 렌더링할지. 기본값은 true.

header: string mini 또는 default일 수 있어요. header가 mini로 설정되면 Space가 미니 플로팅 헤더와 함께 전체 화면으로 표시돼요.

short_description: string Space의 짧은 설명. 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가 프로필 맨 위에 유지되는지. Spaces가 많다면 자신과 다른 사람이 최고의 Space를 빠르게 볼 수 있어 유용해요.

hf_oauth : boolean 연결된 OAuth 앱이 이 Space와 연관되는지. 자세한 내용은 Space에 Sign-In with HF 버튼 추가를 참고해요.

hf_oauth_scopes : List[string] 연결된 OAuth 앱의 승인된 scope. openid와 profile은 기본으로 승인되며 이 파라미터가 필요 없어요. 자세한 내용은 Space에 Sign-In with HF 버튼 추가를 참고해요.

hf_oauth_expiration_minutes : int OAuth 토큰의 지속 시간(분). 기본값 480분(8시간). 최대 43200분(30일). 자세한 내용은 Space에 Sign-In with HF 버튼 추가를 참고해요.

hf_oauth_authorized_org : string 또는 List[string] 특정 조직 구성원으로 OAuth 접근을 제한. 자세한 내용은 Space에 Sign-In with HF 버튼 추가를 참고해요.

disable_embedding : boolean Space iframe을 다른 웹사이트에 임베드할 수 있는지. 기본값은 false, 즉 Spaces는 임베드 가능해요.

startup_duration_timeout: string Space에 커스텀 시작 기간 타임아웃 설정. Space가 시작하도록 허용된 최대 시간으로, 이것을 넘으면 타임아웃되어 비정상(unhealthy)으로 표시돼요. 기본값 30분이지만 유효한 지속 시간(예: 1h, 30m)은 다 허용돼요.

custom_headers : Dict[string, string] Space를 서빙할 때 모든 HTTP 응답에 추가할 커스텀 HTTP 헤더 설정. 지금은 cross-origin-embedder-policy (COEP), cross-origin-opener-policy (COOP), cross-origin-resource-policy (CORP) 헤더만 허용돼요. 이 헤더들로 cross-origin isolated 환경을 구성하고 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 모델 또는 기타 대용량 파일 목록을 지정. 애플리케이션 시작 시 파일이 준비되어 있어 시작 시간을 최적화해요. 런타임에 다운로드해야 하는 대형 모델·데이터셋에 의존하는 Spaces에 특히 유용해요.

각 항목의 형식은 리포지토리에서 모든 파일을 다운로드하는 "repository_name" 또는 해당 리포지토리 내 특정 파일을 다운로드하는 "repository_name file1,file2"예요. 특정 커밋을 다운로드하려면 "repository_name file1,file2 commit_sha256" 형식을 사용할 수도 있어요.

예시:

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

이 예시에서 Space는 빌드 시간에 Hugging Face Hub에서 warp-ai/wuerstchen-prior의 특정 .safetensors 파일, coqui/XTTS-v1 리포지토리 전체, openai-community/gpt2 리포지토리의 config.json 파일 특정 리비전을 미리 로드해요.

[!WARNING] 파일은 기본 huggingface_hub 디스크 캐시 ~/.cache/huggingface/hub에 저장돼요. 애플리케이션이 다른 곳을 기대하거나 HF_HOME 변수를 바꿨다면 이 프리로딩은 지금 그걸 따르지 않아요.

[!NOTE] 비공개 리포지토리의 프리로딩은 아직 지원되지 않아요.

더 알아보기 (Learn more)

  • README의 YAML 블록에서 sdk, app_file, title 등으로 Space를 구성해요.
  • OAuth, 커스텀 헤더, preload_from_hub로 Space 기능을 확장해요.
  • Spaces 설정과 Spaces 하드웨어 문서를 함께 참고해 보세요.