企业官网建设流程全解析

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/litellm

LiteLLM 是一个开源 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 Gateway

README 将 LiteLLM 的价值概括为四点：统一 API（一套接口对接 100+ LLM，无需切换各家的 SDK）、OpenAI 兼容的“即插即用”（换提供商而无需重写代码）、生产级网关能力（虚拟密钥、花费追踪、护栏、负载均衡、管理后台开箱即用），以及官方宣称的 1k RPS 下 8ms P95 延迟的基准成绩。

针对“SDK 还是 Gateway”的选择，README 给出了清晰的对照表：

一句话理解：个人项目选 SDK，组织级流量治理选 Gateway。两者共享同一套底层实现，Gateway 本质上就是带管理面的 SDK 运行时。

2. Python SDK 快速上手

README 给出的最小可用示例是：

uv add litellm

from litellm import completion import os os.environ["OPENAI_API_KEY"] = "your-openai-key" os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-key" # OpenAI response = completion(model="openai/gpt-4o", messages=[{"role": "user", "content": "Hello!"}]) # Anthropic response = completion(model="anthropic/claude-sonnet-4-20250514", messages=[{"role": "user", "content": "Hello!"}])

要点：

• model参数采用“提供商前缀/模型名”的约定（如openai/gpt-4o、anthropic/claude-sonnet-4-20250514），LiteLLM 据此自动路由到对应提供商的认证与请求转换逻辑；
• 认证通过各提供商的标准环境变量注入（OPENAI_API_KEY、ANTHROPIC_API_KEY等），也可以直接在参数中传api_key；
• 返回的response是 OpenAI 风格的统一结构，与直接用 OpenAI SDK 时的对象形状一致，因此下游解析代码可以复用。

3. AI Gateway（Proxy Server）快速上手

3.1 两行命令启动

README 推荐用 uv 安装 CLI 并直接拉起单模型网关：

uv tool install 'litellm[proxy]' litellm --model gpt-4o

随后用标准 OpenAI 客户端指向代理即可，api_key在没配密钥策略时可以传任意值：

import openai client = openai.OpenAI(api_key="anything", base_url="http://0.0.0.0:4000") response = client.chat.completions.create( model="gpt-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、用户llmproxy），STORE_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）：

仓库中每个提供商的转换逻辑对应 litellm/llms/ 下的独立子包（如anthropic/、bedrock/、gemini/、vertex_ai/、openai/等 100+ 目录），这是“统一 API”承诺的源码级体现：每个提供商一个目录，各自实现请求转换与响应解析，上层completion()通过模型前缀路由到对应实现。若缺少你在用的提供商，README 建议走 issue 提 feature request。

5. 调用 A2A Agent（Agent 网关能力）

README 把 A2A（Agent-to-Agent 协议）作为与 LLM 并列的一级功能：既支持 Python SDK 直连 Agent，也支持把 Agent 挂到 Gateway 后面统一鉴权。

5.1 Python SDK：A2AClient

from litellm.a2a_protocol import A2AClient from a2a.types import SendMessageRequest, MessageSendParams from uuid import uuid4 client = A2AClient(base_url="http://localhost:10001") request = SendMessageRequest( id=str(uuid4()), params=MessageSendParams( 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 注册进代理

官方流程分两步：

1. 把 Agent 添加到 AI Gateway，按 Agent 设置protocolVersion（1.0或0.3）；
2. 通过 A2A SDK 调用（要求a2a-sdk>=1.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(headers=headers, timeout=60.0) as http_client: resolver = A2ACardResolver(httpx_client=http_client, base_url=base_url) agent_card = await resolver.get_agent_card() config = ClientConfig( httpx_client=http_client, streaming=False, supported_protocol_bindings=[TransportProtocol.JSONRPC, TransportProtocol.HTTP_JSON], ) client = ClientFactory(config).create(agent_card) request = SendMessageRequest( message=Message( message_id=uuid4().hex, role=Role.ROLE_USER, parts=[Part(text="Hello!")], ) ) 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 中与“统一接口”配套的另一大块能力：把 MCP（Model Context Protocol）Server 注册进网关后，任何经 LiteLLM 发起的 LLM 请求都能直接调用 MCP 工具。

6.1 Python SDK：MCP 桥接

from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from litellm import experimental_mcp_client import litellm server_params = StdioServerParameters(command="python", 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(session=session, format="openai") # Use with any LiteLLM model response = await litellm.acompletion( model="gpt-4o", messages=[{"role": "user", "content": "What's 3 + 5?"}], tools=tools )

源码侧，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 Server（litellm/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 / GCP）

README 提供了两套“组件化拆分”的 Terraform 生产栈：网关、后端、UI 作为独立服务部署，配套托管 Postgres（writer + reader）、Redis、带版本的对象存储，云密钥管理器中自动生成LITELLM_MASTER_KEY，并在代理启动前执行一次性prisma migrate deploy迁移任务。模块源码位于本仓库 terraform/litellm/aws/ 与 terraform/litellm/gcp/，发布时同步到公共 Terraform Registry（无需鉴权）。

7.1 AWS：ECS 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 GCP：Cloud Run + Cloud SQL + Memorystore + HTTPS LB

由于 Cloud Run 无法直接拉取ghcr.io镜像，需先建立一次性的 Artifact Registry 远程仓库指向 GHCR：

gcloud artifacts repositories create litellm \ --location=us-central1 \ --repository-format=docker \ --mode=remote-repository \ --remote-docker-repo=https://ghcr.io \ --project=my-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 apply

GCP 侧密钥同样放 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” 一节给出的最小开发环境搭建：

依赖服务

1. 在仓库根目录创建.env；
2. 启动基础服务：docker-compose up db prometheus（对应 docker-compose.yml 中的db与prometheus两个 service）。

后端

1. 执行make bootstrap；
2. 启动代理后端：uv run python litellm/proxy/proxy_cli.py。

前端

1. 进入ui/litellm-dashboard（依赖已由make bootstrap安装）；
2. 启动仪表盘：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-dev（uv 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-tag>

<release-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 --frozen；format/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（格式化）、Ruff（lint 与代码质量）、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 workspace，litellm-rust/README.md 说明它承载的是“分阶段推进中的 Rust 实现”，包含五个 crate：

该文档同时明确了边界：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.py（SDK 侧 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