AB
AB
AiBoss站

全部分类

教程

Gemma

教程

用 Gemma 3 搭建本地多模态对话应用：AI Studio、Transformers 与 Chainlit 三条路径

Gemma 3 是 Google 开放权重模型家族，提供 1B、4B、12B、27B 四种规模，支持图像与文本输入、128K 上下文与 140 多种语言。本文按三条路径讲清如何上手：在 Google AI Studio 里直接试跑、用 Hugging Face Transformers 在本地加载 4B 指令模型做图文问答、通过 Google 的 API 调用 27B 模型，最后用 Chainlit 把 API 调用包装成一个可本地运行的对话式网页应用。

Gemma 3 是 Google 开放权重的模型家族，定位是「能在单张 GPU 上跑起来」的通用模型：权重可以下载到本地自行托管，也可以走托管 API 调用。它支持文本与图像混合输入、128,000 token 的上下文窗口，并覆盖 140 多种语言，家族内提供 1B、4B、12B、27B 四种参数规模，规模越大能力越强，小尺寸版本则可以在内存有限的笔记本上运行。本文面向第一次接触 Gemma 3 的开发者，把三条上手路径讲完整：在 Google AI Studio 里零代码试跑、用 Hugging Face Transformers 在本地做图文问答、通过 Google 的 API 调用大尺寸模型，最后用 Chainlit 把 API 调用封装成一个本地运行的对话式网页应用。如果你只是想先确认自己的机器能不能跑得动，可以先参考 Gemma 相关的环境说明，再回到本文按步骤操作。

准备工作

三条路径的前置条件并不相同，先按自己要走的路线把环境备齐，可以少走弯路。

通用条件

  • 一个 Google 账号。使用 Google AI Studio 和申请 API key 都需要它。
  • 一个代码编辑器，例如 VS Code。
  • Python 环境。走本地模型和 API 两条路线都需要安装 Python。

本地运行路线的额外条件

  • 一个 Hugging Face 账号，用于在模型页面接受许可协议。
  • 足够的本地内存或显存。素材没有给出各尺寸模型的具体内存占用数字，实际需求请以模型页面与官方文档的当前说明为准；如果机器偏弱，优先选 1B 或 4B 这类小尺寸。
  • Python 虚拟环境工具（标准库自带的 venv 即可）。

API 与网页应用路线的额外条件

  • 在 Google AI Studio 中生成的一个 API key。
  • 能访问 Google 服务的网络环境。

需要提醒的是，模型版本、可用尺寸、API 配额与计费方式都属于会变动的信息，本文只描述操作流程，具体数值请以官网当前信息为准。

操作步骤

第一步：在 Google AI Studio 中零代码试跑

这是最快确认模型行为的方式，不需要安装任何东西。

  1. 在浏览器中打开 Google AI Studio，用 Google 账号登录。
  2. 点击「Create Prompt」新建一个提示。
  3. 在 Model Settings 里把模型切换为 Gemma 3，下拉列表中会出现不同尺寸的选项，例如 27B、4B 等，按需要选择。
  4. 在输入框里写下你的任务，可以是写作、写代码，也可以是普通的问答。
  5. 点击「Run」，等待模型返回结果。

这一步的价值在于快速建立对模型能力的直觉：同一个提示分别用 4B 和 27B 跑一遍，就能感受到尺寸差异带来的回答质量差别，再决定后面是本地部署还是走 API。

第二步：用 Hugging Face Transformers 在本地加载模型

这条路把权重下载到本机，推理完全在本地完成，不需要按次付费。整体流程是：注册账号、接受模型许可、建虚拟环境、装依赖、写脚本、运行。

1. 接受模型许可

  1. 打开 Hugging Face 并注册账号。
  2. 在顶部导航点击「Models」，在搜索框输入 Gemma，从结果中挑选 Google 发布的模型。
  3. 进入目标模型页面，例如 google/gemma-3-4b-it，接受许可协议。没有接受许可，后续下载会被拒绝。

