/rag/ingest

/rag/ingest

문서 업로드 → 청크 분할 → 임베딩 → 벡터 스토어까지 처리하는 올인원 문서 수집 파이프라인 엔드포인트예요. OpenAI, Bedrock, Vertex AI, S3 Vectors 같은 다양한 벡터 스토어를 지원해요.

출처: 문서

본문

올인원 문서 수집 파이프라인: 업로드 → 청크 → 임베딩 → 벡터 스토어

기능	지원
로깅	예
지원 제공자	openai, bedrock, vertex_ai, gemini, s3_vectors

tip

문서를 수집한 후에는 /rag/query를 사용해 수집된 콘텐츠로 검색하고 응답을 생성할 수 있어요.

Quick Start

OpenAI

OpenAI 벡터 스토어로 수집

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

Bedrock

Bedrock Knowledge Base로 수집

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

Vertex AI RAG Engine

Vertex AI RAG Corpus로 수집

curl -X POST "http://localhost:4000/v1/rag/ingest" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d "{
        \"file\": {
            \"filename\": \"document.txt\",
            \"content\": \"$(base64 -i document.txt)\",
            \"content_type\": \"text/plain\"
        },
        \"ingest_options\": {
            \"vector_store\": {
                \"custom_llm_provider\": \"vertex_ai\",
                \"vector_store_id\": \"your-corpus-id\",
                \"gcs_bucket\": \"your-gcs-bucket\"
            }
        }
    }"

AWS S3 Vectors

전체 설정, IAM 권한, 검색 구성: AWS S3 Vectors. S3 Vectors로 수집

curl -X POST "http://localhost:4000/v1/rag/ingest" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d "{
        \"file\": {
            \"filename\": \"document.txt\",
            \"content\": \"$(base64 -i document.txt)\",
            \"content_type\": \"text/plain\"
        },
        \"ingest_options\": {
            \"embedding\": {
                \"model\": \"text-embedding-3-small\"
            },
            \"vector_store\": {
                \"custom_llm_provider\": \"s3_vectors\",
                \"vector_bucket_name\": \"my-embeddings\",
                \"aws_region_name\": \"us-west-2\"
            }
        }
    }"

응답

{
  "id": "ingest_abc123",
  "status": "completed",
  "vector_store_id": "vs_xyz789",
  "file_id": "file_123"
}

RAG로 쿼리하기

수집 후 /rag/query 엔드포인트를 사용해 검색하고 LLM 응답을 생성해요: RAG 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 is the main topic?"}],
        "retrieval_config": {
            "vector_store_id": "vs_xyz789",
            "custom_llm_provider": "openai",
            "top_k": 5
        }
    }'

이렇게 하면:

• 관련 컨텍스트를 위해 벡터 스토어를 검색해요.
• 컨텍스트를 메시지 앞에 붙여요.
• LLM 응답을 생성해요.

벡터 스토어 직접 검색

또는 /vector_stores/{vector_store_id}/search로 벡터 스토어를 직접 검색할 수도 있어요: Search the vector store

curl -X POST "http://localhost:4000/v1/vector_stores/vs_xyz789/search" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "query": "What is the main topic?",
        "max_num_results": 5
    }'

엔드투엔드 예시

OpenAI

1. 문서 수집

Step 1: Ingest

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

응답:

{
  "id": "ingest_d834f544-fc5e-4751-902d-fb0bcc183b85",
  "status": "completed",
  "vector_store_id": "vs_692658d337c4819183f2ad8488d12fc9",
  "file_id": "file-M2pJJiWH56cfUP4Fe7rJay"
}

2. 쿼리

Step 2: Query

curl -X POST "http://localhost:4000/v1/vector_stores/vs_692658d337c4819183f2ad8488d12fc9/search" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "query": "What is LiteLLM?",
        "custom_llm_provider": "openai"
    }'

응답:

{
  "object": "vector_store.search_results.page",
  "search_query": ["What is LiteLLM?"],
  "data": [
    {
      "file_id": "file-M2pJJiWH56cfUP4Fe7rJay",
      "filename": "test_document.txt",
      "score": 0.4004629778869299,
      "attributes": {},
      "content": [
        {
          "type": "text",
          "text": "Test document abc123 for RAG ingestion.\nThis is a sample document to test the RAG ingest API.\nLiteLLM provides a unified interface for vector stores."
        }
      ]
    }
  ],
  "has_more": false,
  "next_page": null
}

요청 파라미터

최상위

파라미터	타입	필수	설명
file	object	file/file_url/file_id 중 하나 필수	Base64 인코딩된 파일
file.filename	string	예	확장자를 포함한 파일명
file.content	string	예	Base64 인코딩된 콘텐츠
file.content_type	string	예	MIME 타입 (예: text/plain)
file_url	string	file/file_url/file_id 중 하나 필수	파일을 가져올 URL
file_id	string	file/file_url/file_id 중 하나 필수	기존 파일 ID
ingest_options	object	예	파이프라인 구성

ingest_options

파라미터	타입	필수	설명
vector_store	object	예	벡터 스토어 구성
name	string	아니요	로깅용 파이프라인 이름

등록된 스토어 vector_store.vector_store_id가 벡터 스토어 레지스트리에 있거나 이전 수집으로 저장된 스토어를 가리키면, 제공자, 자격 증명, 목적지 설정은 그 등록에서 가져와요. 요청은 업로드별 옵션(data_source_id, wait_for_ingestion, ingestion_timeout, custom_metadata, file_description, max_embedding_requests_per_min)만 유지하며, 보내진 다른 vector_store 키는 무시돼요. 수집 구현이 없는 custom_llm_provider는 지원 목록을 명시한 400으로 거부돼요.

vector_store (OpenAI)

