Skip to content

vLLM

VLLM

To begin, start a vLLM server. Be sure to specify --structured-outputs-config.backend guidance if your vLLM version is >0.12.0.

vllm serve RedHatAI/gemma-3-12b-it-quantized.w4a16 --host 0.0.0.0 \
--port 8000 \
--enable-prefix-caching \
--max-model-len 8000 \
--structured-outputs-config.backend guidance \
--gpu_memory_utilization 0.8 \
--enable-prompt-tokens-details

Bases: ModelBase

Class for vLLM endpoints.

Parameters:

Name Type Description Default
model_name_or_path str

Name of the model

required
base_url str

Base URL for http requests

required

Examples:

from blendsql.models import VLLM

model = VLLM("RedHatAI/gemma-3-12b-it-quantized.w4a16", base_url="http://localhost:8000/v1/")
Source code in blendsql/models/vllm.py
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
class VLLM(ModelBase):
    """Class for vLLM endpoints.

    Args:
        model_name_or_path: Name of the model
        base_url: Base URL for http requests

    Examples:
        ```python
        from blendsql.models import VLLM

        model = VLLM("RedHatAI/gemma-3-12b-it-quantized.w4a16", base_url="http://localhost:8000/v1/")
        ```
    """

    def __init__(
        self,
        model_name_or_path: str,
        base_url: str,
        api_key: str = "N/A",
        tokenizer: "BaseTokenizer" = None,
        extra_body: dict | None = None,
        caching: bool = False,
        **kwargs,
    ):
        from openai import AsyncOpenAI

        self.extra_body = extra_body or dict()

        super().__init__(
            model_name_or_path=model_name_or_path,
            caching=caching,
            _allows_parallel_requests=True,
            **kwargs,
        )
        if tokenizer is None:
            from huggingface_hub import hf_hub_download
            import json

            with open(
                hf_hub_download(
                    repo_id=model_name_or_path, filename="tokenizer_config.json"
                ),
                "r",
            ) as f:
                config = json.load(f)
            self.chat_template = config["chat_template"]
            with open(
                hf_hub_download(
                    repo_id=model_name_or_path, filename="special_tokens_map.json"
                ),
                "r",
            ) as f:
                special_tokens_map = json.load(f)
            self.special_tokens_map = {
                k: v["content"] if isinstance(v, dict) else v
                for k, v in special_tokens_map.items()
            }
        self.tokenizer = tokenizer
        self.client = AsyncOpenAI(base_url=base_url, api_key=api_key)

    async def generate(
        self, item: GenerationItem, cancel_event: asyncio.Event | None = None
    ):
        buffer = ""
        extra_body = (
            DEFAULT_BODY
            | {"max_tokens": int(os.getenv(MAX_TOKENS_KEY, DEFAULT_MAX_TOKENS))}
            | self.extra_body
        )
        if item.grammar:
            extra_body |= {
                "guided_decoding_backend": "guidance",
                "guided_grammar": item.grammar,
                "structured_outputs": {"grammar": item.grammar},
            }
        messages = [{"role": "user", "content": item.prompt}]
        if item.assistant_continuation is not None:
            messages.append(
                {"role": "assistant", "content": item.assistant_continuation}
            )

        if self.tokenizer is None:
            from .tokenization import render_jinja_template

            prompt_to_send = render_jinja_template(
                messages=messages,
                chat_template=self.chat_template,
                continue_final_message=item.assistant_continuation is not None,
                add_generation_prompt=item.assistant_continuation is None,
                **self.special_tokens_map,
            )
        else:
            prompt_to_send = self.tokenizer.apply_chat_template(
                messages,
                tokenize=False,
                continue_final_message=item.assistant_continuation is not None,
                add_generation_prompt=item.assistant_continuation is None,
            )

        stream = await self.client.completions.create(
            model=self.model_name_or_path,
            prompt=prompt_to_send,
            stream=True,
            stream_options={"include_usage": True},
            extra_body=extra_body,
        )
        self.num_generation_calls += 1
        add_to_global_history(prompt_to_send)

        try:
            async for chunk in stream:
                if cancel_event and cancel_event.is_set():
                    return GenerationResult(item.identifier, buffer, completed=False)

                if chunk.choices and chunk.choices[0].text:
                    buffer += chunk.choices[0].text

                if hasattr(chunk, "usage") and chunk.usage is not None:
                    self.prompt_tokens += chunk.usage.prompt_tokens
                    self.completion_tokens += chunk.usage.completion_tokens
                    if chunk.usage.prompt_tokens_details is not None:
                        self.cached_tokens += (
                            chunk.usage.prompt_tokens_details.cached_tokens
                        )

        finally:
            await stream.close()

        return GenerationResult(item.identifier, buffer, completed=True)