스페이스 개요 (Spaces Overview)

스페이스 개요 (Spaces Overview)

허깅페이스 Spaces는 ML 기반 데모를 몇 분 만에 만들고 배포할 수 있게 해줘요. 여기서는 Space를 만들고, 설정하고, 코드를 배포하는 기초를 다룰게요.

새 Space 만들기

새 Space를 만들려면 Spaces 메인 페이지에 가서 Create new Space를 클릭해요. Space 이름을 정하고, 선택적으로 라이선스를 고르고, 공개 범위(public, protected, private)를 정하는 것과 함께, SDK를 선택하라는 안내가 나와요. 허브는 세 가지 SDK 옵션을 제공해요: Gradio, Docker, 정적 HTML. "Gradio"를 SDK로 선택하면 다음 페이지를 보여주는 새 저장소로 이동해요.

정적(Static) Space는 모두에게 무료예요. Gradio와 Docker Space는 컴퓨트에서 실행되므로 만들려면 유료 플랜이 필요해요: 개인 계정은 PRO, 조직은 Team 또는 Enterprise. 상태가 좋은 무료 개인 계정은 ZeroGPU에서 실행되는 Gradio Space를 최대 2개까지 호스팅할 수 있어요.

내부적으로 Spaces는 모델·데이터셋 저장소처럼 코드를 Git 저장소에 저장해요. 덕분에 허브의 다른 저장소에 쓰는 것과 같은 도구(git, git-xet)가 Spaces에도 그대로 작동해요. Repositories 시작하기와 같은 흐름으로 Space에 파일을 추가하면 돼요. 새 커밋이 푸시될 때마다 Space는 자동으로 다시 빌드하고 재시작해요.

첫 Space를 만드는 단계별 튜토리얼은 아래 가이드를 참고하세요.

Space 공개 범위

Space의 공개 범위는 Settings 탭의 visibility 드롭다운으로 설정할 수 있어요. Spaces는 public, protected, private 세 가지 공개 범위 수준을 지원해요.

Protected 공개 범위는 PRO 또는 Team & Enterprise 플랜에 포함돼요.

Public Protected Private
허브의 소스 코드 모두에게 보임 비공개 (소유자/협업자만) 비공개 (소유자/협업자만)
임베드 URL로 앱 접근 가능 가능 불가능
커스텀 도메인으로 앱 접근 가능 가능 불가능
다른 사람이 복제(clone) 가능 불가능 불가능
Public Space는 완전히 열려 있어요. 누구나 소스 코드를 보고, 실행 중인 앱에 접근하고, 저장소를 복제할 수 있어요.

