LiteLLM 入门完全指南（小白快速上手）

最新推荐文章于 2026-08-29 14:59:08 发布

原创最新推荐文章于 2026-08-29 14:59:08 发布 · 615 阅读

本内容遵循CC 4.0 BY-SA版权协议

简单来说，LiteLLM 是一个开源的 LLM 网关和 SDK，让你通过一套 API 格式就能调用超 100 种大语言模型。它由 BerriAI 团队维护，GitHub 上已获得超 22.6k Stars，并被 Netflix、Adobe 等公司用于生产环境。

LiteLLM 本身不是模型。你可以把它理解成一个“万能适配器”：

对外，它暴露的是 OpenAI 兼容的 API
对内，它可以接入 OpenAI、Anthropic、Gemini、本地 Ollama 等各种模型
效果：你的应用只需要认一个地址、一套调用方式，背后换什么模型都不用改代码

为什么你需要它？ 如果你用过不同厂商的大模型，一定会遇到这些问题：每个厂商的 API 格式不一样、切换模型要改一大堆代码、管理多个 API Key 让人头疼、费用也难以统一追踪。LiteLLM 就是为解决这些痛点而生的。

二、核心概念速览（5 分钟搞懂）

在动手之前，先理解这几个关键概念：

概念	简单解释
统一接口	无论调用哪个模型，请求和响应的格式都跟 OpenAI 一样
模型路由	根据任务复杂度自动选择不同模型：简单任务用便宜的，复杂任务用高级的
故障转移（Fallback）	主模型挂了，自动切到备用模型，保证服务不中断
成本追踪	实时统计每个请求花了多少钱（Token 用量 × 单价）
虚拟密钥（Virtual Key）	不直接暴露模型厂商的真实 API Key，而是生成虚拟 Key 来控制权限和预算
SDK 模式	在 Python 代码里直接 `import litellm` 调用模型，适合简单场景
Proxy 模式	把 LiteLLM 跑成一个独立服务，任何语言都能通过 HTTP 调用，适合团队使用

三、模式一：Python SDK（最快速上手）

适合场景：你只是想在自己的 Python 脚本里调用不同模型，暂时不需要团队管理、权限控制等功能。

3.1 环境准备

确保你的 Python 版本 ≥ 3.8：

python --version

3.2 安装 LiteLLM

打开终端，输入以下命令：

pip install litellm

3.3 设置 API Key

在使用模型之前，需要把对应的 API Key 设置为环境变量：

export OPENAI_API_KEY="你的OpenAI-Key"
export ANTHROPIC_API_KEY="你的Anthropic-Key"

Windows 用户用 set 代替 export。

如果你习惯用 .env 文件管理密钥，可以先安装 python-dotenv：

pip install python-dotenv

然后在项目目录下创建一个 .env 文件：

OPENAI_API_KEY=你的OpenAI-Key
ANTHROPIC_API_KEY=你的Anthropic-Key

3.4 发送第一个请求

创建一个 Python 文件，比如 hello_litellm.py：

from litellm import completion
import os

# 加载 .env 中的环境变量（可选）
from dotenv import load_dotenv
load_dotenv()

# 调用 OpenAI 的 GPT-4o
response = completion(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "你好，请用一句话介绍你自己"}]
)

# 打印回复内容
print(response.choices[0].message.content)

运行：

python hello_litellm.py

你应该能看到模型返回的文本。

3.5 切换模型只需改一个参数

这是 LiteLLM 最方便的地方。换一个模型，只需修改 model 参数：

# 调用 Anthropic Claude
response = completion(
    model="anthropic/claude-3-sonnet-20240229",
    messages=[{"role": "user", "content": "你好！"}]
)

# 调用本地 Ollama
response = completion(
    model="ollama/llama3",
    messages=[{"role": "user", "content": "用中文说一句问候语"}],
    api_base="http://localhost:11434"
)

模型命名规则：提供商名/模型名，例如 openai/gpt-4o、anthropic/claude-3-sonnet、ollama/llama3。

3.6 流式响应

