LiteLLM Proxy: 1 API pentru 100+ LLM-uri (Configurare Docker în 15 min)

LiteLLM Proxy: 1 API pentru 100+ LLM-uri (Configurare Docker în 15 min)

Echipa ta partajează cheile API OpenAI prin mesaje directe pe Slack. Nimeni nu știe cine a cheltuit 400 $ marțea trecută. Nu există limitare a ratei (rate limiting), nu există fallback când un provider pică, iar schimbarea de la GPT-4o la Claude implică modificarea codului în douăsprezece locuri. Sună familiar? Un gateway LLM self-hosted rezolvă toate aceste probleme, iar proxy-ul LiteLLM este cea mai populară opțiune open-source, oferind un singur endpoint compatibil OpenAI care rutează cererile către peste 100 de provideri LLM.

Acest ghid acoperă întreaga configurare a proxy-ului litellm: Docker Compose cu PostgreSQL, chei virtuale pentru echipe cu bugete, monitorizarea costurilor, limite de rată și conectarea IDE-urilor AI precum Claude Code și Cursor. Dacă evaluezi unelte de tip gateway LLM, acesta este tutorialul practic care te duce de la zero la producție.

O notă importantă înainte de a începe: SDK-ul LiteLLM (biblioteca Python) și Serverul Proxy sunt lucruri diferite. SDK-ul este destinat unui singur developer care apelează multiple API-uri LLM din Python. Proxy-ul este destinat echipelor; funcționează ca un server intermediar între aplicațiile tale și providerii LLM. Dacă ești un developer solo care scrie un script, SDK-ul este suficient. Dacă gestionezi chei, bugete și acces pentru o echipă, ai nevoie de proxy. Asta vom configura aici.

LiteLLM Proxy în linii mari

Iată cum se compară metodele de implementare:

Pentru majoritatea echipelor, Docker Compose cu PostgreSQL este soluția optimă. Spre asta ne îndreptăm, dar mai întâi, să punem în funcțiune un proxy în 60 de secunde.

Cerințe preliminare și configurarea mediului

Înainte de a începe, asigură-te că ai:

• Docker și Docker Compose instalate (Docker Desktop le include pe ambele)
• Cel puțin o cheie API LLM (OpenAI, Anthropic sau o instanță locală Ollama)
• Familiaritate de bază cu terminalul / CLI

Verifică dacă Docker este pregătit și exportă-ți cheile API:

# Check Docker is installed
docker --version
docker compose version

# Export your LLM API keys (add to your shell profile for persistence)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: set a master key for your proxy (you'll need this later)
export LITELLM_MASTER_KEY="sk-master-your-secret-key"

Asta e tot. Fără versiuni speciale de Python, fără unelte specifice sistemului de operare. Dacă Docker rulează pe mașina ta, ești gata.

Pornire Rapidă: Primul tău Proxy LiteLLM în 60 de Secunde

O singură comandă pentru a porni un proxy cu GPT-4o:

docker run -d \
  --name litellm-proxy \
  -p 4000:4000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e LITELLM_MASTER_KEY=$LITELLM_MASTER_KEY \
  ghcr.io/berriai/litellm:main-stable \
  --model openai/gpt-4o

Testează-l cu curl:

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Say hello from LiteLLM"}]
  }'

Sau testează din Python:

from openai import OpenAI

# Point the standard OpenAI SDK at your proxy
client = OpenAI(
    api_key="sk-master-your-secret-key",
    base_url="http://localhost:4000/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Say hello from LiteLLM"}]
)
print(response.choices[0].message.content)

Ce s-a întâmplat? Codul tău comunică cu localhost:4000 folosind formatul standard al SDK-ului OpenAI. Proxy-ul primește cererea, o forward-ează către API-ul OpenAI cu cheia reală și returnează răspunsul. Codul aplicației tale nu atinge niciodată cheia API actuală.

Aceasta este ideea de bază. Acum să construim o configurare de producție.

Configurare Producție Docker Compose cu PostgreSQL

Comanda simplă docker run funcționează pentru testare, dar echipele de producție au nevoie de tracking persistent al costurilor, chei virtuale și stocare adecvată în baza de date. Aceasta înseamnă Docker Compose cu PostgreSQL.

