⚡ 生产环境最佳实践

1. 使用此 config.yaml

在生产环境中使用此 config.yaml（配置您自己的 LLM）

model_list:
  - model_name: fake-openai-endpoint
    litellm_params:
      model: openai/fake
      api_key: fake-key
      api_base: https://exampleopenaiendpoint-production.up.railway.app/

general_settings:
  master_key: sk-1234      # enter your own master key, ensure it starts with 'sk-'
  alerting: ["slack"]      # Setup slack alerting - get alerts on LLM exceptions, Budget Alerts, Slow LLM Responses
  proxy_batch_write_at: 60 # Batch write spend updates every 60s
  database_connection_pool_limit: 10 # connection pool limit per worker process. Total connections = limit × workers × instances. Calculate: MAX_DB_CONNECTIONS / (instances × workers). Default: 10.

:::warning
**Multiple instances:** If running multiple LiteLLM instances (e.g., Kubernetes pods), remember each instance multiplies your total connections. Example: 3 instances × 4 workers × 10 connections = 120 total connections.
:::

  # OPTIONAL Best Practices
  disable_error_logs: True # turn off writing LLM Exceptions to DB
  allow_requests_on_db_unavailable: True # Only USE when running LiteLLM on your VPC. Allow requests to still be processed even if the DB is unavailable. We recommend doing this if you're running LiteLLM on VPC that cannot be accessed from the public internet.

litellm_settings:
  request_timeout: 600    # raise Timeout error if call takes longer than 600 seconds. Default value is 6000seconds if not set
  set_verbose: False      # Switch off Debug Logging, ensure your logs do not have any debugging on
  json_logs: true         # Get debug logs in json format

在环境变量中设置 slack webhook url

export SLACK_WEBHOOK_URL="example-slack-webhook-url"

关闭 FASTAPI 的默认信息日志 (info logs)

export LITELLM_LOG="ERROR"

信息

