เรียกใช้ Gemma กับ Hugging Face Transformers

ดูใน ai.google.dev เรียกใช้ใน Google Colab เรียกใช้ใน Kaggle เปิดใน Vertex AI ดูซอร์สโค้ดใน GitHub

การสร้างข้อความ การสรุป และการวิเคราะห์เนื้อหาเป็นเพียงตัวอย่างงานบางส่วนที่คุณทำได้ด้วยโมเดลแบบเปิดของ Gemma บทแนะนำนี้จะแสดงวิธีเริ่มต้นใช้งาน Gemma โดยใช้ Hugging Face Transformers ทั้งอินพุตข้อความและรูปภาพเพื่อสร้างเนื้อหาข้อความ ไลบรารี Transformers Python มี API สำหรับเข้าถึงโมเดล Generative AI ที่ผ่านการฝึกแล้ว ซึ่งรวมถึง Gemma ดูข้อมูลเพิ่มเติมได้ในเอกสารประกอบของ Transformers

ตั้งค่า

ก่อนเริ่มบทแนะนำนี้ ให้ทำตามขั้นตอนต่อไปนี้

  • เข้าถึง Gemma โดยเข้าสู่ระบบ Hugging Face แล้วเลือก ยอมรับใบอนุญาต สำหรับโมเดล Gemma
  • เลือกรันไทม์ Colab ที่มีทรัพยากรเพียงพอที่จะเรียกใช้โมเดล Gemma ขนาดที่คุณต้องการ ดูข้อมูลเพิ่มเติม
  • สร้างโทเค็นเพื่อการเข้าถึง Hugging Face แล้วเพิ่มลงในสภาพแวดล้อม Colab

กำหนดค่าโทเค็นเพื่อการเข้าถึง

เพิ่มโทเค็นเพื่อการเข้าถึงลงใน Colab เพื่อเปิดใช้การดาวน์โหลดโมเดล Gemma จากเว็บไซต์ Hugging Face ใช้ฟีเจอร์ Secrets ของ Colab เพื่อบันทึกโทเค็นอย่างปลอดภัยโดยไม่ต้องเพิ่มลงในโค้ดที่ใช้งาน

วิธีเพิ่มโทเค็นเพื่อการเข้าถึง Hugging Face เป็น Secret

  1. เปิดแท็บ Secrets โดยเลือกไอคอนกุญแจทางด้านซ้ายของอินเทอร์เฟซ หรือเลือกเครื่องมือ > จานสีคำสั่ง พิมพ์ secrets แล้วกด Enter
  2. เลือกเพิ่ม Secret ใหม่ เพื่อเพิ่มรายการ Secret ใหม่
  3. ในช่องชื่อ ให้ป้อน HF_TOKEN
  4. ในช่องค่า ให้ป้อนข้อความของโทเค็นเพื่อการเข้าถึง Hugging Face
  5. ในช่องการเข้าถึง Notebook ให้เลือกสวิตช์เพื่อเปิดใช้การเข้าถึง

เมื่อป้อนโทเค็นเพื่อการเข้าถึงเป็น HF_TOKEN และค่าแล้ว คุณจะเข้าถึงและตั้งค่าโทเค็นดังกล่าวได้ภายในสภาพแวดล้อม Colab Notebook โดยใช้โค้ดต่อไปนี้

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

ติดตั้งไลบรารี Hugging Face ที่จำเป็นสำหรับการเรียกใช้โมเดล Gemma และทำการส่งคำขอ

# 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 เพื่อสร้างอินสแตนซ์ของคลาส pipeline สำหรับการดำเนินการโมเดลด้วย Gemma เมื่อใช้โมเดลเพื่อสร้างเอาต์พุตหรือทำตามคำแนะนำ ให้เลือกโมเดลที่ปรับแต่งคำแนะนำ (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 คุณสามารถใช้ "cuda" สำหรับ Colab หรือ "msu" สำหรับอุปกรณ์ iOS หรือเพียงตั้งค่านี้เป็น 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 เพื่อใช้กับข้อมูลรูปภาพ คุณจะกำหนดค่าอินสแตนซ์ pipeline ของ Transformer ให้ใช้กับรูปภาพโดยเฉพาะ โดยเฉพาะอย่างยิ่ง คุณต้องเลือกการกำหนดค่าไปป์ไลน์ที่จัดการข้อมูลภาพได้โดยตั้งค่าพารามิเตอร์ 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
)

เรียกใช้การสร้างข้อความ

เมื่อกำหนดค่าโมเดล Gemma ให้จัดการอินพุตรูปภาพด้วยอินสแตนซ์ pipeline แล้ว คุณจะส่งพรอมต์พร้อมรูปภาพไปยังโมเดลได้ ใช้โทเค็น <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)

คุณสามารถใส่รูปภาพหลายรูปในพรอมต์ได้โดยเพิ่มรายการ "type": "image", เพิ่มเติมในรายการ content

สร้างข้อความจากข้อมูลเสียง

ด้วย Gemma 3n คุณสามารถใช้ข้อมูลเสียงเป็นส่วนหนึ่งของพรอมต์ได้ ส่วนนี้จะแสดงวิธีใช้ไลบรารี Transformers เพื่อโหลดและกำหนดค่าโมเดล Gemma ให้ใช้ข้อมูลเสียงและอินพุตข้อความเพื่อสร้างเอาต์พุตข้อความ

ติดตั้งแพ็กเกจ Python

คุณต้องใช้ไลบรารี Transformers เวอร์ชันล่าสุดเพื่อใช้อินพุตเสียงกับ Gemma ติดตั้งไลบรารี Hugging Face สำหรับการเรียกใช้โมเดล Gemma และทำการส่งคำขอด้วยข้อมูลเสียง ดังที่แสดงด้านล่าง

# 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 ให้ใช้กับข้อมูลเสียงโดยเฉพาะ โดยเฉพาะอย่างยิ่ง คุณต้องกำหนดออบเจ็กต์ processor และ model โดยใช้คลาส AutoProcessor และ AutoModelForImageTextToText ดังที่แสดงในตัวอย่างโค้ดต่อไปนี้

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"},
        ]
    }
]

คุณสามารถใส่ไฟล์เสียงหลายไฟล์ในพรอมต์ได้โดยเพิ่มรายการ "type": "audio", เพิ่มเติมในรายการ content หากคุณป้อนพรอมต์ด้วยข้อมูลเสียง แต่ไม่มีเทมเพลต ให้ใช้ไวยากรณ์ <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