Hugging Face Transformers로 Gemma 실행

ai.google.dev에서 보기 Google Colab에서 실행 Kaggle에서 실행 Vertex AI에서 열기 GitHub에서 소스 보기

텍스트 생성, 콘텐츠 요약, 분석은 Gemma 개방형 모델로 수행할 수 있는 몇 가지 작업 중 하나입니다. 이 튜토리얼에서는 텍스트 및 이미지 입력을 모두 사용하여 텍스트 콘텐츠를 생성하는 Hugging Face Transformers를 사용하여 Gemma를 실행하는 방법을 보여줍니다. Transformers Python 라이브러리는 Gemma를 비롯한 사전 학습된 생성형 AI 모델에 액세스하기 위한 API를 제공합니다. 자세한 내용은 Transformers 문서를 참고하세요.

설정

이 튜토리얼을 시작하기 전에 다음 단계를 완료하세요.

  • Hugging Face에 로그인하고 Gemma 모델의 라이선스 확인을 선택하여 Gemma에 액세스합니다.
  • 실행하려는 Gemma 모델 크기를 실행하는 데 충분한 리소스가 있는 Colab 런타임을 선택합니다. 자세히 알아보기
  • Hugging Face 액세스 토큰을 생성하고 Colab 환경에 추가합니다.

액세스 토큰 구성

Hugging Face 웹사이트에서 Gemma 모델을 다운로드할 수 있도록 Colab에 액세스 토큰을 추가합니다. Colab 보안 비밀 기능을 사용하여 작동하는 코드에 토큰을 추가하지 않고도 토큰을 안전하게 저장할 수 있습니다.

Hugging Face 액세스 토큰을 보안 비밀로 추가하려면 다음 단계를 따르세요.

  1. 인터페이스 왼쪽에 있는 키 아이콘을 선택하거나 도구 > 명령어 팔레트를 선택하고 secrets를 입력한 다음 Enter 키를 눌러 비밀번호 탭을 엽니다.
  2. 새 보안 비밀 추가를 선택하여 새 보안 비밀 항목을 추가합니다.
  3. 이름 필드에 HF_TOKEN를 입력합니다.
  4. 값 필드에 Hugging Face 액세스 토큰의 텍스트를 입력합니다.
  5. Notebook 액세스 필드에서 스위치를 선택하여 액세스를 사용 설정합니다.

액세스 토큰을 HF_TOKEN 및 값으로 입력한 후 다음 코드를 사용하여 Colab 노트북 환경 내에서 액세스 토큰에 액세스하고 설정할 수 있습니다.

from google.colab import userdata
from huggingface_hub import login

# Login into Hugging Face Hub
hf_token = userdata.get('HF_TOKEN') # If you are running inside a Google Colab
login(hf_token)

Python 패키지 설치

Gemma 모델을 실행하고 요청하는 데 필요한 Hugging Face 라이브러리를 설치합니다.

# Install Pytorch & other libraries
%pip install "torch>=2.4.0"

# Install a transformers version that supports Gemma 3 (>= 4.51.3)
%pip install "transformers>=4.51.3"

텍스트에서 텍스트 생성

Gemma 모델에 텍스트를 프롬프트하여 텍스트 응답을 받는 것이 Gemma를 사용하는 가장 간단한 방법이며 거의 모든 Gemma 변형에서 작동합니다. 이 섹션에서는 Hugging Face Transformers 라이브러리를 사용하여 텍스트 대 텍스트 생성을 위한 Gemma 모델을 로드하고 구성하는 방법을 보여줍니다.

모델 로드

torch 및 transformers 라이브러리를 사용하여 Gemma로 모델 실행 pipeline 클래스의 인스턴스를 만듭니다. 출력을 생성하거나 안내를 따르는 데 모델을 사용하는 경우 일반적으로 모델 ID 문자열에 it가 있는 조정된 명령 (IT) 모델을 선택합니다. 다음 코드 예와 같이 pipeline 객체를 사용하여 사용하려는 Gemma 변형, 수행하려는 작업 유형(특히 텍스트 대 텍스트 생성의 경우 "text-generation")을 지정합니다.

import torch
from transformers import pipeline

