/vector_stores - Create Vector Store

검색 증강 생성(RAG) 사용 사례를 위해 문서 청크를 저장하고 검색하는 데 사용할 수 있는 벡터 스토어를 만듭니다.

개요

proxy는 벡터 스토어의 조회(retrieve), 목록(list), 업데이트(update), **삭제(delete)**도 지원합니다(OpenAI 호환). curl 예시와 제공자 라우팅은 proxy의 Vector store management and routing을 참고하세요.

생성 vs 등록

POST /v1/vector_stores(이 페이지)는 제공자에 새 스토어를 만들며 create 구현이 있는 제공자에서만 동작합니다(개요 매트릭스 참조). 스토어가 제공자에 이미 존재한다면(Bedrock Knowledge Base, Vertex AI Search datastore, Azure AI Search index 등) 대신 POST /vector_store/new를 사용해 LiteLLM에 등록하면 통합 API로 검색할 수 있어요. Managed Vector Stores를 참고하세요.

사용법

LiteLLM Python SDK

Basic Usage
Advanced Configuration
OpenAI Provider

Async 예시

Create Vector Store - Basic

import litellmresponse = await litellm.vector_stores.acreate(
    name="My Document Store",
    file_ids=["file-abc123", "file-def456"])print(response)

Sync 예시

Create Vector Store - Sync

import litellmresponse = litellm.vector_stores.create(
    name="My Document Store",
    file_ids=["file-abc123", "file-def456"])print(response)

만료 및 청킹 전략 포함

Create Vector Store - Advanced

import litellmresponse = await litellm.vector_stores.acreate(
    name="My Document Store",
    file_ids=["file-abc123", "file-def456"],
    expires_after={
        "anchor": "last_active_at",
        "days": 7
    },
    chunking_strategy={
        "type": "static",
        "static": {
            "max_chunk_size_tokens": 800,
            "chunk_overlap_tokens": 400
        }
    },
    metadata={
        "project": "rag-system",
        "environment": "production"
    })print(response)

OpenAI 제공자를 명시적으로 사용

Create Vector Store - OpenAI Provider

import litellmimport os# Set API keyos.environ["OPENAI_API_KEY"] = "your-openai-api-key"response = await litellm.vector_stores.acreate(
    name="My Document Store",
    file_ids=["file-abc123", "file-def456"],
    custom_llm_provider="openai")print(response)

LiteLLM Proxy Server

Setup & Usage
curl (create)
curl (retrieve, list, update, delete)
config.yaml 설정

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEYgeneral_settings:
  # Vector store settings can be added here if needed

Proxy 시작

litellm --config /path/to/config.yaml

OpenAI SDK로 테스트! OpenAI SDK via LiteLLM Proxy

from openai import OpenAI# Point OpenAI SDK to LiteLLM proxyclient = OpenAI(
    base_url="http://0.0.0.0:4000",
    api_key="sk-",  # Your LiteLLM API key)vector_store = client.beta.vector_stores.create(
    name="My Document Store",
    file_ids=["file-abc123", "file-def456"])print(vector_store)

Create Vector Store via curl

curl -L -X POST 'http://0.0.0.0:4000/v1/vector_stores' \-H 'Content-Type: application/json' \-H "Authorization: Bearer ***" \-d '{
  "name": "My Document Store",
  "file_ids": ["file-abc123", "file-def456"],
  "expires_after": {
    "anchor": "last_active_at",
    "days": 7
  },
  "chunking_strategy": {
    "type": "static",
    "static": {
      "max_chunk_size_tokens": 800,
      "chunk_overlap_tokens": 400
    }
  },
  "metadata": {
    "project": "rag-system",
    "environment": "production"
  }}'

create와 같은 base URL과 API key를 사용하세요. vs_abc123을 여러분의 벡터 스토어 id로 바꾸세요.

Retrieve

curl -L 'http://0.0.0.0:4000/v1/vector_stores/vs_abc123' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ***"

List(선택 쿼리 params: after, before, limit, order)

curl -L 'http://0.0.0.0:4000/v1/vector_stores?limit=20&order=desc' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ***"

Update(POST with JSON body)

curl -L -X POST 'http://0.0.0.0:4000/v1/vector_stores/vs_abc123' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ***" \
  -d '{ "name": "Renamed store", "metadata": { "env": "staging" } }'

Delete

curl -L -X DELETE 'http://0.0.0.0:4000/v1/vector_stores/vs_abc123' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ***"

제공자 라우팅 세부 사항과 OpenAI API 참조는 proxy의 Vector store management and routing을 참고하세요.

OpenAI SDK (Standalone)

Direct OpenAI UsageOpenAI SDK Direct

from openai import OpenAIclient = OpenAI(api_key="your-openai-api-key")vector_store = client.beta.vector_stores.create(
    name="My Document Store",
    file_ids=["file-abc123", "file-def456"])print(vector_store)

Proxy에서의 벡터 스토어 관리 및 라우팅

create(POST /v1/vector_stores 또는 /vector_stores) 외에도 LiteLLM proxy는 OpenAI 호환 retrieve, list, update, delete를 노출합니다. 경로는 /v1 프리픽스가 있든 없든 동작합니다(예: /v1/vector_stores/... 및 /vector_stores/...).

