跳至主要内容

Docker, Helm, Terraform

LiteLLM OSS 无限制

在 LiteLLM OSS 上，您可以创建的**用户、密钥和团队数量没有限制**。

您可以在 此处 找到用于构建 litellm 代理的 Dockerfile

注意：生产环境至少需要 4 个 CPU 核心和 8 GB RAM。

快速入门​

信息

在拉取 docker 镜像时遇到问题？请通过 support@berri.ai 与我们联系。

要开始使用 Litellm，请在 shell 中运行以下命令

docker pull docker.litellm.ai/berriai/litellm:main-latest

查看所有 docker 镜像

Docker Run​

步骤 1. 创建 config.yaml​

示例 litellm_config.yaml

model_list:
  - model_name: azure-gpt-4o
    litellm_params:
      model: azure/<your-azure-model-deployment>
      api_base: os.environ/AZURE_API_BASE # runs os.getenv("AZURE_API_BASE")
      api_key: os.environ/AZURE_API_KEY # runs os.getenv("AZURE_API_KEY")
      api_version: "2025-01-01-preview"

步骤 2. 运行 Docker 镜像​

docker run \
    -v $(pwd)/litellm_config.yaml:/app/config.yaml \
    -e AZURE_API_KEY=d6*********** \
    -e AZURE_API_BASE=https://openai-***********/ \
    -p 4000:4000 \
    docker.litellm.ai/berriai/litellm:main-stable \
    --config /app/config.yaml --detailed_debug

获取最新镜像 👉 此处

步骤 3. 测试请求​

传递 model=azure-gpt-4o，这在步骤 1 中已设置

curl --location 'http://0.0.0.0:4000/chat/completions' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "azure-gpt-4o",
    "messages": [
        {
        "role": "user",
        "content": "what llm are you"
        }
    ]
}'

Docker Run - CLI 参数​

查看所有支持的 CLI 参数 此处

以下是如何运行 docker 镜像并将您的配置传递给 litellm

docker run docker.litellm.ai/berriai/litellm:main-stable --config your_config.yaml

以下是如何运行 docker 镜像并在 8002 端口启动 litellm，并设置 num_workers=8

docker run docker.litellm.ai/berriai/litellm:main-stable --port 8002 --num_workers 8

将 litellm 用作基础镜像​

# Use the provided base image
FROM docker.litellm.ai/berriai/litellm:main-stable

# Set the working directory to /app
WORKDIR /app

# Copy the configuration file into the container at /app
COPY config.yaml .

# Make sure your docker/entrypoint.sh is executable
RUN chmod +x ./docker/entrypoint.sh

# Expose the necessary port
EXPOSE 4000/tcp

# Override the CMD instruction with your desired command and arguments
# WARNING: FOR PROD DO NOT USE `--detailed_debug` it slows down response times, instead use the following CMD
# CMD ["--port", "4000", "--config", "config.yaml"]

CMD ["--port", "4000", "--config", "config.yaml", "--detailed_debug"]

从 litellm pip 包构建​

请按照这些说明从 litellm pip 包构建 docker 容器。如果您的公司对安全性/构建镜像有严格要求，您可以按照这些步骤操作。

注意：您需要将 schema.prisma 文件从 litellm 仓库 复制到您的构建目录，与 Dockerfile 和 requirements.txt 文件放在一起。

Dockerfile

FROM cgr.dev/chainguard/python:latest-dev

USER root
WORKDIR /app

ENV HOME=/home/litellm
ENV PATH="${HOME}/venv/bin:$PATH"

# Install runtime dependencies
RUN apk update && \
    apk add --no-cache gcc python3-dev openssl openssl-dev

RUN python -m venv ${HOME}/venv
RUN ${HOME}/venv/bin/pip install --no-cache-dir --upgrade pip

COPY requirements.txt .
RUN --mount=type=cache,target=${HOME}/.cache/pip \
    ${HOME}/venv/bin/pip install -r requirements.txt

# Copy Prisma schema file
COPY schema.prisma .

# Generate prisma client
RUN prisma generate

EXPOSE 4000/tcp

ENTRYPOINT ["litellm"]
CMD ["--port", "4000"]

示例 requirements.txt

litellm[proxy]==1.57.3 # Specify the litellm version you want to use
litellm-enterprise
prometheus_client
langfuse
prisma

