AWS S3 벡터

AWS S3 벡터 (Vectors)

LiteLLM의 통합 벡터 스토어와 RAG 엔드포인트의 백엔드로 Amazon S3 Vectors를 사용하는 방법을 알아봐요.

출처: 문서

본문

LiteLLM은 SigV4 서명 요청으로 S3 Vectors REST API를 직접 호출해요. 벡터 연산 자체에는 boto3 클라이언트가 필요 없어요.

속성	내용
LiteLLM 라우트	`s3_vectors`
지원 엔드포인트	`POST /v1/vector_stores/{id}/search`, `POST /rag/ingest`, `POST /rag/query`, `/chat/completions`와 `/v1/responses`의 `file_search`
미지원	`POST /v1/vector_stores` (OpenAI 형태의 생성). `/rag/ingest`를 사용하면 벡터 버킷과 인덱스를 자동 생성
벡터 스토어 id 형식	`:`
제공사 문서	Amazon S3 Vectors ↗

동작 원리

/rag/ingest는 문서를 받아 청킹하고, 어떤 LiteLLM 임베딩 모델로든 임베딩을 생성한 뒤, 벡터를 S3 벡터 버킷 안의 인덱스에 써 넣어요(PutVectors). 버킷과 인덱스는 없으면 자동 생성돼요. 결과 스토어는 다른 모든 곳에서 bucket_name:index_name으로 주소가 지정돼요. /v1/vector_stores/{id}/search는 설정된 임베딩 모델로 쿼리를 임베딩하고 해당 인덱스에 대해 QueryVectors를 실행하며, 동일한 id가 /chat/completions와 /v1/responses의 file_search 도구에서 동작해요.

proxy에서는 성공적인 ingest가 스토어를 LiteLLM 데이터베이스에 등록하므로(아래 "추적 및 접근 제어" 참조) Admin UI에 나타나고, 요청별 AWS 구성 없이 id로 검색할 수 있어요.

빠른 시작

1. config.yaml 설정

ingest와 search에는 임베딩 모델이 필요해요. AWS 자격 증명은 환경에서 오며(다른 지원 방식은 Credentials 참조) config.yaml:

model_list:
  - model_name: text-embedding-3-small
    litellm_params:
      model: openai/text-embedding-3-small
      api_key: os.environ/OPENAI_API_KEY

환경:

export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_REGION_NAME="us-west-2"

litellm --config config.yaml

2. 문서 ingest

vector_store 블록에서 custom_llm_provider: "s3_vectors"를 전달해요. 여기서 aws_region_name과 embedding_model을 설정하는 것이 중요해요. vector_store 블록의 모든 키는 스토어 등록에 영속되므로, 이후 등록된 스토어에 대한 검색이 이를 자동으로 재사용해요.

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\",
                \"embedding_model\": \"text-embedding-3-small\"
            }
        }
    }"

응답:

{
  "id": "ingest_abc123",
  "status": "completed",
  "vector_store_id": "my-embeddings:litellm-index-a1b2c3d4",
  "file_id": "document.txt"
}

index_name이 생략되면 LiteLLM이 하나(litellm-index-)를 생성해요. 요청 간에 같은 인덱스로 계속 ingest하려면 명시적 index_name을 전달해요. 전체 ingest 옵션 목록은 RAG Ingest 레퍼런스에 있어요.

임베딩 모델 일관성 유지: 인덱스 차원은 ingest 임베딩 모델에서 생성 시점에 고정돼요(자동 감지, 예: text-embedding-3-small은 1536). 검색은 같은 차원의 모델로 쿼리를 임베딩해야 해요. vector_store 블록(위처럼) 또는 레지스트리 항목에 embedding_model을 설정하세요. 어디에도 없으면 검색은 text-embedding-3-small로 폴백해요.

3. 스토어 검색

curl -X POST "http://localhost:4000/v1/vector_stores/my-embeddings:litellm-index-a1b2c3d4/search" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{"query": "What does the document say about pricing?", "max_num_results": 5}'

응답:

{
  "object": "vector_store.search_results.page",
  "search_query": "What does the document say about pricing?",
  "data": [
    {
      "score": 0.87,
      "content": [{"text": "Pricing is based on ...", "type": "text"}],
      "file_id": "s3-vectors-chunk-0",
      "filename": "document.txt",
      "attributes": {"source_text": "Pricing is based on ...", "chunk_index": "0", "filename": "document.txt"}
    }
  ]
}

max_num_results는 S3 Vectors topK(기본값 5)에 매핑돼요. 결과는 LiteLLM이 ingest 시 작성하는 source_text 메타데이터 키에서 읽으며, 해당 키가 없는 다른 도구가 쓴 벡터는 건너뛰어요.

