trtllm-serve#
About#
The trtllm-serve
command starts an OpenAI compatible server that supports the following endpoints:
/v1/models
/v1/completions
/v1/chat/completions
For information about the inference endpoints, refer to the OpenAI API Reference.
The server also supports the following endpoints:
/health
/metrics
/version
The metrics
endpoint provides runtime-iteration statistics such as GPU memory use and inflight-batching details.
Starting a Server#
The following abbreviated command syntax shows the commonly used arguments to start a server:
trtllm-serve <model> [--tp_size <tp> --pp_size <pp> --ep_size <ep> --host <host> --port <port>]
For the full syntax and argument descriptions, refer to Syntax.
Inference Endpoints#
After you start the server, you can send inference requests through completions API and Chat API, which are compatible with corresponding OpenAI APIs. We use TinyLlama-1.1B-Chat-v1.0 for examples in the following sections.
Chat API#
You can query Chat API with any http clients, a typical example is OpenAI Python client:
Another example uses curl
:
Completions API#
You can query Completions API with any http clients, a typical example is OpenAI Python client:
Another example uses curl
:
Multimodal Serving#
For multimodal models, you need to create a configuration file and start the server with additional options due to the following limitations:
TRT-LLM multimodal is currently not compatible with
kv_cache_reuse
Multimodal models require
chat_template
, so only the Chat API is supported
To set up multimodal models:
First, create a configuration file:
cat >./extra-llm-api-config.yml<<EOF
kv_cache_config:
enable_block_reuse: false
EOF
Then, start the server with the configuration file:
trtllm-serve Qwen/Qwen2-VL-7B-Instruct \
--extra_llm_api_options ./extra-llm-api-config.yml
Multimodal Chat API#
You can query Completions API with any http clients, a typical example is OpenAI Python client:
Another example uses curl
:
Multimodal Modality Coverage#
TRT-LLM multimodal supports the following modalities and data types (depending on the model):
Text
No type specified:
{"role": "user", "content": "What's the capital of South Korea?"}
Explicit “text” type:
{"role": "user", "content": [{"type": "text", "text": "What's the capital of South Korea?"}]}
Image
Using “image_url” with URL:
{"role": "user", "content": [ {"type": "text", "text": "What's in this image?"}, {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}} ]}
Using “image_url” with base64-encoded data:
{"role": "user", "content": [ {"type": "text", "text": "What's in this image?"}, {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,{image_base64}"}} ]}
Note
To convert images to base64-encoded format, use the utility function
tensorrt_llm.utils.load_base64_image()
. Refer to the
load_base64_image utility
for implementation details.
Video
Using “video_url”:
{"role": "user", "content": [ {"type": "text", "text": "What's in this video?"}, {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}} ]}
Audio
Using “audio_url”:
{"role": "user", "content": [ {"type": "text", "text": "What's in this audio?"}, {"type": "audio_url", "audio_url": {"url": "https://example.com/audio.mp3"}} ]}
Multi-node Serving with Slurm#
You can deploy DeepSeek-V3 model across two nodes with Slurm and trtllm-serve
echo -e "enable_attention_dp: true\npytorch_backend_config:\n enable_overlap_scheduler: true" > extra-llm-api-config.yml
srun -N 2 -w [NODES] \
--output=benchmark_2node.log \
--ntasks 16 --ntasks-per-node=8 \
--mpi=pmix --gres=gpu:8 \
--container-image=<CONTAINER_IMG> \
--container-mounts=/workspace:/workspace \
--container-workdir /workspace \
bash -c "trtllm-llmapi-launch trtllm-serve deepseek-ai/DeepSeek-V3 --max_batch_size 161 --max_num_tokens 1160 --tp_size 16 --ep_size 4 --kv_cache_free_gpu_memory_fraction 0.95 --extra_llm_api_options ./extra-llm-api-config.yml"
See the source code of trtllm-llmapi-launch
for more details.
Metrics Endpoint#
Note
This endpoint is beta maturity.
The statistics for the PyTorch backend are beta and not as comprehensive as those for the TensorRT backend.
Some fields, such as CPU memory usage, are not available for the PyTorch backend.
Enabling enable_iter_perf_stats
in the PyTorch backend can impact performance slightly, depending on the serving configuration.
The /metrics
endpoint provides runtime-iteration statistics such as GPU memory use and inflight-batching details.
For the TensorRT backend, these statistics are enabled by default.
However, for the PyTorch backend, you must explicitly enable iteration statistics logging by setting the enable_iter_perf_stats field in a YAML configuration file as shown in the following example:
# extra-llm-api-config.yml
pytorch_backend_config:
enable_iter_perf_stats: true
Then start the server and specify the --extra_llm_api_options
argument with the path to the YAML file as shown in the following example:
trtllm-serve <model> \
--extra_llm_api_options <path-to-extra-llm-api-config.yml> \
[--tp_size <tp> --pp_size <pp> --ep_size <ep> --host <host> --port <port>]
After at least one inference request is sent to the server, you can fetch the runtime-iteration statistics by polling the /metrics endpoint:
curl -X GET http://<host>:<port>/metrics
Example Output
[
{
"gpuMemUsage": 56401920000,
"inflightBatchingStats": {
...
},
"iter": 1,
"iterLatencyMS": 16.505143404006958,
"kvCacheStats": {
...
},
"newActiveRequestsQueueLatencyMS": 0.0007503032684326172
}
]
Syntax#
trtllm-serve#
trtllm-serve [OPTIONS] COMMAND [ARGS]...
disaggregated#
Running server in disaggregated mode
trtllm-serve disaggregated [OPTIONS]
Options
- -c, --config_file <config_file>#
Specific option for disaggregated mode.
- -m, --metadata_server_config_file <metadata_server_config_file>#
Path to metadata server config file
- -t, --server_start_timeout <server_start_timeout>#
Server start timeout
- -r, --request_timeout <request_timeout>#
Request timeout
- -l, --log_level <log_level>#
The logging level.
- Options:
internal_error | error | warning | info | verbose | debug | trace
disaggregated_mpi_worker#
Launching disaggregated MPI worker
trtllm-serve disaggregated_mpi_worker [OPTIONS]
Options
- -c, --config_file <config_file>#
Specific option for disaggregated mode.
- --log_level <log_level>#
The logging level.
- Options:
internal_error | error | warning | info | verbose | debug | trace
serve#
Running an OpenAI API compatible server
MODEL: model name | HF checkpoint path | TensorRT engine path
trtllm-serve serve [OPTIONS] MODEL
Options
- --tokenizer <tokenizer>#
Path | Name of the tokenizer.Specify this value only if using TensorRT engine as model.
- --host <host>#
Hostname of the server.
- --port <port>#
Port of the server.
- --backend <backend>#
Set to ‘pytorch’ for pytorch path. Default is cpp path.
- Options:
pytorch | trt
- --log_level <log_level>#
The logging level.
- Options:
internal_error | error | warning | info | verbose | debug | trace
- --max_beam_width <max_beam_width>#
Maximum number of beams for beam search decoding.
- --max_batch_size <max_batch_size>#
Maximum number of requests that the engine can schedule.
- --max_num_tokens <max_num_tokens>#
Maximum number of batched input tokens after padding is removed in each batch.
- --max_seq_len <max_seq_len>#
Maximum total length of one request, including prompt and outputs. If unspecified, the value is deduced from the model config.
- --tp_size <tp_size>#
Tensor parallelism size.
- --pp_size <pp_size>#
Pipeline parallelism size.
- --ep_size <ep_size>#
expert parallelism size
- --cluster_size <cluster_size>#
expert cluster parallelism size
- --gpus_per_node <gpus_per_node>#
Number of GPUs per node. Default to None, and it will be detected automatically.
- --kv_cache_free_gpu_memory_fraction <kv_cache_free_gpu_memory_fraction>#
Free GPU memory fraction reserved for KV Cache, after allocating model weights and buffers.
- --num_postprocess_workers <num_postprocess_workers>#
[Experimental] Number of workers to postprocess raw responses to comply with OpenAI protocol.
- --trust_remote_code#
Flag for HF transformers.
- --extra_llm_api_options <extra_llm_api_options>#
Path to a YAML file that overwrites the parameters specified by trtllm-serve.
- --reasoning_parser <reasoning_parser>#
[Experimental] Specify the parser for reasoning models.
- Options:
deepseek-r1
- --metadata_server_config_file <metadata_server_config_file>#
Path to metadata server config file
- --server_role <server_role>#
Server role. Specify this value only if running in disaggregated mode.
- --fail_fast_on_attention_window_too_large#
Exit with runtime error when attention window is too large to fit even a single sequence in the KV cache.
Arguments
- MODEL#
Required argument
Besides the above examples, trtllm-serve is also used as an entrypoint for performance benchmarking. Please refer to Performance Benchmarking with `trtllm-serve <NVIDIA/TensorRT-LLM>` for more details.