허깅페이스 트랜스포머 라이브러리 사용법 총정리

이 글은 그 동안 틈틈히 사용했었던 허깅페이스 트랜스포머 라이브러리 사용법을 총정리해본다. 이 글은 QA 시스템, 문장 분류, 토큰 의미 예측 방법 등을 소개한다. 이 글은 생성AI의 핵심 아키텍처 모델인 트랜스포머를 잘 이용하고 싶은 개발자, 연구자, 학생들에게 도움이 된다. 

만약, 트랜스포머의 내부 동작 메커니즘이 궁금하다면, 다음 링크를 참고한다.

• 딥러닝 모델 트랜스포머 인코더 핵심 코드 구현을 통한 동작 메커니즘 이해하기

소개

허깅페이스는 트랜스포머 라이브러리를 개발하여, 관련 최신 모델을 다운로드하고, 쉽게 학습 및 사용할 수 있는 API 도구를 제공한다. 

트랜스포머를 통해 다음 기능을 구현할 수 있다. 

• 자연어처리: 텍스트 분류, 엔티티 인식, 질문 및 답변, 언어 모델링, 요약, 번역, 객관식 및 주관식 텍스트 생성
• 컴퓨터 비전: 이미지 분류, 객체 인식 및 세그먼테이션
• 오디오: 자동 음성 인식 및 분류
• 멀티모달: 표 해석 질문, OCR, 스캔 문서에서 정보 추출, 비디오 분류, 시각적 질문
• 사전 학습모델, 훈련 데이터셋 무료 다운로드 및 파인튜닝(Fine-tune a pretrained model, Fine-Tuning BERT using Hugging Face Transformers, How to Fine-Tune BERT for NER Using HuggingFace, Fine-Tuning the Pre-Trained bert-base-NER in Hugging Face for Named Entity Recognition (NER))

훈련 데이터셋 다운로드 제공 예(yelp_review_full · Datasets at Hugging Face)

지원되는 모델

아래 표를 보면 알겠지만, LLM(Large Language Model) 뿐 아니라 생성AI와 관련된 모든 사전 학습된 모델을 제공한다(상세 참고). 

• BERT
• CLIP
• EfficientNet
• LLaMA
• LLaVA
• ResNet
• Time series transformer
• ViT
• Wav2Vec2
• YOLOS

라이브러리 설치 방법

이 라이브러리 사용을 위해서는 NVIDIA GPU, CUDA, PyTorch, Tensorflow 사전 설치가 필요하다. 

명령행 터미널을 실행하고, 가상환경에서 다음을 입력해, 라이브러리를 설치한다.

pip install transformers[torch] datasets evaluate

설치하면, 추론 inference 등에 사용할 수 있는 파이프라인 객체를 사용할 수 있다. 파이프라인은 대부분 학습된 모델의 복잡성을 간소화한 API를 제공한다. 인식, 마스킹 언어 모델링, 특징 추출이 가능하다. 다음 코드는 그 예이다. 

import transformers, torch

from transformers import pipeline

print(transformers.__version__)

print(torch.cuda.is_available())

pipe = pipeline("text-classification", model="nlptown/bert-base-multilingual-uncased-sentiment", device=0)

msg = pipe("This restaurant is awesome")

print(msg)

다음과 같이 출력되면 성공한 것이다. 

트러블슈팅

현재 시점에서 텐서플로우 GPU버전은 패키지 의존성 에러가 발생한다. 참고로, pipeline에서 model과 device=0를 명시하면, 파이토치 GPU 버전으로 실행된다. 

방화벽으로 인해 오프라인 환경에서 실행해야 한다면 다음과 같이 설정 후 실행한다.

HF_DATASETS_OFFLINE=1 TRANSFORMERS_OFFLINE=1 \

python examples/pytorch/translation/run_translation.py --model_name_or_path google-t5/t5-small --dataset_name wmt16 --dataset_config ro-en ...

질의 응답 자료 학습

ChatGPT와 같이 질의 응답 자료를 학습 해본다. 학습된 모델은 허깅페이스의 허브에 저장해 놓고 재활용하기로 한다. 이를 위해, 다음과 같이 허깅페이스 토큰을 생성한다. 

이제, 다음과 같이 하습 데이터셋 다운로드 코딩한다. 

from huggingface_hub import notebook_login  # 허깅페이스 모델 업로드 위한 임포트

notebook_login()

from datasets import load_dataset  # squad 데이터셋 다운로드

squad = load_dataset("squad", split="train[:5000]")

squad = squad.train_test_split(test_size=0.2)

print(squad['train'][0])

다음과 같이 토크나이저에 훈련 텍스트 입력 처리를 위해, 최대 길이를 절단하는 등의 처리 함수를 코딩한다.

from transformers import AutoTokenizer  #  distilbert 토큰나이저 임포트

tokenizer = AutoTokenizer.from_pretrained("distilbert/distilbert-base-uncased") 