需要帮助或想要获取专属支持？[点击这里]与创始人交谈：(https://enterprise.litellm.ai/demo)

2. 推荐机器配置

为了在生产环境中获得最佳性能，我们建议使用以下最低机器配置

资源	推荐值
CPU	4 vCPU
内存	8 GB 内存

这些配置可以提供：

• 充足的计算能力以处理并发请求
• 足够的内存用于请求处理和缓存

3. 在 Kubernetes 上 — 使 Uvicorn 工作进程数与 CPU 核心数匹配 [建议 CMD]

使用此 Docker CMD。它会自动将 Uvicorn 工作进程数与 Pod 的 CPU 核心数匹配，确保每个工作进程有效使用一个核心，从而获得更好的吞吐量和稳定的延迟。

CMD ["--port", "4000", "--config", "./proxy_server_config.yaml", "--num_workers", "$(nproc)"]

可选：如果您观察到在持续负载下内存逐渐增长，请考虑在固定请求数后重启工作进程以缓解内存泄漏。您可以通过 CLI 或环境变量进行配置。

# CLI
CMD ["--port", "4000", "--config", "./proxy_server_config.yaml", "--num_workers", "$(nproc)", "--max_requests_before_restart", "10000"]

# or ENV (for deployment manifests / containers)
export MAX_REQUESTS_BEFORE_RESTART=10000

提示：使用 --max_requests_before_restart 时，--run_gunicorn 标志更加稳定和成熟，因为它使用了 Gunicorn 经过实战检验的工作进程回收机制，而不是 Uvicorn 的实现。

# Use Gunicorn for more stable worker recycling
CMD ["--port", "4000", "--config", "./proxy_server_config.yaml", "--num_workers", "$(nproc)", "--run_gunicorn", "--max_requests_before_restart", "10000"]

4. 使用 Redis 的 'port', 'host', 'password'。不要使用 'redis_url'

如果您决定使用 Redis，请勿使用 'redis_url'。我们建议使用 redis 端口、主机和密码参数。

redis_url 的每秒请求数 (RPS) 会慢 80 次

我们仍在调查原因。请在此处关注进展

Redis 版本要求

组件	最低版本
Redis	7.0+

生产环境推荐操作

router_settings:
  routing_strategy: simple-shuffle # (default) - recommended for best performance
  # redis_url: "os.environ/REDIS_URL"
  redis_host: os.environ/REDIS_HOST
  redis_port: os.environ/REDIS_PORT
  redis_password: os.environ/REDIS_PASSWORD

litellm_settings:
  cache: True
  cache_params:
    type: redis
    host: os.environ/REDIS_HOST
    port: os.environ/REDIS_PORT
    password: os.environ/REDIS_PASSWORD

警告：由于性能影响，不建议在生产环境中使用基于用量的路由 (Usage-based routing)。 在高流量场景下，请使用 simple-shuffle（默认）以获得最佳性能。

5. 禁用 'load_dotenv'

设置 export LITELLM_MODE="PRODUCTION"

这将禁用 load_dotenv() 功能，该功能通常会自动从本地的 .env 文件加载您的环境变量凭据。

6. 如果在 VPC 上运行 LiteLLM，请优雅地处理数据库不可用的情况

当在 VPC 上运行 LiteLLM（且无法从公共互联网访问）时，您可以启用优雅降级，以便即使数据库暂时不可用，请求处理仍能继续。

警告：仅当您在无法从公共互联网访问的 VPC 上运行 LiteLLM 时才这样做。

配置

litellm config.yaml

general_settings:
  allow_requests_on_db_unavailable: True

预期行为

当 allow_requests_on_db_unavailable 设置为 true 时，LiteLLM 将按如下方式处理错误：

错误类型	预期行为	详情
Prisma 错误	✅ 允许请求	涵盖由 LiteLLM 使用的 ORM（Prisma）导致的数据库连接重置或拒绝等问题。
Httpx 错误	✅ 允许请求	当数据库不可达时发生，允许请求在数据库中断的情况下继续进行。
Pod 启动行为	✅ Pod 照常启动	即使数据库关闭或不可达，LiteLLM Pod 也会启动，从而确保部署的更高正常运行时间。
健康/就绪检查	✅ 总是返回 200 OK	/health/readiness 端点返回 200 OK 状态，以确保即使在数据库不可用时，Pod 也能保持运行。
LiteLLM 预算错误或模型错误	❌ 阻塞请求	在数据库可达但身份验证令牌无效、缺乏访问权限或超过预算限制时触发。

关于数据库用途的更多信息请点击此处

7. 使用 Helm PreSync Hook 进行数据库迁移 [BETA]

为了确保只有一个服务管理数据库迁移，请使用我们的 Helm PreSync hook 进行数据库迁移。这可以确保迁移在 helm upgrade 或 helm install 期间处理，同时 LiteLLM Pod 会显式禁用迁移。

1. Helm PreSync Hook:
   • Helm PreSync hook 在 chart 中配置，以便在部署期间运行数据库迁移。
   • 该 hook 始终将 DISABLE_SCHEMA_UPDATE=false，确保迁移可靠执行。

在 ArgoCD 上设置 values.yaml 的参考设置

db:
  useExisting: true # use existing Postgres DB
  url: postgresql://ishaanjaffer0324:... # url of existing Postgres DB

2. LiteLLM Pod:

   • 在 LiteLLM Pod 配置中设置 DISABLE_SCHEMA_UPDATE=true，以防止它们运行迁移。

   LiteLLM Pod 配置示例

   env:
     - name: DISABLE_SCHEMA_UPDATE
       value: "true"

8. 设置 LiteLLM Salt Key

如果您打算使用数据库，请设置一个 salt key 用于加密/解密数据库中的变量。

添加模型后请勿更改此项。它用于加密/解密您的 LLM API 密钥凭据。

我们建议使用 https://1password.com/password-generator/ 密码生成器来获取用于 LiteLLM salt key 的随机哈希值。

export LITELLM_SALT_KEY="sk-1234"

查看代码

9. 使用 prisma migrate deploy

使用此命令处理生产环境中各 LiteLLM 版本之间的数据库迁移

环境变量

USE_PRISMA_MIGRATE="True"

CLI

litellm

优势

migrate deploy 命令

• 如果迁移历史中缺少已应用的迁移，则不会发出警告
• 不会检测漂移（例如由于热修复导致生产数据库架构与迁移历史最终状态不同）
• 不会重置数据库或生成工件（如 Prisma Client）
• 不依赖影子数据库

LiteLLM 如何处理生产环境中的数据库迁移？

1. 一个新的迁移文件被写入我们的 litellm-proxy-extras 包中。查看全部

2. 核心 litellm pip 包的版本会提升以指向新的 litellm-proxy-extras 包。这确保了旧版本的 LiteLLM 将继续使用旧的迁移。查看代码

3. 当您升级到新版本的 LiteLLM 时，迁移文件会应用于数据库。查看代码

只读文件系统

以 readOnlyRootFilesystem: true 运行 LiteLLM 是一种 Kubernetes 安全最佳实践，可防止容器进程写入根文件系统。LiteLLM 完全支持此配置。

权限错误的快速修复

如果您看到 Permission denied 错误，这意味着 LiteLLM Pod 正在以只读文件系统运行。LiteLLM 需要可写目录用于：

• 数据库迁移：设置 LITELLM_MIGRATION_DIR="/path/to/writable/directory"
• 管理 UI：设置 LITELLM_UI_PATH="/path/to/writable/directory"
• UI 资源/Logo：设置 LITELLM_ASSETS_PATH="/path/to/writable/directory"

完整的只读文件系统设置 (Kubernetes)

对于具有增强安全性的生产部署，请使用此配置：

选项 1：使用带有 InitContainer 的 EmptyDir 卷（推荐）

此方法在 Pod 启动时将预构建的 UI 从 Docker 镜像复制到可写的 emptyDir 卷中。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: litellm-proxy
spec:
  template:
    spec:
      initContainers:
        - name: setup-ui
          image: ghcr.io/berriai/litellm:main-stable
          command:
            - sh
            - -c
            - |
              cp -r /var/lib/litellm/ui/* /app/var/litellm/ui/ && \
              cp -r /var/lib/litellm/assets/* /app/var/litellm/assets/
          volumeMounts:
            - name: ui-volume
              mountPath: /app/var/litellm/ui
            - name: assets-volume
              mountPath: /app/var/litellm/assets

      containers:
        - name: litellm
          image: ghcr.io/berriai/litellm:main-stable
          env:
            - name: LITELLM_NON_ROOT
              value: "true"
            - name: LITELLM_UI_PATH
              value: "/app/var/litellm/ui"
            - name: LITELLM_ASSETS_PATH
              value: "/app/var/litellm/assets"
            - name: LITELLM_MIGRATION_DIR
              value: "/app/migrations"
            - name: PRISMA_BINARY_CACHE_DIR
              value: "/app/cache/prisma-python/binaries"
            - name: XDG_CACHE_HOME
              value: "/app/cache"
          securityContext:
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            runAsUser: 101
            capabilities:
              drop:
                - ALL
          volumeMounts:
            - name: config
              mountPath: /app/config.yaml
              subPath: config.yaml
              readOnly: true
            - name: ui-volume
              mountPath: /app/var/litellm/ui
            - name: assets-volume
              mountPath: /app/var/litellm/assets
            - name: cache
              mountPath: /app/cache
            - name: migrations
              mountPath: /app/migrations

      volumes:
        - name: config
          configMap:
            name: litellm-config
        - name: ui-volume
          emptyDir:
            sizeLimit: 100Mi
        - name: assets-volume
          emptyDir:
            sizeLimit: 10Mi
        - name: cache
          emptyDir:
            sizeLimit: 500Mi
        - name: migrations
          emptyDir:
            sizeLimit: 64Mi

选项 2：无 UI（仅 API 部署）

如果您不需要管理 UI，可以以最小化配置运行。

env:
  - name: LITELLM_NON_ROOT
    value: "true"
  - name: LITELLM_MIGRATION_DIR
    value: "/app/migrations"
securityContext:
  readOnlyRootFilesystem: true

代理会记录一条关于 UI 的警告，但 API 端点将正常工作。

只读文件系统的环境变量

变量	目的	默认
LITELLM_UI_PATH	管理 UI 目录	/var/lib/litellm/ui (Docker)
LITELLM_ASSETS_PATH	UI 资源/Logo	/var/lib/litellm/assets (Docker)
LITELLM_MIGRATION_DIR	数据库迁移	包目录
PRISMA_BINARY_CACHE_DIR	Prisma 二进制缓存	系统默认
XDG_CACHE_HOME	通用缓存目录	系统默认

重要说明

1. 迁移：始终将 LITELLM_MIGRATION_DIR 设置为可写的 emptyDir 路径
2. Prisma 缓存：将 PRISMA_BINARY_CACHE_DIR 和 XDG_CACHE_HOME 设置为可写路径
3. 服务器根路径：如果使用自定义的 server_root_path，您必须在 Dockerfile 中预处理 UI 文件，因为在只读文件系统下，代理无法在运行时修改文件。
4. 自动检测：如果 UI 包含 .litellm_ui_ready 标记文件（由官方 Docker 镜像创建），则会自动将其检测为预重构状态。

10. 使用单独的健康检查应用

信息

仅当通过 LiteLLM Docker 镜像运行并使用 Docker，且设置了环境变量 SEPARATE_HEALTH_APP="1" 时，才会运行单独的健康检查应用。

使用单独的健康检查应用可确保您的存活探针 (liveness probes) 和就绪探针 (readiness probes) 即使在主应用程序处于重负载下时也能保持响应。

为什么这很重要？

• 如果您的健康检查端点与主应用共享同一个进程，高流量或资源耗尽可能导致健康检查挂起或失败。
• 当 Kubernetes 存活探针挂起或超时时，它可能会错误地认为您的 Pod 不健康并重启它——即使主应用只是很忙，而不是已死。
• 通过在单独的轻量级 FastAPI 应用（拥有独立的端口）上运行健康检查端点，您可以保证健康检查的快速和可靠，防止在流量高峰或沉重工作负载期间发生不必要的 Pod 重启。
• 其工作原理是：如果健康检查应用或主代理应用因任何原因挂掉，它都会杀死该 Pod，从而将其标记为不健康，进而促使编排器重启 Pod。
• 由于代理和健康检查应用运行在同一个 Pod 中，如果 Pod 挂掉，健康检查探针会失败，这意味着 Pod 不健康，需要重启或采取相应措施。

如何启用

设置以下环境变量：

SEPARATE_HEALTH_APP="1" # Default "0" 
SEPARATE_HEALTH_PORT="8001" # Default "4001", Works only if `SEPARATE_HEALTH_APP` is "1"
SUPERVISORD_STOPWAITSECS="3600" # Optional: Upper bound timeout in seconds for graceful shutdown. Default: 3600 (1 hour). Only used when SEPARATE_HEALTH_APP=1.

优雅关机

之前未设置 stopwaitsecs，默认值为 10 秒，导致进行中的请求失败。SUPERVISORD_STOPWAITSECS（默认：3600）为优雅关机提供了一个上限，允许 Uvicorn 等待所有进行中的请求完成。

或在 Loom 上观看。

高层架构

附加内容

生产环境预期性能

查看基准测试在此处

验证调试日志已关闭

在代理服务器的日志中，您应该只看到以下详细级别的信息。

# INFO:     192.168.2.205:11774 - "POST /chat/completions HTTP/1.1" 200 OK
# INFO:     192.168.2.205:34717 - "POST /chat/completions HTTP/1.1" 200 OK
# INFO:     192.168.2.205:29734 - "POST /chat/completions HTTP/1.1" 200 OK