pipeline = pipeline(
    task="text-generation",
    model="google/gemma-3-4b-it",
    device=0, # "cuda" for Colab, "msu" for iOS devices
    torch_dtype=torch.bfloat16
)

Gemma는 생성에 몇 가지 task 설정만 지원합니다. 사용 가능한 task 설정에 관한 자세한 내용은 Hugging Face Pipelines task() 문서를 참고하세요. torch 데이터 유형 torch.bfloat16를 사용하여 모델의 출력 품질에 큰 영향을 미치지 않으면서 모델의 정밀도와 필요한 컴퓨팅 리소스를 줄입니다. device 설정의 경우 Colab에는 "cuda"을, iOS 기기에는 "msu"을 사용하거나 0 (0)으로 설정하여 시스템의 첫 번째 GPU를 지정할 수 있습니다. Pipeline 클래스 사용에 관한 자세한 내용은 Hugging Face Pipelines 문서를 참고하세요.

텍스트 생성 실행

Gemma 모델을 로드하고 pipeline 객체에 구성한 후에는 모델에 프롬프트를 보낼 수 있습니다. 다음 예시 코드는 text_inputs 매개변수를 사용하는 기본 요청을 보여줍니다.

pipeline(text_inputs="roses are red")

[{'generated_text': 'roses are red, violets are blue, \ni love you more than you ever knew.\n\n**Explanation'}]

프롬프트 템플릿 사용

더 복잡한 프롬프트로 콘텐츠를 생성할 때는 프롬프트 템플릿을 사용하여 요청을 구성하세요. 프롬프트 템플릿을 사용하면 user 또는 model와 같은 특정 역할의 입력을 지정할 수 있으며, Gemma 모델과의 여러 번의 채팅 상호작용을 관리하는 데 필요한 형식입니다. 다음 코드 예는 Gemma의 프롬프트 템플릿을 구성하는 방법을 보여줍니다.

messages = [
    [
        {
            "role": "system",
            "content": [{"type": "text", "text": "You are a helpful assistant."},]
        },
        {
            "role": "user",
            "content": [{"type": "text", "text": "Roses are red..."},]
        },
    ],
]

pipeline(messages, max_new_tokens=50)

이미지 데이터에서 텍스트 생성

Gemma 3부터 모델 크기가 4B 이상인 경우 프롬프트의 일부로 이미지 데이터를 사용할 수 있습니다. 이 섹션에서는 Transformers 라이브러리를 사용하여 Gemma 모델을 로드하고 구성하여 이미지 데이터와 텍스트 입력을 사용하여 텍스트 출력을 생성하는 방법을 보여줍니다.

모델 로드

이미지 데이터와 함께 사용할 Gemma 모델을 로드할 때는 특히 이미지와 함께 사용할 Transformer pipeline 인스턴스를 구성합니다. 특히 다음 코드 예와 같이 task 매개변수를 "image-text-to-text"로 설정하여 시각적 데이터를 처리할 수 있는 파이프라인 구성을 선택해야 합니다.

import torch
from transformers import pipeline

pipeline = pipeline(
    task="image-text-to-text", # required for image input
    model="google/gemma-3-4b-it",
    device=0,
    torch_dtype=torch.bfloat16
)

텍스트 생성 실행

pipeline 인스턴스로 이미지 입력을 처리하도록 Gemma 모델을 구성한 후에는 이미지가 포함된 프롬프트를 모델에 전송할 수 있습니다. <start_of_image> 토큰을 사용하여 프롬프트의 텍스트에 이미지를 추가합니다. 다음 예시 코드는 pipeline 매개변수를 사용하는 기본 요청을 보여줍니다.

pipeline(
    "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg",
    text="<start_of_image> What is shown in this image?"
)

[{'input_text': '<start_of_image> What is shown in this image?',
  'generated_text': '<start_of_image> What is shown in this image?\n\nThis image showcases a traditional Indian Thali. A Thali is a platter that contains a variety'}]

프롬프트 템플릿 사용

