MongoDB - 벡터 스토어

MongoDB - 벡터 스토어 (Vector Store, BETA)

MongoDB 벡터 검색 인덱스를 LiteLLM의 선택적 MongoDB sidecar를 통해 검색하는 방법을 알아봐요. 채팅 완성의 컨텍스트로 MongoDB 문서를 사용할 수 있어요.

출처: 문서

본문

BETA: MongoDB 벡터 스토어 통합은 BETA 기능이에요. 선택적 LiteLLM MongoDB sidecar를 통해 기존 MongoDB 벡터 검색 인덱스를 검색해요. 컬렉션, 인덱스, 임베딩된 문서를 LiteLLM에 연결하기 전에 준비하세요.

MongoDB Atlas 또는 자체 관리 MongoDB 배포의 문서를 채팅 완성의 컨텍스트로 사용해요. LiteLLM이 사용자 쿼리를 임베딩하고, 인덱스를 검색하며, 검색된 텍스트를 채팅 모델에 전달해요. 답변을 생성하지 않고 문서와 유사도 점수를 직접 검색할 수도 있어요.

인덱스를 Admin UI, 설정 파일, 또는 관리 API로 연결
curl 또는 OpenAI Python SDK로 채팅 완성에 MongoDB 사용
Atlas의 원본 정책 문서를 사용한 작업 예시 따라하기

시작 전에

필요한 것:

Vector Search가 활성화된 MongoDB 배포. 자체 관리 배포는 MongoDB 배포 가이드와 버전 호환성 요구사항을 따라야 해요. Vector Search가 없는 MongoDB 서버는 이러한 쿼리를 제공할 수 없어요.
채워진 컬렉션과 쿼리 가능한 Vector Search 인덱스. 문서에는 읽을 수 있는 텍스트와 저장된 임베딩이 모두 있어야 해요. 인덱스를 만들어야 한다면 MongoDB의 Vector Search 인덱스 가이드를 참고해요.
sidecar에서 연결할 수 있는 연결 문자열. 데이터베이스 사용자는 컬렉션 검색과 인덱스 목록 검색 권한이 필요해요. 데이터베이스의 네트워크 규칙으로 sidecar 호스트를 허용해요.
문서에 사용한 임베딩 모델. 쿼리 임베딩은 저장된 벡터와 같은 모델·출력 차원을 사용해야 해요. 같은 차원의 다른 모델은 오류 없이 무관한 결과를 반환할 수 있어요.

LiteLLM을 정상 설치해요. MongoDB 드라이버는 별도의 sidecar에서만 실행돼요:

pip install 'litellm[proxy]'

직접 Python SDK 사용 시 litellm을 설치하고 sidecar를 배포한 뒤 Python SDK로 검색을 따르세요. SDK나 표준 LiteLLM 이미지 모두 PyMongo가 필요 없어요. LiteLLM은 sidecar를 자동으로 시작하거나 설치하지 않아요.

모델 선택

Proxy 요청에는 구성된 LiteLLM proxy를 사용해요. UI·관리 API를 통한 등록도 proxy 데이터베이스가 필요해요. Admin UI의 Models 아래나 기존 model_list 구성에 모델을 추가하세요:

모델	용도	요구사항
임베딩 모델	각 검색 쿼리를 벡터로 변환	컬렉션을 임베딩하는 데 쓴 모델 및 차원과 일치해야 함
채팅 모델	검색된 텍스트에서 답변 생성	LiteLLM 지원 채팅 모델. 채팅 완성에만 필요

sidecar 배포

MongoDB 연결 문자열마다 sidecar 하나를 실행해요. 여러 LiteLLM 등록이 그 sidecar를 사용해 같은 MongoDB 사용자에게 접근 가능한 데이터베이스·컬렉션·인덱스에 쓸 수 있어요. sidecar가 공식 MongoDB 드라이버를 실행하고, LiteLLM은 계속 설정된 모델로 쿼리 임베딩을 생성하며 채팅 요청을 정상 라우팅해요.

