★ FEATURED ARTICLE 1. 为什么要在 K8s 里跑 LiteLLM 网关LiteLLM 是一个把多家大模型 API 统一成 OpenAI 兼容格式的网关你可以把它理解成集群里的「模型路由中枢」上游是各家模型服务下游是业务 Pod中间由它负责鉴权、路由、限流和日志。放到 Kubernetes 里跑好处是副本可扩、配置可版本化、密钥可集中管理团队里谁要用模型只认一个集群内地址就行。真正让人头疼的不是 LiteLLM 本身而是 Key 的散落。业务 A 用一家、业务 B 用另一家每个 Pod 里塞一份密钥轮换一次要改十几个 Deployment。我试过把 endpoint 和 Key 统一收敛到 TaoToken 这一层LiteLLM 只保留一份上游凭据模型名到实际后端的映射写在 ConfigMap 里改配置不用动业务代码。这篇就按这个思路把「Kubernetes 部署 LiteLLM 统一多模型 Key」的完整路径走一遍包含可直接复制的 Deployment、Service、ConfigMap YAML以及用 curl 验证模型列表和一次对话请求的检查动作。适合谁看手里有 K8s 集群、需要给多个团队或服务统一发模型能力的平台同学已经在用 LiteLLM 但 Key 管理混乱、想收敛入口的运维同学以及准备把本地 LiteLLM 迁到集群、想要一份能跑通的清单的人。读完你应该能拿到一个一次部署、稳定路由多模型调用的最小可用形态。需要提前说明的是LiteLLM 的镜像、端口、环境变量在不同版本间偶有差异本文以ghcr.io/berriai/litellm:main-latest和 8000 端口为基准你落地时按自己锁定的 tag 微调即可。下面从集群前置检查开始。2. 部署前的集群检查与 TaoToken 凭据准备先把地基打牢再谈部署。集群侧要确认三件事kubectl 能连上、节点资源够、命名空间隔离好。LiteLLM 本体不重单副本 1 核 1Gi 起步足够但它要维护到上游的连接池副本数建议至少 2 个做滚动更新时的可用性兜底。kubectl version --short kubectl get nodes -o wide kubectl top nodes如果kubectl top报 metrics 不可用说明 metrics-server 没装不影响部署但后面排查资源问题会少一个手段建议顺手补上。接着建独立命名空间别和业务混在一起kubectl create namespace litellm kubectl config set-context --current --namespacelitellm然后是凭据这一层。TaoToken 的定位是统一入口你需要在控制台生成一个 API Key后面 LiteLLM 就用这个 Key 去访问上游。地址方面官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带查询参数配置里填的就是这个纯基址。生成 Key 的入口在控制台的 API Keys 页面对应 deep link 是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到形如sk-开头的字符串后不要写进 YAML 明文用 Secret 存。这里有个细节LiteLLM 读取上游凭据既支持环境变量也支持配置文件里的api_key字段两种方式我都给出来你按团队习惯选。先把 Secret 建好键名统一用upstream_api_key避免和 LiteLLM 自身的 master key 混淆kubectl create secret generic litellm-upstream \ --namespacelitellm \ --from-literalupstream_api_keysk-你的TaoToken密钥再建一个给 LiteLLM 网关自身用的 master key业务侧调用集群内网关时校验用kubectl create secret generic litellm-master \ --namespacelitellm \ --from-literalmaster_keysk-litellm-local-2024两个 Secret 分开是有原因的上游 Key 泄露影响的是你的额度网关 master key 泄露影响的是集群内调用权限轮换节奏和范围都不一样。到这里前置就绪下一节进入可复制的配置。3. 可复制的 ConfigMap 与 Deployment 配置这一节是全文的核心配置写对了后面基本一次过。LiteLLM 的配置分两块一块是config.yaml描述模型列表和上游地址一块是 Deployment 的环境变量告诉它去哪读配置、用哪个 master key。先写 ConfigMap。注意api_base指向 TaoToken 的 API 基址model字段写你要路由的模型名model_name是暴露给业务侧的别名业务只认别名换后端时改这里就行apiVersion: v1 kind: ConfigMap metadata: name: litellm-config namespace: litellm data: config.yaml: | model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_base: https://taotoken.net/api api_key: os.environ/UPSTREAM_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_base: https://taotoken.net/api api_key: os.environ/UPSTREAM_API_KEY general_settings: master_key: os.environ/LITELLM_MASTER_KEY database_url: litellm_settings: drop_params: true request_timeout: 600os.environ/UPSTREAM_API_KEY是 LiteLLM 的语法表示从环境变量取值这样密钥不进 ConfigMap。drop_params: true建议开着不同上游对参数支持不一致多余参数直接丢弃比报错友好。接着是 Deployment。镜像用官方镜像端口 8000把 ConfigMap 挂到/app/config.yaml环境变量从两个 Secret 注入apiVersion: apps/v1 kind: Deployment metadata: name: litellm namespace: litellm labels: app: litellm spec: replicas: 2 selector: matchLabels: app: litellm template: metadata: labels: app: litellm spec: containers: - name: litellm image: ghcr.io/berriai/litellm:main-latest args: - --config - /app/config.yaml - --port - 8000 ports: - containerPort: 8000 env: - name: UPSTREAM_API_KEY valueFrom: secretKeyRef: name: litellm-upstream key: upstream_api_key - name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: litellm-master key: master_key volumeMounts: - name: config mountPath: /app/config.yaml subPath: config.yaml readinessProbe: httpGet: path: /health/readiness port: 8000 initialDelaySeconds: 15 periodSeconds: 10 livenessProbe: httpGet: path: /health/liveness port: 8000 initialDelaySeconds: 30 periodSeconds: 20 resources: requests: cpu: 250m memory: 512Mi limits: cpu: 1 memory: 1Gi volumes: - name: config configMap: name: litellm-configService 用 ClusterIP 就够集群内业务通过litellm-service.litellm.svc.cluster.local:8000访问要对外再叠 IngressapiVersion: v1 kind: Service metadata: name: litellm-service namespace: litellm spec: selector: app: litellm ports: - protocol: TCP port: 8000 targetPort: 8000 type: ClusterIP一次性 applykubectl apply -f litellm-configmap.yaml kubectl apply -f litellm-deployment.yaml kubectl apply -f litellm-service.yaml kubectl get pods -n litellm -w看到两个 Pod 都Running且READY 1/1就说明探针过了。如果卡在CrashLoopBackOff先看日志多半是 config.yaml 缩进或环境变量名对不上下一节验证时会顺带覆盖。4. 用 curl 验证模型列表与一次对话请求部署完不验证等于没部署。验证分两步先确认网关活着并能列出模型再打一次真实对话请求确认上游链路通。第一步端口转发到本地避免依赖 Ingresskubectl port-forward -n litellm svc/litellm-service 8000:8000另开一个终端带上 master key 请求模型列表curl -s http://127.0.0.1:8000/v1/models \ -H Authorization: Bearer sk-litellm-local-2024 | jq .返回里应该能看到gpt-4o-mini和claude-sonnet两个别名。如果返回 401说明 master key 没对上检查 Secret 里的值和请求头是否一致。第二步打一次对话请求验证上游真的通curl -s http://127.0.0.1:8000/v1/chat/completions \ -H Authorization: Bearer sk-litellm-local-2024 \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话说明什么是网关}], max_tokens: 64 } | jq .choices[0].message.content能打印出一句话回答就说明 LiteLLM 用 TaoToken 的 Key 成功路由到了上游。再换claude-sonnet打一次确认多模型路由都通。这一步很关键模型列表能列出不代表上游可达只有真实 completion 返回才算打通。如果你更想先在网页里确认模型可用性可以走模型对话入口 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 用同一个 Key 手动发一条和集群内结果对照能快速区分是网关问题还是上游问题。验证通过后业务侧接入就简单了把 OpenAI SDK 的base_url指向http://litellm-service.litellm.svc.cluster.local:8000/v1api_key填 master keymodel填别名。业务代码零改动换模型只改 ConfigMap。5. 常见报错排查401、local proxy failed 与 reading choices部署阶段最容易撞的几类报错我按真实日志对照给你排一遍。401 Unauthorized。两种来源要分清一种是请求网关时 master key 不对日志里是Authentication Error检查请求头Authorization: Bearer和 Secret 是否一致另一种是网关访问上游时被拒日志里会出现upstream字样说明 TaoToken 的 Key 无效或额度问题去控制台核对 Key 状态。区分方法看报错里有没有litellm前缀。local proxy failed / connection refused。这通常是 Pod 没起来或端口不对。先kubectl get pods -n litellm看状态再kubectl logs -n litellm pod-name看启动日志。如果日志停在读取 config多半是 ConfigMap 挂载路径不对确认mountPath是/app/config.yaml且subPath匹配。如果报Address already in use检查 args 里的端口和 containerPort 是否一致。reading choices 相关报错。这类多半是上游返回结构不符合预期常见于模型名写错或上游不支持该参数。日志里会带KeyError: choices或reading choices。处理办法先在模型对话页面用同一模型名手动发一次确认上游本身可用再检查 ConfigMap 里model字段的 provider 前缀是否正确比如openai/和anthropic/不能混。drop_params: true能挡掉一部分参数不兼容的问题。OAuth / token 过期类报错。如果你用的是需要 OAuth 的 providerLiteLLM 侧要额外配置凭据刷新纯 API Key 模式不会遇到。看到OAuth字样先确认是不是误配了需要交互登录的 provider统一走 TaoToken 的 Key 模式可以规避这类问题。Pod 一直 Pending。资源不够或节点亲和性问题kubectl describe pod -n litellm pod-name看 Events多半是 requests 超过节点可分配量把 requests 调小即可。排查时记住一个顺序先看 Pod 状态再看容器日志最后看上游连通性。三步能定位九成问题。日志命令kubectl logs -n litellm -l applitellm --tail100 kubectl describe pod -n litellm -l applitellm6. 长期编码与 Agent 场景的接入建议集群里跑通 LiteLLM 只是第一步真正省心的是把它接到日常编码和 Agent 工作流里。如果你团队在用 Claude Code 这类工具或者要跑长任务的 Agent建议把网关地址和 Key 固化到工具配置里而不是每次手动填。长期编码场景更适合用 Coding Plan 这类按周期计费的方式入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 配合集群内 LiteLLM 做统一出口额度管理和路由就都在你手里了。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言 SDK 的 base_url 填法照着改就行。几个落地经验ConfigMap 改动后记得kubectl rollout restart deployment/litellm -n litellmLiteLLM 不会自动热加载副本数别只开 1 个滚动更新时会有短暂不可用给网关加个 NetworkPolicy只允许业务命名空间访问 8000 端口减少暴露面。密钥轮换时先更新 Secret再重启 Deployment业务侧无感。到这里一个能稳定路由多模型调用的 LiteLLM 网关就在集群里跑起来了。后续要加模型只改 ConfigMap 里的model_list业务代码一行不用动。
阅读完成 · 觉得有帮助？
