[BETA] LiteLLM 관리형 파일

[BETA] LiteLLM 관리형 파일 (Managed Files)

LiteLLM 관리형 파일(Managed Files) 기능은 같은 파일을 여러 공급자(provider)에서 재사용할 수 있게 해주고, list·retrieve 호출 시 사용자가 접근 권한이 없는 파일을 보지 못하도록 해요. 이제 파일을 모델마다 각 공급자에 따로 올릴 필요 없이, 한 번 업로드한 파일 id를 모델들에 걸쳐 그대로 쓸 수 있어요.

이 기능은 프록시 전용이며 별도 Enterprise 라이선스가 필요 없는 Free Enterprise 기능이에요. litellm[proxy] 패키지 또는 아무 litellm 도커 이미지에서 사용할 수 있고, 파일 id 저장을 위해 Postgres DB가 필요해요.

출처: 문서

본문

  • 다른 공급자에서 같은 파일을 재사용해요.
  • 사용자가 list·retrieve 호출에서 접근 권한이 없는 파일을 못 보게 해요.

무료 Enterprise 기능이에요.

litellm[proxy] 패키지나 아무 litellm 도커 이미지에서 사용할 수 있고, Enterprise 라이선스는 필요 없어요.

특성 값 설명
Proxy ✅
SDK ❌ 파일 id 저장에 Postgres DB 필요
모든 공급자에서 사용 ✅
지원 엔드포인트 /chat/completions, /batch, /fine_tuning, /responses

사용법 (Usage)

1. config.yaml 설정하기

    model_list:
        - model_name: "gemini-3.8-flash"
          litellm_params:
            model: vertex_ai/gemini-3.8-flash
            vertex_project: my-project-id
            vertex_location: us-central1
        - model_name: "gpt-4o-mini-openai"
          litellm_params:
            model: gpt-5.6-luna
            api_key: os.environ/OPENAI_API_KEY

    general_settings:
      master_key: os.environ/LITELLM_MASTER_KEY  # alternatively use the env var - LITELLM_MASTER_KEY
      database_url: "postgresql://<user>:***@<host>:<port>/<dbname>" # alternatively use the env var - DATABASE_URL

    litellm_settings:
      require_managed_files: true # optional - reject POST /v1/files without target_model_names

(선택) 업로드 시 관리형 파일 강제하기

기본적으로 POST /v1/files는 target_model_names가 빠지면 기존 provider 파일 경로로 폴백해요. 모든 업로드에서 관리형 파일을 강제하려면 litellm_settings 아래 require_managed_files: true를 설정하세요.

    litellm_settings:
      require_managed_files: true

이 설정을 켜면 target_model_names 없는 업로드는 400을 반환해요. target_model_names를 제공하면 기존 관리형 파일 동작은 그대로 유지돼요.

    # String (comma-separated for multiple models)
    extra_body={"target_model_names": "gpt-4o-mini-openai, gemini-3.8-flash"}

    # List (OpenAI Python SDK sends this as target_model_names[] in multipart form)
    extra_body={"target_model_names": ["gpt-4o-mini-openai"]}

2. 프록시 시작하기

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

3. 테스트하기!

target_model_names를 지정하면 같은 파일 id를 여러 공급자에서 쓸 수 있어요. 이 값은 config.yaml로 설정한 model_names 목록(addit UI에서는 'public_model_names')이에요.

    target_model_names="gpt-4o-mini-openai, gemini-3.8-flash" # 👈 Specify model_names

키에 사용 가능한 모델 이름 목록은 /v1/models에서 확인할 수 있어요.

PDF 파일 저장하기

    from openai import OpenAI

    client = OpenAI(base_url="http://0.0.0.0:4000", api_key="sk-<your-litellm-api-key>", max_retries=0)


    # Download and save the PDF locally
    url = (
        "https://storage.googleapis.com/cloud-samples-data/generative-ai/pdf/2403.05530.pdf"
    )
    response = requests.get(url)
    response.raise_for_status()

    # Save the PDF locally
    with open("2403.05530.pdf", "wb") as f:
        f.write(response.content)

    file = client.files.create(
        file=open("2403.05530.pdf", "rb"),
        purpose="user_data", # can be any openai 'purpose' value
        extra_body={"target_model_names": "gpt-4o-mini-openai, gemini-3.8-flash"}, # 👈 Specify model_names
    )

    print(f"file id={file.id}")

