เรียกใช้ 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 ใช้ฟีเจอร์Secret ของ Colab เพื่อบันทึกโทเค็นอย่างปลอดภัยโดยไม่ต้องเพิ่มลงในโค้ดที่ใช้งาน

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

  1. เปิดแท็บลับโดยเลือกไอคอนกุญแจทางด้านซ้ายของอินเทอร์เฟซ หรือเลือกเครื่องมือ > แถบคำสั่ง พิ������� secrets แล้วกด Enter
  2. เลือกเพิ่มข้อมูลลับใหม่เพื่อเพิ่มรายการข้อมูลลับใหม่
  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การตั้งค่าที่ใช้ได้ในเอกสารประกอบเกี่ยวกับ task() ของ Hugging Face Pipelines ใช้ประเภทข้อมูล Torch torch.bfloat16 เพื่อลดความแม่นยำของโมเดลและทรัพยากรการคำนวณที่จำเป็น โดยไม่ส่งผลกระทบต่อคุณภาพเอาต์พุตของโมเดลอย่างมีนัยสำคัญ สำหรับการตั้งค่า device คุณสามารถใช้ "cuda" สำหรับ Colab หรือ "msu" สำหรับอุปกรณ์ iOS หรือเพียงตั้งค่านี้เป็น 0 (0) เพื่อระบุ GPU แรกในระบบ ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้คลาสไปป์ไลน์ได้ในเอกสารประกอบไปป์ไลน์ของ Hugging Face

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

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

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

เมื่อกำหนดค่าโมเดล 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