transformers

transformers 5.x (5.18.0以降、main でも未修正) の既知のバグ: MMGroundingDinoForObjectDetection._tied_weights_keys が、チェックポイントの設定 decoder_bbox_embed_share: false / decoder_cls_embed_share: false を無視して、すべてのデコーダ層のボックスヘッドとクラスヘッドを層0に紐付けてしまいます。その結果、層1〜5は層0のヘッドを再利用することになり、ボックスの出力が誤ったものになります(例: RefCOCO の acc@0.5 が 7/8 から 0/8 に低下)。影響を受けるチェックポイントには、iSEE-Laboratory/llmdet_tiny/base/large、openmmlab-community/mm_grounding_dino_tiny_*、mm_grounding_dino_large_all が含まれます。

修正方法1 — 各層が独自のヘッドを保持していた v4 の動作にダウングレードする:
pip install "transformers==4.57.1"

修正方法2 — 読み込み後に、チェックポイントから各デコーダ層の独自ヘッドを復元する:

from huggingface_hub import hf_hub_download
from safetensors.torch import load_file

weights = load_file(hf_hub_download(model_id, "model.safetensors"))
for i in range(1, model.config.decoder_layers):
    model.bbox_embed[i] = type(model.bbox_embed[0])(model.config.d_model, model.config.d_model, 4, 3)
    model.bbox_embed[i].load_state_dict({k.split(f"bbox_embed.{i}.")[1]: v for k, v in weights.items()
                                         if k.startswith(f"model.decoder.bbox_embed.{i}.")})
    model.class_embed[i] = type(model.class_embed[0])(model.config)
    model.class_embed[i].bias.data = weights[f"model.decoder.class_embed.{i}.bias"].clone()
model.model.decoder.bbox_embed = model.bbox_embed
model.model.decoder.class_embed = model.class_embed

これは src/transformers/video_utils.py 内の default_sample_indices_fn() のバグです。この関数は num_frames = int(total_num_frames / video_fps * fps) を計算しますが、短い動画ではこの値が 0 に切り捨てられてしまいます（例えば、10フレーム・30 FPS の動画を 1 FPS でサンプリングすると int(10/30*1) == 0 となります）。その結果、下流のデコーダーがクラッシュします。read_video_pyav() は indices[-1] で失敗し、read_video_opencv() は np.stack(frames) で失敗します。修正方法：このパッチを含むバージョンに transformers をアップグレードしてください。このパッチは、空でない動画に対して正の FPS が要求された場合に、少なくとも1つのフレームインデックス（例：[0]）が返されるよう結果をクランプします。古いバージョンでの回避策：int(total_num_frames / video_fps * fps) >= 1 となるよう、より高い fps を要求するか、total_num_frames > 0 かつ fps > 0 の場合に num_frames = max(1, int(total_num_frames / video_fps * fps)) となるようこの関数にモンキーパッチを適用してください。

Hugging Face Transformers の VLM プロセッサは受け付ける入力フォーマットが一貫していないため、あるモデルで動作する pipeline 呼び出しが別のモデルではクラッシュすることがあります。重要なルールと回避策は次のとおりです。

1. **URL**: 画像 URL を直接受け付けるのは Idefics、Idefics2、Idefics3、Pixtral のみです。その他すべてのモデル（LLaVA、BLIP、PaliGemma、Qwen2-VL など）では、まずダウンロードして PIL に変換してください。

from PIL import Image
import requests
image = Image.open(requests.get(url, stream=True).raw)

2. **ファイルパス**: 生のファイルパスを受け付ける VLM プロセッサはありません。必ず先に Image.open(path) で読み込んでください。

3. **テキストごとに画像の数が異なるネストされたバッチ**（例: images=[[img1, img2], [img3]]）: これをサポートしているのは Qwen2-VL、Chameleon、PaliGemma、Llava-Next、LLaVA-OneVision、Mllama、InstructBLIP、Idefics2、Idefics3 のみです。LLaVA、BLIP2、VipLlava、Pixtral などのモデルはプロセッサレベルでクラッシュします。回避策: 互換性のあるモデルに切り替える（例: llava-hf/llava-interleave-qwen-0.5b-hf の代わりに llava-hf/llava-onevision-qwen2-0.5b-ov-hf を使用する）か、各テキスト/画像セットをバッチ化せず個別の呼び出しで処理してください。

4. **パディングの注意点**: Qwen2-VL は padding=True の場合、ネストされていないバッチ画像でクラッシュします。Chameleon はそもそも動作させるために padding を手動で True に設定する必要があります。

PIL は唯一すべてのモデルで共通してサポートされているフォーマットなので、モデルのプロセッサのドキュメントを確認するか、まず単一の PIL 画像でテストしてください。

SpanBERTの事前学習済み重みはHugging Face Hub上で公開されており、標準のBERTアーキテクチャで読み込むことができます：

from transformers import AutoTokenizer, AutoModel
tokenizer = AutoTokenizer.from_pretrained("SpanBERT/spanbert-base-cased")
model = AutoModel.from_pretrained("SpanBERT/spanbert-base-cased")

SpanBERT/spanbert-large-casedも利用可能です。ただし、元の論文における共参照ヘッド（TensorFlow 1.14のmandarjoshi90/coref実装）はTransformersに移植されていないため、組み込みのSpanBERT共参照パイプラインは存在しません。現在の共参照解決のための回避策は次のとおりです：

1. コミュニティモデルbiu-nlp/f-coref（fastcoref）を使用する。これはすぐに使える共参照パイプラインを提供します。
2. 代替としてneuralcoref（spaCyベース）を使用する。
3. 論文のアプローチを再現する必要がある場合は、読み込んだSpanBERTのAutoModelの上にスパン分類ヘッドを自分でファインチューニングする。

根本原因: Gemma4AudioAttention は masked_fill(attention_mask.logical_not(), ...) によってアテンションマスクを適用しており、これはboolマスクを想定しています。しかし create_bidirectional_mask はeagerでは加算型のfloatマスク(0.0 = 許可、finfo.min = 不許可)を返すため、logical_not() がセマンティクスを反転させてしまいます — 許可された位置がマスクアウトされ、完全に許可されたマスクの場合、内容に関係なくアテンションがほぼ一様な平均化に退化してしまいます。即時の回避策: 正しいboolマスクを使用するsdpaアテンションを強制します — attn_implementation="sdpa" を指定してモデルをロードするか、model.set_attn_implementation("sdpa") を呼び出してください。恒久的な修正(transformers にパッチを適用): Gemma4AudioAttention で両方のマスク規約を処理します — boolマスク → masked_fill(mask.logical_not(), invalid_value)、floatマスク → ブロック化された5-D変換の後に attn_weights = attn_weights + attention_mask として加算的に適用します。また、_convert_4d_mask_to_blocked_5d をdtype対応にします: floatマスクの場合は value=False(これは 0.0 でパディングし、float規約では*許可*を意味します)ではなく、F.pad(..., value=torch.finfo(dtype).min) を使用してください。同一のシードでeagerとsdpaの出力を比較して修正を検証してください — 最大絶対差は ~0.12 から ~1e-6 に低下するはずです。