用 Terraform 管理 LiteLLMLiteLLM Terraform Provider 架構(gòu)解析與完整實(shí)操指南【免費(fèi)下載鏈接】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]項(xiàng)目地址: https://gitcode.com/GitHub_Trending/li/litellm本文以 LiteLLM 倉庫terraform/provider/README.md的官方文檔為主線結(jié)合倉庫中的 Go 源碼provider.go、端點(diǎn)審計(jì)工具endpointaudit與發(fā)布說明RELEASING.md系統(tǒng)講解如何用 Terraform 以代碼方式管理 LiteLLM Proxy 的模型、團(tuán)隊(duì)、密鑰等全部管理面資源。讀完本文你將能夠正確聲明并配置 provider、編寫litellm_model與litellm_key資源、理解Provider 版本即 LiteLLM 版本的鎖定策略并掌握端點(diǎn)漂移審計(jì)與本地開發(fā)構(gòu)建的完整工作流。Provider 能管理什么資源全景LiteLLM Terraform Provider 允許你通過 Infrastructure as Code 管理 LiteLLM 資源支持通過 LiteLLM REST API 管理模型、團(tuán)隊(duì)、團(tuán)隊(duì)成員、API 密鑰、用戶、組織、預(yù)算、標(biāo)簽、項(xiàng)目、護(hù)欄guardrails、提示詞、Agent、搜索工具、訪問組、回退fallbacks、MCP 服務(wù)器、憑據(jù)與向量存儲(chǔ)并為它們提供只讀數(shù)據(jù)源。README 中列出的核心能力包括管理 LiteLLM 模型配置將模型與特定團(tuán)隊(duì)關(guān)聯(lián)創(chuàng)建與管理團(tuán)隊(duì)配置團(tuán)隊(duì)成員及其權(quán)限設(shè)置用量限制與預(yù)算控制對(duì)特定模型的訪問指定模型模式如 completion、embedding、image generation使用細(xì)粒度控制管理 API 密鑰在 model 資源中支持 reasoning effort 配置從源碼 provider.go 的ResourcesMap可以看到當(dāng)前實(shí)際注冊(cè)的可寫資源共 25 個(gè)比 README 表格覆蓋得更全資源名用途資源名用途litellm_model模型配置litellm_user用戶litellm_team團(tuán)隊(duì)litellm_budget預(yù)算litellm_organization組織litellm_tag標(biāo)簽litellm_organization_member組織成員litellm_project項(xiàng)目litellm_organization_member_add批量添加組織成員litellm_fallback回退鏈litellm_team_member團(tuán)隊(duì)成員litellm_key_block/litellm_team_block封禁密鑰/團(tuán)隊(duì)litellm_team_member_add批量添加團(tuán)隊(duì)成員litellm_access_group/litellm_unified_access_group訪問組litellm_keyAPI 密鑰litellm_guardrail/litellm_prompt護(hù)欄 / 提示詞litellm_mcp_serverMCP 服務(wù)器litellm_agent/litellm_search_toolAgent / 搜索工具litellm_credential憑據(jù)litellm_jwt_key_mappingJWT 聲明到虛擬密鑰的映射DataSourcesMap中注冊(cè)了33 個(gè)只讀數(shù)據(jù)源litellm_credential、litellm_vector_store、litellm_fallback、單數(shù)/復(fù)數(shù)形式的litellm_*_s等可用于在 Terraform 配置中讀取現(xiàn)有對(duì)象的狀態(tài)。README 中重點(diǎn)標(biāo)注了litellm_credential與litellm_vector_store兩個(gè)數(shù)據(jù)源完整文檔位于 docs/data-sources/ 目錄每個(gè)對(duì)象均有單數(shù)/復(fù)數(shù)兩份文檔如 credential.md、vector_store.md。源碼歸屬terraform/provider 是唯一事實(shí)來源README 明確了代碼歸屬規(guī)則倉庫中的terraform/provider/目錄是 Provider 的唯一事實(shí)來源source of truth公開的BerriAI/terraform-provider-litellm倉庫只是一個(gè)薄發(fā)布鏡像供公共 Terraform Registry 攝取不應(yīng)向其提 PR。所有變更都落在本倉庫中CI 在這里構(gòu)建 Provider、運(yùn)行測(cè)試并靜態(tài)審計(jì) Provider 調(diào)用的每一個(gè)端點(diǎn)對(duì)照 Proxy 生成的 OpenAPI 模式tools/endpointaudit/確保 Provider 不會(huì)與 LiteLLM API 靜默漂移。該審計(jì)還會(huì)反向運(yùn)行作為覆蓋率門禁模式中的每一個(gè)管理端點(diǎn)必須被某個(gè)資源或數(shù)據(jù)源覆蓋或出現(xiàn)在tools/endpointaudit/coverage_allowlist.txt的允許列表中過期的允許列表?xiàng)l目會(huì)讓 CI 失敗。這一機(jī)制的實(shí)現(xiàn)可以對(duì)照源碼理解main.go 用 Go 的go/ast解析器靜態(tài)提取源碼中對(duì)fmt.Sprintf構(gòu)造路徑的 HTTP 調(diào)用把%s、%d、%v格式動(dòng)詞歸一化為{param}占位符見 normalizePath從而把源碼中的端點(diǎn)調(diào)用還原為與 OpenAPI 模式可比對(duì)的路徑集合coverage.go 定義了管理端點(diǎn)的判定前綴表access_group、agent、budget、cache、config、credentials、fallback、guardrails、key、model、organization、project、prompts、router、team、user、vector_store等只有落在這些前綴下的路徑才納入覆蓋率檢查coverage_allowlist.txt 中每一條豁免都要寫明理由文件頭注釋強(qiáng)調(diào)該文件相對(duì)于 schema 只能隨時(shí)間收縮。當(dāng)前豁免項(xiàng)分為幾類只讀分析/消費(fèi)報(bào)表如GET /key/spend/report、Admin UI 輔助端點(diǎn)如GET /router/fields、命令式一次性操作如POST /key/regenerate、POST /cache/flushall、已有資源在別處管理的功能的替代方法/路徑如PATCH /model/{model_id}/update以及標(biāo)注 known gap 的真實(shí)覆蓋缺口如 cache settings 資源、pass-through endpoint 資源——這些條目會(huì)在對(duì)應(yīng)資源落地時(shí)刪除。版本策略Provider 版本就是 LiteLLM 版本這是使用本 Provider 時(shí)最重要的一條規(guī)則Provider 版本即 LiteLLM 版本。每一個(gè) LiteLLM 發(fā)布dev、rc 與 stable都會(huì)以與 Proxy 相同的版本號(hào)發(fā)布 Provider并且構(gòu)建自同一個(gè) commit——因此1.99.0的 Provider 就是隨1.99.0的 Proxy 一起發(fā)布、并針對(duì)該 Proxy 的 API 完成端點(diǎn)審計(jì)的版本。最佳實(shí)踐是把 Provider 固定到你 Proxy 實(shí)際運(yùn)行的版本線version ~ 1.99.0預(yù)發(fā)布版本1.99.0-rc.1、1.99.0-dev.1同樣會(huì)發(fā)布但 Terraform 只有在精確固定版本號(hào)時(shí)才會(huì)選中它們。需要注意的歷史版本0.1.0至0.4.0早于這套版本體系屬于獨(dú)立的一條版本線。它們?nèi)粤粼?Registry 中但**~ 0.4約束永遠(yuǎn)不會(huì)命中其他發(fā)布**——要繼續(xù)接收更新必須重新固定到對(duì)應(yīng)的 LiteLLM 版本號(hào)。結(jié)合 RELEASING.md 可以看到發(fā)布流水線的完整鏈路發(fā)布流水線解析出要發(fā)布的 commitdev 取mainHEADrc/stable 取mainHEAD 或運(yùn)維指定的 SHA后把該 commit 的terraform/provider/目錄 rsync 到鏡像倉庫并打上vlitellm version標(biāo)簽例如v1.99.0、v1.99.0-rc.1、v1.99.0-dev.1標(biāo)簽推送觸發(fā)鏡像側(cè)的 goreleaser 工作流完成多平臺(tái)構(gòu)建、GPG 簽名校驗(yàn)和與 GitHub Release公共 Terraform Registry 隨后把該 GitHub Release 攝取為 Provider 版本。由于版本號(hào)就是 LiteLLM 版本號(hào)它不承擔(dān) SemVer 的破壞性變更信號(hào)職責(zé)——破壞性變更改由CHANGELOG.md和 Registry 文檔公告。鏡像倉庫是 push-only 的標(biāo)簽不可變goreleaser 失敗的版本通過重跑該標(biāo)簽的 Release 工作流恢復(fù)而不是重新打標(biāo)簽。聲明與連接 Provider環(huán)境要求來自 README Requirements 一節(jié)Terraform 0.13.xGo 1.16僅開發(fā)需要在terraform塊中聲明 Providerterraform { required_providers { litellm { source BerriAI/litellm version ~ 1.99.0 # the LiteLLM version your proxy runs } } } provider litellm { api_base var.litellm_api_base api_key var.litellm_api_key }從 provider.go 的 Provider 級(jí) Schema 可以看到三個(gè)配置項(xiàng)的精確語義配置項(xiàng)類型必填環(huán)境變量回退說明api_basestring是LITELLM_API_BASELiteLLM API 的基礎(chǔ) URLapi_keystring是LITELLM_API_KEY認(rèn)證用 API 密鑰標(biāo)記為SensitiveTerraform 輸出中隱藏insecure_skip_verifybool否默認(rèn)falseLITELLM_INSECURE_SKIP_VERIFY跳過 TLS 證書校驗(yàn)僅限開發(fā)環(huán)境或自簽名證書場(chǎng)景ConfigureFuncproviderConfigure把這三項(xiàng)組裝成ProviderConfig再交給NewClient構(gòu)造統(tǒng)一的 HTTP 客戶端所有資源與數(shù)據(jù)源共用該客戶端。由于三項(xiàng)都支持EnvDefaultFunc在 CI 中完全可以用環(huán)境變量注入憑據(jù)而不必寫入 HCL。litellm_model 資源實(shí)戰(zhàn)創(chuàng)建模型配置的最小示例resource litellm_model gpt4 { model_name gpt-4-proxy custom_llm_provider openai model_api_key var.openai_api_key model_api_base https://api.openai.com/v1 base_model gpt-4 tier paid mode chat reasoning_effort medium # Optional: low, medium, or high input_cost_per_million_tokens 30.0 output_cost_per_million_tokens 60.0 }結(jié)合 model 資源文檔必填參數(shù)只有三個(gè)model_nameAPI 調(diào)用中識(shí)別模型配置的名稱、custom_llm_provider底層 LLM 提供方如openai、anthropic、azure、bedrock與base_model提供方側(cè)的真實(shí)模型標(biāo)識(shí)如gpt-4、claude-3-sonnet-20240229。其余關(guān)鍵參數(shù)mode模型用途合法值包括completion、embedding、image_generation、chat、moderation、audio_transcription、audio_speech、reranktierfree或paid默認(rèn)freetpm/rpm該模型的每分鐘 token / 請(qǐng)求數(shù)限額reasoning_effortlow/medium/high三檔推理強(qiáng)度thinking_enabled默認(rèn)false與thinking_budget_tokens默認(rèn)1024僅在 thinking 開啟時(shí)生效計(jì)費(fèi)字段input_cost_per_million_tokens與output_cost_per_million_tokensProvider 會(huì)換算成每 token 成本再發(fā)給 API圖像模型還有input_cost_per_pixel/output_cost_per_pixel音頻模型有input_cost_per_second/output_cost_per_secondpricing_base_model與路由解耦的獨(dú)立計(jì)費(fèi) key——當(dāng)路由/部署名與成本表 key 不一致時(shí)例如以azure/gpt-4.1路由、實(shí)際是 Data Zone 檔位的 Azure 部署可設(shè)pricing_base_model us/gpt-4.1-2025-04-14使其按對(duì)應(yīng)檔位計(jì)費(fèi)vertex_project/vertex_location/vertex_credentialscustom_llm_provider vertex時(shí)的 Vertex AI 三件套team_id把模型關(guān)聯(lián)到特定團(tuán)隊(duì)additional_litellm_params任意附加參數(shù)的 map(string)會(huì)被合并進(jìn)發(fā)送給 API 的litellm_params對(duì)象專為未暴露為一級(jí)參數(shù)的提供方專屬或?qū)嶒?yàn)性選項(xiàng)設(shè)計(jì)。倉庫中的 examples/model_additional_params.tf 給出了一份可直接參照的完整示例展示了additional_litellm_params的類型強(qiáng)制轉(zhuǎn)換規(guī)則additional_litellm_params { use_fine_tune true # 轉(zhuǎn)為布爾 true max_context 16384 # 轉(zhuǎn)為整數(shù) 16384 temperature_scale 0.75 # 轉(zhuǎn)為浮點(diǎn) 0.75 experimental_feature enabled # 保持字符串 complex_config {\nested\: {\value\: 42}} # 解析為 JSON 對(duì)象 additional_drop_params [\reasoningEffort\] # 移除最終參數(shù)中的 reasoningEffort }轉(zhuǎn)換規(guī)則是字符串true/false轉(zhuǎn)為布爾數(shù)字字符串先按整數(shù)解析、失敗再按浮點(diǎn)解析16384→ 163840.75→ 0.75以[或{開頭的字符串按 JSON 解析無法轉(zhuǎn)換的保持字符串非字符串值原樣透傳。特殊的additional_drop_params鍵以 JSON 數(shù)組字符串形式指定要在發(fā)送前從最終litellm_params中刪除的參數(shù)且該鍵本身不會(huì)出現(xiàn)在最終 payload 中。文檔同時(shí)提示遠(yuǎn)端 API 可能不回顯所有自定義參數(shù)Provider 會(huì)在配置存在時(shí)于 state 中保留additional_litellm_params。AWS Bedrock 與跨賬號(hào)訪問README Notes 中特別提到Provider 現(xiàn)支持通過 model 資源的aws_session_name與aws_role_name參數(shù)實(shí)現(xiàn) AWS 跨賬號(hào)訪問。完整寫法resource litellm_model bedrock_claude { model_name bedrock-claude-proxy custom_llm_provider bedrock base_model anthropic.claude-3-sonnet-20240229-v1:0 tier paid mode chat # AWS configuration with cross-account access aws_access_key_id var.aws_access_key_id aws_secret_access_key var.aws_secret_access_key aws_region_name us-east-1 aws_session_name litellm-cross-account-session aws_role_name arn:aws:iam::123456789012:role/LiteLLMCrossAccountRole input_cost_per_million_tokens 3.0 output_cost_per_million_tokens 15.0 }Anthropic 與 Azure 的直接接入示例resource litellm_model claude { model_name claude-proxy custom_llm_provider anthropic model_api_key var.anthropic_api_key base_model claude-3-sonnet-20240229 tier paid mode chat input_cost_per_million_tokens 3.0 output_cost_per_million_tokens 15.0 } resource litellm_model azure_gpt4 { model_name azure-gpt4-proxy custom_llm_provider azure model_api_key var.azure_openai_key model_api_base var.azure_openai_endpoint api_version 2023-12-01-preview base_model gpt-4 tier paid mode chat input_cost_per_million_tokens 30.0 output_cost_per_million_tokens 60.0 }導(dǎo)入已有模型模型配置可以用模型 ID 導(dǎo)入注意 ID 在創(chuàng)建時(shí)生成與model_name不同terraform import litellm_model.gpt4 model-idlitellm_key 資源細(xì)粒度 API 密鑰管理README 給出的 API 密鑰創(chuàng)建示例展示了該資源的完整參數(shù)面resource litellm_key example_key { models [gpt-4, claude-3.5-sonnet] max_budget 100.0 user_id user123 team_id team456 max_parallel_requests 5 tpm_limit 1000 rpm_limit 60 budget_duration monthly key_alias prod-key-1 duration 30d metadata { environment production } allowed_cache_controls [no-cache, max-age3600] soft_budget 80.0 aliases { gpt-4 gpt4 } config { default_model gpt-4 } permissions { can_create_keys true } model_max_budget { gpt-4 50.0 } model_rpm_limit { claude-3.5-sonnet 30 } model_tpm_limit { gpt-4 500 } guardrails [content_filter, token_limit] blocked false tags [production, api] }README 對(duì)每個(gè)選項(xiàng)的說明完整保留如下models該密鑰允許訪問的模型列表max_budget密鑰的最大預(yù)算user_id/team_id把密鑰關(guān)聯(lián)到用戶與團(tuán)隊(duì)max_parallel_requests限制并發(fā)請(qǐng)求數(shù)tpm_limit/rpm_limit每分鐘 token 數(shù)與請(qǐng)求數(shù)上限budget_duration預(yù)算周期如monthly、weeklykey_alias密鑰的友好名稱duration密鑰有效期metadata自定義元數(shù)據(jù)allowed_cache_controls允許的緩存控制指令soft_budget軟預(yù)算上限aliases模型別名映射config配置項(xiàng)permissions密鑰權(quán)限model_max_budget、model_rpm_limit、model_tpm_limit按模型設(shè)置限額guardrails為該密鑰應(yīng)用特定護(hù)欄blocked封禁/解封開關(guān)tags用于組織與過濾的標(biāo)簽。對(duì)照 resource_key.go 的 Schema 定義還有幾個(gè)源碼層面值得注意的細(xì)節(jié)key字段被聲明為WriteOnly: true且Sensitive: true——它只寫入、不回顯token_id是Computed字段即創(chuàng)建后從 API 返回的真實(shí)標(biāo)識(shí)spend是Computed字段消費(fèi)金額由遠(yuǎn)端計(jì)算不在配置中維護(hù)除 README 所列外Schema 還包含budget_id關(guān)聯(lián)預(yù)算對(duì)象、enforced_params強(qiáng)制參數(shù)列表、allowed_routes允許的路由列表等更細(xì)的控制項(xiàng)多個(gè)數(shù)值字段max_budget、max_parallel_requests、tpm_limit、rpm_limit、soft_budget同時(shí)標(biāo)記了Optional與Computed即不設(shè)置時(shí)以服務(wù)端默認(rèn)值為準(zhǔn)并回填到 state。本地開發(fā)項(xiàng)目結(jié)構(gòu)與 MakefileREADME 描述的 Provider 源碼組織結(jié)構(gòu)以terraform/provider/為準(zhǔn)源碼目錄litellm/下每個(gè)資源對(duì)應(yīng)resource_*.go與*_test.go文件對(duì)terraform-provider-litellm/ ├── litellm/ │ ├── provider.go │ ├── resource_model.go │ ├── resource_model_crud.go │ ├── resource_team.go │ ├── resource_team_member.go │ ├── resource_key.go │ ├── resource_key_utils.go │ ├── types.go │ └── utils.go ├── main.go ├── go.mod ├── go.sum ├── Makefile └── ...對(duì)照倉庫實(shí)際內(nèi)容litellm/ 目錄中每個(gè)資源都遵循resource_*.goSchemaresource_*_crud.go增刪改查邏輯resource_*_test.go驗(yàn)收測(cè)試的三件套命名例如 resource_model_crud.go、resource_key_utils.go數(shù)據(jù)源同樣是data_source_*.go 測(cè)試文件。開發(fā)流程按 README 說明克隆包含本目錄的倉庫進(jìn)入terraform/provider/目錄執(zhí)行make install構(gòu)建并安裝 Provider。Makefile 提供的一組命令與源碼一一對(duì)應(yīng)命令作用實(shí)際執(zhí)行make build構(gòu)建 Providergo build -o terraform-provider-litellmmake install構(gòu)建并安裝默認(rèn)目標(biāo)安裝到~/.terraform.d/plugins/registry.terraform.io/local/litellm/1.0.0/${OS_ARCH}/make test運(yùn)行測(cè)試套件go test ./...make fmt格式化代碼go fmt ./...make vet靜態(tài)檢查go vet ./...make lintgolangci-lintgolangci-lint runmake clean清理構(gòu)建產(chǎn)物與已安裝 Provider刪除二進(jìn)制與本地插件目錄注意 Makefile 中NAMESPACElocal、OS_ARCHdarwin_amd64make install走的是本地插件開發(fā)目錄local/litellm適合開發(fā)期配合dev_overrides使用正式分發(fā)的 Provider 源是 Registry 中的BerriAI/litellm。提 PR 前建議在本地先跑make test與make build這也是 RELEASING.md 對(duì)貢獻(xiàn)者的要求變更以 PR 形式落入BerriAI/litellm附帶CHANGELOG.md的[Unreleased]條目CI 會(huì)執(zhí)行g(shù)ofmt、go vet、構(gòu)建、測(cè)試與端點(diǎn)漂移審計(jì)隨后由下一次 LiteLLM 發(fā)布夜間的 dev 發(fā)布通常一天內(nèi)自動(dòng)帶上。安全實(shí)踐與注意事項(xiàng)綜合 README Notes、model 資源文檔的安全說明與 Provider Schema使用本 Provider 時(shí)應(yīng)遵循以下準(zhǔn)則敏感值優(yōu)先走環(huán)境變量或密鑰管理系統(tǒng)不要把 API 密鑰、AWS 憑據(jù)硬編碼在 HCL 文件里api_key等字段支持LITELLM_API_KEY等環(huán)境變量回退敏感屬性在 state 中仍是明文model_api_key、aws_secret_access_key等 Sensitive 字段只是從 Terraform 輸出中隱藏state 文件里仍是明文存儲(chǔ)。文檔建議將提供方密鑰存入litellm_credential資源、在 model 資源中通過litellm_credential_name引用并保護(hù) state 后端Provider 版本必須與 Proxy 版本保持同步見上文 Versioning 一節(jié)否則可能出現(xiàn)Provider 調(diào)用的端點(diǎn)在該 Proxy 版本上不存在或行為不同的漂移問題——這正是端點(diǎn)審計(jì)機(jī)制要在 CI 中攔截的所有示例配置已統(tǒng)一整合進(jìn) docs/ 目錄便于組織與維護(hù)完整資源參數(shù)請(qǐng)以 docs/resources/ 下對(duì)應(yīng)文檔為準(zhǔn)本項(xiàng)目遵循 Apache License 2.0 許可見 LICENSE。小結(jié)LiteLLM 的 Terraform Provider 把 Proxy 的整個(gè)管理面——模型注冊(cè)、團(tuán)隊(duì)與組織、密鑰與預(yù)算、護(hù)欄與訪問組、MCP 服務(wù)器與向量存儲(chǔ)——納入了聲明式管理。它的三個(gè)工程特點(diǎn)是選型時(shí)值得記住的其一Provider 版本與 LiteLLM 版本鎖定、同 commit 構(gòu)建并針對(duì)該版本 API 完成審計(jì)固定到 Proxy 版本線是唯一正確的用法其二tools/endpointaudit的靜態(tài)端點(diǎn)審計(jì) 只可收縮的覆蓋率允許列表從 CI 層面保證了 Provider 與 Proxy API 不漂移其三資源面覆蓋 25 個(gè)可寫資源與 33 個(gè)只讀數(shù)據(jù)源配合additional_litellm_params的參數(shù)透傳與類型強(qiáng)制轉(zhuǎn)換能力足以把 LiteLLM 集群配置完整地放進(jìn)版本控制?！久赓M(fèi)下載鏈接】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]項(xiàng)目地址: https://gitcode.com/GitHub_Trending/li/litellm創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考