VLLMChatGenerator

vLLM으로 서빙된 모델을 사용해 채팅 완성(chat completion)을 실행하는 컴포넌트예요.

파이프라인에서 가장 흔한 위치: ChatPromptBuilder 다음 필수 init 변수: model — vLLM이 서빙하는 모델 이름 필수 run 변수: messages — ChatMessage 객체 리스트 출력 변수: replies — ChatMessage 객체 리스트 API 레퍼런스: vLLM GitHub 링크: https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/vllm 패키지 이름: vllm-haystack

출처: 문서

본문

개요 (Overview)

vLLM은 LLM을 위한 고처리량·메모리 효율적 추론/서빙 엔진이에요. OpenAI 호환 HTTP 서버를 노출하는데, VLLMChatGenerator가 이걸 사용해 채팅 완성을 실행해요.

VLLMChatGenerator는 api_base_url 파라미터(기본 http://localhost:8000/v1)에서 접근 가능한 vLLM 서버가 실행 중이어야 동작해요. 컴포넌트는 동작에 ChatMessage 객체 리스트가 필요해요. ChatMessage는 메시지, 역할(누가 생성했는지 — user, assistant, system, tool 등), 그리고 선택적 메타데이터를 담는 데이터 클래스예요.

vLLM OpenAI 호환 Chat Completion API에 유효한 어떤 텍스트 생성 파라미터든 __init__의 generation_kwargs 파라미터나 run 메서드로 이 컴포넌트에 직접 전달할 수 있어요. 표준 OpenAI API에 없는 vLLM 특유의 파라미터(top_k, min_tokens, repetition_penalty 등)는 generation_kwargs["extra_body"]로 전달할 수 있어요. 자세한 내용은 vLLM 문서를 참고하세요.

vLLM 서버를 --api-key로 시작했다면, Haystack의 Secret API를 통해 VLLM_API_KEY 환경 변수나 api_key init 파라미터로 API 키를 제공하세요.

도구 지원 (Tool Support)

VLLMChatGenerator는 tools 파라미터를 통해 함수 호출을 지원해요. 유연한 도구 구성을 받아요:

Tool 객체 리스트: 개별 도구를 리스트로 전달 단일 Toolset: Toolset 전체를 그대로 전달 Tool과 Toolset 혼합: 독립 도구와 여러 Toolset을 하나의 리스트에 섞어 조합

이렇게 하면 관련 도구를 논리적 그룹으로 묶으면서 필요에 따라 독립 도구도 함께 넣을 수 있어요.

도구 호출이 동작하려면 vLLM 서버를 --enable-auto-tool-choice와 --tool-call-parser로 시작해야 해요. 사용 가능한 도구 호출 파서는 모델에 따라 달라져요. 전체 목록은 vLLM 도구 호출 문서를 참고하세요.

도구 작업에 대한 자세한 내용은 Tool과 Toolset 문서를 참고하세요.

스트리밍 (Streaming)

VLLMChatGenerator는 LLM의 스트리밍 응답을 지원해요. 토큰이 생성되는 대로 방출되게 할 수 있죠. 스트리밍을 활성화하려면 초기화할 때 streaming_callback 파라미터에 콜러블을 전달하면 돼요.

추론 모델 (Reasoning models)

VLLMChatGenerator는 추론 모델(reasoning models)을 지원해요. 이걸 쓰려면 적절한 --reasoning-parser로 vLLM 서버를 시작하세요. 모델이 생성한 추론 내용은 반환된 ChatMessage의 reasoning 필드에 노출돼요.

사용법 (Usage)

VLLMChatGenerator를 쓰려면 vllm-haystack 패키지를 설치해요:

pip install vllm-haystack

vLLM 서버 시작 (Starting the vLLM server)

이 컴포넌트를 쓰기 전에 vLLM 서버를 시작하세요:

vllm serve Qwen/Qwen3-4B-Instruct-2507

추론 모델의 경우 적절한 추론 파서로 서버를 시작하세요:

vllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3

도구 호출의 경우 --enable-auto-tool-choice와 --tool-call-parser로 서버를 시작하세요:

vllm serve Qwen/Qwen3-0.6B --enable-auto-tool-choice --tool-call-parser hermes

서버 옵션에 대한 자세한 내용은 vLLM CLI 문서를 참고하세요.

단독으로 사용하기 (On its own)

기본 사용법:

from haystack.dataclasses import ChatMessage
from haystack_integrations.components.generators.vllm import VLLMChatGenerator

generator = VLLMChatGenerator(
    model="Qwen/Qwen3-4B-Instruct-2507",
    generation_kwargs={"max_tokens": 512, "temperature": 0.7},
)
messages = [ChatMessage.from_user("What's Natural Language Processing?")]
response = generator.run(messages=messages)
print(response["replies"][0].text)

vLLM 특유 파라미터 사용 (With vLLM-specific parameters)

vLLM 특유 파라미터는 generation_kwargs["extra_body"] 딕셔너리로 전달해요:

from haystack_integrations.components.generators.vllm import VLLMChatGenerator

generator = VLLMChatGenerator(
    model="Qwen/Qwen3-4B-Instruct-2507",
    generation_kwargs={
        "max_tokens": 512,
        "extra_body": {
            "top_k": 50,
            "min_tokens": 10,
            "repetition_penalty": 1.1,
        },
    },
)

도구 호출 사용 (With tool calling)

--enable-auto-tool-choice와 --tool-call-parser로 vLLM 서버를 시작한 뒤:

from haystack.dataclasses import ChatMessage
from haystack.tools import tool
from haystack_integrations.components.generators.vllm import VLLMChatGenerator

@tool
def weather(city: str) -> str:
    """Get the weather in a given city."""
    return f"The weather in {city} is sunny"

generator = VLLMChatGenerator(model="Qwen/Qwen3-0.6B", tools=[weather])
messages = [ChatMessage.from_user("What is the weather in Paris?")]
response = generator.run(messages=messages)
print(response["replies"][0].tool_calls)

추론 모델 사용 (With reasoning models)

--reasoning-parser로 vLLM 서버를 시작한 뒤:

from haystack.dataclasses import ChatMessage
from haystack_integrations.components.generators.vllm import VLLMChatGenerator

generator = VLLMChatGenerator(model="Qwen/Qwen3-0.6B")
messages = [ChatMessage.from_user("Solve step by step: what is 15 * 37?")]
response = generator.run(messages=messages)
reply = response["replies"][0]
if reply.reasoning:
    print("Reasoning:", reply.reasoning.reasoning_text)
print("Answer:", reply.text)

파이프라인 안에서 사용하기 (In a pipeline)

from haystack import Pipeline
from haystack.components.builders import ChatPromptBuilder
from haystack.dataclasses import ChatMessage
from haystack_integrations.components.generators.vllm import VLLMChatGenerator

prompt_builder = ChatPromptBuilder()
llm = VLLMChatGenerator(model="Qwen/Qwen3-4B-Instruct-2507")

pipe = Pipeline()
pipe.add_component("prompt_builder", prompt_builder)
pipe.add_component("llm", llm)
pipe.connect("prompt_builder.prompt", "llm.messages")

messages = [
    ChatMessage.from_system("Give brief answers."),
    ChatMessage.from_user("Tell me about {{city}}"),
]
response = pipe.run(
    data={
        "prompt_builder": {
            "template": messages,
            "template_variables": {"city": "Berlin"},
        },
    },
)
print(response)

VLLMChatGenerator