如何快速上手tipsv1-g14-lowres:从环境搭建到首次推理的完整新手教程
如何快速上手tipsv1-g14-lowres:从环境搭建到首次推理的完整新手教程
tipsv1-g14-lowres 是 Google TIPS(Text-Image Pre-training with Spatial awareness,ICLR 2025)系列中的一款视觉语言模型,主打零样本图像分类、图像与文本特征对齐等能力。它采用低分辨率(224)输入,推理更省资源,非常适合新手快速体验。本教程带你从零完成环境搭建、加载模型,到跑通第一次推理,全程只需几分钟。
一、先认识 tipsv1-g14-lowres 是什么 🧭
TIPS 是一族对比学习训练的多模态模型:它同时理解图片和文字,并把两者映射到同一向量空间,从而支持"不训练直接分类"的零样本任务。
TIPS 家族有多种尺寸,g/14 low-res 是其中的旗舰规格,只是把输入分辨率降到 224,让普通显卡也能轻松跑动:
| 变体 | 视觉参数 | 文本参数 | 嵌入维度 | 输入分辨率 |
|---|---|---|---|---|
| S/14 | 22M | 34M | 384 | 448 |
| B/14 | 86M | 110M | 768 | 448 |
| L/14 | 304M | 184M | 1024 | 448 |
| g/14 | 1.1B | 389M | 1536 | 448 |
| g/14 low-res | 1.1B | 389M | 1536 | 224 |
💡 一句话理解:输入一张 224×224 的图片 + 一组文字候选,模型直接告诉你是谁。
它的内部由两大编码器构成:
- 视觉编码器:40 层 ViT-g/14,输出"全局向量 + 每个局部 patch 的向量",详见 image_encoder.py
- 文本编码器:12 层 Transformer,把文字转成同维度的向量,详见 text_encoder.py
二、仓库文件结构速览 📁
打开 README.md 前,先了解每个文件是干嘛的,遇到问题时能直接对照查看:
| 文件 | 作用 |
|---|---|
| config.json | 模型超参数配置(层数、维度、温度值等) |
| configuration_tips.py | 自定义模型配置类 TIPSv2Config |
| modeling_tips.py | 核心推理逻辑,含 encode_image / encode_text |
| image_encoder.py | 视觉塔实现 |
| text_encoder.py | 文本塔实现 |
| tokenizer.model | SentencePiece 分词器 |
| tokenizer_config.json | 分词器配置(小写化、最大 64 tokens) |
| processor_config.json | 图像预处理配置(224×224、不做归一化) |
| model.safetensors | 模型权重文件 |
如果你希望对照源码调试,可以先把仓库拉到本地:
git clone https://gitcode.com/hf_mirrors/google/tipsv1-g14-lowres
三、一键安装环境:依赖清单 ✅
模型基于 Hugging Face transformers 生态,依赖很少。推荐使用 Python 3.9+ 并创建虚拟环境:
python -m venv tips_env
source tips_env/bin/activate # Windows 用 tips_env\Scripts\activate
安装所需库:
pip install transformers torch torchvision sentencepiece scikit-learn requests
📌
torch会自动带入 GPU/CPU 版本。若你使用 NVIDIA 显卡,建议参考官方渠道安装带 CUDA 的版本,推理速度会大幅提升。
四、加载模型:3 行代码搞定 ⚡
加载模型只需 AutoModel 一行,加上 trust_remote_code=True(因为仓库内附带了自定义代码):
from transformers import AutoModel
model = AutoModel.from_pretrained("google/tipsv1-g14-lowres", trust_remote_code=True)
model.eval()
加载成功后,模型内部会同时就绪图像编码器与文本编码器(见 modeling_tips.py 中的类说明)。
五、第一次推理:编码一张图片 🖼️
关键细节:图像必须缩放到 224×224,且只转成 [0, 1] 的张量,不要做 ImageNet 归一化(这点在 processor_config.json 中已明确 do_normalize: false)。
import requests
from PIL import Image
from torchvision import transforms
url = "https://huggingface.co/spaces/google/TIPSv2/resolve/main/examples/zeroseg/pascal_context_00049_image.png"
image = Image.open(requests.get(url, stream=True).raw).convert("RGB")
transform = transforms.Compose([
transforms.Resize((224, 224)),
transforms.ToTensor()
])
pixel_values = transform(image).unsqueeze(0)
out = model.encode_image(pixel_values)
print(out.cls_token.shape) # (1, 1, 1536) 全局图像向量
print(out.patch_tokens.shape) # (1, 256, 1536) 每个 patch 的空间特征
跑通后你会得到两种向量(方法定义见 modeling_tips.py):
cls_token:整张图的全局表示,用于和文字做相似度匹配(与文本塔对齐的正是第一个 CLS)patch_tokens:16×16 网格、共 256 个局部块的特征,可用于空间感知任务,如定位、分割
六、编码文字:让图像与文本同频 📝
文字侧调用 encode_text,直接传入句子列表即可,模型会自动用 tokenizer.model 分词(实现见 modeling_tips.py):
text_emb = model.encode_text(["a photo of a bus", "a photo of a dog"])
print(text_emb.shape) # (2, 1536) —— 每个句子一个向量
七、零样本图像分类:不训练就能用 🎯
把图像向量与候选文字向量做余弦相似度,取最高分即预测类别——全程无需任何训练:
import torch.nn.functional as F
classes = ["bus", "car", "dog", "cat"]
cls = F.normalize(out.cls_token[:, 0, :], dim=-1)
text_emb = F.normalize(model.encode_text(classes), dim=-1)
similarity = cls @ text_emb.T
print(classes[similarity.argmax()]) # 预测类别
✨ 技巧:类别描述越贴近图像(如 "a photo of ..."),匹配通常越准。
八、进阶玩法:可视化空间特征 🔍
TIPS 的一大特色是"空间感知"。把 patch_tokens 用 PCA 降维到 3 通道,就能直观看到图像各区域对应什么语义:
import numpy as np
from sklearn.decomposition import PCA
feat = out.patch_tokens[0].detach().cpu().numpy()
rgb = PCA(n_components=3, whiten=True).fit_transform(feat).reshape(16, 16, 3)
rgb = 1 / (1 + np.exp(-2.0 * rgb)) # sigmoid 映射到 [0,1],对比度更好
得到的 16×16 矩阵可还原成一张"特征热力图",帮助你理解模型看到了图中哪些局部区域。
九、新手避坑指南 🛡️
| 常见问题 | 正确做法 |
|---|---|
| 图像做了 ImageNet 归一化 | ❌ 去掉,保持 [0, 1] 即可 |
| 分辨率用了 448 | 低分辨率版原生为 224(见 config.json) |
| 加载报代码相关错误 | 记得加 trust_remote_code=True |
| 文字没生效 | 输入会自动转小写,且最长 64 tokens(见 tokenizer_config.json) |
| 显存不够 | 用低分辨率版正是为此,必要时可用 CPU 跑通流程 |
补充:模型支持 patch 倍数的其它分辨率(通过位置编码插值实现),但新手建议先用原生 224 跑通。
十、总结:你已完成首次推理 🏁
跟随本教程,你已经掌握了 tipsv1-g14-lowres 的核心链路:装依赖 → 加载模型 → 编码图像 → 编码文字 → 零样本分类。接下来可以试试:
- 换成自己的照片做分类
- 把候选类别扩展到上百个,观察相似度排序
- 结合
patch_tokens做局部区域分析
更多变体(S/14、B/14、L/14 等)与学术引用信息,可在 README.md 中查看。
祝你玩得开心,顺利上手 tipsv1-g14-lowres!🚀