ImageLongCLIPEvaluator
748 字约 2 分钟
2025-10-15
📘 概述
ImageLongCLIPEvaluator 使用 LongCLIP 计算图像与长文本的对齐分数,分数范围为 [0,1]。
相较于标准 CLIP,LongCLIP 支持更长的文本上下文(本实现默认 context_length=248),适合段落级描述的匹配评估与对齐打分任务。
内部流程与 CLIP 类似:对图像与文本分别编码,得到向量后做 L2 归一化,再计算余弦相似度,并通过 (cos + 1) / 2 映射到 [0,1] 区间。
__init__函数
def __init__(
self,
model_name: str = "BeichenZhang/LongCLIP-L-336px",
device: str = None,
):
...init参数说明
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model_name | str | "BeichenZhang/LongCLIP-L-336px" | LongCLIP 模型 checkpoint 标识;若为目录路径,算子会在目录中搜索以 .pt / .bin / .ckpt 结尾的文件并自动选择一个进行加载;若为文件路径,则直接将该文件作为权重加载。 |
device | str | None | None | 推理设备;None 时自动选择可用的 "cuda",否则使用 "cpu"。 |
run函数
def run(
self,
storage: DataFlowStorage,
input_image_key: str = "image_path",
input_text_key: str = "text",
output_key: str = "longclip_score",
):
...执行算子主逻辑
- 从
storage读取 DataFrame,逐行读取input_image_key与input_text_key。 - 使用
self.preprocess将图像转为张量img_t;使用_tokenize_safe对长文本进行安全分词与截断(优先context_length=248,失败则回退)。 - 分别前向
model.encode_image(img_t)与model.encode_text(txt_t)得到图像/文本特征。 - 对两个特征做 L2 归一化并计算点积余弦相似度
cos,映射为分数score = (cos + 1) / 2,裁剪到[0,1]。 - 将分数写入新列
output_key,写回storage并返回[output_key]。 - 若图片无法读取或文本为空,则该样本分数记为
0.0。
参数
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
storage | DataFlowStorage | 无 | Dataflow 的读写存储对象,用于在算子内部读取与写回 DataFrame。 |
input_image_key | str | "image_path" | 输入图片列名,对应该 DataFrame 中存放图像路径的字段。 |
input_text_key | str | "text" | 输入长文本列名,对应该 DataFrame 中存放段落级文本描述的字段。 |
output_key | str | "longclip_score" | 输出分数字段名(范围 [0,1]),用于存放 LongCLIP 图文对齐分数。 |
🧠 示例用法
from dataflow.utils.storage import FileStorage
from dataflow.operators.core_vision import ImageLongCLIPEvaluator
# 1) 准备 FileStorage(至少包含 image_path 与 text 两列)
storage = FileStorage(
first_entry_file_name="./dataflow/example/test_image_eval/test_image_eval.jsonl",
cache_path="./cache_local",
file_name_prefix="longclip_eval",
cache_type="jsonl"
)
# 2) 初始化 LongCLIP 评估算子(model_name 可以是目录或具体权重文件路径)
evaluator = ImageLongCLIPEvaluator(
model_name="BeichenZhang/LongCLIP-L-336px",
device=None # 自动选择 cuda/cpu
)
# 3) 执行评估:将为每行新增 longclip_score ∈ [0,1]
cols = evaluator.run(
storage=storage.step(),
input_image_key="image_path",
input_text_key="text",
output_key="longclip_score"
)
print(cols) # ["longclip_score"]🧾 默认输出格式(Output Format)
| 字段名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
image_path(或 input_image_key 指定列) | string | 无 | 输入图片路径。 |
text(或 input_text_key 指定列) | string | 无 | 输入长文本描述。 |
longclip_score(或 output_key) | float | 无 | 长文本图文对齐分数,范围 [0,1]。 |
示例输入:
{
"image_path": "1.png",
"text": "The image shows a man and a woman in what appears to be a car."
}示例输出:
{
"image_path": "1.png",
"text": "The image shows a man and a woman in what appears to be a car.",
"clip_score": 0.642
}
