LiteLLMChatGenerator

LiteLLM을 통해 다양한 LLM 제공자를 사용해 채팅 완성(chat completion)을 만들어주는 컴포넌트예요. 주로 ChatPromptBuilder 뒤에 두면 돼요.

출처: LiteLLMChatGenerator

본문

개요

LiteLLMChatGenerator는 채팅 완성을 LiteLLM을 거쳐 라우팅해요. LiteLLM은 OpenAI, Anthropic, Google, AWS Bedrock, Azure, Cohere, Mistral, Groq를 포함한 100개 이상의 LLM 제공자에 단일·통합 인터페이스를 제공해요. 그래서 model 문자열만 바꾸면 제공자를 전환할 수 있고 파이프라인을 다시 작성할 필요가 없어요.

파라미터

모델 이름은 LiteLLM의 provider/model-name 형식을 사용해요. 예: openai/gpt-4o, anthropic/claude-sonnet-4-20250514, bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0. 기본 모델은 openai/gpt-4o예요. 지원되는 제공자와 모델 식별자의 전체 목록은 LiteLLM providers 문서를 참고하세요.

LiteLLMChatGenerator는 선택한 제공자의 API 키가 필요해요. 두 가지 방법으로 제공할 수 있어요.

LiteLLM이 제공자의 표준 환경 변수(예: OPENAI_API_KEY, ANTHROPIC_API_KEY)에서 자격 증명을 스스로 해석하게 두는 방법(권장).
api_key 초기화 파라미터와 Haystack의 Secret API로 명시적으로 전달하는 방법: Secret.from_env_var("OPENAI_API_KEY"). Haystack이 키를 관리하고 직렬화하길 원할 때만 사용하세요.

셀프 호스팅 LiteLLM 프록시나 커스텀 엔드포인트를 대상으로 실행한다면 api_base_url 파라미터를 설정해요.

litellm.completion()이 지원하는 어떤 파라미터든 generation_kwargs 파라미터를 통해 초기화 때와 실행 때 모두 넘길 수 있어요. LiteLLM은 이 파라미터들을 제공자에 맞게 정규화하고, 특정 제공자가 지원하지 않는 파라미터는 버려요.

마지막으로 컴포넌트가 동작하려면 ChatMessage 객체 목록이 필요해요. ChatMessage는 메시지, 역할(누가 생성했는지: user, assistant, system, tool), 선택적 메타데이터를 담는 데이터 클래스예요.

도구 지원

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

Tool 객체 목록: 개별 도구를 리스트로 전달.
단일 Toolset: 전체 Toolset을 바로 전달.
도구·Toolset 혼합: 여러 Toolset을 독립 도구와 한 리스트에 결합.

툴 호출은 동기·스트리밍 응답 모두에서 동작해요(기본 제공자와 모델이 함수 호출을 지원한다면). 도구 작업에 대한 자세한 내용은 Tool과 Toolset 문서를 참고하세요.

스트리밍

생성되는 대로 출력을 스트리밍할 수 있어요. streaming_callback에 콜백을 전달하면 돼요. 내장된 print_streaming_chunk를 쓰면 텍스트 토큰과 툴 이벤트(툴 호출·툴 결과)를 출력해요.

from haystack.components.generators.utils import print_streaming_chunk
from haystack.dataclasses import ChatMessage
from haystack_integrations.components.generators.litellm import LiteLLMChatGenerator

generator = LiteLLMChatGenerator(
    model="openai/gpt-4o",
    streaming_callback=print_streaming_chunk,
)
generator.run([ChatMessage.from_user("Your question here")])

StreamingChunk가 어떻게 동작하는지, 커스텀 콜백을 어떻게 작성하는지는 Streaming Support 문서를 참고하세요.

비동기 실행

LiteLLMChatGenerator는 비동기 파이프라인·애플리케이션용 run_async 메서드를 제공해요. run과 같은 파라미터를 받으며 일반·스트리밍 응답을 모두 지원해요(스트리밍 때는 비동기 스트리밍 콜백을 전달하세요).

사용법

LiteLLMChatGenerator를 쓰려면 litellm-haystack 패키지를 설치해요.

pip install litellm-haystack

단독 사용:

from haystack_integrations.components.generators.litellm import LiteLLMChatGenerator
from haystack.dataclasses import ChatMessage

generator = LiteLLMChatGenerator(
    model="anthropic/claude-sonnet-4-20250514",
    generation_kwargs={"max_tokens": 1024, "temperature": 0.7},
)

messages = [
    ChatMessage.from_system("You are a helpful assistant"),
    ChatMessage.from_user("What's Natural Language Processing? Be brief."),
]
result = generator.run(messages=messages)
print(result["replies"][0].text)

파이프라인 안에서:

LiteLLMChatGenerator를 ChatPromptBuilder와 함께 파이프라인에서 쓸 수도 있어요.

from haystack import Pipeline
from haystack.components.builders import ChatPromptBuilder
from haystack.dataclasses import ChatMessage
from haystack_integrations.components.generators.litellm import LiteLLMChatGenerator

pipe = Pipeline()
pipe.add_component("prompt_builder", ChatPromptBuilder())
pipe.add_component("llm", LiteLLMChatGenerator(model="openai/gpt-4o"))
pipe.connect("prompt_builder", "llm")

country = "Germany"
system_message = ChatMessage.from_system(
    "You are an assistant giving out valuable information to language learners.",
)
messages = [
    system_message,
    ChatMessage.from_user("What's the official language of {{ country }}?"),
]

res = pipe.run(
    data={
        "prompt_builder": {
            "template_variables": {"country": country},
            "template": messages,
        },
    },
)
print(res)

LiteLLMChatGenerator