> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liquid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LFM3-VL-2B

> 2B vision-language model with video understanding, thinking, and spatial reasoning for on-device deployment

[← Back to Vision Models](https://docs.liquid.ai/lfm/models/vision-models.md)

LFM3-VL-2B is a vision-language model in the LFM3 family designed for on-device deployment. It processes text, images, and videos at their native resolution, and pairs the LFM3 language backbone with a new in-house Liquid hybrid convolution/attention vision encoder. It is the first LFM vision model to take video as input, and it reasons step by step before answering.

[HF](https://huggingface.co/LiquidAI/LFM3-VL-2B)
[GGUF](https://huggingface.co/LiquidAI/LFM3-VL-2B-GGUF)
[MLX](https://huggingface.co/LiquidAI/LFM3-VL-2B-MLX-8bit)
[ONNX](https://huggingface.co/LiquidAI/LFM3-VL-2B-ONNX)

## Specifications

| Property | Value |
| - | - |
| Parameters | 2B (1.73B language model + 164M vision encoder + 25M projector) |
| Architecture | LFM3-VL — LFM3 backbone + Liquid hybrid vision encoder, 14 layers (8 gated depthwise 2D convolution + 6 bidirectional attention) |
| Context Length | 128K tokens |
| Languages | English, Arabic, Chinese, French, German, Italian, Japanese, Korean, Portuguese, Spanish, Vietnamese, Thai, Indonesian, Hindi, Russian, Polish |
| Vocabulary Size | 128K |
| Generation Parameters | `temperature=0.1`, `top_k=50`, `repetition_penalty=1.1` |
| License | [LFM Open License v1.0](https://docs.liquid.ai/lfm/help/model-license.md) |

> **Video Understanding**
>
> Questions about recorded lectures, phone walkthroughs, and camera clips

> **Thinking**
>
> Step-by-step reasoning for math, charts, and multi-step visual questions

> **Spatial & Embodied Reasoning**
>
> Object localization and spatial relationships for robotics applications

## Quick Start

**Transformers**

**Install:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install "transformers>=5.21.0" torch torchvision pillow
```

**Download & Run:**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import torch
from transformers import AutoModelForImageTextToText, AutoProcessor

model_id = "LiquidAI/LFM3-VL-2B"

model = AutoModelForImageTextToText.from_pretrained(model_id, dtype=torch.bfloat16, device_map="auto", trust_remote_code=True)
processor = AutoProcessor.from_pretrained(model_id, trust_remote_code=True)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "http://images.cocodataset.org/val2017/000000039769.jpg"},
            {"type": "text", "text": "Describe this image."},
        ],
    }
]

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

with torch.inference_mode():
    output_ids = model.generate(
        **inputs,
        do_sample=True,
        temperature=0.1,
        top_k=50,
        repetition_penalty=1.1,
        max_new_tokens=16384,
    )

generated_ids = output_ids[:, inputs["input_ids"].shape[1] :]
print(processor.batch_decode(generated_ids, skip_special_tokens=True)[0])
```

**vLLM**

Requires a vLLM build with LFM3-VL support.

**Launch server:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
vllm serve LiquidAI/LFM3-VL-2B \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice --tool-call-parser qwen3_coder \
  --chat-template-content-format openai \
  --structured-outputs-config '{"backend": "xgrammar", "disable_any_whitespace": true}' \
  --media-io-kwargs '{"video": {"video_backend": "qwen3_vl"}}'
```

**Query (OpenAI-compatible):**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

response = client.chat.completions.create(
    model="LiquidAI/LFM3-VL-2B",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": "http://images.cocodataset.org/val2017/000000039769.jpg"}},
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
    temperature=0.1,
    extra_body={"top_k": 50, "repetition_penalty": 1.1},
)
print(response.choices[0].message.content)
```

**SGLang**

Requires an SGLang build with LFM3-VL support.

**Launch server:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sglang serve --model-path LiquidAI/LFM3-VL-2B \
  --reasoning-parser qwen3 \
  --tool-call-parser qwen3_coder \
  --constrained-json-disable-any-whitespace \
  --host 0.0.0.0 --port 30000
```

**Query (OpenAI-compatible):**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI

client = OpenAI(base_url="http://localhost:30000/v1", api_key="None")

response = client.chat.completions.create(
    model="LiquidAI/LFM3-VL-2B",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": "http://images.cocodataset.org/val2017/000000039769.jpg"}},
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
    temperature=0.1,
    extra_body={"top_k": 50, "repetition_penalty": 1.1},
)
print(response.choices[0].message.content)
```

**llama.cpp**

Requires a llama.cpp build with LFM3-VL support.

**Install:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
brew install llama.cpp
```

**Start the server:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
llama-server \
  -hf LiquidAI/LFM3-VL-2B-GGUF:Q4_0 \
  --temp 0.1 --top-p 1.0 --top-k 50 --min-p 0.0 --repeat-penalty 1.1 \
  --no-reasoning-preserve --port 8080
```

With `-hf`, llama.cpp downloads the model and the matching vision projector (mmproj). The server is OpenAI-compatible, so you can query it with the vLLM example above by changing `base_url` to `http://localhost:8080/v1`. To chat in the terminal, use `llama-cli` with the same flags, then type `/image <path>` to add an image to the chat.

For advanced usage, see the [llama.cpp guide](https://docs.liquid.ai/deployment/on-device/llama-cpp.md#vision-models).

## Reasoning

LFM3-VL-2B thinks in a `<think>` block before it answers. Reasoning can be long, so allow up to 16,384 new tokens. See [Chat Template](https://docs.liquid.ai/lfm/key-concepts/chat-template.md) and [Tool Use](https://docs.liquid.ai/lfm/key-concepts/tool-use.md) for the message format.

## Video Input

Images and videos are processed at their native resolution, and every 2×2 block of patches is merged into one language token. Videos are sampled at 2 fps, consecutive frames are paired, and each frame is prefixed with its timestamp. See [Vision Capabilities](https://docs.liquid.ai/lfm/key-concepts/vision-capabilities.md#video-understanding) for a video example.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.