本教程主示例为Gemma 4 E2B it，并附官方QAT GGUF入口。Gemma 4使用多模态加载类，不能把旧版Gemma 3的代码直接替换模型名后照用。

阅读顺序：先完成第1节选型与空间检查，再安装下载工具，下载并校验。只有确认满足运行条件后，才进入运行章节。

1 先选对模型

it表示经过指令调优。E2B是产品规格名称，包含嵌入参数的总量更大，不能简单按2B计算内存。Gemma 3和Gemma 4的访问状态、许可证与多模态能力应逐仓库确认。

容量按官方API的文件字节数相加，包含文档、配置及仓库内可能并存的其他权重格式；不是运行内存最低要求。GB按十进制，GiB按二进制换算。

下载目录建议至少预留19 GB可用空间。这是整仓大小加约30%和5 GB余量的建议，不含额外转换副本、框架环境、系统空间及其他缓存。

打开官方模型主页

打开固定版本文件列表

检查自己的电脑

Windows：按Win加I打开设置，进入系统中的系统信息查看内存；在任务管理器的性能页查看GPU及专用显存。macOS：打开苹果菜单中的关于本机，查看芯片与内存。内存和硬盘空间是两回事。

下载只依赖网络与磁盘；运行还需要内存、显存、对应架构和框架。FP16或BF16权重可用总参数量乘2字节估算基础权重占用，float32约乘4字节，实际还要加运行开销和上下文缓存。MoE不能仅按激活参数估算。

磁盘必须支持大文件。Windows通常用NTFS，Mac通常用APFS，跨系统外置盘可用exFAT。不要为了下载随意格式化已有资料的硬盘。FAT32无法保存超过4 GB的单个文件。

2 安装下载工具与准备账号

Windows 按顺序操作

1. 打开Python官方下载页，安装Python 3.12。若安装器显示Add python.exe to PATH，请勾选；安装结束后重新打开PowerShell。可在开始菜单搜索PowerShell。

Python Windows官方下载页

2. 每次复制一行命令，按回车，等待完成后再执行下一行。使用独立环境可减少与电脑上其他Python软件冲突。

py --version
py -3.12 -m venv "$env:USERPROFILEhf-gemma-env"
& "$env:USERPROFILEhf-gemma-envScriptsActivate.ps1"
python -m pip install --upgrade pip huggingface_hub
hf --help

应看到Python版本、安装成功信息和hf帮助列表。若py -3.12找不到版本，确认安装了Python 3.12；若系统只有python可用，可将创建环境命令中的py -3.12替换为python。

如果PowerShell阻止激活脚本，可在本窗口执行下面一行后再激活；只影响当前窗口。关闭窗口后恢复原状态。

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

macOS 与 Linux 按顺序操作

macOS按Command加空格搜索终端；Linux打开终端。先安装Python 3.12并确认python3存在。Linux若缺少venv模块，按发行版官方说明安装python3-venv。

Python macOS官方下载页

python3 --version
python3 -m venv "$HOME/hf-gemma-env"
source "$HOME/hf-gemma-env/bin/activate"
python -m pip install --upgrade pip huggingface_hub
hf --help

以后新开窗口时，Windows重新执行Activate.ps1那一行；macOS和Linux重新执行source那一行。不必每次重建环境。

需要审批时如何处理

1. 在Hugging Face注册并验证邮箱。2. 登录后打开目标模型主页。3. 如果页面要求接受许可证、填写用途或申请访问，按页面要求完成。4. 等页面确认获准，再创建具备该仓库读取权限的令牌。5. 回到终端执行下面命令，按提示粘贴令牌。粘贴时没有字符显示可能是正常的。

hf auth login
hf auth whoami

创建或管理读取令牌

访问审批官方说明

公开仓库通常可先直接下载。令牌只填在工具提示中，不写进文档、截图或聊天消息。申请等待时间由发布方决定，登录成功不等于已获得仓库权限。

3 固定版本完整下载

本节下载主示例的全部文件。仓库ID由发布者名称、斜杠和模型名组成；revision是这次核对的固定提交。请不要自行把名称换成相似的社区仓库。

