用 Terraform 管理 LiteLLM Prompt：litellm_prompt 资源完整实战指南

用 Terraform 管理 LiteLLM Promptlitellm_prompt 资源完整实战指南【免费下载链接】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/litellmLiteLLM 的 Prompt 管理能力允许开发者把提示词模板集中托管在代理侧通过 Langfuse、dotprompt 等外部/内置集成统一取用而官方 Terraform Provider 中的litellm_prompt资源正是以「基础设施即代码」的方式管理这些 Prompt 的入口。本文以 terraform/provider/docs/resources/prompt.md 为主线结合资源实现源码与代理端接口系统讲解其全部参数、真实请求语义、版本化存储细节与导入/数据源配套用法读完即可在 Terraform 工程中落地可维护、可审计的 Prompt 模板管线。一、litellm_prompt是什么在 LiteLLM 的体系里Prompt 指一组由代理统一托管与版本化的提示词模板它们既可以引用外部 Prompt 管理平台如 Langfuse 中的模板也可以是内置 dotprompt 内联内容。litellm_prompt资源对 LiteLLM 代理暴露的 Prompt CRUD 接口做了完整封装让 Terraform 声明式地完成「创建、读取、更新、删除、导入」全套生命周期管理。从资源实现 resource_prompt.go 可以看到它与代理端的四个 REST 端点一一对应Terraform 生命周期函数HTTP 请求端点CreatePOST/promptsReadGET/prompts/{prompt_id}/infoUpdatePUT/prompts/{prompt_id}DeleteDELETE/prompts/{prompt_id}列表数据源GET/prompts/list代理端对应的 FastAPI 路由实现位于 prompt_endpoints.py它调用PromptRepository读写数据库中的 Prompt 行支持按prompt_id environment维度自动递增版本号——这解释了资源为何必须显式声明prompt_id以及数据源为何能返回version与environments等字段。前置条件配置 Provider 连接使用该资源前请先配置与 LiteLLM 代理的连接。Provider 本身需要api_base代理地址与api_key管理员鉴权密钥二者也可通过环境变量LITELLM_API_BASE、LITELLM_API_KEY注入详细说明见 terraform/provider/docs/index.mdterraform { required_providers { litellm { source registry.terraform.io/BerriAI/litellm } } } provider litellm { api_base https://your-litellm-proxy.com api_key var.litellm_api_key }二、两种典型用法示例2.1 引用 Langfuse 上的远程 Prompt当团队已把 Prompt 模板托管在 Langfuse 时可以只让 LiteLLM 保存「指向 Langfuse 模板的引用」运行时再由代理从 Langfuse 拉取最新模板resource litellm_prompt langfuse_prompt { prompt_id my-langfuse-prompt prompt_integration langfuse api_base https://cloud.langfuse.com api_key var.langfuse_api_key prompt_type db litellm_params jsonencode({ prompt_id prompt-name-in-langfuse }) }这里需要特别注意prompt_id的双层含义顶层prompt_id本例为my-langfuse-prompt是LiteLLM 代理侧的本地标识用于唯一索引该条 Prompt 记录也是后续 import、data source 读取、路由时使用的 IDlitellm_params里嵌套的prompt_id本例为prompt-name-in-langfuse是Langfuse 平台内的模板名代理据此定位远端模板。2.2 使用内置 dotprompt 内联内容如果不想依赖外部平台可以直接把 dotprompt 格式的模板内容内联进 HCL。dotprompt 采用 YAML frontmatter 模板正文的结构frontmatter 中的model等元数据会由代理侧解析并参与请求组装resource litellm_prompt greeting { prompt_id greeting prompt_integration dotprompt prompt_type db dotprompt_content -EOT --- model: gpt-5.2 --- Say hello to {{name}}. EOT }该内联内容的解析逻辑可对照 litellm/integrations/dotprompt/init.py它读取dotprompt_content后先解析 frontmatter 元数据再按 Prompt 管理器期望的格式构造数据从而让「模板即代码」真正落地。三、参数详解Argument Reference完整 Schema 定义见 resource_prompt.go下表为全部参数及行为说明参数必填类型/约束说明prompt_id是stringForceNewPrompt 的唯一标识。修改它会触发资源重建先删后建因为它同时是数据库主键与全部 REST 路径的组成部分prompt_integration是stringPrompt 集成提供方文档给出langfuse、dotprompt两类api_base否stringPrompt 提供方 API 的基础 URL如https://cloud.langfuse.comapi_key否stringSensitive访问 Prompt 提供方如 Langfuse的密钥。永不回读进 state配置值始终作为权威来源provider_specific_query_params否JSON 字符串传给提供方的额外查询参数写入前会被解析为对象HCL 侧以 JSON 字符串书写ignore_prompt_manager_model否bool为true时忽略 Prompt 管理器远端模板里指定的 modelignore_prompt_manager_optional_params否bool为true时忽略来自 Prompt 管理器的可选参数dotprompt_content否stringdotprompt 集成时使用的内联模板内容litellm_params否JSON 字符串Sensitive需要并入请求的额外litellm_params例如集成自身的prompt_id、prompt_directory或prompt_data。可能携带密钥永不回读进 stateprompt_type否stringPrompt 类型config或db通过prompt_info.prompt_type落到代理端数据库3.1 两个Sensitive字段的刻意设计api_key与litellm_params被标记为Sensitive且故意不回读。这在实现中非常明确——resourceLiteLLMPromptRead只回填prompt_integration、api_base、dotprompt_content、两个ignore_*开关、provider_specific_query_params与prompt_type源码注释直白地写着api_key与litellm_params可能携带机密state 中保留配置值作为权威来源见 resource_prompt.go。对应的单元测试TestPromptRead_MapsFieldsAndKeepsAPIKey也断言了「读回后配置的api_key依然权威」避免每次terraform plan产生无意义的 diff。3.2 JSON 字段的 Diff 抑制provider_specific_query_params与litellm_params两个 JSON 字符串字段通过promptSuppressJSONDiff做了 Diff 抑制两边都能成功反序列化且语义深度相等reflect.DeepEqual时即使键序、空白等文本层面不同也不会被判为变更见 resource_prompt.go。这意味着你在 HCL 里手写 JSON 时可以放心排版。3.3 请求体如何组装buildPromptData揭示了 HCL 字段到底如何映射到代理 API 请求体resource_prompt.goprompt_integration始终进入litellm_paramsapi_base、api_key、dotprompt_content非空时才写入provider_specific_query_params先做 JSON 校验并解析成嵌套对象非法 JSON 会在 apply 前直接报错两个ignore_*开关固定以 bool 写入未配置即falselitellm_params中的任意键值被逐项合并进外层litellm_params因此你可以往里塞集成特有的任何参数如 Langfuse 的prompt_id、dotprompt 的prompt_directory最终请求体为{ prompt_id, litellm_params, prompt_info: { prompt_type } }prompt_type未配置时不带prompt_info。四、Attribute Reference 与 Import4.1 导出属性id—— 即 Prompt ID与prompt_id完全相同Create 成功后即d.SetId(promptID)。4.2 状态导入对已在代理中、但尚未纳入 Terraform 管理的存量 Prompt可直接用 ID 导入terraform import litellm_prompt.example my-langfuse-prompt资源在 resource_prompt.go 中通过ImportStatePassthroughContext透传 ID导入后执行terraform plan时按常规流程比对即可。需注意由于api_key与litellm_params永不回读导入后应保持配置与远端一致或明确它们为敏感输入。五、配套 Data Source安全地读回版本与元数据由于资源的Read不回读密钥需要读取 Prompt 的版本、环境归属、时间戳等元数据时建议使用配套数据源litellm_prompt。它按prompt_id可追加environment过滤调用GET /prompts/{prompt_id}/infodata litellm_prompt existing { prompt_id my-langfuse-prompt } output prompt_integration { value data.litellm_prompt.existing.prompt_integration } # 指定环境版本 data litellm_prompt prod { prompt_id my-langfuse-prompt environment production }数据源额外暴露version、environments、created_at、updated_at等计算属性而api_key同样不会被读出实现见 data_source_prompt.go。数据源内部复用与资源一致的promptIsNotFoundResponse判定逻辑Prompt 不存在时返回明确错误。如需批量盘点代理上的全部 Prompt可用列表数据源litellm_promptsdata litellm_prompts production { environment production } output prompt_ids { value data.litellm_prompts.production.ids }它会请求/prompts/list返回prompts含prompt_id、prompt_integration、prompt_type、version、environment、时间戳与ids全部 Prompt ID 列表。六、生命周期行为与源码佐证6.1 更新语义PUT 整包替换Update对/prompts/{prompt_id}发起PUT请求体依旧由buildPromptData生成因此任何可写参数的变更都会整体重推。测试TestPromptUpdate_SendsPUTToPromptEndpoint验证了请求方法与路径并断言修改后的api_base确实出现在 payload 中见 resource_prompt_test.go。6.2 漂移处理远端被删则清除状态Read阶段若收到404或收到带not found字样的400资源会打印 WARN 并清空 IDd.SetId()把该资源从 state 中移除交由 Terraform 决定重建而其他类型的400则按真实错误上报。这两个分支分别由TestPromptRead_NotFound400ClearsID与TestPromptRead_Other400ReturnsError覆盖。6.3 代理端的版本与多环境模型值得理解的是代理端对同一条逻辑 Prompt 是按**「基础 prompt_id environment」**维度保存多个版本的默认环境为development每次发布自动取当前最大版本号 1见 prompt_endpoints.py 中get_next_version_for_prompt、DEFAULT_PROMPT_ENVIRONMENT。/info响应同时携带prompt_spec含当前解析到的version、environment、时间戳与顶层environments数组这正是数据源能展示多环境归属的原因。因此在生产环境前先确认prompt_type、环境语义与代理版本策略是否匹配你的发布流程。七、最佳实践小结把密钥交给变量Langfuseapi_key、Provider 管理员密钥等一律经var.xxx或环境变量注入禁止硬编码在.tf中区分两类prompt_id顶层是 LiteLLM 侧唯一键也用于 import嵌套litellm_params.prompt_id才指向外部平台模板善用 Diff 抑制与不回读设计JSON 字段语义相等不会触发 plan diff敏感字段由配置侧权威无需担心漂移配合 data source 观测需要version、environments、时间戳或做状态审计时用litellm_prompt/litellm_prompts读取避免触碰敏感键改造存量先 importterraform import litellm_prompt.name prompt_id是纳管已有 Prompt 的唯一入口理解版本递增语义资源写入的是新版本记录理解代理端按环境递增版本后跨环境复制 Prompt 时务必显式规划environment与内容快照。通过上述配置团队的 Prompt 模板可以像模型、Key、Team 一样纳入同一套 Terraform 工程进行版本化、评审与回滚真正实现「LLM 应用配置全链路 IaC」。延伸阅读资源实现与 Schematerraform/provider/litellm/resource_prompt.go资源单元测试覆盖建/读/改/删与漂移terraform/provider/litellm/resource_prompt_test.go数据源实现terraform/provider/litellm/data_source_prompt.goProvider 注册与全局入口terraform/provider/litellm/provider.go代理端 Prompt CRUD 接口litellm/proxy/prompts/prompt_endpoints.pydotprompt 内联内容解析litellm/integrations/dotprompt/init.py【免费下载链接】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），仅供参考