Skip to content

docs: Update Llava guide to PyTorch backend with Qwen2.5-VL - #160

Open
faradawn wants to merge 1 commit into
triton-inference-server:mainfrom
faradawn:docs-llava-qwen3vl
Open

docs: Update Llava guide to PyTorch backend with Qwen2.5-VL#160
faradawn wants to merge 1 commit into
triton-inference-server:mainfrom
faradawn:docs-llava-qwen3vl

Conversation

@faradawn

@faradawn faradawn commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

Rewrite the multimodal deployment tutorial to use the TensorRT-LLM PyTorch backend (LLM API) instead of the deprecated TensorRT engine-build workflow, and update the example model from Llava-1.5-7B to Qwen2.5-VL-7B-Instruct. The guide now configures the model through model.yaml and serves it directly without building separate visual and LLM engines, and points to the multimodal LLM API docs for image request formatting.

@greptile-apps

greptile-apps Bot commented Jul 22, 2026

Copy link
Copy Markdown

Greptile Summary

This PR rewrites the Llava1.5 TensorRT-LLM deployment guide to use the modern PyTorch/LLM API backend with Qwen2.5-VL-7B-Instruct, replacing the deprecated trtllm-build + visual engine workflow. The guide is significantly shorter and simpler as a result.

  • Removes the multi-engine build flow (trtllm-build, build_visual_engine.py, fill_template.py) in favor of a single model.yaml config pointing directly at a HuggingFace checkpoint.
  • Replaces the old Llava1.5 model with Qwen2.5-VL-7B-Instruct and updates the inference request example to the Triton generate endpoint.
  • Defers the multimodal (image+text) request format to external documentation links rather than providing an inline example.

Confidence Score: 4/5

Documentation-only change that simplifies the deployment workflow; two concrete usability gaps need addressing before this guides users successfully end-to-end.

The HF_TOKEN is never wired into the container, silently breaking downloads for gated models. The model.yaml snippet gives no indication of whether it replaces the file or patches existing keys, risking loss of required default configuration.

Popular_Models_Guide/Llava1.5/llava_trtllm_guide.md — the docker run command and the model.yaml edit instruction both need clarification.

Important Files Changed

Filename Overview
Popular_Models_Guide/Llava1.5/llava_trtllm_guide.md Tutorial rewritten to use PyTorch/LLM API backend; HF_TOKEN propagation into the container is not handled, and the model.yaml snippet is ambiguous about whether it is a full-file replacement or a targeted field update.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Host: docker run with HF cache mount] --> B[Interactive container session]
    B --> C[git clone TensorRT-LLM]
    C --> D[Edit model.yaml\nmodel: Qwen/Qwen2.5-VL-7B-Instruct\nbackend: pytorch]
    D --> E[launch_triton_server.py\n--model_repo=.../llmapi/]
    E --> F{Server Ready?}
    F -->|Yes| G[curl /v2/models/tensorrt_llm/generate\ntext-only prompt]
    F -->|No| H[Check logs]
    G --> I[For image+text: see external docs]
Loading

Reviews (2): Last reviewed commit: "docs: Update Llava guide to PyTorch back..." | Re-trigger Greptile

Comment on lines 56 to 93
```bash
docker run --rm -it --net host --shm-size=2g \
--ulimit memlock=-1 --ulimit stack=67108864 --gpus all \
-v </path/to/tensorrtllm_backend>:/tensorrtllm_backend \
-v </path/to/Llava1.5/repo>:/llava-1.5-7b-hf \
-v </path/to/engines>:/engines \
-v </path/to/tutorials>:/tutorials \
-v ~/.cache/huggingface:/root/.cache/huggingface \
nvcr.io/nvidia/tritonserver:<xx.yy>-trtllm-python-py3
```

