LiteLLM 安装部署实战：用 TaoToken 统一 Key 打通 Docker 与 Kubernetes 多模型调用

1. 为什么要在 Docker 与 K8s 里折腾 LiteLLM如果你手里同时握着 OpenAI、Claude、Gemini 甚至本地 Ollama 的 Key每次写代码都要判断「这个模型该用哪个 SDK、哪个 base_url、哪个鉴权头」那 LiteLLM 就是来救场的。它本质上是一个 OpenAI 兼容的网关你对外只暴露一个地址、一个 Key内部帮你把请求路由到不同厂商。对团队来说这意味着换模型不用改业务代码加模型不用重新发版。但真正落地时问题往往不在「LiteLLM 是什么」而在「怎么把它稳定地跑起来」。本地pip install五分钟能跑通可一旦进了 Docker 或 Kubernetes就会遇到配置文件挂载路径不对、环境变量没注入、健康检查一直失败、多副本之间缓存不共享这些坑。我见过太多人卡在local proxy failed或者容器起来了但/v1/models返回空列表。这篇就聚焦安装部署这一环把 Docker Compose 和 Kubernetes 两套配置都给全再配合 TaoToken 的统一 Key 通道让你用一份配置管理多模型请求。TaoToken 在这里的角色是统一的上游 API 通道你不需要在 LiteLLM 里为每个厂商单独配 Key而是把 TaoToken 的 Base URL 和 Key 填进去由它来承接多模型调用。这样 LiteLLM 的model_list可以写得更干净密钥管理也集中在一处。适合谁看正在做 AI 应用后端、需要给多个业务线提供统一模型入口的工程师已经在用 LiteLLM SDK 但想升级到 Proxy 模式的开发者以及准备把模型网关搬上 K8s 的运维同学。下面所有配置都可以直接复制改掉 Key 就能跑。2. 前置准备TaoToken 统一 Key 与 LiteLLM 版本选择在动手写 Docker 和 K8s 配置之前先把两件事定下来上游通道用谁、LiteLLM 用哪个版本。先说通道。LiteLLM 的model_list里每个模型都要写api_key和api_base如果你直连各家厂商配置会变成一堆os.environ/OPENAI_API_KEY、os.environ/ANTHROPIC_API_KEY密钥分散、轮换麻烦。用 TaoToken 做统一通道后所有模型都指向同一个api_baseKey 也只用一份。配置里写起来是这样model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-sonnet-4-20250514 api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY注意model字段仍然保留openai/、anthropic/前缀这是告诉 LiteLLM 用哪套请求格式去转换而api_base统一指向 TaoToken。这样 LiteLLM 负责协议适配TaoToken 负责通道分发职责清晰。Key 的获取在 TaoToken 控制台的 API Keys 页面生成后形如sk-开头的一串。建议单独建一个 Key 给 LiteLLM 用方便后续按网关维度统计用量。控制台地址是 https://taotoken.net/console API Keys 页面在 https://taotoken.net/api-keys 。版本方面LiteLLM 1.50 对 Proxy 模式的支持已经比较成熟镜像标签用main-v1.50.2这种带具体版本号的别用latest。生产环境锁版本能避免上游更新带来的兼容性问题。Python 侧要求 3.8 以上Docker 20.10K8s 1.24Helm 3.10 作为包管理可选。还有一个容易忽略的点LITELLM_MASTER_KEY。这是 Proxy 自己的管理密钥用来签发虚拟 Key、访问管理接口和上游的 TaoToken Key 是两回事。前者管「谁能访问我的网关」后者管「我的网关怎么访问上游」。两个都要设且都要用强随机值。3. 可复制配置Docker Compose 与 K8s 部署清单这一节给两套完整配置Docker Compose 适合中小团队单机或小集群K8s 适合需要弹性伸缩的场景。两套共用同一份config.yaml区别只在编排层。3.1 Docker Compose 部署先建目录结构mkdir -p litellm-deploy cd litellm-deploy touch config.yaml docker-compose.yaml .envconfig.yaml内容如下注意api_base统一指向 TaoTokenmodel_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY timeout: 30 - model_name: claude-sonnet litellm_params: model: anthropic/claude-sonnet-4-20250514 api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY timeout: 60 - model_name: gemini-pro litellm_params: model: gemini/gemini-1.5-pro api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY timeout: 30 litellm_settings: drop_params: true num_retries: 3 request_timeout: 30 telemetry: false router_settings: routing_mode: simple-shuffle fallbacks: - gpt-4o: - claude-sonnet - gemini-pro general_settings: master_key: os.environ/LITELLM_MASTER_KEY database_url: os.environ/DATABASE_URL redis_url: os.environ/REDIS_URLdocker-compose.yaml把 Proxy、PostgreSQL、Redis 串起来services: litellm: image: ghcr.io/berriai/litellm:main-v1.50.2 ports: - 4000:4000 volumes: - ./config.yaml:/app/config.yaml command: [--config, /app/config.yaml, --port, 4000, --num_workers, 4] environment: - TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} - LITELLM_MASTER_KEY${LITELLM_MASTER_KEY} - DATABASE_URLpostgresql://litellm:litellmdb:5432/litellm - REDIS_URLredis://redis:6379 - LITELLM_LOGINFO depends_on: - db - redis restart: unless-stopped healthcheck: test: [CMD, curl, -f, http://localhost:4000/health/liveliness] interval: 30s timeout: 10s retries: 3 db: image: postgres:15 environment: POSTGRES_DB: litellm POSTGRES_USER: litellm POSTGRES_PASSWORD: litellm volumes: - pgdata:/var/lib/postgresql/data restart: unless-stopped redis: image: redis:7-alpine restart: unless-stopped volumes: pgdata:.env文件放密钥权限设 600TAOTOKEN_API_KEYsk-你的TaoToken密钥 LITELLM_MASTER_KEYsk-litellm-$(openssl rand -hex 16)启动docker compose up -d docker compose ps docker compose logs -f litellm3.2 Kubernetes 部署K8s 侧把配置拆成 ConfigMap、Secret、Deployment、Service、HPA 五份。ConfigMap 存config.yamlSecret 存密钥Deployment 挂载配置并注入环境变量。apiVersion: v1 kind: ConfigMap metadata: name: litellm-config namespace: litellm data: config.yaml: | model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-sonnet-4-20250514 api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY litellm_settings: drop_params: true num_retries: 3 general_settings: master_key: os.environ/LITELLM_MASTER_KEY database_url: os.environ/DATABASE_URL redis_url: os.environ/REDIS_URL --- apiVersion: v1 kind: Secret metadata: name: litellm-secrets namespace: litellm type: Opaque stringData: TAOTOKEN_API_KEY: sk-你的TaoToken密钥 LITELLM_MASTER_KEY: sk-litellm-强随机值 DATABASE_URL: postgresql://litellm:litellmlitellm-db:5432/litellm REDIS_URL: redis://litellm-redis:6379 --- apiVersion: apps/v1 kind: Deployment metadata: name: litellm-proxy namespace: litellm spec: replicas: 2 selector: matchLabels: app: litellm template: metadata: labels: app: litellm spec: containers: - name: litellm image: ghcr.io/berriai/litellm:main-v1.50.2 args: [--config, /app/config.yaml, --port, 4000, --num_workers, 4] ports: - containerPort: 4000 envFrom: - secretRef: name: litellm-secrets volumeMounts: - name: config mountPath: /app/config.yaml subPath: config.yaml readinessProbe: httpGet: path: /health/readiness port: 4000 initialDelaySeconds: 10 periodSeconds: 10 livenessProbe: httpGet: path: /health/liveliness port: 4000 initialDelaySeconds: 30 periodSeconds: 30 resources: requests: cpu: 1000m memory: 2Gi limits: cpu: 2000m memory: 4Gi volumes: - name: config configMap: name: litellm-config --- apiVersion: v1 kind: Service metadata: name: litellm-proxy namespace: litellm spec: type: ClusterIP ports: - port: 4000 targetPort: 4000 selector: app: litellm应用并检查kubectl create namespace litellm kubectl apply -f litellm-config.yaml kubectl apply -f litellm-secrets.yaml kubectl apply -f litellm-deployment.yaml kubectl -n litellm get pods kubectl -n litellm logs -f deployment/litellm-proxy这里有个关键点volumeMounts的subPath: config.yaml必须和 ConfigMap 里的 key 名一致否则容器里/app/config.yaml会变成一个目录启动直接报找不到配置。这个坑我在第一次部署时踩过日志里只显示config file not found排查了半天。4. 验证请求curl 与 Python 双路确认路由正常服务起来后别急着接业务先用两条路径确认模型路由真的通了。4.1 curl 验证先看模型列表确认model_list被正确加载curl -s http://localhost:4000/v1/models \ -H Authorization: Bearer sk-litellm-你的master-key | python3 -m json.tool返回里应该能看到gpt-4o、claude-sonnet、gemini-pro三个 id。如果列表为空说明config.yaml没挂载成功或者 YAML 格式有问题。再发一次真实请求curl -X POST http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-litellm-你的master-key \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 用一句话说明 LiteLLM 的作用}] }正常返回里choices[0].message.content会有模型输出。如果返回 401检查Authorization头里的 Key 是不是LITELLM_MASTER_KEY如果返回 500 且日志里有api_base相关错误检查 TaoToken 的 Base URL 有没有写错。4.2 Python 验证Python 侧直接用 openai SDK 指向 LiteLLM 网关即可不需要装 LiteLLM SDKfrom openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-litellm-你的master-key, ) resp client.chat.completions.create( modelclaude-sonnet, messages[{role: user, content: 你好确认一下路由}], ) print(resp.choices[0].message.content)这段代码的关键是base_url指向 LiteLLM 而不是 TaoTokenapi_key用 master key。LiteLLM 收到请求后根据model字段匹配model_name再用对应的api_base和api_key转发到 TaoToken。你可以在 LiteLLM 日志里看到类似POST /v1/chat/completions和上游转发的记录确认路由链路完整。如果想验证 fallback 是否生效可以把gpt-4o的api_key临时改成一个错误值再发请求观察是否自动切到claude-sonnet。日志里会出现Fallback to claude-sonnet的字样。5. 常见报错排查401、local proxy failed 与 choices 为空部署阶段最容易撞上的几类错误这里按现象、原因、动作列清楚。401 Unauthorized。两种可能一是请求头里的 Key 不是LITELLM_MASTER_KEY二是config.yaml里general_settings.master_key引用的环境变量没注入。排查时先docker compose exec litellm env | grep LITELLM看变量在不在再确认请求头格式是Bearer sk-xxx。K8s 里如果 Secret 的 key 名和envFrom对不上变量也不会注入用kubectl -n litellm exec deploy/litellm-proxy -- env确认。local proxy failed。这个报错通常出现在 LiteLLM 尝试连接上游时日志里会带local proxy failed或connection refused。原因多半是api_base写成了localhost或内网地址而容器里访问不到。用 TaoToken 的话api_base固定是https://taotoken.net/api不会出现这个问题如果你直连厂商要确认容器网络能出公网。另一个可能是 DNS 解析失败在容器里curl -v https://taotoken.net/api测一下。reading choices 报错或 choices 为空。这通常是上游返回了非预期结构LiteLLM 解析失败。先看 LiteLLM 日志里上游的原始响应如果上游返回的是错误 JSON比如额度不足、模型名不对LiteLLM 会把它包成异常。检查model字段的写法openai/gpt-4o里的gpt-4o必须是 TaoToken 支持的模型标识写错了上游会返回 404。另外drop_params: true能避免因为传了上游不支持的参数导致报错建议保持开启。OAuth 或鉴权相关报错。如果你用的是需要 OAuth 的通道LiteLLM 侧要配litellm_params里的extra_headers或自定义鉴权。用 TaoToken 的 API Key 模式不涉及 OAuth直接api_key即可。如果日志里出现OAuth字样先确认是不是误配了某个需要 OAuth 的 provider。健康检查一直失败。Docker 里healthcheck用的curl在镜像里可能不存在换成wget或者用 Python 的urllib。K8s 里readinessProbe的initialDelaySeconds太短也会导致 Pod 反复重启LiteLLM 启动加载配置需要几秒给到 10 秒以上比较稳。排查时统一看日志Docker 用docker compose logs -f litellmK8s 用kubectl -n litellm logs -f deploy/litellm-proxy。日志里会打印每个请求的模型匹配、上游转发、耗时定位问题比猜快得多。6. 把统一 Key 通道接进你的编码工作流部署验证通过后LiteLLM 网关就成了你所有 AI 调用的统一入口。接下来可以把它接到日常编码工具里比如 Claude Code、Cline 这类支持自定义 Base URL 的客户端。配置三件套是固定的Base URL 填http://你的网关地址:4000/v1Key 填LITELLM_MASTER_KEYModel ID 填config.yaml里定义的model_name比如claude-sonnet。如果你想让网关长期稳定运行、并且需要按团队维度管理用量和预算可以了解下 TaoToken 的 Coding Plan它把通道和额度管理做在了一起适合需要长期跑 Agent 或批量编码的场景https://taotoken.net/coding-plan 。模型对话调试入口在 https://taotoken.net/chat 接入文档在 https://taotoken.net/doc API Keys 管理在 https://taotoken.net/api-keys 。最后留一个实操建议把config.yaml纳入 Git 管理但.env和 K8s Secret 不要提交。每次改完配置先docker compose config或kubectl apply --dry-runclient校验语法再滚动更新。LiteLLM 的配置热加载能力有限改完model_list建议重启 Pod 或容器别指望它自动生效。