Spaces 개요

Hugging Face Spaces를 사용하면 몇 분 만에 ML 기반 데모를 만들고 배포할 수 있습니다. Spaces에 대한 간단한 소개를 위해 다음 영상을 시청해 보세요:

다음 섹션에서는 Space를 만들고, 구성하며, 코드를 배포하는 기본 사항을 학습합니다.

새로운 Space 만들기

새로운 Space를 만들려면 Spaces 메인 페이지에 접속하여 Create new Space를 클릭하세요. Space 이름 지정, 선택 사항인 라이선스 선택, Space의 visibility(public, protected, private) 설정과 함께 Space에 사용할 SDK를 선택하도록 안내됩니다. Hub에서는 Gradio, Docker, static HTML 세 가지 SDK 옵션을 제공합니다. SDK로 “Gradio”를 선택하면 다음 페이지가 표시되는 새 저장소로 이동합니다:

Static Spaces는 모든 사용자에게 무료입니다. Gradio 및 Docker Spaces는 컴퓨트 리소스를 사용하며, 생성하려면 유료 플랜이 필요합니다: 개인 계정의 경우 PRO, 조직의 경우 Team 또는 Enterprise입니다. 정상 상태의 무료 개인 계정은 ZeroGPU에서 실행되는 Gradio Spaces를 최대 2개까지 호스팅할 수 있습니다.

Spaces는 내부적으로 모델 및 데이터셋 저장소와 마찬가지로 git 저장소에 코드를 저장합니다. 이를 통해 Hub의 다른 저장소에 사용하는 도구인 git과 git-xet도 Spaces에서 동일하게 사용할 수 있습니다. 저장소 시작하기의 흐름을 그대로 따라 Space에 파일을 추가하세요. 새로운 커밋이 push될 때마다 Space는 자동으로 재빌드되고 재시작됩니다.

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

• Gradio Space 만들기
• Docker Space 만들기

Space 가시성

Settings 탭의 가시성 드롭다운을 사용하여 Space의 가시성을 설정할 수 있습니다. Spaces는 세 가지 가시성 수준을 지원합니다: public, protected, private.

보호된 가시성은 PRO 또는 Team & Enterprise 플랜의 일부입니다.

Public Spaces는 완전히 공개되어 있어 누구나 소스 코드를 볼 수 있고, 실행 중인 앱에 접근하며, 저장소를 클론할 수 있습니다.

