跳至主要内容

入门教程

LiteLLM Proxy 端到端教程，旨在：

  • 添加 Azure OpenAI 模型
  • 成功发起 /chat/completion 调用
  • 生成虚拟密钥
  • 为虚拟密钥设置每分钟请求数（RPM）限制

快速安装（推荐本地使用/新手）​

刚接触 LiteLLM？这是本地上手最简单的方法。只需一条命令即可安装 LiteLLM，并引导您通过交互式方式完成设置——无需手动编写配置文件。

1. 安装​

curl -fsSL https://raw.githubusercontent.com/BerriAI/litellm/main/scripts/install.sh | sh

该脚本会自动检测您的操作系统，安装 litellm[proxy]，并直接进入设置向导。

2. 按照向导操作​

$ litellm --setup

  Welcome to LiteLLM

  Choose your LLM providers
  ○ 1. OpenAI        GPT-4o, GPT-4o-mini, o1
  ○ 2. Anthropic     Claude Opus, Sonnet, Haiku
  ○ 3. Azure OpenAI  GPT-4o via Azure
  ○ 4. Google Gemini Gemini 2.0 Flash, 1.5 Pro
  ○ 5. AWS Bedrock   Claude, Llama via AWS
  ○ 6. Ollama        Local models

  ❯ Provider(s): 1,2

  ❯ OpenAI API key: sk-...
  ❯ Anthropic API key: sk-ant-...

  ❯ Port [4000]:
  ❯ Master key [auto-generate]:

  ✔ Config saved → ./litellm_config.yaml

  ❯ Start the proxy now? (Y/n):

向导将引导您完成：

  1. 选择您的 LLM 提供商（OpenAI、Anthropic、Azure、Bedrock、Gemini、Ollama）
  2. 输入各提供商的 API 密钥
  3. 设置端口和主密钥（或接受默认值）
  4. 配置将保存到 ./litellm_config.yaml，代理随即启动

3. 发起调用​

您的代理正在 http://0.0.0.0:4000 上运行。请进行测试

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your-master-key>' \
-d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
}'
已经安装了 uv？

您可以跳过 curl 安装，在运行 uv tool install 'litellm[proxy]' 后直接执行 litellm --setup。

先决条件​

请选择您的安装方式。Docker Compose 用户在标签页内完成全部设置即可。Docker 和 LiteLLM CLI 用户请继续按照标签页下方的步骤操作。

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

查看所有 docker 镜像

Docker Compose 用户

您的设置已完成——以下步骤仅针对 Docker 和 LiteLLM CLI 用户。

第一步 — 添加模型​

使用 config.yaml 文件控制 LiteLLM 代理。创建一个包含您的 Azure 模型的文件

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: azure/my_azure_deployment
      api_base: os.environ/AZURE_API_BASE
      api_key: "os.environ/AZURE_API_KEY"
      api_version: "2025-01-01-preview" # [OPTIONAL] litellm uses the latest azure api_version by default

模型列表规范​

您可以在模型配置部分详细了解模型解析的工作原理。

  • model_name (str) - 该字段应包含接收到的模型名称。
  • litellm_params (dict) 查看所有 LiteLLM 参数
    • model (str) - 指定发送给 litellm.acompletion / litellm.aembedding 等的模型名称。这是 LiteLLM 在后端路由到正确的模型和提供商逻辑时使用的标识符。
    • api_key (str) - 身份验证所需的 API 密钥。可以通过 os.environ/ 从环境变量中获取。
    • api_base (str) - 您 Azure 部署的 API 基础地址。
    • api_version (str) - 调用 Azure OpenAI API 时使用的 API 版本。点击此处获取最新的 Inference API 版本。

2. 成功发起 /chat/completion 调用​

LiteLLM 代理 100% 兼容 OpenAI。通过 /chat/completions 路由测试您的 Azure 模型。

2.1 启动代理​

将第一步中的 config.yaml 保存为 litellm_config.yaml。

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-latest \
    --config /app/config.yaml --detailed_debug

# RUNNING on http://0.0.0.0:4000

确认您的配置已正确加载——您应该能在日志中看到相关信息

Loaded config YAML (api_key and environment_variables are not shown):
{
  "model_list": [
    {
      "model_name": ...

2.2 发起调用​

LiteLLM 代理 100% 兼容 OpenAI。通过 /chat/completions 测试您的模型

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-1234' \
-d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are an LLM named gpt-4o"
      },
      {
        "role": "user",
        "content": "what is your name?"
      }
    ]
}'

预期响应

