벡터 스토어(지식 베이스) 사용하기

벡터 스토어(지식 베이스) 사용하기 (Using Vector Stores / Knowledge Bases)

LiteLLM이 지원하는 어떤 모델이든 벡터 스토어를 사용해요.

LiteLLM은 벡터 스토어와 통합되어, 모델이 조직의 데이터에 접근해 더 정확하고 컨텍스트에 맞는 응답을 하게 합니다.

지원되는 벡터 스토어

Bedrock Knowledge Bases
OpenAI Vector Stores
Azure Vector Stores (직접 쿼리 불가. Assistants 메시지에서 호출할 때만 사용 가능)
Azure AI Search (Azure AI Search 인덱스로 벡터 검색)
Vertex AI RAG API
Gemini File Search
MongoDB Vector Search (BETA) (기존 Atlas 또는 셀프 관리 MongoDB 인덱스를 채팅 컴플리션의 컨텍스트로 사용)
RAGFlow Datasets (데이터셋 관리만, 검색은 지원 안 함)

빠른 시작

LiteLLM에서 벡터 스토어를 사용하려면:

litellm.vector_store_registry 를 초기화합니다
컴플리션 요청에 vector_store_ids 를 가진 tools를 전달합니다. vector_store_ids 는 litellm.vector_store_registry 에서 초기화한 벡터 스토어 id 목록입니다

LiteLLM Python SDK

LiteLLM을 사용하면 사용하려는 vector_store_ids 를 가진 tool을 전달해 OpenAI API 스펙에서 벡터 스토어를 사용할 수 있어요.

import os
import litellm

from litellm.vector_stores.vector_store_registry import VectorStoreRegistry, LiteLLM_ManagedVectorStore

# Init vector store registry
litellm.vector_store_registry = VectorStoreRegistry(
    vector_stores=[
        LiteLLM_ManagedVectorStore(
            vector_store_id="T37J8R4WTM",
            custom_llm_provider="bedrock"
        )
    ]
)

# Make a completion request with vector_store_ids parameter
response = await litellm.acompletion(
    model="anthropic/claude-sonnet-5", 
    messages=[{"role": "user", "content": "What is litellm?"}],
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": ["T37J8R4WTM"]
        }
    ],
)

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

출처: 문서

본문

LiteLLM Proxy

1. vector_store_registry 구성

LiteLLM에서 벡터 스토어를 사용하려면 vector_store_registry를 구성해야 해요. 이는 litellm에게 어떤 벡터 스토어를 사용할지, 벡터 스토어에 어떤 api 프로바이더를 사용할지 알려줍니다.

config.yaml
LiteLLM UI

model_list:
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

vector_store_registry:
  - vector_store_name: "bedrock-litellm-website-knowledgebase"
    litellm_params:
      vector_store_id: "T37J8R4WTM"
      custom_llm_provider: "bedrock"
      vector_store_description: "Bedrock vector store for the Litellm website knowledgebase"
      vector_store_metadata:
        source: "https://www.litellm.com/docs"

2. vector_store_ids 파라미터로 요청 만들기

Curl
OpenAI Python SDK

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "What is litellm?"}],
    "tools": [
        {
            "type": "file_search",
            "vector_store_ids": ["T37J8R4WTM"]
        }
    ]
  }'

from openai import OpenAI

# Initialize client with your LiteLLM proxy URL
client = OpenAI(
    base_url="http://localhost:4000",
    api_key="your-litellm-api-key"
)

# Make a completion request with vector_store_ids parameter
response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "What is litellm?"}],
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": ["T37J8R4WTM"]
        }
    ]
)

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

프로바이더별 가이드

이 섹션은 벡터 스토어를 LiteLLM에 추가하는 방법을 다룬다. 새 프로바이더 지원이 필요하면 여기서 이슈를 제출하세요.

Bedrock Knowledge Bases

Bedrock Knowledge Base 설정 — AWS 계정에 적절한 권한과 함께 Bedrock Knowledge Base가 만들어져 있는지 확인.
LiteLLM UI에 추가:
- Tools > Vector Stores > "Add new vector store" 이동
- 프로바이더로 "Bedrock" 선택
- "Vector Store ID" 필드에 Bedrock Knowledge Base ID 입력

Vertex AI RAG Engine