파라미터	타입	기본값	설명
custom_llm_provider	string	-	"openai"
vector_store_id	string	자동 생성	기존 벡터 스토어 ID

vector_store (Bedrock)

파라미터	타입	기본값	설명
custom_llm_provider	string	-	"bedrock"
vector_store_id	string	자동 생성	기존 Knowledge Base ID
wait_for_ingestion	boolean	false	인덱싱 완료 대기
ingestion_timeout	integer	300	타임아웃(초, 대기 시)
s3_bucket	string	자동 생성	문서용 S3 버킷
s3_prefix	string	"data/"	S3 키 접두어
embedding_model	string	amazon.titan-embed-text-v2:0	Bedrock 임베딩 모델
aws_region_name	string	us-west-2	AWS 리전

Bedrock 자동 생성 vector_store_id를 생략하면 LiteLLM이 자동으로 생성해요:

• 문서 저장용 S3 버킷
• OpenSearch Serverless 컬렉션
• 필요한 권한이 있는 IAM 역할
• Bedrock Knowledge Base
• Data Source

vector_store (Vertex AI)

파라미터	타입	기본값	설명
custom_llm_provider	string	-	"vertex_ai"
vector_store_id	string	필수	RAG corpus ID
gcs_bucket	string	필수	파일 업로드용 GCS 버킷
vertex_project	string	env VERTEXAI_PROJECT	GCP 프로젝트 ID
vertex_location	string	us-central1	GCP 리전
vertex_credentials	string	ADC	자격 증명 JSON 경로
wait_for_import	boolean	true	임포트 완료 대기
import_timeout	integer	600	타임아웃(초, 대기 시)

Vertex AI 사전 요구 사항

• Vertex AI 콘솔 또는 API에서 RAG corpus 생성
• 파일 업로드용 GCS 버킷 생성
• gcloud auth application-default login으로 인증
• 설치: uv add 'google-cloud-aiplatform>=1.60.0'

vector_store (AWS S3 Vectors)

파라미터	타입	기본값	설명
custom_llm_provider	string	-	"s3_vectors"
vector_store_id	string	자동 생성	기존 인덱스(bucket:index) 또는 vector_bucket_name 안의 인덱스 이름
vector_bucket_name	string	vector_store_id가 bucket:index가 아니면 필수	S3 벡터 버킷 이름
index_name	string	자동 생성	벡터 인덱스 이름
dimension	integer	자동 감지	벡터 차원 (임베딩 모델에서 자동 감지)
distance_metric	string	cosine	거리 메트릭: cosine 또는 euclidean
non_filterable_metadata_keys	array	["source_text"]	필터링에서 제외되는 메타데이터 키
aws_region_name	string	us-west-2	AWS 리전
aws_access_key_id	string	env	AWS 액세스 키
aws_secret_access_key	string	env	AWS 시크릿 키

S3 Vectors 자동 생성 index_name을 생략하면 LiteLLM이 자동으로 생성해요:

• S3 벡터 버킷 (없으면)
• 임베딩 모델에서 자동 감지된 차원의 벡터 인덱스

차원 자동 감지: 벡터 차원은 지정된 모델에 테스트 임베딩 요청을 보내 자동으로 감지돼요. 차원을 수동으로 지정할 필요가 없어요!

지원되는 임베딩 모델: LiteLLM이 지원하는 어떤 임베딩 모델(OpenAI, Cohere, Bedrock, Azure 등)과도 동작해요.

자동 감지 예시:

{
  "embedding": {
    "model": "text-embedding-3-small"  // Dimension auto-detected as 1536
  },
  "vector_store": {
    "custom_llm_provider": "s3_vectors",
    "vector_bucket_name": "my-embeddings"
  }
}

커스텀 임베딩 제공자 예시:

{
  "embedding": {
    "model": "cohere/embed-english-v3.0"  // Dimension auto-detected as 1024
  },
  "vector_store": {
    "custom_llm_provider": "s3_vectors",
    "vector_bucket_name": "my-embeddings",
    "distance_metric": "cosine"
  }
}

입력 예시

파일 (Base64)

Request body

{
  "file": {
    "filename": "document.txt",
    "content": "<base64-encoded-content>",
    "content_type": "text/plain"
  },
  "ingest_options": {
    "vector_store": {"custom_llm_provider": "openai"}
  }
}

파일 URL

URL에서 수집

curl -X POST "http://localhost:4000/v1/rag/ingest" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "file_url": "https://example.com/document.pdf",
        "ingest_options": {"vector_store": {"custom_llm_provider": "openai"}}
    }'

청크 분할 전략

임베딩 전에 문서를 청크로 어떻게 나눌지 제어해요. ingest_options에서 chunking_strategy를 지정하세요.

파라미터	타입	기본값	설명
chunk_size	integer	1000	각 청크의 최대 크기
chunk_overlap	integer	200	연속 청크 간 겹침

Vertex AI RAG Engine

Vertex AI RAG Engine은 chunking_strategy 파라미터로 커스텀 청크 분할을 지원해요. 청크는 임포트 중 서버 측에서 처리돼요. Vertex AI with custom chunking

curl -X POST "http://localhost:4000/v1/rag/ingest" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d "{
        \"file\": {
            \"filename\": \"document.txt\",
            \"content\": \"$(base64 -i document.txt)\",
            \"content_type\": \"text/plain\"
        },
        \"ingest_options\": {
            \"chunking_strategy\": {
                \"chunk_size\": 500,
                \"chunk_overlap\": 100
            },
            \"vector_store\": {
                \"custom_llm_provider\": \"vertex_ai\",
                \"vector_store_id\": \"your-corpus-id\",
                \"gcs_bucket\": \"your-gcs-bucket\"
            }
        }
    }"

더 알아보기 (Learn more)

• /rag/query