/rag/query

/rag/query

벡터 스토어 검색 → (리랭킹) → LLM 완성까지 처리하는 RAG 쿼리 엔드포인트예요. 검색 결과를 메시지에 붙여 LLM 응답을 생성하는 전체 흐름과 파라미터를 알려드릴게요.

출처: 문서

본문

RAG 쿼리 엔드포인트: 벡터 스토어 검색 → (리랭킹) → LLM 완성

기능 지원
로깅 예
스트리밍 예
리랭킹 예 (선택)
지원 제공자 openai, bedrock, vertex_ai

Quick Start

OpenAI로 RAG 쿼리

curl -X POST "http://localhost:4000/v1/rag/query" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-5.6-luna",
        "messages": [{"role": "user", "content": "What is LiteLLM?"}],
        "retrieval_config": {
            "vector_store_id": "vs_abc123",
            "custom_llm_provider": "openai",
            "top_k": 5
        }
    }'

동작 방식

RAG 쿼리 엔드포인트는 다음 단계를 수행해요:

  • 쿼리 추출: 마지막 사용자 메시지에서 쿼리 텍스트를 추출해요.
  • 벡터 스토어 검색: 지정된 벡터 스토어에서 관련 컨텍스트를 검색해요.
  • 리랭킹 (선택): 리랭킹 모델로 검색 결과를 재정렬해요.
  • 응답 생성: 가져온 컨텍스트를 메시지 앞에 붙여 LLM을 호출해요.

응답

응답은 추가 검색 메타데이터와 함께 표준 OpenAI 채팅 완성 형식을 따라요:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1703123456,
  "model": "gpt-5.6-luna",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "LiteLLM is a unified interface for 100+ LLMs..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 150,
    "completion_tokens": 50,
    "total_tokens": 200
  },
  "_hidden_params": {
    "search_results": {...},
    "rerank_results": {...}
  }
}

리랭킹 사용

결과 품질을 높이려면 rerank 구성을 추가해요: RAG Query with Reranking

curl -X POST "http://localhost:4000/v1/rag/query" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-5.6-luna",
        "messages": [{"role": "user", "content": "What is LiteLLM?"}],
        "retrieval_config": {
            "vector_store_id": "vs_abc123",
            "custom_llm_provider": "openai",
            "top_k": 10
        },
        "rerank": {
            "enabled": true,
            "model": "cohere/rerank-english-v3.0",
            "top_n": 3
        }
    }'

스트리밍

실시간 응답을 위해 스트리밍을 활성화해요: RAG Query with Streaming

curl -X POST "http://localhost:4000/v1/rag/query" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-5.6-luna",
        "messages": [{"role": "user", "content": "What is LiteLLM?"}],
        "retrieval_config": {
            "vector_store_id": "vs_abc123",
            "custom_llm_provider": "openai"
        },
        "stream": true
    }'

검색 필터링

retrieval_config.retrieval_filter를 설정해 메타데이터가 일치하는 청크로 검색을 좁혀요. 필터는 벡터 스토어에 filters 인수로 전달되므로 제공자가 받아들이는 형식을 그대로 사용해요: Bedrock Knowledge Bases는 자체 네이티브 연산자(equals, notEquals, andAll, orAll 등; andAll/orAll은 절이 두 개 이상 필요)와 OpenAI 비교 형태({"key": ..., "value": ..., "operator": "eq"})를 받고, OpenAI 벡터 스토어는 자체 필터 객체를 받아요. retrieval_config.filters는 별칭으로 허용되며, 둘 다 설정되면 retrieval_filter가 우선해요. 벡터 스토어가 거부하는 필터는 스토어의 상태 코드와 메시지로 요청을 실패시켜요. RAG Query with a Bedrock metadata filter

