Hugging Face Spaces

개요

Hugging Face는 자연어 처리(NLP)와 컴퓨터 비전을 중심으로 다양한 머신러닝 모델을 제공하는 종합 플랫폼입니다. 오픈 액세스 머신러닝 모델의 학습, 배포, 사용을 쉽게 하도록 설계되어 개발자와 연구자가 최신 모델에 접근하기 쉬워집니다.

Hugging Face는 Spaces 프로젝트의 일부로 애플리케이션과 정적 사이트 호스팅도 제공합니다. Hugging Face Spaces를 사용해 Quarto 웹사이트를 렌더링하고 호스팅하여 작업을 문서화하고 소개할 수 있습니다.

Hugging Face Spaces에서 Quarto 통합은 Quarto 팀이 만든 Docker 이미지로 이루어지며, Hugging Face가 이를 템플릿으로 쉽게 사용할 수 있도록 제공합니다.

Quarto로 Hugging Face Space를 만들고 배포하려면 Quarto의 Docker 템플릿으로 새 Space를 먼저 생성합니다. 그런 다음 예제 콘텐츠를 자신의 콘텐츠로 편집하거나 교체합니다. 자세한 과정은 아래 시작하기를 참고하세요.

Hugging Face Space에 변경 사항을 커밋하면 새 빌드가 시작되어 Quarto 웹사이트를 렌더링하고 제공합니다. Hugging Face UI에서 직접 변경하고 커밋할 수도 있지만, Hugging Face에서 빌드로 미리보는 과정은 시간이 오래 걸립니다. 더 빠른 반복을 위해 로컬에서 작업하고 quarto publish huggingface 명령을 사용하는 것을 권장합니다. 이 워크플로는 아래 배포 명령에서 설명합니다.

시작하기

새 Space 만들기

시작하려면 Quarto 템플릿으로 새 Hugging Face Space를 만드세요.

Hugging Face 새 Space 만들기 페이지로 이동하세요.

Hugging Face에 로그인되어 있지 않다면 먼저 로그인하세요.

Screenshot of UI for logging in to Hugging Face.

The UI for logging in to Hugging Face

Space 이름과 라이선스를 먼저 선택하세요.

Screenshot of Hugging Face UI for space creation consisting of three text boxes labelled: Owner, Space name and License.

The UI for choosing name and license for your space

위 링크를 사용했다면 Space SDK로 “Docker”, Docker 템플릿으로 “Quarto”가 선택되어 있을 것입니다. 그렇지 않다면 아래처럼 선택하세요.

Screenshot of Hugging Face UI for selecting the space SDK and template. The Docker SDK and Quarto template are highlighted.

The UI for Hugging Face Spaces creation webpage

마지막으로 Space 실행에 사용할 하드웨어와 공개/비공개 여부를 선택하고 “Create Space”를 클릭하세요.

Screenshot of Hugging Face UI showing: a dropdown labelled 'Space Hardware', two radio buttons labelled Public (selected) and Private, and a button labelled 'Create Space'.

The UI for choosing hardware configuration and space visibility

그 다음 Hugging Face가 Space를 “Build”합니다.

Warning

Docker 빌드가 끝난 후 Space가 Hugging Face에 배포되는 데 몇 분이 걸릴 수 있습니다. 변경 사항을 보려면 다음 두 가지를 수행해야 합니다.

  1. Space 상태가 ’Building’에서 ’Running’으로 바뀔 때까지 기다리기(상태 바에서 확인 가능)

  2. 브라우저에서 Shift를 누른 채 새로고침 버튼을 눌러 강제 새로고침하기

Screenshot of the Build log in a Hugging Face Space. Log starts with and ends with

Build process for a new space based on the Quarto template

상단 바에 Running이 표시되면 빌드가 완료된 것입니다.

Hugging Face Running badge

빌드가 완료되면 Space에 렌더링된 예제 웹사이트가 표시됩니다(브라우저에서 새로고침해야 보일 수 있습니다).

Screenshot of a Hugging Face Space, displaying a website with the title ''.

A Quarto template website running in a Hugging Face Space

Quarto의 Hugging Face 템플릿