{
  "id": "chatcmpl-BcO8tRQmQV6Dfw6onqMufxPkLLkA8",
  "created": 1748488967,
  "model": "gpt-4o-2024-11-20",
  "object": "chat.completion",
  "system_fingerprint": "fp_ee1d74bde0",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "My name is **gpt-4o**! How can I assist you today?",
        "role": "assistant",
        "tool_calls": null,
        "function_call": null,
        "annotations": []
      }
    }
  ],
  "usage": {
    "completion_tokens": 19,
    "prompt_tokens": 28,
    "total_tokens": 47,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cached_tokens": 0
    }
  },
  "service_tier": null,
  "prompt_filter_results": [
    {
      "prompt_index": 0,
      "content_filter_results": {
        "hate": {
          "filtered": false,
          "severity": "safe"
        },
        "self_harm": {
          "filtered": false,
          "severity": "safe"
        },
        "sexual": {
          "filtered": false,
          "severity": "safe"
        },
        "violence": {
          "filtered": false,
          "severity": "safe"
        }
      }
    }
  ]
}

可选：生成虚拟密钥​

通过代理的虚拟密钥跟踪消费并控制模型访问。

先决条件 — 设置数据库​

Docker Compose 用户

您的 Postgres 容器已经运行——直接跳到下方的 创建带 RPM 限制的密钥。

Docker / LiteLLM CLI 用户 — 您需要一个 Postgres 数据库（例如 Supabase、Neon 或自托管）。在 config.yaml 中添加 general_settings

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: azure/my_azure_deployment
      api_base: os.environ/AZURE_API_BASE
      api_key: "os.environ/AZURE_API_KEY"
      api_version: "2025-01-01-preview" # [OPTIONAL] litellm uses the latest azure api_version by default

general_settings: 
  master_key: sk-1234 
  database_url: "postgresql://<user>:<password>@<host>:<port>/<dbname>" # 👈 KEY CHANGE

继续操作前，请将 config.yaml 保存为 litellm_config.yaml。

启动代理服务器之前，必须完成此设置。

什么是 general_settings？

这些是 LiteLLM 代理服务器的设置。

点击此处查看所有常规设置。

  1. master_key (str)

    • 描述:
      • 设置一个 master key，这是您的代理管理密钥——您可以使用它创建其他密钥（🚨 必须以 sk- 开头）。
    • 用法:
      • 在 config.yaml 中设置：在 general_settings:master_key 下设置主密钥，例如 - master_key: sk-1234
      • 设置环境变量：设置 LITELLM_MASTER_KEY

  2. database_url (str)

    • 描述:
      • 设置一个 database_url，这是您的 Postgres 数据库连接地址，用于 litellm 生成密钥、用户和团队。
    • 用法:
      • 在 config.yaml 中设置：在 general_settings:database_url 下设置您的 database_url，例如 - database_url: "postgresql://..."
      • 在环境中设置 DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname>

启动代理​

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

创建带 RPM 限制的密钥​

创建一个 rpm_limit: 1 的密钥。这将只允许使用该密钥对代理发起的每分钟 1 次请求。

curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "rpm_limit": 1
}'

查看完整 API 规范

预期响应

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

测试它！​

使用您刚创建的虚拟密钥。

第 1 次调用 - 预期成功！

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-12...' \
-d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful math tutor. Guide the user through the solution step by step."
      },
      {
        "role": "user",
        "content": "how can I solve 8x + 7 = -23"
      }
    ]
}'

预期响应

{
    "id": "chatcmpl-2076f062-3095-4052-a520-7c321c115c68",
    "choices": [
        ...
}

第 2 次调用 - 预期失败！

为什么这次调用失败了？

我们将该虚拟密钥的每分钟请求数 (RPM) 限制设置为 1。该限制现已被超过。

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-12...' \
-d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful math tutor. Guide the user through the solution step by step."
      },
      {
        "role": "user",
        "content": "how can I solve 8x + 7 = -23"
      }
    ]
}'

预期响应

{
  "error": {
    "message": "LiteLLM Rate Limit Handler for rate limit type = key. Crossed TPM / RPM / Max Parallel Request Limit. current rpm: 1, rpm limit: 1, current tpm: 348, tpm limit: 9223372036854775807, current max_parallel_requests: 0, max_parallel_requests: 9223372036854775807",
    "type": "None",
    "param": "None",
    "code": "429"
  }
}

核心概念​

本节介绍 LiteLLM AI 网关的核心概念。

理解模型配置​

针对此 config.yaml 示例

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: azure/my_azure_deployment
      api_base: os.environ/AZURE_API_BASE
      api_key: "os.environ/AZURE_API_KEY"
      api_version: "2025-01-01-preview" # [OPTIONAL] litellm uses the latest azure api_version by default

模型解析的工作原理

Client Request                LiteLLM Proxy                 Provider API
──────────────              ────────────────              ─────────────
    
POST /chat/completions      
{                           1. Looks up model_name
  "model": "gpt-4o" ──────────▶ in config.yaml
  ...                          
}                           2. Finds matching entry:
                               model_name: gpt-4o
                               
                            3. Extracts litellm_params:
                               model: azure/my_azure_deployment
                               api_base: https://...
                               api_key: sk-...
                               
                            4. Routes to provider ──▶ Azure OpenAI API
                                                      POST /deployments/my_azure_deployment/...

解析 litellm_params 下的 model 参数

