Hugging Face's logo

Transformers documentation

Qwen3-VL

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

このモデルは2025年2月19日にHF papersで公開され、2025年9月15日にHugging Face Transformersに貢献されました。

FlashAttention SDPA

Qwen3-VL

Qwen3-VL は、Dense 型と MoE 型、さらに Instruct 版と Thinking 版を含む、マルチモーダルなビジョン・言語モデルシリーズです。先行モデルを基盤としつつ、純粋なテキスト処理能力を維持したまま、視覚理解能力を大幅に向上させています。主なアーキテクチャ上の進歩としては、空間・時間モデリングの向上を目的としたインターリーブ配置を備えた MRope の強化、Vision Transformer (ViT) 由来の多層特徴量を効果的に活用するための DeepStack の統合、そしてテキストベースの時間アラインメントによる動画理解の改善（T-RoPE からテキストタイムスタンプアラインメントへの移行による、より正確な時間的グラウンディングの実現）が挙げられます。これらの革新により、Qwen3-VL は複雑なマルチモーダルタスクにおいて優れたパフォーマンスを発揮します。

use_kernels=True を from_pretrained() に設定すると、対応するレイヤーが Hub からの最適化されたカーネルに置き換えられます。詳細は カーネルの読み込み を参照してください。

モデルの使用方法

AutoModel
from transformers import AutoProcessor, Qwen3VLForConditionalGeneration


model = Qwen3VLForConditionalGeneration.from_pretrained(
    "Qwen/Qwen3-VL",
    device_map="auto",
    attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained("Qwen/Qwen3-VL")
messages = [
    {
        "role":"user",
        "content":[
            {
                "type":"image",
                "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
            },
            {
                "type":"text",
                "text":"Describe this image."
            }
        ]
    }

]

inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt",
)
inputs.pop("token_type_ids", None)

generated_ids = model.generate(**inputs, max_new_tokens=128)
generated_ids_trimmed = [
            out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
]
output_text = processor.batch_decode(
       generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
)
print(output_text)

Qwen3VLConfig

クラス transformers.Qwen3VLConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneimage_token_id: int = 151655video_token_id: int = 151656vision_start_token_id: int = 151652vision_end_token_id: int = 151653tie_word_embeddings: bool = False )

パラメータ

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig]、省略可) — テキストバックボーンの設定オブジェクトまたは辞書。
  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig]、任意) — ビジョンバックボーンの config オブジェクトまたは辞書です。
  • image_token_id (int、任意、デフォルトは 151655) — 入力画像のプレースホルダーとして使用される画像トークンのインデックスです。
  • video_token_id (int、任意、デフォルトは 151656) — 入力動画のプレースホルダーとして使用される動画トークンのインデックスです。
  • vision_start_token_id (int、任意、デフォルトは 151652) — マルチモーダル入力シーケンスにおける視覚セグメントの開始を示すトークン ID。
  • vision_end_token_id (int、任意、デフォルトは 151653) — マルチモーダル入力シーケンスにおける視覚セグメントの終了を示すトークン ID。
  • tie_word_embeddings (bool、任意、デフォルトは False) — モデルの tied_weights_keys マッピングに従って重み埋め込みを共有するかどうかを指定します。

これは Qwen3VLModel の設定を保存するための設定クラスです。指定された引数に基づいて Qwen3 Vl モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、Qwen/Qwen3-VL-4B-Instruct と同様の設定が得られます。

設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。

例:

>>> from transformers import Qwen3VLForConditionalGeneration, Qwen3VLConfig

>>> # Initializing a Qwen3-VL style configuration
>>> configuration = Qwen3VLConfig()

>>> # Initializing a model from the Qwen3-VL-4B style configuration
>>> model = Qwen3VLForConditionalGeneration(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

Qwen3VLVisionConfig

class transformers.Qwen3VLVisionConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonedepth: int = 27hidden_size: int = 1152hidden_act: str = 'gelu_pytorch_tanh'intermediate_size: int = 4304num_heads: int = 16in_channels: int = 3patch_size: int | list[int] | tuple[int, int] = 16spatial_merge_size: int = 2temporal_patch_size: int | list[int] | tuple[int, int] = 2out_hidden_size: int = 3584num_position_embeddings: int = 2304deepstack_visual_indexes: list[int] | tuple[int, ...] = (8, 16, 24)initializer_range: float = 0.02rope_parameters: dict | None = None )

