 在 ai.google.dev 上查看
|
 在 Google Colab 中运行
|
 在 Kaggle 中运行
|
 在 Vertex AI 中打开
|
 在 GitHub 上查看源代码
|
生成文本、总结和分析内容只是您可以使用 Gemma 开放模型完成的一些任务。本教程介绍了如何开始使用 Hugging Face Transformer 运行 Gemma，同时使用文本和图片输入生成文本内容。Transformers Python 库提供了一个 API，用于访问预训练的生成式 AI 模型（包括 Gemma）。如需了解详情，请参阅转换器文档。
设置
在开始本教程之前，请完成以下步骤：
- 如需获取对 Gemma 的访问权限，请登录 Hugging Face，然后为 Gemma 模型选择确认许可。
- 选择一个具有足够资源的 Colab 运行时，以运行您要运行的 Gemma 模型大小。了解详情。
- 生成 Hugging Face 访问令牌，并将其添加到您的 Colab 环境中。
配置访问令牌
将您的访问令牌添加到 Colab，以便从 Hugging Face 网站下载 Gemma 模型。使用 Colab 的 Secret 功能可安全地保存令牌，而无需将其添加到工作代码中。
如需将 Hugging Face 访问令牌添加为 Secret，请执行以下操作：
- 选择界面左侧的密钥图标，打开“Secrets”标签页；或者选择 Tools > Command Palette，输入
secrets，然后按 Enter。 - 选择添加新 Secret 以添加新的 Secret 条目。
- 在名称字段中，输入
HF_TOKEN。 - 在值字段中，输入您的 Hugging Face Access Token 的文本。
- 在对笔记本的访问权限字段中，选中相应开关以启用访问权限。
将访问令牌输入为 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 类的实例。使用模型生成输出或遵循指示时，请选择指令调优 (IT) 模型，该模型的模型 ID 字符串中通常包含 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（零）以指定系统上的第一个 GPU。如需详细了解如何使用 Pipeline 类，请参阅 Hugging Face 的 Pipelines 文档。
运行文本生成
在 pipeline 对象中加载并配置 Gemma 模型后，您可以向模型发送提示。以下示例代码展示了使用 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
)
运行文本生成
将 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)
您可以在 content 列表中添加其他 "type": "image", 条目，以便在问题中添加多张图片。
根据音频数据生成文本
借助 Gemma 3n，您可以将音频数据用作问题的一部分。本部分介绍了如何使用 Transformers 库加载和配置 Gemma 模型，以使用音频数据和文本输入生成文本输出。
安装 Python 软件包
若要将音频输入与 Gemma 搭配使用，您需要安装较新版本的 Transformers 库。安装 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 实例，以便与音频数据搭配使用。具体而言，您必须使用 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> 语法。
运行文本生成
使用 processor 和 model 对象配置 Gemma 模型后，并使用问题模板创建包含音频数据的问题，您就可以发送问题来生成输出了。以下示例代码展示了使用聊天模板的请求、输出生成和响应解码：
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 模型构建和探索更多内容：