model_list:
  - model_name: gpt-4o                       # What the client calls
    litellm_params:
      model: azure/my_azure_deployment       # <provider>/<model-name>
             ─────  ───────────────────
               │           │
               │           └─────▶ Model name sent to the provider API
               │
               └─────────────────▶ Provider that LiteLLM routes to

视觉分解

model: azure/my_azure_deployment
       └─┬─┘ └─────────┬─────────┘
         │             │
         │             └────▶ The actual model identifier that gets sent to Azure
         │                   (e.g., your deployment name, or the model name)
         │
         └──────────────────▶ Tells LiteLLM which provider to use
                             (azure, openai, anthropic, bedrock, etc.)

核心概念

  • model_name：客户端调用模型时使用的别名。这是您在 API 请求中发送的内容（例如，gpt-4o）。

  • model (在 litellm_params 中)：格式为 <provider>/<model-identifier>

    • 提供商（/ 之前）：路由到正确的 LLM 提供商（例如，azure, openai, anthropic, bedrock）
    • 模型标识符（/ 之后）：发送到该提供商 API 的实际模型/部署名称

高级配置示例

针对自定义 OpenAI 兼容端点（例如，vLLM、Ollama、自定义部署）

model_list:
  - model_name: my-custom-model
    litellm_params:
      model: openai/nvidia/llama-3.2-nv-embedqa-1b-v2
      api_base: http://my-service.svc.cluster.local:8000/v1
      api_key: "sk-1234"

解析复杂的模型路径

model: openai/nvidia/llama-3.2-nv-embedqa-1b-v2
       └─┬──┘ └────────────┬────────────────┘
         │                 │
         │                 └────▶ Full model string sent to the provider API
         │                       (in this case: "nvidia/llama-3.2-nv-embedqa-1b-v2")
         │
         └──────────────────────▶ Provider (openai = OpenAI-compatible API)

关键点：第一个 / 之后的所有内容都将按原样传递给提供商的 API。

通用模式

model_list:
  # Azure deployment
  - model_name: gpt-4
    litellm_params:
      model: azure/gpt-4-deployment
      api_base: https://my-azure.openai.azure.com
      
  # OpenAI
  - model_name: gpt-4
    litellm_params:
      model: openai/gpt-4
      api_key: os.environ/OPENAI_API_KEY
      
  # Custom OpenAI-compatible endpoint
  - model_name: my-llama-model
    litellm_params:
      model: openai/meta/llama-3-8b
      api_base: http://my-vllm-server:8000/v1
      api_key: "optional-key"
      
  # Bedrock
  - model_name: claude-3
    litellm_params:
      model: bedrock/anthropic.claude-3-sonnet-20240229-v1:0
      aws_region_name: us-east-1

故障排除​

prometheus.yml 挂载错误 — "not a directory"​

如果您看到

Error: cannot create subdirectories in ".../prometheus.yml": not a directory

Docker 将 prometheus.yml 创建为一个空目录而不是一个文件。这发生在 docker compose up 时缺少该文件的情况下。

修复方法：创建该文件（参见 第二步 2.3 — 创建 prometheus.yml）并再次运行 docker compose up。

rm -rf prometheus.yml

然后创建该文件（参见 第二步 2.4）并再次运行 docker compose up。

非 root docker 镜像？​

如果您需要以非 root 用户身份运行 docker 镜像，请使用此镜像。

SSL 验证问题 / 连接错误。​

如果您看到

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1006)

或者

Connection Error.

您可以禁用 SSL 验证

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: azure/my_azure_deployment
      api_base: os.environ/AZURE_API_BASE
      api_key: "os.environ/AZURE_API_KEY"
      api_version: "2025-01-01-preview"

litellm_settings:
    ssl_verify: false # 👈 KEY CHANGE

(数据库) 所有连接尝试均失败​

如果您看到

httpx.ConnectError: All connection attempts failed                                                                        
                                                                                                                         
ERROR:    Application startup failed. Exiting.                                                                            
3:21:43 - LiteLLM Proxy:ERROR: utils.py:2207 - Error getting LiteLLM_SpendLogs row count: All connection attempts failed

这可能是数据库权限问题。

  1. 验证数据库用户权限问题

尝试创建一个新数据库。

STATEMENT: CREATE DATABASE "litellm"

如果您收到

ERROR: permission denied to create

这表明您存在权限问题。

  1. 向您的数据库用户授予权限

它应该看起来像这样

psql -U postgres
CREATE DATABASE litellm;

在 CloudSQL 上，这是

GRANT ALL PRIVILEGES ON DATABASE litellm TO your_username;

什么是 litellm_settings？

LiteLLM 代理使用 LiteLLM Python SDK 来处理 LLM API 调用。

litellm_settings 是 LiteLLM Python SDK 的模块级参数（等同于在 SDK 上执行 litellm.<some_param>）。您可以点击此处查看所有参数

支持与联系创始人​

Chat on WhatsApp Chat on Discord

🚅
LiteLLM 企业版
SSO/SAML、审计日志、支出跟踪、多团队管理和护栏 —— 专为生产环境构建。
了解更多 →