2. 创建虚拟环境并安装依赖

在终端中依次执行：

python3 -m venv venv
source venv/bin/activate
pip install transformers datasets evaluate accelerate
pip install torch

Windows 下激活虚拟环境的命令与上面不同，用对应的激活脚本即可，其余命令一致。

3. 编写图文问答脚本

新建 main.py，写入下面的代码。它用 pipeline 加载 4B 指令微调模型，把一张图片和一句问题一起送进模型，让它识别图片中的内容。

from transformers import pipeline
import torch

pipe = pipeline(
    "image-text-to-text",
    model="google/gemma-3-4b-it",
    device="cpu",
    torch_dtype=torch.bfloat16,
)

messages = [
    {
        "role": "system",
        "content": [{"type": "text", "text": "You are a helpful assistant."}],
    },
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "<图片地址>"},
            {"type": "text", "text": "What animal is on the candy?"},
        ],
    },
]

output = pipe(text=messages, max_new_tokens=200)
print(output[0]["generated_text"][-1]["content"])

几个参数值得单独说明：

  • model 指定具体权重，-it 后缀表示指令微调版本，适合对话式使用。
  • device 设为 "cpu" 表示纯 CPU 推理；有可用 GPU 时可以改成对应的设备标识，速度会明显不同。
  • torch_dtype 设为 torch.bfloat16，用较低精度加载以节省内存。
  • max_new_tokens 控制生成的最大 token 数，示例里是 200，回答较长时可以调大。

4. 运行脚本

python3 main.py

脚本会先下载权重（首次运行耗时较长），然后输出模型对图片的回答。把 messages 里的图片地址换成你自己的图片，问题换成你想问的内容，就能复用到其他图文任务上。

第三步：通过 Google 的 API 调用 Gemma 3

如果不想在本机加载权重，可以走托管 API。这条路适合机器配置一般、但需要较大尺寸模型能力的场景。

1. 获取 API key

  1. 打开 Google AI Studio，用 Google 账号登录。
  2. 点击「Get API key」。
  3. 在页面上生成一个 API key，并妥善保存。

2. 安装 SDK

pip install google-generativeai
pip install google-genai

3. 编写调用脚本

新建 google-cloud-api-terminal.py：

import google.generativeai as genai

# 配置 API key
genai.configure(api_key="[REPLACE-THIS-TEXT-WITH-YOUR-API-KEY]")

# 初始化模型，模型名作为位置参数传入
model = genai.GenerativeModel("gemma-3-27b-it")

# 生成内容
response = model.generate_content("What is the latest version of iphone?")

# 打印生成的文本
print(response.text)

把占位字符串替换成你自己的 key 再运行。这个例子用的是 27B 指令微调模型加一句纯文本提示，返回结果通过 response.text 取出。

注意不要把 API key 硬编码后提交到公开仓库。实际项目里应通过环境变量或配置文件注入，脚本中只读取变量。

第四步：用 Chainlit 做一个本地对话网页

前面三步都是在终端里看输出。这一步把 API 调用包装成带聊天界面的网页应用，在浏览器里就能对话。

1. 安装依赖

pip install google-generativeai
pip install google-genai
pip install chainlit

Chainlit 是一个开源的 Python 包，用来构建对话式 AI 应用，自带前端界面，不需要另外写 HTML 或 JavaScript。

2. 编写应用脚本

新建 google-cloud-web-interface.py：

import chainlit as cl
import google.generativeai as genai

# 配置 Generative AI 客户端
genai.configure(api_key="[REPLACE-THIS-TEXT-WITH-YOUR-API-KEY]")

# 初始化模型
model = genai.GenerativeModel("gemma-3-27b-it")

@cl.on_message
async def handle_message(message: cl.Message):
    # 根据用户输入生成内容
    response = model.generate_content(contents=[message.content])
    reply = response.text
    # 把生成的回复发回给用户
    await cl.Message(content=reply).send()