构建 docker 镜像

docker build \
  -f Dockerfile.build_from_pip \
  -t litellm-proxy-with-pip-5 .

运行 docker 镜像

docker run \
    -v $(pwd)/litellm_config.yaml:/app/config.yaml \
    -e OPENAI_API_KEY="sk-1222" \
    -e DATABASE_URL="postgresql://xxxxxxxxx \
    -p 4000:4000 \
    litellm-proxy-with-pip-5 \
    --config /app/config.yaml --detailed_debug

Terraform​

感谢 Nicholas Cecere 的 LiteLLM 用户管理 Terraform

👉 前往此处获取 Terraform

Kubernetes​

部署基于配置文件 litellm 实例只需要一个简单的部署，通过 config map 加载 config.yaml 文件。同时，使用环境变量声明 API 密钥并将其作为不透明的 secret 附加也是一个好的做法。

apiVersion: v1
kind: ConfigMap
metadata:
  name: litellm-config-file
data:
  config.yaml: |
      model_list: 
        - model_name: gpt-4o
          litellm_params:
            model: azure/gpt-4o-ca
            api_base: https://my-endpoint-canada-berri992.openai.azure.com/
            api_key: os.environ/CA_AZURE_OPENAI_API_KEY
---
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: litellm-secrets
data:
  CA_AZURE_OPENAI_API_KEY: bWVvd19pbV9hX2NhdA== # your api key in base64
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: litellm-deployment
  labels:
    app: litellm
spec:
  selector:
    matchLabels:
      app: litellm
  template:
    metadata:
      labels:
        app: litellm
    spec:
      containers:
      - name: litellm
        image: docker.litellm.ai/berriai/litellm:main-stable # it is recommended to fix a version generally
        args:
          - "--config"
          - "/app/proxy_server_config.yaml"
        ports:
        - containerPort: 4000
        volumeMounts:
        - name: config-volume
          mountPath: /app/proxy_server_config.yaml
          subPath: config.yaml
        envFrom:
        - secretRef:
            name: litellm-secrets
      volumes:
        - name: config-volume
          configMap:
            name: litellm-config-file
信息

为了避免可预测性问题、回滚困难和环境不一致，请使用版本号或 SHA 摘要（例如，litellm:main-v1.30.3 或 litellm@sha256:12345abcdef...）代替 litellm:main-stable。

Helm Chart​

信息

[BETA] Helm Chart 处于 BETA 阶段。如果您遇到问题/有反馈，请告知我们 https://github.com/BerriAI/litellm/issues

当您希望将 litellm helm chart 作为其他 chart 的依赖项使用时，请使用此项。litellm-helm OCI 在此处托管 https://github.com/BerriAI/litellm/pkgs/container/litellm-helm

步骤 1. 拉取 litellm helm chart​

helm pull oci://docker.litellm.ai/berriai/litellm-helm

# Pulled: docker.litellm.ai/berriai/litellm-helm:0.1.2
# Digest: sha256:7d3ded1c99c1597f9ad4dc49d84327cf1db6e0faa0eeea0c614be5526ae94e2a

步骤 2. 解压缩 litellm helm​

解压缩在步骤 1 中拉取的特定版本

tar -zxvf litellm-helm-0.1.2.tgz

步骤 3. 安装 litellm helm​

helm install lite-helm ./litellm-helm

步骤 4. 将服务暴露到 localhost​

kubectl --namespace default port-forward $POD_NAME 8080:$CONTAINER_PORT

您的 LiteLLM 代理服务器现在正在运行于 http://127.0.0.1:4000。

就是这样！这是部署 litellm 的快速入门指南

发起 LLM API 请求​

信息

💡 前往 👉 发起您的第一个 LLM API 请求

LiteLLM 与多个 SDK 兼容 - 包括 OpenAI SDK、Anthropic SDK、Mistral SDK、LLamaIndex、Langchain (Js, Python)

部署选项​

文档使用场景
快速入门调用 100+ LLM + 负载均衡
与数据库一起部署+ 使用虚拟密钥 + 跟踪支出（注意：当与数据库一起部署时，需要在您的环境变量中提供 DATABASE_URL 和 LITELLM_MASTER_KEY）
LiteLLM 容器 + Redis+ 在多个 litellm 容器之间进行负载均衡
LiteLLM 数据库容器 + PostgresDB + Redis+ 使用虚拟密钥 + 跟踪支出 + 在多个 litellm 容器之间进行负载均衡

