PaliGemma：从零手写 PyTorch 多模态大模型的完整指南

想象一下，你正在阅读一篇关于大模型的论文。算法原理看懂了，公式推导也没问题——但当你打开代码仓库，却发现核心实现被 PyTorch 的 nn.Module 层层封装，隐藏了所有细节。数百行代码里，backward() 一行就完成了所有反向传播，你仍然不知道权重到底是怎么更新的。PaliGemma 这个项目，正是为解决这个痛点而生的。

背景：从 Google I/O 到代码迷雾

2024年5月，Google 在 I/O 大会上发布了 PaliGemma——一个开源的多模态视觉语言模型（VLM）。它能够根据图片回答问题，例如"图中有什么"、"这段代码的作用是什么"。然而，官方实现发布在 Hugging Face 的 transformers 库里，数万行代码依赖于高度抽象的框架层，对于想深入理解 VLM 架构的学习者而言，门槛依然很高。

GitHub 用户 hkproj 创建了这个项目，并在 YouTube 上发布了配套教程。他的目标非常明确：用最少的依赖，从零实现 PaliGemma，让任何有 PyTorch 基础的人都能完全读懂模型内部的每一个矩阵运算。项目上线半年获得 615 颗 GitHub Stars，说明这个需求确实击中了大量学习者的痛点。

核心技术：从 CLIP 到 SigLIP，再到 Gemma

PaliGemma 本质上是一个"拼接"出来的模型：由视觉编码器 SigLIP 提取图像特征，由语言模型 Gemma 生成文本，两者之间靠一个投影层（Projection Layer）弥合模态鸿沟。

SigLIP Vision Encoder（视觉编码器）

SigLIP 是 Google Brain 在 2024 年提出的视觉模型，是 CLIP 的改进版。在 modeling_siglip.py 中，作者实现了完整的 SigLIP 架构，包括：

• Patch Embedding：将输入图片分割成 16×16 的小块，通过 nn.Conv2d 实现无填充的 patch 提取。每个 patch 被展平为一个嵌入向量。
• 位置编码：nn.Embedding 为每个 patch 位置分配一个可学习的位置向量，注入空间位置信息。
• Transformer Encoder：多层标准自注意力结构，每层包含多头注意力（Multi-Head Attention）和前馈网络（FFN）。
• SigLIP Loss：区别于 CLIP 的 InfoNCE loss，SigLIP 使用 Sigmoid Loss，支持大规模批次训练且不需要全局归一化。

Gemma Language Model（语言解码器）

Gemma 是 Google 的小型开源大语言模型，参数量从 2B 到 27B 不等。本项目实现了一个可配置的 Gemma 架构，支持自定义隐藏层维度、注意力头数和上下文长度。关键特性包括：

• RoPE（旋转位置编码）：modeling_gemma.py 中实现了完整的 Rotary Position Embedding，通过旋转坐标系而非添加位置偏置来编码位置信息，避免了原始 Transformer 中位置编码难以泛化到长序列的问题。
• RMSNorm：用均方根归一化替代 LayerNorm，参数量更少，训练更稳定。
• KV-Cache 机制：在 inference.py 的推理循环中，通过 KVCache 类缓存已计算的 Key-Value 状态，避免在自回归生成时重复计算，大幅提升推理速度。每生成一个 token，只需计算当前 token 的注意力，无需重新处理整个历史序列。

Multimodal Projection（跨模态投影层）

这是 PaliGemma 区别于纯语言模型的核心：视觉特征（SigLIP 输出）和文本特征（Gemma 输入）维度不同，需要一个投影层将两者对齐。在 PaliGemmaConfig 中，projection_dim=2048 就是这个投影层的维度。投影层通常是一个线性映射，将 SigLIP 的视觉 embedding 投影到 Gemma 的语言空间。

PaliGemmaProcessor（输入处理）

processing_paligemma.py 实现了完整的输入预处理流程，这是最容易被忽视但又至关重要的环节：

• 图片经过 SigLIP 的预处理（resize、normalize、center-crop）转换为标准化 tensor。
• 文本 prompt 被 tokenize，并在前面添加固定数量的 <image> token（数量由 image_seq_len 决定），告诉 Gemma 有多少图像特征需要处理。
• 在推理时，<image> token 的 embedding 被替换为 SigLIP 提取的视觉特征，实现真正的多模态融合。

代码结构与依赖

项目结构极为简洁，所有核心逻辑仅 5 个 Python 文件，总代码量约 2500 行：

依赖极为克制：除了 PyTorch 和 transformers，几乎没有第三方依赖。这意味着你可以在没有复杂环境的情况下，完整追踪每一行前向和反向传播的计算过程。notes/ 目录下还提供了 4 篇配套 PDF（Multi-Head Attention、Normalization、KV-Cache、From CLIP to SigLIP），对应视频教程的核心理论部分。

上手门槛与局限

优势方面： 代码极其精炼，没有工程代码的噪声。每个类、每个函数都可以独立理解。YouTube 视频提供了逐行讲解，配合代码学习效率很高。requirements.txt 明确指定了版本号，环境可复现。

不足方面： 无 Docker 支持，无 Web UI，必须手动配置 Python + CUDA 环境。模型权重需要从 HuggingFace 单独下载，可能对新手造成障碍。该实现侧重于教学目的，推理速度相比 transformers 库的优化版本会慢很多，不适合做性能敏感的部署场景。

行业意义

PaliGemma 的出现折射出一个趋势：开源 AI 的民主化正在从"发布模型"向"透明化模型"演进。传统上，学术团队发布新模型只提供推理 API 或高度封装的权重，学习者只能黑盒调用。而像 hkproj 这样的社区力量，正在填补"透明化"这一空白——用几千行代码，拆解几十亿参数模型的工作原理。

截至目前，该项目已获得 615 Stars 和 102 Forks，在 GitHub 上同主题项目中属于高热度。它也代表了一类新型开源项目：不以功能为目标，而以学习为核心价值。这类项目的生命力往往很长——只要 AI 技术持续演进，就永远有新的模型需要被"从零实现"。