4. 채팅 완성에서 RAG로 사용

curl -X POST "http://localhost:4000/v1/chat/completions" \
    -H "Authorization: Bearer ***" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-5.6-terra",
        "messages": [{"role": "user", "content": "Summarize our pricing policy"}],
        "tools": [{"type": "file_search", "vector_store_ids": ["my-embeddings:litellm-index-a1b2c3d4"]}]
    }'

/rag/query(검색과 완성을 한 번에)도 같은 스토어 id로 동작해요.

기존 인덱스 등록

벡터 버킷과 인덱스가 이미 존재한다면(이전 ingest, 다른 도구, Terraform으로 생성) 벡터 스토어 레지스트리에 등록해서 proxy의 모든 키가 검색할 수 있게 해요:

config.yaml:

vector_store_registry:
  - vector_store_name: "product-docs"
    litellm_params:
      vector_store_id: "my-embeddings:my-index"
      custom_llm_provider: "s3_vectors"
      aws_region_name: "us-west-2"
      embedding_model: "text-embedding-3-small"

검색에는 aws_region_name이 필수예요. embedding_model은 인덱스가 만들어진 모델과 일치해야 해요. bucket:index id 대신 litellm_params에 vector_bucket_name을 설정하고 vector_store_id로 일반 인덱스 이름을 사용할 수도 있어요. 등록 후, 스토어 id를 지칭하는 /rag/ingest 요청도 해당 인덱스로 들어가며, 제공사·리전·자격 증명·임베딩 모델을 요청 대신 등록에서 가져와요.

구성 레퍼런스

검색 측 litellm_params(레지스트리 항목 또는 ingest에서 자동 영속):

파라미터	필수	설명
`custom_llm_provider`	예	`"s3_vectors"`
`vector_store_id`	예	`bucket:index`, 또는 `vector_bucket_name` 설정 시 일반 인덱스 이름
`aws_region_name`	예	벡터 버킷의 리전
`embedding_model`	아니오	검색 쿼리를 임베딩하는 모델. 기본 `text-embedding-3-small`
`vector_bucket_name`	아니오	`vector_store_id`가 일반 인덱스 이름이 되게 함
`aws_access_key_id`, `aws_secret_access_key`, `aws_session_token`, `aws_role_name`, `aws_session_name`, `aws_profile_name`, `aws_web_identity_token`	아니오	명시적 AWS 자격 증명 (Credentials 참조)
`litellm_credential_name`	아니오	`credential_list`에서 이름 있는 자격 증명 참조

ingest 측 옵션(ingest_options의 vector_store 블록)은 RAG Ingest 레퍼런스에 문서화돼 있어요: vector_store_id(기존 인덱스 bucket:index 또는, vector_bucket_name 설정 시 일반 인덱스 이름), vector_bucket_name(vector_store_id가 버킷을 담지 않으면 필수), index_name, dimension, distance_metric(cosine 기본값 또는 euclidean), non_filterable_metadata_keys(기본값 ["source_text"]), 그리고 동일한 AWS 자격 증명 파라미터들.

리전, 엔드포인트, 암호화

LiteLLM은 항상 지역 S3 Vectors 엔드포인트 https://s3vectors.<region>.api.aws를 호출해요. 이 제공사에는 api_base 오버라이드가 없어요. ingest의 리전은 요청의 aws_region_name, 그다음 AWS_REGION_NAME과 AWS_REGION 환경 변수, 마지막으로 us-west-2 폴백 순으로 결정돼요. 검색에는 aws_region_name이 레지스트리 항목이나 영속된 ingest 파라미터에 있어야 해요.

자동 생성된 벡터 버킷은 S3 Vectors 기본 서버 측 암호화(SSE-S3)를 사용해요. LiteLLM은 CreateVectorBucket에 암호화 구성을 전달하지 않으므로, SSE-KMS를 사용하려면 KMS 키로 벡터 버킷을 직접 만들고 LiteLLM이 그 버킷을 가리키게 하면 돼요. 존재 확인이 버킷을 보고 생성을 건너뛰어요. 버킷 이름은 S3 규칙을 따르며(최소 3자, 소문자, 숫자, 하이픈, 마침표만) vector_bucket_name은 그 밖의 S3 규칙을 따라야 해요.

자격 증명

인증은 LiteLLM의 표준 AWS 자격 증명 해석(Bedrock과 같은 BaseAWSLLM 체인)을 재사용해요. 순서는: 레지스트리 항목이나 ingest 요청의 명시적 aws_* 파라미터, litellm_credential_name으로 이름 있는 자격 증명, 환경 변수(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN), aws_profile_name, aws_role_name과 aws_session_name으로 STS 역할 위임, 웹 ID 토큰(EKS의 IRSA), 마지막으로 기본 boto3 체인(인스턴스 프로파일, ECS 태스크 역할)이에요. 각 방법에 대한 자세한 내용은 Bedrock 인증을 참고해요.

