Quickstart

Quickstart

Hugging Face의 CPU와 GPU에서 Python 코드를 실행해요. 이 가이드에서는 CPU에서 간단한 명령을 실행한 다음, GPU에서 작은 언어 모델로 텍스트를 생성해 볼 거예요.

출처: 문서

본문

선불 크레딧(pre-paid credits)이 있는 Hugging Face 계정이 필요해요. 컴퓨팅 비용은 Pricing and Billing을 참고하세요.

1. CLI 설정

Hugging Face CLI 설치 후 계정에 로그인하세요.

>>> hf auth login

2. Hello World 실행

터미널에서 다음 명령을 실행하세요.

>>> hf jobs uv run python -c 'print("Hello from the cloud!")'

hf jobs uv run은 Hugging Face 인프라의 Python 환경에서 명령을 실행해요. 기본적으로 CPU를 사용하고 Job의 로그를 터미널로 스트리밍해요. 시작 후 다음이 보여요.

Hello from the cloud!

CLI는 Job ID와 페이지 링크도 출력해요. 링크를 열면 브라우저에서 상태와 로그를 볼 수 있어요. Job은 Jobs 페이지에서 다시 찾거나, ID를 아래 CLI 명령과 함께 사용할 수 있어요.

Job은 어떤 Docker 이미지에서도 명령을 실행할 수 있어요.

>>> hf jobs run ubuntu echo 'Hello from the cloud!'

이 가이드의 나머지는 hf jobs uv run을 사용해요. 이미지 사용 시점과 방법은 Using Docker images를 참고하세요.

3. GPU에서 모델 실행

준비된 스크립트로 로봇 이름을 생성해 보세요. GitHub에서 볼 수 있고 아래 코드도 확인할 수 있어요.

hf jobs uv run \
    --flavor t4-small \
    --timeout 5m \
    https://raw.githubusercontent.com/huggingface/hub-docs/main/examples/jobs/hello_gpu.py
  • --flavor t4-small은 NVIDIA T4 GPU가 있는 머신을 선택해요.
  • --timeout 5m은 Job에 5분 제한을 설정해요.

Job은 모델을 다운로드하고 답을 로그에 출력해요. 예를 들어:

RoboLearnbot

전체 스크립트는 다음과 같아요.

# /// script
# dependencies = ["torch", "transformers"]
# ///

from transformers import pipeline

generator = pipeline(
    "text-generation",
    model="HuggingFaceTB/SmolLM2-360M-Instruct",
    dtype="float16",
)
messages = [{
    "role": "user",
    "content": "Suggest a name for a robot that helps people learn Python. Answer with only the name.",
}]
outputs = generator(messages, max_new_tokens=48, do_sample=False, return_full_text=False)
print(outputs[0]["generated_text"])

의존성 헤더는 uv에게 Job에 torch와 transformers를 설치하라고 알려줘요. --with로 의존성을 지정할 수도 있어요. 로컬에는 hf CLI만 있으면 돼요.

스크립트는 Job의 GPU에서 SmolLM2-360M-Instruct를 실행해요. max_new_tokens는 답의 길이를 제한해요.

시작 시간은 하드웨어 가용성, 의존성 설치, 모델 다운로드에 따라 달라져요.

[!TIP] Ctrl+C를 누르면 로그 스트리밍이 멈추지만 Job은 계속 실행돼요. Job을 중지하려면 hf jobs cancel JOB_ID를 실행하고, JOB_ID를 CLI가 출력한 ID로 바꾸세요.

huggingface_hub 클라이언트로 Python에서도 같은 Job을 실행할 수 있어요.

from huggingface_hub import run_uv_job

job = run_uv_job(
    "https://raw.githubusercontent.com/huggingface/hub-docs/main/examples/jobs/hello_gpu.py",
    flavor="t4-small",
    timeout="5m",
)
print(job.url)

4. 결과 확인

GPU Job의 ID로 상태를 확인하고 로그를 다시 읽어보세요.

>>> hf jobs inspect JOB_ID
>>> hf jobs logs JOB_ID

성공적인 실행은 COMPLETED 상태를 가지며, 로그에 생성된 답이 담겨요.

답은 Job이 끝난 뒤에도 로그에 남아 있어요. 스크립트를 파일을 생성하도록 바꾼다면, 그 결과를 버킷이나 Hub 저장소에 저장해 Job이 지나도 살아남게 하세요.

직접 스크립트 시도해 보기 (선택)

위 코드를 hello_gpu.py에 복사하고 messages의 프롬프트를 수정한 뒤 로컬 파일을 실행하세요.

hf jobs uv run --flavor t4-small --timeout 5m hello_gpu.py

CLI가 수정된 스크립트를 자동으로 업로드해요. 다른 위치에 저장했다면 hello_gpu.py를 해당 경로로 바꾸세요.

다음 단계

더 큰 워크로드로 확장해 보세요.

더 알아보기 (Learn more)

hf jobs uv run으로 CPU/GPU에서 Python을 바로 실행하고, --flavor t4-small로 GPU 머신을, --timeout으로 실행 시간을 제한할 수 있어요. 스크립트의 의존성 헤더에 torch·transformers 같은 패키지를 적어두면 Job 환경에 자동 설치돼요. 상태·로그 확인은 hf jobs inspect와 hf jobs logs를 쓰세요.