Skip to content

vLLM

Installation

You need to install the vllm library to use the vLLM integration. See the installation section for instructions to install vLLM for CPU or ROCm.

Load the model

Outlines supports models available via vLLM's offline batched inference interface. You can load a model using:

from outlines import models

model = models.vllm("microsoft/Phi-3-mini-4k-instruct")

Or alternatively:

import vllm
from outlines import models

llm = vllm.LLM("microsoft/Phi-3-mini-4k-instruct")
model = models.VLLM(llm)

Models are loaded from the HuggingFace hub.

Device

The default installation of vLLM only allows to load models on GPU. See the installation instructions to run models on CPU.

You can pass any parameter that you would normally pass to vllm.LLM, as keyword arguments:

from outlines import models

model = models.vllm(
    "microsoft/Phi-3-mini-4k-instruct",
    trust_remote_code=True,
    gpu_memory_utilization=0.7
)

Main parameters:

Parameters Type Description Default
tokenizer_mode str "auto" will use the fast tokenizer if available and "slow" will always use the slow tokenizer. auto
trust_remote_code bool Trust remote code when downloading the model and tokenizer. False
tensor_parallel_size int The number of GPUs to use for distributed execution with tensor parallelism. 1
dtype str The data type for the model weights and activations. Currently, we support float32, float16, and bfloat16. If auto, we use the torch_dtype attribute specified in the model config file. However, if the torch_dtype in the config is float32, we will use float16 instead. auto
quantization Optional[str] The method used to quantize the model weights. Currently, we support "awq", "gptq" and "squeezellm". If None, we first check the quantization_config attribute in the model config file. If that is None, we assume the model weights are not quantized and use dtype to determine the data type of the weights. None
revision Optional[str] The specific model version to use. It can be a branch name, a tag name, or a commit id. None
tokenizer_revision Optional[str] The specific tokenizer version to use. It can be a branch name, a tag name, or a commit id. None
gpu_memory_utilization float The ratio (between 0 and 1) of GPU memory to reserve for the model weights, activations, and KV cache. Higher values will increase the KV cache size and thus improve the model's throughput. However, if the value is too high, it may cause out-of-memory (OOM) errors. 0.9
swap_space int The size (GiB) of CPU memory per GPU to use as swap space. This can be used for temporarily storing the states of the requests when their best_of sampling parameters are larger than 1. If all requests will have best_of=1, you can safely set this to 0. Otherwise, too small values may cause out-of-memory (OOM) errors. 4
enforce_eager bool Whether to enforce eager execution. If True, we will disable CUDA graph and always execute the model in eager mode. If False, we will use CUDA graph and eager execution in hybrid. False
enable_lora bool Whether to enable loading LoRA adapters False

See the vLLM code for a list of all the available parameters.

Use quantized models

vLLM supports AWQ, GPTQ and SqueezeLLM quantized models:

from outlines import models

model = models.vllm("TheBloke/Llama-2-7B-Chat-AWQ", quantization="awq")
model = models.vllm("TheBloke/Mistral-7B-Instruct-v0.2-GPTQ", quantization="gptq")
model = models.vllm("https://huggingface.co/squeeze-ai-lab/sq-llama-30b-w4-s5", quantization="squeezellm")

Dependencies

To use AWQ model you need to install the autoawq library pip install autoawq.

To use GPTQ models you need to install the autoGTPQ and optimum libraries pip install auto-gptq optimum.

Multi-GPU usage

To run multi-GPU inference with vLLM you need to set the tensor_parallel_size argument to the number of GPUs available when initializing the model. For instance to run inference on 2 GPUs:

from outlines import models

model = models.vllm(
    "microsoft/Phi-3-mini-4k-instruct"
    tensor_parallel_size=2
)

Load LoRA adapters

You can load LoRA adapters and alternate between them dynamically:

from outlines import models

model = models.vllm("facebook/opt-350m", enable_lora=True)
model.load_lora("ybelkaa/opt-350m-lora")  # Load LoRA adapter
model.load_lora(None)  # Unload LoRA adapter

Generate text

In addition to the parameters described in the text generation section you can pass an instance of SamplingParams directly to any generator via the sampling_params keyword argument:

from vllm.sampling_params import SamplingParams
from outlines import models, generate


model = models.vllm("microsoft/Phi-3-mini-4k-instruct")
generator = generate.text(model)

params = SamplingParams(n=2, frequency_penalty=1., min_tokens=2)
answer = generator("A prompt", sampling_params=params)