パラメータ

  • depth (int、任意、デフォルトは 27) — ビジョンエンコーダーにおける Transformer レイヤーの数。
  • hidden_size (int、任意、デフォルトは 1152) — 隠れ表現の次元数。
  • hidden_act (str、任意、デフォルトは gelu_pytorch_tanh) — デコーダーで使用する非線形活性化関数（関数または文字列）です。例えば、"gelu"、 "relu"、"silu" などです。
  • intermediate_size (int、任意、デフォルトは 4304) — MLP 表現の次元数。
  • num_heads (int、任意、デフォルトは16) — Transformerデコーダーの各アテンション層におけるアテンションヘッドの数。
  • in_channels (int、任意、デフォルトは3) — 入力チャネル数。
  • patch_size (Union[int, list[int], tuple[int, int]]、任意、デフォルトは16) — 各パッチのサイズ（解像度）です。
  • spatial_merge_size (int, 省略可、デフォルトは 2) — 隣接するパッチをマージしてビジュアルトークンの数を削減するために使用される、空間マージウィンドウのサイズです。
  • temporal_patch_size (Union[int, list[int], tuple[int, int]]、任意、デフォルトは 2) — 動画入力における3Dパッチ埋め込みで使用する時間方向のパッチサイズ。
  • out_hidden_size (int, 任意、デフォルトは 3584) — ビジョンモデルの出力隠れ層サイズです。
  • num_position_embeddings (int、任意、デフォルト値は 2304) — このモデルが使用される可能性のある最大シーケンス長
  • deepstack_visual_indexes (list[int]、任意、デフォルトは [8, 16, 24]) — deepstack 埋め込み用のレイヤーのインデックスです。
  • initializer_range (float、任意、デフォルトは 0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。
  • rope_parameters (dict, 任意) — RoPE 埋め込みの設定パラメータを含む辞書です。辞書には rope_theta の値が含まれており、より長い max_position_embeddings で RoPE を使用する場合、スケーリングに使用されるパラメータが任意で含まれます。

これは Qwen3VLModel の設定を保存するための設定クラスです。指定された引数に基づいて Qwen3 Vl モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、Qwen/Qwen3-VL-4B-Instruct と同様の設定が得られます。

設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。

Qwen3VLTextConfig

class transformers.Qwen3VLTextConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 151936hidden_size: int = 4096intermediate_size: int = 22016num_hidden_layers: int = 32num_attention_heads: int = 32num_key_value_heads: int | None = 32head_dim: int = 128hidden_act: str = 'silu'max_position_embeddings: int = 128000initializer_range: float = 0.02rms_norm_eps: float = 1e-06use_cache: bool = Truerope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: float | int = 0.0pad_token_id: int | None = None )

パラメータ

  • vocab_size (int、任意、デフォルトは 151936) — モデルの語彙サイズです。input_ids で表現できるトークンの種類数を定義します。
  • hidden_size (int、任意、デフォルトは 4096) — 隠れ表現の次元数。
  • intermediate_size (int、任意、デフォルトは 22016) — MLP 表現の次元数。
  • num_hidden_layers (int、任意、デフォルトは 32) — Transformer デコーダーの隠れ層の数。
  • num_attention_heads (int、任意、デフォルトは 32) — Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。
  • num_key_value_heads (int、任意、デフォルトは32) — Grouped Query Attention の実装に使用する key_value ヘッドの数を指定します。 num_key_value_heads=num_attention_heads の場合、モデルは Multi Head Attention (MHA) を使用し、 num_key_value_heads=1 の場合は Multi Query Attention (MQA) を使用し、それ以外の場合は GQA が使用されます。 マルチヘッドのチェックポイントを GQA チェックポイントに変換する際は、各グループの key ヘッドと value ヘッドは、そのグループ内の元のすべてのヘッドを平均プーリングして構築する必要があります。詳細については、この論文を参照してください。指定しない場合、デフォルトで num_attention_heads が使用されます。
  • head_dim (int、任意、デフォルトは128) — アテンションヘッドの次元です。None の場合、hidden_size // num_attention_heads がデフォルトとして使用されます。
  • hidden_act (str、任意、デフォルトは silu) — デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、"gelu"、 "relu"、"silu" など。
  • max_position_embeddings (int、任意、デフォルトは 128000) — このモデルが使用される可能性のある最大シーケンス長です。
  • initializer_range (float、任意、デフォルトは 0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。
  • rms_norm_eps (float、任意、デフォルトは 1e-06) — RMS 正規化レイヤーで使用する epsilon。
  • use_cache (bool、任意、デフォルトは True) — モデルが最後のキー/バリューの注意を返すかどうか（すべてのモデルで利用されるわけではありません）。config.is_decoder=True の場合、またはモデルがデコーダー専用の生成モデルである場合にのみ関連します。
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], 省略可) — RoPE 埋め込みの設定パラメータを含む辞書です。この辞書には rope_theta の値が含まれており、より長い max_position_embeddings で RoPE を使用する場合にスケーリングに使用されるパラメータが任意で含まれます。
  • attention_bias (bool、任意、デフォルトはFalse) — 自己注意機構において、クエリ、キー、バリュー、出力の投影層にバイアスを使用するかどうかを指定します。
  • attention_dropout (Union[float, int]、任意、デフォルトは 0.0) — アテンション確率のドロップアウト率です。
  • pad_token_id (int, 任意) — 語彙内でパディングに使用されるトークン ID。

これは Qwen3VLModel の設定を保存するための設定クラスです。指定された引数に基づいて Qwen3 Vl モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、Qwen/Qwen3-VL-4B-Instruct と同様の設定が得られます。

設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。

例:

>>> from transformers import Qwen3VLTextModel, Qwen3VLTextConfig

>>> # Initializing a Qwen3VL style configuration
>>> configuration = Qwen3VLTextConfig()

>>> # Initializing a model from the Qwen3-VL-7B style configuration
>>> model = Qwen3VLTextModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

Qwen3VLProcessor

クラス transformers.Qwen3VLProcessor

< >