sidecar 배포 시크릿에 MONGODB_CONNECTION_STRING과 강한 MONGODB_SIDECAR_API_KEY를 설정해요. LiteLLM에 같은 sidecar 키를 주세요. MongoDB 자격 증명과 TLS 파일은 sidecar 환경에 둬요.

Docker:

docker run --rm --name mongodb-sidecar \
  -p 127.0.0.1:8080:8080 \
  -e MONGODB_CONNECTION_STRING \
  -e MONGODB_SIDECAR_API_KEY \
  ghcr.io/berriai/litellm-mongodb:v0.1.0-beta.1

Sidecar URL로 http://127.0.0.1:8080을 사용해요. 릴리스 태그 또는 다이제스트를 고정하세요. 이미지는 Linux amd64·arm64를 지원하며 사용자 10001:10001로 실행돼요.

완전한 Docker Compose, Kubernetes/Helm 구성은 원문 문서를 참고해요. LiteLLM은 원격 sidecar에 HTTPS를 요구하며, 두 프로세스가 같은 호스트·네트워크 네임스페이스를 공유할 때만 HTTP 루프백 IP(예: 127.0.0.1, [::1])를 허용해요.

인덱스 연결

기존 인덱스를 한 번 등록한 뒤 요청에서 ID로 참조해요. 등록은 인덱스를 만들지 않고, 문서를 ingest하지 않으며, 연결이 동작하는지 확인하지 않아요.

요구 값

값	어디서 찾나
`<index_name>`	MongoDB Vector Search 인덱스의 정확한 이름. LiteLLM `vector_store_id`가 됨
`<db>` / `<collection>`	문서를 담은 데이터베이스와 컬렉션
`<vector_field>`	인덱스 정의의 벡터 `path`
`<text_field>`	읽을 수 있는 텍스트를 담은 문서 필드 (예: `text` 또는 `metadata.body`)
`<embedding_model>`	LiteLLM proxy에 등록된 임베딩 모델 이름
`<chat_model>`	LiteLLM proxy에 등록된 채팅 모델 이름

인덱스는 검색 전에 READY이고 쿼리 가능해야 해요.

config.yaml 등록:

vector_store_registry:
  - vector_store_name: ""
    litellm_params:
      vector_store_id: ""
      custom_llm_provider: mongodb
      api_base: http://127.0.0.1:8080
      api_key: os.environ/MONGODB_SIDECAR_API_KEY
      mongodb_database: ""
      mongodb_collection: ""
      mongodb_text_field: ""
      mongodb_embedding_field: ""
      litellm_embedding_model: ""

litellm --config config.yaml --port 4000

환경 변수는 실행 중인 proxy 프로세스에 사용 가능해야 해요. Docker에서는 --env-file 또는 -e로 전달해요. 호스트의 .env 파일은 컨테이너 안에서 자동으로 사용할 수 없어요.

Management API 등록:

curl -X POST 'http://localhost:4000/vector_store/new' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "vector_store_id": "",
    "custom_llm_provider": "mongodb",
    "vector_store_name": "",
    "litellm_params": {
      "api_base": "http://127.0.0.1:8080",
      "api_key": "",
      "mongodb_database": "",
      "mongodb_collection": "",
      "mongodb_text_field": "",
      "mongodb_embedding_field": "",
      "litellm_embedding_model": ""
    }
  }'

채팅 완성에서 MongoDB 사용

file_search 도구로 참조하는 등록된 인덱스 ID와 함께 /v1/chat/completions를 호출해요. LiteLLM이 같은 요청에서 컨텍스트를 검색하고 채팅 모델을 호출해요.

curl -X POST 'http://localhost:4000/v1/chat/completions' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "",
    "messages": [
      {
        "role": "system",
        "content": "Answer using the provided context. If the context does not contain the answer, say you do not know."
      },
      {
        "role": "user",
        "content": ""
      }
    ],
    "tools": [
      {
        "type": "file_search",
        "vector_store_ids": [""]
      }
    ]
  }'

