litellm 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

litellm 是 BerriAI 维护的开源人工智能网关（AI Gateway），提供 Python 软件开发工具包（Python SDK）和代理服务器（Proxy Server）两种使用方式。仓库描述将其定位为“Rust core with Python SDK”，README 则强调它可以用 OpenAI 格式调用 100 多个大语言模型（LLM）提供商。

截至给定仓库资料，项目有 59,157 个 Star 和 11,581 个 Fork，主要语言标注为 Python，默认分支为 main。pyproject.toml 中的项目版本为 1.103.0，支持 Python >=3.10, <3.15；GitHub 元信息中的许可证字段显示为 NOASSERTION，但仓库 LICENSE 文件明确给出了 MIT 许可及企业目录的单独许可说明。

• 统一调用：将多个模型提供商的调用入口收敛到统一接口。
• 部署形态：既可以作为 Python 库集成，也可以运行集中式网关。
• 网关能力：README 列出虚拟密钥、消费追踪、护栏、负载均衡和管理界面。
• 运行方式：仓库提供 Dockerfile 和 Docker Compose 配置，Compose 示例使用端口 4000 暴露服务。

定位与目标用户

LiteLLM 的核心定位不是单一模型客户端，而是位于应用与多个模型提供商之间的适配层。应用侧使用统一请求格式，网关侧负责将请求转发至 OpenAI、Anthropic、Gemini、Bedrock、Azure 等提供商；README 将这一能力概括为“Call any LLM in OpenAI format”。

该定位适合需要统一认证、成本统计、路由和日志入口的团队。若应用只调用单一提供商，并且不需要代理、模型路由或集中治理，直接使用对应提供商客户端的架构更简单；这一判断属于根据本文作者的经验判断，仓库资料没有提供针对该场景的官方选型结论。

• 应用需要在多个模型提供商之间切换，而不希望修改每个业务调用点。
• 团队希望把虚拟密钥、消费统计和模型访问控制集中管理。
• 部署环境要求自托管网关，数据路径和凭据由组织自行控制。
• 需要为模型调用增加负载均衡、日志或护栏处理。

核心功能

LiteLLM 的功能可以分成协议统一、网关治理和运行观测三层。下面的说明严格依据 README、pyproject.toml、Dockerfile 和 Compose 配置；未在资料中给出完整接口参数的部分，不补充未经验证的调用签名。

统一模型接口

统一接口的输入是应用侧的模型请求，输出是网关或 SDK 按统一格式返回的模型响应。README 指出项目支持 100 多个 LLM 提供商，并列举了 Bedrock、Azure、OpenAI、Anthropic、VertexAI、vLLM 和 Nvidia NIM 等名称。

该机制的价值在于将提供商差异集中在 LiteLLM 的适配层中。应用不必在每个业务模块中分别处理不同的认证方式、请求格式和错误类型；不过，具体模型能力、参数兼容性和提供商侧限制仍需以对应文档为准，仓库资料没有给出一份完整的能力对照表。

代理服务器与集中治理

代理服务器（Proxy Server）以独立服务的形式接收应用请求，并按照配置选择后端模型。README 将其描述为面向团队或组织的集中式 AI Gateway，仓库的 Docker Compose 文件则提供了 litellm 服务、PostgreSQL 数据库和 Prometheus 服务。

Compose 示例中设置 STORE_MODEL_IN_DB 为 True，注释说明该配置允许通过管理界面向代理添加模型。服务的健康检查访问 /health/liveliness，这说明该路径可用于 Compose 容器存活检查，但资料没有说明其他健康检查端点的语义。

成本追踪、虚拟密钥与护栏

README 将成本追踪、虚拟密钥和护栏列为生产网关能力。其工作链路可以表述为：请求进入网关后，网关根据认证信息和路由配置选择模型，再对请求结果及消费信息进行记录；护栏则属于请求或响应处理链路中的治理组件。

资料没有提供成本计算公式、计费数据源、护栏规则格式或虚拟密钥的完整配置字段，因此本文不对这些内部实现作进一步推断。生产部署时，应以官方文档和当前分支源码中的配置说明为准。