Protected Spaces는 Hub에서 소스 코드를 비공개로 유지합니다. 소유자와 협업자만 저장소를 조회하거나 클론할 수 있습니다. 그러나 실행 중인 앱은 임베드 URL(https://<space-subdomain>.hf.space)을 통해, 또는 custom domain이 설정된 경우 이를 통해 공개적으로 접근할 수 있습니다. 이는 소스 코드를 공개하지 않고 웹사이트나 앱을 호스팅하는 데 특히 유용합니다.

Private Spaces는 완전히 비공개입니다. 소스 코드와 실행 중인 앱은 소유자와 협업자만 접근할 수 있습니다. 해당 Space는 검색 결과에 표시되지 않으며, 다른 사용자가 URL을 방문하면 404 오류가 발생합니다.

하드웨어 리소스

각 Spaces 환경은 기본적으로 16GB RAM, 2개의 CPU 코어, 50GB의 (영구 저장되지 않는) 디스크 공간으로 제한됩니다. 기본 CPU Basic 하드웨어는 시간당 비용이 없지만, compute(Gradio 또는 Docker)로 실행되는 Space를 생성하려면 유료 플랜이 필요하며, Static Spaces는 모든 사용자에게 무료입니다. 경쟁력 있는 가격으로 다양한 GPU 가속기를 포함한 더 나은 하드웨어로 업그레이드할 수 있습니다. 업그레이드를 요청하려면 Space에서 Settings 버튼을 클릭하고 원하는 하드웨어 환경을 선택하세요.

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

훌륭한 Space를 보유하고 있지만 하드웨어 업그레이드 비용에 도움이 필요하신가요? 혁신적인 Space를 가진 분들을 돕는 것을 좋아하므로, Space의 Settings 탭에 있는 링크를 통해 커뮤니티 GPU 보조금을 신청해 보시고, 선정될 수 있는지 확인해 보세요!

Spaces GPU 업그레이드 및 Spaces 디스크 사용량 및 저장소에 대한 전용 섹션에서 자세히 알아보세요.

비밀 정보 및 환경 변수 관리

애플리케이션에 환경 변수(예: 시크릿 키 또는 토큰)가 필요한 경우, 이를 앱 내부에 하드코딩하지 마세요. 대신 Space 저장소의 Settings 페이지로 이동하여 새로운 variable 또는 secret을 추가하세요. 민감하지 않은 구성 값을 저장할 때는 변수를, 액세스 토큰, API 키 또는 기타 민감한 값이나 자격 증명을 저장할 때는 시크릿을 사용하세요.

다음과 같은 것을 사용할 수 있습니다:

• 비밀이 아닌 설정 값을 저장해야 하는 경우 Variables를 사용하세요. 공개적으로 접근 및 조회할 수 있으며, 사용자의 Spaces에서 복제된 Spaces에 자동으로 추가됩니다.
• 액세스 토큰, API 키 또는 기타 민감한 값이나 자격 증명을 저장하는 Secrets입니다. 비공개이며, 설정 후에는 Space의 설정 페이지에서 값을 읽을 수 없습니다. 저장소에서 복제된 Spaces에는 추가되지 않습니다.

Space SDK에 따라 secrets와 variables에 접근하는 방식이 다릅니다:

• Static Spaces의 경우, 둘 다 window.huggingface.variables를 통해 클라이언트 측 JavaScript에서 사용할 수 있습니다.
• Docker Spaces의 경우 Docker를 사용한 환경 관리를 확인하세요.

다른 Spaces의 경우, 둘 다 환경 변수로 앱에 노출됩니다. 이전에 선언한 MODEL_REPO_ID 변수에 Python으로 접근하는 매우 간단한 예제는 다음과 같습니다(시크릿도 동일합니다):

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

Spaces 소유자는 Spaces Secrets Scanner가 하드코딩된 시크릿을 발견하면 경고 메시지를 받습니다.

Space 복제

새 데모를 만들 때 다른 데모를 초기 템플릿으로 활용하고 싶다면 Space 복제가 유용합니다. 빠른 추론을 위해 개인용 Upgraded Space를 별도로 유지하고 싶을 때도 복제된 Space가 유용합니다.

Space를 복제하려면 Space 오른쪽 상단의 세 점을 클릭한 후 Duplicate this Space를 클릭하세요. 이렇게 하면 다음 속성을 변경할 수 있습니다:

• Owner: 중복된 Space는 사용자의 계정 또는 사용자에게 쓰기 권한이 있는 조직 중 어디에나 있을 수 있습니다
• Space 이름
• 가시성: Space는 기본적으로 비공개입니다. 가시성 옵션에 대한 자세한 내용은 여기에서 확인하세요.
• 하드웨어: Space가 실행될 하드웨어를 선택할 수 있습니다. 하드웨어 업그레이드에 대한 자세한 내용은 여기에서 확인하세요.
• Storage: 원본 저장소가 storage bucket를 사용하는 경우, storage를 구성하도록 안내됩니다. disk 사용량 및 storage에 대한 자세한 내용은 여기에서 확인하세요.
• Secrets and variables: 원본 저장소에 secrets와 variables가 설정되어 있다면, 저장소를 복제하는 동안 이를 설정할 수 있습니다.

일부 Spaces에는 설정이 필요한 환경 변수가 있을 수 있습니다. 이러한 경우, 복제 워크플로우는 소스 Space의 공개 Variables를 자동으로 채우고 Secrets 설정에 대한 경고를 표시합니다. 복제된 Space는 기본적으로 CPU Basic 하드웨어를 사용하지만, 필요 시 나중에 업그레이드할 수 있습니다. 복제는 새로운 Space를 생성하는 것과 동일한 규칙을 따릅니다. Gradio 또는 Docker Space를 복제하려면 대상 계정 또는 조직에 유료 플랜이 필요하며(개인 계정의 ZeroGPU free tier 예외는 동일하게 적용됨)

네트워킹

Space에서 네트워크 요청을 보내야 하는 경우, 표준 HTTP 및 HTTPS 포트(80 및 443)와 포트 8080을 통해 요청을 보낼 수 있습니다. 다른 포트에 대한 요청은 차단됩니다.

라이프사이클 관리

무료 하드웨어에서 Space는 일정 시간 동안 사용되지 않으면 “수면” 상태로 전환되어 실행이 중단됩니다. Space를 무기한으로 실행하려면 유료 하드웨어로 업그레이드하는 것을 고려해 보세요. 또한 설정 탭에서 Space를 수동으로 일시 중지할 수 있습니다. 일시 중지된 Space는 쓰기 권한이 있는 사용자가 다시 시작할 때까지 실행이 중단됩니다. 일시 중지된 시간은 과금되지 않습니다.

내장 환경 변수

일부 경우 Space의 작성자 또는 저장소 이름에 대한 프로그래밍 방식의 접근이 필요할 수 있습니다. 이 기능은 사용자가 Space를 복제하는 것을 기대할 때 특히 유용합니다. 이를 돕기 위해 Spaces는 런타임에 다양한 환경 변수를 노출합니다(또한 Jobs의 내장 환경 변수도 참조하세요). Space osanseviero/i-like-flan의 경우:

• ACCELERATOR: 사용 가능한 가속기의 유형(예: t4-medium, a10g-small) 또는 CPU 전용 Spaces의 경우 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_SIGNING_SECRET: Space에 고유한 무작위 시크릿으로, 시크릿으로 노출됩니다. 재시작, 재빌드, 리플리카를 거치더라도 동일하게 유지되므로 쿠키, OAuth 상태, CSRF 토큰과 같은 항목에 서명하는 데 사용할 수 있습니다. 자체 값을 사용하려면 Space 설정에 SPACE_SIGNING_SECRET이라는 이름의 시크릿을 추가하세요.

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 저장소를 로컬 머신에 클론하는 방법에 대한 지침을 따를 수 있습니다.

Hub에서 모델과 데이터셋 연결

Space의 README 메타데이터에 식별자를 추가하여 Space가 연결하는 모든 모델과 데이터셋을 보여줄 수 있습니다. 이를 위해 models 및 datasets 키 아래에서 정의할 수 있습니다. README 파일에 아티팩트를 나열하는 것 외에도, .py, .ini 또는 .html 파일에도 기록할 수 있습니다. 자동으로 파싱해 드립니다!

다음은 스페이스에서 두 모델을 연결하는 예시입니다:

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