def preprocess_function(examples):

    questions = [q.strip() for q in examples["question"]]

    inputs = tokenizer(

        questions,

        examples["context"],

        max_length=384,

        truncation="only_second",

        return_offsets_mapping=True,

        padding="max_length",

    )

    offset_mapping = inputs.pop("offset_mapping")

    answers = examples["answers"]

    start_positions = []

    end_positions = []

    for i, offset in enumerate(offset_mapping):

        answer = answers[i]

        start_char = answer["answer_start"][0]

        end_char = answer["answer_start"][0] + len(answer["text"][0])

        sequence_ids = inputs.sequence_ids(i)

        # Find the start and end of the context

        idx = 0

        while sequence_ids[idx] != 1:

            idx += 1

        context_start = idx

        while sequence_ids[idx] == 1:

            idx += 1

        context_end = idx - 1

        # If the answer is not fully inside the context, label it (0, 0)

        if offset[context_start][0] > end_char or offset[context_end][1] < start_char:

            start_positions.append(0)

            end_positions.append(0)

        else:

            # Otherwise it's the start and end token positions

            idx = context_start

            while idx <= context_end and offset[idx][0] <= start_char:

                idx += 1

            start_positions.append(idx - 1)

            idx = context_end

            while idx >= context_start and offset[idx][1] >= end_char:

                idx -= 1

            end_positions.append(idx + 1)

    inputs["start_positions"] = start_positions

    inputs["end_positions"] = end_positions

    return inputs

데이터셋을 앞의 정의된 함수로 전처리한다. 필요하지 않은 열은 제거한다. 

tokenized_squad = squad.map(preprocess_function, batched=True, remove_columns=squad["train"].column_names)

학습을 위해 배치를 만든다. 

from transformers import DefaultDataCollator

data_collator = DefaultDataCollator()

from transformers import AutoModelForQuestionAnswering, TrainingArguments, Trainer

model = AutoModelForQuestionAnswering.from_pretrained("distilbert/distilbert-base-uncased")  # 사전 학습 모델을 파인튜닝한다

training_args = TrainingArguments(

    output_dir="my_awesome_qa_model",

    evaluation_strategy="epoch",

    learning_rate=2e-5,

    per_device_train_batch_size=16,

    per_device_eval_batch_size=16,

    num_train_epochs=3,

    weight_decay=0.01,

    push_to_hub=True,

)  # 학습될 모델 및 파라메터 명시

trainer = Trainer(

    model=model,

    args=training_args,

    train_dataset=tokenized_squad["train"],

    eval_dataset=tokenized_squad["test"],

    tokenizer=tokenizer,

    data_collator=data_collator,

)  # 전이학습모델, 파라메터, 데이터셋, 토크나이져, 배치처리를 위한 데이터 컬렉터 설정

trainer.train()  # 학습

trainer.push_to_hub()  # 학습된 데이터를 허브에 업로드

그 결과 다음과 같이 파인 튜닝된 학습 모델이 허브에 업로드되었다. 

다음과 같이 실행한다.

from transformers import pipeline

question = "How many programming languages does BLOOM support?"

context = "BLOOM has 176 billion parameters and can generate text in 46 languages natural languages and 13 programming languages."

question_answerer = pipeline("question-answering", model="my_awesome_qa_model")

question_answerer(question=question, context=context)

결과가 다음과 같다면 성공한 것이다.

NER(Named Entity Recognition) BERT 모델 파인튜닝

각 문장의 토큰 엔티티 의미를 인식하는 모델을 NER이라 한다. 문장 토큰의 의미를 인식할 수 있다면, 문장에서 특정 토큰에 대한 의미를 알고, 해당 의미에 대한 에이전트를 자동 실행하는 등의 서비스를 쉽게 개발할 수 있다. 

코드 개발 전에 다음을 설치한다. 

pip install transformers[torch] datasets

이 예제는 NER 데이터셋을 다운로드하고, BERT-BASE-NER(참고) 사전학습모델을 이용해 파인튜닝한다. BERT-BASE-NER 모델 사용방법은 다음과 같다. 

from transformers import AutoTokenizer, AutoModelForTokenClassification

from transformers import pipeline

tokenizer = AutoTokenizer.from_pretrained("dslim/bert-base-NER")

model = AutoModelForTokenClassification.from_pretrained("dslim/bert-base-NER")

nlp = pipeline("ner", model=model, tokenizer=tokenizer)

example = "My name is Wolfgang and I live in Berlin"

ner_results = nlp(example)

print(ner_results)

파인튜닝 데이터셋은 희귀한 토큰 의미를 정의한 데이터셋이다. 

wnut_17 · Datasets at Hugging Face (설명)

NER 의미는 다음과 같다. 

Person

Location (including GPE, facility)

Corporation

Consumer good (tangible goods, or well-defined services)

Creative work (song, movie, book, and so on)

Group (subsuming music band, sports team, and non-corporate organisations)

이는 코드 상해 좀 더 상세화되어 표현되었다.

0: O

1: B-corporation

2: I-corporation

3: B-creative-work

4: I-creative-work

5: B-group

6: I-group

7: B-location

8: I-location

9: B-person

10: I-person

11: B-product

12: I-product