Windows 保存到D盘示例

先在此电脑中确认D盘存在且空间足够。没有D盘时，把下面的D:Models改为你实际的大容量磁盘路径。保留英文双引号，防止路径含空格时出错。

$repo = "google/gemma-4-E2B-it"
$rev = "3e22461f65e89153144f8adb70e3b8c2cc9845a7"
$dest = "D:Modelsgemma-4-E2B-it"
New-Item -ItemType Directory -Force $dest
hf download $repo --revision $rev --local-dir $dest --dry-run

上面的dry-run只查看待下载文件和预计下载量，不下载模型权重。若CLI不认识dry-run，先升级huggingface_hub。确认预计大小、目标磁盘和权限无误，再执行正式下载：

hf download $repo --revision $rev --local-dir $dest

macOS 与 Linux 保存到主目录示例

先确认主目录所在磁盘足够大。外置盘用户需替换dest为真实挂载路径；Mac常见路径以/Volumes/开头，Linux以实际挂载位置为准。

repo="google/gemma-4-E2B-it"
rev="3e22461f65e89153144f8adb70e3b8c2cc9845a7"
dest="$HOME/Models/gemma-4-E2B-it"
mkdir -p "$dest"
hf download "$repo" --revision "$rev" --local-dir "$dest" --dry-run
hf download "$repo" --revision "$rev" --local-dir "$dest"

变量只在当前窗口有效。换窗口后先激活环境，再重新执行repo、rev和dest三行赋值。Word自动换行不代表命令结束，请按完整段落复制。

下载过程怎样判断

正常会出现文件进度与传输信息，完成后回到命令提示符。第一次连接和大分片可能等待较久。电脑保持供电，关闭自动睡眠，外置盘不要中途拔出。按Ctrl加C可停止，恢复时按第4节重试。

按固定有效速度粗算：10 MB每秒约0.29小时，50 MB每秒约0.06小时；实际还受网络、磁盘和服务器影响。网络套餐的Mbps与下载界面的MB每秒单位不同，需除以8再估算。

4 校验完整性与恢复下载

整仓下载应保留原始目录结构。所有safetensors分片、索引、配置和分词器文件都属于配套内容；不要把多个分片手工合成一个文件，也不要只留最大的一个分片。

本示例整仓共9项，其中名称以.safetensors结尾的文件1个。是否包含重复格式、视觉模块或额外目录，以附录实际文件名为准。

Windows 校验

hf cache verify $repo --revision $rev --local-dir $dest --fail-on-missing-files

macOS 与 Linux 校验

hf cache verify "$repo" --revision "$rev" --local-dir "$dest" --fail-on-missing-files

以校验摘要显示All checksums match且没有缺失文件为整仓完成标准。校验需要联网获取元数据，还会读取本地大文件；运行时间可能较长。只数文件个数不能代替校验。

中断以后怎么继续

重新打开终端并激活环境，恢复相同repo、rev和dest，重新执行第3节正式下载命令。工具会利用已经完成的文件和可用缓存继续。未完成片段能否直接续传取决于传输后端与缓存状态。保留目标目录内的.cache/huggingface及临时文件。

若校验明确指出一个文件损坏，可只重下那个文件。下面仅是按本仓库真实文件名写出的示例；先把文件名换成报错对应的项，再执行，避免重下正常大文件。

hf download google/gemma-4-E2B-it "model.safetensors" --revision 3e22461f65e89153144f8adb70e3b8c2cc9845a7 --local-dir "实际模型目录" --force-download

替换实际模型目录为第3节的dest路径。重下后再做整仓校验。不要为一个文件报错就删除整个下载目录。

用网页逐个下载

打开固定文件列表，在Files and versions中找到文件并点下载图标；也可用附录直链。浏览器若显示文本而不保存，使用另存为并保留原文件名。按子目录原样创建文件夹，例如original/下的文件不能放到根目录覆盖同名配置。大量分片优先用CLI。

直链形如/resolve/固定提交/文件路径。浏览器最终跳转到的存储地址可能带临时签名，会过期；分享资料时保留本教程提供的入口。受访问审批保护的文件，打开直链仍需权限。

