TL;DR
- 허깅페이스 사용법의 기본은 Hub다. 모델과 데이터셋, 데모 앱(Spaces)이 저장소 형태로 올라와 있고 깃과 같은 방식으로 받아 쓴다.
- 파이썬에서는 transformers 한 줄로 모델을 불러오고, 직접 돌리기 부담스러우면 Inference Providers로 API 호출만 한다.
- 공개 저장소는 무료다. PRO 구독과 Team·Enterprise 플랜은 사설 저장소 용량, 조직 통제, 전용 추론 같은 항목을 위한 것이다.
허깅페이스 사용법을 알아보는 사람은 대개 모델 파일이 필요한 상황이다.
로컬에서 돌릴 가중치를 받거나, 데이터셋을 구하거나, 남이 만든 데모를 열어보고 싶은 것.
Hugging Face Hub는 그 셋을 한곳에 모아둔 저장소다.
공식 문서 기준으로 200만 개가 넘는 모델과 150만 개의 데이터셋, 150만 개의 앱이 공개돼 있다.
구조를 이해하면 나머지가 쉬워진다.
Hub의 모든 항목은 깃 저장소다.
모델도 저장소이고 데이터셋도 저장소다.
그래서 클론하고, 커밋하고, 브랜치를 딸 수 있다.
큰 파일은 별도 저장 백엔드로 처리되지만 다루는 방식은 같다.
아래는 계정을 만든 다음 모델을 받아 돌리고, 자기 모델을 올리고, 배포까지 가는 경로를 공식 문서 기준으로 정리한 것이다.
Hub에 올라와 있는 세 가지
모델은 학습된 가중치와 설정, 모델 카드로 이뤄진다.
모델 카드는 그 모델이 무엇으로 학습됐고 어떤 용도에 맞는지, 라이선스는 무엇인지 적는 문서다.
상업적으로 쓸 수 있는지 확인하려면 여기부터 봐야 한다.
데이터셋도 같은 구조다.
데이터셋 뷰어가 붙어 있어 내려받기 전에 브라우저에서 내용을 훑어볼 수 있다.
통계와 스키마도 함께 보인다.
Spaces는 데모 앱이다.
Gradio 같은 도구로 만든 화면이 실제로 돌아가고 있어서, 모델을 설치하지 않고 결과를 먼저 확인할 수 있다.
이미지 생성이나 영상 변환처럼 무거운 데모도 무료 GPU 자원 위에서 돌아가는 경우가 있다.
허깅페이스 사용법, 파이썬에서 모델 부르기
가장 흔한 경로는 transformers 라이브러리다.
모델 저장소 이름만 알면 코드 몇 줄로 불러온다.
저장소 이름은 조직명/모델명 형식이라, Hub 페이지 상단에 보이는 그 문자열을 그대로 쓰면 된다.
작업 흐름은 이렇다.
- Hub에서 하려는 작업으로 모델을 찾습니다. 텍스트 생성, 번역, 이미지 분류처럼 작업별로 분류돼 있습니다.
- 모델 카드에서 라이선스와 입출력 형식, 권장 사용법을 확인합니다.
- 접근이 제한된 모델이라면 페이지에서 사용 조건에 동의하고 토큰을 발급받습니다.
- 로컬에 라이브러리를 설치하고 저장소 이름으로 모델을 불러옵니다.
- 처음 실행하면 가중치를 내려받아 캐시에 저장합니다. 두 번째부터는 캐시를 씁니다.
- 결과가 나오면 입력 형식과 후처리를 모델 카드 예제와 대조합니다.
캐시 위치를 알아두면 디스크 관리가 편해진다.
큰 모델을 여러 개 시험하다 보면 수십 기가가 금방 쌓인다.
공식 문서에 로컬 캐시 구조와 정리 방법이 따로 정리돼 있다.
직접 돌리지 않고 API로 부르는 방법
장비가 감당하지 못하는 모델이라면 추론을 넘길 수 있다.
Inference Providers는 여러 추론 파트너를 하나의 인터페이스로 묶어둔 것으로, 공식 문서 기준으로 20만 개가 넘는 모델을 호출할 수 있다.
제공사를 직접 고르지 않고 같은 형식으로 요청을 보내는 구조다.
트래픽이 꾸준하고 지연이 중요한 서비스라면 Inference Endpoints 쪽이다.
전용 인프라에 모델을 올려두고 쓰는 방식이라 요청마다 대기 시간이 줄어든다.
자체 인프라에 올리는 경로도 있다.
텍스트 생성용 TGI와 임베딩용 TEI가 그것이고, AWS와 Azure, 구글 클라우드에 배포하는 문서가 각각 준비돼 있다.
라이브러리 지도
허깅페이스가 관리하는 라이브러리가 많아서 처음에는 어느 것을 써야 할지 헷갈린다.
자주 쓰는 것만 추리면 이렇다.
| 라이브러리 | 쓰는 곳 |
|---|---|
| Transformers | 언어·비전 모델 불러오기와 추론 |
| Diffusers | 이미지 생성 계열 확산 모델 |
| Datasets | 데이터셋 내려받기와 전처리 |
| Tokenizers | 토큰화 |
| PEFT | 적은 자원으로 미세조정 |
| Accelerate | 다중 GPU·혼합 정밀도 학습 |
| Sentence Transformers | 임베딩과 검색, 재순위 |
| Transformers.js | 브라우저에서 모델 실행 |
여기에 Hub와 직접 대화하는 도구가 따로 있다.
파이썬 클라이언트, 자바스크립트 라이브러리, 그리고 사람과 에이전트가 모두 쓸 수 있는 CLI다.
모델 업로드와 다운로드, 저장소 관리는 이쪽으로 처리한다.
자기 모델이나 데이터를 올릴 때
올리는 것도 저장소를 만드는 일이다.
웹에서 저장소를 만들고 파일을 올리거나, CLI로 푸시한다.
챙길 항목이 몇 가지 있다.
모델 카드를 쓰는 게 첫째다.
무엇으로 학습했고 어떤 한계가 있는지 적어두지 않으면 남이 쓸 수 없고, 나중에 자기도 기억하지 못한다.
라이선스를 명시하는 게 둘째다.
셋째는 접근 범위다.
공개로 둘지, 조직 안에서만 볼지, 조건에 동의한 사람에게만 열지 고를 수 있다.
민감한 데이터가 섞이지 않았는지 확인하는 절차도 필요하다.
한번 공개 저장소에 올라간 파일은 커밋 기록에 남는다.
요금이 붙는 지점
공개 모델과 데이터셋, Spaces를 호스팅하는 것 자체는 무료다.
이 정책이 Hub가 커진 이유이기도 하다.
유료 항목은 성격이 다르다.
PRO 구독이 개인용으로 있고, 조직용으로 Team과 Enterprise 플랜이 있다.
공식 문서의 구독 항목을 보면 조직 플랜에 붙는 기능이 무엇인지 드러난다.
통합 인증, 감사 로그, 저장 리전 지정, 리소스 그룹, 고급 보안, 토큰 관리, 네트워크 보안 같은 것들이다.
조직이 데이터와 접근을 통제하기 위해 사는 항목이다.
여기에 연산이 별도로 붙는다.
Spaces에 좋은 하드웨어를 붙이거나, 전용 추론 엔드포인트를 띄우거나, 학습용 자원을 쓰면 사용량 기준으로 요금이 발생한다.
한계와 안 맞는 경우
- 모델을 고르는 판단까지 대신해주지는 않는다. 200만 개 중 무엇이 내 작업에 맞는지는 직접 골라야 한다.
- 라이선스가 제각각이다. 상업적 사용이 막힌 모델이 섞여 있어 확인 없이 제품에 넣으면 문제가 된다.
- 큰 모델을 로컬에서 돌리려면 장비가 필요하다. 이 경우 LM Studio 사용법 쪽 구성이 더 편할 수 있다.
- 데모 Spaces는 언제든 멈출 수 있다. 만든 사람이 유지하는 것이라 서비스 가용성을 기대할 대상이 아니다.
Spaces로 결과를 먼저 확인하기
모델을 받기 전에 결과를 보고 싶을 때 쓰는 경로가 Spaces다.
다른 사람이 만들어 올린 데모가 실제로 돌아가고 있어서, 브라우저에서 입력을 넣어 출력을 확인할 수 있다.
이 단계가 시간을 크게 아낀다.
수십 기가짜리 모델을 받아 환경을 맞추고 돌려본 뒤에야 “내 작업에는 안 맞는다”를 알게 되는 상황을 피할 수 있기 때문이다.
Spaces를 직접 만들 수도 있다.
간단한 화면 프레임워크로 입력과 출력을 붙이면 데모가 되고, 저장소처럼 공개 범위를 정할 수 있다.
팀 안에서 모델을 검토할 때 각자 환경을 맞추는 대신 링크 하나를 공유하는 방식이 된다.
주의할 점은 가용성이다.
만든 사람이 유지하는 것이라 언제든 멈출 수 있고, 무료 자원 위에서 도는 데모는 대기가 걸리기도 한다.
확인 용도로는 충분하지만 서비스로 의존할 대상은 아니다.
제품 만들 때 가져갈 설계
첫째는 모든 것을 깃 저장소로 통일한 결정이다.
모델도 데이터도 앱도 같은 방식으로 다뤄지니 배울 것이 하나로 줄어든다.
새 개념을 만드는 대신 개발자가 이미 아는 개념을 재사용한 사례다.
둘째는 공개 호스팅을 무료로 연 점이다.
저장 비용을 회사가 감당하는 대신 생태계가 모였고, 그 생태계가 유료 상품의 근거가 됐다.
무료 구간을 마케팅 비용으로 본 셈이다.
셋째는 모델 카드라는 형식을 만든 것이다.
모델의 용도와 한계, 라이선스를 적는 자리를 제품 안에 규격으로 두면 그 정보가 쌓인다.
문서를 권장 사항이 아니라 저장소의 일부로 만든 방식이다.
실행 체크리스트
- 계정을 만들고 액세스 토큰을 발급받습니다.
- Hub에서 작업 종류로 모델을 검색합니다.
- 모델 카드에서 라이선스와 입출력 형식을 확인합니다.
- 상업적으로 쓸 계획이면 라이선스 조건을 먼저 확정합니다.
- 로컬에서 돌릴 거면 모델 크기와 장비 메모리를 대조합니다.
- 캐시 위치와 디스크 여유를 확인합니다.
- 장비가 부족하면 Inference Providers로 API 호출을 먼저 시험합니다.
- 서비스에 넣을 계획이면 전용 엔드포인트나 자체 배포 경로를 비교합니다.
- 자기 모델을 올릴 때는 모델 카드와 라이선스, 공개 범위를 함께 정합니다.
조직에서 쓸 때 정리할 것
회사 계정으로 쓴다면 개인 사용과 다른 항목이 생긴다.
토큰 관리가 첫째다.
액세스 토큰이 코드나 노트북에 그대로 남으면 저장소에 딸려 올라간다.
권한 범위를 최소로 발급하고 정기적으로 교체하는 규칙을 정해둔다.
둘째는 저장소 공개 범위다.
실수로 공개 저장소에 올린 파일은 커밋 기록에 남으므로, 조직 저장소를 기본 비공개로 두고 공개는 명시적으로 결정하는 방식이 안전하다.
자주 묻는 질문
허깅페이스는 무료인가요
공개 모델과 데이터셋, Spaces 호스팅은 무료입니다.
개인용 PRO 구독과 조직용 Team·Enterprise 플랜이 따로 있고, 전용 추론이나 고성능 하드웨어를 쓰면 사용량 요금이 붙습니다.
모델을 상업적으로 써도 되나요
모델마다 라이선스가 다릅니다.
모델 카드에 명시된 라이선스를 확인해야 하고, 상업적 사용이 제한된 모델도 있습니다.
장비가 부족하면 어떻게 하나요
Inference Providers로 API를 호출하거나 전용 Inference Endpoints를 씁니다.
자체 인프라에 올릴 경우에는 TGI나 TEI 같은 서빙 도구를 사용합니다.
내려받은 모델은 어디에 저장되나요
로컬 캐시 디렉터리에 저장되고 다음 실행부터 재사용됩니다.
여러 모델을 시험하면 용량이 빠르게 늘어나므로 캐시 정리 방법을 함께 봐두는 게 좋습니다.