Alternatively, you can follow instructions
[here](https://github.com/triton-inference-server/tensorrtllm_backend/blob/main/docs/build.md#build-the-docker-container)
to build Triton Server with Tensorrt-LLM Backend if you want
to build a specialized container.

Don't forget to allow gpu usage when you launch the container.

### Create Engines for each model [skip this step if you already have engines]

TensorRT-LLM requires each model to be compiled for the configuration
you need before running. To do so, before you run your model for the first time
on Triton Server you will need to create a TensorRT-LLM engine.
For gated models, set your token first: `export HF_TOKEN=hf_...`

Starting with [24.04 release](https://github.com/triton-inference-server/server/releases/tag/v2.45.0),
Triton Server TensrRT-LLM container comes with
pre-installed TensorRT-LLM package, which allows users to build engines inside
the Triton container.

Llava1.5 requires 2 engines: a TensorRT engine for visual components,
and a TRT-LLM engine for the language components. This tutorial bases on 24.05
release, which corresponds to `v0.9.0` version of TensorRT-LLM and
TensorRT-LLM backend and follows [this](https://github.com/NVIDIA/TensorRT-LLM/tree/v0.9.0/examples/multimodal#llava-and-vila)
TensorRT-LLM multi-modal guide.

To generate engines, simply follow the next steps:
## Prepare the model repository

```bash
HF_LLAVA_MODEL=/llava-1.5-7b-hf
UNIFIED_CKPT_PATH=/tmp/ckpt/llava/7b/
ENGINE_DIR=/engines/llava1.5
CONVERT_CHKPT_SCRIPT=/tensorrtllm_backend/tensorrt_llm/examples/llama/convert_checkpoint.py
python3 ${CONVERT_CHKPT_SCRIPT} --model_dir ${HF_LLAVA_MODEL} --output_dir ${UNIFIED_CKPT_PATH} --dtype float16
trtllm-build --checkpoint_dir ${UNIFIED_CKPT_PATH} \
--output_dir ${ENGINE_DIR} \
--gemm_plugin float16 \
--use_fused_mlp \
--max_batch_size 1 \
--max_input_len 2048 \
--max_output_len 512 \
--max_multimodal_len 576 # 1 (max_batch_size) * 576 (num_visual_features)

python /tensorrtllm_backend/tensorrt_llm/examples/multimodal/build_visual_engine.py --model_path ${HF_LLAVA_MODEL} --model_type llava --output_dir ${ENGINE_DIR}
git clone https://github.com/NVIDIA/TensorRT-LLM.git
```

Edit `TensorRT-LLM/triton_backend/all_models/llmapi/tensorrt_llm/1/model.yaml`
and set the model:

> Optional: You can check test the output of the model with `run.py`
> located in the same llama examples folder.
>
> ```bash
> python3 /tensorrtllm_backend/tensorrt_llm/examples/multimodal/run.py --max_new_tokens 30 --hf_model_dir ${HF_LLAVA_MODEL} --visual_engine_dir ${ENGINE_DIR} --llm_engine_dir ${ENGINE_DIR} --decoder_llm --input_text "Question: which city is this? Answer:"
> ```
> You should expect the following response:
> ```
> [TensorRT-LLM] TensorRT-LLM version: 0.9.0
> ...
> [06/18/2024-01:02:24] [TRT-LLM] [I] ---------------------------------------------------------
> [06/18/2024-01:02:24] [TRT-LLM] [I]
> [Q] Question: which city is this? Answer:
> [06/18/2024-01:02:24] [TRT-LLM] [I]
> [A] ['Singapore']
> [06/18/2024-01:02:24] [TRT-LLM] [I] Generated 1 tokens
> [06/18/2024-01:02:24] [TRT-LLM] [I] ---------------------------------------------------------
> ```

### Serving with Triton
```yaml
model: Qwen/Qwen3-VL-8B-Instruct
backend: pytorch
```

The last step is to set up a Triton model repository. For this tutorial,
we provide all necessary Triton related files under `model_repository/`.
You simply need to provide TensorRT-LLM engine location in its `config.pbtxt`:
All keys in `model.yaml` map directly to the
[`LLM()` constructor arguments](https://nvidia.github.io/TensorRT-LLM/llm-api/) —
this is where you configure KV cache, parallelism, and more. You can also point
`model` at a local filesystem path if you have pre-downloaded the checkpoint.

```bash
FILL_TEMPLATE_SCRIPT=/tensorrtllm_backend/tools/fill_template.py
python3 ${FILL_TEMPLATE_SCRIPT} -i /tutorials/Popular_Models_Guide/Llava1.5/model_repository/tensorrt_llm/config.pbtxt engine_dir:${ENGINE_DIR}
```
## Serving with Triton

3. Launch Tritonserver
Launch Triton Server with the
[launch_triton_server.py](https://github.com/NVIDIA/TensorRT-LLM/blob/main/triton_backend/scripts/launch_triton_server.py)
script, running from the parent of `TensorRT-LLM/`:

Use the [launch_triton_server.py](https://github.com/triton-inference-server/tensorrtllm_backend/blob/release/0.5.0/scripts/launch_triton_server.py) script. This launches multiple instances of `tritonserver` with MPI.
```bash
export TRT_ENGINE_LOCATION="/engines/llava1.5/visual_encoder.engine"
export HF_LOCATION="/llava-1.5-7b-hf"
python3 /tensorrtllm_backend/scripts/launch_triton_server.py --world_size=<world size of the engine> --model_repo=/tutorials/Popular_Models_Guide/Llava1.5/model_repository
python3 TensorRT-LLM/triton_backend/scripts/launch_triton_server.py \
--model_repo=TensorRT-LLM/triton_backend/all_models/llmapi/
```

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Missing volume mount breaks the workflow

The docker run command mounts only ~/.cache/huggingface, but the subsequent steps require access to the cloned TensorRT-LLM/ directory. If users follow the natural reading (clone on the host, then run Triton inside the container), the TensorRT-LLM/ path will not exist inside the container and the launch_triton_server.py command will fail. If the intent is to clone inside the running container, the guide should say so explicitly — but the --rm flag means the clone is discarded on container exit, making the workflow non-reproducible across sessions. A -v /path/to/TensorRT-LLM:/TensorRT-LLM mount (matching the git clone location on the host) needs to be added to the docker run command, or the guide must explicitly state that steps 2–4 are all performed inside a single interactive container session.

Comment on lines 67 to 69
```bash
HF_LLAVA_MODEL=/llava-1.5-7b-hf
UNIFIED_CKPT_PATH=/tmp/ckpt/llava/7b/
ENGINE_DIR=/engines/llava1.5
CONVERT_CHKPT_SCRIPT=/tensorrtllm_backend/tensorrt_llm/examples/llama/convert_checkpoint.py
python3 ${CONVERT_CHKPT_SCRIPT} --model_dir ${HF_LLAVA_MODEL} --output_dir ${UNIFIED_CKPT_PATH} --dtype float16
trtllm-build --checkpoint_dir ${UNIFIED_CKPT_PATH} \
--output_dir ${ENGINE_DIR} \
--gemm_plugin float16 \
--use_fused_mlp \
--max_batch_size 1 \
--max_input_len 2048 \
--max_output_len 512 \
--max_multimodal_len 576 # 1 (max_batch_size) * 576 (num_visual_features)

python /tensorrtllm_backend/tensorrt_llm/examples/multimodal/build_visual_engine.py --model_path ${HF_LLAVA_MODEL} --model_type llava --output_dir ${ENGINE_DIR}
git clone https://github.com/NVIDIA/TensorRT-LLM.git
```

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Unversioned git clone risks reproducibility

Cloning from main without a branch or tag pin means the directory layout (triton_backend/all_models/llmapi/, triton_backend/scripts/launch_triton_server.py) and the model.yaml schema could change at any commit, silently breaking the tutorial. Adding --branch <release-tag> (e.g. the same tag that matches the <xx.yy> container version) would make the guide self-consistent and reproducible.

Comment thread Popular_Models_Guide/Llava1.5/llava_trtllm_guide.md
@faradawn
faradawn force-pushed the docs-llava-qwen3vl branch from b10f542 to 352fb52 Compare July 22, 2026 21:01
@faradawn faradawn changed the title docs: Update Llava guide to PyTorch backend with Qwen3-VL docs: Update Llava guide to PyTorch backend with Qwen2.5-VL Jul 22, 2026
Signed-off-by: Faradawn Yang <73060648+faradawn@users.noreply.github.com>
@faradawn
faradawn force-pushed the docs-llava-qwen3vl branch from 352fb52 to 1f6f1cd Compare July 22, 2026 21:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant