扩展t2v_metrics:如何为自己的多模态大模型实现自定义打分指标(完整插件式架构开发指南)
扩展t2v_metrics:如何为自己的多模态大模型实现自定义打分指标(完整插件式架构开发指南)
📌 t2v_metrics 是一个用 VQAScore 等指标自动评估文生图 / 文生视频 / 3D 生成模型的开源工具包,已内置 CLIP-FlanT5、LLaVA、Qwen2.5-VL 等 20 多个多模态大模型。更关键的是:它采用三层插件式架构,让"为你自己的多模态大模型实现自定义打分指标"只需几十行代码,无需改动任何框架核心。本文面向新手,拆解这套架构,带你 5 步把自研模型接进 t2v_metrics。
什么是 t2v_metrics:一行代码评估文生图/视频模型
在谈扩展之前,先看它的日常用法。安装后只需一行代码即可获得图文对齐分数(分数越高表示生成结果与提示词越吻合):
import t2v_metrics
clip_flant5_score = t2v_metrics.VQAScore(model='clip-flant5-xxl')
score = clip_flant5_score(images=["images/0.png"],
texts=["someone talks on the phone angrily"])
t2v_metrics 内置了三大类指标,覆盖了目前主流的两种技术路线:
| 指标族 | 思路 | 代表模型 |
|---|---|---|
| VQAScore | 让多模态大模型回答"图中是否展示了这个描述?",用"Yes"的概率作分数 | CLIP-FlanT5、LLaVA、GPT-4o、Qwen2-VL |
| CLIPScore | 计算图像与文本嵌入的余弦相似度 | OpenCLIP(200+ 模型)、HPSv2、PickScore |
| ITMScore | 图文匹配(ITM)二分类模型的判断概率 | BLIP2-ITM、UMT-ITM、InternVideo2-ITM |
比如用文生图模型生成下面的图,再用打分指标自动检验"生成内容是否忠实于提示词":
💡 为什么用"大模型答题"来打分?因为 CLIP 类相似度对组合式提示词(数量、空间关系、动作)不敏感,而 VQAScore 把"图文是否匹配"变成一个视觉问答(VQA)问题,由多模态大模型直接作答,与人类判断更一致。
读懂插件式架构:新打分模型如何被"插进去"
t2v_metrics 的扩展性来自清晰的三层设计,自底向上看:
第 1 层:统一打分接口(Score 基类)
所有指标共享一个基类 t2v_metrics/score.py,它固定了 forward(单对打分)和 batch_forward(批量打分)的行为:
class Score(nn.Module):
def prepare_scoremodel(self, model, device, cache_dir, **kwargs):
raise NotImplementedError("Subclasses must implement prepare_scoremodel")
def list_all_models(self) -> List[str]:
raise NotImplementedError("Subclasses must implement list_all_models")
子类只需回答两个问题:"模型实例怎么创建"、"支持哪些模型名"。像视频抽帧拼接这类通用逻辑,基类已经替你处理好了。
第 2 层:指标子类 + 模型包装器
以 VQAScore 为例,t2v_metrics/vqascore.py 里的 VQAScore(Score) 只做了"转发"。真正的模型实现放在 t2v_metrics/models/vqascore_models/ 目录,每个模型一个文件,且都继承同一个抽象基类 t2v_metrics/models/vqascore_models/vqa_model.py(其父类是 t2v_metrics/models/model.py 中的 ScoreModel):
class ScoreModel(ABC):
@abstractmethod
def load_model(self): ...
@abstractmethod
def load_images(self, image: List[str]) -> torch.Tensor: ...
@abstractmethod
def forward(self, images: List[str], texts: List[str]) -> torch.Tensor: ...
这就是插件契约:实现这三个方法,你的模型就是一个合法插件。 官方推荐的参考实现是 llava_model.py 和 instructblip_model.py——结构完整、注释清晰,照着抄即可。
第 3 层:模型注册表(名字 → 实现)
打开 t2v_metrics/models/vqascore_models/init.py,你会看到"注册表"的真身:
ALL_VQA_MODELS = [CLIP_T5_MODELS, LLAVA_MODELS, InstructBLIP_MODELS, ...]
def get_vqascore_model(model_name, device='cuda', cache_dir=HF_CACHE_DIR, **kwargs):
if model_name in CLIP_T5_MODELS:
return CLIPT5Model(model_name, device=device, cache_dir=cache_dir, **kwargs)
elif model_name in LLAVA_MODELS:
return LLaVAModel(model_name, device=device, cache_dir=cache_dir, **kwargs)
# ... 每个模型族一个 elif 分支
用户调用 t2v_metrics.VQAScore(model='llava-v1.5-7b') 时,t2v_metrics/init.py 里的 get_score_model() 会按名字在三个指标族中查找,最终路由到对应模型类。新增模型 = 写一个类 + 在注册表登记一行,其余一切(批量处理、视频拼接、设备管理)自动继承。
分步实操:为你的多模态大模型实现自定义 VQAScore 指标
下面以"把自己的 7B 多模态大模型接进来"为例,完整走一遍。
第 1 步:新建模型包装文件
在 t2v_metrics/models/vqascore_models/ 下新建 my_metric_model.py,先定义模型名列表并继承 VQAScoreModel:
# t2v_metrics/models/vqascore_models/my_metric_model.py
from typing import List
import torch
from .vqa_model import VQAScoreModel
from ...constants import HF_CACHE_DIR
MY_MODELS = ['my-model-7b'] # 对外暴露的模型名
class MyModel(VQAScoreModel):
"""你自研多模态大模型的打分包装器"""
video_mode = "concat" # "concat"=视频抽帧拼接 / "direct"=原生视频输入
allows_image = True
def __init__(self, model_name='my-model-7b', device='cuda',
cache_dir=HF_CACHE_DIR):
assert model_name in MY_MODELS
super().__init__(model_name=model_name, device=device,
cache_dir=cache_dir)
第 2 步:实现三个核心方法
对照 llava_model.py 的写法,只需填充骨架:
def load_model(self):
"""加载权重、tokenizer、图像预处理管线"""
self.model = ... # 你的多模态大模型
self.tokenizer = ...
self.model.eval().to(self.device)
def load_images(self, image: List[str]) -> torch.Tensor:
"""图像路径 -> 预处理后的张量(放到 self.device)"""
images = [self.image_loader(x) for x in image] # 基类自带的图像加载器
return torch.stack([self.preprocess(img) for img in images], 0).to(self.device)
@torch.no_grad()
def forward(self, images, texts,
question_template='Does this figure show "{}"? Please answer yes or no.',
answer_template='Yes') -> torch.Tensor:
"""返回 n 个 (image, text) 对的相似度分数(1 维 Tensor)"""
questions = [question_template.format(t) for t in texts]
# 调用你的模型计算 P("Yes" | image, question),返回概率张量
...
⚠️ 关键约定:forward 返回的是 n 个分数组成的 1 维张量(每个图文对一个),分数应落在 0~1 之间。基类 t2v_metrics/score.py 会把它组装成 M×N 矩阵返回给用户。
第 3 步:在注册表登记
修改 t2v_metrics/models/vqascore_models/init.py 的两处:
from .my_metric_model import MY_MODELS, MyModel
ALL_VQA_MODELS = [
CLIP_T5_MODELS,
LLAVA_MODELS,
# ...
MY_MODELS # ← 加入列表,list_all_vqascore_models() 即可查到
]
def get_vqascore_model(model_name, device='cuda', cache_dir=HF_CACHE_DIR, **kwargs):
# ... 现有分支
elif model_name in MY_MODELS:
return MyModel(model_name, device=device, cache_dir=cache_dir, **kwargs)
第 4 步:一行代码调用验证
import t2v_metrics
print(t2v_metrics.list_all_vqascore_models()) # 应能看到 'my-model-7b'
my_score = t2v_metrics.VQAScore(model='my-model-7b')
score = my_score(images=["images/0.png"],
texts=["someone talks on the phone angrily while another person sits happily"])
第 5 步(可选):免费获得视频与批量能力
- 视频评分:声明
video_mode = "concat"后,基类会自动抽帧并横向拼接成"长图"再交给你的模型(见 t2v_metrics/score.py);若你的模型原生支持视频,设"direct"并在forward里处理帧序列即可。 - 批量评分:
batch_forward()直接可用,返回(样本数, 图像数, 文本数)张量,是跑 GenAI-Bench 这类大规模评测的标准姿势。
进阶技巧:问题模板、视频支持与常见坑
1. 自定义问题模板。 VQAScore 的分数 = 大模型对"Yes"的置信度,提问方式会影响分数。默认模板在各模型文件中定义,例如 clip_t5_model.py:
default_question_template = 'Does this figure show "{}"? Please answer yes or no.'
default_answer_template = 'Yes'
{} 会被提示词替换。你也可以像官方实现那样,让用户通过 forward(question_template=..., answer_template=...) 在运行时传入——这对复现论文结果很重要。
2. 视频抽帧参数。 Qwen 系模型建议用 fps=8.0,LLaVA 系用 num_frames=8,这些参数会透传到你的 forward,记得按需接收。
3. 缓存目录。 所有模型权重的默认下载位置由 t2v_metrics/constants.py 中的 HF_CACHE_DIR(默认 ./hf_cache/)控制,大模型插件请遵循这一约定。
4. 常见坑清单:
| 坑 | 正确做法 |
|---|---|
forward 返回 2 维张量 |
必须返回 1 维(n 个分数) |
忘记 assert model_name in MY_MODELS |
与官方实现保持一致,防止拼写错误静默通过 |
| 模型名与 HF 仓库路径混淆 | MY_MODELS 里填"逻辑名",仓库路径写在类内部 |
张量没放到 self.device |
load_images 的返回值必须在模型所在设备 |
这套"大模型当评委"的自动评估流程,本质上就是:参考描述(提示词)与模型生成结果做交叉校验,逐条抽取关键信息再比对,从而得到召回/精确率式的量化分数:
扩展 CLIPScore 与 ITMScore:同一套插件思路
如果你要接入的不是"答题型"大模型,而是相似度/匹配型模型,走完全相同的路径,只是换目录:
- CLIPScore 插件:继承 t2v_metrics/models/clipscore_models/clip_model.py 同款结构(实现
load_model/load_images/forward,forward返回余弦相似度),再登记进 t2v_metrics/models/clipscore_models/init.py 的ALL_CLIP_MODELS。参考实现:hpsv2_model.py、pickscore_model.py。 - ITMScore 插件:登记进 t2v_metrics/models/itmscore_models/init.py 的
ALL_ITM_MODELS,参考 blip2_itm_model.py。
三个指标族共享同一个 Score 基类与调用习惯,所以学会一套扩展方法 = 学会全部三套。
总结:插件式架构的核心文件清单
| 你要做的事 | 关键文件 |
|---|---|
| 理解统一打分接口 | t2v_metrics/score.py |
| 理解指标子类(VQAScore/CLIPScore/ITMScore) | t2v_metrics/vqascore.py / t2v_metrics/clipscore.py / t2v_metrics/itmscore.py |
| 实现模型插件(三方法契约) | t2v_metrics/models/model.py、t2v_metrics/models/vqascore_models/vqa_model.py |
| 抄一份完整参考实现 | t2v_metrics/models/vqascore_models/llava_model.py、instructblip_model.py |
| 登记新模型(注册表) | t2v_metrics/models/vqascore_models/init.py |
| 修改缓存目录等全局常量 | t2v_metrics/constants.py |
记住插件契约的三句话:继承 VQAScoreModel → 实现 load_model / load_images / forward → 在注册表加一行。从此,你的多模态大模型就和 CLIP-FlanT5 一样,被一行 t2v_metrics.VQAScore(model='你的名字') 优雅调用。🚀