负载均衡与日志

README 将负载均衡和日志列为网关能力。负载均衡的输入是可用模型或提供商路由，输出是被选中的后端请求；日志的输入是调用事件，输出则取决于部署和存储配置。仓库资料没有给出具体的调度算法、重试策略、日志字段清单或保留周期。

因此，不能仅根据功能名称推断其具备固定的故障转移语义。需要确认路由、重试、超时和日志脱敏要求时，应查阅官方文档中的代理配置章节。

系统架构与关键模块

从仓库文件可以确认，项目包含 Python 核心包、代理运行依赖、管理界面构建流程、数据库和容器启动脚本。README 还将 Rust 核心列入项目描述，但给定文件资料没有展示 Rust 模块路径或编译入口，因此下文只描述已被文件直接证明的组件。

Dockerfile 使用多阶段构建：先准备 PgBouncer，再构建管理界面，随后安装 Python 依赖并生成最终运行镜像。其基础镜像、Node.js 镜像和 uv 镜像均使用了明确的版本或摘要固定值，但这些构建细节属于仓库当前 Docker 构建实现，不应直接等同于所有部署环境的最低要求。

依赖与运行环境

核心项目要求 Python 版本满足 >=3.10, <3.15。核心依赖包括 httpx[http2]、openai、python-dotenv、tiktoken、tokenizers、pydantic、jsonschema 和 boto3 等，具体版本范围以 pyproject.toml 为准。

代理部署使用单独的 proxy 可选依赖组，其中包含 fastapi、uvicorn、gunicorn、granian、redis 相关组件、PyJWT、cryptography、websockets 和管理界面相关包。仓库还定义了 extra_proxy、caching、mcp、saml、mlflow 等可选依赖组。

package.json 记录了 prism-react-renderer、prisma 和 react-copy-to-clipboard 等前端或工具依赖，并使用 Jest 和 Testing Library 作为开发依赖。Dockerfile 还安装了 Python 3.13、Rust、Node.js、npm、OpenSSL 和 libsndfile。

快速开始：Docker Compose 最小闭环

仓库提供的 Compose 文件已经包含 LiteLLM、PostgreSQL 和 Prometheus 三个服务，适合在本地或测试环境验证容器启动、数据库连接和健康检查。下面的命令以仓库根目录为工作目录，不代表生产环境的安全默认值。

安装：获取仓库并准备环境文件

git clone https://github.com/BerriAI/litellm.git
cd litellm
cp .env.example .env

.env.example 中包含 OpenAI、Cohere、OpenRouter 和 Azure 等环境变量示例。示例中的密钥字段应替换为测试环境凭据；本文不提供真实密钥，也不建议将凭据写入版本库。

运行：构建并启动服务

docker compose up --build -d

Compose 文件将 LiteLLM 映射到主机端口 4000，PostgreSQL 映射到 5432，Prometheus 映射到 9090。其中数据库用户、数据库名和密码在示例文件中是固定示例值，测试完成后应在本地环境中修改，不应直接用于生产部署。

验证：检查容器健康状态

curl http://localhost:4000/health/liveliness
docker compose ps

第一条命令对应 Compose 健康检查中使用的 URL；第二条命令用于查看服务状态。若健康检查失败，应优先检查容器日志、数据库服务状态、环境变量和端口占用，不能仅凭端口已监听判断网关已经正确连接后端模型。

配置说明

配置项分布在 docker-compose.yml 和 .env.example 中。下表只列出资料中明确出现的字段；“默认值”保留文件中的真实值，未在资料中给出的内容标记为“未提供”。

DATABASE_URL_READ_REPLICA 的注释说明，它可用于只读查询，例如 find_*、count、group_by、query_raw 和 _first。Compose 文件同时说明，单数据库部署可以不设置该字段；资料没有提供读写一致性、故障切换或连接池参数的完整说明。

进阶用法

进阶使用应围绕代理配置、提供商凭据、模型登记和可选依赖组展开。仓库 README 提供了代理文档入口和提供商文档入口，但给定资料没有包含完整的 config.yaml 样例，因此不能补写未经核实的模型路由字段。

