LiteLLM 统一 LLM API 调用

FreeGuideOnline 最新 2026-07-11

bash pip install litellm


如需特定提供商的依赖，可以额外安装，例如：

```bash
pip install litellm[openai,azure,anthropic]

一分钟完成第一次调用

只需指定模型名和消息，剩余工作交给 LiteLLM：

import litellm

response = litellm.completion(
    model="openai/gpt-3.5-turbo",
    messages=[{"role": "user", "content": "用一句话介绍 LiteLLM"}]
)
print(response.choices[0].message.content)

输出将是你熟悉的 OpenAI 格式，但实际请求被 LiteLLM 自动路由到了 OpenAI 的 API。

核心概念：模型标识与格式

模型命名规范

LiteLLM 采用 provider/model_name 的格式来唯一标识模型。常见写法：

openai/gpt-4
anthropic/claude-3-opus-20240229
cohere/command-r-plus
azure/<your-deployment-name>
huggingface/mistralai/Mistral-7B-Instruct-v0.2

如果模型在某个提供商中是唯一的，你也可以直接使用简短名称，例如 gpt-3.5-turbo 会被自动识别为 OpenAI 模型。

输入输出格式

无论底层模型是什么，litellm.completion() 始终返回标准化的响应对象。结构完全仿照 OpenAI：

response.choices[0].message.content   # 文本回复
response.usage.total_tokens           # 总 token 数
response.model                        # 实际调用的模型名

这种一致性让你可以轻松编写处理函数，无需关心后端差异。

统一调用实战详解

文本补全（completion）

最常用的对话生成场景：

response = litellm.completion(
    model="anthropic/claude-3-haiku-20240307",
    messages=[
        {"role": "system", "content": "你是一个翻译助手"},
        {"role": "user", "content": "将'Hello, world'翻译成法语"}
    ],
    temperature=0.3,
    max_tokens=100
)

流式输出（streaming）

只需添加 stream=True，即可逐块获取响应：

response = litellm.completion(
    model="openai/gpt-4",
    messages=[{"role": "user", "content": "讲一个关于程序员的笑话"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

函数调用（Function Calling）

LiteLLM 也支持工具调用，格式与 OpenAI 保持一致：

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "城市名"}
                },
                "required": ["location"]
            }
        }
    }
]

response = litellm.completion(
    model="openai/gpt-4-turbo",
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto"
)

多提供商配置与 API 密钥管理

设置 API 密钥

LiteLLM 会从环境变量中自动读取对应提供商的密钥，无需在代码中传递：

export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export COHERE_API_KEY="your-cohere-key"

若需要在代码中动态设置，可以使用 litellm.api_key 或 provider 专属参数，但更推荐环境变量方式以保障安全。

Azure 特殊配置

Azure OpenAI 需要基础信息：

import litellm
litellm.api_base = "https://your-endpoint.openai.azure.com/"
litellm.api_version = "2023-12-01-preview"
# API key 仍从环境变量 AZURE_API_KEY 读取
response = litellm.completion(
    model="azure/your-deployment",
    messages=[{"role": "user", "content": "Hello"}]
)

错误处理与重试机制

统一异常捕获

LiteLLM 将各类提供商的错误统一为 litellm.exceptions.* 异常类，便于集中处理：

from litellm import completion, exceptions

try:
    response = completion(model="openai/gpt-4", messages=[...])
except exceptions.AuthenticationError:
    print("API 密钥无效")
except exceptions.RateLimitError:
    print("速率超限，稍后重试")
except exceptions.ServiceUnavailableError:
    print("服务暂时不可用")
except exceptions.APIError as e:
    print(f"其他 API 错误: {e}")

内置重试

在调用时设置 num_retries 参数，即可在发生瞬时错误时自动重试：

response = litellm.completion(
    model="anthropic/claude-3-sonnet",
    messages=[...],
    num_retries=3
)

LiteLLM 默认采用指数退避策略，你还可以通过 litellm.set_verbose=True 查看重试日志。

高级功能与最佳实践

成本追踪与使用量统计

开启 success_callback 和 failure_callback 可以记录每次调用的 token 用量和成本：

import litellm

def track_cost(kwargs, completion_response, start_time, end_time):
    cost = litellm.completion_cost(completion_response)
    print(f"本次调用模型: {kwargs['model']}，花费: ${cost:.6f}")

litellm.success_callback = [track_cost]

LiteLLM 内置了各模型的定价数据，completion_cost() 可自动计算费用。

并发调用与异步支持

使用 acompletion 实现异步请求，提升吞吐量：

import asyncio
from litellm import acompletion

async def main():
    response = await acompletion(
        model="openai/gpt-3.5-turbo",
        messages=[{"role": "user", "content": "异步调用测试"}]
    )
    print(response.choices[0].message.content)

asyncio.run(main())

通过路由器实现负载均衡与故障转移

LiteLLM 提供了 Router 类，可配置多个模型作为后备，或实现负载均衡：

from litellm import Router

model_list = [
    {"model_name": "gpt-3.5", "litellm_params": {"model": "openai/gpt-3.5-turbo"}},
    {"model_name": "gpt-3.5", "litellm_params": {"model": "azure/gpt-35-turbo"}}
]

router = Router(model_list=model_list, routing_strategy="usage-based")

response = router.completion(
    model="gpt-3.5",
    messages=[{"role": "user", "content": "负载均衡示例"}]
)

当某个实例调用失败时，路由器可自动切换到下一个可用模型，保证服务高可用。

常见问题与调试

如何查看实际发送的请求

设置 litellm.set_verbose=True 可以在控制台看到详细的请求体和响应头，方便调试。

模型不支持某些参数怎么办

不同提供商允许的参数有差异。使用 litellm.drop_params=True 可以让 LiteLLM 自动删除提供商不支持的参数，避免调用报错：

litellm.drop_params = True
response = litellm.completion(
    model="cohere/command-r-plus",
    messages=[...],
    temperature=0.5,
    top_p=0.9  # Cohere 可能不支持 top_p，会被自动忽略
)