---
title: آموزش نصب LiteLLM با Docker Compose
description: آموزش نصب LiteLLM روی VPS با Docker Compose؛ راه‌اندازی AI Gateway، PostgreSQL، HTTPS، Virtual Key و تست API مرحله‌به‌مرحله.
url: "https://negarnovin.com/docs/install-litellm-docker/"
updated: "2026-10-08"
category: تحقیق و توسعه / داکر
tags:
  - LiteLLM
---

# آموزش نصب LiteLLM با Docker Compose

# آموزش نصب LiteLLM با Docker Compose روی VPS

**LiteLLM** یک AI Gateway متن‌باز است که یک API سازگار با OpenAI در اختیار شما قرار می‌دهد تا بتوانید مدل‌ها و سرویس‌های مختلف هوش مصنوعی را پشت یک درگاه واحد مدیریت کنید. با اجرای LiteLLM روی یک VPS، می‌توانید احراز هویت، Virtual Key، محدودیت بودجه، ثبت مصرف، مسیریابی درخواست‌ها و دسترسی برنامه‌ها به مدل‌های مختلف را از یک نقطه کنترل کنید.

در این آموزش، LiteLLM را روی یک سرور لینوکسی با **Docker Compose** اجرا می‌کنیم و برای ذخیره‌سازی اطلاعات از **PostgreSQL**، برای HTTPS از **Traefik + Let's Encrypt** و برای پایش متریک‌ها از **Prometheus** استفاده خواهیم کرد.