这段代码的结构很简单：@cl.on_message 装饰器注册一个消息处理函数，用户每发一条消息就触发一次；函数内部调用模型生成回复，再用 cl.Message 把结果推回界面。

3. 启动应用

chainlit run google-cloud-web-interface.py

启动后终端会打印本地访问地址，在浏览器中打开即可看到聊天界面。如果一切正常，输入问题就能收到 Gemma 3 的回答。

这个示例走的是 Google API。如果希望完全本地化，可以把模型初始化部分换成第二步里的 Transformers 加载方式，其余的消息处理逻辑保持不变。

一个完整示例

下面把 API 路线从零到跑通串一遍，假设你从一台干净的机器开始。

环境准备

python3 -m venv venv
source venv/bin/activate
pip install google-generativeai google-genai chainlit

获取 key

登录 Google AI Studio，点击「Get API key」生成密钥，复制备用。

写入应用文件

新建 app.py，内容如下（把 key 换成你自己的）：

import chainlit as cl
import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY_HERE")
model = genai.GenerativeModel("gemma-3-27b-it")

@cl.on_chat_start
async def start():
    await cl.Message(content="Gemma 3 已就绪，可以开始提问。").send()

@cl.on_message
async def handle_message(message: cl.Message):
    response = model.generate_content(contents=[message.content])
    await cl.Message(content=response.text).send()

相比前面的版本，这里多了一个 @cl.on_chat_start 钩子，在会话开始时先发一条欢迎消息，方便确认应用已经连上模型。

启动并验证

chainlit run app.py

打开终端给出的地址，先看到欢迎消息，然后输入任意问题，例如让它解释一段代码或翻译一句话，确认能收到回复。至此一个最小可用的本地对话应用就跑通了。

换成纯本地推理

如果不想依赖 API，把模型部分替换为 Transformers 的加载方式：

from transformers import pipeline
import torch

pipe = pipeline(
    "image-text-to-text",
    model="google/gemma-3-4b-it",
    device="cpu",
    torch_dtype=torch.bfloat16,
)

然后在消息处理函数里把用户输入组装成 messages 结构传给 pipe，从返回结果里取出最后一条 content 即可。这样整个链路都在本机完成，不需要网络请求，但首次运行要下载权重，且推理速度取决于本机硬件。

注意事项

许可与商用

Gemma 3 的权重可以免费下载并自行托管，自行托管时不需要按提示付费。它允许商业使用，但附带负责任 AI 方面的使用准则，把模型集成进产品前应先阅读许可条款的当前版本。

硬件与尺寸选择

四种尺寸的能力与资源需求差异明显。27B 是家族中质量最高的版本，但仍设计为可在单张 GPU 上运行；1B 和 4B 面向内存更有限的设备。素材没有给出各尺寸的精确内存门槛，选型时请以模型页面与官方文档的当前说明为准，不要凭经验估算。

首次下载耗时

本地路线第一次运行会下载完整权重，耗时与网络状况直接相关。建议在稳定的网络环境下执行，并预留足够的磁盘空间。

API key 管理

示例代码里的 key 是占位符，实际使用时不要把它写进会公开的代码。API 的可用模型、调用配额与计费规则都可能调整，以官网当前信息为准。

设备参数的影响

device 设为 "cpu" 时不需要 GPU，但速度较慢；有 GPU 时改成对应设备标识可以提速。torch_dtype 用 bfloat16 是为了降低内存占用，如果硬件不支持该精度，需要改用其他精度设置。

上下文长度

128,000 token 的上下文窗口意味着可以一次读入很长的文档或对话历史，但长输入同样会占用更多内存与计算资源，实际使用时要结合硬件条件控制输入规模。

安全机制

Gemma 3 配套了 ShieldGemma 2 相关工具用于内容安全，拦截有害输出。如果应用面向终端用户，建议在业务层再加一层输入输出校验。

输出格式

模型可以按要求返回 JSON 等结构化格式，便于程序解析。但生成结果不保证永远严格符合格式，解析时应做好异常处理。

返回