• 需要集中式服务时，使用代理服务器文档中的部署方式，并按实际提供商设置环境变量。
• 需要从配置文件启动代理时，Compose 文件提供了挂载 ./config.yaml:/app/config.yaml 和传入 --config=/app/config.yaml 的注释示例。
• 需要管理界面登记模型时，确认 STORE_MODEL_IN_DB 的值，并为数据库设置持久化卷。
• 需要语义路由、SAML、缓存或 MLflow 集成时，检查 pyproject.toml 对应的可选依赖组。

services:
  litellm:
    volumes:
      - ./config.yaml:/app/config.yaml
    command:
      - "--config=/app/config.yaml"

上面的片段直接对应 Compose 文件中的注释配置。它只展示文件挂载和命令行参数，不虚构配置文件内部字段；实际配置格式应以官方代理文档和当前仓库示例为准。

可观测性与运维

仓库的 Compose 示例把 Prometheus 作为独立服务运行，并将其数据目录持久化到 prometheus_data 卷。Prometheus 服务使用 prom/prometheus 镜像，端口为 9090，数据保留参数在 Compose 命令中设置为 15d。

LiteLLM 服务的健康检查每 30 秒执行一次，超时时间为 10 秒，重试次数为 3，启动宽限期为 40 秒。这些参数只描述仓库 Compose 示例，不构成生产环境的可用性承诺；README 提到的“8ms P95 latency at 1k RPS”属于项目提供的基准描述，详细测试条件应通过 README 中的 Benchmark 文档核验。

• 使用 docker compose ps 查看服务状态。
• 使用 docker compose logs litellm 查看网关容器日志。
• 检查 http://localhost:4000/health/liveliness 是否返回健康响应。
• 检查 PostgreSQL 卷 litellm_postgres_data 是否存在并持续使用。
• 确认 Prometheus 配置文件 prometheus.yml 已按部署环境准备。

项目还在 README 中列出日志、成本追踪和管理界面，但给定资料没有提供指标名称、告警规则、日志脱敏策略或备份恢复流程。涉及这些运维决策时，应形成组织自己的运行手册。

安全与合规边界

LiteLLM 会接触模型访问凭据、用户请求、模型响应和成本记录，因此部署时必须把它视为敏感数据处理组件。本文只讨论在获得授权的本地、测试或组织内部环境中使用，不提供针对未授权目标的访问、绕过检测或凭据滥用方法。

• API 密钥应通过环境变量或受控密钥系统注入，不能将真实值提交到 Git 仓库。
• 生产环境不应直接沿用 Compose 文件中的示例数据库密码。
• 应限制代理服务的网络访问范围，并区分管理界面、数据库和业务调用方的权限。
• 发送到第三方模型提供商的数据必须经过组织的数据分类、隐私和跨境合规审查。
• 日志、消费记录和数据库备份应设置访问控制与保留策略；资料没有给出 LiteLLM 的统一默认保留规则。

仓库资料没有声明特定行业认证、数据驻留承诺、服务等级协议（SLA）或默认脱敏保证。不能将开源代码本身视为合规结论，具体要求应由部署组织结合提供商合同和适用法律完成评估。

许可证与商用条款

GitHub 元信息中的许可证字段为 NOASSERTION，但仓库根目录 LICENSE 文件写明：enterprise/ 目录中的内容，如该目录存在，按 enterprise/LICENSE 定义的许可证授权；企业目录之外的内容按 MIT License 提供。

“Content outside of the above mentioned directories or restrictions above is available under the MIT license as defined below.”

来源：README

根据 MIT 许可条款，授权范围包含使用、复制、修改、合并、发布、分发、再许可和销售软件副本，但分发软件或其主要部分时必须保留版权声明和许可声明。软件按“现状”提供，许可证文本不提供担保；企业目录及其依赖的具体授权应以仓库中的 enterprise/LICENSE 和根目录 LICENSE 为准。

因此，企业商用部署不能只依据项目名或 GitHub 页面标签判断授权范围。应在分发、修改或将企业目录纳入产品前审阅实际文件，并保留必要的版权和许可文本。