오른쪽 상단의 Files 탭을 클릭해 템플릿 파일을 확인할 수 있습니다. Quarto의 Hugging Face 템플릿은 Quarto 웹사이트를 빌드/렌더링하는 환경을 만드는 파일(Dockerfile, requirements.txt)과 src/에 있는 웹사이트 소스로 구성됩니다.

  • Dockerfile: Hugging Face에서 Quarto 사이트를 빌드하고 제공하기 위한 시스템 설정이 들어 있습니다. 추가 시스템 의존성을 넣거나 Quarto 버전을 변경해야 하지 않는 한 수정할 필요가 없습니다.

  • requirements.txt: 웹사이트에 필요한 Python 의존성을 여기에 포함합니다. Dockerfile 빌드 시 설치됩니다.

  • src 디렉터리에는 Quarto 웹사이트의 소스 파일이 있습니다. Jupyter 노트북이나 마크다운(.qmd, .md) 파일을 포함할 수 있습니다.

  • src/_quarto.yml은 웹사이트 내비게이션을 정의합니다. 새 페이지를 추가하거나 기존 페이지를 재구성하려면 이 파일을 변경해야 합니다.

Hugging Face UI에서 직접 편집할 수도 있지만, Space를 클론해 로컬에서 변경과 미리보기를 수행한 뒤 다음 섹션에서 설명하는 배포 명령을 사용하는 것을 권장합니다.

배포 명령

quarto publish huggingface 명령은 로컬에서 편집 및 미리보기를 한 뒤 Hugging Face Space에 배포하는 워크플로를 지원합니다. 명령을 사용하기 전에 설정을 완료해야 합니다.

설정

quarto publish huggingface 사용을 위해 다음을 먼저 완료해야 합니다.

  1. 위에서 설명한 대로 Quarto Docker 템플릿으로 Space 생성

그 다음 아래에 자세히 설명된 단계를 완료하세요.

  1. (선택) 권한 토큰이 없다면 생성

  2. 저장소를 로컬로 클론

권한 토큰 만들기

Hugging Face에 배포하려면 quarto publish가 자격 증명에 접근해야 합니다. 권한 토큰이 없다면 Hugging Face 사용자 액세스 토큰 문서를 참고해 write 역할의 토큰을 생성하세요. 배포 명령을 처음 실행할 때 이 토큰이 필요합니다.

저장소를 로컬로 클론

Space URL과 저장소 클론 URL은 https://huggingface.co/spaces/<your-hugging-face-username>/<name-of-space> 형식입니다. 위 URL로 방금 만든 Hugging Face Space를 원하는 git 인터페이스로 클론하세요. Space의 ⋮ > Clone repository에서도 안내를 확인할 수 있습니다.

편집 및 미리보기

저장소가 준비되면 원하는 텍스트 편집기로 변경 사항을 작성하세요. Quarto의 Hugging Face 템플릿은 저장소의 src/ 디렉터리에 Quarto 웹사이트를 포함합니다. Quarto로 웹사이트를 만드는 방법은 문서를 참고하세요.

변경 사항을 미리보려면 저장소 루트에서 다음을 실행합니다.

Terminal
quarto preview src

배포

저장소 결과가 만족스러우면 다음을 실행하세요.

Terminal
quarto publish huggingface

Quarto는 필요한 변경 사항을 스테이징, 커밋, 푸시하며, 먼저 원격 콘텐츠를 가져와 저장소 내용과 병합합니다. 작업 중인 저장소가 사용자 이름과 권한 토큰을 명시적으로 받도록 설정되지 않았다면, Quarto가 명령줄에서 해당 정보를 요청합니다.

완료되면 Quarto가 기본 브라우저에서 Space를 엽니다.

기존 저장소 배포

quarto publish huggingface 명령은 origin git remote가 https://huggingface.co/spaces URL을 가리켜야 합니다. 위 안내를 따랐다면 자동으로 설정됩니다.

올바른 URL을 가리키는 Quarto 템플릿으로 이미 구성된 기존 저장소를 사용 중이라면, 새 Space를 만들거나 클론하지 않고도 quarto publish huggingface를 바로 사용할 수 있습니다.