5 下载后开始运行

本节仅运行第1节指定的主示例，并先测试纯文本。教程附带run_model.py，读取已下载的本地目录，不会自动改用另一个在线模型。它是一轮一轮独立问答，不会记住上轮内容。

原始Gemma 4 E2B示例建议16 GB及以上可用显存；CPU float32建议32 GB以上内存。这些是短文本试跑的建议条件，不是官方承诺的最低配置。先关闭占内存的软件；长上下文和多用户会显著增加占用。

安装推理所需软件

在第2节已激活的环境里运行。CPU用户安装官方PyTorch CPU版本即可；Windows或Linux的NVIDIA显卡用户，如希望用CUDA，请到PyTorch安装页选择与你的系统及驱动匹配的命令。Mac使用对应的macOS安装选项。

PyTorch官方安装选择器

python -m pip install --upgrade torch transformers accelerate sentencepiece

Gemma 4使用AutoProcessor和AutoModelForMultimodalLM。若提示无法导入加载类，先确认环境中的Transformers为当前支持Gemma 4的版本，再对照固定版本模型卡；不要替换成旧版Gemma加载类。附带脚本只测试文本，不演示图像、视频或音频输入。

打开脚本所在文件夹

把整份教程压缩包解压。在当前系列文件夹找到run_model.py。Windows在资源管理器地址栏输入powershell并回车；Mac打开终端，输入cd和一个空格，再把该系列文件夹拖进终端，按回车。重新激活第2节环境。

第一次运行先选择一种设备

CPU方式兼容面较广，但会把权重按float32装入内存，速度可能较慢。使用前检查本节内存建议。Windows示例：

python run_model.py --model-dir "D:Modelsgemma-4-E2B-it" --device cpu

macOS和Linux示例：

python run_model.py --model-dir "$HOME/Models/gemma-4-E2B-it" --device cpu

具备匹配CUDA版PyTorch和足够显存的NVIDIA设备，可将命令最后的cpu改为cuda。Apple Silicon可尝试mps；若当前算子或精度不受支持，回到cpu。脚本不做自动分卡或磁盘卸载，全部权重需能装入所选设备。

第一次问答与完成标准

看到Model ready后，在You提示后输入：请用一句话解释什么是人工智能模型。按回车，等待AI输出。输入exit并回车退出；Ctrl加C也可终止。第一次加载和CPU生成较慢，请先用短问题。

运行成功标准：加载无错误、能收到与问题相关的回复、可以正常退出。文件校验通过仅代表下载完整，不能替代这个运行检查。

脚本关键逻辑

脚本从本地读取分词器或处理器与模型，套用该模型聊天模板，再生成新内容。完整脚本在同目录，下面为主示例对应的加载类：

from transformers import AutoProcessor, AutoModelForMultimodalLM

6 其他版本与图形界面路线

本次重点核对的仓库

打开 google/gemma-3-1b-it

打开 google/gemma-4-E2B-it

打开 google/gemma-4-E2B-it-qat-q4_0-gguf

每个重点仓库的所有文件路径、原始字节大小和API提供的LFS SHA256，均在精讲仓库文件大小与校验.csv和精讲仓库全部文件地址.txt中。不同仓库固定提交不同，不混用配置、分片与分词器。

使用官方GGUF和LM Studio

GGUF适用于支持该架构的桌面运行工具。官方GGUF仓库如下；只下载需要的量化文件及模型卡要求的配套文件，不必一次下载同仓库所有量化档位。

官方GGUF仓库

本次看到的GGUF文件：gemma-4-E2B-it-mmproj.gguf；gemma-4-E2B_q4_0-it.gguf

LM Studio官方下载

官方图形界面下载说明

1. 安装适合你系统的LM Studio，按应用提示安装或更新运行时。2. 在My Models中设置模型保存目录。3. 打开Discover，将上面的完整仓库URL粘入搜索栏。4. 检查发布者与量化文件名，选定文件下载。5. 下载结束后进入聊天页，从模型选择器加载模型。6. 先把上下文设为4096左右，发一个短问题。