OpenAI Python SDK:

import os

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000/v1",
    api_key=os.environ["LITELLM_API_KEY"],
)

response = client.chat.completions.create(
    model="",
    messages=[
        {
            "role": "system",
            "content": "Answer using the provided context. If the context does not contain the answer, say you do not know.",
        },
        {"role": "user", "content": ""},
    ],
    extra_body={
        "tools": [{"type": "file_search", "vector_store_ids": [""]}]
    },
)

message = response.model_dump()["choices"][0]["message"]
print(message["content"])

# Inspect the documents retrieved for this answer.
for page in (message.get("provider_specific_fields") or {}).get("search_results", []):
    for result in page["data"]:
        print(result["file_id"], result["score"], result["content"])

LiteLLM은 스토어에 설정된 임베딩 모델로 마지막 사용자 메시지를 임베딩하고, MongoDB의 $vectorSearch aggregation을 실행하며, 검색된 텍스트를 대화에 추가해요. 그러면 채팅 모델이 choices[0].message.content에서 답변을 생성해요.

vector_store_ids에는 정확한 인덱스 이름을 사용하세요. 등록의 표시 이름이 아닙니다.

검색 확인

성공한 검색은 그 문서들을 choices[0].message.provider_specific_fields.search_results에 반환해요. 텍스트와 점수를 검사해 답변에 관련 소스 자료가 있는지 확인하세요.

성공한 채팅 응답만으로 MongoDB 검색이 동작했다는 증거는 아니에요. 채팅은 검색이 실패해도 완료될 수 있어요. 소스가 없으면 직접 검색을 실행해 연결을 독립적으로 진단하세요.

인덱스 직접 검색

채팅 응답을 생성하지 않고 문서를 검색하려면 직접 검색을 사용해요.

curl -X POST 'http://localhost:4000/v1/vector_stores/<index>/search' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "",
    "max_num_results": 3
  }'

결과가 응답의 data 배열에 나타나요:

응답 필드	의미
`content`	설정된 `mongodb_text_field`에서 읽은 텍스트
`file_id` / `filename`	문자열로 변환된 MongoDB 문서의 `_id`
`score`	MongoDB의 `vectorSearchScore`. 값이 높을수록 더 유사함. 점수는 답변 신뢰도 백분율이 아님

max_num_results는 기본 10이며 1~50 값을 받아요.

Python SDK로 검색

sidecar 설정을 litellm.vector_stores.search에 직접 전달해요. proxy 등록은 필요 없어요. SDK 프로세스 환경에서 MONGODB_SIDECAR_API_KEY와 임베딩 제공사 자격 증명을 설정해요. MongoDB URI는 별도로 배포된 sidecar에 있어요.

import os

import litellm

response = litellm.vector_stores.search(
    vector_store_id="",
    query="",
    custom_llm_provider="mongodb",
    api_base="http://127.0.0.1:8080",
    api_key=os.environ["MONGODB_SIDECAR_API_KEY"],
    mongodb_database="",
    mongodb_collection="",
    mongodb_text_field="",
    mongodb_embedding_field="",
    litellm_embedding_model="/",
    max_num_results=3,
)

print(response)

비동기 사용은 같은 인자로 await litellm.vector_stores.asearch(...)를 호출해요. 직접 SDK에서는 제공사 임베딩 모델 이름을, proxy에서는 등록된 임베딩 모델 이름을 사용해요.

설정 레퍼런스

등록된 스토어의 litellm_params 또는 직접 SDK 검색의 키워드 인자로 전달해요.

