LiteLLM Terraform Provider 管理 Search Tool 资源litellm_search_tool完整指南【免费下载链接】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 开源仓库中 Terraform Provider 的litellm_search_tool资源文档展开说明如何在 LiteLLM Proxy 上以基础设施即代码IaC的方式管理「搜索工具Search Tool」配置。搜索工具把 Proxy 的/search端点与外部搜索服务商如 Tavily、Perplexity、Exa连接起来。读完本文你将掌握litellm_search_tool资源的完整参数语义、底层 REST API 调用关系、敏感字段与导入时的安全行为以及与其配套的 Data Source、配置文件声明方式和端到端落地建议。一、背景什么是 LiteLLM 的 Search Tool在 LiteLLM Proxy 中Search Tool 是一份把某次 Web 搜索请求路由到指定外部搜索服务商的命名配置。它由三部分信息组成search_tool_name工具名作为后续调用时的寻址标识litellm_params搜索参数其中必须包含search_provider服务商类型并通常携带api_key等凭据search_tool_info可选的附加元数据例如description描述信息。调用侧通过 Proxy 提供的/search及其/v1/search、/search/{search_tool_name}、/v1/search/{search_tool_name}端点执行搜索。搜索端点核心实现位于 search 端点路由它会根据请求中的search_tool_name在 router 已加载的search_tools中匹配工具取出litellm_params.search_provider最终委托给 litellm.search 模块 的search/asearch函数完成真实调用。search_provider的合法取值由 SearchProviders 枚举 定义当前包括perplexity、tavily、exa_ai、brave、google_pse、dataforseo、firecrawl、searxng、linkup、duckduckgo、searchapi、serper、you_com、parallel_ai、apiserpent、tinyfish、agentcore、nimble、bing_grounding等。Search Tool 有两个来源数据库通过管理 API 或 Terraform 创建持久化到LiteLLM_SearchToolsTable表与Proxy 配置文件YAML 中的search_tools:段见示例 agentcore_websearch_config.yaml。Terraform 的litellm_search_tool资源管理的是前者。二、Example Usage最小可用配置litellm_search_tool资源的典型用法如下来自资源文档 search_tool.mdresource litellm_search_tool tavily { search_tool_name tavily-search litellm_params jsonencode({ search_provider tavily api_key var.tavily_api_key }) search_tool_info jsonencode({ description Tavily web search }) }需要注意的几个 HCL 细节litellm_params与search_tool_info都是字符串字段因此需要用jsonencode()把对象编码成 JSON 字符串后再传入Terraform 在做 diff 时并不关心键的顺序provider 内部会把字符串解析为对象做语义比较见下文Diff 抑制。api_key建议通过变量var.tavily_api_key或变量引用注入避免把明文密钥写进 HCL 源码。search_tool_name需要与后续/search/{search_tool_name}调用时使用的名字保持一致。三、Argument Reference字段语义与底层实现资源支持的参数如下参数必填类型说明search_tool_nameRequiredstring搜索工具名称litellm_paramsRequired (Sensitive)string (JSON)搜索参数 JSON 字符串必须包含search_provider通常含api_key也可携带api_base、timeout、max_retries等服务商相关选项search_tool_infoOptionalstring (JSON)附加元数据 JSON 字符串如{description: ...}id只读属性stringLiteLLM 分配的工具 IDcreated_at/updated_at只读属性string创建/最近更新时间戳3.1litellm_params的敏感性与不回读行为litellm_params在 Go schema 中被声明为Sensitive: true见 resource_search_tool.go。原因是它携带api_key等密钥类信息。更关键的是管理 API 返回的litellm_params永远是被掩码masked的值因此该字段never read back。查看 Read 实现可以确认这一点——Read 函数 只回填search_tool_name、search_tool_info、created_at、updated_at并特意用注释说明 litellm_params is intentionally not read back: the API masks its values and it may hold secrets.。这意味着 Terraform state 中保存的litellm_params就是你在配置里写的那个权威值每次 apply 都以 HCL 中的声明为准不会出现被 API 掩码值覆盖的问题。Provider 侧的测试也明确断言了这一行为TestResourceLiteLLMSearchToolReadMapsFields期望 Read 之后litellm_params依然保持为空、从未被回读见 resource_search_tool_test.go。服务端掩码的实现位于管理端点/search_tools/list与/search_tools/{search_tool_id}都调用_get_masked_values(litellm_params_dict, unmasked_length4, number_of_asterisks4)把明文密钥替换为sk-****形式的掩码串源码见 search_tool_management.py。3.2litellm_params的常见键位根据资源字段描述与 搜索路由实现路由层只从litellm_params中读取search_provider而其余参数如api_key、api_base、timeout、max_retries则按搜索服务商的规则在真正发起调用时使用。litellm.search的 search 函数签名 支持api_key、api_base、timeout、extra_headers以及 provider 专属的max_results、search_domain_filter、max_tokens_per_page、country等请求级参数。一个需要特别留意的坑Proxy 配置文件中定义的litellm_params块在搜索路由转发时只透传search_provider/api_key/api_base其它键会被静默忽略这一点在 agentcore_websearch_config.yaml 的注释中有明确警告。因此配置搜索工具时应把 provider 相关的请求选项放进每次调用的请求体而非塞进工具级的litellm_params。3.3 Diff 抑制语义化 JSON 比较由于litellm_params、search_tool_info以字符串存储如果按字符串字面量比较仅因键顺序不同就会产生无意义的 diff。Provider 为此实现了searchToolSuppressEquivalentJSON见 resource_search_tool.go把新旧值都json.Unmarshal成对象后用reflect.DeepEqual比较语义等价则抑制 diff。search_tool_name、created_at、updated_at没有该抑制函数。四、Attribute Reference导出属性除全部可配置参数外资源还会导出以下只读属性idLiteLLM 侧分配的搜索工具 ID。创建成功后Provider 从响应中读取search_tool_id并调用d.SetId(...)写入 Terraform state见 Create 实现。created_at创建时间戳。updated_at最近一次更新时间戳。这两个时间戳并非来自 Create 响应本身而是在 Create 末尾调用 Read 时从GET /search_tools/{id}的响应回填的。五、资源生命周期CRUD 与底层 REST APIlitellm_search_tool的 CRUD 在 resource_search_tool.go 中定义端点常量位于文件开头endpointSearchTools /search_tools endpointSearchToolByID /search_tools/%s endpointSearchToolsList /search_tools/list各操作与 Proxy 管理端点的对应关系如下Terraform 操作HTTP 调用说明CreatePOST /search_tools请求体包裹在{search_tool: {...}}中响应必须含search_tool_idReadGET /search_tools/{id}404 时清空 stated.SetId()并从 state 移除UpdatePUT /search_tools/{id}请求体除原字段外还会带上search_tool_idDeleteDELETE /search_tools/{id}404 被视为成功幂等删除结束后清空 state ID服务端对应的 REST 处理器在 search_tool_management.py 中POST /search_toolscreate_search_tool把工具写入数据库并调用_refresh_router_search_tools()刷新当前 worker 的 router 缓存PUT /search_tools/{search_tool_id}update_search_tool先校验工具存在不存在返回 404再更新并刷新 routerDELETE /search_tools/{search_tool_id}delete_search_tool同样先做存在性校验GET /search_tools/{search_tool_id}get_search_tool_info返回掩码后的litellm_params。Go 侧测试 resource_search_tool_test.go 对上述行为有完整覆盖例如TestResourceLiteLLMSearchToolCreate断言请求体确实包裹在search_tool键下且litellm_params以对象而非字符串形式传输TestResourceLiteLLMSearchToolRead404ClearsID验证 404 时从 state 移除资源。若想深入理解数据流转可以从这几个测试入手。5.1 数据库存储工具持久化在 Prisma 模型LiteLLM_SearchToolsTable见 schema.prisma其中search_tool_id为主键并以default(uuid())自动生成 UUID。Go 侧的buildSearchToolData见 resource_search_tool.go负责把 HCL 字符串解析成对象后组包若 JSON 解析失败会返回形如litellm_params must be a JSON object: ...的错误测试TestResourceLiteLLMSearchToolCreateInvalidParamsJSON验证了这一点。六、Import导入已有搜索工具已存在的搜索工具可以通过工具 ID 导入terraform import litellm_search_tool.example search_tool_id导入由schema.ImportStatePassthroughContext实现见 resource_search_tool.go即直接把传入的 ID 写入 state随后走 Read 流程拉取属性。但有一个必须知道的限制资源文档中已明确标注导入无法恢复litellm_params。因为 Read 不回读该字段导入后它在 state 中为空。因此导入完成后必须重新执行一次 apply补上你配置中的litellm_params否则工具在下次计划中会显示为待更新甚至可能因litellm_params必填校验而无法正常运作。七、配套 Data Source 与安全注意事项除资源外仓库还提供两个只读数据源均不暴露litellm_params因为其可能持有服务商 API 密钥litellm_search_tool单条数据源通过search_tool_id获取单条工具信息导出search_tool_name、search_tool_info、created_at、updated_at。litellm_search_tools列表数据源拉取 Proxy 上全部搜索工具数据库 配置文件来源导出ids与search_tools列表列表项额外包含is_from_config字段用于标识该工具来自配置文件而非数据库。data litellm_search_tool existing { search_tool_id 123e4567-e89b-12d3-a456-426614174000 } output search_tool_name { value data.litellm_search_tool.existing.search_tool_name }7.1is_from_config的由来列表端点/search_tools/list会合并两个来源数据库中的工具以及从proxy_config.parse_search_tools(config)解析出的 YAML 配置工具见 search_tool_management.py。配置来源的工具没有数据库 ID 与时间戳因此响应中对应字段为null且is_from_configtrue。理解这一点有助于避免误用 Terraform 管理本就声明在 YAML 配置文件中的工具——那部分更适合直接改配置文件来管理。7.2 鉴权搜索工具的管理端点/search_tools系列都挂载了user_api_key_auth依赖工具级访问控制can_key_call_search_tool、can_team_call_search_tool在调用/search/{search_tool_name}时执行。若在 Admin UI 或脚本中管理工具请使用具备相应权限如 Proxy Admin的密钥。八、端到端落地建议一个完整的用 Terraform 管理 LiteLLM 搜索能力的流程大致是用litellm_search_tool资源声明并创建搜索工具把api_key通过变量安全注入用配套 Data Source 反查已有工具供其它配置消费工具 ID 与名称通过POST /search/{search_tool_name}或/v1/search/{search_tool_name}发起搜索请求体遵循 Perplexity Search API 风格例如curl -X POST http://localhost:4000/v1/search/tavily-search \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { query: latest AI developments 2024, max_results: 5, search_domain_filter: [arxiv.org, nature.com] }变更密钥等litellm_params内容后正常terraform plan/apply即可——由于 API 只返回掩码值、配置值始终是权威来源Terraform 会以你声明的明文值持续覆盖更新不会产生漂移若管理的是版本化团队、多环境的 Proxy可以进一步把search_tool_name、search_provider提取为变量或locals配合模块化组织实现按环境复用的搜索工具编排。九、小结litellm_search_tool是 LiteLLM Terraform Provider 中管理 Proxy 搜索工具的标准资源。理解其三个要点即可放心使用JSON 字符串承载配置litellm_params与search_tool_info必须用jsonencode编码provider 内部做语义化 diff密钥不回读API 返回掩码值litellm_params的权威值始终来自你的配置删除/重放 apply 会重建完整配置导入需补 applyterraform import后务必再 apply 一次以补回litellm_params。更进一步可以结合 search_tool_management.py、搜索端点路由、search_tool_registry.py 与 Provider 的 resource_search_tool.go 及其测试文件从 HTTP 协议到数据库存储完整地掌握这一能力的运行机制。【免费下载链接】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），仅供参考