Vertex AI RAG Engine ID 가져오기 — Google Cloud Console의 RAG Engine Corpus로 이동 → LiteLLM과 통합할 RAG Engine 선택 → "Details" 버튼 클릭 후 UUID 복사. ID는 6917529027641081856 처럼 보입니다.
LiteLLM UI에 추가 — "Add new vector store" → 프로바이더 "Vertex AI RAG Engine" → "Vector Store ID" 필드에 ID 입력

PG Vector

litellm-pg-vector-store 커넥터 배포 — LiteLLM은 PG Vector용 OpenAI 호환 vector_store 엔드포인트를 노출하는 서버를 제공합니다. LiteLLM Proxy 서버는 배포된 서비스에 연결해 쿼리 시 벡터 스토어로 사용합니다.
- 배포 지침은 여기 참고
- 상세 구성 옵션은 구성 가이드 참고

리텔레 litellm-pg-vector-store 배포 예시 .env 구성:

DATABASE_URL="postgresql://neondb_owner:xxxx"
SERVER_API_KEY="sk-<your-litellm-api-key>"
HOST="0.0.0.0"
PORT=8001
EMBEDDING__MODEL="text-embedding-ada-002"
EMBEDDING__BASE_URL="http://localhost:4000"
EMBEDDING__API_KEY="sk-<your-litellm-api-key>"
EMBEDDING__DIMENSIONS=1536
DB_FIELDS__ID_FIELD="id"
DB_FIELDS__CONTENT_FIELD="content"
DB_FIELDS__METADATA_FIELD="metadata"
DB_FIELDS__EMBEDDING_FIELD="embedding"
DB_FIELDS__VECTOR_STORE_ID_FIELD="vector_store_id"
DB_FIELDS__CREATED_AT_FIELD="created_at"

LiteLLM UI에 추가 — litellm-pg-vector-store 배포 후: "Add new vector store" → 프로바이더 "PG Vector" → litellm-pg-vector-store 컨테이너의 API Base URL과 API Key 입력 (.env 구성의 SERVER_API_KEY 에 해당).

OpenAI Vector Stores

OpenAI Vector Store 설정 — OpenAI 플랫폼에서 Vector Store 생성, ID 기록 (vs_687ae3b2439881918b433cb99d10662e 형식).
LiteLLM UI에 추가 — "Add new vector store" → 프로바이더 "OpenAI" → 해당 필드에 Vector Store ID, API Key 필드에 OpenAI API Key 입력.

고급

벡터 스토어 사용량 로깅

LiteLLM을 사용하면 LiteLLM UI의 Logs 페이지에서 벡터 스토어 사용량을 볼 수 있습니다. 벡터 스토어로 요청을 완료한 후, LiteLLM의 Logs 페이지로 이동하면 벡터 스토어로 보낸 쿼리와 점수가 있는 대응 응답을 볼 수 있어요.

사용 가능한 벡터 스토어 나열

/vector_store/list 엔드포인트로 모든 사용 가능한 벡터 스토어를 나열할 수 있어요.

요청:

curl -X GET "http://localhost:4000/vector_store/list" \
  -H "Authorization: Bearer ***"

응답은 LiteLLM에서 사용할 수 있는 모든 벡터 스토어의 목록입니다.

{
  "object": "list",
  "data": [
    {
      "vector_store_id": "T37J8R4WTM",
      "custom_llm_provider": "bedrock",
      "vector_store_name": "bedrock-litellm-website-knowledgebase",
      "vector_store_description": "Bedrock vector store for the Litellm website knowledgebase",
      "vector_store_metadata": {
        "source": "https://www.litellm.com/docs"
      },
      "created_at": "2023-05-03T18:21:36.462Z",
      "updated_at": "2023-05-03T18:21:36.462Z",
      "litellm_credential_name": "bedrock_credentials"
    }
  ],
  "total_count": 1,
  "current_page": 1,
  "total_pages": 1
}

특정 모델에 항상 사용

특정 모델에 벡터 스토어가 기본으로 사용되길 원한다면 이 기능을 사용하세요. 이 config에서 claude-3-5-sonnet-with-vector-store 모델에 vector_store_ids 를 추가합니다. 즉, 그 모델로의 모든 요청이 vector_store_registry 에 정의된 ID T37J8R4WTM 의 벡터 스토어를 항상 사용합니다.

model_list:
  - model_name: claude-3-5-sonnet-with-vector-store
    litellm_params:
      model: anthropic/claude-sonnet-5
      vector_store_ids: ["T37J8R4WTM"]

