実行前の準備
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 を使用します。
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." 最初の結果を確認
画像を image.png として保存して実行。成功すると生成された回答のみが表示されます。画像と質問に対応するか確認してください。
トラブルシューティング
- ImportError:Transformers 5.0.0 を入れた環境か確認。
- ダウンロード失敗:Hugging Face 接続とディスクを確認。
- メモリ不足:0.5B を使い、他の GPU 処理を終了して出力を短縮。
- 質問が回答に混入:input_ids 以降の生成トークンのみデコード。
2026年9月12日出典確認。性能は実行端末に依存します。
手順
- 1
FastVLM 対応版 Transformers をインストールします。
- 2
互換モデルと AutoProcessor を読み込みます。
- 3
image と text を分けたメッセージを構築します。
- 4
generate 前に apply_chat_template を使用します。単純な文字列だけでは動作しません。
例
"""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 では外側にも設定が必要です。ロード前に設定します。
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 にはネイティブクラスがない場合があります。
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 取得で解消しましたが、全ネットワーク問題への解決策ではありません。
HF_HUB_DISABLE_XET=1 python fastvlm_transformers.py image.png 2026年9月12日、完全なスクリプトで合成レシートの $15.00 を確認。他の画像や環境は別途確認してください。