liminfoHugging Face Reference
Hugging Face Transformers 레퍼런스
Hugging Face Reference 소개
Hugging Face Transformers 레퍼런스는 transformers, datasets, evaluate, huggingface_hub Python 라이브러리를 위한 검색 가능한 빠른 참조 도구입니다. 모델, 토크나이저, 파이프라인, Trainer, 데이터셋, 평가, 양자화, Hub의 여섯 가지 카테고리로 정리되어 있어 머신러닝 엔지니어가 NLP 및 생성형 AI 애플리케이션을 개발할 때 필요한 API 시그니처와 코드 스니펫을 즉시 찾을 수 있습니다.
연구자와 ML 엔지니어들은 AutoModelForCausalLM.from_pretrained(device_map="auto") 패턴, 학습률 스케줄링을 위한 TrainingArguments, 배치 토큰화를 사용한 dataset.map, evaluate 라이브러리와 compute_metrics 콜백 같은 패턴을 이 레퍼런스로 빠르게 확인합니다. 4비트 NF4 양자화를 위한 BitsAndBytesConfig, target_modules를 사용한 LoRA/PEFT, GPTQ 및 AWQ 양자화 모델 로딩, Gradio Spaces 배포 같은 고급 주제도 다룹니다.
콘텐츠는 일반적인 파인튜닝 워크플로를 따라 구성됩니다. 사전 학습 모델과 토크나이저 로드, Hub 또는 로컬 딕셔너리에서 데이터셋 준비, 학습 인자 정의, Trainer API로 학습, BLEU/ROUGE 또는 정확도 메트릭으로 평가, 메모리 절감을 위한 LoRA 또는 4비트 양자화 적용, 마지막으로 파인튜닝된 모델을 Hub에 업로드하는 흐름으로 이어집니다.
주요 기능
- AutoModel 계열: AutoModel, AutoModelForSequenceClassification, AutoModelForCausalLM, AutoModelForTokenClassification와 from_pretrained 옵션
- 토크나이저 API: AutoTokenizer.from_pretrained, encode/decode, max_length와 return_tensors를 사용한 패딩과 잘라내기
- 파이프라인 태스크: text-classification, text-generation, question-answering, translation, summarization, zero-shot-classification
- Trainer와 TrainingArguments: learning_rate, weight_decay, evaluation_strategy, per_device_train_batch_size, num_train_epochs
- 데이터셋 라이브러리: Hub에서 load_dataset, 배치 처리를 사용한 dataset.map, filter, train_test_split, Dataset.from_dict
- 평가 메트릭: evaluate.load로 accuracy, BLEU, ROUGE 계산; compute_metrics 콜백; eval_loss로 퍼플렉시티 계산
- 양자화: BitsAndBytesConfig (4비트 NF4), GPTQ 및 AWQ 모델 로딩, LoraConfig와 target_modules를 사용한 LoRA/PEFT
- Hub 작업: push_to_hub, save_pretrained, huggingface-cli login, HfApi, create_repo, snapshot_download, Gradio Spaces
자주 묻는 질문
Hugging Face Transformers 라이브러리란 무엇인가요?
Hugging Face Transformers 라이브러리는 NLP, 비전, 오디오 태스크를 위한 수천 개의 사전 학습 모델을 제공합니다. AutoModel, AutoTokenizer, pipeline이라는 통합 API로 Hub에서 모델을 로드하고 Trainer 클래스로 파인튜닝할 수 있습니다. PyTorch, TensorFlow, JAX 백엔드를 지원하며 datasets 및 evaluate 라이브러리와 통합됩니다.
pipeline API란 무엇이고 언제 사용하나요?
pipeline API는 사전 학습 모델로 추론을 실행하는 가장 간단한 방법입니다. pipeline("text-classification")을 호출하면 원시 문자열을 받아 구조화된 예측을 반환하는 callable이 생성됩니다. 프로토타입 제작과 커스텀 학습 로직이 필요 없는 프로덕션 추론에 이상적입니다. 파인튜닝이 필요하면 Trainer나 커스텀 학습 루프를 사용합니다.
Trainer 클래스로 모델을 파인튜닝하는 방법은?
TrainingArguments를 output_dir, num_train_epochs, learning_rate, per_device_train_batch_size로 초기화합니다. 그런 다음 model, args, train_dataset, eval_dataset, 선택적으로 compute_metrics 콜백을 전달하여 Trainer를 생성합니다. trainer.train()으로 학습을 시작하고 trainer.evaluate()로 검증 메트릭을 계산합니다. Trainer는 그래디언트 누적, 혼합 정밀도, 분산 학습을 자동으로 처리합니다.
GPTQ, AWQ, BitsAndBytes 4비트 양자화의 차이는 무엇인가요?
BitsAndBytesConfig의 load_in_4bit는 bitsandbytes 라이브러리를 사용해 로드 시 사후 양자화를 수행합니다. 편리하지만 품질이 약간 낮습니다. GPTQ는 캘리브레이션 데이터를 사용해 가중치를 사전 양자화하여 Hub에 저장합니다. AWQ(활성화 인식 가중치 양자화)도 사전 양자화하지만 중요 가중치를 보존해 더 나은 정확도를 제공합니다. 일상적 추론에는 BitsAndBytes, 프로덕션 배포에는 GPTQ나 AWQ를 선호합니다.
LoRA / PEFT가 파인튜닝 메모리 요구량을 줄이는 원리는?
LoRA(저랭크 적응)는 원래 모델 가중치를 동결하고 특정 선형 레이어(q_proj, v_proj 같은 target_modules)에 작은 학습 가능한 저랭크 행렬을 추가합니다. 학습 중 이 어댑터 가중치만 업데이트되어 전체 파인튜닝 대비 GPU 메모리를 10~100배 줄일 수 있습니다. peft 라이브러리의 get_peft_model(model, LoraConfig(...))로 모든 모델을 래핑할 수 있습니다.
evaluate 라이브러리로 BLEU나 ROUGE 점수를 계산하는 방법은?
evaluate 라이브러리를 설치하고 evaluate.load("rouge") 또는 evaluate.load("bleu")를 호출합니다. 예측값(생성된 텍스트)과 참조값(정답)을 문자열 리스트로 metric.compute()에 전달합니다. ROUGE는 rouge1, rouge2, rougeL, rougeLsum 점수를 반환합니다. EvalPrediction 네임드튜플을 받는 compute_metrics 콜백을 통해 Trainer와 통합할 수 있습니다.
파인튜닝된 모델을 Hugging Face Hub에 업로드하는 방법은?
huggingface-cli login 또는 Python에서 login(token="hf_xxx")으로 로그인합니다. model.save_pretrained("./my_model")과 tokenizer.save_pretrained("./my_model")으로 로컬에 저장한 후 model.push_to_hub("username/my-model")로 업로드합니다. create_repo("my-model", private=True)로 비공개 저장소를 먼저 만들 수도 있습니다. HfApi 클래스는 저장소 관리를 프로그래밍 방식으로 제어합니다.
model.generate()로 출력 길이와 샘플링을 제어하는 방법은?
model.generate()는 자기회귀 텍스트 생성을 실행합니다. 토크나이저의 input_ids를 전달하고 max_new_tokens로 출력 길이를 제한합니다. do_sample=True(샘플링 활성화), temperature(낮을수록 더 집중적), top_p(핵 샘플링), repetition_penalty로 품질을 제어합니다. 탐욕적 디코딩에는 do_sample을 생략합니다. 생성된 토큰 ID는 tokenizer.decode(outputs[0], skip_special_tokens=True)로 디코딩합니다.