vector_store_registry:
  - vector_store_name: "bedrock-litellm-website-knowledgebase"
    litellm_params:
      vector_store_id: "T37J8R4WTM"
      custom_llm_provider: "bedrock"
      vector_store_description: "Bedrock vector store for the Litellm website knowledgebase"
      vector_store_metadata:
        source: "https://www.litellm.com/docs"

동작 방식

요청에 vector_store_ids 파라미터가 있고, 그 중 어떤 벡터 스토어 id든 vector_store_registry 에 있으면, LiteLLM이 자동으로 요청에 벡터 스토어를 사용합니다.

vector_store_ids 파라미터로 컴플리션 요청을 하고, 어떤 id든 litellm.vector_store_registry 에 있음
LiteLLM이 자동으로: 마지막 메시지를 쿼리로 사용해 Knowledge Base에서 관련 정보 검색, 검색된 컨텍스트를 대화에 추가, 증강된 메시지를 모델로 전송

예시 변환

vector_store_ids=["YOUR_KNOWLEDGE_BASE_ID"] 를 전달하면 요청이 다음 단계를 거칩니다:

LiteLLM에 대한 원래 요청:

{
    "model": "anthropic/claude-sonnet-5",
    "messages": [
        {"role": "user", "content": "What is litellm?"}
    ],
    "vector_store_ids": ["YOUR_KNOWLEDGE_BASE_ID"]
}

AWS Bedrock Knowledge Base에 대한 요청:

{
    "retrievalQuery": {
        "text": "What is litellm?"
    }
}

이것은 https://bedrock-agent-runtime.{aws_region}.amazonaws.com/knowledgebases/YOUR_KNOWLEDGE_BASE_ID/retrieve 로 전송됩니다.

LiteLLM에 대한 최종 요청:

{
    "model": "anthropic/claude-sonnet-5",
    "messages": [
        {"role": "user", "content": "What is litellm?"},
        {"role": "user", "content": "Context: \n\nLiteLLM is an open-source SDK to simplify LLM API calls across providers (OpenAI, Claude, etc). It provides a standardized interface with robust error handling, streaming, and observability tools."}
    ]
}

이 과정은 요청에 vector_store_ids 파라미터를 포함할 때마다 자동으로 발생합니다.

검색 결과 접근 (인용)

벡터 스토어를 사용할 때 LiteLLM은 provider_specific_fields 에서 검색 결과를 자동으로 반환합니다. 이를 통해 사용자에게 AI 응답에 대한 인용을 보여줄 수 있어요.

핵심 개념

검색 결과는 항상 response.choices[0].message.provider_specific_fields["search_results"] 에 있습니다.

스트리밍: finish_reason == "stop" 일 때 최종 청크에 결과가 나타납니다.

비스트리밍 예시

검색 결과가 있는 비스트리밍 응답:

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "LiteLLM is a platform...",
      "provider_specific_fields": {
        "search_results": [{
          "search_query": "What is litellm?",
          "data": [{
            "score": 0.95,
            "content": [{"text": "...", "type": "text"}],
            "filename": "litellm-docs.md",
            "file_id": "doc-123"
          }]
        }]
      }
    },
    "finish_reason": "stop"
  }]
}

Python SDK
TypeScript SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="your-litellm-api-key"
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "What is litellm?"}],
    tools=[{"type": "file_search", "vector_store_ids": ["T37J8R4WTM"]}]
)

# Get AI response
print(response.choices[0].message.content)

# Get search results (citations)
search_results = response.choices[0].message.provider_specific_fields.get("search_results", [])

for result_page in search_results:
    for idx, item in enumerate(result_page['data'], 1):
        print(f"[{idx}] {item.get('filename', 'Unknown')} (score: {item['score']:.2f})")

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:4000',
  apiKey: process.env.LITELLM_API_KEY
});

const response = await client.chat.completions.create({
  model: 'claude-sonnet-5',
  messages: [{ role: 'user', content: 'What is litellm?' }],
  tools: [{ type: 'file_search', vector_store_ids: ['T37J8R4WTM'] }]
});

// Get AI response
console.log(response.choices[0].message.content);

// Get search results (citations)
const message = response.choices[0].message as any;
const searchResults = message.provider_specific_fields?.search_results || [];

searchResults.forEach((page: any) => {
  page.data.forEach((item: any, idx: number) => {
    console.log(`[${idx + 1}] ${item.filename || 'Unknown'} (${item.score.toFixed(2)})`);
  });
});

스트리밍 예시

