성남 프론트엔드

16일차_Hugging Face

sojsoj 2026. 7. 22. 16:51

1. Hugging Face란?

Hugging Face는 AI 모델을 검색하고, 시험하고, 내려받고, 공유하는 플랫폼입니다.

흔히 “AI 분야의 GitHub”라고 부릅니다.

Models: 텍스트·이미지·음성·영상 AI 모델
Datasets: AI 학습용 데이터
Spaces: 브라우저에서 실행해 볼 수 있는 AI 데모
Papers: 최신 AI 논문
Collections: 목적별 모델 모음

Hugging Face의 Inference Providers는 무료 계정에 매달 소액의 체험 크레딧을 제공합니다. 현재 공식 문서에는 무료 사용자가 받는 크레딧이 월 $0.10이며 변경될 수 있다고 명시돼 있습니다. 크레딧을 소진하면 추가 크레딧 또는 별도 공급자 결제가 필요합니다.

공식 요금 안내

2. 목적별 무료 다운로드 가능 모델

아래 목록은 대표적인 공개·오픈 가중치 모델입니다. API 무료 제공을 보장하는 목록은 아니며, PC 사양과 라이선스를 반드시 확인해야 합니다.

텍스트 생성·챗봇·코딩

Qwen/Qwen3-4B	다국어·한국어·코딩·추론, 비교적 작은 4B 모델	Apache-2.0
Qwen/Qwen3-0.6B	저사양 PC 실습용	Apache-2.0
google/gemma-3-4b-it	이미지와 텍스트 이해가 가능한 소형 멀티모달 모델	Google 이용약관 동의 필요
microsoft/Phi-4-mini-instruct	작은 크기, 지시 수행과 코딩	MIT
deepseek-ai/DeepSeek-R1-Distill-Qwen-7B	수학·논리 추론 특화	비교적 높은 메모리 필요

초보자에게는 Qwen3-0.6B 또는 Qwen3-4B가 편합니다. Qwen3-4B는 100개 이상의 언어를 지원하며 Apache-2.0 라이선스로 공개돼 있습니다.

모델 설명

텍스트 → 이미지

black-forest-labs/FLUX.1-schnell	빠르고 품질이 좋은 이미지 생성	12B 모델로 GPU 메모리 요구량이 큼, 접근 조건 동의 필요
stabilityai/stable-diffusion-xl-base-1.0	자료와 예제가 풍부한 SDXL	라이선스 확인 필요
stabilityai/sd-turbo	적은 단계로 빠르게 생성	세밀한 품질은 SDXL과 차이 가능

FLUX.1-schnell은 Apache-2.0 모델이지만 파일 접근 전 조건 동의가 필요할 수 있습니다. 모델 페이지

이미지 → 이미지·사진 편집

Qwen/Qwen-Image-Edit	자연어로 사진 수정, 물체·스타일 변경	고성능 GPU 권장
timbrooks/instruct-pix2pix	“배경을 밤으로 바꿔줘” 같은 지시 기반 편집	비교적 오래됐지만 예제가 많음
stabilityai/stable-diffusion-2-1-unclip	이미지를 참고한 변형 생성	라이선스 확인 필요

Qwen Image Edit는 Apache-2.0이며 Diffusers에서 이미지와 명령을 함께 입력할 수 있습니다. 사용 예제

이미지 → 텍스트·이미지 이해

Salesforce/blip-image-captioning-base	사진 설명문 생성
Salesforce/blip-vqa-base	사진에 관한 질문에 답변
Qwen/Qwen2.5-VL-3B-Instruct	이미지·문서·차트 이해
google/gemma-3-4b-it	이미지와 텍스트를 함께 이해

저사양 실습에는 BLIP, 문서·표·복합 이미지 분석에는 Qwen2.5-VL 계열이 알맞습니다.

음성 → 텍스트

openai/whisper-small	한국어 포함 99개 언어 음성 인식
openai/whisper-large-v3-turbo	정확도와 속도가 좋은 대형 모델
facebook/wav2vec2-base-960h	영어 음성 인식 실습

Whisper Small은 Apache-2.0이며 automatic-speech-recognition 파이프라인으로 실행할 수 있습니다. 모델 사용법

텍스트 → 음성

hexgrad/Kokoro-82M	작고 빠른 고품질 음성 합성	기본적으로 영어 중심
suno/bark-small	말투·효과음·다국어 음성 생성	결과가 일정하지 않을 수 있음
facebook/mms-tts-kor	한국어 음성 합성	자연스러움은 최신 상용 TTS보다 낮을 수 있음

