企业官网建设流程全解析

PaliGemma2 目标检测微调实战：用自定义数据集训练扑克牌检测模型

这篇教程是我根据 PaliGemma2 多模态目标检测微调、自定义数据集导出和 supervision 评估流程整理出来的。重点演示如何把 从数据集后台导出的 PaliGemma JSONL 数据集用于检测任务微调，并用 mAP、混淆矩阵和可视化样例评估结果。

PaliGemma2 可以把目标检测任务表述为“图像 + 文本前缀 -> 文本后缀”的生成式任务。这里的 suffix 保存了类别和框坐标，训练完成后再用supervision解析为标准检测结果。

本文会重点跑通以下流程：

• 下载 PaliGemma 格式目标检测数据集
• 用 JSONL 样本构造图像和文本训练对
• 冻结视觉编码器进行轻量微调
• 用supervision解析 PaliGemma 检测文本
• 计算 mAP 和混淆矩阵评估模型

如果你正在系统学习多模态微调、目标检测、OCR 或图像分割，建议收藏本文；配套 notebook、示例图片和运行环境说明后续会继续整理。如果环境配置卡住，可以在评论区说明具体报错。

⚙️ 环境准备

检查 GPU，安装 supervision、PEFT、bitsandbytes 和指定版本 transformers。

!nvidia-smi

📦 下载 PaliGemma 数据集

从数据集后台获取扑克牌检测数据集，导出格式为paligemma。

!pip install-q supervision peft bitsandbytes transformers==4.47.0

fromtypesimportSimpleNamespace# 从数据集后台下载并解压数据集后，修改 DATASET_DIR 指向数据集目录。DATASET_DIR="/content/dataset"# 修改为数据集后台导出的数据集目录dataset=SimpleNamespace(location=DATASET_DIR)

!head-n5{dataset.location}/dataset/_annotations.train.jsonl

🧾 加载并预览 JSONL 数据

定义 JSONL 数据集类，读取图片和标注文本，并用 supervision 预览训练样本。

importosimportjsonimportrandomfromPILimportImagefromtorch.utils.dataimportDatasetclassJSONLDataset(Dataset):def__init__(self,jsonl_file_path:str,image_directory_path:str):self.jsonl_file_path=jsonl_file_path self.image_directory_path=image_directory_path self.entries=self._load_entries()def_load_entries(self):entries=[]withopen(self.jsonl_file_path,'r')asfile:forlineinfile:data=json.loads(line)entries.append(data)returnentriesdef__len__(self):returnlen(self.entries)def__getitem__(self,idx:int):ifidx<0oridx>=len(self.entries):raiseIndexError("Index out of range")entry=self.entries[idx]image_path=os.path.join(self.image_directory_path,entry['image'])image=Image.open(image_path)returnimage,entry

train_dataset=JSONLDataset(jsonl_file_path=f"{dataset.location}/dataset/_annotations.train.jsonl",image_directory_path=f"{dataset.location}/dataset",)valid_dataset=JSONLDataset(jsonl_file_path=f"{dataset.location}/dataset/_annotations.valid.jsonl",image_directory_path=f"{dataset.location}/dataset",)test_dataset=JSONLDataset(jsonl_file_path=f"{dataset.location}/dataset/_annotations.test.jsonl",image_directory_path=f"{dataset.location}/dataset",)

fromtqdmimporttqdmimportsupervisionassv CLASSES=train_dataset[0][1]['prefix'].replace("detect ","").split(" ; ")images=[]foriinrange(25):image,label=train_dataset[i]detections=sv.Detections.from_lmm(lmm='paligemma',result=label["suffix"],resolution_wh=(image.width,image.height),classes=CLASSES)image=sv.BoxAnnotator(thickness=4).annotate(image,detections)image=sv.LabelAnnotator(text_scale=2,text_thickness=4).annotate(image,detections)images.append(image)sv.plot_images_grid(images,(5,5))

🧠 加载 PaliGemma2 模型

加载 PaliGemma2 processor 和模型，并提供冻结视觉编码器或 LoRA/QLoRA 两种训练方式。

importtorchfromtransformersimportPaliGemmaProcessor,PaliGemmaForConditionalGeneration MODEL_ID="google/paligemma2-3b-pt-448"DEVICE=torch.device("cuda"iftorch.cuda.is_available()else"cpu")

fromhuggingface_hubimportnotebook_login notebook_login()

processor=PaliGemmaProcessor.from_pretrained(MODEL_ID)

# @title Freeze the image encoderTORCH_DTYPE=torch.bfloat16 model=PaliGemmaForConditionalGeneration.from_pretrained(MODEL_ID,torch_dtype=TORCH_DTYPE).to(DEVICE)forparaminmodel.vision_tower.parameters():param.requires_grad=Falseforparaminmodel.multi_modal_projector.parameters():param.requires_grad=False

# @title Fine-tune the entire model with LoRA and QLoRA# from transformers import BitsAndBytesConfig# from peft import get_peft_model, LoraConfig# bnb_config = BitsAndBytesConfig(# load_in_4bit=True,# bnb_4bit_compute_dtype=torch.bfloat16# )# lora_config = LoraConfig(# r=8,# target_modules=["q_proj", "o_proj", "k_proj", "v_proj", "gate_proj", "up_proj", "down_proj"],# task_type="CAUSAL_LM",# )# model = PaliGemmaForConditionalGeneration.from_pretrained(MODEL_ID, device_map="auto")# model = get_peft_model(model, lora_config)# model.print_trainable_parameters()# TORCH_DTYPE = model.dtype

🏋️ 微调 PaliGemma2 检测模型