与数据库一起部署​

Docker, Kubernetes, Helm Chart​
高流量部署 (1000+ RPS)

如果您预计高流量（每秒 1000+ 个请求），**需要 Redis** 以防止数据库连接耗尽和死锁。

将此添加到您的配置中

general_settings:
  use_redis_transaction_buffer: true

litellm_settings:
  cache: true
  cache_params:
    type: redis
    host: your-redis-host

请参阅 解决数据库死锁 以获取详细信息。

要求

  • 需要一个 postgres 数据库（例如，Supabase、Neon 等）。在您的环境变量中设置 DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname>
  • 设置 LITELLM_MASTER_KEY，这是您的代理管理员密钥 - 您可以使用它来创建其他密钥（🚨 必须以 sk- 开头）

我们维护一个 单独的 Dockerfile，用于在运行与连接的 Postgres 数据库一起的 LiteLLM 代理时减少构建时间

docker pull docker.litellm.ai/berriai/litellm-database:main-stable
docker run \
    -v $(pwd)/litellm_config.yaml:/app/config.yaml \
    -e LITELLM_MASTER_KEY=sk-1234 \
    -e DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname> \
    -e AZURE_API_KEY=d6*********** \
    -e AZURE_API_BASE=https://openai-***********/ \
    -p 4000:4000 \
    docker.litellm.ai/berriai/litellm-database:main-stable \
    --config /app/config.yaml --detailed_debug

您的 LiteLLM 代理服务器现在正在运行于 http://0.0.0.0:4000。

使用 Redis 部署​

当您需要 litellm 在多个 litellm 容器之间进行负载均衡时，使用 Redis

唯一需要的更改是在您的 config.yaml 中设置 Redis。LiteLLM Proxy 支持在多个 litellm 实例之间共享 rpm/tpm，传递 redis_host、redis_password 和 redis_port 以启用此功能。（LiteLLM 将使用 Redis 来跟踪 rpm/tpm 使用情况）

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: azure/<your-deployment-name>
      api_base: <your-azure-endpoint>
      api_key: <your-azure-api-key>
      rpm: 6      # Rate limit for this deployment: in requests per minute (rpm)
  - model_name: gpt-4o
    litellm_params:
      model: azure/gpt-4o-ca
      api_base: https://my-endpoint-canada-berri992.openai.azure.com/
      api_key: <your-azure-api-key>
      rpm: 6
router_settings:
  redis_host: <your redis host>
  redis_password: <your redis password>
  redis_port: 1992

使用配置启动 docker 容器

docker run docker.litellm.ai/berriai/litellm:main-stable --config your_config.yaml

使用数据库 + Redis 部署​

唯一需要的更改是在您的 config.yaml 中设置 Redis。LiteLLM Proxy 支持在多个 litellm 实例之间共享 rpm/tpm，传递 redis_host、redis_password 和 redis_port 以启用此功能。（LiteLLM 将使用 Redis 来跟踪 rpm/tpm 使用情况）

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: azure/<your-deployment-name>
      api_base: <your-azure-endpoint>
      api_key: <your-azure-api-key>
      rpm: 6      # Rate limit for this deployment: in requests per minute (rpm)
  - model_name: gpt-4o
    litellm_params:
      model: azure/gpt-4o-ca
      api_base: https://my-endpoint-canada-berri992.openai.azure.com/
      api_key: <your-azure-api-key>
      rpm: 6
router_settings:
  redis_host: <your redis host>
  redis_password: <your redis password>
  redis_port: 1992

使用配置启动 litellm-database docker 容器

docker run --name litellm-proxy \
-e DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname> \
-p 4000:4000 \
docker.litellm.ai/berriai/litellm-database:main-stable --config your_config.yaml

(非 Root) - 无互联网连接​

默认情况下，prisma generate 会下载 prisma 的引擎二进制文件。这在没有互联网连接的情况下运行时可能会导致错误。

使用此 docker 镜像部署带有预生成 prisma 二进制文件的 litellm。

docker pull docker.litellm.ai/berriai/litellm-non_root:main-stable