Kokoro는 82M 크기의 Apache-2.0 오픈 가중치 모델이어서 로컬 실습에 적합합니다. 모델 설명

영상 생성

Wan-AI/Wan2.1-T2V-1.3B	텍스트 → 짧은 영상	이미지보다 훨씬 많은 GPU 메모리와 시간이 필요
stabilityai/stable-video-diffusion-img2vid-xt	이미지 → 영상	라이선스·GPU 요구사항 확인
ali-vilab/i2vgen-xl	이미지 기반 영상 생성	고성능 GPU 권장

이미지 분석·분리·깊이 측정

facebook/sam2-hiera-small	이미지·영상 속 물체 영역 분리
depth-anything/Depth-Anything-V2-Small-hf	한 장의 사진에서 깊이 추정
facebook/detr-resnet-50	사진 속 물체 탐지

SAM2 Small과 Depth Anything V2 Small은 모두 Apache-2.0으로 공개돼 있습니다. SAM2, Depth Anything

번역·임베딩·검색

facebook/nllb-200-distilled-600M	다국어 번역
intfloat/multilingual-e5-small	한국어 문서 검색·RAG·유사도
sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2	다국어 문장 비교

3. Hugging Face Access Token을 VS Code에 연결하는 방법

VS Code 터미널에 Hugging Face 로그인 정보를 저장한 뒤, VS Code에서 실행하는 Python 코드가 해당 Access Token을 자동으로 사용하도록 설정합니다.

아래는 Windows와 VS Code 기준입니다.

아래처럼 venv 부분을 Conda 가상환경 기준으로 바꾸면 됩니다.

1단계: Conda 가상환경 준비

VS Code에서 File → Open Folder로 작업 폴더를 엽니다.

C:\AI\huggingface-study

VS Code에서 Terminal → New Terminal을 선택한 후 Conda 설치 여부를 확인합니다.

conda --version

Conda 가상환경 생성

Python 3.11 환경을 만듭니다.

conda create -n huggingface-study python=3.11 -y

가상환경을 활성화합니다.

conda activate huggingface-study

정상적으로 활성화되면 터미널 왼쪽에 다음처럼 표시됩니다.

(huggingface-study)

conda activate 오류가 발생할 때

다음 명령을 실행합니다.

conda init powershell

그다음 VS Code의 터미널을 모두 닫고 새 터미널을 열거나, VS Code를 재시작합니다.

conda activate huggingface-study

conda 명령 자체가 인식되지 않는다면 VS Code에서 Ctrl+Shift+P를 누르고 다음을 실행합니다.

Terminal: Select Default Profile

Command Prompt를 선택한 뒤 새 터미널에서 다시 시도할 수도 있습니다.

conda activate huggingface-study

VS Code Python 환경 선택

Ctrl+Shift+P를 누릅니다.
Python: Select Interpreter를 검색합니다.
다음과 비슷한 환경을 선택합니다.

Python 3.11 ('huggingface-study': conda)

선택된 Python 확인:

python -c "import sys; print(sys.executable)"

출력 경로에 huggingface-study 또는 Conda 환경 경로가 포함되어야 합니다.

4단계: 필요한 패키지 설치

먼저 Conda 환경이 활성화됐는지 확인합니다.

conda activate huggingface-study
python --version

pip를 업데이트합니다.

python -m pip install --upgrade pip

Hugging Face 기본 패키지를 설치합니다.

python -m pip install --upgrade huggingface_hub transformers accelerate safetensors

CPU에서 실행하는 경우

python -m pip install torch --index-url https://download.pytorch.org/whl/cpu

설치 확인:

python -c "import torch; print(torch.__version__); print('CUDA:', torch.cuda.is_available())"

CPU 환경이라면 다음처럼 표시되는 것이 정상입니다.

CUDA: False

NVIDIA GPU를 사용하는 경우

GPU 인식 여부를 확인합니다.

nvidia-smi

GPU가 표시되면 PyTorch 설치 페이지에서 다음 조건을 선택해 설치 명령을 받습니다.

OS: Windows
Package: Pip
Language: Python
Compute Platform: 자신의 CUDA 환경

설치 후 확인합니다.

python -c "import torch; print(torch.__version__); print('CUDA:', torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU 사용')"

이미지 생성·편집 패키지

python -m pip install diffusers pillow sentencepiece protobuf

음성 처리 패키지

python -m pip install librosa soundfile

