프로바이더 파일 엔드포인트

프로바이더 파일 엔드포인트 (Provider Files Endpoints)

파일은 Assistants, Fine-tuning, Batch API 같은 기능과 함께 사용할 수 있는 문서를 업로드하는 데 사용됩니다.

이것을 사용해 프로바이더의 /files 엔드포인트를 OpenAI 형식으로 직접 호출하세요.

빠른 시작

파일 업로드
파일 목록
파일 정보 가져오기
파일 삭제
파일 콘텐츠 가져오기

다중 계정 지원 (여러 OpenAI 키)

model_list 의 항목을 참조하는 모델 파라미터를 지정해 파일과 배치에 서로 다른 OpenAI API 키를 사용하세요. 이 방법은 데이터베이스 없이 동작하며 파일/배치를 다른 OpenAI 계정으로 라우팅할 수 있게 합니다.

동작 방식

model_list 에 서로 다른 API 키로 모델 정의
파일을 만들 때 모델 파라미터 전달
LiteLLM이 라우팅 정보가 포함된 인코딩된 ID 반환
인코딩된 ID를 이후 모든 작업(조회, 삭제, 배치)에 사용
모델을 다시 지정할 필요 없음 - 라우팅 정보가 ID에 있음

설정

model_list:
  # litellm OpenAI Account
  - model_name: "gpt-4o-litellm"
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_LITELLM_API_KEY
  
  # Free OpenAI Account
  - model_name: "gpt-4o-free"
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_FREE_API_KEY

사용 예시

from openai import OpenAI

client = OpenAI(
    api_key="sk-<your-litellm-api-key>",  # Your LiteLLM proxy key
    base_url="http://0.0.0.0:4000"
)

# Create file using litellm account
file_response = client.files.create(
    file=open("batch_data.jsonl", "rb"),
    purpose="batch",
    extra_body={"model": "gpt-4o-litellm"}  # Routes to litellm key
)
print(f"File ID: {file_response.id}")
# Returns encoded ID like: file-bGl0ZWxsbTpmaWxlLWFiYzEyMzttb2RlbCxncHQtNG8taWZvb2Q

# Create batch using the encoded file ID
# No need to specify model again - it's embedded in the file ID
batch_response = client.batches.create(
    input_file_id=file_response.id,  # Encoded ID
    endpoint="/v1/chat/completions",
    completion_window="24h"
)
print(f"Batch ID: {batch_response.id}")
# Returns encoded batch ID with routing info

# Retrieve batch - routing happens automatically
batch_status = client.batches.retrieve(batch_response.id)
print(f"Status: {batch_status.status}")

# List files for a specific account
files = client.files.list(
    extra_body={"model": "gpt-4o-free"}  # List free files
)

# List batches for a specific account
batches = client.batches.list(
    extra_query={"model": "gpt-4o-litellm"}  # List litellm batches
)

출처: 문서

본문

파라미터 옵션

model 파라미터를 다음으로 전달할 수 있습니다:

요청 본문: extra_body={"model": "gpt-4o-litellm"}
쿼리 파라미터: ?model=gpt-4o-litellm
헤더: x-litellm-model: gpt-4o-litellm

인코딩된 ID 동작 방식

모델 파라미터로 파일/배치를 만들면 LiteLLM이 반환된 ID에 모델 이름을 인코딩합니다
인코딩된 ID는 base64 인코딩이며 file-bGl0ZWxsbTpmaWxlLWFiYzEyMzttb2RlbCxncHQtNG8taWZvb2Q 처럼 보입니다
이후 작업(조회, 삭제, 배치 생성)에서 이 ID를 사용하면 LiteLLM이 자동으로: ID 디코딩, 모델 이름 추출, 자격 증명 조회, 올바른 OpenAI 계정으로 요청 라우팅
원래 프로바이더 파일/배치 ID는 내부적으로 보존됩니다

이점

✅ 데이터베이스 불필요 - 모든 라우팅 정보가 ID에 저장 ✅ 상태 없음 (Stateless) - 프록시 재시작에서도 동작 ✅ 단순 - ID를 일반처럼 전달하기만 하면 됨 ✅ 하위 호환 - 기존 custom_llm_provider 와 files_settings 가 계속 동작 ✅ 미래 지향 - 관리형 배치(managed batches) 접근 방식과 일치

files_settings에서 마이그레이션

기존 방식(여전히 동작):

files_settings:
  - custom_llm_provider: openai
    api_key: os.environ/OPENAI_KEY