IAM 권한

액션	필요한 곳
`s3vectors:QueryVectors`	search, `/rag/query`, `file_search`
`s3vectors:PutVectors`	`/rag/ingest`
`s3vectors:GetVectorBucket`	`/rag/ingest` 존재 확인
`s3vectors:CreateVectorBucket`	`/rag/ingest` 자동 생성
`s3vectors:GetIndex`	`/rag/ingest` 존재 확인
`s3vectors:CreateIndex`	`/rag/ingest` 자동 생성

사전 생성된 버킷과 인덱스를 쓰는 경우 최소 ingest 정책은 GetVectorBucket, GetIndex, PutVectors이고, 검색 전용 자격 증명은 QueryVectors만 필요해요. proxy는 임베딩 모델이 요구하는 자격 증명도 필요해요(위 빠른 시작의 OpenAI 키, 또는 AWS 안에 머무르려면 bedrock/amazon.titan-embed-text-v2:0).

ingest된 파일 추적 방식

데이터베이스 연결 proxy에서 /rag/ingest는 호출 키의 team_id와 user_id로 새 스토어를 LiteLLM_ManagedVectorStoresTable에 저장하고, 인메모리 레지스트리에 추가하며, 각 ingest된 파일(파일명 또는 URL, 타임스탬프)을 스토어의 ingested_files 메타데이터에 기록해요. 같은 버킷과 인덱스에 다시 ingest하면 새 항목을 만들지 않고 파일 목록에 추가돼요. 이후 스토어는 Admin UI의 Vector Stores에 나타나며, 접근은 표준 벡터 스토어 권한 모델을 따릅니다. 키나 팀의 object_permission.vector_stores를 설정해 요청이 참조할 수 있는 스토어 id를 제어할 수 있어요.

원본 파일 바이트는 S3나 LiteLLM 데이터베이스에 저장되지 않아요. 청크 텍스트(벡터 메타데이터의 source_text로)와 파일 메타데이터만 유지돼요.

"기본 벡터 스토어" 설정이 있나요?

아니요. LiteLLM에는 오늘날 proxy 전역 기본 벡터 스토어 제공사가 없어요. /rag/ingest는 vector_store 블록에서 제공사를 생략하면 custom_llm_provider: "openai"를 기본값으로 해요. 따라서 S3 Vectors에 저장돼야 하는 모든 ingest 요청은 명시적으로 custom_llm_provider: "s3_vectors"를 전달해야 해요. 단, vector_store_id가 레지스트리나 데이터베이스의 스토어를 지칭한다면 제공사·리전·자격 증명·임베딩 모델이 그 등록에서 오므로 요청에는 id만 필요해요. ingest 후에는 다른 곳에서 제공사 선택이 필요 없어요. 검색, /rag/query, file_search 모두 id로 스토어에 주소를 지정하고, 영속된 등록이 제공사와 AWS 설정을 담고 있어요.

S3가 /v1/files의 기본 스토리지가 될 수 있나요?

오늘날에는 아니에요. /v1/files 업로드는 대상 LLM 제공사(OpenAI, Azure, Bedrock, Vertex)로 가며, target_storage 업로드 파라미터의 유일한 대체 스토리지 백엔드는 azure_storage(Azure Blob Storage)이고 S3 스토리지 백엔드는 없어요. S3에 인접한 두 경로는 있어요. Bedrock 배치용으로 업로드된 파일은 모델의 s3_bucket_name 파라미터를 통해 S3 버킷에 스테이징되고, 이 페이지의 RAG 흐름에는 파일 스토리지가 전혀 필요 없어요. /rag/ingest가 파일을 인라인(multipart 또는 base64), file_url, 또는 기존 제공사 file_id로 받기 때문이에요.

검증

ingest 후 파이프라인을 끝에서 끝까지 확인하세요: ingest 응답에 "status": "completed"와 vector_store_id가 있고, 해당 id에 대한 검색이 data[].content에 문서 텍스트를 반환하며, Admin UI가 Vector Stores 아래에 스토어를 나열하고, AWS 콘솔에서 벡터 버킷과 인덱스가 구성된 리전의 Amazon S3 > Vector buckets에 보이는지 확인하세요. 검색이 빈 data 배열을 반환하면 쿼리 임베딩 모델이 ingest 모델과 일치하는지(차원 불일치는 S3 Vectors가 거부), 벡터가 source_text 메타데이터를 담는지 확인하세요.

더 알아보기 (Learn more)

Amazon S3 Vectors 공식 문서
LiteLLM RAG 기능
LiteLLM 벡터 스토어 레지스트리