전체 설치 확인

python -c "import torch, transformers, huggingface_hub; print('PyTorch:', torch.__version__); print('Transformers:', transformers.__version__); print('Hub:', huggingface_hub.__version__)"

5단계: Access Token으로 로그인

Conda 환경을 먼저 활성화합니다.

conda activate huggingface-study

Hugging Face에 로그인합니다.

hf auth login

메뉴에서 다음을 선택합니다.

Paste an access token

발급받은 hf_... 토큰을 붙여 넣습니다.

로그인 확인:

hf auth whoami

사용자 이름이 표시되면 정상적으로 연결된 것입니다.

로그아웃

hf auth logout

다른 토큰으로 다시 로그인

hf auth login --force

6단계: 연결 시험

Conda 환경을 활성화합니다.

conda activate huggingface-study

Python에서 로그인 상태를 확인합니다.

python -c "from huggingface_hub import whoami; print(whoami())"

모델 설정 파일 다운로드를 시험합니다.

hf download Qwen/Qwen3-0.6B config.json

파일이 내려받아지면 연결과 인증이 모두 정상입니다.

이후 VS Code를 다시 열 때

매번 새 터미널에서 다음 명령만 실행하면 됩니다.

conda activate huggingface-study

작업이 끝났을 때 가상환경 종료:

conda deactivate

전체 명령 모음

CPU 환경 기준으로 순서대로 실행할 명령입니다.

conda create -n huggingface-study python=3.11 -y
conda activate huggingface-study
python -m pip install --upgrade pip
python -m pip install --upgrade huggingface_hub transformers accelerate safetensors
python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install diffusers pillow sentencepiece protobuf
python -m pip install librosa soundfile
hf auth login
hf auth whoami
python -c "from huggingface_hub import whoami; print(whoami())"
hf download Qwen/Qwen3-0.6B config.json

7단계: 텍스트 AI 실행하기

VS Code에서 text_ai.py 파일을 만들고 다음 코드를 입력합니다.

from transformers import pipeline

model_id = "Qwen/Qwen3-0.6B"

generator = pipeline(
    task="text-generation",
    model=model_id,
    device_map="auto",
)

messages = [
    {
        "role": "user",
        "content": "허깅페이스가 무엇인지 초보자에게 한국어로 설명해 줘. /no_think",
    }
]

result = generator(
    messages,
    max_new_tokens=300,
    do_sample=True,
    temperature=0.7,
)

print(result[0]["generated_text"][-1]["content"])

실행합니다.

python text_ai.py

첫 실행에는 모델을 내려받기 때문에 시간이 걸립니다. 이후에는 기본적으로 다음 위치의 캐시를 사용합니다.

C:\Users\사용자이름\.cache\huggingface\hub

8단계: Access Token으로 API 호출하기

로컬 PC에서 모델 전체를 실행하지 않고 Hugging Face의 서버에 요청하는 방식입니다.

api_chat.py 파일을 만듭니다.

from huggingface_hub import InferenceClient

# hf auth login으로 저장한 토큰을 자동으로 사용합니다.
client = InferenceClient(provider="auto")

response = client.chat.completions.create(
    model="Qwen/Qwen3-4B",
    messages=[
        {
            "role": "user",
            "content": "인공지능을 초등학생도 이해할 수 있게 설명해 줘.",
        }
    ],
    max_tokens=300,
)

print(response.choices[0].message.content)

실행합니다.

python api_chat.py

모델이 현재 Inference Provider에서 제공되지 않으면 다른 API 지원 모델을 선택해야 합니다. API 사용은 무료 크레딧을 소모하며 한도 이후 비용이 발생할 수 있습니다.

9단계: 환경변수로 토큰 전달하기

CLI에 로그인하지 않고 현재 터미널에서만 토큰을 사용할 수도 있습니다.

$env:HF_TOKEN="hf_발급받은_토큰"

확인할 때 실제 토큰 전체를 출력하지 말고 다음처럼 검사합니다.

if ($env:HF_TOKEN) { "HF_TOKEN 설정됨" } else { "HF_TOKEN 없음" }

그다음 Python 프로그램을 실행합니다.

python api_chat.py

VS Code 터미널을 닫으면 이 환경변수는 사라집니다.

공식적으로 HF_TOKEN 환경변수가 설정돼 있으면 컴퓨터에 저장된 토큰보다 우선합니다. 환경변수 설명

피해야 하는 방법

다음처럼 토큰을 Python 코드에 직접 쓰지 않습니다.