已发布的 Docker 镜像链接

高级部署设置​

1. 自定义服务器根路径（Proxy 基础 URL）​

有关更多详细信息，请参阅 自定义根路径。

2. SSL 证书​

如果您需要为您的本地 litellm proxy 设置 ssl 证书，请使用此选项

在启动 litellm proxy 时，传递 ssl_keyfile_path（SSL 密钥文件的路径）和 ssl_certfile_path（SSL 证书文件的路径）

docker run docker.litellm.ai/berriai/litellm:main-stable \
    --ssl_keyfile_path ssl_test/keyfile.key \
    --ssl_certfile_path ssl_test/certfile.crt

在启动 litellm proxy 服务器时提供 ssl 证书

3. 使用 Hypercorn 的 Http/2​

如果您想使用 hypercorn 运行 proxy 以支持 http/2，请使用此选项

第 1 步：使用 hypercorn 构建您的自定义 docker 镜像

# Use the provided base image
FROM docker.litellm.ai/berriai/litellm:main-stable

# Set the working directory to /app
WORKDIR /app

# Copy the configuration file into the container at /app
COPY config.yaml .

# Make sure your docker/entrypoint.sh is executable
RUN chmod +x ./docker/entrypoint.sh

# Expose the necessary port
EXPOSE 4000/tcp

# 👉 Key Change: Install hypercorn
RUN pip install hypercorn

# Override the CMD instruction with your desired command and arguments
# WARNING: FOR PROD DO NOT USE `--detailed_debug` it slows down response times, instead use the following CMD
# CMD ["--port", "4000", "--config", "config.yaml"]

CMD ["--port", "4000", "--config", "config.yaml", "--detailed_debug"]

第 2 步：在启动 proxy 时传递 --run_hypercorn 标志

docker run \
    -v $(pwd)/proxy_config.yaml:/app/config.yaml \
    -p 4000:4000 \
    -e LITELLM_LOG="DEBUG"\
    -e SERVER_ROOT_PATH="/api/v1"\
    -e DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname> \
    -e LITELLM_MASTER_KEY="sk-1234"\
    your_custom_docker_image \
    --config /app/config.yaml
    --run_hypercorn

4. Keepalive 超时​

默认值为 5 秒。在请求之间，连接必须在此期间内接收到新数据，否则将被断开连接。

用法示例：在此示例中，我们将 keepalive 超时设置为 75 秒。

docker run
docker run docker.litellm.ai/berriai/litellm:main-stable \
    --keepalive_timeout 75

或者通过环境变量设置：在此示例中，我们将 keepalive 超时设置为 75 秒。

环境变量
export KEEPALIVE_TIMEOUT=75
docker run docker.litellm.ai/berriai/litellm:main-stable

在 N 个请求后重启 Workers​

通过在固定数量的请求后回收 workers 来缓解内存增长。设置后，每个 worker 在完成指定数量的请求后将重新启动。如果未设置，则默认禁用。

使用示例

docker run (CLI 标志)
docker run docker.litellm.ai/berriai/litellm:main-stable \
    --max_requests_before_restart 10000

或者通过环境变量设置

环境变量
export MAX_REQUESTS_BEFORE_RESTART=10000
docker run docker.litellm.ai/berriai/litellm:main-stable

5. s3、GCS Bucket Object/url 上的 config.yaml 文件​

如果您无法在部署服务上挂载配置文件（例如 - AWS Fargate、Railway 等），请使用此选项

LiteLLM Proxy 将从 s3 Bucket 或 GCS Bucket 读取您的 config.yaml

设置以下 .env 变量

LITELLM_CONFIG_BUCKET_TYPE = "gcs"                              # set this to "gcs"         
LITELLM_CONFIG_BUCKET_NAME = "litellm-proxy"                    # your bucket name on GCS
LITELLM_CONFIG_BUCKET_OBJECT_KEY = "proxy_config.yaml"         # object key on GCS

使用这些环境变量启动 litellm proxy - litellm 将从 GCS 读取您的配置

docker run --name litellm-proxy \
   -e DATABASE_URL=<database_url> \
   -e LITELLM_CONFIG_BUCKET_NAME=<bucket_name> \
   -e LITELLM_CONFIG_BUCKET_OBJECT_KEY="<object_key>> \
   -e LITELLM_CONFIG_BUCKET_TYPE="gcs" \
   -p 4000:4000 \
   docker.litellm.ai/berriai/litellm-database:main-stable --detailed_debug

