Skip to content

FASTVLM ガイド · Transformers

Transformers で FastVLM を実行

正式な Transformers 統合、マルチモーダル chat template、モデル読み込み方法を確認します。

FastVLM ガイド一覧

実行前の準備

Python 3.10+ の新しい環境を使用。例は FastVLM 対応の Transformers 5.0.0 に固定しています。ハードウェアに合う PyTorch を選択。スクリプトは CUDA / MPS / CPU を選びますが、CPU は遅い場合があります。

ライブラリとモデル形式を合わせる

apple/FastVLM-* は Apple 公開ファイルです。Transformers 例は公式文書で参照されるコミュニティ変換 KamilaMila/FastVLM-0.5B、ブラウザは onnx-community/FastVLM-0.5B-ONNX を使用します。

Setup · macOS / Linux
python -m venv .venv
source .venv/bin/activate
python -m pip install "transformers==5.0.0" "timm==1.0.29" torch pillow
curl -fLO https://fastvlm.net/examples/fastvlm_transformers.py
python fastvlm_transformers.py image.png --prompt "Describe this image."
完全な Python スクリプトを取得 ↓

最初の結果を確認

画像を image.png として保存して実行。成功すると生成された回答のみが表示されます。画像と質問に対応するか確認してください。

トラブルシューティング

  • ImportError:Transformers 5.0.0 を入れた環境か確認。
  • ダウンロード失敗:Hugging Face 接続とディスクを確認。
  • メモリ不足:0.5B を使い、他の GPU 処理を終了して出力を短縮。
  • 質問が回答に混入:input_ids 以降の生成トークンのみデコード。
Stage2 / Stage3 と Apple Silicon 形式 →

2026年9月12日出典確認。性能は実行端末に依存します。

手順

  1. 1

    FastVLM 対応版 Transformers をインストールします。

  2. 2

    互換モデルと AutoProcessor を読み込みます。

  3. 3

    image と text を分けたメッセージを構築します。

  4. 4

    generate 前に apply_chat_template を使用します。単純な文字列だけでは動作しません。

Transformers
"""Single-image FastVLM inference using the native Transformers integration.

Setup: python -m pip install 'transformers==5.0.0' 'timm==1.0.29' torch pillow
Run: python fastvlm_transformers.py image.png --prompt 'What is in this image?'
Source: https://huggingface.co/docs/transformers/model_doc/fast_vlm
The default is a community conversion used by that guide, not Apple's original ZIP.
"""

import argparse
from pathlib import Path

import torch
from transformers import AutoConfig, AutoProcessor, FastVlmForConditionalGeneration


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('image', type=Path)
    parser.add_argument('--prompt', default='Describe this image briefly.')
    parser.add_argument('--model', default='KamilaMila/FastVLM-0.5B')
    args = parser.parse_args()
    if not args.image.is_file():
        parser.error('The image file does not exist.')

    device = 'cuda' if torch.cuda.is_available() else 'mps' if torch.backends.mps.is_available() else 'cpu'
    dtype = torch.float16 if device == 'cuda' else torch.float32
    config = AutoConfig.from_pretrained(args.model)
    if args.model == 'KamilaMila/FastVLM-0.5B':
        # This older conversion records weight tying only in text_config.
        # Transformers 5 also needs it on the outer config to restore lm_head.
        config.tie_word_embeddings = config.text_config.tie_word_embeddings
    model = FastVlmForConditionalGeneration.from_pretrained(args.model, config=config, dtype=dtype).to(device).eval()
    processor = AutoProcessor.from_pretrained(args.model, use_fast=False)
    messages = [{'role': 'user', 'content': [
        {'type': 'image', 'path': str(args.image.resolve())},
        {'type': 'text', 'text': args.prompt},
    ]}]
    inputs = processor.apply_chat_template(
        messages, add_generation_prompt=True, tokenize=True,
        return_dict=True, return_tensors='pt',
    ).to(device)
    if 'pixel_values' in inputs:
        inputs['pixel_values'] = inputs['pixel_values'].to(dtype=dtype)
    # Qwen chat turns may end with im_end instead of the legacy endoftext.
    stop_tokens = [processor.tokenizer.eos_token_id]
    chat_end = processor.tokenizer.get_vocab().get('<|im_end|>')
    if chat_end is not None:
        stop_tokens.append(chat_end)
    with torch.inference_mode():
        output = model.generate(
            **inputs, max_new_tokens=192, do_sample=False, repetition_penalty=1.2,
            eos_token_id=stop_tokens,
            pad_token_id=processor.tokenizer.pad_token_id,
        )
    answer = output[:, inputs['input_ids'].shape[1]:]
    print(processor.batch_decode(answer, skip_special_tokens=True)[0].strip())


if __name__ == '__main__':
    main()

実際に再現した初回実行の問題

KamilaMila/FastVLM-0.5B、Transformers 5.0.0、timm 1.0.29 で確認したケースです。共有重みの修正はこの古い変換モデル向けです。

ロードできるが回答が文字化けする

lm_head.weight の欠落を確認。この変換は text_config にのみ共有重み設定があり、Transformers 5.0.0 では外側にも設定が必要です。ロード前に設定します。

KamilaMila/FastVLM-0.5B · Transformers 5.0.0
config = AutoConfig.from_pretrained(model_id)
if model_id == "KamilaMila/FastVLM-0.5B":
    config.tie_word_embeddings = config.text_config.tie_word_embeddings
model = FastVlmForConditionalGeneration.from_pretrained(
    model_id, config=config, dtype=dtype
)

回答が繰り返す・次のターンを生成する

endoftext に加え、Qwen の im_end があれば終了トークンに含めます。生成長を制限し入力以降のみデコード。反復ペナルティは正確さを保証しません。

timm や FastVlmForConditionalGeneration がない

同じ Python 環境に依存を入れてください。画像側に timm が必要で、古い Transformers にはネイティブクラスがない場合があります。

Same environment
python -m pip install "transformers==5.0.0" "timm==1.0.29" torch pillow
python -c "import sys, transformers, timm; print(sys.executable, transformers.__version__, timm.__version__)"

モデル取得が止まる

空き容量と接続を確認。検証中の Xet 停止は HF_HUB_DISABLE_XET=1 による HTTP 取得で解消しましたが、全ネットワーク問題への解決策ではありません。

macOS / Linux · retry
HF_HUB_DISABLE_XET=1 python fastvlm_transformers.py image.png

2026年9月12日、完全なスクリプトで合成レシートの $15.00 を確認。他の画像や環境は別途確認してください。

一次情報で確認

API、モデルファイル、依存バージョンは変わる可能性があります。このページを実装マップとして使い、リンク先の公式文書で現在のコマンドとライセンスを確認してください。

公式ソースを開く