search는 Search vector store를, 스토어의 files는 Vector store files를 참고하세요.

인증

LiteLLM proxy virtual key를 다음 중 하나와 함께 사용하세요:

-H "Authorization: Bearer ***"# or-H 'x-litellm-api-key: ***

제공자 라우팅

LiteLLM은 추가 쿼리 파라미터 없이 요청 컨텍스트에서 벡터 스토어 제공자를 자동으로 선택합니다:

LiteLLM-managed stores — vector_store_id가 LiteLLM-managed 스토어면 proxy가 레지스트리(데이터베이스에 저장된 litellm_params)에서 제공자를 해석합니다.
Model-based routing — 요청에 구성된 배포/모델 그룹과 일치하는 model이 있으면 자격 증명이 그 배포에서 옵니다.
SDK default — 둘 다 아니면 그 호출에 대한 LiteLLM SDK 기본값(예: openai)이 사용됩니다.

OpenAI API reference (management operations)

Retrieve vector store
List vector stores
Modify vector store — LiteLLM proxy에서 modify는 JSON body와 함께 /v1/vector_stores/{vector_store_id}로의 POST 입니다.
Delete vector store

요청 형식

요청 본문은 OpenAI의 벡터 스토어 API 형식을 따릅니다.

예시 요청 본문

{
  "name": "My Document Store",
  "file_ids": ["file-abc123", "file-def456"],
  "expires_after": {
    "anchor": "last_active_at",
    "days": 7
  },
  "chunking_strategy": {
    "type": "static",
    "static": {
      "max_chunk_size_tokens": 800,
      "chunk_overlap_tokens": 400
    }
  },
  "metadata": {
    "project": "rag-system",
    "environment": "production"
  }
}

선택 필드

name (string): 벡터 스토어의 이름.
file_ids (array of strings): 벡터 스토어가 사용해야 할 File ID 목록. file_search처럼 파일에 접근할 수 있는 도구에 유용함.
expires_after (object): 벡터 스토어의 만료 정책.
- anchor (string): 만료 정책이 적용되는 기준 타임스탬프. 지원 앵커: last_active_at.
- days (integer): 앵커 시간 이후 벡터 스토어가 만료되는 일수.
chunking_strategy (object): 파일을 청킹하는 데 사용되는 전략. 설정하지 않으면 auto 전략을 사용함.
- type (string): 항상 static.
- static (object): 정적 청킹 전략.
  - max_chunk_size_tokens (integer): 각 청크의 최대 토큰 수. 기본값 800. 최소 100, 최대 4096.
  - chunk_overlap_tokens (integer): 청크 사이에 겹치는 토큰 수. 기본값 400.
metadata (object): 객체에 첨부할 수 있는 16개 키-값 쌍. 객체에 대한 추가 정보를 구조화된 형식으로 저장하는 데 유용함. 키는 최대 64자, 값은 최대 512자.

응답 형식

예시 응답

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "My Document Store",
  "bytes": 139920,
  "file_counts": {
    "in_progress": 0,
    "completed": 2,
    "failed": 0,
    "cancelled": 0,
    "total": 2
  },
  "status": "completed",
  "expires_after": {
    "anchor": "last_active_at",
    "days": 7
  },
  "expires_at": null,
  "last_active_at": 1699061776,
  "metadata": {
    "project": "rag-system",
    "environment": "production"
  }
}

응답 필드

id (string): API 엔드포인트에서 참조할 수 있는 식별자.
object (string): 객체 유형. 항상 vector_store.
created_at (integer): 벡터 스토어가 생성된 Unix 타임스탬프(초).
name (string): 벡터 스토어의 이름.
bytes (integer): 벡터 스토어의 파일이 사용하는 총 바이트 수.
file_counts (object): 벡터 스토어의 파일 수.
- in_progress (integer): 현재 처리 중인 파일 수.
- completed (integer): 성공적으로 처리된 파일 수.
- failed (integer): 처리에 실패한 파일 수.
- cancelled (integer): 취소된 파일 수.
- total (integer): 총 파일 수.
status (string): 벡터 스토어의 상태. expired, in_progress, completed 중 하나. completed는 벡터 스토어를 사용할 준비가 됐음을 의미함.
expires_after (object or null): 벡터 스토어의 만료 정책.
expires_at (integer or null): 벡터 스토어가 만료되는 Unix 타임스탬프(초).
last_active_at (integer or null): 벡터 스토어가 마지막으로 활성화된 Unix 타임스탬프(초).
metadata (object or null): 객체에 첨부할 수 있는 16개 키-값 쌍.

Mock Response 테스팅

테스트 목적으로 mock 응답을 사용할 수 있어요:

Mock Response Example

import litellm# Mock response for testingmock_response = {
    "id": "vs_mock123",
    "object": "vector_store",
    "created_at": 1699061776,
    "name": "Mock Vector Store",
    "bytes": 0,
    "file_counts": {
        "in_progress": 0,
        "completed": 0,
        "failed": 0,
        "cancelled": 0,
        "total": 0
    },
    "status": "completed"}response = await litellm.vector_stores.acreate(
    name="Test Store",
    mock_response=mock_response)print(response)

/vector_stores - Create Vector Store