6. 禁用拉取实时模型价格​

如果您看到长时间的冷启动时间或网络安全问题，请禁用从 LiteLLM 的 托管模型价格文件 拉取模型价格。

export LITELLM_LOCAL_MODEL_COST_MAP="True"

这将使用本地模型价格文件。

平台特定指南​

基于 Terraform 的 ECS 部署​

LiteLLM 维护一个专门的 Terraform 教程，用于在 ECS 上部署 proxy。请按照 litellm-ecs-deployment 仓库 中的分步指南，配置所需的 ECS 服务、任务定义和支持的 AWS 资源。

  1. 克隆教程仓库以查看 Terraform 模块和变量。
git clone https://github.com/BerriAI/litellm-ecs-deployment.git
cd litellm-ecs-deployment
  1. 在应用到您选择的工作区/帐户之前，初始化并验证 Terraform 项目。
terraform init
terraform plan
terraform apply
  1. 完成 terraform apply 后，执行 ./build.sh 将仓库推送到 ECR 并更新 ECS 集群。使用该端点（默认端口 4000）进行 API 请求到您的 LiteLLM proxy。

附加内容​

Docker compose​

步骤 1

这是一个示例 docker-compose.yml 文件

version: "3.9"
services:
  litellm:
    build:
      context: .
      args:
        target: runtime
    image: docker.litellm.ai/berriai/litellm:main-stable
    ports:
      - "4000:4000" # Map the container port to the host, change the host port if necessary
    volumes:
      - ./litellm-config.yaml:/app/config.yaml # Mount the local configuration file
    # You can change the port or number of workers as per your requirements or pass any new supported CLI argument. Make sure the port passed here matches with the container port defined above in `ports` value
    command: [ "--config", "/app/config.yaml", "--port", "4000", "--num_workers", "8" ]

# ...rest of your docker-compose config if any

第 2 步

创建一个 litellm-config.yaml 文件，其中包含相对于您的 docker-compose.yml 文件的 LiteLLM 配置。

查看配置文档 此处

步骤 3

根据您的 docker 安装，运行命令 docker-compose up 或 docker compose up。

使用 -d 标志以分离模式（后台）运行容器，例如 docker compose up -d

您的 LiteLLM 容器现在应该在定义的端口上运行，例如 4000。

基于 IAM 的 RDS 数据库身份验证​

  1. 设置 AWS 环境变量
export AWS_WEB_IDENTITY_TOKEN='/path/to/token'
export AWS_ROLE_NAME='arn:aws:iam::123456789012:role/MyRole'
export AWS_SESSION_NAME='MySession'

查看所有身份验证选项

  1. 将 RDS 凭据添加到环境变量
export DATABASE_USER="db-user"
export DATABASE_PORT="5432"
export DATABASE_HOST="database-1-instance-1.cs1ksmwz2xt3.us-west-2.rds.amazonaws.com"
export DATABASE_NAME="database-1-instance-1"
export DATABASE_SCHEMA="schema-name" # skip to use the default "public" schema
  1. 使用 iam+rds 运行代理
litellm --config /path/to/config.yaml --iam_token_db_auth

✨ 阻止网络爬虫​

注意：这是一个 企业版专属功能。

要阻止网络爬虫索引代理服务器端点，请在您的 litellm_config.yaml 文件中将 block_robots 设置为 true。

litellm_config.yaml
general_settings:
  block_robots: true

工作原理​

启用后，/robots.txt 端点将返回一个 200 状态码，内容如下

robots.txt
User-agent: *
Disallow: /

部署常见问题解答​

问：Postgres 是唯一支持的数据库吗？是否支持其他数据库（例如 Mongo）？

答：我们探索过 MySQL，但维护起来很困难，并导致客户出现错误。目前，PostgreSQL 是我们生产部署的主要支持数据库。

问：如果 Postgres 出现停机，LiteLLM 会如何反应？它会失效打开还是会发生 API 停机？

答：如果它在您的 VPC 上，您可以优雅地处理数据库不可用。有关更多详细信息，请参阅我们的生产指南：优雅地处理数据库不可用