# 사용 금지
token = "hf_실제토큰"

또한 토큰을 명령어에 그대로 포함하면 PowerShell 명령 기록에 남을 수 있으므로 hf auth login에서 대화식으로 붙여 넣는 방법이 가장 편리합니다.

10단계: 텍스트로 이미지 만들기

GPU가 있는 환경을 권장합니다.

image_ai.py를 만듭니다.

import torch
from diffusers import AutoPipelineForText2Image

model_id = "stabilityai/sd-turbo"

pipe = AutoPipelineForText2Image.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
    variant="fp16",
)

pipe = pipe.to("cuda")

prompt = """
A quiet Korean traditional village in winter,
warm lights, cinematic composition, highly detailed
"""

image = pipe(
    prompt=prompt,
    num_inference_steps=2,
    guidance_scale=0.0,
).images[0]

image.save("generated_image.png")
print("generated_image.png 저장 완료")

실행:

python image_ai.py

일부 모델은 모델 페이지에 들어가 이용약관에 먼저 동의해야 합니다. 로그인했더라도 약관 동의가 없으면 401 또는 403 오류가 발생할 수 있습니다.

11단계: 이미지 내용을 글로 설명하기

필요 패키지:

pip install pillow transformers torch

image_caption.py:

from transformers import pipeline

captioner = pipeline(
    "image-to-text",
    model="Salesforce/blip-image-captioning-base",
    device_map="auto",
)

result = captioner("sample.jpg")
print(result[0]["generated_text"])

실행:

python image_caption.py

12단계: 음성을 텍스트로 변환하기

whisper_ai.py:

from transformers import pipeline

transcriber = pipeline(
    "automatic-speech-recognition",
    model="openai/whisper-small",
    device_map="auto",
)

result = transcriber(
    "meeting.mp3",
    generate_kwargs={
        "language": "korean",
        "task": "transcribe",
    },
)

print(result["text"])

실행:

python whisper_ai.py

13단계: Claude Code에서 Hugging Face CLI 활용하기

Claude는 Hugging Face 모델 자체가 아닙니다. 두 서비스를 연결하는 방법은 크게 두 가지입니다.

방법 A: Claude에게 실행 코드를 작성·수정하게 하기

Claude 또는 Claude Code에 다음처럼 요청할 수 있습니다.

Hugging Face의 Qwen/Qwen3-0.6B 모델을 로컬에서 실행하는
Python 프로그램을 작성해 줘.

조건:
- transformers pipeline 사용
- Windows와 VS Code 기준
- 토큰은 환경 변수로 읽기
- 한국어 입력 예제 포함
- 오류가 발생하면 원인을 설명하기

Claude Code를 VS Code 터미널에서 사용한다면 Claude가 프로젝트 파일을 만들고 실행 오류를 수정하도록 할 수도 있습니다. 다만 모델 다운로드와 실제 연산은 여전히 사용자 PC 또는 Hugging Face API에서 수행됩니다.

방법 B: Hugging Face MCP 연결하기

Hugging Face에 로그인합니다.
MCP 설정 페이지에서 Claude Desktop 또는 해당 MCP 클라이언트를 선택합니다.
페이지가 제공하는 설정을 복사합니다.
Claude의 MCP 설정에 붙여 넣습니다.
Claude를 다시 시작합니다.
다음처럼 요청합니다.

Hugging Face에서 Apache-2.0 라이선스이며
한국어를 지원하는 4B 이하 텍스트 생성 모델을 찾아서 비교해 줘.

또는:

텍스트를 이미지로 만드는 공개 모델 중
현재 Inference Provider로 시험 가능한 모델을 찾아 줘.

Hugging Face 공식 MCP는 Claude Desktop, VS Code, Cursor, Codex 등 MCP 호환 도구에서 모델·데이터셋·Spaces를 탐색할 수 있도록 지원합니다. 공식 문서

14단계: VS Code 또는 Claude에 MCP 연결하기

Hugging Face 공식 MCP 서버를 연결하면 AI 비서가 다음 작업을 수행할 수 있습니다.

모델과 데이터셋 검색
모델 설명서 확인
Hugging Face 문서 검색
Spaces 기반 커뮤니티 도구 실행

연결 순서:

Hugging Face에 로그인합니다.
Hugging Face MCP 설정을 엽니다.
VS Code 또는 Claude Desktop을 선택합니다.
화면에 제공되는 설정을 복사합니다.
해당 프로그램의 MCP 설정에 붙여 넣습니다.
VS Code 또는 Claude를 다시 시작합니다.
MCP 도구 목록에서 Hugging Face가 표시되는지 확인합니다.

