허깅페이스에서 모델을 받는 명령은 이제 hf download입니다. 검색하면 많이 나오는 huggingface-cli는 구 명령이라 최신 버전에서는 hf로 바뀌었습니다. 이 글은 가상환경 만들기부터 모델 다운로드, 저장 위치 확인, 받은 모델을 파이썬에서 실제로 돌려 토큰을 뽑아내는 것까지 직접 실행한 결과로 정리했습니다. 기준은 huggingface_hub 2.2.0, transformers 5.19.0입니다.
허깅페이스가 무엇을 하는 곳인가
허깅페이스(Hugging Face)는 공개된 AI 모델과 데이터셋이 모여 있는 저장소입니다. 깃허브가 코드를 올려두는 곳이라면, 허깅페이스는 학습이 끝난 모델 가중치를 올려두는 곳이라고 보면 됩니다. Qwen, Gemma, Llama 같은 모델의 원본이 전부 여기 있습니다.
로컬 LLM을 쓰는 입장에서 중요한 건 두 가지입니다. 모델 저장소 이름이 조직명/모델명 형식이라는 것(예: Qwen/Qwen2.5-0.5B-Instruct), 그리고 같은 모델이 여러 형식으로 올라와 있다는 것입니다. 파이썬에서 돌릴 거면 safetensors 형식을, Ollama나 LM Studio에서 쓸 거면 GGUF 형식을 받으면 됩니다.
설치 — 가상환경부터 만든다
시스템 파이썬에 바로 설치하면 나중에 버전이 꼬입니다. 프로젝트별로 가상환경을 만드는 게 기본입니다.
python3 -m venv hf
source hf/bin/activate
pip install huggingface_hub
윈도우에서는 두 번째 줄이 hf\Scripts\activate입니다. 설치가 끝나면 확인합니다.
hf version
여기서 command not found: huggingface-cli가 뜬다면 명령 이름이 바뀐 것뿐입니다. 최신 버전은 hf 하나로 통합됐고, download upload auth cache 같은 하위 명령을 받습니다.
모델 다운로드 — 세 가지 방법
저장소 전체를 받을 수도 있고 파일 하나만 받을 수도 있습니다. 용량이 크므로 필요한 파일만 지정하는 편이 낫습니다.
| 방법 | 명령·코드 | 용도 |
|---|---|---|
| CLI (파일 1개) | hf download Qwen/Qwen2.5-0.5B-Instruct-GGUF qwen2.5-0.5b-instruct-q4_k_m.gguf |
GGUF 하나만 |
| CLI (저장소 전체) | hf download Qwen/Qwen2.5-0.5B-Instruct |
파이썬에서 쓸 safetensors |
| 파이썬 | from huggingface_hub import snapshot_download |
스크립트에 내장 |
실제로 0.5B GGUF 파일 하나를 받아보면 491.4MB가 7.6초에 끝납니다. 명령이 끝나면 저장된 전체 경로를 출력해 주므로 그 경로를 그대로 Ollama나 LM Studio에 넣으면 됩니다.
받은 모델은 어디에 저장되나
현재 폴더에 떨어지지 않습니다. 공용 캐시에 들어갑니다.
| 항목 | 경로 |
|---|---|
| 기본 캐시 | ~/.cache/huggingface/hub |
| 실제 파일 | hub/models--조직명--모델명/snapshots/커밋해시/ |
| 경로 변경 | 환경변수 HF_HOME 지정 |
용량 관리 명령이 따로 있습니다. hf cache ls로 받은 저장소와 크기를 보고, hf cache rm으로 지우고, hf cache prune으로 중단된 다운로드와 참조가 끊긴 버전을 정리합니다. 캐시 폴더를 탐색기로 직접 지우면 블롭과 참조가 어긋나므로 명령을 쓰는 편이 안전합니다. 같은 원칙이 Ollama에도 적용되는데, 그 부분은 Ollama 설치와 모델 삭제에 정리했습니다.
토큰은 언제 필요한가
공개 모델은 토큰 없이도 받아집니다. 다만 받을 때마다 인증되지 않은 요청이라는 경고가 뜨고, 속도 제한이 더 빡빡하게 걸립니다. 토큰이 반드시 필요한 경우는 두 가지입니다. 라이선스 동의가 필요한 제한 모델을 받을 때, 그리고 본인 저장소에 업로드할 때입니다.
발급은 허깅페이스 계정의 설정에서 액세스 토큰을 만들면 되고, 읽기 전용이면 read 권한으로 충분합니다. 등록은 다음 명령입니다.
hf auth login
받은 모델을 파이썬에서 돌려보기
여기서부터가 본론입니다. transformers를 설치하고 네 줄이면 돌아갑니다.
from transformers import AutoModelForCausalLM, AutoTokenizer
tok = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct", dtype=torch.float16).to("mps")
inputs = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt", return_dict=True).to("mps")
맥이면 "mps", 엔비디아 GPU면 "cuda"로 바꿉니다. 여기서 많이 걸리는 함정이 하나 있습니다. transformers 5.x부터 apply_chat_template이 텐서가 아니라 딕셔너리를 돌려줍니다. 예전 코드처럼 결과를 바로 generate()에 넣으면 AttributeError가 납니다. return_dict=True를 주고 generate(**inputs) 형태로 넘겨야 합니다.
M5 Max에서 실제로 돌린 결과입니다. 캐시가 있는 상태에서 모델 로드 0.7초, 생성 60토큰에 3.89초로 60 ÷ 3.89 = 15.4 tok/s가 나왔습니다. 가중치는 fp16 기준 0.99GB를 차지했습니다.
다만 출력 품질은 짚고 넘어가야 합니다. 0.5B 모델에 한국어로 질문하니 답변 중간에 한자어가 그대로 섞여 나왔습니다. 작은 모델은 한국어에서 다른 언어 토큰이 섞이는 일이 흔합니다. 동작 확인용으로는 충분하지만 실사용은 7B 이상을 권합니다. 내 카드가 몇 B까지 감당하는지는 VRAM 뜻과 확인 방법에서 계산식과 함께 정리했습니다.
자주 묻는 질문
huggingface-cli 가 없다고 나옵니다.
명령 이름이 hf로 바뀌었습니다. hf download, hf auth login처럼 쓰면 됩니다. 구 명령을 설명한 글이 아직 많아서 생기는 혼동입니다.
모델을 받았는데 폴더에 파일이 없습니다.
현재 폴더가 아니라 ~/.cache/huggingface/hub 아래에 저장됩니다. hf cache ls로 목록과 용량을 확인할 수 있고, 다운로드 명령이 끝나면 전체 경로도 출력됩니다.
safetensors 와 GGUF 중 뭘 받아야 하나요?
파이썬 transformers로 돌릴 거면 safetensors, Ollama나 LM Studio에서 쓸 거면 GGUF입니다. 같은 모델이라도 형식이 다르면 호환되지 않습니다.
토큰 없이도 쓸 수 있나요?
공개 모델은 가능합니다. 다만 속도 제한이 걸리고 경고가 뜹니다. 라이선스 동의가 필요한 모델은 토큰이 있어야 받아집니다.
출처: 제조사 공식 스펙과 공개 유통 가격 기준. 가격·스펙은 변동될 수 있으므로 구매 전 최신 정보를 확인하세요.
댓글 남기기