# Had to specify provider on every call
client.files.create(..., extra_headers={"custom-llm-provider": "openai"})
client.files.retrieve(file_id, extra_headers={"custom-llm-provider": "openai"})

새 방식(권장):

model_list:
  - model_name: "gpt-4o-account1"
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_KEY

# Specify model once on create
file = client.files.create(..., extra_body={"model": "gpt-4o-account1"})

# Then just use the ID - routing is automatic
client.files.retrieve(file.id)  # No need to specify account
client.batches.create(input_file_id=file.id)  # Routes correctly

LiteLLM PROXY Server
SDK

Proxy 서버 사용

config.yaml 설정

# for /files endpoints
files_settings:
  - custom_llm_provider: azure
    api_base: https://exampleopenaiendpoint-production.up.railway.app
    api_key: fake-key
    api_version: "2023-03-15-preview"
  - custom_llm_provider: openai
    api_key: os.environ/OPENAI_API_KEY

LiteLLM PROXY Server 시작

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

## RUNNING on http://0.0.0.0:4000

OpenAI /files 엔드포인트 사용

파일 업로드:

from openai import OpenAI
client = OpenAI(
    api_key="sk-...",
    base_url="http://0.0.0.0:4000/v1"
)
client.files.create(
    file=wav_data,
    purpose="user_data",
    extra_headers={"custom-llm-provider": "openai"}
)

파일 목록:

from openai import OpenAI
client = OpenAI(
    api_key="sk-...",
    base_url="http://0.0.0.0:4000/v1"
)
files = client.files.list(
    extra_headers={"custom-llm-provider": "openai"}
)
print("files=", files)

파일 정보 가져오기:

from openai import OpenAI
client = OpenAI(
    api_key="sk-...",
    base_url="http://0.0.0.0:4000/v1"
)
file = client.files.retrieve(
    file_id="file-abc123",
    extra_headers={"custom-llm-provider": "openai"}
)
print("file=", file)

파일 삭제:

from openai import OpenAI
client = OpenAI(
    api_key="sk-...",
    base_url="http://0.0.0.0:4000/v1"
)
response = client.files.delete(
    file_id="file-abc123",
    extra_headers={"custom-llm-provider": "openai"}
)
print("delete response=", response)

파일 콘텐츠 가져오기:

from openai import OpenAI
client = OpenAI(
    api_key="sk-...",
    base_url="http://0.0.0.0:4000/v1"
)
content = client.files.content(
    file_id="file-abc123",
    extra_headers={"custom-llm-provider": "openai"}
)
print("content=", content)

SDK 사용

파일 업로드:

import litellm
import os

os.environ["OPENAI_API_KEY"] = "sk-.."
file_obj = await litellm.acreate_file(
    file=open("mydata.jsonl", "rb"),
    purpose="fine-tune",
    custom_llm_provider="openai",
)
print("Response from creating file=", file_obj)

파일 목록:

files = await litellm.afile_list(
    custom_llm_provider="openai",
    limit=10
)
print("files=", files)

파일 정보 가져오기:

file = await litellm.afile_retrieve(
    file_id="file-abc123",
    custom_llm_provider="openai"
)
print("file=", file)

파일 삭제:

response = await litellm.afile_delete(
    file_id="file-abc123",
    custom_llm_provider="openai"
)
print("delete response=", response)

파일 콘텐츠 가져오기:

content = await litellm.afile_content(
    file_id="file-abc123",
    custom_llm_provider="openai"
)
print("file content=", content)

파일 콘텐츠 가져오기 (Bedrock):

# For Bedrock batch output files stored in S3
content = await litellm.afile_content(
    file_id="s3://bucket-name/path/to/file.jsonl",  # S3 URI or unified file ID
    custom_llm_provider="bedrock",
    aws_region_name="us-west-2"
)
print("file content=", content.text)

지원 프로바이더:

OpenAI

Azure OpenAI

Vertex AI

Bedrock

Anthropic

Anthropic Files API는 OpenAI의 것과 다른 목적을 가집니다. Batches나 Fine-tuning을 제공하는 대신, 파일을 한 번 업로드하고 여러 메시지에서 file_id 로 참조할 수 있게 해 재업로드를 피합니다. File API 작업은 무료이며, Messages 요청에서 사용된 파일 콘텐츠는 입력 토큰으로 가격이 매겨집니다.

프로바이더 파일 엔드포인트