같은 파일 id를 여러 공급자에서 사용하기

  • OpenAI
  • Vertex AI
    completion = client.chat.completions.create(
        model="gpt-4o-mini-openai",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "What is in this recording?"},
                    {
                        "type": "file",
                        "file": {
                            "file_id": file.id,
                        },
                    },
                ],
            },
        ]
    )

    print(completion.choices[0].message)

    completion = client.chat.completions.create(
        model="gemini-3.8-flash",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "What is in this recording?"},
                    {
                        "type": "file",
                        "file": {
                            "file_id": file.id,
                        },
                    },
                ],
            },
        ]
    )

    print(completion.choices[0].message)

전체 예제 (Complete Example)

    import base64
    import requests
    from openai import OpenAI

    client = OpenAI(base_url="http://0.0.0.0:4000", api_key="sk-<your-litellm-api-key>", max_retries=0)


    # Download and save the PDF locally
    url = (
        "https://storage.googleapis.com/cloud-samples-data/generative-ai/pdf/2403.05530.pdf"
    )
    response = requests.get(url)
    response.raise_for_status()

    # Save the PDF locally
    with open("2403.05530.pdf", "wb") as f:
        f.write(response.content)

    # Read the local PDF file
    file = client.files.create(
        file=open("2403.05530.pdf", "rb"),
        purpose="user_data", # can be any openai 'purpose' value
        extra_body={"target_model_names": "gpt-4o-mini-openai, vertex_ai/gemini-3.8-flash"},
    )

    print(f"file.id: {file.id}") # 👈 Unified file id

    ## GEMINI CALL ###
    completion = client.chat.completions.create(
        model="gemini-3.8-flash",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "What is in this recording?"},
                    {
                        "type": "file",
                        "file": {
                            "file_id": file.id,
                        },
                    },
                ],
            },
        ]
    )

    print(completion.choices[0].message)


    ### OPENAI CALL ###
    completion = client.chat.completions.create(
        model="gpt-4o-mini-openai",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "What is in this recording?"},
                    {
                        "type": "file",
                        "file": {
                            "file_id": file.id,
                        },
                    },
                ],
            },
        ],
    )

    print(completion.choices[0].message)

파일 권한 (File Permissions)

사용자가 list·retrieve 호출에서 접근 권한이 없는 파일을 못 보게 해요.

1. config.yaml 설정하기

    model_list:
        - model_name: "gpt-4o-mini-openai"
          litellm_params:
            model: gpt-5.6-luna
            api_key: os.environ/OPENAI_API_KEY

    general_settings:
      master_key: os.environ/LITELLM_MASTER_KEY  # alternatively use the env var - LITELLM_MASTER_KEY
      database_url: "postgresql://<user>:***@<host>:<port>/<dbname>" # alternatively use the env var - DATABASE_URL

2. 프록시 시작하기

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

3. 사용자에게 키 발급하기

id가 user_123인 사용자를 만들어 봐요.

    curl -L -X POST 'http://0.0.0.0:4000/user/new' \
    -H "Authorization: Bearer ***" \
    -H 'Content-Type: application/json' \
    -d '{"models": ["gpt-4o-mini-openai"], "user_id": "user_123"}'

응답에서 키를 받아요.

    {
        "key": "sk-..."
    }

4. 사용자가 파일 만들기

4a. 파일 만들기

    {"messages": [{"role": "system", "content": "Clippy is a factual chatbot that is also sarcastic."}, {"role": "user", "content": "What's the capital of France?"}, {"role": "assistant", "content": "Paris, as if everyone doesn't know that already."}]}
    {"messages": [{"role": "system", "content": "Clippy is a factual chatbot that is also sarcastic."}, {"role": "user", "content": "Who wrote 'Romeo and Juliet'?"}, {"role": "assistant", "content": "Oh, just some guy named William Shakespeare. Ever heard of him?"}]}

4b. 파일 업로드하기

    from openai import OpenAI

    client = OpenAI(
        base_url="http://0.0.0.0:4000",
        api_key="sk-...", # 👈 Use the key you generated in step 3
        max_retries=0
    )

    # Upload file
    finetuning_input_file = client.files.create(
        file=open("./fine_tuning.jsonl", "rb"), # {"model": "azure-gpt-4o"} <-> {"model": "gpt-4o-my-special-deployment"}
        purpose="fine-tune",
        extra_body={"target_model_names": "gpt-4.1-openai"} # 👈 Tells litellm which regions/projects to write the file in.
    )
    print(finetuning_input_file) # file.id = "litellm_proxy/..." = {"model_name": {"deployment_id": "deployment_file_id"}}