[**سرور مجازی خارج**](https://negarnovin.com/%D8%B3%D8%B1%D9%88%D8%B1-%D9%85%D8%AC%D8%A7%D8%B2%DB%8C-%D8%AE%D8%A7%D8%B1%D8%AC/)

> **نسخه این آموزش:** LiteLLM 1.104.0
>  **آخرین بازبینی:** ۸ اکتبر ۲۰۲۶

## معماری نهایی

پس از پایان نصب، ساختار سرویس به این شکل خواهد بود:

```text
Client / Application
        |
        | HTTPS :443
        v
     Traefik
        |
        v
   LiteLLM :4000
      /        \
     /          \
PostgreSQL     LLM Provider
   :5432
     
Prometheus
   :9090
   داخلی
```

در این معماری، کاربران و برنامه‌ها مستقیماً با LiteLLM ارتباط دارند. Traefik درخواست‌های HTTPS را دریافت می‌کند و به LiteLLM می‌فرستد. PostgreSQL اطلاعات مربوط به کلیدها، کاربران، مصرف و تنظیمات را نگه می‌دارد و Prometheus متریک‌های LiteLLM را جمع‌آوری می‌کند.

PostgreSQL برای قابلیت‌هایی مانند Virtual Key، مدیریت کاربران و ثبت هزینه و مصرف اهمیت دارد؛ در deployment بدون دیتابیس، این قابلیت‌ها در دسترس نخواهند بود. Redis نیز برای یک نصب تک‌سروری ضروری نیست و زمانی اهمیت بیشتری پیدا می‌کند که چند نمونه LiteLLM، rate limiting توزیع‌شده، routing state یا cache مشترک داشته باشید.

## LiteLLM چه کاربردی دارد؟

فرض کنید یک برنامه دارید که امروز از OpenAI استفاده می‌کند و فردا قصد دارید از Anthropic، Gemini، مدل داخلی یا یک سرویس دیگر نیز استفاده کنید.

بدون Gateway، معمولاً باید منطق احراز هویت، مدیریت کلیدها، مسیریابی و کنترل هزینه را در خود برنامه پیاده کنید.

LiteLLM این لایه را جدا می‌کند:

```text
Application
     |
     v
 LiteLLM
  / | \
 /  |  \
AI  AI  AI
```

در نتیجه، برنامه شما به‌جای اینکه مستقیماً به هر Provider متصل شود، با یک API مرکزی کار می‌کند.

یکی از ویژگی‌های مهم LiteLLM این است که API آن با الگوی OpenAI سازگار است؛ بنابراین بسیاری از برنامه‌هایی که از OpenAI SDK استفاده می‌کنند، فقط با تغییر `base_url` و API Key می‌توانند از Gateway شما استفاده کنند.

## پیش‌نیازهای نصب LiteLLM

برای این آموزش پیشنهاد می‌شود از یک VPS لینوکسی استفاده کنید.

حداقل پیشنهادی برای شروع:

| مورد | مقدار پیشنهادی |
| --- | --- |
| سیستم‌عامل | Ubuntu ۲۲.۰۴ یا Ubuntu ۲۴.۰۴ |
| CPU | حداقل ۴ هسته |
| RAM | حداقل 8GB |
| دسترسی | کاربر معمولی با `sudo` |
| Docker | نصب‌شده |
| Docker Compose | نصب‌شده |
| دامنه | دارای DNS A Record |
| API Key | حداقل یک Provider هوش مصنوعی |

حداقل منابع ۴ CPU و 8GB RAM در آموزش Vultr نیز به‌عنوان پیش‌نیاز معرفی شده است.

> **توجه:** LiteLLM خودش مدل زبانی را اجرا نمی‌کند. این Gateway درخواست را به Provider یا مدل شما ارسال می‌کند. بنابراین مقدار CPU و RAM موردنیاز به نوع استفاده، تعداد درخواست‌ها، logging، routing و سرویس‌های جانبی نیز بستگی دارد.

## مرحله اول: نصب Docker و Docker Compose

ابتدا سیستم را به‌روزرسانی کنید:

```bash
sudo apt update
sudo apt upgrade -y
```

سپس ابزارهای پایه را نصب کنید:

```bash
sudo apt install -y ca-certificates curl gnupg openssl python3 python3-venv
```

اگر Docker روی سرور نصب نیست، می‌توانید از اسکریپت رسمی نصب Docker استفاده کنید:

```bash
curl -fsSL https://get.docker.com | sudo sh
```

سرویس Docker را فعال کنید:

```bash
sudo systemctl enable --now docker
```

کاربر فعلی را به گروه Docker اضافه کنید:

```bash
sudo usermod -aG docker $USER
```

برای اعمال گروه جدید:

```bash
newgrp docker
```

نسخه Docker و Compose را بررسی کنید:

```bash
docker --version
docker compose version
```

اگر هر دو دستور خروجی معتبر برگردانند، محیط برای ادامه نصب آماده است.

## مرحله دوم: ساخت پوشه LiteLLM

پوشه اصلی پروژه را ایجاد کنید:

```bash
mkdir -p ~/litellm/{letsencrypt,postgres,prometheus}
cd ~/litellm
```

Prometheus در کانتینر خود با UID مشخصی اجرا می‌شود. برای اینکه بتواند اطلاعات متریک‌ها را در پوشه مربوطه ذخیره کند، مجوز مناسب را تنظیم کنید:

```bash
sudo chown -R 65534:65534 prometheus
```

برای فایل گواهی Traefik نیز فایل ACME را ایجاد و محدود کنید:

```bash
touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.json
```

در این مرحله ساختار پوشه باید تقریباً به این شکل باشد:

```text
~/litellm/
├── letsencrypt/
├── postgres/
└── prometheus/
```

## مرحله سوم: ساخت کلیدهای امنیتی LiteLLM

LiteLLM به یک Master Key نیاز دارد. این کلید برای احراز هویت مدیریتی Gateway استفاده می‌شود.

[![آموزش نصب LiteLLM با Docker Compose](https://negarnovin.com/wp-content/uploads/2026/10/ChatGPT-Image-Oct-8-2026-04_52_49-AM-1.png)](https://negarnovin.com/wp-content/uploads/2026/10/ChatGPT-Image-Oct-8-2026-04_52_49-AM-1.png)
آموزش نصب LiteLLM با Docker Compose

یک کلید تصادفی بسازید:

```bash
openssl rand -hex 32
```

خروجی را ذخیره کنید.

دوباره همین دستور را اجرا کنید تا کلید دوم ساخته شود:

```bash
openssl rand -hex 32
```

کلید اول برای:

```text
LITELLM_MASTER_KEY
```

و کلید دوم برای:

```text
LITELLM_SALT_KEY
```

استفاده خواهد شد.

پیشوند `sk-` را می‌توانید به مقادیر اضافه کنید:

```text
sk-xxxxxxxxxxxxxxxx
```

### هشدار مهم درباره LITELLM_SALT_KEY

`LITELLM_SALT_KEY` فقط یک رمز معمولی نیست. این مقدار برای رمزنگاری اطلاعات Provider در دیتابیس استفاده می‌شود.

بعد از اضافه‌شدن مدل‌ها و اطلاعات Provider، تغییر این مقدار می‌تواند باعث شود credentialهای ذخیره‌شده در PostgreSQL دیگر قابل خواندن نباشند. بنابراین آن را در محل امنی نگهداری کنید و هیچ‌گاه داخل Git یا فایل عمومی قرار ندهید.

## مرحله چهارم: ساخت فایل .env

فایل متغیرهای محیطی را بسازید:

```bash
nano .env
```

محتوای زیر را قرار دهید:

```ini
DOMAIN=llm.example.com
LETSENCRYPT_EMAIL=admin@example.com

LITELLM_MASTER_KEY=sk-YOUR_MASTER_KEY
LITELLM_SALT_KEY=sk-YOUR_SALT_KEY

LLM_PROVIDER_API_KEY=YOUR_LLM_PROVIDER_API_KEY

POSTGRES_PASSWORD=YOUR_STRONG_DATABASE_PASSWORD

UI_USERNAME=admin
UI_PASSWORD=YOUR_STRONG_UI_PASSWORD
```

مقادیر نمونه را با اطلاعات واقعی خودتان جایگزین کنید.

مثلاً:

```ini
DOMAIN=ai.example.com
LETSENCRYPT_EMAIL=admin@example.com

LITELLM_MASTER_KEY=sk-xxxxxxxxxxxxxxxx
LITELLM_SALT_KEY=sk-yyyyyyyyyyyyyyyy

LLM_PROVIDER_API_KEY=YOUR_PROVIDER_KEY

POSTGRES_PASSWORD=CHANGE_THIS_TO_A_STRONG_PASSWORD

UI_USERNAME=admin
UI_PASSWORD=CHANGE_THIS_TO_A_LONG_RANDOM_PASSWORD
```

مجوز فایل را محدود کنید:

```bash
chmod 600 .env
```

## مرحله پنجم: ساخت config.yaml

فایل تنظیمات اصلی LiteLLM را بسازید:

```bash
nano config.yaml
```

برای شروع، ساختار زیر مناسب است:

```yaml
model_list:
  - model_name: my-model
    litellm_params:
      model: provider/model-name
      api_key: os.environ/LLM_PROVIDER_API_KEY

litellm_settings:
  callbacks:
    - prometheus
  require_auth_for_metrics_endpoint: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
```

عبارت زیر:

```text
provider/model-name
```

باید با Provider و شناسه مدل واقعی شما جایگزین شود.

مثلاً ساختار نام مدل در LiteLLM به این شکل است:

```text
provider/model-name
```

در نتیجه، LiteLLM می‌تواند یک نام داخلی برای برنامه شما تعریف کند:

```yaml
model_name: my-model
```

در حالی که پشت این نام، مدل واقعی Provider قرار دارد.

این روش باعث می‌شود برنامه‌های شما به‌جای وابستگی مستقیم به نام مدل Provider، با یک alias ثابت کار کنند.

## مرحله ششم: تنظیم Prometheus

فایل Prometheus را ایجاد کنید:

```bash
nano prometheus.yml
```

محتوای زیر را قرار دهید:

```yaml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: "litellm"
    static_configs:
      - targets: ["litellm:4000"]

    bearer_token: "sk-YOUR_MASTER_KEY"
```

مقدار:

```text
sk-YOUR_MASTER_KEY
```

را با همان مقدار واقعی `LITELLM_MASTER_KEY` جایگزین کنید.

در این تنظیم، Prometheus متریک‌های LiteLLM را از شبکه داخلی Docker دریافت می‌کند و endpoint عمومی `/metrics` نیز با احراز هویت محافظت می‌شود.

## مرحله هفتم: ساخت Docker Compose

فایل Compose را ایجاد کنید:

```bash
nano docker-compose.yaml
```

نسخه زیر را قرار دهید:

```yaml
services:

  traefik:
    image: traefik:v3.6
    container_name: traefik
    restart: unless-stopped

    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"

      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"

      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"

      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"

    ports:
      - "80:80"
      - "443:443"

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt


  litellm:
    image: ghcr.io/berriai/litellm:v1.104.0
    container_name: litellm
    restart: unless-stopped

    env_file:
      - .env

    environment:
      DATABASE_URL: "postgresql://llmproxy:${POSTGRES_PASSWORD}@db:5432/litellm"
      STORE_MODEL_IN_DB: "True"

    volumes:
      - ./config.yaml:/app/config.yaml:ro

    command:
      - "--config=/app/config.yaml"

    expose:
      - "4000"

    depends_on:
      db:
        condition: service_healthy

    healthcheck:
      test:
        [
          "CMD-SHELL",
          "python3 -c \"import urllib.request; urllib.request.urlopen('http://localhost:4000/health/liveliness')\""
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.litellm.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.litellm.entrypoints=websecure"
      - "traefik.http.routers.litellm.tls=true"
      - "traefik.http.routers.litellm.tls.certresolver=le"
      - "traefik.http.services.litellm.loadbalancer.server.port=4000"


  db:
    image: postgres:16
    container_name: litellm_db
    restart: unless-stopped

    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: llmproxy
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

    volumes:
      - ./postgres:/var/lib/postgresql/data

    expose:
      - "5432"

    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d litellm -U llmproxy"]
      interval: 5s
      timeout: 5s
      retries: 10


  prometheus:
    image: prom/prometheus:latest
    container_name: litellm_prometheus
    restart: unless-stopped

    volumes:
      - ./prometheus:/prometheus
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro

    expose:
      - "9090"

    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
      - "--storage.tsdb.retention.time=15d"
```

در این معماری فقط Traefik پورت‌های عمومی ۸۰ و ۴۴۳ را منتشر می‌کند. پورت‌های PostgreSQL، Prometheus و LiteLLM مستقیماً روی اینترنت باز نمی‌شوند.

مستندات فعلی LiteLLM استفاده از image رسمی `ghcr.io/berriai/litellm` و pin کردن نسخه را برای deploymentهای monolithic توصیه می‌کند. همچنین نسخه ۱.۱۰۴.۰ مستقیماً در release notes رسمی به‌عنوان release قابل استقرار معرفی شده است.

[سرور خارج](https://negarnovin.com/%D8%B3%D8%B1%D9%88%D8%B1-%D9%85%D8%AC%D8%A7%D8%B2%DB%8C-%D8%AE%D8%A7%D8%B1%D8%AC/)

## مرحله هشتم: بررسی فایل Compose

قبل از اجرای سرویس‌ها، فایل Compose را بررسی کنید:

```bash
docker compose config
```

اگر خطای YAML یا متغیر محیطی وجود نداشته باشد، خروجی نهایی Compose نمایش داده می‌شود.

سپس imageها را دریافت کنید:

```bash
docker compose pull
```

## مرحله نهم: بررسی امنیت image LiteLLM با Cosign

LiteLLM برای imageهای Docker خود از Cosign استفاده می‌کند. بررسی امضای image قبل از اجرای سرویس، یک مرحله امنیتی مفید برای اطمینان از اصالت image است.

Cosign را دریافت کنید:

```bash
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64"
```

سپس آن را نصب کنید:

```bash
sudo mv cosign-linux-amd64 /usr/local/bin/cosign
sudo chmod +x /usr/local/bin/cosign
```

نسخه را بررسی کنید:

```bash
cosign version
```

اکنون image LiteLLM را بررسی کنید:

```bash
cosign verify \
  --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \
  ghcr.io/berriai/litellm:v1.104.0
```

در صورت موفقیت، Cosign اطلاعات مربوط به signature را نمایش می‌دهد.

## مرحله دهم: اجرای LiteLLM

اکنون تمام سرویس‌ها را اجرا کنید:

```bash
docker compose up -d
```

وضعیت containerها را بررسی کنید:

```bash
docker compose ps
```

باید سرویس‌های زیر را ببینید:

```text
traefik
litellm
litellm_db
litellm_prometheus
```

برای بررسی لاگ LiteLLM:

```bash
docker compose logs --tail=100 litellm
```

برای بررسی Traefik:

```bash
docker compose logs --tail=100 traefik
```

برای بررسی PostgreSQL:

```bash
docker compose logs --tail=100 db
```

## مرحله یازدهم: ورود به پنل LiteLLM

پس از صدور گواهی SSL، آدرس پنل را در مرورگر باز کنید:

```text
https://llm.example.com/ui
```

به‌جای `llm.example.com` دامنه خودتان را قرار دهید.

نام کاربری و رمز عبور همان مقادیری هستند که در `.env` تعیین کردید:

```ini
UI_USERNAME=admin
UI_PASSWORD=YOUR_STRONG_UI_PASSWORD
```

LiteLLM پنل مدیریتی را برای مشاهده مدل‌ها، Virtual Keyها، مصرف و هزینه در اختیار شما قرار می‌دهد.

## اگر HTTPS فعال نشد

اول DNS را بررسی کنید.

باید یک A Record داشته باشید:

```text
llm.example.com  ->  SERVER_IP
```

پورت‌های زیر نیز باید از اینترنت قابل دسترسی باشند:

```text
80/tcp
443/tcp
```

اگر روی VPS فایروال فعال است:

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
```

سپس:

```bash
docker compose logs traefik
```

یکی از خطاهای رایج، DNS اشتباه یا اشغال بودن پورت ۸۰/۴۴۳ توسط سرویس دیگری است.

> اگر cPanel، Apache یا LiteSpeed روی همان VPS روی پورت‌های ۸۰ و ۴۴۳ فعال باشد، این معماری را روی همان سرور اجرا نکنید. برای LiteLLM از VPS جدا استفاده کنید.

## مرحله دوازدهم: بررسی سلامت LiteLLM

وضعیت healthcheck داخلی را از داخل container بررسی کنید:

```bash
docker compose exec litellm \
python3 -c "import urllib.request; print(urllib.request.urlopen('http://localhost:4000/health/liveliness').read().decode())"
```

اگر سرویس سالم باشد، پاسخ HTTP معتبر دریافت می‌کنید.

وضعیت PostgreSQL را نیز بررسی کنید:

```bash
docker compose exec db \
pg_isready -U llmproxy -d litellm
```

خروجی سالم معمولاً شامل عبارتی مشابه زیر خواهد بود:

```text
accepting connections
```

## مرحله سیزدهم: تست API با Python

برای تست API سازگار با OpenAI، ابتدا محیط مجازی Python بسازید:

```bash
python3 -m venv litellm-env
```

آن را فعال کنید:

```bash
source litellm-env/bin/activate
```

سپس OpenAI SDK را نصب کنید:

```bash
pip install -U openai
```

کلید اصلی و دامنه Gateway را به محیط وارد کنید:

```bash
export LITELLM_MASTER_KEY="sk-YOUR_MASTER_KEY"
export LITELLM_DOMAIN="llm.example.com"
```

فایل تست را ایجاد کنید:

```bash
nano test_litellm.py
```

محتوا:

```python
import os

from openai import OpenAI


client = OpenAI(
    api_key=os.environ["LITELLM_MASTER_KEY"],
    base_url=f"https://{os.environ['LITELLM_DOMAIN']}/v1",
)


response = client.chat.completions.create(
    model="my-model",
    messages=[
        {
            "role": "user",
            "content": "LiteLLM چیست؟",
        }
    ],
)

print(response.choices[0].message.content)
```

اسکریپت را اجرا کنید:

```bash
python3 test_litellm.py
```

اگر پاسخ مدل نمایش داده شد، Gateway با موفقیت درخواست را دریافت کرده، مدل را پیدا کرده و آن را به Provider ارسال کرده است.

## مرحله چهاردهم: ساخت Virtual Key

استفاده مستقیم از Master Key برای تمام برنامه‌ها کار درستی نیست.

برای هر برنامه یا کاربر بهتر است یک Virtual Key مجزا ایجاد کنید. LiteLLM امکان تعیین model access، budget و rate limit را برای کلیدها فراهم می‌کند.

ابتدا:

```bash
export LITELLM_MASTER_KEY="sk-YOUR_MASTER_KEY"
export LITELLM_DOMAIN="llm.example.com"
```

سپس:

```bash
curl -sS -X POST \
  "https://${LITELLM_DOMAIN}/key/generate" \
  -H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "test-app-key",
    "models": ["my-model"],
    "max_budget": 5.00
  }'
```

در پاسخ، LiteLLM یک کلید Virtual Key در اختیار شما قرار می‌دهد.

مثلاً:

```text
sk-xxxxxxxxxxxxxxxx
```

این کلید را مانند password یا API credential محرمانه نگه دارید.

## مرحله پانزدهم: تست Virtual Key

کلید تولیدشده را در یک متغیر ذخیره کنید:

```bash
export LITELLM_VIRTUAL_KEY="sk-YOUR_VIRTUAL_KEY"
```

حالا با Virtual Key یک درخواست API ارسال کنید:

```bash
curl -X POST \
  "https://${LITELLM_DOMAIN}/v1/chat/completions" \
  -H "Authorization: Bearer ${LITELLM_VIRTUAL_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "messages": [
      {
        "role": "user",
        "content": "Hello from LiteLLM"
      }
    ]
  }'
```

اگر پاسخ مدل برگردد، مسیر کامل زیر با موفقیت کار می‌کند:

```text
Application
    ↓
Virtual Key
    ↓
Traefik
    ↓
LiteLLM
    ↓
Provider
    ↓
LLM Response
```

## مرحله شانزدهم: مشاهده مصرف و هزینه

وارد پنل LiteLLM شوید:

```text
https://llm.example.com/ui
```

در پنل می‌توانید بخش‌های مرتبط با مدل‌ها، Virtual Keyها، Usage و Logs را بررسی کنید.

مزیت استفاده از PostgreSQL در این معماری این است که اطلاعات مدیریت Gateway، کلیدها و داده‌های مصرف بعد از restart یا recreate شدن containerها باقی می‌مانند، چون دیتابیس روی storage دائمی نگهداری می‌شود.

## محدود کردن هزینه برای هر API Key

یکی از کاربردهای مهم Virtual Keyها، تعیین سقف هزینه است.

مثلاً:

```json
{
  "key_alias": "website-ai",
  "models": ["my-model"],
  "max_budget": 10.00
}
```

در این مثال سقف بودجه کلید روی ۱۰ دلار قرار می‌گیرد.

LiteLLM همچنین امکان استفاده از budget duration، محدودیت درخواست و محدودیت token را برای کنترل بهتر مصرف فراهم می‌کند.

برای سرویس‌های واقعی، بهتر است برای هر پروژه یک Key جدا ایجاد کنید:

```text
website-ai
customer-panel
wordpress-plugin
mobile-app
internal-tools
```

به این ترتیب مصرف هر برنامه جداگانه قابل ردیابی خواهد بود.

## نکات امنیتی مهم

فایل `.env` را هرگز داخل Git قرار ندهید.

برای آن مجوز محدود تنظیم کنید:

```bash
chmod 600 .env
```

پورت‌های زیر را مستقیماً روی اینترنت منتشر نکنید:

```text
4000
5432
9090
```

در Compose این پورت‌ها فقط با `expose` در شبکه داخلی Docker در دسترس هستند و تنها Traefik پورت‌های عمومی ۸۰ و ۴۴۳ را منتشر می‌کند.

Master Key را در کد برنامه قرار ندهید. برای برنامه‌ها Virtual Key بسازید.

همچنین `LITELLM_SALT_KEY` را به‌عنوان یک credential دائمی در نظر بگیرید و از آن backup امن داشته باشید. مستندات فعلی LiteLLM صراحتاً درباره غیرقابل‌چرخش‌بودن این کلید پس از ذخیره credentialهای Provider هشدار می‌دهند.

## چرا نباید از LiteLLM v1.۸۹.۱ استفاده کنیم؟

آموزش قدیمی Vultr از `v1.89.1` استفاده می‌کند، اما این نسخه مربوط به چند نسل قبل از LiteLLM فعلی است.

در حال حاضر نسخه stable منتشرشده `v1.104.0` است و LiteLLM در فاصله کوتاه بین نسخه‌ها تغییرات متعدد امنیتی، Gateway و routing دریافت کرده است. علاوه بر این، صفحه امنیت رسمی پروژه در سال ۲۰۲۶ چندین advisory با severity بالا و بحرانی را ثبت کرده است.

بنابراین برای یک نصب جدید، استفاده از نسخه بسیار قدیمی فقط برای اینکه آموزش اصلی از آن استفاده کرده، توصیه نمی‌شود. نسخه را pin کنید، release notes را بررسی کنید و قبل از ارتقا از PostgreSQL backup بگیرید.

## آپدیت LiteLLM

قبل از هر به‌روزرسانی:

```bash
cd ~/litellm
```

از دیتابیس backup تهیه کنید.

سپس release notes نسخه مقصد را بررسی کنید.

بعد image جدید را دریافت کنید:

```bash
docker compose pull
```

و سرویس را مجدداً اجرا کنید:

```bash
docker compose up -d
```

وضعیت را بررسی کنید:

```bash
docker compose ps
```

و لاگ LiteLLM:

```bash
docker compose logs --tail=100 litellm
```

در deploymentهای بزرگ‌تر، LiteLLM برای migrationهای PostgreSQL روال جداگانه‌ای دارد و در معماری production، migration job از proxy instanceها جدا می‌شود. برای نصب‌های چندنمونه‌ای و productionهای حساس، قبل از upgrade باید مستندات migration نسخه مقصد بررسی شود.

## خطاهای رایج LiteLLM

### خطای ۵۰۲ Bad Gateway

اگر Traefik پاسخ ۵۰۲ برگرداند:

```bash
docker compose ps
```

سپس:

```bash
docker compose logs --tail=100 litellm
```

و:

```bash
docker compose logs --tail=100 traefik
```

همچنین healthcheck LiteLLM را بررسی کنید.

### خطای اتصال PostgreSQL

این دستور را اجرا کنید:

```bash
docker compose exec db \
pg_isready -U llmproxy -d litellm
```

اگر PostgreSQL سالم است، لاگ LiteLLM را بررسی کنید:

```bash
docker compose logs --tail=200 litellm
```

### مدل پیدا نمی‌شود

مقدار `model_name` در `config.yaml` باید دقیقاً با مقداری که در درخواست API ارسال می‌کنید یکسان باشد.

مثلاً اگر دارید:

```yaml
model_name: my-model
```

در درخواست نیز باید بنویسید:

```json
{
  "model": "my-model"
}
```

### Provider API Key اشتباه است

اطمینان حاصل کنید که:

```ini
LLM_PROVIDER_API_KEY=...
```

مقدار صحیح دارد و در `config.yaml` از همان environment variable استفاده شده است:

```yaml
api_key: os.environ/LLM_PROVIDER_API_KEY
```

### HTTPS صادر نمی‌شود

سه مورد را بررسی کنید:

```text
DNS A Record
Port 80
Port 443
```

سپس:

```bash
docker compose logs traefik
```

را بررسی کنید.

### پنل `/ui` باز نمی‌شود

ابتدا وضعیت container را بررسی کنید:

```bash
docker compose ps
```

سپس:

```bash
docker compose logs --tail=200 litellm
```

همچنین مقادیر زیر در `.env` را بررسی کنید:

```ini
UI_USERNAME=admin
UI_PASSWORD=YOUR_STRONG_PASSWORD
```

LiteLLM در نسخه‌های فعلی همچنان امکان ورود Admin UI با `UI_USERNAME` و `UI_PASSWORD` را دارد؛ اگر `UI_PASSWORD` تنظیم نشده باشد، رفتار ورود می‌تواند به Master Key وابسته شود. برای محیط‌های حساس، از credential مستقل برای UI و Virtual Keyهای جدا برای برنامه‌ها استفاده کنید.

## آیا LiteLLM بدون PostgreSQL هم اجرا می‌شود؟

بله، LiteLLM می‌تواند به‌صورت بدون دیتابیس نیز برای سناریوهای ساده اجرا شود؛ اما در آن حالت قابلیت‌هایی مانند Virtual Key و budget tracking که به دیتابیس متکی هستند در دسترس نخواهند بود.

برای Gatewayای که قرار است چند برنامه یا کاربر از آن استفاده کنند، PostgreSQL انتخاب مناسب‌تری است.

## آیا Redis برای LiteLLM لازم است؟

برای یک نصب تک‌سروری ساده، Redis الزام نیست.

اما وقتی LiteLLM را در چند instance اجرا می‌کنید، یا به rate limiting توزیع‌شده، router state و cache مشترک نیاز دارید، Redis وارد معماری می‌شود. در معماری production رسمی LiteLLM نیز Redis به‌عنوان جزء زیرساختی deploymentهای چندنمونه‌ای معرفی شده است.

## آیا می‌توان LiteLLM را روی VPS اجرا کرد؟

بله. VPS یکی از ساده‌ترین محیط‌ها برای اجرای LiteLLM است، به‌خصوص زمانی که قصد دارید Docker Compose، PostgreSQL و reverse proxy را روی یک ماشین اجرا کنید.

برای workloadهای بزرگ‌تر، high availability و چند نمونه Gateway، بهتر است معماری به سمت سرورهای مستقل برای دیتابیس و Redis و در ادامه Kubernetes یا زیرساخت مشابه حرکت کند.

## LiteLLM برای چه پروژه‌هایی مناسب است؟

LiteLLM می‌تواند برای سناریوهایی مانند این موارد مناسب باشد:

- ساخت AI Gateway اختصاصی
- اتصال چند Provider از طریق یک API
- مدیریت API Key برای چند پروژه
- اعمال سقف بودجه
- ثبت مصرف توکن
- مسیریابی درخواست‌ها بین مدل‌ها
- ساخت لایه مرکزی بین اپلیکیشن و سرویس‌های LLM
- اتصال نرم‌افزارهایی که از OpenAI SDK استفاده می‌کنند به Gateway داخلی

## پرسش‌های متداول

### LiteLLM چیست؟

LiteLLM یک AI Gateway متن‌باز است که درخواست‌های مدل‌های زبانی را از طریق یک API یکپارچه مدیریت و به Providerهای مختلف ارسال می‌کند.

### آیا LiteLLM رایگان است؟

نسخه Open Source LiteLLM قابل self-host است و هسته Gateway امکاناتی مانند API سازگار با OpenAI، Virtual Key، spend tracking، budget و logging را ارائه می‌کند. قابلیت‌های Enterprise امکانات مدیریتی و سازمانی بیشتری اضافه می‌کنند.

### حداقل RAM برای نصب LiteLLM چقدر است؟

برای این سناریو حداقل 8GB RAM و ۴ هسته CPU به‌عنوان نقطه شروع مناسب است؛ مقدار واقعی موردنیاز به تعداد درخواست‌ها و سرویس‌های جانبی وابسته است.

### آیا برای LiteLLM به GPU نیاز داریم؟

خیر، اگر LiteLLM فقط به‌عنوان Gateway برای APIهای خارجی استفاده شود، GPU لازم نیست. GPU زمانی مطرح می‌شود که خودتان بخواهید مدل‌های محلی را روی همان سرور اجرا کنید.

### Virtual Key در LiteLLM چیست؟

Virtual Key یک credential محدودشده برای دسترسی یک کاربر یا برنامه به Gateway است. می‌توان دسترسی مدل، بودجه و محدودیت درخواست را برای آن تعیین کرد.

### آیا LiteLLM با OpenAI SDK کار می‌کند؟

بله. یکی از اهداف LiteLLM ارائه API سازگار با OpenAI است؛ بنابراین در بسیاری از پروژه‌ها با تغییر `base_url` و API Key می‌توان درخواست‌ها را از Gateway عبور داد.

### پورت پیش‌فرض LiteLLM چیست؟

LiteLLM به‌صورت پیش‌فرض سرویس Gateway را روی پورت `4000` ارائه می‌کند. در این معماری، پورت ۴۰۰۰ به اینترنت منتشر نمی‌شود و Traefik از داخل شبکه Docker به آن دسترسی دارد.

## جمع‌بندی

با این ساختار، یک LiteLLM AI Gateway مستقل و قابل توسعه روی VPS دارید:

```text
HTTPS
  ↓
Traefik
  ↓
LiteLLM
  ↓
PostgreSQL
  ↓
Virtual Keys / Usage / Budgets

LiteLLM
  ↓
LLM Provider
```

در کنار آن، Prometheus برای جمع‌آوری متریک‌ها فعال است و PostgreSQL داده‌های مدیریتی و مصرف را به‌صورت دائمی نگهداری می‌کند.

برای استفاده واقعی، توصیه می‌شود LiteLLM را روی VPS جداگانه اجرا کنید، نسخه را pin نگه دارید، `.env` و کلیدها را امن نگه دارید، از Master Key برای اپلیکیشن‌ها استفاده نکنید و برای هر برنامه Virtual Key جدا بسازید.

در این آموزش از **LiteLLM v1.104.0** استفاده شده است؛ در صورت انتشار نسخه stable جدیدتر، پیش از تغییر نسخه release notes و migrationهای PostgreSQL را بررسی کنید.