검색 결과가 있는 스트리밍 응답 (최종 청크):

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "index": 0,
    "delta": {
      "provider_specific_fields": {
        "search_results": [{
          "search_query": "What is litellm?",
          "data": [{
            "score": 0.95,
            "content": [{"text": "...", "type": "text"}],
            "filename": "litellm-docs.md",
            "file_id": "doc-123"
          }]
        }]
      }
    },
    "finish_reason": "stop"
  }]
}

Python SDK
TypeScript SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="your-litellm-api-key"
)

stream = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "What is litellm?"}],
    tools=[{"type": "file_search", "vector_store_ids": ["T37J8R4WTM"]}],
    stream=True
)

for chunk in stream:
    # Stream content
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    
    # Get citations in final chunk
    if chunk.choices[0].finish_reason == "stop":
        search_results = getattr(chunk.choices[0].delta, 'provider_specific_fields', {}).get('search_results', [])
        if search_results:
            print("\n\nSources:")
            for page in search_results:
                for idx, item in enumerate(page['data'], 1):
                    print(f"  [{idx}] {item.get('filename', 'Unknown')} ({item['score']:.2f})")

검색 결과 필드

필드	타입	설명
`search_query`	string	벡터 스토어를 검색하는 데 사용된 쿼리
`data`	array	검색 결과 배열
`data[].score`	float	관련성 점수 (0-1, 높을수록 관련성 높음)
`data[].content`	array	텍스트와 타입이 있는 콘텐츠 청크
`data[].filename`	string	원본 파일 이름 (선택)
`data[].file_id`	string	원본 파일 식별자 (선택)
`data[].attributes`	object	프로바이더별 메타데이터 (선택)

API 레퍼런스

LiteLLM 컴플리션 지식 베이스 파라미터

LiteLLM에서 Knowledge Base 통합을 사용할 때 다음 파라미터를 포함할 수 있어요:

파라미터	타입	설명
`vector_store_ids`	List[str]	쿼리할 Knowledge Base ID 목록

VectorStoreRegistry

VectorStoreRegistry 는 LiteLLM에서 벡터 스토어를 관리하는 중앙 구성 요소입니다. 벡터 스토어를 구성하고 접근하는 레지스트리 역할을 합니다.

VectorStoreRegistry란?

VectorStoreRegistry 는 다음을 하는 클래스입니다:

LiteLLM이 사용할 수 있는 벡터 스토어 모음 유지
자격 증명과 메타데이터로 벡터 스토어 등록 허용
컴플리션 요청에서 ID로 벡터 스토어에 접근 가능하게 함

Python에서 VectorStoreRegistry 사용

from litellm.vector_stores.vector_store_registry import VectorStoreRegistry, LiteLLM_ManagedVectorStore

# Initialize the vector store registry with one or more vector stores
litellm.vector_store_registry = VectorStoreRegistry(
    vector_stores=[
        LiteLLM_ManagedVectorStore(
            vector_store_id="YOUR_VECTOR_STORE_ID",  # Required: Unique ID for referencing this store
            custom_llm_provider="bedrock"            # Required: Provider (e.g., "bedrock")
        )
    ]
)

LiteLLM_ManagedVectorStore 파라미터

파라미터	타입	필수	설명
`vector_store_id`	str	예	벡터 스토어의 고유 식별자
`custom_llm_provider`	str	예	벡터 스토어의 프로바이더 (예: `"bedrock"`)
`vector_store_name`	str	아니요	벡터 스토어의 친근한 이름
`vector_store_description`	str	아니요	벡터 스토어가 포함하는 것에 대한 설명
`vector_store_metadata`	dict 또는 str	아니요	벡터 스토어에 대한 추가 메타데이터
`litellm_credential_name`	str	아니요	이 벡터 스토어에 사용할 자격 증명 이름

config.yaml에서 VectorStoreRegistry 구성

LiteLLM Proxy의 경우 config.yaml 파일에서 같은 레지스트리를 구성할 수 있어요:

vector_store_registry:
  - vector_store_name: "bedrock-litellm-website-knowledgebase"  # Optional friendly name
    litellm_params:
      vector_store_id: "T37J8R4WTM"                            # Required: Unique ID  
      custom_llm_provider: "bedrock"                           # Required: Provider
      vector_store_description: "Bedrock vector store for the Litellm website knowledgebase"
      vector_store_metadata:
        source: "https://www.litellm.com/docs"

litellm_params 섹션은 Python SDK의 LiteLLM_ManagedVectorStore 생성자와 같은 모든 파라미터를 받아들입니다.

벡터 스토어(지식 베이스) 사용하기