对于需要实时看到输出结果的场景，可以开启流式模式：

response = completion(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "写一首关于春天的五言绝句"}],
    stream=True
)

# 逐词打印
for chunk in response:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

3.7 异步调用

高并发场景下，使用异步调用可以大幅提升性能：

import asyncio
from litellm import acompletion

async def main():
    response = await acompletion(
        model="openai/gpt-4o",
        messages=[{"role": "user", "content": "你好！"}]
    )
    print(response.choices[0].message.content)

asyncio.run(main())

3.8 设置故障转移（Fallback）

当主要模型不可用时，自动切换到备用模型：

from litellm import completion

litellm.fallbacks = [
    {"openai/gpt-4o": ["anthropic/claude-3-sonnet"]}
]

# 如果 GPT-4o 调用失败，会自动尝试 Claude
response = completion(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "你好！"}]
)

四、模式二：Proxy Server 网关代理（团队使用推荐）

适合场景：多人团队、多项目共享模型资源、需要统一管理权限和预算。

Proxy 模式把 LiteLLM 跑成一个独立的 HTTP 服务，任何编程语言都能通过 http://localhost:4000 调用。

4.1 最简单的启动方式

# 安装 Proxy 依赖
pip install 'litellm[proxy]'

# 设置 API Key
export OPENAI_API_KEY="你的Key"

# 一行命令启动代理
litellm --model openai/gpt-4o-mini

访问 http://localhost:4000 即可使用。

4.2 用配置文件管理多个模型

创建 config.yaml：

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-3-sonnet-20240229
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3
      api_base: http://localhost:11434

general_settings:
  master_key: sk-1234  # 你的主密钥，访问代理时使用

启动代理：

litellm --config config.yaml

代理跑在 http://0.0.0.0:4000。

4.3 通过 HTTP 调用代理

启动后，用 curl 或任意 HTTP 客户端发送请求：

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-mini",
    "messages": [{"role": "user", "content": "Hello from LiteLLM Gateway"}]
  }'

也可以用 Python 的 OpenAI SDK 调用（注意 base_url 指向你的代理）：

from openai import OpenAI

client = OpenAI(
    api_key="sk-1234",
    base_url="http://localhost:4000"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好！"}]
)

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

这就实现了：代码只认 LiteLLM 代理，背后实际用的是哪个模型，完全由配置文件决定。

4.4 Docker Compose 部署（生产环境推荐）

如果要在服务器上长期运行，推荐使用 Docker Compose 部署。目录结构如下：

litellm/
├── docker-compose.yml
└── .env

docker-compose.yml：

services:
  litellm:
    image: docker.litellm.ai/berriai/litellm:main-stable
    ports:
      - "4000:4000"
    environment:
      DATABASE_URL: "postgresql://llmproxy:dbpassword9090@db:5432/litellm"
      STORE_MODEL_IN_DB: "True"
    env_file:
      - .env
    depends_on:
      - db

  db:
    image: postgres:16
    restart: always
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: llmproxy
      POSTGRES_PASSWORD: dbpassword9090
    ports:
      - "5432:5432"
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

.env 文件：

LITELLM_MASTER_KEY=sk-1234
OPENAI_API_KEY=你的OpenAI-Key
ANTHROPIC_API_KEY=你的Anthropic-Key

启动：

docker compose up -d

Proxy 跑在 http://localhost:4000，访问 http://localhost:4000/ui 可以打开管理界面。

4.5 通过 Admin UI 管理模型和 Key

启动代理后，在浏览器中打开 http://localhost:4000/ui，用 sk-1234 登录。在管理界面中你可以：

添加/删除模型
生成虚拟 Key 并设置预算
查看用量统计

4.6 虚拟 Key 与预算管理

为不同用户或项目生成独立的虚拟 Key，并设置预算上限：

虚拟 Key 是该文档涉及的功能，实际使用时请参考官方最新文档或 LiteLLM 管理后台的交互式指导。

在管理界面中，进入 Virtual Keys 页面，点击生成新 Key，设置 max_budget（预算上限），即可为不同项目分配不同的 Key。业务代码只需知道这个虚拟 Key，无需关心后面到底用的是哪家模型。