curl -X POST "http://localhost:4000/v1/rag/query" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "bedrock/us.anthropic.claude-sonnet-5",
        "messages": [{"role": "user", "content": "How do I reset my password?"}],
        "retrieval_config": {
            "vector_store_id": "KNOWLEDGE_BASE_ID",
            "custom_llm_provider": "bedrock",
            "top_k": 5,
            "retrieval_filter": {
                "andAll": [
                    {"equals": {"key": "department", "value": "billing"}},
                    {"equals": {"key": "doc_type", "value": "manual"}}
                ]
            }
        }
    }'

요청 파라미터

최상위

파라미터 타입 필수 설명
model string 예 생성에 사용할 LLM 모델
messages array 예 채팅 메시지 배열 (OpenAI 형식)
retrieval_config object 예 벡터 스토어 검색 구성
rerank object 아니요 리랭킹 구성
stream boolean 아니요 스트리밍 활성화 (기본값: false)

retrieval_config

파라미터 타입 기본값 설명
vector_store_id string 필수 검색할 벡터 스토어 ID
custom_llm_provider string "openai" 벡터 스토어 제공자
top_k integer 10 검색할 결과 수
retrieval_filter object - 벡터 스토어 검색에 전달되는 메타데이터 필터 (Filtering Retrieval 참고)
filters object - retrieval_filter의 별칭; 둘 다 설정되면 retrieval_filter가 우선

rerank

파라미터 타입 기본값 설명
enabled boolean false 리랭킹 활성화
model string - 리랭킹 모델 (예: cohere/rerank-english-v3.0)
top_n integer 5 리랭킹 후 결과 수

엔드투엔드 예시

1. 문서 수집

먼저 /rag/ingest 엔드포인트로 문서를 수집해요: Step 1: Ingest

curl -X POST "http://localhost:4000/v1/rag/ingest" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d "{
        \"file\": {
            \"filename\": \"company_docs.txt\",
            \"content\": \"$(base64 -i company_docs.txt)\",
            \"content_type\": \"text/plain\"
        },
        \"ingest_options\": {
            \"vector_store\": {
                \"custom_llm_provider\": \"openai\"
            }
        }
    }"

응답:

{
  "id": "ingest_abc123",
  "status": "completed",
  "vector_store_id": "vs_xyz789",
  "file_id": "file-123"
}

2. RAG로 쿼리

이제 수집된 문서를 쿼리해요: Step 2: Query

curl -X POST "http://localhost:4000/v1/rag/query" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-5.6-luna",
        "messages": [
            {"role": "user", "content": "What products does the company offer?"}
        ],
        "retrieval_config": {
            "vector_store_id": "vs_xyz789",
            "custom_llm_provider": "openai",
            "top_k": 5
        }
    }'

응답:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-5.6-luna",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Based on the company documents, the company offers..."
      },
      "finish_reason": "stop"
    }
  ]
}

제공자 예시

Bedrock

Bedrock으로 RAG 쿼리

curl -X POST "http://localhost:4000/v1/rag/query" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "bedrock/us.anthropic.claude-sonnet-5",
        "messages": [{"role": "user", "content": "What is LiteLLM?"}],
        "retrieval_config": {
            "vector_store_id": "KNOWLEDGE_BASE_ID",
            "custom_llm_provider": "bedrock",
            "top_k": 5
        }
    }'

Vertex AI

Vertex AI로 RAG 쿼리

curl -X POST "http://localhost:4000/v1/rag/query" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "vertex_ai/gemini-3.1-pro-preview",
        "messages": [{"role": "user", "content": "What is LiteLLM?"}],
        "retrieval_config": {
            "vector_store_id": "your-corpus-id",
            "custom_llm_provider": "vertex_ai",
            "top_k": 5
        }
    }'

Python SDK

litellm.aquery() 사용

import litellm

response = await litellm.aquery(
    model="gpt-5.6-luna",
    messages=[{"role": "user", "content": "What is LiteLLM?"}],
    retrieval_config={
        "vector_store_id": "vs_abc123",
        "custom_llm_provider": "openai",
        "top_k": 5,
    },
    rerank={
        "enabled": True,
        "model": "cohere/rerank-english-v3.0",
        "top_n": 3,
    },
)

print(response.choices[0].message.content)

더 알아보기 (Learn more)