각 B, I, O는 Begin location, Inside location, Outside를 의미한다(NER 연구에 자주 나오는 용어). 참고로, New York City is a bustling metropolis의 NER 해석은 다음과 같다. 

New: O (Outside of any named entity)

York: B-LOC (Beginning of a Location entity)

City: I-LOC (Inside of a Location entity)

is: O

a: O

bustling: O

metropolis: O 

사용된 데이터셋은 다음과 같이 문장 토큰에 대한 NER이 정의되어 있다. 

이제, 다음 파인튜닝 코드를 입력해 실행, 학습한다. 

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("dslim/bert-base-NER")

def tokenize_and_align_tags(records):

    # 입력 단어를 토큰으로 분리함. 예를 들어, ChatGPT경우, ['Chat', '##G', '##PT']로 분해

    tokenized_results = tokenizer(records["tokens"], truncation=True, is_split_into_words=True)

    input_tags_list = []

    for i, given_tags in enumerate(records["ner_tags"]):

        word_ids = tokenized_results.word_ids(batch_index=i)

        previous_word_id = None

        input_tags = []

        for wid in word_ids:

            if wid is None:

                input_tags.append(-100)

            elif wid != previous_word_id:

                input_tags.append(given_tags[wid])

            else:

                input_tags.append(-100)

            previous_word_id = wid

        input_tags_list.append(input_tags)

    tokenized_results["labels"] = input_tags_list

    return tokenized_results

from datasets import load_dataset

wnut = load_dataset('wnut_17')

tokenized_wnut = wnut.map(tokenize_and_align_tags, batched=True)

tag_names = wnut["test"].features[f"ner_tags"].feature.names

id2label = dict(enumerate(tag_names))

label2id = dict(zip(id2label.values(), id2label.keys()))

from transformers import AutoModelForTokenClassification

model = AutoModelForTokenClassification.from_pretrained(

    "dslim/bert-base-NER", num_labels=len(id2label), id2label=id2label, label2id=label2id, ignore_mismatched_sizes=True

)

from transformers import Trainer, TrainingArguments, DataCollatorForTokenClassification

training_args = TrainingArguments(

    output_dir="my_finetuned_wnut_model",

)

''' # 하이퍼파라메터 튜닝용

training_args = TrainingArguments(

    output_dir="my_finetuned_wnut_model_1012",

    learning_rate=2e-5,

    per_device_train_batch_size=16,

    per_device_eval_batch_size=16,

    num_train_epochs=2,

    weight_decay=0.01,

    evaluation_strategy="epoch",

    save_strategy="epoch",

    load_best_model_at_end=True,

    push_to_hub=True,

)'''

data_collator = DataCollatorForTokenClassification(tokenizer=tokenizer)     

trainer = Trainer(

    model=model,

    args=training_args,

    train_dataset=tokenized_wnut["train"],

    eval_dataset=tokenized_wnut["test"],

    tokenizer=tokenizer,

    data_collator=data_collator,

)

trainer.train()

from transformers import pipeline

model = AutoModelForTokenClassification.from_pretrained("my_finetuned_wnut_model/checkpoint-1000")

tokenizer = AutoTokenizer.from_pretrained("my_finetuned_wnut_model/checkpoint-1000")

classifier = pipeline("ner", model=model, tokenizer=tokenizer)

out = classifier("My name is Sylvain and I work at Hugging Face in Brooklyn.")

print(out)

import evaluate

seqeval = evaluate.load("seqeval")

results = trainer.evaluate()

print(results)

trainer.push_to_hub()

실행 결과는 다음과 같다. 

다음과 같이 문장 각 토큰의 의미(예. 사람, 위치 등)를 높은 정확도로 제공해 준다. 

마무리

이 글은 허깅페이스 트랜스포머를 이용해 다양한 사전학습 모델을 이용해 여러가지 서비스 개발 방법을 살펴보았다. 자체 데이터로 학습하거나, 데이터 학습을 좀 더 많이 할 수록 결과가 더 정확하고, 전문적이며, 풍부해 질 것이다.

레퍼런스

• Question answering (huggingface.co)
• Agents & Tools (huggingface.co)
• Fine-tune a pretrained model (huggingface.co)
• Fine-Tuning BERT using Hugging Face Transformers (learnopencv.com)
• How to Fine-Tune BERT for NER Using HuggingFace (freecodecamp.org)
• Fine-Tuning the Pre-Trained bert-base-NER in Hugging Face for Named Entity Recognition (NER) | by Yuan An, PhD | Medium
• medium/src/working_huggingface/Working_with_HuggingFace_ch2_Preparing_Dataset_for_Fine_Tuning_NER_Model.ipynb at main · anyuanay/medium (github.com)
• pankajmathur/orca_mini_v2_7b · Hugging Face
• RunPod GPU Cloud

참고: 그래프, 그래픽 데이터셋

CADTransformer (CADTransformer_Panoptic_Symbol_Spotting_Transformer_for_CAD_Drawings)

Shape Transformer Architecture (Robust 3D Reconstruction from Three Orthographic Views with Learnt Shape Programs)

CADSketchNet (An Annotated Sketch dataset for 3D CAD Model Retrieval with Deep Neural Networks)