局限性与已知限制

LiteLLM 的统一接口降低了多提供商接入成本，但不会消除模型能力、计费规则、上下文限制和错误语义之间的差异。项目资料没有给出所有 100 多个提供商的版本兼容矩阵，也没有保证每个模型都支持完全相同的请求参数。

• 提供商列表和模型能力会随代码版本及第三方 API 变化，必须以当前文档为准。
• README 的性能数据没有在给定资料中展开测试拓扑、请求类型和硬件条件，不能直接用于容量承诺。
• Compose 文件适合验证和基础部署示例，但没有提供完整的生产高可用、备份、密钥轮换和灾备方案。
• 代理高级配置的完整字段未包含在给定资料中，无法据此确认所有路由和护栏参数。
• GitHub 许可证元信息与仓库 LICENSE 文件的呈现不同，授权判断应以实际许可证文件为准。

官方仓库未提供本文所需的完整性能复现实验、SLA、CVE 清单、数据保留承诺和所有接口签名，建议以最新 README 和官方文档为准。

适合谁

以下信号表明 LiteLLM 的网关抽象可能与团队需求匹配；这些是基于项目已提供能力的选型条件，不是仓库声明的客户承诺。

1. 应用同时接入 OpenAI、Anthropic、Bedrock、Azure 或其他提供商，需要统一调用格式。
2. 团队需要集中管理虚拟密钥、消费追踪、日志、护栏和模型路由。
3. 组织能够维护 Python 服务、Docker Compose、PostgreSQL 和相关凭据管理流程。
4. 业务希望将模型提供商切换成本放在网关层，而不是分散在多个应用代码库中。

不适合谁

以下信号说明引入网关会增加不必要的系统边界，或需要先补齐运维与合规能力。

1. 应用只调用单一模型提供商，并且不需要集中认证、成本统计或路由治理。
2. 团队无法维护数据库、容器运行环境、密钥管理和网关日志审计流程。
3. 组织要求某项认证、数据驻留或 SLA，但无法在供应商合同和部署设计中单独落实。
4. 系统需要已在资料中明确但当前仓库未提供的特殊协议、模型参数或性能保证。
5. 部署方准备直接使用 Compose 中的示例密码和公开端口，而没有隔离测试环境与生产环境。

常见问题与排查（FAQ / Troubleshooting）

排查顺序应从配置文件、容器状态、健康检查和数据库连接开始。以下问题只覆盖给定仓库资料能够支持的判断。

为什么容器没有通过健康检查

Compose 的健康检查访问 http://localhost:4000/health/liveliness。先执行 docker compose ps 和 docker compose logs litellm，再核对服务是否监听了容器内的 4000 端口、数据库是否启动以及环境变量是否加载。

为什么修改了配置却没有生效

Compose 文件默认没有挂载 config.yaml，相关内容以注释形式存在。若使用配置文件启动，需要取消对应的 volumes 和 command 配置，并重新创建服务；官方仓库未提供更完整的配置热加载说明。

数据库连接失败如何处理

核对 DATABASE_URL 中的主机名是否为 Compose 服务名 db，以及数据库名、用户和密码是否与 db 服务一致。若是首次启动，还应查看 PostgreSQL 健康检查和 postgres_data 卷状态。

如何判断 Python 版本是否满足要求

pyproject.toml 声明 Python 范围为 >=3.10, <3.15。Dockerfile 的构建阶段使用 Python 3.13；本地环境应使用该范围内的版本，具体依赖安装方式以项目当前文档为准。

项目地址与资源

以下链接均来自仓库元信息、README 或项目文件，适合继续核对版本、提供商支持、代理配置和授权范围。

• GitHub 仓库：BerriAI/litellm
• LiteLLM 官方文档
• LiteLLM Proxy Server 文档
• 支持的 LLM 提供商文档
• LiteLLM 基准测试文档
• LiteLLM 官方网站
• AI Gateway 产品页面
• Enterprise 页面
• PyPI LiteLLM 项目页面
• Render 部署入口
• Railway 部署入口
• LiteLLM Discord 社区
• LiteLLM 支持页面