( image_processor = Nonetokenizer = Nonevideo_processor = Nonechat_template = None**kwargs )

パラメータ

  • image_processor (Qwen2VLImageProcessor) — 画像プロセッサは必須の入力です。
  • tokenizer (Qwen2Tokenizer) — トークナイザーは必須の入力です。
  • video_processor (Qwen3VLVideoProcessor) — ビデオプロセッサは必須の入力です。
  • chat_template (str) — チャット内のメッセージのリストをトークン化可能な文字列に変換するための Jinja テンプレート。

画像プロセッサ、トークナイザ、および動画プロセッサを単一のプロセッサにラップするQwen3VLProcessorを構築します。

Qwen3VLProcessor は、Qwen2VLImageProcessor、Qwen2Tokenizer、および Qwen3VLVideoProcessor のすべての機能を提供します。詳細については、~Qwen2VLImageProcessor、~Qwen2Tokenizer、および ~Qwen3VLVideoProcessor を参照してください。

__call__

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

パラメータ

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], 任意) — 前処理対象の画像です。ピクセル値が 0 から 255 の範囲にある単一の画像またはバッチを想定しています。ピクセル値が 0 から 1 の範囲にある画像を渡す場合は、do_rescale=False を設定してください。
  • text (Union[str, list[str], list[list[str]]]、省略可) — エンコード対象のシーケンスまたはシーケンスのバッチです。各シーケンスは文字列、または文字列のリスト（事前トークン化済み文字列）であることができます。事前トークン化済みの入力を渡す場合は、バッチ入力との曖昧さを避けるために is_split_into_words=True を設定してください。
  • videos (Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]], 任意) — 前処理を行う動画です。ピクセル値が 0 から 255 の範囲にある、単一の動画またはバッチの動画を想定しています。ピクセル値が 0 から 1 の範囲にある動画を渡す場合は、do_rescale=False を設定してください。
  • audio (Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], 任意) — 準備対象のオーディオまたはオーディオのバッチです。各オーディオは NumPy 配列または PyTorch テンソルであることができます。 NumPy 配列/PyTorch テンソルの場合、各オーディオの形状は (C, T) である必要があります。ここで C はチャネル数、T はオーディオのサンプル長です。
  • return_tensors (str または TensorType, 省略可) — 設定すると、特定のフレームワークのテンソルを返します。使用可能な値は以下の通りです:
    • 'pt': PyTorchのtorch.Tensorオブジェクトを返します。
    • 'np': NumPyのnp.ndarrayオブジェクトを返します。
  • **kwargs (ProcessingKwargs、任意) — 各モダリティ（テキスト、画像、動画、音声）の追加処理オプション。モデル固有のパラメータは上記にリストされています。サポートされている引数の完全なリストについては、TypedDictクラスを参照してください。

Qwen3VLVideoProcessor

class transformers.Qwen3VLVideoProcessor

< >

( **kwargs: *<class 'transformers.models.qwen3_vl.video_processing_qwen3_vl.Qwen3VLVideoProcessorInitKwargs'> )

パラメータ

  • **kwargs (Qwen3VLVideoProcessorInitKwargs、任意) — テキスト、画像、動画、音声の各モダリティに対する追加の処理オプションです。モデル固有のパラメータは上記にリストされています。サポートされている引数の完全なリストについては、TypedDict クラスを参照してください。

Qwen3VLVideoProcessorの動画プロセッサを構築します。

get_num_of_video_patches

< >

( num_frames: intheight: intwidth: intvideos_kwargs = None ) → int

パラメータ

  • num_frames (int) — 入力動画のフレーム数。
  • height (int) — 入力動画の高さ。
  • width (int) — 入力動画の幅。
  • videos_kwargs (dict, 省略可) — 動画プロセッサのデフォルト値を上書きするための任意のキーワード引数。

戻り値

int

1つの動画あたりの動画パッチの数。

指定された動画サイズに対する動画パッチの数を返すユーティリティです。

patchify

< >

( videos: torch.Tensorpatch_size: intmerge_size: inttemporal_patch_size: int )

各動画を(seq_len, patch_dim)の形状のフラットなレイアウトにパッチ化し、動的な形状のピクセルを連結できるようにします。

リサイズ

< >

( videos: torch.Tensorsize: SizeDictresample: PILImageResampling | tvF.InterpolationMode | int | Nonefactor: inttemporal_factor: intcap_pixels_per_frame: bool | None = None**kwargs )

入力動画のアスペクト比に基づいて動的にリサイズします。

sample_frames

< >

( metadata: VideoMetadatanum_frames: int | None = Nonefps: int | float | None = None**kwargs ) → np.ndarray

パラメータ

  • video (torch.Tensor) — サンプリングが必要な動画。
  • metadata (VideoMetadata) — 総再生時間、fps、総フレーム数などの情報が含まれる動画のメタデータ。
  • num_frames (int, 任意) — サンプリングするフレームの最大数。デフォルトは self.num_frames です。
  • fps (int または float、省略可) — 1 秒あたりにサンプリングするターゲットフレーム数。デフォルトは self.fps です。

戻り値

np.ndarray

サンプリングされた動画フレーム。

