尧图网站建设 
使用 Terraform 管理 Onyx 部署级默认 LLM 模型onyx_llm_provider_default 资源完全指南【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer本篇指南基于开源仓库 terraform-provider-onyx 中的官方文档 llm_provider_default.md 编写并结合后端 API 与 Provider 源码进行纵深剖析。它适用于所有希望通过 Infrastructure as Code 方式统一管理 Onyx开源 AI 平台部署默认文本模型、默认视觉模型与聊天自动命名模型的平台工程师。为什么需要一个默认模型资源Onyx 是一个开源 AI 平台其 LLM 供应商Provider体系允许管理员注册多个 Provider每个 Provider 下再配置若干 Model Configuration。整个部署需要指定一个部署级默认 LLM 模型——它决定用户发起聊天时默认使用哪个 Provider 的哪个模型。在 terraform-provider-onyx 中这个默认值被建模为一个独立资源onyx_llm_provider_default而不是 Provider 资源上的一个字段。官方文档terraform-provider-onyx/docs/resources/llm_provider_default.md给出的定位是The deployment-wide default LLM model — a singleton pointer at one provider model pair (plus optional vision and chat auto-naming defaults).即它是一个单例指针指向一个 Provider 一个模型的组合并可选附带默认视觉模型vision和聊天自动命名模型chat auto-naming的配置。将其独立建模的核心价值在于依赖排序depends_on ordering当某个 Provider 需要被删除或缩减shrunk时Terraform 需要先把默认指针重定向repoint到别的 Provider再执行删除由于onyx_llm_provider_default通过provider_id onyx_llm_provider.xxx.id引用 Provider 的 idTerraform 的依赖图会自动保证先更新/重定向默认指针再删除持有该默认的 Provider这避免了删除默认 Provider 时后端报错或默认被意外清空的局面后端 API 对持有 chat 默认的 Provider 删除有保护逻辑详见下文。资源 Schema 详解onyx_llm_provider_default的 Schema 由 llm_provider_default_resource.go 定义共 7 个属性分为三类Required必填属性类型说明provider_idString持有默认模型的onyx_llm_provider资源的 id。model_nameString该 Provider 内的模型名称例如gpt-5-mini。必须命中该 Provider 下可见的model_configurations之一即必须与onyx_llm_provider中声明的model_configurations里的name对应。Optional可选属性类型说明vision_provider_idString默认视觉模型所在的 Provider id。vision_model_nameString默认视觉模型名称。chat_naming_provider_idString聊天自动命名专用模型的 Provider id。不设置时自动命名使用当前会话session的模型删除该对配置会清除服务器端值。chat_naming_model_nameString聊天自动命名专用模型名称。配对校验规则源码中对这四个可选属性都配置了stringvalidator.AlsoRequires验证器即vision_provider_id与vision_model_name必须成对出现不能只填其中一个chat_naming_provider_id与chat_naming_model_name必须成对出现。Read-Only只读属性类型说明idString恒为default。因为该资源是单例id 固定不变。完整示例配置官方文档 Example Usage 与示例文件 resource.tf 给出了最小可用配置# The deployment-wide default model. Referencing the providers id also # orders destroys correctly: the default is repointed/released before the # provider holding it is deleted. resource onyx_llm_provider_default this { provider_id onyx_llm_provider.openai.id model_name gpt-5 vision_provider_id onyx_llm_provider.openai.id vision_model_name gpt-5 }下面是一个更贴近生产实践的组合示例先创建两个 Provider再分别把文本默认、视觉默认、聊天命名默认指向不同的模型组合。# 供应商 A负责文本对话 resource onyx_llm_provider primary { name openai-primary provider_type openai api_key var.openai_api_key model_configurations [ { name gpt-5 }, { name gpt-5-mini }, { name gpt-5-nano }, ] } # 供应商 B负责视觉与命名 resource onyx_llm_provider vision { name openai-vision provider_type openai api_key var.openai_api_key model_configurations [ { name gpt-5 }, { name gpt-5-mini }, ] } resource onyx_llm_provider_default this { # 部署级文本默认 provider_id onyx_llm_provider.primary.id model_name gpt-5 # 部署级视觉默认 vision_provider_id onyx_llm_provider.vision.id vision_model_name gpt-5 # 聊天自动命名默认 chat_naming_provider_id onyx_llm_provider.primary.id chat_naming_model_name gpt-5-nano }底层原理一次 apply 最多三次后端写入onyx_llm_provider_default的 CRUD 实现在 llm_provider_default_resource.go 中其核心是apply方法——它最多做三次写入把每次成功的结果叠加到 base 之上失败时返回部分结果以及是否写过任何内容以便调用方精确持久化服务器端已发生的变更。三次写入分别对应三个后端端点client/llm_provider.goTerraform 字段HTTP 方法与路径说明provider_idmodel_namePOST /admin/llm/default设置部署级默认文本模型SetDefaultLLMModelvision_provider_idvision_model_namePOST /admin/llm/default-vision设置部署级默认视觉模型SetDefaultVisionModelchat_naming_provider_idchat_naming_model_namePOST /admin/llm/default-chat-naming设置聊天自动命名模型SetDefaultChatNamingModel删除 chat-naming 对DELETE /admin/llm/default-chat-naming清除聊天自动命名模型ClearDefaultChatNamingModel在 Go 客户端中这些调用通过doJSON完成例如// SetDefaultLLMModel sets the global default text model. func (c *Client) SetDefaultLLMModel(ctx context.Context, req DefaultModel) error { return c.doJSON(ctx, http.MethodPost, /admin/llm/default, req, nil) }而DefaultModel结构体仅包含两个字段ProviderID int64与ModelName stringllm_provider.go与文档中一个 Provider 一个 Model 的单例指针定位完全一致。后端 API 的对应实现后端 FastAPI 路由定义在 backend/onyx/server/manage/llm/api.pyPOST /admin/llm/default→update_default_provider(provider_id, model_name, ...)权限要求Permission.MANAGE_LLMSPOST /admin/llm/default-vision→update_default_vision_provider(...)POST /admin/llm/default-chat-naming→update_default_chat_naming_provider(...)权限要求Permission.FULL_ADMIN_PANEL_ACCESSDELETE /admin/llm/default-chat-naming→update_no_default_chat_naming_provider(...)注释明确说明清除专用命名模型后自动命名回退到会话的模型。这解释了资源文档中的一个关键差异文本与视觉默认没有 unset API而聊天命名默认有。生命周期语义创建、更新、读取、删除、导入Create创建Create以空 state 为 base 调用apply把计划中的三个默认逐一写入。即便部分失败如 vision 写入失败也会把已成功的部分写入 state确保 Terraform state 与服务器端实际状态一致llm_provider_default_resource.go。Update更新Update读取新旧 state计算clearChatNaming当计划中chat_naming_provider_id为 null 而旧 state 非 null 时说明用户从配置中删除了 chat-naming 对此时会调用DELETE /admin/llm/default-chat-naming清除服务器端值llm_provider_default_resource.go。Read读取Read调用GET /admin/llm/provider?include_image_gentrueListLLMProviders获取服务器端default_text、default_vision、default_chat_naming。值得注意的两个细节llm_provider_default_resource.go若服务器端default_text为空资源会直接从 state 中移除RemoveResourcevision 与 chat-naming 默认只有在被 Terraform 管理即 state 中非 null时才会被刷新未管理时即使服务器端配置了state 中也保持 null——避免 Terraform 接管未声明管理的配置。Delete删除Delete的行为是文档中特别强调、也是最容易踩坑的一点llm_provider_default_resource.go文本与视觉默认Onyx 没有 unset API因此销毁该资源后服务器端的默认文本/视觉模型依然保留在原 Provider 上。Provider 只会发出一个 WarningDefault LLM model left unchanged聊天命名默认如果 state 中管理了 chat-naming 对删除时会调用DELETE /admin/llm/default-chat-naming将其清除。换句话说terraform destroy此资源 ≠ 清空部署默认。如果目标是把默认文本模型切回无默认该行为不被 API 支持属于后端能力边界。Import导入该资源是单例导入 id 恒为defaultimport.sh#!/bin/sh # Singleton: the import id is always default. terraform import onyx_llm_provider_default.this defaultImportState会对非default的导入 id 直接报错llm_provider_default_resource.go。导入后的后续Read会自动从服务器端刷新provider_id与model_namevision 与 chat-naming 对则保持 null直到用户在配置中显式声明。与 onyx_llm_provider 的协同删除顺序与 force_delete将默认指针独立成资源的最大收益体现在 Provider 生命周期管理中。后端在删除 Provider 时存在保护逻辑backend/onyx/server/manage/llm/api.py只有 chat 默认会阻止 Provider 删除。删除持有其他流程文本/视觉默认的 Provider会故意连带清空该默认——这由测试test_delete_default_vision_provider_clears_vision_default覆盖。也就是说持有文本或视觉默认的 Provider 可以删除但会连带丢失默认配置而持有 chat 默认的 Provider 不允许删除除非传forcetrue。后端逻辑如下model fetch_default_llm_model(db_session) if model and model.llm_provider_id provider_id: raise OnyxError( OnyxErrorCode.RESOURCE_IN_USE, Cannot delete this provider: it holds the deployments chat default model. Repoint that default first, or pass forcetrue., )因此正确做法是让 Terraform 的依赖关系天然保证先重定向、后删除onyx_llm_provider_default引用onyx_llm_provider.id删除 Provider 时 Terraform 会先重算默认指针再执行 Provider 删除避免RESOURCE_IN_USE报错。作为兜底onyx_llm_provider还提供force_delete参数允许在持有默认的情况下强制删除。端到端验证从 AccTest 看资源行为资源的行为在 llm_provider_default_resource_test.go 的验收测试AccTest中被完整验证创建创建onyx_llm_provider带gpt-5-mini、gpt-5-nano两个 model_configurations 与force_delete true再创建onyx_llm_provider_default指向gpt-5-mini断言id default、provider_id与 Provider 的id一致并调用testAccCheckServerDefaultModel验证服务器端默认确实被设置更新将model_name改为gpt-5-nano再次断言服务器端默认同步更新导入以ImportStateId default执行导入并ImportStateVerify。这套测试同时覆盖了 Provider 与默认资源的联动可以作为你在自己基础设施中编写配置时的参考模板。另外client 层的单元测试TestSetDefaultLLMModel、TestSetDefaultVisionModel、TestSetDefaultChatNamingModel、TestClearDefaultChatNamingModel直接验证了四个端点的请求路径与参数构造。关键要点速查onyx_llm_provider_default是单例资源id恒为default导入 id 也必须是defaultprovider_idmodel_name是唯一必填组合其余均为成对出现的可选属性引用onyx_llm_provider.xxx.id而非硬编码数字 id可获得正确的销毁顺序销毁资源不会清空服务器端文本/视觉默认无 unset API仅会清除被管理的 chat-naming 默认后端对持有 chat 默认的 Provider 删除有保护RESOURCE_IN_USE需要通过重定向默认或force_delete解决model_name必须命中 Provider 下可见的model_configurations否则后端写入会失败。通过将部署级默认 LLM 纳入 Terraform 管理你可以把哪个 Provider、哪个模型作为全局默认这一关键决策版本化、可审计、可回滚并与 Provider 资源、权限配置一起构成完整的 LLM 基础设施声明。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Terraform 管理 Onyx 部署级默认 LLM 模型：onyx_llm_provider_default 资源完全指南
使用 Terraform 管理 Onyx 部署级默认 LLM 模型onyx_llm_provider_default 资源完全指南【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer本篇指南基于开源仓库 terraform-provider-onyx 中的官方文档 llm_provider_default.md 编写并结合后端 API 与 Provider 源码进行纵深剖析。它适用于所有希望通过 Infrastructure as Code 方式统一管理 Onyx开源 AI 平台部署默认文本模型、默认视觉模型与聊天自动命名模型的平台工程师。为什么需要一个默认模型资源Onyx 是一个开源 AI 平台其 LLM 供应商Provider体系允许管理员注册多个 Provider每个 Provider 下再配置若干 Model Configuration。整个部署需要指定一个部署级默认 LLM 模型——它决定用户发起聊天时默认使用哪个 Provider 的哪个模型。在 terraform-provider-onyx 中这个默认值被建模为一个独立资源onyx_llm_provider_default而不是 Provider 资源上的一个字段。官方文档terraform-provider-onyx/docs/resources/llm_provider_default.md给出的定位是The deployment-wide default LLM model — a singleton pointer at one provider model pair (plus optional vision and chat auto-naming defaults).即它是一个单例指针指向一个 Provider 一个模型的组合并可选附带默认视觉模型vision和聊天自动命名模型chat auto-naming的配置。将其独立建模的核心价值在于依赖排序depends_on ordering当某个 Provider 需要被删除或缩减shrunk时Terraform 需要先把默认指针重定向repoint到别的 Provider再执行删除由于onyx_llm_provider_default通过provider_id onyx_llm_provider.xxx.id引用 Provider 的 idTerraform 的依赖图会自动保证先更新/重定向默认指针再删除持有该默认的 Provider这避免了删除默认 Provider 时后端报错或默认被意外清空的局面后端 API 对持有 chat 默认的 Provider 删除有保护逻辑详见下文。资源 Schema 详解onyx_llm_provider_default的 Schema 由 llm_provider_default_resource.go 定义共 7 个属性分为三类Required必填属性类型说明provider_idString持有默认模型的onyx_llm_provider资源的 id。model_nameString该 Provider 内的模型名称例如gpt-5-mini。必须命中该 Provider 下可见的model_configurations之一即必须与onyx_llm_provider中声明的model_configurations里的name对应。Optional可选属性类型说明vision_provider_idString默认视觉模型所在的 Provider id。vision_model_nameString默认视觉模型名称。chat_naming_provider_idString聊天自动命名专用模型的 Provider id。不设置时自动命名使用当前会话session的模型删除该对配置会清除服务器端值。chat_naming_model_nameString聊天自动命名专用模型名称。配对校验规则源码中对这四个可选属性都配置了stringvalidator.AlsoRequires验证器即vision_provider_id与vision_model_name必须成对出现不能只填其中一个chat_naming_provider_id与chat_naming_model_name必须成对出现。Read-Only只读属性类型说明idString恒为default。因为该资源是单例id 固定不变。完整示例配置官方文档 Example Usage 与示例文件 resource.tf 给出了最小可用配置# The deployment-wide default model. Referencing the providers id also # orders destroys correctly: the default is repointed/released before the # provider holding it is deleted. resource onyx_llm_provider_default this { provider_id onyx_llm_provider.openai.id model_name gpt-5 vision_provider_id onyx_llm_provider.openai.id vision_model_name gpt-5 }下面是一个更贴近生产实践的组合示例先创建两个 Provider再分别把文本默认、视觉默认、聊天命名默认指向不同的模型组合。# 供应商 A负责文本对话 resource onyx_llm_provider primary { name openai-primary provider_type openai api_key var.openai_api_key model_configurations [ { name gpt-5 }, { name gpt-5-mini }, { name gpt-5-nano }, ] } # 供应商 B负责视觉与命名 resource onyx_llm_provider vision { name openai-vision provider_type openai api_key var.openai_api_key model_configurations [ { name gpt-5 }, { name gpt-5-mini }, ] } resource onyx_llm_provider_default this { # 部署级文本默认 provider_id onyx_llm_provider.primary.id model_name gpt-5 # 部署级视觉默认 vision_provider_id onyx_llm_provider.vision.id vision_model_name gpt-5 # 聊天自动命名默认 chat_naming_provider_id onyx_llm_provider.primary.id chat_naming_model_name gpt-5-nano }底层原理一次 apply 最多三次后端写入onyx_llm_provider_default的 CRUD 实现在 llm_provider_default_resource.go 中其核心是apply方法——它最多做三次写入把每次成功的结果叠加到 base 之上失败时返回部分结果以及是否写过任何内容以便调用方精确持久化服务器端已发生的变更。三次写入分别对应三个后端端点client/llm_provider.goTerraform 字段HTTP 方法与路径说明provider_idmodel_namePOST /admin/llm/default设置部署级默认文本模型SetDefaultLLMModelvision_provider_idvision_model_namePOST /admin/llm/default-vision设置部署级默认视觉模型SetDefaultVisionModelchat_naming_provider_idchat_naming_model_namePOST /admin/llm/default-chat-naming设置聊天自动命名模型SetDefaultChatNamingModel删除 chat-naming 对DELETE /admin/llm/default-chat-naming清除聊天自动命名模型ClearDefaultChatNamingModel在 Go 客户端中这些调用通过doJSON完成例如// SetDefaultLLMModel sets the global default text model. func (c *Client) SetDefaultLLMModel(ctx context.Context, req DefaultModel) error { return c.doJSON(ctx, http.MethodPost, /admin/llm/default, req, nil) }而DefaultModel结构体仅包含两个字段ProviderID int64与ModelName stringllm_provider.go与文档中一个 Provider 一个 Model 的单例指针定位完全一致。后端 API 的对应实现后端 FastAPI 路由定义在 backend/onyx/server/manage/llm/api.pyPOST /admin/llm/default→update_default_provider(provider_id, model_name, ...)权限要求Permission.MANAGE_LLMSPOST /admin/llm/default-vision→update_default_vision_provider(...)POST /admin/llm/default-chat-naming→update_default_chat_naming_provider(...)权限要求Permission.FULL_ADMIN_PANEL_ACCESSDELETE /admin/llm/default-chat-naming→update_no_default_chat_naming_provider(...)注释明确说明清除专用命名模型后自动命名回退到会话的模型。这解释了资源文档中的一个关键差异文本与视觉默认没有 unset API而聊天命名默认有。生命周期语义创建、更新、读取、删除、导入Create创建Create以空 state 为 base 调用apply把计划中的三个默认逐一写入。即便部分失败如 vision 写入失败也会把已成功的部分写入 state确保 Terraform state 与服务器端实际状态一致llm_provider_default_resource.go。Update更新Update读取新旧 state计算clearChatNaming当计划中chat_naming_provider_id为 null 而旧 state 非 null 时说明用户从配置中删除了 chat-naming 对此时会调用DELETE /admin/llm/default-chat-naming清除服务器端值llm_provider_default_resource.go。Read读取Read调用GET /admin/llm/provider?include_image_gentrueListLLMProviders获取服务器端default_text、default_vision、default_chat_naming。值得注意的两个细节llm_provider_default_resource.go若服务器端default_text为空资源会直接从 state 中移除RemoveResourcevision 与 chat-naming 默认只有在被 Terraform 管理即 state 中非 null时才会被刷新未管理时即使服务器端配置了state 中也保持 null——避免 Terraform 接管未声明管理的配置。Delete删除Delete的行为是文档中特别强调、也是最容易踩坑的一点llm_provider_default_resource.go文本与视觉默认Onyx 没有 unset API因此销毁该资源后服务器端的默认文本/视觉模型依然保留在原 Provider 上。Provider 只会发出一个 WarningDefault LLM model left unchanged聊天命名默认如果 state 中管理了 chat-naming 对删除时会调用DELETE /admin/llm/default-chat-naming将其清除。换句话说terraform destroy此资源 ≠ 清空部署默认。如果目标是把默认文本模型切回无默认该行为不被 API 支持属于后端能力边界。Import导入该资源是单例导入 id 恒为defaultimport.sh#!/bin/sh # Singleton: the import id is always default. terraform import onyx_llm_provider_default.this defaultImportState会对非default的导入 id 直接报错llm_provider_default_resource.go。导入后的后续Read会自动从服务器端刷新provider_id与model_namevision 与 chat-naming 对则保持 null直到用户在配置中显式声明。与 onyx_llm_provider 的协同删除顺序与 force_delete将默认指针独立成资源的最大收益体现在 Provider 生命周期管理中。后端在删除 Provider 时存在保护逻辑backend/onyx/server/manage/llm/api.py只有 chat 默认会阻止 Provider 删除。删除持有其他流程文本/视觉默认的 Provider会故意连带清空该默认——这由测试test_delete_default_vision_provider_clears_vision_default覆盖。也就是说持有文本或视觉默认的 Provider 可以删除但会连带丢失默认配置而持有 chat 默认的 Provider 不允许删除除非传forcetrue。后端逻辑如下model fetch_default_llm_model(db_session) if model and model.llm_provider_id provider_id: raise OnyxError( OnyxErrorCode.RESOURCE_IN_USE, Cannot delete this provider: it holds the deployments chat default model. Repoint that default first, or pass forcetrue., )因此正确做法是让 Terraform 的依赖关系天然保证先重定向、后删除onyx_llm_provider_default引用onyx_llm_provider.id删除 Provider 时 Terraform 会先重算默认指针再执行 Provider 删除避免RESOURCE_IN_USE报错。作为兜底onyx_llm_provider还提供force_delete参数允许在持有默认的情况下强制删除。端到端验证从 AccTest 看资源行为资源的行为在 llm_provider_default_resource_test.go 的验收测试AccTest中被完整验证创建创建onyx_llm_provider带gpt-5-mini、gpt-5-nano两个 model_configurations 与force_delete true再创建onyx_llm_provider_default指向gpt-5-mini断言id default、provider_id与 Provider 的id一致并调用testAccCheckServerDefaultModel验证服务器端默认确实被设置更新将model_name改为gpt-5-nano再次断言服务器端默认同步更新导入以ImportStateId default执行导入并ImportStateVerify。这套测试同时覆盖了 Provider 与默认资源的联动可以作为你在自己基础设施中编写配置时的参考模板。另外client 层的单元测试TestSetDefaultLLMModel、TestSetDefaultVisionModel、TestSetDefaultChatNamingModel、TestClearDefaultChatNamingModel直接验证了四个端点的请求路径与参数构造。关键要点速查onyx_llm_provider_default是单例资源id恒为default导入 id 也必须是defaultprovider_idmodel_name是唯一必填组合其余均为成对出现的可选属性引用onyx_llm_provider.xxx.id而非硬编码数字 id可获得正确的销毁顺序销毁资源不会清空服务器端文本/视觉默认无 unset API仅会清除被管理的 chat-naming 默认后端对持有 chat 默认的 Provider 删除有保护RESOURCE_IN_USE需要通过重定向默认或force_delete解决model_name必须命中 Provider 下可见的model_configurations否则后端写入会失败。通过将部署级默认 LLM 纳入 Terraform 管理你可以把哪个 Provider、哪个模型作为全局默认这一关键决策版本化、可审计、可回滚并与 Provider 资源、权限配置一起构成完整的 LLM 基础设施声明。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考