使用 Terraform 管理 LiteLLM Team：`litellm_team` 资源完全指南

使用 Terraform 管理 LiteLLM Teamlitellm_team资源完全指南【免费下载链接】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 的团队Team机制用于将用户分组并在团队维度统一管理模型访问权限、预算与限流策略。本文以仓库内 Terraform Provider 的官方资源文档 terraform/provider/docs/resources/team.md 为主体结合 resource_team.go、resource_team_test.go 等源码完整讲解litellm_team资源的每个参数、三种典型配置写法、CRUD 底层调用链与导入方式。读完你可以在 IaC基础设施即代码流程中用可版本化、可评审的 HCL 声明团队及其配额替代在 UI 或 curl 中手工维护配置。一、为什么需要litellm_team团队在 LiteLLM 中的定位LiteLLM Proxy 是统一 LLM API 网关。当多个业务团队工程、算法、财务共享同一个 Proxy 实例时需要一种“按团队隔离 按团队计量”的边界谁可以用哪些模型、总共能花多少钱、每分钟能打多少请求、超预算时通知谁。Team 正是承担这一职责的一等公民对象其官方定义为把用户分组并统一管理这群用户对模型的访问权限与用量上限。litellm_team资源把这些原本只能通过POST /team/new、GET /team/info、POST /team/update、POST /team/delete等 HTTP 管理端点执行的运维动作封装成 Terraform 生命周期内的 Create/Read/Update/Delete 四个回调见 resource_team.go从而让团队配置进入代码库随 CI 进行变更评审与审计。二、准备 Provider连接 Proxy 的基础配置使用litellm_team前需要先声明并配置 LiteLLM Terraform Provider。Provider 级参数有两个详见 index.md参数必填说明等价环境变量api_base是LiteLLM Proxy 实例的基础 URLLITELLM_API_BASEapi_key是调用管理端口的 API KeyLITELLM_API_KEY推荐用环境变量方式避免把密钥写进.tf文件export LITELLM_API_BASEhttps://your-litellm-proxy.com export LITELLM_API_KEYyour-api-keyterraform { required_providers { litellm { source registry.terraform.io/BerriAI/litellm } } } # Provider 自动读取 LITELLM_API_BASE / LITELLM_API_KEY provider litellm {}请求发出时API Key 通过x-api-key请求头发送见 client.go且日志输出前会对api_key、secret、token等字段做自动脱敏client.go避免调试日志泄露凭据。三、三种典型用法示例原文档提供了三个由浅入深的使用场景以下完整保留并附注要点。3.1 基础团队配置最简形态只声明团队别名与可访问模型并给一个总预算resource litellm_team engineering { team_alias engineering-team models [gpt-4-proxy, claude-2] max_budget 1000.0 }这里的models是 Proxy 上的模型名proxy model name即litellm_model资源中登记的对外名称如gpt-4-proxy不一定是上游供应商模型原名。若模型未先创建团队将被授予一个尚不存在的模型引用因此生产环境建议先建模型见 3.3。3.2 完整配置预算、限流、告警、标签、权限与元数据resource litellm_team advanced_team { team_alias ai-research-team organization_id org_123456 models [gpt-4-proxy, claude-2, gpt-3.5-turbo] # 预算与限流 max_budget 1000.0 soft_budget 800.0 budget_duration 1mo tpm_limit 500000 rpm_limit 5000 blocked false # 花费越过 soft_budget 时哪些邮箱会被告警 soft_budget_alerting_emails [finopsexample.com] # 用于花费追踪与基于标签路由的标签 tags [team:ai-research, environment:production] # 团队成员的权限 team_member_permissions [ create_key, delete_key, view_spend, edit_team ] # 组织的元数据 metadata { department Engineering project AI Research cost_center RD-001 } }一个值得注意的架构细节tags与soft_budget_alerting_emails在 Proxy 侧实际存储于metadata之内但 Provider 将它们剥离为独立的一级属性单独管理而不是塞进metadatamap。从源码看发送请求时buildTeamMetadata()会把soft_budget_alerting_emails合并回 metadataresource_team.go回读状态时splitTeamMetadata()则会把 metadata 里的tags、soft_budget_alerting_emails拆回对应属性并剔除服务端管理的team_member_budget_idresource_team.go。因此不要在metadata里重复书写这两项否则会产生漂移。这条约束在单测 resource_team_test.go 中有明确断言服务端返回的team_member_budget_id必须被丢弃、不进 state。3.3 带模型依赖的团队配置团队通常依赖先创建好的模型资源。使用 Terraform 资源引用语法可以自动建立依赖图——terraform apply会先创建模型、再创建团队# 先创建模型 resource litellm_model gpt4 { model_name gpt-4-proxy custom_llm_provider openai base_model gpt-4 model_api_key var.openai_api_key } resource litellm_model claude { model_name claude-proxy custom_llm_provider anthropic base_model claude-3-sonnet-20240229 model_api_key var.anthropic_api_key } # 再创建可访问这些模型的团队 resource litellm_team model_dependent_team { team_alias model-users models [ litellm_model.gpt4.model_name, litellm_model.claude.model_name ] max_budget 500.0 budget_duration 1mo team_member_permissions [ view_spend ] }model_api_key属于敏感值Provider 客户端在日志中会将其脱敏为[REDACTED]见 client.go。更完整的模型参数用法可参考官方示例文件 examples/model_additional_params.tf。四、Argument Reference全参数权威速查以下是文档列出的全部受支持参数。按功能归类说明同时结合源码类型定义types.go、resource_team.go补充底层约束。4.1 身份与归属参数必填类型说明team_alias是string团队的人类可读标识非唯一 IDorganization_id否string团队所属组织的 IDteam_alias在 Go Schema 中被标记为Requiredresource_team.go创建时同时作为team_id与team_alias一起发送buildTeamData中team_id恒为必填。4.2 模型访问与内容管控参数类型说明modelslist(string)团队可访问的 Proxy 模型名列表model_aliasesmap(string)模型别名映射别名 → 模型名让团队用稳定别名调用模型guardrailslist(string)应用于该团队每一次请求的护栏guardrail列表promptslist(string)允许该团队使用的 Prompt ID 列表allowed_passthrough_routeslist(string)允许该团队调用的 pass-through 路由列表tagslist(string)团队标签用于花费追踪与基于标签的路由原文档明确指出tags的两大用途是花费追踪与标签路由标签让 Proxy 能把团队请求的花费按自定义维度聚合统计也能按标签把请求路由到特定模型组。在本文档语境下请把tags视为“团队维度计量与路由的钥匙”。4.3 预算、限流与告警参数类型说明max_budgetfloat团队总预算上限美元soft_budgetfloat软预算阈值花费越过该值即触发软预算告警但不阻断请求soft_budget_alerting_emailslist(string)花费越过soft_budget时收到通知的邮箱列表budget_durationstring预算周期合法值daily、weekly、monthly、yearlytpm_limitint团队级每分钟 Token 上限rpm_limitint团队级每分钟请求上限rpm_limit_typestringRPM 限流的执行模式guaranteed_throughput或best_effort_throughput修改会强制重建团队tpm_limit_typestringTPM 限流的执行模式guaranteed_throughput或best_effort_throughput修改会强制重建团队model_rpm_limitmap(string→int)按模型设置每分钟请求上限model_tpm_limitmap(string→int)按模型设置每分钟 Token 上限两个值得展开的源码细节soft_budget的清除语义。/team/update是整体替换式语义因此当配置里删除soft_budget时Provider 会显式发送soft_budget: null而不是直接漏掉字段resource_team.go。对应单测 resource_team_test.go 断言了删除标签与软预算后 payload 里必须出现空列表/显式 null。rpm_limit_type/tpm_limit_type仅限创建时设置。这两个字段在 Schema 中被声明为ForceNew: trueresource_team.go意味着一旦变更Terraform 会销毁旧团队并新建。原因是它们只被/team/new接受、不被/team/update接受Create 回调里被显式塞入 payloadresource_team.go而 Update 走的是公共的buildTeamData不会携带这两个 key。TestTeamLimitTypesSentOnCreateOnlyresource_team_test.go双向验证了“创建必须发送、更新必须不发送”。4.4 团队成员级限制团队级与成员级限制分离是 LiteLLM Team 设计的一个关键点——下面这些参数把额度下发到每个团队成员个体参数类型说明team_member_permissionslist(string)团队成员在团队上下文内可执行动作的权限列表team_member_budgetfloat应用到每个团队成员个体的预算美元team_member_budget_durationstring成员级预算的重置周期如30d、1moteam_member_rpm_limitint应用到每个成员个体的每分钟请求上限team_member_tpm_limitint应用到每个成员个体的每分钟 Token 上限team_member_key_durationstring团队成员创建的 Key 的存活期如1d、1w4.5 杂项控制参数类型说明blockedbool是否封禁该团队发起请求默认falsemetadatamap(string→string)团队的字符串键值元数据。注意tags与soft_budget_alerting_emails虽然也存于 metadata但必须通过各自的独立属性管理不要写进这个 map五、Attribute Reference导出属性除上述参数外资源只导出如下只读属性id- 团队的唯一标识符。需要注意id是创建时生成的内部 UUID不同于team_alias。从源码看创建时客户端直接生成了teamID : uuid.New().String()并作为team_id随请求发送resource_team.go随后作为资源 ID 写入 state。因此别名可以重复变更alias 可更新而id在整个生命周期内稳定不变删除重建会产生新 ID。六、Import把存量团队纳入 Terraform 管理如果团队是通过 UI 或 API 手工创建的可用terraform import将其纳入 state实现 GitOps 接管terraform import litellm_team.engineering team-id导入使用team_id即资源id而非team_alias。Importer 采用ImportStatePassthroughContext导入成功后 ResourceRead 会调用GET /team/info?team_idid拉取服务端真实状态回填resource_team.go。七、团队成员另属资源litellm_team_member原文档特别强调团队成员不由litellm_team管理而是通过独立的litellm_team_member资源管理以获得更细粒度的成员与权限控制。对应实现见 resource_team.go 同级目录的resource_team_member.go官方文档为 team_member.md。典型用法成员挂在已创建团队的id下resource litellm_team_member alice { team_id litellm_team.engineering.id user_id user-alice-001 user_email aliceexample.com role user # 合法值org_admin / internal_user / internal_user_viewer / admin / user max_budget_in_team 50.0 }成员管理走独立的/team/member_add、/team/member_update、/team/member_delete端点其资源id是team_id:user_id的复合主键见 resource_team_member.go。八、CRUD 生命周期与权限同步的源码实现把文档与源码对照litellm_team的真实行为如下阶段Provider 回调底层 HTTP 调用关键行为CreateresourceLiteLLMTeamCreatePOST /team/new客户端生成 UUID 作为team_idrpm_limit_type/tpm_limit_type仅在此发送ReadresourceLiteLLMTeamReadGET /team/info?team_id解析team_info信封结构回填 state404 时清空 state 标记资源已删除UpdateresourceLiteLLMTeamUpdatePOST /team/update 必要时POST /team/permissions_update常规字段走整体更新team_member_permissions变更时额外显式调用权限更新端点DeleteresourceLiteLLMTeamDeletePOST /team/delete以team_ids: [id]数组形式删除权限的读写值得单独说明虽然团队信息本身来自/team/info但当前生效的成员权限以/team/permissions_list返回为准——Read 阶段会单独请求权限列表端点并覆盖 stateresource_team.goUpdate 阶段若检测到team_member_permissions有变更会调用/team/permissions_update提交新权限集resource_team.go。这样设计是因为/team/update并不接受权限字段二者需要分端点写入。以上生命周期逻辑均有对应单测覆盖TestTeamCreateSendsSoftBudgetTagsAndAlertEmails、TestTeamReadMapsTeamInfoEnvelope、TestTeamUpdateClearsRemovedTagsAndSoftBudget、TestBuildTeamDataIncludesNewFields、TestTeamReadMapsNewFields与TestTeamLimitTypesSentOnCreateOnly全部集中在 resource_team_test.go可作为理解各字段往返语义的权威参考。九、实战要点小结先建模型再建团队用litellm_model.xxx.model_name引用建立依赖保证models里的引用真实存在模型级 provider 的 key 属于敏感值Provider 日志会自动脱敏。tags与soft_budget_alerting_emails不要写进metadata它们由独立属性管理写重会引发计划漂移。rpm_limit_type/tpm_limit_type只在创建时生效Plan 中若变更会显示“替换replace”务必在新建团队前一次性确定。删除soft_budget或tags能真正清空Provider 会发送显式 null / 空列表不会出现“删不掉”的残留配置。成员与团队解耦团队资源只管“这个团队允许什么”成员是谁请交给litellm_team_member资源二者通过团队id关联。导入用team_idterraform import litellm_team.label team-id别名无法用于导入。结合以上要点与 team.md 的完整参数表你已具备把 LiteLLM 团队治理整体迁入 Terraform 的全套知识若需管理成员、模型、Key、预算等相邻对象可继续查阅 index.md 所列的全部资源清单。【免费下载链接】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），仅供参考