MCP 설정 형식은 프로그램 버전에 따라 바뀔 수 있으므로 공식 설정 페이지에서 현재 클라이언트용 코드를 복사하는 것이 안전합니다. 공식 MCP 안내

설치 명령 한 번에 보기

기본 텍스트·API 환경:

python -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install --upgrade huggingface_hub transformers accelerate safetensors
pip install torch --index-url https://download.pytorch.org/whl/cpu
hf auth login
hf auth whoami

이미지·음성 기능 추가:

pip install diffusers pillow sentencepiece protobuf librosa soundfile

설치 검사:

python -c "import torch; print('PyTorch:', torch.__version__)"
python -c "import transformers; print('Transformers:', transformers.__version__)"
python -c "from huggingface_hub import whoami; print(whoami())"

화면 캡처 없이도 메뉴 이름과 명령만으로 진행할 수 있도록 구성했습니다. Hugging Face 화면이 변경되더라도 Settings → Access Tokens와 공식 MCP 설정 페이지를 기준으로 진행하면 됩니다.

'성남 프론트엔드' 카테고리의 다른 글

15일차_YOLO 심화 (1)	2026.07.21
14일차_DATA 수집 ~ YOLO 객체 탐지 (0)	2026.07.20
13일차_ Anaconda / Python문법 (0)	2026.07.16
12일차_Vercel배포 (0)	2026.07.15
12일차_Node·Express /POST 보내기/ (0)	2026.07.14

현재글16일차_Hugging Face

sojsoj 님의 블로그

sojsoj 님의 블로그 입니다.

Today :
Yesterday :

sojsoj 님의 블로그

16일차_Hugging Face

1. Hugging Face란?

2. 목적별 무료 다운로드 가능 모델

3. Hugging Face Access Token을 VS Code에 연결하는 방법

1단계: Conda 가상환경 준비

Conda 가상환경 생성

conda activate 오류가 발생할 때

VS Code Python 환경 선택

4단계: 필요한 패키지 설치

CPU에서 실행하는 경우

NVIDIA GPU를 사용하는 경우

이미지 생성·편집 패키지

음성 처리 패키지

전체 설치 확인

5단계: Access Token으로 로그인

로그아웃

다른 토큰으로 다시 로그인

6단계: 연결 시험

이후 VS Code를 다시 열 때

전체 명령 모음

7단계: 텍스트 AI 실행하기

8단계: Access Token으로 API 호출하기

9단계: 환경변수로 토큰 전달하기

피해야 하는 방법

10단계: 텍스트로 이미지 만들기

11단계: 이미지 내용을 글로 설명하기

12단계: 음성을 텍스트로 변환하기

13단계: Claude Code에서 Hugging Face CLI 활용하기

14단계: VS Code 또는 Claude에 MCP 연결하기

설치 명령 한 번에 보기

'성남 프론트엔드' 카테고리의 다른 글

'성남 프론트엔드'의 다른글

티스토리툴바

« 2026/08 »
일	월	화	수	목	금	토
						1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30	31

16일차_Hugging Face

1. Hugging Face란?

2. 목적별 무료 다운로드 가능 모델

3. Hugging Face Access Token을 VS Code에 연결하는 방법

1단계: Conda 가상환경 준비

Conda 가상환경 생성

conda activate 오류가 발생할 때

VS Code Python 환경 선택

4단계: 필요한 패키지 설치

CPU에서 실행하는 경우

NVIDIA GPU를 사용하는 경우

이미지 생성·편집 패키지

음성 처리 패키지

전체 설치 확인

5단계: Access Token으로 로그인

로그아웃

다른 토큰으로 다시 로그인

6단계: 연결 시험

이후 VS Code를 다시 열 때

전체 명령 모음

7단계: 텍스트 AI 실행하기

8단계: Access Token으로 API 호출하기

9단계: 환경변수로 토큰 전달하기

피해야 하는 방법

10단계: 텍스트로 이미지 만들기

11단계: 이미지 내용을 글로 설명하기

12단계: 음성을 텍스트로 변환하기

13단계: Claude Code에서 Hugging Face CLI 활용하기

14단계: VS Code 또는 Claude에 MCP 연결하기

설치 명령 한 번에 보기

'성남 프론트엔드' 카테고리의 다른 글

'성남 프론트엔드'의 다른글

관련글

티스토리툴바