5. 사용자가 파일 조회하기

  • 사용자가 만든 파일
  • 사용자가 만들지 않은 파일
    from openai import OpenAI

    ... # User created file (3b)

    file = client.files.retrieve(
        file_id=finetuning_input_file.id
    )

    print(file) # File retrieved successfully

    from openai import OpenAI

    ... # User created file (3b)

    try:
        file = client.files.retrieve(
            file_id="bGl0ZWxsbV9wcm94eTphcHBsaWNhdGlvbi9vY3RldC1zdHJlYW07dW5pZmllZF9pZCwyYTgzOWIyYS03YzI1LTRiNTUtYTUxYS1lZjdhODljNzZkMzU7dGFyZ2V0X21vZGVsX25hbWVzLGdwdC00by1iYXRjaA"
        )
    except Exception as e:
        print(e) # User does not have access to this file

지원 엔드포인트 (Supported Endpoints)

파일 만들기 - /files

    from openai import OpenAI

    client = OpenAI(base_url="http://0.0.0.0:4000", api_key="sk-<your-litellm-api-key>", max_retries=0)

    # Download and save the PDF locally
    url = (
        "https://storage.googleapis.com/cloud-samples-data/generative-ai/pdf/2403.05530.pdf"
    )
    response = requests.get(url)
    response.raise_for_status()

    # Save the PDF locally
    with open("2403.05530.pdf", "wb") as f:
        f.write(response.content)

    # Read the local PDF file
    file = client.files.create(
        file=open("2403.05530.pdf", "rb"),
        purpose="user_data", # can be any openai 'purpose' value
        extra_body={"target_model_names": "gpt-4o-mini-openai, vertex_ai/gemini-3.8-flash"},
    )

파일 조회하기 - /files/{file_id}

    client = OpenAI(base_url="http://0.0.0.0:4000", api_key="sk-<your-litellm-api-key>", max_retries=0)

    file = client.files.retrieve(file_id=file.id)

파일 삭제하기 - /files/{file_id}/delete

    client = OpenAI(base_url="http://0.0.0.0:4000", api_key="sk-<your-litellm-api-key>", max_retries=0)

    file = client.files.delete(file_id=file.id)

파일 목록 조회하기 - /files

    client = OpenAI(base_url="http://0.0.0.0:4000", api_key="sk-<your-litellm-api-key>", max_retries=0)

    files = client.files.list(extra_body={"target_model_names": "gpt-4o-mini-openai"})

    print(files) # All files user has created

List Files의 Pre-GA 제한사항:

  • 멀티 모델 미지원: 지금은 모델 이름 1개만 지원해요.
  • 멀티 디플로이먼트 미지원: 지금은 모델의 디플로이먼트 1개만 지원해요 (예: gpt-4o-mini-openai public model name으로 디플로이먼트 2개가 있으면 하나를 골라 그 디플로이먼트의 모든 파일을 반환해요).

Pre-GA 제한사항은 Managed Files 기능 GA 이전에 모두 해결될 예정이에요.

FAQ

1. LiteLLM이 파일을 저장하나요?

아니요, LiteLLM은 파일 자체를 저장하지 않아요. Postgres DB에 파일 id만 저장해요.

2. LiteLLM은 주어진 file id에 어떤 파일을 쓸지 어떻게 알까요?

LiteLLM은 litellm 파일 id와 모델별 파일 id의 매핑을 Postgres DB에 저장해요. 요청이 들어오면 LiteLLM이 모델별 파일 id를 조회해서 그 id로 공급자에 요청해요.

3. 파일 삭제는 어떻게 동작하나요?

파일이 삭제되면 LiteLLM이 Postgres DB에서 매핑을 삭제하고, 각 공급자의 파일도 함께 삭제해요.

4. 다른 사용자가 만든 파일 id를 다른 사용자가 호출할 수 있나요?

아니요, v1.71.2부터 사용자는 자신이 만든 파일만 조회/수정/삭제할 수 있어요.

아키텍처 (Architecture)

더 알아보기 (Learn more)