더 복잡한 프롬프트로 콘텐츠를 생성할 때는 프롬프트 템플릿을 사용하여 요청을 구성하세요. 프롬프트 템플릿을 사용하면 user 또는 model와 같은 특정 역할의 입력을 지정할 수 있으며, Gemma 모델과의 여러 번의 채팅 상호작용을 관리하는 데 필요한 형식입니다. 다음 코드 예는 Gemma의 프롬프트 템플릿을 구성하는 방법을 보여줍니다.

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg"},
            {"type": "text", "text": "What is shown in this image?"},
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "This image shows"},
        ],
    },
]

pipeline(text=messages, max_new_tokens=50, return_full_text=False)

content 목록에 "type": "image", 항목을 추가하여 프롬프트에 여러 이미지를 포함할 수 있습니다.

오디오 데이터에서 텍스트 생성

Gemma 3n을 사용하면 프롬프트의 일부로 오디오 데이터를 사용할 수 있습니다. 이 섹션에서는 Transformers 라이브러리를 사용하여 오디오 데이터와 텍스트 입력을 사용하여 텍스트 출력을 생성하도록 Gemma 모델을 로드하고 구성하는 방법을 보여줍니다.

Python 패키지 설치

Gemma에서 오디오 입력을 사용하려면 최신 버전의 Transformers 라이브러리가 필요합니다. 아래와 같이 Gemma 모델을 실행하고 오디오 데이터로 요청을 처리하기 위한 Hugging Face 라이브러리를 설치합니다.

# Install Pytorch & other libraries
%pip install "torch>=2.4.0"

# Install a transformers version that supports Gemma 3n (>= 4.53)
%pip install "transformers>=4.53.0"

모델 로드

오디오 데이터와 함께 사용할 Gemma 모델을 로드할 때는 오디오 데이터와 함께 사용할 Transformer 인스턴스를 구성합니다. 특히 다음 코드 예와 같이 AutoProcessor 및 AutoModelForImageTextToText 클래스를 사용하여 processor 및 model 객체를 정의해야 합니다.

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText

GEMMA_MODEL_ID = "google/gemma-3n-E4B-it"

processor = AutoProcessor.from_pretrained(GEMMA_MODEL_ID, device_map="auto")
model = AutoModelForImageTextToText.from_pretrained(
            GEMMA_MODEL_ID, torch_dtype="auto", device_map="auto")

프롬프트 템플릿 사용

오디오가 포함된 콘텐츠를 생성할 때는 프롬프트 템플릿을 사용하여 요청을 구성합니다. 프롬프트 템플릿을 사용하면 user 또는 model와 같은 특정 역할의 입력을 지정할 수 있으며, Gemma 모델과의 여러 번의 채팅 상호작용을 관리하는 데 필요한 형식입니다. 다음 코드 예는 오디오 데이터 입력으로 Gemma의 프롬프트 템플릿을 구성하는 방법을 보여줍니다.

messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "https://ai.google.dev/gemma/docs/audio/roses-are.wav"},
            {"type": "text", "text": "Transcribe this audio and complete the statement"},
        ]
    }
]

content 목록에 "type": "audio", 항목을 추가하여 프롬프트에 여러 이미지를 포함할 수 있습니다. 오디오 데이터를 사용해 프롬프트를 표시하지만 템플릿이 없는 경우 프롬프트 텍스트에 <audio_soft_token> 문법을 사용합니다.

텍스트 생성 실행

Gemma 모델을 processor 및 model 객체로 구성하고 프롬프트 템플릿을 사용하여 오디오 데이터가 포함된 프롬프트를 만든 후 프롬프트를 전송하여 출력을 생성할 수 있습니다. 다음 코드 예는 채팅 템플릿을 사용한 요청, 출력 생성, 응답 디코딩을 보여줍니다.

input_ids = processor.apply_chat_template(
        messages,
        add_generation_prompt=True,
        tokenize=True, return_dict=True,
        return_tensors="pt",
)
input_ids = input_ids.to(model.device, dtype=model.dtype)

# Generate output from the model
outputs = model.generate(**input_ids, max_new_tokens=128)

# decode and print the output as text
text = processor.batch_decode(
    outputs,
    skip_special_tokens=False,
    clean_up_tokenization_spaces=False
)
print(text[0])

다음 단계

Gemma 모델로 더 많은 것을 빌드하고 살펴보세요.