Fișierul Docker Compose

# docker-compose.yml
version: "3.9"

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    container_name: litellm-proxy
    ports:
      - "4000:4000"         # Proxy API port
    volumes:
      - ./config.yaml:/app/config.yaml   # Mount your config file
    environment:
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://litellm:litellm_password@postgres:5432/litellm
      - LITELLM_SALT_KEY=${LITELLM_SALT_KEY:-sk-salt-random-string}
    command: --config /app/config.yaml --detailed_debug
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    container_name: litellm-db
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm_password
    volumes:
      - litellm_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  litellm_pgdata:

LITELLM_SALT_KEY criptează datele cheilor virtuale în baza de date. Documentația best practices pentru producție LiteLLM recomandă setarea acesteia pentru orice implementare în echipă.

Pornirea Stivei

# Create a .env file with your keys (don't commit this to git)
echo "LITELLM_MASTER_KEY=sk-master-your-secret" > .env
echo "OPENAI_API_KEY=sk-..." >> .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
echo "LITELLM_SALT_KEY=sk-salt-$(openssl rand -hex 16)" >> .env

# Start everything
docker compose up -d

# Check logs
docker compose logs -f litellm

Verificarea funcționării

# Health check
curl http://localhost:4000/health

# Test a request
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}]}'

Dacă vezi un răspuns de succes, stiva ta de producție rulează. PostgreSQL stochează toate datele de cost, cheile virtuale și metricile de utilizare în mod persistent, chiar și după restartarea containerelor.

Verdict: Docker Compose + PostgreSQL este configurarea de producție recomandată. Îți oferă stocare persistentă, tracking al costurilor și chei virtuale cu aproximativ 10 minute de muncă. Documentația de implementare Docker acoperă Kubernetes și Helm dacă ai nevoie de auto-scaling mai târziu.

Parcurgerea config.yaml: O Configurare Reală Multi-Provider

Majoritatea tutorialelor arată un config.yaml cu un singur model. Iată cum arată o configurare reală pentru o echipă, cu trei provideri, fallback-uri și load balancing.

Fișierul de Configurare

# config.yaml -- Real multi-provider setup
model_list:
  # Primary: OpenAI GPT-4o
  - model_name: gpt-4o          # The name YOUR code uses
    litellm_params:
      model: openai/gpt-4o      # The actual provider/model
      api_key: os.environ/OPENAI_API_KEY

  # Secondary: Anthropic Claude
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

  # Local: Ollama for development / cost-free testing
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3.1
      api_base: http://host.docker.internal:11434

  # Fallback: route "gpt-4o" to Claude if OpenAI is down
  - model_name: gpt-4o
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  routing_strategy: least-busy    # Load balance across same-name models
  num_retries: 3
  retry_after: 5                  # Seconds between retries
  fallbacks: [{"gpt-4o": ["claude-sonnet"]}]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

Aliasuri Model și Rutare

Observă că gpt-4o apare de două ori în config, o dată指向 către OpenAI, o dată către Anthropic. Când codul tău solicită gpt-4o, LiteLLM încearcă mai întâi OpenAI. Dacă aceasta eșuează, setarea fallbacks rutează automat către Claude. Codul aplicației tale nu se schimbă deloc.

Dacă folosești backend-uri de inferență pentru producție precum vLLM sau SGLang, le poți adăuga în același mod, setând doar api_base către serverul tău de inferență.

Referință Rapidă Provideri

Setarea routing_strategy: least-busy distribuie cererile între modelele cu același model_name. Dacă ai două chei OpenAI (poate organizații diferite cu limite de rată diferite), listează-le pe ambele sub gpt-4o, iar LiteLLM va echilibra sarcina.

Chei Virtuale: Chei API per-Echipă cu Bugete și Limite de Rată

Aici LiteLLM încetează să mai fie „doar un proxy” și devine un instrument de management al echipei. Cheile virtuale îți permit să oferi fiecărui membru al echipei sau serviciu propria cheie API cu limite de cheltuieli și capete de rată, toate rutate prin setul tău unic de chei API ale providerilor.