설정	필수	설명
`vector_store_id`	예	정확한 MongoDB Vector Search 인덱스 이름
`custom_llm_provider`	예	`mongodb`로 설정
`api_base`	예	Sidecar HTTPS origin 또는 reverse-proxy 경로 접두사. HTTP는 리터럴 루프백 IP에만 지원. `/v1` 붙이지 말 것
`api_key`	예	Sidecar bearer 키. `MONGODB_SIDECAR_API_KEY`로도 제공 가능
`mongodb_database`	예	컬렉션을 담은 데이터베이스. URI에 데이터베이스 이름이 있어도 필수
`mongodb_collection`	예	문서와 벡터를 담은 컬렉션
`litellm_embedding_model`	예	쿼리를 임베딩하는 모델. 저장된 벡터에 쓴 모델과 일치해야 함
`mongodb_embedding_field`	아니오	인덱스가 덮는 벡터 필드. 기본 `embedding`
`mongodb_text_field`	아니오	읽을 수 있는 텍스트가 있는 필드. 기본 `text`; `metadata.body` 같은 점 경로 지원
`mongodb_num_candidates`	아니오	상위 결과 반환 전 고려되는 후보 수. 기본 `max(100, 10 * max_num_results)`. 명시 값은 `max_num_results` 이상, `10000` 이하
`litellm_embedding_config`	아니오	`dimensions`, `api_key`, `api_base` 같은 추가 임베딩 호출 인자. proxy에서는 가능하면 임베딩 모델 배포에 구성

검색 query는 비어 있지 않아야 하고 32,000자 이하여야 해요. 문자열 목록은 공백으로 결합되어 단일 쿼리로 임베딩돼요.

문제 해결

증상	확인할 것
이전 구성이 `pymongo`나 `mongodb_connection_string` 요구	BETA sidecar 어댑터를 담은 LiteLLM 릴리스 사용, sidecar 배포, `api_base`와 `api_key` 구성
HTTP 401: sidecar 인증 실패	LiteLLM의 `api_key`를 sidecar의 `MONGODB_SIDECAR_API_KEY`와 일치시킬 것. MongoDB 비밀번호 및 LiteLLM 클라이언트 키와 별개
HTTP 400: 인덱스 누락 또는 쿼리 불가	정확한 데이터베이스·컬렉션·인덱스 이름 확인, 인덱스 READY·쿼리 가능까지 대기
HTTP 400: 차원 불일치 또는 벡터 필드 미인덱스	쿼리 임베딩 모델과 차원을 문서와 일치시키고 `mongodb_embedding_field`를 인덱스 `path`와 일치시킬 것
HTTP 400: 일치 문서에 텍스트 필드 없음	`mongodb_text_field`를 읽을 수 있는 텍스트가 있는 필드로 (중첩이면 점 경로 포함)
HTTP 408 / 503	sidecar가 실행 중인지, URL이 도달 가능한지 확인 후 MongoDB 연결 확인

타임아웃·연결 끊김은 재시도 가능 오류(408, 503)를 반환해요. 연결이 복구되면 LiteLLM 재시작 없이 검색이 재개될 수 있어요.

BETA 제한 사항

검색만: 컬렉션·인덱스 생성, 문서 임베딩 생성, 문서 ingest는 LiteLLM 밖에서. MongoDB는 LiteLLM의 벡터 스토어 생성, 파일 관리, /rag/ingest API를 지원하지 않아요.
검색 필터링·쿼리 재작성 없음: filters, ranking_options, rewrite_query가 거부됩니다(rewrite_query: false 포함). 제공사 전용 mongodb_filter도 미지원·거부돼요.
MongoDB를 통한 자동 임베딩 없음: litellm_embedding_model을 구성하세요. MongoDB의 자동 임베딩 통합은 사용하지 않아요.
첫 등록은 채팅 요청에 도달하는 데 시간이 걸릴 수 있음: 실행 중인 proxy에 벡터 스토어 레지스트리가 아직 없으면, 첫 UI·API 등록은 file_search가 채팅 완성에서 동작하기 전에 데이터베이스 동기화나 재시작이 필요해요.

더 알아보기 (Learn more)

MongoDB Vector Search 문서
LiteLLM 벡터 스토어 레지스트리
LiteLLM RAG