serhiimandrykin/litellm

LiteLLM Docker镜像文档

1. 镜像概述

本镜像为LiteLLM的预构建Docker容器，基于BerriAI开源项目（https://github.com/BerriAI/litellm%EF%BC%89%E6%9E%84%E5%BB%BA%E3%80%82LiteLLM%E6%98%AF%E4%B8%80%E6%AC%BE%E5%A4%A7%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9E%8B%EF%BC%88LLM%EF%BC%89%E6%8E%A5%E5%8F%A3%E7%BB%9F%E4%B8%80%E5%B7%A5%E5%85%B7%EF%BC%8C%E6%97%A8%E5%9C%A8%E9%80%9A%E8%BF%87%E6%A0%87%E5%87%86%E5%8C%96API%E7%AE%80%E5%8C%96%E5%A4%9A%E6%A8%A1%E5%9E%8B%E8%B0%83%E7%94%A8%E6%B5%81%E7%A8%8B%EF%BC%8C%E4%BD%BF%E5%BC%80%E5%8F%91%E8%80%85%E6%97%A0%E9%9C%80%E9%92%88%E5%AF%B9%E4%B8%8D%E5%90%8CLLM%E5%8E%82%E5%95%86%EF%BC%88%E5%A6%82OpenAI%E3%80%81Anthropic%E3%80%81Google%E7%AD%89%EF%BC%89%E7%BC%96%E5%86%99%E5%B7%AE%E5%BC%82%E5%8C%96%E9%9B%86%E6%88%90%E4%BB%A3%E7%A0%81%E3%80%82%E8%AF%A5%E9%95%9C%E5%83%8F%E6%8F%90%E4%BE%9B%E5%BC%80%E7%AE%B1%E5%8D%B3%E7%94%A8%E7%9A%84%E9%83%A8%E7%BD%B2%E6%96%B9%E6%A1%88%EF%BC%8C%E6%B6%88%E9%99%A4%E6%89%8B%E5%8A%A8%E6%9E%84%E5%BB%BA%E4%BE%9D%E8%B5%96%EF%BC%8C%E6%94%AF%E6%8C%81%E5%BF%AB%E9%80%9F%E6%90%AD%E5%BB%BALLM%E7%BB%9F%E4%B8%80%E8%B0%83%E7%94%A8%E6%9C%8D%E5%8A%A1%E3%80%82

2. 核心功能与特性

• 多模型兼容：支持主流LLM提供商，包括OpenAI（GPT系列）、Anthropic（Claude系列）、Google（Gemini）、AWS Bedrock、Cohere、Hugging Face等
• API标准化：兼容OpenAI API格式，现有OpenAI客户端可无缝切换至其他模型，无需修改调用代码
• 内置代理服务：提供HTTP端点（默认端口4000）接收LLM请求，支持同步/异步调用模式
• 请求管理：集成批处理请求、超时控制、自动重试机制，提升服务稳定性
• 缓存优化：支持Redis/内存缓存，减少重复请求成本，提高响应速度
• 可观测性：提供结构化日志输出，支持日志级别配置（debug/info/warn/error），便于问题排查

3. 使用场景与适用范围

• 多模型集成应用：需在单一系统中调用多种LLM的场景（如模型对比、任务路由、成本优化）
• LLM应用开发：快速搭建开发/测试环境，无需本地配置多厂商SDK与依赖
• 生产环境部署：通过容器化确保环境一致性，简化水平扩展与版本管理
• API网关服务：作为LLM请求统一入口，实现权限控制、流量管理、模型路由等功能

4. 使用方法与配置说明

4.1 基本部署（docker run）

4.1.1 快速启动（默认配置）

bash
docker run -d -p 4000:4000 --name litellm berriai/litellm:latest

4.1.2 带API密钥的典型部署

bash
docker run -d -p 4000:4000 \
  -e OPENAI_API_KEY="your-openai-key" \
  -e ANTHROPIC_API_KEY="your-anthropic-key" \
  -e LOG_LEVEL="info" \
  --name litellm berriai/litellm:latest

4.2 docker-compose配置示例

yaml
version: '3.8'
services:
  litellm:
    image: berriai/litellm:latest
    container_name: litellm-service
    restart: unless-stopped
    ports:
      - "4000:4000"  # 映射服务端口
    environment:
      # 基础配置
      - PORT=4000  # 服务监听端口（容器内）
      - LOG_LEVEL=info  # 日志级别
      # LLM API密钥（按需配置）
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}  # Bedrock需要
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}  # Bedrock需要
      # 缓存配置（可选）
      - CACHE_TYPE=redis
      - REDIS_URL=redis://redis:6379  # 需配合redis服务
    volumes:
      - ./litellm_config.yaml:/app/config/litellm_config.yaml  # 挂载自定义配置
    depends_on:
      - redis  # 如使用Redis缓存

  redis:
    image: redis:alpine
    container_name: litellm-redis
    ports:
      - "6379:6379"

4.3 环境变量配置

4.4 自定义配置文件

通过挂载YAML配置文件实现高级定制（需设置LITELLM_CONFIG环境变量指定路径），支持模型路由、超时控制、默认参数等配置。示例配置（litellm_config.yaml）：

yaml
# 模型列表配置
model_list:
  - model_name: gpt-3.5-turbo  # 自定义模型别名
    litellm_params:
      model: openai/gpt-3.5-turbo  # 实际模型标识
      api_key: ${OPENAI_API_KEY}   # 引用环境变量
      temperature: 0.7             # 默认温度值
  - model_name: claude-3-sonnet
    litellm_params:
      model: anthropic/claude-3-sonnet-20240229
      api_key: ${ANTHROPIC_API_KEY}
      max_tokens: 4096             # 默认最大token数

# 全局设置
general_settings:
  timeout: 60  # 请求超时时间（秒）
  max_retries: 2  # 失败重试次数
  allowed_origins: "*"  # CORS配置

挂载配置文件启动命令：

bash
docker run -d -p 4000:4000 \
  -v $(pwd)/litellm_config.yaml:/app/config/litellm_config.yaml \
  -e LITELLM_CONFIG=/app/config/litellm_config.yaml \
  -e OPENAI_API_KEY="your-key" \
  berriai/litellm:latest

4.5 API调用示例

服务启动后，可通过HTTP请求调用LLM，接口格式与OpenAI兼容：

调用默认模型（需配置模型列表默认项）

bash
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello LiteLLM!"}]
  }'

调用指定厂商模型

bash
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3-sonnet-20240229",  # 直接指定厂商模型标识
    "messages": [{"role": "user", "content": "Hello LiteLLM!"}]
  }'

5. 注意事项

• 安全建议：API密钥等敏感信息通过环境变量注入，避免硬编码；生产环境建议启用API密钥认证（参考官方文档配置api_key参数）
• 资源配置：根据请求量调整容器资源（推荐至少1核CPU/2GB内存），高并发场景需配置负载均衡
• 版本管理：生产环境优先使用具体版本标签（如v1.30.0）而非latest，避免自动更新导致兼容性问题
• 网络策略：如需外部访问，确保宿主机端口映射正确，并通过防火墙限制访问源IP