This also works with generators built with generate.regex, generate.json, generate.cfg, generate.format and generate.choice.

Note

The values passed via the SamplingParams instance supersede the other arguments to the generator or the samplers.

SamplingParams attributes:

Parameters Type Description Default
n int Number of output sequences to return for the given prompt. 1
best_of Optional[int] Number of output sequences that are generated from the prompt. From these best_of sequences, the top n sequences are returned. best_of must be greater than or equal to n. This is treated as the beam width when use_beam_search is True. By default, best_of is set to n. None
presence_penalty float Float that penalizes new tokens based on whether they appear in the generated text so far. Values > 0 encourage the model to use new tokens, while values < 0 encourage the model to repeat tokens. 0.0
frequency_penalty float Float that penalizes new tokens based on their frequency in the generated text so far. Values > 0 encourage the model to use new tokens, while values < 0 encourage the model to repeat tokens. 0.0
repetition_penalty float Float that penalizes new tokens based on whether they appear in the prompt and the generated text so far. Values > 1 encourage the model to use new tokens, while values < 1 encourage the model to repeat tokens. 1.0
temperature float Float that controls the randomness of the sampling. Lower values make the model more deterministic, while higher values make the model more random. Zero means greedy sampling. 1.0
top_p float Float that controls the cumulative probability of the top tokens to consider. Must be in (0, 1]. Set to 1 to consider all tokens. 1.0
top_k int Integer that controls the number of top tokens to consider. Set to -1 to consider all tokens. -1
min_p float Float that represents the minimum probability for a token to be considered, relative to the probability of the most likely token. Must be in [0, 1]. Set to 0 to disable this. 0.0
seed Optional[int] Random seed to use for the generation. None
use_beam_search bool Whether to use beam search instead of sampling. False
length_penalty float Float that penalizes sequences based on their length. Used in beam search. 1.0
early_stopping Union[bool, str] Controls the stopping condition for beam search. It accepts the following values: True, where the generation stops as soon as there are best_of complete candidates; False, where an heuristic is applied and the generation stops when is it very unlikely to find better candidates; "never", where the beam search procedure only stops when there cannot be better candidates (canonical beam search algorithm). False
stop Optional[Union[str, List[str]]] List of strings that stop the generation when they are generated. The returned output will not contain the stop strings. None
stop_token_ids Optional[List[int]] List of tokens that stop the generation when they are generated. The returned output will contain the stop tokens unless the stop tokens are special tokens. None
include_stop_str_in_output bool Whether to include the stop strings in output text. Defaults to False. False
ignore_eos bool Whether to ignore the EOS token and continue generating tokens after the EOS token is generated. False
max_tokens int Maximum number of tokens to generate per output sequence. 16
min_tokens int Minimum number of tokens to generate per output sequence before EOS or stop_token_ids can be generated 0
skip_special_tokens bool Whether to skip special tokens in the output. True
spaces_between_special_tokens bool Whether to add spaces between special tokens in the output. Defaults to True. True

Streaming

Warning

Streaming is not available for the offline vLLM integration.

Installation

By default the vLLM library is installed with pre-commpiled C++ and CUDA binaries and will only run on GPU:

pip install vllm

CPU

You need to have the gcc compiler installed on your system. Then you will need to install vLLM from source. First clone the repository:

git clone https://github.com/vllm-project/vllm.git
cd vllm

Install the Python packages needed for the installation:

pip install --upgrade pip
pip install wheel packaging ninja setuptools>=49.4.0 numpy
pip install -v -r requirements-cpu.txt --extra-index-url https://download.pytorch.org/whl/cpu

and finally run:

VLLM_TARGET_DEVICE=cpu python setup.py install

See the vLLM documentation for more details, alternative installation methods (Docker) and performance tips.

ROCm

You will need to install vLLM from source. First install Pytorch on ROCm:

pip install torch==2.2.0.dev20231206+rocm5.7 --index-url https://download.pytorch.org/whl/nightly/rocm5.7 # tested version

You will then need to install flash attention for ROCm following these instructions. You can then install xformers=0.0.23 and apply the patches needed to adapt Flash Attention for ROCm:

pip install xformers==0.0.23 --no-deps
bash patch_xformers.rocm.sh

And finally build vLLM:

cd vllm
pip install -U -r requirements-rocm.txt
python setup.py install # This may take 5-10 minutes.

See the vLLM documentation for alternative installation methods (Docker).