若运行时不识别新架构，先更新运行时并核对应用支持列表；显示可下载不等于已支持运行。已手工下载的GGUF可用LM Studio官方导入功能导入，或按其说明使用lms import。

Gemma 4的多模态GGUF可能另含mmproj文件。文本测试与图像、音频输入所需文件不同；不要误删配套投影文件。以该GGUF模型卡及桌面运行时支持说明为准。

7 常见问题逐项排查

hf 找不到

确认当前窗口已激活hf-gemma-env，再运行python -m pip show huggingface_hub。若安装到了另一套Python，重新激活正确环境后安装。

401 或 403

检查是否登录正确账号、令牌是否有该仓库读取权限、网页是否已接受许可证并获准访问。公开元数据可见不代表受限权重可下载。

404 或 Revision not found

先核对完整仓库ID和固定提交，确认没有空格或多余标点。仓库可能重命名或被删除，回官方主页查询，不要凭相似名字猜地址。

下载超时或速度低

先用浏览器打开官方主页，再检查大文件下载是否也可连接。网络不稳定时保持同一路径和版本重试。出现Xet相关报错时查看官方环境变量说明，不关闭证书校验。

磁盘满了

按Ctrl加C停止，换到更大磁盘。复制完整模型目录及隐藏缓存后，更新dest路径并重新执行同版本命令。保留原目录直到新目录校验通过。

文件只有几KB

可能保存成网页、错误响应或Git LFS指针。与精讲仓库文件大小与校验.csv对比；使用hf download重新取得实际文件。

CUDA unavailable

当前PyTorch可能是CPU版，或驱动、显卡环境不可用。用PyTorch官方安装页的匹配命令；没有受支持的显卡时选择cpu。

CUDA out of memory 或系统内存不足

先退出其他程序，减小输入与输出长度。模型权重本身装不下时，换更小模型或经核对的量化版；仅缩短上下文不能消除权重占用。

KeyError 或模型架构不认识

检查依赖是否符合该仓库模型卡，区分旧自定义代码版与原生支持版。新模型可能需特定提交、专用镜像或尚未发布的运行时。

输出重复或没有最终回答

确认使用模型自己的聊天模板。推理模型可能先生成长推理；增加输出token上限，按模型卡调采样参数。小模型能力有限，先用短问题验证流程。

8 全部地址文件怎么使用

本系列按明确的官方发布账号与命名条件收录412个公开可枚举仓库。它是2026年10月29日的快照，不包含私有仓库、已删除仓库或全站社区微调、转换版本。清单收录不代表每项都适合聊天。

检索账号 google；命名条件 仓库名不区分大小写包含 gemma。同名官方旧账号的历史地址可能发生跳转，以表中当前API返回的仓库ID为准。

CSV可用Excel、Numbers或文本编辑器打开，用筛选查仓库ID和任务。TXT可用记事本打开，搜索精确模型名。全部文件直链依据官方API siblings字段枚举；非精讲仓库未逐一获取文件大小，不能据此估算全部仓库总容量。

下载命令.txt中的每一组是不同模型，只执行你选择的一组。没有要求一次下载整个系列。固定版本用于重现本清单，main会持续变化；以后想下载新版，先重新查看文件和容量。

附录 主示例全部文件直链

google/gemma-4-E2B-it 固定提交 3e22461f65e89153144f8adb70e3b8c2cc9845a7。共9项。字节大小来自仓库API；单击下载入口获取文件，Word中也可按Ctrl并点击。完整URL已保存在同目录TXT与CSV。

来源与核对说明

仓库列表来自官方Models API，已按分页链接读取到底；文件列表来自其siblings字段。重点仓库另查询blobs=true取得字节和LFS校验元数据。元数据核对不等于实际下载权重或完成运行测试。本教程的运行脚本依据模型卡加载方式编写，未在本机实测这些模型。

官方发布账号  |  本系列仓库API  |  主示例精确文件元数据  |  主示例固定模型卡  |  Hub CLI官方说明  |  Hub网络与环境变量  |