五、实战：接入本地 Ollama 模型

Ollama 可以让你在本地运行开源模型（如 Llama、Qwen 等），LiteLLM 则统一了调用接口，两者结合非常适合隐私敏感或离线使用场景。

5.1 安装 Ollama 并拉取模型

到 ollama.com 下载安装 Ollama，然后拉取模型：

ollama pull llama3

5.2 确保 Ollama 在运行

ollama serve

5.3 通过 LiteLLM 调用

SDK 方式：

from litellm import completion

response = completion(
    model="ollama/llama3",
    messages=[{"role": "user", "content": "写一个快速排序的 Python 实现"}],
    api_base="http://localhost:11434"
)
print(response.choices[0].message.content)

Proxy 方式，在 config.yaml 中添加：

model_list:
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3
      api_base: http://localhost:11434

然后就可以通过 HTTP 请求调用 model: "local-llama" 了。

六、支持的中国模型（国内用户重点关注）

LiteLLM 支持国内主流的大模型平台：

提供商	模型示例	说明
阿里云 DashScope（Qwen）	`qwen/qwen-plus`、`qwen/qwen-max`	通义千问系列
月之暗面 Moonshot	`moonshot/moonshot-v1-8k`	Kimi
智谱 Zhipu	`zhipu/glm-4`	ChatGLM 系列
DeepSeek	`deepseek/deepseek-chat`	性价比极高
SiliconFlow	`siliconflow/Qwen/Qwen2.5-VL-32B-Instruct`	模型聚合平台

使用示例：

# 调用通义千问
response = completion(
    model="qwen/qwen-plus",
    messages=[{"role": "user", "content": "介绍一下杭州"}],
    api_key="你的DashScope-Key"
)

# 调用 DeepSeek
response = completion(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "你好！"}],
    api_key="你的DeepSeek-Key"
)

七、常见问题与小贴士

Q1：报错 AuthenticationError？
检查 API Key 是否正确设置。用 echo $OPENAI_API_KEY（Mac/Linux）或 echo %OPENAI_API_KEY%（Windows）确认。
Q2：Python 版本报错？
LiteLLM 要求 Python 3.8+。
Q3：Proxy 模式端口被占用？
默认使用 4000 端口，可加参数指定其他端口：litellm --config config.yaml --port 8080
Q4：模型名怎么写才对？
格式是 提供商名/模型名，比如 openai/gpt-4o、ollama/llama3。
Q5：支持哪些类型的请求？
LiteLLM 支持聊天补全、文本补全、向量嵌入、图像生成、OCR、结果重排、批量请求等多种端点。
Q6：免费吗？
LiteLLM 本身完全开源免费。但调用各个模型提供商的 API 需要支付相应费用。
Q7：如何查看花了多少钱？
可在请求的响应中查看 usage 和 cost 字段。Proxy 模式下，管理 UI 还可以看到详细的用量统计和成本分析。
Q8：国内用户需要注意什么？
如果使用 OpenAI、Anthropic、Gemini 等海外 API，通常需要科学上网工具。建议优先使用国内可直接访问的模型（如通义千问、DeepSeek、Moonshot 等）。

八、推荐学习路径

阶段	学习内容	预计时间
第 1 天	安装 LiteLLM，用 SDK 模式发第一个请求	30 分钟
第 2 天	尝试切换不同模型，理解统一接口的意义	1 小时
第 3 天	搭建 Proxy Server，用配置文件管理多个模型	1 小时
第 4 天	接入本地 Ollama，体验离线使用	1 小时
第 5 天	学习虚拟 Key 管理、预算设置和 Admin UI	1 小时
长期	深入学习路由策略、缓存、可观测性等高级特性	按需

九、常用资源汇总

资源	链接
官方文档	docs.litellm.ai
GitHub 仓库	github.com/BerriAI/litellm
Python 包	pypi.org/project/litellm
Discord 社区	discord.gg/wuPM9dRgDw

标签

#AI Gateway