LibreVLM

LibreVLMは任意のvlm追加機能として提供されます。新しいバージョンのtransformersと、一部のプロセッサに必要なヘルパーがインストールされます。この追加機能がない状態でVLMファミリーをインポートすると、このページを案内するImportErrorが発生します。

1
pip install 'libreyolo[vlm]'

重みは初回使用時にHugging Face Hubからローカルのweights/フォルダーへダウンロードされます。一部のファミリーはOSI非承認のライセンスで提供され、ダウンロード前に一度だけ通知をログに記録します。大きなバックエンドにはGPUを推奨しますが、すべてのモデルはdevice="cpu"を指定してCPUでも実行できます。

モデルを構築し、対象とする単語を宣言して、推論します。デフォルトのバックエンドは、ティア内で最も強力な検出器でApache-2.0ライセンスのQwen3-VL-4Bです。

1
from libreyolo import LibreVLM
2
3
# Qwen3-VL-4B by default; weights autodownload on first use
4
model = LibreVLM()
5
6
# The vocabulary is just words. Any words.
7
model.set_classes(["pink car", "wheel"])
8
9
result = model.predict("street.jpg")
10
11
print(result.boxes.xyxy)   # pixel [x1, y1, x2, y2]
12
print(result.boxes.cls)    # ids into ["pink car", "wheel"]
13
result.plot()              # same drawing helpers as any LibreYOLO model
14
result.save("out.jpg")

これが処理の全体です。predict()以降はすべて通常の検出器と同様に動作するため、既存の可視化、切り抜き、追跡コードをそのまま使えます。

LibreVLM(...)に渡すエイリアスでバックエンドを選びます。サイズを付けずにファミリー名だけを指定すると、デフォルトサイズに解決されます。全体のデフォルトバックエンドはqwen3-vl-4bです。実際に最も強力な検出器はQwen3-VL、LFM2-VL、Florence-2です。

バックエンドの選択

• 最高品質：qwen3-vl-8bまたはqwen3-vl-4b（デフォルト）。
• 正確なボックス、小さなフットプリント：florence-2-large。
• エッジ・CPU：lfm2-vl-450mまたはsmolvlm2-500m。
• 完全に寛容なライセンス：任意のサイズのQwen3-VL、SmolVLM2、Florence-2、Kosmos-2。

語彙はオープンボキャブラリ検出の中心です。ラベル文字列のリストを指定してset_classes()を呼び出します。この設定は保持されます。再設定するまで、以降のすべてのpredict()とtrack()の呼び出しに引き継がれます。selfを返すため、メソッドチェーンにできます。

1
# Sticky and chainable
2
model = LibreVLM("qwen3-vl-2b").set_classes(["person", "dog", "cat"])
3
4
# Set it once at construction instead
5
model = LibreVLM("lfm2-vl-450m", names=["boat"], device="cpu")
6
7
# Re-set any time to change what you are looking for
8
model.set_classes(["a red car", "a blue truck"])

ラベルには任意のフレーズを使えます。大文字と小文字を区別せず一意である必要があり、単一の文字列ではなくリストを渡す必要があります。set_classes()を一度も呼び出さない場合、モデルはCOCO-80語彙にフォールバックするため、引数なしのpredict()でも妥当な処理を行います。

predict()（および同等のmodel(...)呼び出し）は、ほかのLibreYOLO検出器と同じ入力形式（パス、PIL画像、numpy配列、URL、フォルダー、動画）を受け付けます。stream=Trueとtrack()も利用できます。

1
result = model.predict(
2
    source="image.jpg",  # path | PIL | ndarray | URL | folder | video
3
    conf=0.25,           # see note below: scoring is synthetic
4
    classes=[0],         # optional: keep only these vocabulary ids
5
    max_det=300,
6
)

戻り値の形状

クローズドボキャブラリ検出器と同じ、標準のResultsオブジェクトが返されます：

内部では、LibreVLMがモデル出力を寛容に解析し（Markdownフェンス、余分な文章、重複したボックス、途中で切れた配列に対応）、自由形式のラベルをクラスIDに戻し、語彙にないラベルを除外します。この最後の手順により、自由形式の生成モデルをクローズドセット検出器のように動作させます。

特定の色の物体を検出

1
from libreyolo import LibreVLM
2
3
model = LibreVLM("qwen3-vl-4b")
4
model.set_classes(["red car"])
5
6
result = model.predict("parking_lot.jpg")
7
print(f"Found {len(result.boxes.cls)} red car(s)")
8
result.save("red_cars.jpg")

Florence-2で正確なボックスを取得

1
# Florence-2 is a purpose-built grounder: very tight pixel boxes.
2
model = LibreVLM("florence-2-large")
3
model.set_classes(["a red car", "license plate"])
4
5
result = model.predict("car.jpg")
6
result.plot()

実行時に単一クラスへ絞り込み

1
model = LibreVLM("qwen3-vl-2b").set_classes(["person", "dog", "cat"])
2
3
# classes= filters the configured vocabulary by id
4
people_only = model.predict("street.jpg", classes=[0])

内蔵サンプル画像をCPUで実行

1
from libreyolo import LibreVLM, SAMPLE_IMAGE
2
3
model = LibreVLM("lfm2-vl-450m", device="cpu")
4
# No set_classes() -> falls back to the COCO-80 vocabulary
5
result = model.predict(SAMPLE_IMAGE)
6
print(model.names[result.boxes.cls[0]])  # e.g. "person"

バッチ、フォルダー、動画

1
model = LibreVLM().set_classes(["forklift", "pallet"])
2
3
# A whole folder
4
for result in model.predict("warehouse_frames/", stream=True):
5
    result.save()
6
7
# A video file (frames are processed one at a time)
8
model.predict("warehouse.mp4", save=True)

検出器ではなくモデル自体が必要な場合もあります。チャットテンプレートファミリーはchat()を提供し、画像と自由形式のプロンプトを受け取り、デコードしたテキストをそのまま返します。計数、キャプション作成、簡単な画像質問に使えます。

1
model = LibreVLM("qwen3-vl-4b")
2
3
answer = model.chat("harbor.jpg", "How many boats are docked? Answer with a number.")
4
print(answer)

すべてのファミリーが同じResultsを返しますが、そこに至る方法は異なります。通常は気にする必要はありませんが、一部のバックエンドがそのように動作する理由を理解するのに役立ちます。チャットファミリーにはボックスのJSON配列を出力するよう指示し、グラウンディングモデルは専用のタスクトークンを使います。

チャットファミリーでは、コンストラクタのprompt=引数で検出プロンプトを上書きし、max_new_tokens=で生成長の上限を設定できます。デバイスとdtypeは自動的に解決されます。CUDAではbf16またはfp16、CPUではfp32です。

LibreVLMは強力ですが、まだ新しい機能です。事前に制約を把握しておけば、後から驚かずに済みます。

• 合成信頼度。すべてのボックスのスコアは1.0です。そのため、conf=フィルターは実際のしきい値ではなく、全件を通すか全件を除外するかの動作になります。
• mAP・検証は非対応。合成スコアではCOCO mAPが誤解を招くため、val()は例外を発生させます。
• 学習・エクスポートは非対応。train()とexport()は例外を発生させます。代わりにアップストリームでVLMをファインチューニングし、得られた重みを読み込んでください。
• 追跡性能は低下。track()は動作しますが、スコアが均一なため、トラッカーの低信頼度復元段階は機能しません。
• 一度に1枚の画像。v1では生成を逐次実行するため、batch=の値を大きくしても高速化しません。
• Python APIのみ。libreyolo CLIはまだVLMエイリアスを解決できません。