0から総フレーム数までの範囲で、指定されたフレーム数を均等にサンプリングするデフォルトのサンプリング関数です。メタデータとともにfpsが渡された場合、fpsフレーム/秒で均等にサンプリングされます。引数num_framesとfpsは排他的です。

Qwen3VLVisionModel

class transformers.Qwen3VLVisionModel

< >

( config: Qwen3VLVisionConfig*inputs**kwargs )

forward

< >

( hidden_states: Tensorgrid_thw: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → torch.Tensor

パラメータ

  • hidden_states (torch.Tensor、形状 (seq_len, hidden_size)) — モデルの最終的な隠れ状態です。
  • grid_thw (torch.Tensor、形状 (num_images_or_videos, 3)) — LLM における各画像のフィーチャー形状の時間軸、高さ、幅です。

戻り値

torch.Tensor

hidden_states

Qwen3VLTextModel

class transformers.Qwen3VLTextModel

< >

( config: Qwen3VLTextConfig )

パラメータ

  • config (Qwen3VLTextConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

Qwen3VLのテキスト部分は、DeepStackが視覚特徴を初期の隠れ状態に統合するため、純粋なテキスト専用モデルではありません。

このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Noneuse_cache: bool | None = Nonevisual_pos_masks: typing.Optional[torch.Tensor] = Nonedeepstack_visual_embeds: list[torch.Tensor] | None = None**kwargs: *<class 'transformers.modeling_flash_attention_utils.FlashAttentionKwargs'> ) → BaseModelOutputWithPast or tuple(torch.FloatTensor)

パラメータ

  • input_ids (torch.LongTensor の形状 (batch_size, sequence_length), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。

    インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。

    入力IDとは何ですか？

  • attention_mask (torch.Tensor の形状 (batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。 [0, 1]:
    • マスクされていないトークンに対して1
    • マスクされたトークンに対しては 0 です。

    アテンションマスクとは?

  • position_ids (torch.LongTensor の形状 (batch_size, sequence_length), 、任意) — 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックス。範囲 [0, config.n_positions - 1].

    ポジションIDとは?

  • past_key_values (~cache_utils.Cache, 省略可) — 逐次デコードを高速化するために使用できる、事前計算された隠れ状態(自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー)。通常、これはデコードの以前の段階でモデルが返した past_key_values であり、 use_cache=True または config.use_cache=True.

    入力として許可されるのは Cache インスタンスのみです。kv cache ガイドを参照してください。 past_key_values が渡されない場合、デフォルトで DynamicCache が初期化されます。

    モデルは、入力として与えられたのと同じキャッシュ形式を出力します。

    past_key_values を使用する場合、すべての input_ids（形状 (batch_size, sequence_length)）ではなく、このモデルに過去のキー・バリュー状態が与えられていない未処理の input_ids（形状 (batch_size, unprocessed_length)）のみを入力することになります。

  • inputs_embeds (torch.FloatTensor、形状 (batch_size, sequence_length, hidden_size)、任意) — input_ids を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込みルックアップ行列よりも、input_ids のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。
  • use_cache (bool、任意) — True に設定すると、past_key_values のキーバリュー状態が返され、デコーディングの高速化に利用できます（past_key_values を参照）。
  • visual_pos_masks (torch.Tensor、形状 (batch_size, seqlen)、任意) — ビジュアル位置のマスクです。
  • deepstack_visual_embeds (list[torch.Tensor]、任意) — DeepStack による視覚埋め込みです。形状は (num_layers, visual_seqlen, embed_dim) です。 この特徴量は、異なる視覚エンコーダー層から抽出され、デコーダーの隠れ状態に与えられます。 論文 DeepStack(https://arxiv.org/abs/2406.04334) に基づいています。

戻り値

BaseModelOutputWithPast または tuple(torch.FloatTensor)

torch.FloatTensor のタプル（return_dict=False が渡された場合、または config.return_dict=False の場合）、または BaseModelOutputWithPast。設定（Qwen3VLConfig）や入力に応じて、さまざまな要素で構成されます。

Qwen3VLTextModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなくModuleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。

  • last_hidden_state (torch.FloatTensor、shape (batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。

    past_key_valuesが使用されている場合、出力されるのは、形状(batch_size, 1, hidden_size)のシーケンスの最後の隠れ状態のみです。

  • past_key_values (Cache、任意、use_cache=True が渡された場合または config.use_cache=True の場合に返されます) — Cache のインスタンスです。詳細については、kv cache ガイドを参照してください。

    自己アテンションブロック（および config.is_encoder_decoder=True の場合、クロスカレンションブロック）の事前計算済みヒドゥンステート（キーとバリュー）を保持します。これらは逐次デコーディングを高速化するために使用できます（past_key_values 入力参照）。

  • hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます)— torch.FloatTensor のタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は (batch_size, sequence_length, hidden_size) です。

    各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

  • attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル（各レイヤーごとに1つ）、形状は (batch_size, num_heads, sequence_length, sequence_length)。

    アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

Qwen3VLModel

クラス transformers.Qwen3VLModel

< >

( config: Qwen3VLConfig )

パラメータ

  • config (Qwen3VLConfig) — モデルのすべてのパラメータを含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連付けられた重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

Qwen3 Vlのベースモデルで、特定のヘッドを上に載せず、生のhidden-statesを出力します。

このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

forward

< >

( input_ids: LongTensor = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.FloatTensor] = Noneimage_grid_thw: typing.Optional[torch.LongTensor] = Nonevideo_grid_thw: typing.Optional[torch.LongTensor] = Nonemm_token_type_ids: typing.Optional[torch.IntTensor] = Nonemm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Qwen3VLModelOutputWithPast or tuple(torch.FloatTensor)

パラメータ

  • input_ids (torch.LongTensor の形状 (batch_size, sequence_length), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。

    インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。

    入力IDとは何ですか？

  • attention_mask (torch.Tensor の形状 (batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。 [0, 1]:
    • マスクされていないトークンに対して1
    • マスクされたトークンに対しては 0 です。

    アテンションマスクとは?

  • position_ids (torch.LongTensor の形状 (batch_size, sequence_length), 、任意) — 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックス。範囲 [0, config.n_positions - 1].

    ポジションIDとは?

  • past_key_values (~cache_utils.Cache, 省略可) — 逐次デコードを高速化するために使用できる、事前計算された隠れ状態(自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー)。通常、これはデコードの以前の段階でモデルが返した past_key_values であり、 use_cache=True または config.use_cache=True.

    入力として許可されるのは Cache インスタンスのみです。kv cache ガイドを参照してください。 past_key_values が渡されない場合、デフォルトで DynamicCache が初期化されます。

    モデルは、入力として与えられたのと同じキャッシュ形式を出力します。

    past_key_values を使用する場合、すべての input_ids（形状 (batch_size, sequence_length)）ではなく、このモデルに過去のキー・バリュー状態が与えられていない未処理の input_ids（形状 (batch_size, unprocessed_length)）のみを入力することになります。

  • inputs_embeds (torch.FloatTensor、形状 (batch_size, sequence_length, hidden_size)、任意) — input_ids を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込みルックアップ行列よりも、input_ids のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。
  • pixel_values (torch.Tensor、形状 (batch_size, num_channels, image_size, image_size)、任意) — 入力画像に対応するテンソルです。ピクセル値は Qwen2VLImageProcessor を使用して取得できます。詳細は Qwen2VLImageProcessor.call() を参照してください（Qwen3VLProcessor は画像の処理に Qwen2VLImageProcessor を使用します）。
  • pixel_values_videos (torch.FloatTensor、形状 (batch_size, num_frames, num_channels, frame_size, frame_size)、任意) — 入力動画に対応するテンソルです。動画のピクセル値は、Qwen3VLVideoProcessor を使用して取得できます。詳細については、Qwen3VLVideoProcessor.call() を参照してください（Qwen3VLProcessor は動画の処理に Qwen3VLVideoProcessor を使用します）。
  • image_grid_thw (torch.LongTensor、形状 (num_images, 3)、任意) — LLM における各画像のフィーチャー形状の時間軸、高さ、幅です。
  • video_grid_thw (torch.LongTensor、形状 (num_videos, 3)、任意) — LLM における各動画のフィーチャー形状の時間軸、高さ、幅です。
  • mm_token_type_ids (torch.IntTensor、形状 (batch_size, sequence_length)、任意) — 各モダリティに一致する入力シーケンスのトークンインデックスです。例えば、テキスト (0)、画像 (1)、動画 (2) などです。マルチモーダルなトークンタイプIDは、AutoProcessor を使用して取得できます。詳細は ProcessorMixin.call() を参照してください。
  • mm_encoder_outputs (dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 省略可) — キーがサポートされているモダリティ、値がそのモダリティのエンコード済み出力である辞書。各エンコード済み出力は、(pooler_output, 省略可: last_hidden_states, 省略可: hidden_states, 省略可: attentions) pooler_output (形状 (batch_size, sequence_length, hidden_size), 省略可) からなるタプルです。pooler_output は、エンコーダーのマルチモーダル特徴量をテキスト埋め込みにマージしたシーケンスです。

戻り値

Qwen3VLModelOutputWithPast または tuple(torch.FloatTensor)

Qwen3VLModelOutputWithPast または、torch.FloatTensor のタプル（return_dict=False が渡された場合、または config.return_dict=False の場合）。設定（Qwen3VLConfig）や入力に応じて、さまざまな要素で構成されます。

Qwen3VLModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなくModuleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。

  • last_hidden_state (torch.FloatTensor、shape (batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。

    past_key_valuesが使用されている場合、出力されるのは、形状(batch_size, 1, hidden_size)のシーケンスの最後の隠れ状態のみです。

  • past_key_values (Cache、任意、use_cache=True が渡された場合または config.use_cache=True の場合に返されます) — Cache のインスタンスです。詳細については、kv cache ガイドを参照してください。

    自己アテンションブロック（および config.is_encoder_decoder=True の場合、クロスカレンションブロック）の事前計算済みヒドゥンステート（キーとバリュー）を保持します。これらは逐次デコーディングを高速化するために使用できます（past_key_values 入力参照）。

  • hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます)— torch.FloatTensor のタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は (batch_size, sequence_length, hidden_size) です。

    各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

  • attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル（各レイヤーごとに1つ）、形状は (batch_size, num_heads, sequence_length, sequence_length)。

    アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

  • rope_deltas (torch.LongTensor、形状 (batch_size, )、任意) — シーケンス長とマルチモーダル rope の間の rope インデックスの差分です。 この属性は非推奨であり、v5.20 で削除されます。代わりに model.base_model.rope_deltas を使用してください。

get_video_features

< >

( pixel_values_videos: FloatTensorvideo_grid_thw: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithDeepstackFeatures or tuple(torch.FloatTensor)

パラメータ

  • pixel_values_videos (torch.FloatTensor、形状 (batch_size, num_frames, num_channels, frame_size, frame_size)) — 入力動画に対応するテンソルです。動画のピクセル値は、Qwen3VLVideoProcessor を使用して取得できます。詳細については、Qwen3VLVideoProcessor.call() を参照してください（Qwen3VLProcessor は、動画の処理に Qwen3VLVideoProcessor を使用します）。
  • video_grid_thw (torch.LongTensor、形状 (num_videos, 3)、任意) — LLM における各動画のフィーチャー形状の時間軸、高さ、幅です。

戻り値

BaseModelOutputWithDeepstackFeatures または tuple(torch.FloatTensor)

BaseModelOutputWithDeepstackFeatures、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（Qwen3VLConfig）や入力に応じて、さまざまな要素で構成されます。

  • last_hidden_state (torch.FloatTensor、shape (batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。

  • pooler_output (torch.FloatTensor、shape (batch_size, hidden_size)) — 補助事前学習タスクに使用される層をさらに通して処理された後、シーケンスの最初のトークン（分類トークン）の最終層の隠れ状態。例えば、BERT 系のモデルでは、線形層と tanh 活性化関数を経て処理された後の分類トークンを返します。この線形層の重みは、事前学習中の次文予測（分類）目的から学習されます。

  • hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます)— torch.FloatTensor のタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は (batch_size, sequence_length, hidden_size) です。

    各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

  • attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル（各レイヤーごとに1つ）、形状は (batch_size, num_heads, sequence_length, sequence_length)。

    アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

  • deepstack_features (List[torch.FloatTensor], 任意) — deepstack 層からの隠れ状態(特徴マップ)のリスト。

get_image_features

< >

( pixel_values: FloatTensorimage_grid_thw: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithDeepstackFeatures or tuple(torch.FloatTensor)

パラメータ

  • pixel_values (torch.FloatTensor、形状 (batch_size, num_channels, image_size, image_size)) — 入力画像に対応するテンソルです。ピクセル値は Qwen2VLImageProcessor を使用して取得できます。詳細は Qwen2VLImageProcessor.call() を参照してください（Qwen3VLProcessor は画像処理に Qwen2VLImageProcessor を使用します）。
  • image_grid_thw (torch.LongTensor、形状 (num_images, 3)、任意) — LLM における各画像のフィーチャー形状の時間軸、高さ、幅です。

戻り値

BaseModelOutputWithDeepstackFeatures または tuple(torch.FloatTensor)

BaseModelOutputWithDeepstackFeatures、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（Qwen3VLConfig）や入力に応じて、さまざまな要素で構成されます。

  • last_hidden_state (torch.FloatTensor、shape (batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。

  • pooler_output (torch.FloatTensor、shape (batch_size, hidden_size)) — 補助事前学習タスクに使用される層をさらに通して処理された後、シーケンスの最初のトークン（分類トークン）の最終層の隠れ状態。例えば、BERT 系のモデルでは、線形層と tanh 活性化関数を経て処理された後の分類トークンを返します。この線形層の重みは、事前学習中の次文予測（分類）目的から学習されます。

  • hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます)— torch.FloatTensor のタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は (batch_size, sequence_length, hidden_size) です。

    各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

  • attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル（各レイヤーごとに1つ）、形状は (batch_size, num_heads, sequence_length, sequence_length)。

    アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

  • deepstack_features (List[torch.FloatTensor], 任意) — deepstack 層からの隠れ状態(特徴マップ)のリスト。

Qwen3VLForConditionalGeneration

クラス transformers.Qwen3VLForConditionalGeneration

< >

( config: Qwen3VLConfig )

forward

< >

( input_ids: LongTensor = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Nonelabels: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.FloatTensor] = Noneimage_grid_thw: typing.Optional[torch.LongTensor] = Nonevideo_grid_thw: typing.Optional[torch.LongTensor] = Nonemm_token_type_ids: typing.Optional[torch.IntTensor] = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Qwen3VLCausalLMOutputWithPast or tuple(torch.FloatTensor)

パラメータ

  • input_ids (torch.LongTensor の形状 (batch_size, sequence_length), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。

    インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。

    入力IDとは何ですか？

  • attention_mask (torch.Tensor の形状 (batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。 [0, 1]:
    • マスクされていないトークンに対して1
    • マスクされたトークンに対しては 0 です。

    アテンションマスクとは?

  • position_ids (torch.LongTensor の形状 (batch_size, sequence_length), 、任意) — 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックス。範囲 [0, config.n_positions - 1].

    ポジションIDとは?

  • past_key_values (~cache_utils.Cache, 省略可) — 逐次デコードを高速化するために使用できる、事前計算された隠れ状態(自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー)。通常、これはデコードの以前の段階でモデルが返した past_key_values であり、 use_cache=True または config.use_cache=True.

    入力として許可されるのは Cache インスタンスのみです。kv cache ガイドを参照してください。 past_key_values が渡されない場合、デフォルトで DynamicCache が初期化されます。

    モデルは、入力として与えられたのと同じキャッシュ形式を出力します。

    past_key_values を使用する場合、すべての input_ids（形状 (batch_size, sequence_length)）ではなく、このモデルに過去のキー・バリュー状態が与えられていない未処理の input_ids（形状 (batch_size, unprocessed_length)）のみを入力することになります。

  • inputs_embeds (torch.FloatTensor、形状 (batch_size, sequence_length, hidden_size)、任意) — input_ids を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込みルックアップ行列よりも、input_ids のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。
  • labels (torch.LongTensor、shape (batch_size, sequence_length)、任意) — マスク言語モデリング損失を計算するためのラベルです。インデックスは [0, ..., config.vocab_size] の範囲内であるか、-100 である必要があります（input_ids の docstring を参照）。インデックスが -100 に設定されたトークンは無視（マスク）され、損失は [0, ..., config.vocab_size] の範囲内のラベルを持つトークンに対してのみ計算されます。
  • pixel_values (torch.Tensor、形状 (batch_size, num_channels, image_size, image_size)、任意) — 入力画像に対応するテンソルです。ピクセル値は Qwen2VLImageProcessor を使用して取得できます。詳細は Qwen2VLImageProcessor.call() を参照してください（Qwen3VLProcessor は画像の処理に Qwen2VLImageProcessor を使用します）。
  • pixel_values_videos (torch.FloatTensor、形状 (batch_size, num_frames, num_channels, frame_size, frame_size)、任意) — 入力動画に対応するテンソルです。動画のピクセル値は、Qwen3VLVideoProcessor を使用して取得できます。詳細については、Qwen3VLVideoProcessor.call() を参照してください（Qwen3VLProcessor は動画の処理に Qwen3VLVideoProcessor を使用します）。
  • image_grid_thw (torch.LongTensor、形状 (num_images, 3)、任意) — LLM における各画像のフィーチャー形状の時間軸、高さ、幅です。
  • video_grid_thw (torch.LongTensor、形状 (num_videos, 3)、任意) — LLM における各動画のフィーチャー形状の時間軸、高さ、幅です。
  • mm_token_type_ids (torch.IntTensor、形状 (batch_size, sequence_length)、任意) — 各モダリティに一致する入力シーケンスのトークンインデックスです。例えば、テキスト (0)、画像 (1)、動画 (2) などです。マルチモーダルなトークンタイプIDは、AutoProcessor を使用して取得できます。詳細は ProcessorMixin.call() を参照してください。
  • logits_to_keep (Union[int, torch.Tensor]、省略可、デフォルトは 0) — int の場合、最後の logits_to_keep トークンについて logits を計算します。0 の場合、すべての input_ids について logits を計算します（特殊ケース）。生成には最後のトークンの logits だけで十分であり、そのトークンのみについて計算することでメモリを節約できます。これは、長いシーケンスや大規模な語彙サイズの場合に特に顕著な効果があります。 torch.Tensor の場合、シーケンス長次元で保持するインデックスに対応する 1 次元テンソルである必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめた形式）を使用する場合に有用です。
  • mm_encoder_outputs (dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 省略可) — キーがサポートされているモダリティ、値がそのモダリティのエンコード済み出力である辞書。各エンコード済み出力は、(pooler_output, 省略可: last_hidden_states, 省略可: hidden_states, 省略可: attentions) pooler_output (形状 (batch_size, sequence_length, hidden_size), 省略可) からなるタプルです。pooler_output は、エンコーダーのマルチモーダル特徴量をテキスト埋め込みにマージしたシーケンスです。

戻り値

Qwen3VLCausalLMOutputWithPast または tuple(torch.FloatTensor)

Qwen3VLCausalLMOutputWithPast または、return_dict=False が渡された場合、または config.return_dict=False の場合に torch.FloatTensor のタプル。設定 (Qwen3VLConfig) および入力に応じて、さまざまな要素で構成されます。

Qwen3VLForConditionalGenerationのforwardメソッドは、__call__特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなくModuleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。

  • loss (torch.FloatTensor、shape (1,)、optional、labels が指定された場合に返されます) — 言語モデリングの損失（次のトークン予測用）。

  • logits (torch.FloatTensor、shape (batch_size, sequence_length, config.vocab_size)) — 言語モデリングヘッドの予測スコア（SoftMax 適用前の各語彙トークンのスコア）。

  • past_key_values (Cache、任意、use_cache=True が渡された場合または config.use_cache=True の場合に返されます) — Cache のインスタンスです。詳細については、kv cache ガイドを参照してください。

    逐次デコーディングを高速化するために使用できる（past_key_values 入力参照）、事前計算済みの隠れ状態（自己注意ブロックのキーとバリュー）が含まれます。

  • hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます)— torch.FloatTensor のタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は (batch_size, sequence_length, hidden_size) です。

    各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

  • attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル（各レイヤーごとに1つ）、形状は (batch_size, num_heads, sequence_length, sequence_length)。

    アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

  • rope_deltas (torch.LongTensor、形状 (batch_size, )、任意) — シーケンス長とマルチモーダル rope の間の rope インデックスの差分です。 この属性は非推奨であり、v5.20 で削除されます。代わりに model.base_model.rope_deltas を使用してください。

例:

>>> from transformers import AutoProcessor, Qwen3VLForConditionalGeneration

>>> model = Qwen3VLForConditionalGeneration.from_pretrained("Qwen/Qwen3-VL-8B-Instruct")
>>> processor = AutoProcessor.from_pretrained("Qwen/Qwen3-VL-8B-Instruct")

>>> messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg",
            },
            {"type": "text", "text": "Describe the image."},
        ],
    }
]

>>> inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt"
)

>>> # Generate
>>> generated_ids = model.generate(**inputs, max_new_tokens=1024)
>>> generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
>>> output_text = processor.batch_decode(generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
>>> print(output_text)

get_video_features

< >

( pixel_values_videos: FloatTensorvideo_grid_thw: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithDeepstackFeatures or tuple(torch.FloatTensor)

パラメータ

  • pixel_values_videos (torch.FloatTensor、形状 (batch_size, num_channels, image_size, image_size)) — 入力動画に対応するテンソルです。
  • video_grid_thw (torch.LongTensor、形状 (num_videos, 3)、任意) — LLM における各動画のフィーチャー形状の時間軸、高さ、幅です。

戻り値

BaseModelOutputWithDeepstackFeatures または tuple(torch.FloatTensor)

BaseModelOutputWithDeepstackFeatures、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（Qwen3VLConfig）や入力に応じて、さまざまな要素で構成されます。

  • last_hidden_state (torch.FloatTensor、shape (batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。

  • pooler_output (torch.FloatTensor、shape (batch_size, hidden_size)) — 補助事前学習タスクに使用される層をさらに通して処理された後、シーケンスの最初のトークン（分類トークン）の最終層の隠れ状態。例えば、BERT 系のモデルでは、線形層と tanh 活性化関数を経て処理された後の分類トークンを返します。この線形層の重みは、事前学習中の次文予測（分類）目的から学習されます。

  • hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます)— torch.FloatTensor のタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は (batch_size, sequence_length, hidden_size) です。

    各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

  • attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル（各レイヤーごとに1つ）、形状は (batch_size, num_heads, sequence_length, sequence_length)。

    アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

  • deepstack_features (List[torch.FloatTensor], 任意) — deepstack 層からの隠れ状態(特徴マップ)のリスト。

例:

>>> from PIL import Image
>>> from transformers import AutoProcessor, Qwen3VLForConditionalGeneration

>>> model = Qwen3VLForConditionalGeneration.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
>>> processor = AutoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")

>>> messages = [
...     {
...         "role": "user", "content": [
...             {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
...             {"type": "text", "text": "Where is the cat standing?"},
...         ]
...     },
... ]

>>> inputs = processor.apply_chat_template(
...     messages,
...     tokenize=True,
...     return_dict=True,
...     return_tensors="pt",
...     add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]

get_image_features

< >

( pixel_values: FloatTensorimage_grid_thw: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithDeepstackFeatures or tuple(torch.FloatTensor)

パラメータ

  • pixel_values (torch.FloatTensor、形状 (batch_size, num_channels, image_size, image_size)) — 入力画像に対応するテンソルです。
  • image_grid_thw (torch.LongTensor、形状 (num_images, 3)、任意) — LLM における各画像のフィーチャー形状の時間軸、高さ、幅です。

戻り値

BaseModelOutputWithDeepstackFeatures または tuple(torch.FloatTensor)

BaseModelOutputWithDeepstackFeatures、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（Qwen3VLConfig）や入力に応じて、さまざまな要素で構成されます。

  • last_hidden_state (torch.FloatTensor、shape (batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。

  • pooler_output (torch.FloatTensor、shape (batch_size, hidden_size)) — 補助事前学習タスクに使用される層をさらに通して処理された後、シーケンスの最初のトークン（分類トークン）の最終層の隠れ状態。例えば、BERT 系のモデルでは、線形層と tanh 活性化関数を経て処理された後の分類トークンを返します。この線形層の重みは、事前学習中の次文予測（分類）目的から学習されます。

  • hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます)— torch.FloatTensor のタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は (batch_size, sequence_length, hidden_size) です。

    各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

  • attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル（各レイヤーごとに1つ）、形状は (batch_size, num_heads, sequence_length, sequence_length)。

    アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

  • deepstack_features (List[torch.FloatTensor], 任意) — deepstack 層からの隠れ状態(特徴マップ)のリスト。

例:

>>> from PIL import Image
>>> from transformers import AutoProcessor, Qwen3VLForConditionalGeneration

>>> model = Qwen3VLForConditionalGeneration.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
>>> processor = AutoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")

>>> messages = [
...     {
...         "role": "user", "content": [
...             {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
...             {"type": "text", "text": "Where is the cat standing?"},
...         ]
...     },
... ]

>>> inputs = processor.apply_chat_template(
...     messages,
...     tokenize=True,
...     return_dict=True,
...     return_tensors="pt",
...     add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]
Update on GitHub

←Qwen3-Omni-MoE Qwen3VLMoe→