LiteLLM 深度实战指南以 OpenAI 统一格式接入 100 LLM 的 AI 网关与 Python SDK【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellmLiteLLM 是一个开源 AI 网关AI Gateway核心主张是“用一个 OpenAI 兼容的接口调用 100 LLM 提供商”。它可以作为 Python SDK 直接嵌入应用代码也可以部署为独立的代理服务器Proxy Server / AI Gateway为整个团队提供密钥管理、花费追踪、负载均衡、护栏guardrails与管理员仪表盘等生产能力。本文以本仓库的 [README.md] 为主体展开结合 [Makefile]、[docker-compose.yml]、[litellm/proxy/proxy_config.yaml]、[litellm/a2a_protocol/client.py]、[litellm-rust/README.md] 等仓库证据完整覆盖从本地快速上手、Docker 部署、Terraform 云上部署到贡献代码质量门禁的完整链路。1. 两种使用形态Python SDK 与 AI GatewayREADME 将 LiteLLM 的价值概括为四点统一 API一套接口对接 100 LLM无需切换各家的 SDK、OpenAI 兼容的“即插即用”换提供商而无需重写代码、生产级网关能力虚拟密钥、花费追踪、护栏、负载均衡、管理后台开箱即用以及官方宣称的 1k RPS 下 8ms P95 延迟的基准成绩。针对“SDK 还是 Gateway”的选择README 给出了清晰的对照表维度LiteLLM AI GatewayProxyLiteLLM Python SDK用例作为中心化 LLM 网关统一访问多家模型在 Python 代码中直接集成典型用户Gen AI 赋能 / ML 平台团队构建 LLM 项目的开发者关键能力集中式鉴权与授权、多租户成本与花费管理、按项目定制日志/护栏/缓存、虚拟密钥、管理仪表盘代码内直接集成Router 提供跨部署的重试/回退、应用层负载均衡与成本追踪、OpenAI 兼容的异常体系、可观测回调Lunary、MLflow、Langfuse 等一句话理解个人项目选 SDK组织级流量治理选 Gateway。两者共享同一套底层实现Gateway 本质上就是带管理面的 SDK 运行时。2. Python SDK 快速上手README 给出的最小可用示例是uv add litellmfrom litellm import completion import os os.environ[OPENAI_API_KEY] your-openai-key os.environ[ANTHROPIC_API_KEY] your-anthropic-key # OpenAI response completion(modelopenai/gpt-4o, messages[{role: user, content: Hello!}]) # Anthropic response completion(modelanthropic/claude-sonnet-4-20250514, messages[{role: user, content: Hello!}])要点model参数采用“提供商前缀/模型名”的约定如openai/gpt-4o、anthropic/claude-sonnet-4-20250514LiteLLM 据此自动路由到对应提供商的认证与请求转换逻辑认证通过各提供商的标准环境变量注入OPENAI_API_KEY、ANTHROPIC_API_KEY等也可以直接在参数中传api_key返回的response是 OpenAI 风格的统一结构与直接用 OpenAI SDK 时的对象形状一致因此下游解析代码可以复用。3. AI GatewayProxy Server快速上手3.1 两行命令启动README 推荐用 uv 安装 CLI 并直接拉起单模型网关uv tool install litellm[proxy] litellm --model gpt-4o随后用标准 OpenAI 客户端指向代理即可api_key在没配密钥策略时可以传任意值import openai client openai.OpenAI(api_keyanything, base_urlhttp://0.0.0.0:4000) response client.chat.completions.create( modelgpt-4o, messages[{role: user, content: Hello!}] )3.2 配置文件驱动的网关仓库根目录自带一份可直接参考的 litellm/proxy/proxy_config.yaml它展示了网关配置的几个核心区块model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: bedrock-claude-sonnet-4 litellm_params: model: bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0 aws_region_name: us-east-1 # MCP Server Configuration mcp_servers: wikipedia: transport: stdio command: uvx args: [mcp-server-fetch] deepwiki: transport: http url: https://mcp.deepwiki.com/mcp # General Settings general_settings: master_key: sk-1234 store_model_in_db: false # LiteLLM Settings litellm_settings: mcp_semantic_tool_filter: enabled: true embedding_model: text-embedding-3-small几个值得注意的细节model_name是代理对外暴露的名字litellm_params里才是真实路由参数。同一model_name可以挂多个部署配合 Router 做负载均衡与回退api_key: os.environ/OPENAI_API_KEY表示从环境变量取密钥避免把明文写进配置general_settings.master_key是网关的主密钥master key配合数据库可签发团队/用户级别的虚拟密钥store_model_in_db控制模型定义是否落到数据库docker-compose.yml 中默认开启该环境变量用于支持通过 UI 添加模型。3.3 Docker Compose 部署仓库根目录的 docker-compose.yml 是一个“代理 Postgres Prometheus”的完整本地栈关键配置包括litellm服务基于仓库 Dockerfile 构建镜像标签为docker.litellm.ai/berriai/litellm:main-stable映射4000:4000端口环境变量DATABASE_URL指向本地postgres:16实例库名litellm、用户llmproxySTORE_MODEL_IN_DB: True并从根目录.env读取env_file健康检查每 30 秒访问一次http://localhost:4000/health/liveliness容器启动后 40 秒内不判定失败需要配置文件启动时把 docker-compose.yml 中注释掉的volumes挂载./config.yaml与command: [--config/app/config.yaml]解开即可prometheus服务挂载 prometheus.yml抓取指标保留 15 天便于本地做监控验证。关于版本选择README 特别提醒生产环境应使用带-stable标签的 Docker 镜像这些镜像在发布前经历了 12 小时压测。4. 提供商与端点支持矩阵LiteLLM 支持/chat/completions、/responses、/embeddings、/images、/audio、/batches、/rerank、/a2a、/messages等端点族。README 内置一张 100 提供商的端点支持矩阵这里摘录具有代表性的部分完整矩阵见 README.md提供商/chat/completions/messages/responses/embeddings其他OpenAI (openai)✅✅✅✅images/audio/moderations/batchesAnthropic (anthropic)✅✅✅batchesAzure (azure)✅✅✅✅images/audio/moderations/batchesAWS Bedrock (bedrock)✅✅✅✅Google Gemini (gemini)✅✅✅Google Vertex AI (vertex_ai)✅✅✅✅imagesDatabricks (databricks)✅✅✅✅Ollama (ollama)✅✅✅✅本地模型vLLM (vllm)✅✅✅自托管OpenRouter (openrouter)✅✅✅Mistral (mistral)✅✅✅✅Cohere (cohere)✅✅✅✅rerankDeepInfra / Together / Fireworks / Groq / Cerebras / Hyperbolic✅✅✅推理云Huggingface (huggingface)✅✅✅✅rerankIBM Watsonx (watsonx)✅✅✅✅本地/自定义custom_openai、llamafile、lm_studio、oobabooga✅✅✅OpenAI 兼容服务器仓库中每个提供商的转换逻辑对应 litellm/llms/ 下的独立子包如anthropic/、bedrock/、gemini/、vertex_ai/、openai/等 100 目录这是“统一 API”承诺的源码级体现每个提供商一个目录各自实现请求转换与响应解析上层completion()通过模型前缀路由到对应实现。若缺少你在用的提供商README 建议走 issue 提 feature request。5. 调用 A2A AgentAgent 网关能力README 把 A2AAgent-to-Agent 协议作为与 LLM 并列的一级功能既支持 Python SDK 直连 Agent也支持把 Agent 挂到 Gateway 后面统一鉴权。5.1 Python SDKA2AClientfrom litellm.a2a_protocol import A2AClient from a2a.types import SendMessageRequest, MessageSendParams from uuid import uuid4 client A2AClient(base_urlhttp://localhost:10001) request SendMessageRequest( idstr(uuid4()), paramsMessageSendParams( message{ role: user, parts: [{kind: text, text: Hello!}], messageId: uuid4().hex, } ) ) response await client.send_message(request)从源码看这个类是对外 API 的薄封装litellm/a2a_protocol/client.py 中A2AClient.__init__接收base_url、timeout默认 60.0 秒与可选的extra_headers底层客户端惰性创建并复用_get_client首次调用时经litellm.a2a_protocol.main.create_a2a_client构建。也就是说 README 示例与实现完全一致且额外支持超时与自定义请求头参数。5.2 AI Gateway把 Agent 注册进代理官方流程分两步把 Agent 添加到 AI Gateway按 Agent 设置protocolVersion1.0或0.3通过 A2A SDK 调用要求a2a-sdk1.1.0把 base_url 指向http://localhost:4000/a2a/agent-name用 LiteLLM 虚拟密钥做 Bearer 鉴权import httpx from a2a.client import A2ACardResolver, ClientConfig, ClientFactory from a2a.types import Message, Part, Role, SendMessageRequest from a2a.utils.constants import TransportProtocol from uuid import uuid4 base_url http://localhost:4000/a2a/my-agent # LiteLLM proxy agent name headers {Authorization: Bearer sk-1234} # LiteLLM Virtual Key async with httpx.AsyncClient(headersheaders, timeout60.0) as http_client: resolver A2ACardResolver(httpx_clienthttp_client, base_urlbase_url) agent_card await resolver.get_agent_card() config ClientConfig( httpx_clienthttp_client, streamingFalse, supported_protocol_bindings[TransportProtocol.JSONRPC, TransportProtocol.HTTP_JSON], ) client ClientFactory(config).create(agent_card) request SendMessageRequest( messageMessage( message_iduuid4().hex, roleRole.ROLE_USER, parts[Part(textHello!)], ) ) async for event in client.send_message(request): populated event.ListFields() if populated and populated[0][0].name in (message, msg): print(.join(getattr(p, text, ) or for p in populated[0][1].parts))README 列出的 A2A 支持方向包括 LangGraph、Vertex AI Agent Engine、Azure AI Foundry、Bedrock AgentCore、Pydantic AI 等框架产出的 Agent。6. MCP 工具网关让任意 LLM 调用 MCP Server这是 README 中与“统一接口”配套的另一大块能力把 MCPModel Context ProtocolServer 注册进网关后任何经 LiteLLM 发起的 LLM 请求都能直接调用 MCP 工具。6.1 Python SDKMCP 桥接from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from litellm import experimental_mcp_client import litellm server_params StdioServerParameters(commandpython, args[mcp_server.py]) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # Load MCP tools in OpenAI format tools await experimental_mcp_client.load_mcp_tools(sessionsession, formatopenai) # Use with any LiteLLM model response await litellm.acompletion( modelgpt-4o, messages[{role: user, content: Whats 3 5?}], toolstools )源码侧litellm/experimental_mcp_client/init.py 对外导出load_mcp_tools与call_openai_tool两个函数分别对应“把 MCP 工具列表转成 OpenAI tools 格式”和“在 SDK 内执行工具调用”两个环节与 README 示例一一对应。6.2 AI Gateway/chat/completions直接声明 MCP 工具Step 1在网关配置里添加 MCP Serverlitellm/proxy/proxy_config.yaml 中就有现成范例wikipedia走 stdio 由uvx mcp-server-fetch拉起deepwiki走 http 远端。Step 2在聊天请求的tools里声明type: mcp的工具条目curl -X POST http://0.0.0.0:4000/v1/chat/completions \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: Summarize the latest open PR}], tools: [{ type: mcp, server_url: litellm_proxy/mcp/github, server_label: github_mcp, require_approval: never }] }其中server_url指向网关内的 MCP Server 条目require_approval控制工具执行是否需要人工审批此处为never。此外网关本身也暴露标准 MCP 端点可以被 Cursor 等 IDE 作为 MCP Server 消费{ mcpServers: { LiteLLM: { url: http://localhost:4000/mcp/, headers: { x-litellm-api-key: Bearer sk-1234 } } } }结合 litellm/proxy/proxy_config.yaml 中的litellm_settings.mcp_semantic_tool_filter启用语义工具过滤并指定 embedding 模型text-embedding-3-small可以推断网关侧对“工具数量多”的场景提供了按语义检索裁剪工具列表的优化路径。7. Terraform 生产部署AWS / GCPREADME 提供了两套“组件化拆分”的 Terraform 生产栈网关、后端、UI 作为独立服务部署配套托管 Postgreswriter reader、Redis、带版本的对象存储云密钥管理器中自动生成LITELLM_MASTER_KEY并在代理启动前执行一次性prisma migrate deploy迁移任务。模块源码位于本仓库 terraform/litellm/aws/ 与 terraform/litellm/gcp/发布时同步到公共 Terraform Registry无需鉴权。7.1 AWSECS Fargate Aurora ElastiCache ALB在 AWS CloudShell 中可直接执行git clone https://github.com/BerriAI/litellm.git cd litellm/terraform/litellm/aws/examples/default cp terraform.tfvars.example terraform.tfvars # edit region/tenant/env terraform init terraform apply或在自己的根配置中引用模块# main.tf terraform { required_version 1.6.0 required_providers { aws { source hashicorp/aws, version ~ 5.60 } } } provider aws { region us-west-2 } module litellm { source BerriAI/litellm/aws version ~ 1.89 region us-west-2 azs [us-west-2a, us-west-2b] tenant acme env prod # Production: provide an ACM cert. Without one, set allow_plaintext_alb true # (dev/trial only). # acm_certificate_arn arn:aws:acm:us-west-2:111122223333:certificate/... allow_plaintext_alb true } output litellm_url { value module.litellm.alb_dns_name }terraform init terraform apply提供商 API 密钥存放在 AWS Secrets Manager通过gateway_extra_secrets引用 ARN。7.2 GCPCloud Run Cloud SQL Memorystore HTTPS LB由于 Cloud Run 无法直接拉取ghcr.io镜像需先建立一次性的 Artifact Registry 远程仓库指向 GHCRgcloud artifacts repositories create litellm \ --locationus-central1 \ --repository-formatdocker \ --moderemote-repository \ --remote-docker-repohttps://ghcr.io \ --projectmy-gcp-project然后# main.tf terraform { required_version 1.6.0 required_providers { google { source hashicorp/google, version ~ 6.10 } google-beta { source hashicorp/google-beta, version ~ 6.10 } } } provider google { project my-gcp-project; region us-central1 } provider google-beta { project my-gcp-project; region us-central1 } module litellm { source BerriAI/litellm/google version ~ 1.89 project_id my-gcp-project region us-central1 tenant acme env prod # Replace my-gcp-project with your GCP project ID (same value as project_id above). image_registry us-central1-docker.pkg.dev/my-gcp-project/litellm/berriai # Production: provide DNS already pointing at the LB IP for Google-managed certs. # Without one, set allow_plaintext_lb true (dev/trial only). # lb_domains [proxy.example.com] allow_plaintext_lb true } output litellm_url { value module.litellm.load_balancer_url }terraform init terraform applyGCP 侧密钥同样放 Secret Manager通过gateway_extra_secrets引用资源 ID如projects/my-gcp-project/secrets/openai-api-key。README 还强调两套栈暴露与 Helm 图表 相同的proxy_config配置面YAML 以类型化 map 传入意味着 Helm 与 Terraform 的网关行为一致。8. 开发者模式本地起后端与前端README 的 “Run in Developer Mode” 一节给出的最小开发环境搭建依赖服务在仓库根目录创建.env启动基础服务docker-compose up db prometheus对应 docker-compose.yml 中的db与prometheus两个 service。后端执行make bootstrap启动代理后端uv run python litellm/proxy/proxy_cli.py。前端进入ui/litellm-dashboard依赖已由make bootstrap安装启动仪表盘npm run dev。从 Makefile 可以核对bootstrap的真实语义它执行uv sync --inexact --frozen --extra proxy --group proxy-dev --group e2e-dev同步锁定依赖接着运行 scripts/prisma_generate_if_needed.py 按需生成 Prisma 客户端再到ui/litellm-dashboard下执行npm install如果当前是 git worktree 且主工作区已有.env会自动复制过来。install-devuv sync --inexact --frozen与install-proxy-dev则分别面向纯 SDK 开发与代理开发两种依赖组合。9. 验证 Docker 镜像签名README 明确发布到 GHCR 的所有 LiteLLM 镜像都用 cosign 签名且每个发布都使用同一把从指定提交引入的密钥。验证有两种方式方式一推荐用固定提交哈希取公钥——提交哈希在密码学意义上不可变是确认“用的是最初那把签名密钥”的最强方式cosign verify \ --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \ ghcr.io/berriai/litellm:release-tag方式二便捷用发布标签取公钥——标签受仓库保护规则约束并解析到同一密钥可读性更好但依赖标签保护规则cosign verify \ --key https://raw.githubusercontent.com/BerriAI/litellm/release-tag/cosign.pub \ ghcr.io/berriai/litellm:release-tagrelease-tag替换为你部署的版本号例如v1.83.0-stable。仓库根目录保留了公钥文件 cosign.pub 供本地核对。10. 贡献者与代码质量门禁10.1 贡献者快速上手README 要求先安装 uv然后git clone https://github.com/BerriAI/litellm.git cd litellm make install-dev # Install development dependencies make format # Format your code make lint # Run all linting checks make test-unit # Run unit tests make format-check # Check formatting only这些命令在 Makefile 中都有对应目标install-dev即uv sync --inexact --frozenformat/format-check基于 ruff format行宽 120与ruff.toml的line-length保持一致test-unit以pytest tests/test_litellm -x -vv -n 4运行主单元集另有test-unit-llms、test-unit-proxy-core等按 CI 矩阵拆分的细分目标便于只跑受影响的部分。10.2 自动化检查清单README 声明项目遵循 Google Python Style Guide并列出自动检查Black格式化、Rufflint 与代码质量、MyPy类型检查、循环导入检测、导入安全检查——所有检查通过才能合并 PR。对照 Makefile 的lint目标可以看到实际组合与基线分支做 diff 的 ruff format 检查、全树ruff check、严格规则的预算门禁scripts/ruff_strict_gate.py预算文件 ruff-strict-budget.json、类型纪律门禁、测试质量门禁、basedpyright 严格模式按规则数设预算见 basedpyright-code-budget.json、check-circular-imports对应 tests/documentation_tests/test_circular_imports.py以及check-import-safety验证from litellm import *不会因未保护的重依赖导入而失败。另外两点 README 的重要说明文档已迁移到独立仓库文档类 PR 应提交到BerriAI/litellm-docs不再进本仓库本仓库贡献细节见 CONTRIBUTING.md。11. 架构演进Rust 核心与 Python 并存项目定位中提到 “Rust core with Python SDK”。从仓库看litellm-rust/ 是一个独立的 Rust workspacelitellm-rust/README.md 说明它承载的是“分阶段推进中的 Rust 实现”包含五个 crateCrate职责litellm-coreRust 版 SDK按路由划分的入口如messages::messages()、类型、提供商转换、提供商解析、鉴权、HTTP 调用与 routerlitellm-config配置加载边界返回解析后的部署可选委托回 Pythonlitellm-ai-gatewayaxum 服务器与 WebSocket 宿主把 HTTP/WS 翻译为 core 入口litellm-python-interopPyO3 领域无关基础层GIL 处理与 Python/Serde 类型转换litellm-python-bridge暴露给 Python SDK 的 PyO3 cdylibAPI 注册、领域接线、Python 异常映射该文档同时明确了边界Python 目前仍拥有配置、重试、路由策略、日志、回调、花费追踪与客户插件直到每条 Rust 路径达到功能对等并有生产证据为止。目录布局也刻意镜像 Python 的提供商树core/src/providers/provider/route/transformation.rs。结合 tests/rust-python-harness/ 下 167 份 YAML 用例可以推断 Rust 与 Python 实现之间有一套基于配置驱动的对照测试体系来保障行为一致。12. 小结与延伸阅读回到 LiteLLM 的核心命题用一份 OpenAI 格式的请求覆盖 100 提供商的接入差异用一套网关把“调用模型”升级为“治理模型流量”。掌握本文后你应该能够用completion()在数行代码内跨 OpenAI / Anthropic 等提供商切换模型用litellm --model ...或 docker-compose.yml 栈 litellm/proxy/proxy_config.yaml 配置搭起带虚拟密钥与花费追踪的团队网关把 A2A Agent 与 MCP Server 挂进同一网关用虚拟密钥统一鉴权用仓库内 Terraform 模块在 AWS / GCP 上一键拉起组件化生产栈并用 cosign 验证镜像签名。仓库内可继续深入的入口README.md 的完整提供商端点矩阵、proxy_server_config.yaml、helm/litellm/Kubernetes 部署面、litellm/router.pySDK 侧 Router 的负载均衡与回退实现、litellm/caching/多级缓存实现以及 tests/test_litellm/近 2000 个测试文件覆盖各提供商转换逻辑与代理端点行为。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考