Crearea unei Chei de Echipă cu Buget

# Create a virtual key with a $50/month budget
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "frontend-team",
    "max_budget": 50.0,
    "budget_duration": "1mo",
    "models": ["gpt-4o", "claude-sonnet"],
    "metadata": {"purpose": "frontend AI features"}
  }'

Răspunsul îți oferă o nouă cheie de genul sk-team-abc123.... Ofer-o echipei de frontend. O pot folosi exact ca pe o cheie OpenAI, dar este limitată la 50 $/lună și are acces doar la modelele specificate de tine.

Setarea Limitelor de Rată

# Create a key with rate limits: 100 requests/minute, 50K tokens/minute
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "backend-team",
    "max_budget": 200.0,
    "budget_duration": "1mo",
    "rpm_limit": 100,
    "tpm_limit": 50000,
    "models": ["gpt-4o", "claude-sonnet", "local-llama"]
  }'

Documentația cheilor virtuale acoperă fiecare parametru. Poți seta și bugete și limite de rată per-utilizator pentru un control și mai granular.

Monitorizarea Utilizării Cheilor

import requests

# Check a key's current spend and limits
response = requests.get(
    "http://localhost:4000/key/info",
    headers={"Authorization": f"Bearer {MASTER_KEY}"},
    params={"key": "sk-team-abc123..."}
)
info = response.json()
print(f"Spent: ${info['spend']:.2f} / ${info['max_budget']:.2f}")
print(f"RPM used: {info['rpm_limit_used']} / {info['rpm_limit']}")

Trebuie să revoci o cheie compromisă? Un singur apel API:

curl -X POST http://localhost:4000/key/delete \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["sk-team-abc123..."]}'

Verdict: Cheile virtuale sunt cele care transformă LiteLLM într-un instrument de echipă, nu doar un proxy personal. Fără ele, adaugi doar un hop între codul tău și LLM. Cu ele, ai control al accesului, aplicarea bugetului și atribuirea utilizării – genul de lucruri care îl împiedică pe CFO să intre în panică.

Tracking Costuri și Dashboard-ul LiteLLM

Odată ce PostgreSQL este conectat, LiteLLM urmărește automat costul fiecărei cereri. Nu trebuie să configurezi nimic; cunoaște prețurile per-token pentru fiecare model suportat.

Dashboard-ul

Accesează UI-ul integrat la http://localhost:4000/ui (autentifică-te cu cheia master). Vei vedea:

• Cheltuieli totale across all teams and keys
• Defalcare per-model, care modele îți consumă bugetul
• Cheltuieli per-echipă, cine folosește ce
• Volumul de cereri în timp

Pentru echipele serioase privind reducerea costurilor API LLM, dashboard-ul singur justifică rularea proxy-ului. Poți conecta și LiteLLM la platforme externe de observabilitate AI precum Langfuse sau Helicone pentru analitice mai profunde.

Compararea Costurilor per-Provider

Iată cât costă modelele majore per milion de tokeni (din aprilie 2026):

Când vezi aceste numere în dashboard defalcate pe echipe, conversațiile despre „ar trebui să folosim un model mai ieftin pentru acest caz de utilizare?” devin foarte concrete.

Verdict: Tracking-ul costurilor singur justifică proxy-ul pentru orice echipă care cheltuie >100 $/lună pe API-uri LLM. Nu poți optimiza ceea ce nu poți măsura.

Conectarea IDE-urilor AI: Claude Code, Cursor și Continue

Iată ceva ce majoritatea ghidurilor LiteLLM omit complet: poți direcționa și uneltele tale de coding AI către proxy. Un singur proxy, toate uneltele tale IDE, facturare unificată.

Claude Code

# Set Claude Code to use your LiteLLM proxy
export ANTHROPIC_BASE_URL=http://localhost:4000/v1
export ANTHROPIC_API_KEY=sk-team-your-virtual-key

Asta e tot. Claude Code trimite cereri către proxy-ul tău, care le rutează către Anthropic (sau oriunde indică config-ul tău), urmărind în același timp costurile sub cheia ta virtuală.

Cursor