Protected Space는 허브에서 소스 코드를 비공개로 유지해요. 소유자와 협업자만 저장소를 보거나 복제할 수 있고, 실행 중인 앱은 임베드 URL(https://<space-subdomain>.hf.space)이나 커스텀 도메인을 통해 공개적으로 접근할 수 있어요. 소스 코드를 공개하지 않고 웹사이트나 앱을 호스팅할 때 특히 유용해요.

Private Space는 완전히 비공개예요. 소스 코드와 실행 중인 앱 모두 소유자와 협업자만 접근할 수 있어요. 검색 결과에 나타나지 않고, 다른 사용자가 URL을 방문하면 404 오류를 받아요.

하드웨어 리소스

각 Spaces 환경은 기본적으로 16GB RAM, 2 CPU 코어, 50GB(비영구) 디스크로 제한돼요. 기본 CPU Basic 하드웨어는 시간당 비용이 없지만, 컴퓨트(Gradio 또는 Docker)에서 실행되는 Space를 만들려면 유료 플랜이 필요하고 정적 Space는 모두에게 무료예요. 다양한 GPU 가속기를 포함한 더 나은 하드웨어로 업그레이드할 수 있어요(경쟁력 있는 가격). 업그레이드를 요청하려면 Space의 Settings 버튼을 클릭하고 원하는 하드웨어 환경을 선택하세요.

하드웨어 CPU 메모리 GPU 메모리 시간당 가격
CPU Basic 2 vCPU 16 GB FREE
CPU Upgrade 8 vCPU 32 GB $0.03
Nvidia T4 - small 4 vCPU 15 GB 16 GB $0.40
Nvidia T4 - medium 8 vCPU 30 GB 16 GB $0.60
1x Nvidia L4 8 vCPU 30 GB 24 GB $0.80
4x Nvidia L4 48 vCPU 186 GB 96 GB $3.80
1x Nvidia L40S 8 vCPU 62 GB 48 GB $1.80
4x Nvidia L40S 48 vCPU 382 GB 192 GB $8.30
8x Nvidia L40S 192 vCPU 1534 GB 384 GB $23.50
Nvidia A10G - small 4 vCPU 15 GB 24 GB $1.00
Nvidia A10G - large 12 vCPU 46 GB 24 GB $1.50
2x Nvidia A10G - large 24 vCPU 92 GB 48 GB $3.00
4x Nvidia A10G - large 48 vCPU 184 GB 96 GB $5.00
Nvidia A100 - large 12 vCPU 142 GB 80 GB $2.50
4x Nvidia A100 48 vCPU 568 GB 320 GB $10.00
8x Nvidia A100 96 vCPU 1136 GB 640 GB $20.00

참고: 더 상세하고 포괄적인 가격 정보는 가격 페이지에서 확인하세요.

하드웨어 업그레이드 비용을 감당하기 어려운 멋진 Space가 있나요? 혁신적인 Space를 가진 분들을 돕는 걸 좋아해요. Space의 Settings 탭에 있는 링크로 커뮤니티 GPU 그랜트를 신청해 보세요.

시크릿과 환경 변수 관리

앱이 환경 변수(예: 시크릿 키나 토큰)를 요구한다면, 앱 안에 하드코딩하지 마세요! 대신 Space 저장소의 Settings 페이지로 가서 새 variable 또는 secret을 추가하세요. 민감하지 않은 구성 값을 저장할 때는 variables를, 액세스 토큰·API 키·기타 민감한 값이나 자격 증명을 저장할 때는 secrets를 쓰면 돼요.

다음처럼 사용할 수 있어요.

  • Variables: 민감하지 않은 구성 값을 저장할 때. 공개적으로 접근·조회 가능하고, 여러분의 Space를 복제한 Space에 자동으로 추가돼요.
  • Secrets: 액세스 토큰, API 키, 민감한 값·자격 증명을 저장할 때. 비공개이며, 한번 설정하면 Space의 설정 페이지에서 값을 읽을 수 없어요. 복제된 Space에는 추가되지 않아요.

시크릿과 변수에 접근하는 방식은 Space SDK에 따라 달라요.

  • 정적(Static) Space: 둘 다 클라이언트 측 JavaScript의 window.huggingface.variables로 접근
  • Docker Space: Docker 환경 관리 참고

다른 Space는 둘 다 환경 변수로 앱에 노출돼요. 앞서 선언한 MODEL_REPO_ID 변수에 Python으로 접근하는 아주 간단한 예시예요(시크릿도 동일).

import os
print(os.getenv('MODEL_REPO_ID'))

Spaces Secrets Scanner가 하드코딩된 시크릿을 발견하면 Space 소유자에게 경고가 가요.

Space 복제

Space 복제는 다른 데모를 초기 템플릿으로 삼아 새 데모를 만들고 싶을 때 유용해요. 개인용으로 빠른 추론을 제공하는 업그레이드된 Space를 원할 때도 쓸 수 있어요.

Space를 복제하려면 Space 오른쪽 위의 점 세 개를 클릭하고 Duplicate this Space를 누르면 돼요. 그러면 다음 속성을 바꿀 수 있어요.

  • 소유자: 복제된 Space는 내 계정이나 쓰기 권한이 있는 조직 아래 둘 수 있어요
  • Space 이름
  • 공개 범위: 복제된 Space는 기본적으로 비공개예요. 옵션은 여기를 참고하세요.
  • 하드웨어: Space가 실행될 하드웨어를 고를 수 있어요. 업그레이드에 대한 내용은 여기를 참고하세요.
  • 저장소: 원본 저장소가 스토리지 버킷을 쓰면 저장소를 설정하라는 안내가 나와요. 디스크 사용과 저장소에 대한 내용은 여기를 참고하세요.
  • 시크릿과 변수: 원본 저장소가 시크릿·변수를 설정해 뒀다면 복제 중에 설정할 수 있어요.

일부 Space는 설정해야 할 환경 변수가 있을 수 있어요. 이 경우 복제 워크플로가 원본 Space의 공개 Variables를 자동으로 채우고, Secrets 설정에 대한 경고를 줘요. 복제된 Space는 기본적으로 CPU Basic 하드웨어를 쓰지만, 필요하면 나중에 업그레이드할 수 있어요. 복제도 새 Space 만들기와 같은 규칙을 따라요: Gradio나 Docker Space의 복제는 대상 계정이나 조직에 유료 플랜이 필요해요(개인 계정에 대한 ZeroGPU 무료 티어 예외는 동일).

네트워킹

Space가 네트워크 요청을 해야 한다면 표준 HTTP·HTTPS 포트(80, 443)와 포트 8080으로 요청할 수 있어요. 다른 포트로 가는 요청은 차단돼요.

라이프사이클 관리

무료 하드웨어에서는 사용되지 않는 Space가 일정 시간이 지나면 "잠들어" 실행을 멈춰요. Space를 무기한 계속 실행하고 싶다면 유료 하드웨어로 업그레이드하는 걸 고려해 보세요. Settings 탭에서 수동으로 Space를 일시정지할 수도 있어요. 일시정지된 Space는 소유자가 수동으로 다시 시작할 때까지 실행을 멈춰요. 일시정지 시간은 청구되지 않아요.

내장 환경 변수

때로는 Space 저자나 저장소 이름에 프로그래밍 방식으로 접근하고 싶을 때가 있어요. 사용자가 내 Space를 복제하길 기대할 때 특히 유용한 기능이죠. 이에 도움을 주기 위해 Spaces는 런타임에 다양한 환경 변수를 노출해요. Space osanseviero/i-like-flan을 예로 들면:

  • ACCELERATOR: 사용 가능한 가속기 유형 (예: t4-medium, a10g-small), CPU 전용 Space는 none
  • CPU_CORES: 4
  • MEMORY: 15Gi
  • SPACE_AUTHOR_NAME: osanseviero
  • SPACE_REPO_NAME: i-like-flan
  • SPACE_TITLE: I Like Flan (README 파일에 지정)
  • SPACE_ID: osanseviero/i-like-flan
  • SPACE_HOST: osanseviero-i-like-flan.hf.space
  • SPACE_CREATOR_USER_ID: 6032802e1f993496bc14d9e3 — 원래 Space를 만든 사용자의 ID예요. Space가 조직 아래 있을 때 유용해요. 사용자 정보는 https://huggingface.co/api/users/{SPACE_CREATOR_USER_ID}/overview API 호출로 얻을 수 있어요.

Space에 OAuth가 활성화되어 있으면 다음 변수도 사용할 수 있어요.

  • OAUTH_CLIENT_ID: OAuth 앱의 클라이언트 ID(공개)
  • OAUTH_CLIENT_SECRET: OAuth 앱의 클라이언트 시크릿
  • OAUTH_SCOPES: OAuth 앱이 접근할 수 있는 스코프. 현재는 항상 "openid profile".
  • OPENID_PROVIDER_URL: OpenID 제공자의 URL. OpenID 메타데이터는 {OPENID_PROVIDER_URL}/.well-known/openid-configuration에서 볼 수 있어요.

저장소 복제

Space 저장소를 로컬에 복제할 수 있어요. Space 페이지 오른쪽 위의 드롭다운 메뉴에서 시작해요. "Clone repository"를 선택하고 HTTPS 또는 SSH로 Space 저장소를 로컬 머신에 복제하는 방법을 따라 하면 돼요.

허브에서 모델과 데이터셋 연결하기

Space의 README 메타데이터에 models와 datasets 키로 식별자를 정의하면, Space가 연결한 모델·데이터셋을 모두 보여줄 수 있어요. README 파일에 나열하는 것 외에 .py, .ini, .html 파일에도 기록할 수 있어요. 자동으로 파싱해 줘요.

Space에서 두 모델을 연결하는 예시예요.

title: My lovely space
emoji: 🤗
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
models:
- reach-vb/musicgen-large-fp16-endpoint
- reach-vb/wav2vec2-large-xls-r-1B-common_voice7-lt-ft