LlamaIndex 쿼리 엔진 사용 패턴

LlamaIndex 쿼리 엔진 사용 패턴 (Usage Pattern)

쿼리 엔진을 실제로 만들고 다루는 패턴을 순서대로 살펴볼게요. 먼저 인덱스에서 쿼리 엔진을 만들고, 질문을 던지는 것부터 시작해요.

시작하기

인덱스에서 쿼리 엔진을 만들어요.

query_engine = index.as_query_engine()

💡 팁: 인덱스 만드는 법은 Indexing 문서를 참고하세요.

데이터에 대해 질문을 던져요.

response = query_engine.query("Who is Paul Graham?")

출처: 공식문서

쿼리 엔진 구성하기

하이레벨 API

인덱스에서 한 줄로 쿼리 엔진을 만들고 구성할 수 있어요.

query_engine = index.as_query_engine(
    response_mode="tree_summarize",
    verbose=True,
)

⚠️ 참고: 하이레벨 API는 사용 편의성에 최적화되어 있지만, 완전한 범위의 구성 가능성을 노출하지는 않아요.

응답 모드의 전체 목록과 동작은 Response Modes 문서를 참고하세요.

로우레벨 조합 API

더 세밀한 제어가 필요하면 로우레벨 조합 API를 쓸 수 있어요. 구체적으로는 index.as_query_engine(...)을 호출하는 대신 QueryEngine 객체를 직접 생성해요.

⚠️ 참고: API 레퍼런스나 예제 노트북을 확인해야 할 수 있어요.

from llama_index.core import VectorStoreIndex, get_response_synthesizer
from llama_index.core.retrievers import VectorIndexRetriever
from llama_index.core.query_engine import RetrieverQueryEngine


# build index
index = VectorStoreIndex.from_documents(documents)


# configure retriever
retriever = VectorIndexRetriever(
    index=index,
    similarity_top_k=2,
)


# configure response synthesizer
response_synthesizer = get_response_synthesizer(
    response_mode="tree_summarize",
)


# assemble query engine
query_engine = RetrieverQueryEngine(
    retriever=retriever,
    response_synthesizer=response_synthesizer,
)


# query
response = query_engine.query("What did the author do growing up?")
print(response)

리트리버 → 응답 신시사이저 → 쿼리 엔진 순으로 조립하는 구조를 눈여겨보세요.

스트리밍

스트리밍을 켜려면 streaming=True 플래그만 넘기면 돼요.

query_engine = index.as_query_engine(
    streaming=True,
)
streaming_response = query_engine.query(
    "What did the author do growing up?",
)
streaming_response.print_response_stream()

커스텀 쿼리 엔진 정의하기

커스텀 쿼리 엔진도 정의할 수 있어요. CustomQueryEngine 클래스를 상속하고, (Pydantic 클래스를 정의하듯) 원하는 속성을 정의한 뒤, Response 객체나 문자열을 반환하는 custom_query 함수를 구현하면 돼요.

from llama_index.core.query_engine import CustomQueryEngine
from llama_index.core.retrievers import BaseRetriever
from llama_index.core import get_response_synthesizer
from llama_index.core.response_synthesizers import BaseSynthesizer




class RAGQueryEngine(CustomQueryEngine):
    """RAG Query Engine."""


    retriever: BaseRetriever
    response_synthesizer: BaseSynthesizer


    def custom_query(self, query_str: str):
        nodes = self.retriever.retrieve(query_str)
        response_obj = self.response_synthesizer.synthesize(query_str, nodes)
        return response_obj

custom_query 안에서 리트리버로 관련 노드를 가져온 뒤, 응답 신시사이저로 합성하는 흐름이에요.

더 알아보기