În setările Cursor, adaugă un endpoint custom compatibil OpenAI:

{
  "openai.apiBaseUrl": "http://localhost:4000/v1",
  "openai.apiKey": "sk-team-your-virtual-key"
}

Continue (VS Code)

În config.json al Continue:

{
  "models": [
    {
      "title": "GPT-4o via LiteLLM",
      "provider": "openai",
      "model": "gpt-4o",
      "apiBase": "http://localhost:4000/v1",
      "apiKey": "sk-team-your-virtual-key"
    }
  ]
}

De ce să te deranjezi? Pentru că acum utilizarea IDE-ului fiecărui developer trece prin proxy. Obții tracking al costurilor per-persoană pentru asistenții de coding AI, limite de rată astfel încât nimeni să nu ardă accidental 500 $ într-o sesiune de coding și un singur loc pentru a schimba modelele dacă găsești o opțiune mai bună.

Depanarea Problemelor Comune

„Config file not found”

De obicei, aceasta înseamnă că calea de mount a volumului este greșită în Docker. Asigură-te că config.yaml se află în directorul din care montezi:

# Check the file exists where you think it does
ls -la ./config.yaml

# The volume mount in docker-compose.yml should match
# volumes:
#   - ./config.yaml:/app/config.yaml

„Connection refused” către PostgreSQL

Networking-ul Docker îi prinde pe toți măcar o dată. Dacă LiteLLM nu poate ajunge la Postgres, verifică dacă:

• Numele serviciului din DATABASE_URL corespunde cu numele serviciului Docker Compose (postgres, nu localhost)
• Este setat depends_on cu condition: service_healthy (astfel încât LiteLLM așteaptă ca Postgres să fie gata)
• Ambele servicii sunt pe aceeași rețea Docker (sunt implicit în Compose)

„Invalid API key format”

Cea mai comună confuzie: LITELLM_MASTER_KEY este pentru operațiuni de admin (crearea cheilor virtuale, accesarea dashboard-ului). Cheile virtuale (sk-team-...) sunt cele pe care le folosesc aplicațiile tale. Nu le amesteca.

„Model not found”

Câmpul model din cererea ta trebuie să corespundă cu un model_name din config.yaml. Dacă config-ul definește gpt-4o, dar codul tău solicită openai/gpt-4o, nu se va potrivi. Verifică ortografia exactă.

Proxy-ul pornește, dar cererile rămân blocate

De obicei, este o problemă de firewall sau de bindare a portului. Verifică dacă portul 4000 este expus și nu este blocat:

# Check if the port is listening
docker port litellm-proxy
# Should show: 4000/tcp -> 0.0.0.0:4000

Securitate: Evită Versiunile 1.82.7 și 1.82.8

În martie 2026, un incident de supply chain a afectat versiunile LiteLLM 1.82.7 și 1.82.8. Versiunile compromise au fost retrase, iar o lansare curată a fost livrată la 1.83.0. Fixează întotdeauna imaginea Docker la o versiune specifică și verifică actualizarea oficială de securitate înainte de upgrade. Dacă ești pe 1.82.7 sau 1.82.8, actualizează imediat.

Ce Metodă de Configurare LiteLLM Ar Trebui să Alegi?

Dacă citești acest ghid pentru prima dată, începe cu Docker Compose + PostgreSQL. Poți migra oricând la Kubernetes mai târziu, fișierul config.yaml rămâne același.

Întrebări Frecvente (FAQ)

Ce este proxy-ul LiteLLM și cum funcționează?

Proxy-ul LiteLLM este un server gateway AI open-source care se situează între aplicațiile tale și providerii LLM precum OpenAI și Anthropic. Expune un singur endpoint compatibil OpenAI, astfel încât codul tău comunică cu o singură URL, în timp ce proxy-ul gestionează rutarea, managementul cheilor, tracking-ul costurilor și fallback-urile în background.

Cum configurez proxy-ul LiteLLM cu Docker Compose?

Creează un docker-compose.yml cu imaginea proxy-ului LiteLLM și o bază de date PostgreSQL, montează config.yaml, setează cheile API ca variabile de mediu și rulează docker compose up -d. Secțiunea Docker Compose pentru Producție de mai sus conține un fișier complet, gata de copiat.