构造 collate 函数，将检测文本后缀作为训练目标，并使用 Transformers Trainer 启动训练。

fromtransformersimportTrainer,TrainingArgumentsdefaugment_suffix(suffix):parts=suffix.split(' ; ')random.shuffle(parts)return' ; '.join(parts)defcollate_fn(batch):images,labels=zip(*batch)paths=[label["image"]forlabelinlabels]prefixes=["<image>"+label["prefix"]forlabelinlabels]suffixes=[augment_suffix(label["suffix"])forlabelinlabels]inputs=processor(text=prefixes,images=images,return_tensors="pt",suffix=suffixes,padding="longest").to(TORCH_DTYPE).to(DEVICE)returninputs args=TrainingArguments(num_train_epochs=16,remove_unused_columns=False,per_device_train_batch_size=1,gradient_accumulation_steps=16,warmup_steps=2,learning_rate=2e-5,weight_decay=1e-6,adam_beta2=0.999,logging_steps=50,optim="adamw_hf",save_strategy="steps",save_steps=1000,save_total_limit=1,output_dir="paligemma2_object_detection",bf16=True,report_to=["tensorboard"],dataloader_pin_memory=False)trainer=Trainer(model=model,train_dataset=train_dataset,eval_dataset=valid_dataset,data_collator=collate_fn,args=args)

trainer.train()

🔍 使用微调模型推理

在测试集上生成检测文本，解析为检测框并可视化。

image,label=test_dataset[1]prefix="<image>"+label["prefix"]suffix=label["suffix"]inputs=processor(text=prefix,images=image,return_tensors="pt").to(TORCH_DTYPE).to(DEVICE)prefix_length=inputs["input_ids"].shape[-1]withtorch.inference_mode():generation=model.generate(**inputs,max_new_tokens=256,do_sample=False)generation=generation[0][prefix_length:]decoded=processor.decode(generation,skip_special_tokens=True)print(decoded)w,h=image.size detections=sv.Detections.from_lmm(lmm='paligemma',result=decoded,resolution_wh=(w,h),classes=CLASSES)annotated_image=image.copy()annotated_image=sv.BoxAnnotator().annotate(annotated_image,detections)annotated_image=sv.LabelAnnotator(smart_position=True).annotate(annotated_image,detections)annotated_image

📈 评估检测效果

遍历测试集生成预测，计算 mAP、混淆矩阵，并绘制预测样例网格。

importnumpyasnpfromtqdmimporttqdm images=[]targets=[]predictions=[]withtorch.inference_mode():foriintqdm(range(len(test_dataset))):image,label=test_dataset[i]prefix="<image>"+label["prefix"]suffix=label["suffix"]inputs=processor(text=prefix,images=image,return_tensors="pt").to(TORCH_DTYPE).to(DEVICE)prefix_length=inputs["input_ids"].shape[-1]generation=model.generate(**inputs,max_new_tokens=256,do_sample=False)generation=generation[0][prefix_length:]generated_text=processor.decode(generation,skip_special_tokens=True)w,h=image.size prediction=sv.Detections.from_lmm(lmm='paligemma',result=generated_text,resolution_wh=(w,h),classes=CLASSES)prediction.class_id=np.array([CLASSES.index(class_name)forclass_nameinprediction['class_name']])prediction.confidence=np.ones(len(prediction))target=sv.Detections.from_lmm(lmm='paligemma',result=suffix,resolution_wh=(w,h),classes=CLASSES)target.class_id=np.array([CLASSES.index(class_name)forclass_nameintarget['class_name']])images.append(image)targets.append(target)predictions.append(prediction)

# @title Calculate mAPfromsupervision.metricsimportMeanAveragePrecision,MetricTarget map_metric=MeanAveragePrecision(metric_target=MetricTarget.BOXES)map_result=map_metric.update(predictions,targets).compute()print(map_result)

map_result.plot()

# @title Calculate Confusion Matrixconfusion_matrix=sv.ConfusionMatrix.from_detections(predictions=predictions,targets=targets,classes=CLASSES)_=confusion_matrix.plot()

annotated_images=[]foriinrange(25):image=images[i]detections=predictions[i]annotated_image=image.copy()annotated_image=sv.BoxAnnotator(thickness=4).annotate(annotated_image,detections)annotated_image=sv.LabelAnnotator(text_scale=2,text_thickness=4,smart_position=True).annotate(annotated_image,detections)annotated_images.append(annotated_image)sv.plot_images_grid(annotated_images,(5,5))

📌 小结

这篇教程完整整理了Fine-Tune PaliGemma2 on Object Detection Dataset的核心复现流程。实际操作时，建议先确认 GPU、依赖版本、数据集路径和模型权限，再逐段运行 notebook。

• 下载 PaliGemma 格式目标检测数据集
• 用 JSONL 样本构造图像和文本训练对
• 冻结视觉编码器进行轻量微调
• 用supervision解析 PaliGemma 检测文本
• 计算 mAP 和混淆矩阵评估模型

后续我会继续按源项目顺序整理 项目教程 中的目标检测、实例分割、OCR、多目标跟踪和视觉大模型教程。

📚 同系列教程汇总

• Google Gemini 3.5 Flash 零样本目标检测教程：从提示词到可视化结果

• GLM-OCR 文档识别实战教程：从验证码、公式到车牌 OCR

• RF-DETR + ByteTrack 多目标跟踪实战教程：从命令行到 Python 视频轨迹可视化

• SAM 3 图像分割实战教程：文本、框和点提示的多种分割方式

• PaliGemma2 目标检测微调实战：用自定义数据集训练扑克牌检测模型-本文