Cum gestionez cheile API ale echipei cu LiteLLM?

Folosește chei virtuale. Accesează endpoint-ul /key/generate cu cheia ta master pentru a crea chei per-echipă sau per-utilizator. Fiecare cheie virtuală poate avea propriul buget lunar, limite de rată (RPM și TPM) și restricții de acces la modele. Secțiunea Chei Virtuale acoperă fluxul de lucru complet.

Cum adaug tracking al costurilor și limite de rată la API-ul meu LLM?

Conectează PostgreSQL la proxy (prin DATABASE_URL), iar tracking-ul costurilor se face automat. Pentru limite de rată, setează rpm_limit și tpm_limit la generarea cheilor virtuale. Dashboard-ul integrat la /ui afișează cheltuielile per-echipă și per-model.

Este sigur să folosesc proxy-ul LiteLLM în producție?

Da, cu o singură mențiune: evită versiunile 1.82.7 și 1.82.8, care au fost afectate de un incident de supply chain în martie 2026. Folosește versiunea 1.83.0 sau ulterioară. Fixează versiunea imaginii Docker, setează LITELLM_SALT_KEY pentru criptare și urmează best practices oficiale pentru producție.

Care este diferența dintre SDK-ul LiteLLM și proxy-ul LiteLLM?

SDK-ul este o bibliotecă Python pentru apelarea multiplelor API-uri LLM din codul tău. Proxy-ul este un server standalone la care se conectează întreaga ta echipă. Folosește SDK-ul când ești un developer solo care scrie un script. Folosește proxy-ul când ai nevoie de control partajat al accesului, tracking al costurilor și limitare a ratei across o echipă.

Pot folosi proxy-ul LiteLLM cu Ollama și modele locale?

Absolut. Adaugă o intrare în config.yaml cu model: ollama/llama3.1 și api_base: http://host.docker.internal:11434 (sau gazda ta Ollama). Echipa ta poate accesa apoi modelele locale prin același endpoint proxy, ceea ce este excelent pentru dezvoltare și testare fără costuri.

Cât costă proxy-ul LiteLLM?

Proxy-ul LiteLLM este gratuit și open-source (licență MIT). Îl găzduiești singur pe propria infrastructură. Singurele costuri sunt serverul tău (un VPS mic este suficient pentru majoritatea echipelor) și costurile API LLM pe care le plătești deja. BerriAI oferă, de asemenea, o versiune cloud managed dacă nu dorești să te ocupi de self-hosting.

Ce provideri suportă LiteLLM?

Peste 100, inclusiv OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Ollama, Hugging Face, Cohere, Replicate și mulți alții. Lista completă se află pe repository-ul GitHub LiteLLM.

Cum actualizez în siguranță proxy-ul LiteLLM?

Fixează întotdeauna o versiune specifică în tag-ul imaginii Docker (de ex., ghcr.io/berriai/litellm:v1.83.2-stable). Înainte de upgrade, verifică changelog-ul pentru modificări breaking. Nu folosi niciodată latest în producție. Și verifică întotdeauna dacă noua versiune nu se află pe lista de advisory de securitate; incidentul din martie 2026 a demonstrat că chiar și pachetele de încredere pot fi compromise.

Verdict Final și Pașii Următori

Dacă echipa ta cheltuie bani pe API-uri LLM și nu ai încă un proxy, începe astăzi cu Docker Compose + Postgres. Configurarea durează 15 minute, iar până la final vei avea vizibilitatea costurilor și controlul accesului.

Odată ce rulezi, explorează adăugarea de guardrails în pipeline-ul tău LLM pentru filtrarea conținutului și verificări de siguranță. Proxy-ul este fundația, totul celălalt se construiește peste el.

Surse

• Pornire Rapidă Proxy LiteLLM, Documentație Oficială
• Ghid Implementare Docker LiteLLM
• Documentație Chei Virtuale LiteLLM
• Best Practices Producție LiteLLM
• Actualizare Securitate LiteLLM, Martie 2026
• BerriAI/litellm, Repository GitHub