使用 terraform-provider-onyx 管理 Onyx 云嵌入模型提供商onyx_embedding_provider 资源实战指南【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer导读本文围绕 Onyx 官方 Terraform Provider 中的onyx_embedding_provider资源系统讲解如何用 IaC 方式在 Onyx 平台上声明、更新与导入云嵌入模型Embedding提供商的凭据配置。你将掌握该资源全部 Schema 字段的语义与取舍包括api_key与api_key_wo两种密钥管理方式、Provider 底层与 Onyx Admin API 的交互原理以及活跃提供商不可删除更新会全量覆盖字段等关键陷阱的规避方法可直接应用于 Onyx 生产环境的自动化交付。一、资源定位一个提供商类型对应一条云嵌入凭据在 Onyx 平台中Embedding Provider 是负责把文本/文档向量化的云服务凭据配置常见类型包括openai、cohere、voyage、google、litellm、azure。onyx_embedding_provider资源的作用就是为每一种提供商类型保存一份云端凭据其约束与语义可总结为天然键API 以provider_type作为资源的自然主键因此同一类型的 Provider 全局唯一一次一个一个资源实例只对应一种提供商类型同一类型重复声明会被视为更新而非新建不可直接读取密钥API 在读取GET时会屏蔽api_key因此配置之外发生的密钥变更无法被 Terraform 检测到删除受限当前正在被搜索设置Search Settings使用的提供商无法被删除API 不提供任何强制覆盖手段必须先切换搜索设置。该资源在 Provider 内部的注册与 CRUD 实现位于 embedding_provider_resource.go配套的 API 客户端封装位于 embedding_provider.go下文会结合这两份源码逐步展开。二、最小可运行示例官方 resource.tf 给出了一段极简但完整的声明式配置# 务必在配置中保留 api_keyOnyx API 在更新时会替换全部字段 # 若应用时未携带密钥则会清空服务端已存储的密钥。 resource onyx_embedding_provider cohere { provider_type cohere api_key var.cohere_api_key }其中var.cohere_api_key是你在变量文件或环境变量中传入的敏感值。将上述配置加入你的 Terraform 根模块后执行terraform init terraform plan terraform apply即可在 Onyx 平台创建或更新名为cohere的嵌入提供商凭据。示例中的注释并非可有可无——它揭示了一条核心行为Onyx API 的 Upsert 是全量替换语义任何一次 Apply 都会把请求体中的全部字段写回服务端。三、Schema 全解析该资源共包含 8 个属性按 Required / Optional / Read-Only 分类如下Required必填属性类型说明provider_typeString提供商类型取值限定为openai、cohere、voyage、google、litellm、azure六种之一。修改该字段会触发资源重建RequiresReplace因为它是 API 的自然主键从源码看该字段的取值约束由stringvalidator.OneOf(openai, cohere, voyage, google, litellm, azure)在 Plan 阶段直接校验非法取值会在terraform plan时即报错见 embedding_provider_resource.go同时通过stringplanmodifier.RequiresReplace()保证变更类型时先销毁旧资源再创建新资源避免用错误的键覆盖已有数据。Optional可选属性类型说明api_keyStringSensitive提供商 API 密钥。由于 API 没有保留已存密钥的开关更新请求若未携带该值会直接清空服务端存储的密钥。更推荐使用api_key_wo密钥完全不进 State二者互斥不能同时设置api_key_woStringSensitiveWrite-only只写版本的密钥只存在于 Terraform 配置文件中。每次 Apply 都会发送但 Terraform 不落盘 State密钥永远不会出现在 State 文件中。需搭配api_key_wo_version实现轮换且要求Terraform 1.11 及以上版本api_key_wo_versionNumber与api_key_wo配对的轮换计数器。Terraform 从不存储只写值因此无法感知密钥是否变化手动调大该数字即可让下一次 Apply 重新发送当前配置中的密钥。注意不要用密钥本身派生该数字因为计数器会保存在 State 中而密钥不会api_urlString自定义 API 地址典型场景是 LiteLLM 代理或 Azure 端点api_versionStringAPI 版本号Azure 场景使用deployment_nameString部署名称Azure 场景使用Read-Only只读属性类型说明idString与provider_type完全一致API 的自然键由系统计算并写入api_url、api_version、deployment_name三个字段在请求体中均为可选指针*string未设置时以null形式传输见 embedding_provider.go。id字段使用UseStateForUnknown()修饰资源创建后由plan.ID plan.ProviderType写入见 embedding_provider_resource.go后续 Refresh 保持不变。四、API Key 的三种管理姿势与轮换这是该资源设计上最值得关注的部分涉及密钥不进 State可轮换等安全诉求Provider 提供了两条互补的密钥通道。姿势一api_key——简单直接但会进入 State把密钥直接写在资源块中Terraform 会将其记录在 State 文件中虽然被标记为 Sensitive 并在 CLI 输出中打码但仍以明文存在于本地 state 与远端 backend 中。适合密钥本身已在受管控的变量系统中、且你接受 State 明文存储的团队。姿势二api_key_wo——只写属性密钥永不落盘Terraform 1.11 起支持 Write-only Arguments即文档中所说的 write-only arguments。api_key_wo声明为WriteOnly: true见 embedding_provider_resource.goTerraform 会把它从 Plan 和 State 中一并剥离密钥只存在于配置文件。这是所有场景下的推荐姿势。使用方式resource onyx_embedding_provider cohere { provider_type cohere api_key_wo var.cohere_api_key_wo }姿势三api_key_woapi_key_wo_version——可感知的密钥轮换只写值既然不进 StateTerraform 便无法 diff 出密钥变了单独修改api_key_wo不会产生任何 Plan 差异。为此 Provider 提供了配套的整数计数器api_key_wo_versionresource onyx_embedding_provider cohere { provider_type cohere api_key_wo var.cohere_api_key_wo api_key_wo_version 2 # 轮换密钥时调大该数字 }轮换流程修改api_key_wo中的新密钥 → 同时把api_key_wo_version从 1 调到 2 →terraform apply。计数器的变化产生 Diff触发 Update并把当前配置中的密钥随请求发送给 Onyx。相关实现集中在 write_only.goresolveWriteOnly负责在构造请求体时从配置中提取只写值writeOnlyVersionAttribute负责生成计数器字段并约束其必须与api_key_wo同时出现int64validator.AlsoRequires。两组约束务必牢记api_key与api_key_wo互斥同时设置会直接报校验错误stringvalidator.ConflictsWith当两者都未设置时Provider 在 Update 前会发出警告因为 Onyx API 更新时全量替换字段没有密钥的更新会清空服务端已存密钥见 embedding_provider_resource.go 的AddWarning逻辑。五、底层原理资源生命周期与 API 交互理解 Provider 如何与 Onyx 后端交互有助于预判各种边界行为。客户端 API 封装客户端把CloudEmbeddingProvider结构体镜像后端模型以provider_type为键映射为四个 HTTP 调用见 embedding_provider.go操作方法路径说明Upsert创建/更新PUT/admin/embedding/embedding-provider按provider_type全量 upsert列表GET/admin/embedding/embedding-provider返回全部已配置的云嵌入提供商单查GET/admin/embedding/embedding-provider/{provider_type}注意后端没有 get-by-id 端点客户端实际是拉取全量列表后本地按provider_type匹配未命中则合成一个 404APIError删除DELETE/admin/embedding/embedding-provider/{provider_type}后端无条件拒绝删除当前活跃的提供商资源 CRUD 的关键实现Create从 Plan 构建请求体密钥经resolveWriteOnly解析调用 Upsert成功后把id写为provider_type见 embedding_provider_resource.goRead调用 Get若返回 404 则从 State 中移除资源漂移自愈否则回填provider_type、api_url、api_version、deployment_name。api_key不做回填——因为 GET 返回的是打码值写回 State甚至更糟写回后续的 Upsert 请求体会永久损坏已存密钥。这正是配置是权威、每次更新都重发设计的原因见 embedding_provider_resource.goUpdate同样走 Upsert且从 Plan 而非 State 构建请求体——注释明确说明若把 GET 得到的打码 api_key 写回会破坏已存储的密钥见 embedding_provider_resource.goDelete调用 DELETE若后端返回 400则向用户抛出专门错误Onyx API 拒绝删除当前搜索设置正在使用的嵌入提供商且没有覆盖开关请先把搜索设置切换到其他提供商见 embedding_provider_resource.go。后端 API 佐证上述行为在后端有直接对应实现。Admin API 路由定义于 backend/onyx/server/manage/embedding/api.pyGET /admin/embedding/embedding-provider列出全部提供商GET /admin/embedding/embedding-provider/{provider_type}按类型获取单个提供商DELETE /admin/embedding/embedding-provider/{provider_type}删除前会先调用get_current_db_embedding_provider检查当前活跃提供商若provider_type与活跃提供商一致则拒绝删除PUT /admin/embedding/embedding-provider执行云提供商 Upsert。同时搜索设置模块 backend/onyx/server/manage/search_settings.py 中的get_embedding_provider_from_provider_type展示了后端如何按类型解析嵌入提供商印证了当前活跃提供商这一概念的来源。六、配套数据源onyx_embedding_providers与资源配套的只读数据源onyx_embedding_providers用于枚举当前 Onyx 平台上所有已配置的云嵌入提供商官方用法见>data onyx_embedding_providers all {}数据源 Schema 只有一个只读属性providers对象列表每个对象包含provider_type、api_url、api_version、deployment_name四个只读字段。注意api_key不会被暴露见 embedding_providers_data_source.go与资源读取时屏蔽密钥的行为一致确保了密钥的最小暴露面。典型用法是在模块内引用它做条件化配置例如判断目标类型是否已存在、或把全部提供商类型输出给其他资源引用output configured_embedding_providers { value data.onyx_embedding_providers.all.providers[*].provider_type }数据源通过ListEmbeddingProviders即GET /admin/embedding/embedding-provider拉取数据详细 Schema 见 embedding_providers.md。七、导入已有资源如果 Onyx 平台上已存在手工创建的嵌入提供商可以通过terraform import将其纳入 Terraform 管理官方导入脚本见 import.sh#!/bin/sh # 按提供商类型API 的自然键导入 terraform import onyx_embedding_provider.cohere cohere导入 ID 就是provider_type。ImportState 实现会把它同时写入id与provider_type两个属性见 embedding_provider_resource.go。导入后建议立即执行terraform plan对照你的配置确认api_url、api_version、deployment_name等字段与远端一致。八、最佳实践与常见陷阱综合文档与源码总结以下可直接落地的实践要点优先使用api_key_woapi_key_wo_version密钥不进 State安全性最高轮换时记得同步递增计数器否则 Apply 不会触发密钥重发始终在配置中保留密钥Onyx 的 Upsert 是全量替换任何一次不带密钥的 Apply 都会清空服务端密钥且这种清空不可逆、无告警Provider 只会给出 Warning不会阻断删除活跃提供商前先切换搜索设置Onyx 后端强制拒绝删除当前搜索设置正在使用的提供商报错为 HTTP 400Terraform 会将其包装为明确的诊断信息。正确的操作顺序是先把 Search Settings 指向其他提供商再执行terraform destroy不要把api_key与api_key_wo混用二者互斥混用会直接导致 Plan 校验失败provider_type变更会重建资源由于它是 API 的自然主键Terraform 会先销毁再创建请确认没有其他模块引用旧类型后再修改Read 阶段不回填密钥不要依赖terraform refresh或state show来恢复丢失的密钥配置——远端只返回打码值密钥的唯一权威来源是你的配置文件。结语onyx_embedding_provider是 Onyx Terraform Provider 中一个小而深的资源属性不多却集中体现了密钥安全write-only 机制、API 语义映射全量替换、天然键、活跃保护与 IaC 状态管理导入、漂移自愈、轮换计数器等 Terraform Provider 开发的核心议题。掌握了它的 Schema 语义与底层 API 行为你便能在 Onyx 的嵌入能力自动化管理上少踩坑、更安全——建议在仓库中进一步阅读 embedding_provider_resource.go 与 write_only.go 的完整实现以理解每个属性背后的设计决策。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 terraform-provider-onyx 管理 Onyx 云嵌入模型提供商：onyx_embedding_provider 资源实战指南
使用 terraform-provider-onyx 管理 Onyx 云嵌入模型提供商onyx_embedding_provider 资源实战指南【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer导读本文围绕 Onyx 官方 Terraform Provider 中的onyx_embedding_provider资源系统讲解如何用 IaC 方式在 Onyx 平台上声明、更新与导入云嵌入模型Embedding提供商的凭据配置。你将掌握该资源全部 Schema 字段的语义与取舍包括api_key与api_key_wo两种密钥管理方式、Provider 底层与 Onyx Admin API 的交互原理以及活跃提供商不可删除更新会全量覆盖字段等关键陷阱的规避方法可直接应用于 Onyx 生产环境的自动化交付。一、资源定位一个提供商类型对应一条云嵌入凭据在 Onyx 平台中Embedding Provider 是负责把文本/文档向量化的云服务凭据配置常见类型包括openai、cohere、voyage、google、litellm、azure。onyx_embedding_provider资源的作用就是为每一种提供商类型保存一份云端凭据其约束与语义可总结为天然键API 以provider_type作为资源的自然主键因此同一类型的 Provider 全局唯一一次一个一个资源实例只对应一种提供商类型同一类型重复声明会被视为更新而非新建不可直接读取密钥API 在读取GET时会屏蔽api_key因此配置之外发生的密钥变更无法被 Terraform 检测到删除受限当前正在被搜索设置Search Settings使用的提供商无法被删除API 不提供任何强制覆盖手段必须先切换搜索设置。该资源在 Provider 内部的注册与 CRUD 实现位于 embedding_provider_resource.go配套的 API 客户端封装位于 embedding_provider.go下文会结合这两份源码逐步展开。二、最小可运行示例官方 resource.tf 给出了一段极简但完整的声明式配置# 务必在配置中保留 api_keyOnyx API 在更新时会替换全部字段 # 若应用时未携带密钥则会清空服务端已存储的密钥。 resource onyx_embedding_provider cohere { provider_type cohere api_key var.cohere_api_key }其中var.cohere_api_key是你在变量文件或环境变量中传入的敏感值。将上述配置加入你的 Terraform 根模块后执行terraform init terraform plan terraform apply即可在 Onyx 平台创建或更新名为cohere的嵌入提供商凭据。示例中的注释并非可有可无——它揭示了一条核心行为Onyx API 的 Upsert 是全量替换语义任何一次 Apply 都会把请求体中的全部字段写回服务端。三、Schema 全解析该资源共包含 8 个属性按 Required / Optional / Read-Only 分类如下Required必填属性类型说明provider_typeString提供商类型取值限定为openai、cohere、voyage、google、litellm、azure六种之一。修改该字段会触发资源重建RequiresReplace因为它是 API 的自然主键从源码看该字段的取值约束由stringvalidator.OneOf(openai, cohere, voyage, google, litellm, azure)在 Plan 阶段直接校验非法取值会在terraform plan时即报错见 embedding_provider_resource.go同时通过stringplanmodifier.RequiresReplace()保证变更类型时先销毁旧资源再创建新资源避免用错误的键覆盖已有数据。Optional可选属性类型说明api_keyStringSensitive提供商 API 密钥。由于 API 没有保留已存密钥的开关更新请求若未携带该值会直接清空服务端存储的密钥。更推荐使用api_key_wo密钥完全不进 State二者互斥不能同时设置api_key_woStringSensitiveWrite-only只写版本的密钥只存在于 Terraform 配置文件中。每次 Apply 都会发送但 Terraform 不落盘 State密钥永远不会出现在 State 文件中。需搭配api_key_wo_version实现轮换且要求Terraform 1.11 及以上版本api_key_wo_versionNumber与api_key_wo配对的轮换计数器。Terraform 从不存储只写值因此无法感知密钥是否变化手动调大该数字即可让下一次 Apply 重新发送当前配置中的密钥。注意不要用密钥本身派生该数字因为计数器会保存在 State 中而密钥不会api_urlString自定义 API 地址典型场景是 LiteLLM 代理或 Azure 端点api_versionStringAPI 版本号Azure 场景使用deployment_nameString部署名称Azure 场景使用Read-Only只读属性类型说明idString与provider_type完全一致API 的自然键由系统计算并写入api_url、api_version、deployment_name三个字段在请求体中均为可选指针*string未设置时以null形式传输见 embedding_provider.go。id字段使用UseStateForUnknown()修饰资源创建后由plan.ID plan.ProviderType写入见 embedding_provider_resource.go后续 Refresh 保持不变。四、API Key 的三种管理姿势与轮换这是该资源设计上最值得关注的部分涉及密钥不进 State可轮换等安全诉求Provider 提供了两条互补的密钥通道。姿势一api_key——简单直接但会进入 State把密钥直接写在资源块中Terraform 会将其记录在 State 文件中虽然被标记为 Sensitive 并在 CLI 输出中打码但仍以明文存在于本地 state 与远端 backend 中。适合密钥本身已在受管控的变量系统中、且你接受 State 明文存储的团队。姿势二api_key_wo——只写属性密钥永不落盘Terraform 1.11 起支持 Write-only Arguments即文档中所说的 write-only arguments。api_key_wo声明为WriteOnly: true见 embedding_provider_resource.goTerraform 会把它从 Plan 和 State 中一并剥离密钥只存在于配置文件。这是所有场景下的推荐姿势。使用方式resource onyx_embedding_provider cohere { provider_type cohere api_key_wo var.cohere_api_key_wo }姿势三api_key_woapi_key_wo_version——可感知的密钥轮换只写值既然不进 StateTerraform 便无法 diff 出密钥变了单独修改api_key_wo不会产生任何 Plan 差异。为此 Provider 提供了配套的整数计数器api_key_wo_versionresource onyx_embedding_provider cohere { provider_type cohere api_key_wo var.cohere_api_key_wo api_key_wo_version 2 # 轮换密钥时调大该数字 }轮换流程修改api_key_wo中的新密钥 → 同时把api_key_wo_version从 1 调到 2 →terraform apply。计数器的变化产生 Diff触发 Update并把当前配置中的密钥随请求发送给 Onyx。相关实现集中在 write_only.goresolveWriteOnly负责在构造请求体时从配置中提取只写值writeOnlyVersionAttribute负责生成计数器字段并约束其必须与api_key_wo同时出现int64validator.AlsoRequires。两组约束务必牢记api_key与api_key_wo互斥同时设置会直接报校验错误stringvalidator.ConflictsWith当两者都未设置时Provider 在 Update 前会发出警告因为 Onyx API 更新时全量替换字段没有密钥的更新会清空服务端已存密钥见 embedding_provider_resource.go 的AddWarning逻辑。五、底层原理资源生命周期与 API 交互理解 Provider 如何与 Onyx 后端交互有助于预判各种边界行为。客户端 API 封装客户端把CloudEmbeddingProvider结构体镜像后端模型以provider_type为键映射为四个 HTTP 调用见 embedding_provider.go操作方法路径说明Upsert创建/更新PUT/admin/embedding/embedding-provider按provider_type全量 upsert列表GET/admin/embedding/embedding-provider返回全部已配置的云嵌入提供商单查GET/admin/embedding/embedding-provider/{provider_type}注意后端没有 get-by-id 端点客户端实际是拉取全量列表后本地按provider_type匹配未命中则合成一个 404APIError删除DELETE/admin/embedding/embedding-provider/{provider_type}后端无条件拒绝删除当前活跃的提供商资源 CRUD 的关键实现Create从 Plan 构建请求体密钥经resolveWriteOnly解析调用 Upsert成功后把id写为provider_type见 embedding_provider_resource.goRead调用 Get若返回 404 则从 State 中移除资源漂移自愈否则回填provider_type、api_url、api_version、deployment_name。api_key不做回填——因为 GET 返回的是打码值写回 State甚至更糟写回后续的 Upsert 请求体会永久损坏已存密钥。这正是配置是权威、每次更新都重发设计的原因见 embedding_provider_resource.goUpdate同样走 Upsert且从 Plan 而非 State 构建请求体——注释明确说明若把 GET 得到的打码 api_key 写回会破坏已存储的密钥见 embedding_provider_resource.goDelete调用 DELETE若后端返回 400则向用户抛出专门错误Onyx API 拒绝删除当前搜索设置正在使用的嵌入提供商且没有覆盖开关请先把搜索设置切换到其他提供商见 embedding_provider_resource.go。后端 API 佐证上述行为在后端有直接对应实现。Admin API 路由定义于 backend/onyx/server/manage/embedding/api.pyGET /admin/embedding/embedding-provider列出全部提供商GET /admin/embedding/embedding-provider/{provider_type}按类型获取单个提供商DELETE /admin/embedding/embedding-provider/{provider_type}删除前会先调用get_current_db_embedding_provider检查当前活跃提供商若provider_type与活跃提供商一致则拒绝删除PUT /admin/embedding/embedding-provider执行云提供商 Upsert。同时搜索设置模块 backend/onyx/server/manage/search_settings.py 中的get_embedding_provider_from_provider_type展示了后端如何按类型解析嵌入提供商印证了当前活跃提供商这一概念的来源。六、配套数据源onyx_embedding_providers与资源配套的只读数据源onyx_embedding_providers用于枚举当前 Onyx 平台上所有已配置的云嵌入提供商官方用法见>data onyx_embedding_providers all {}数据源 Schema 只有一个只读属性providers对象列表每个对象包含provider_type、api_url、api_version、deployment_name四个只读字段。注意api_key不会被暴露见 embedding_providers_data_source.go与资源读取时屏蔽密钥的行为一致确保了密钥的最小暴露面。典型用法是在模块内引用它做条件化配置例如判断目标类型是否已存在、或把全部提供商类型输出给其他资源引用output configured_embedding_providers { value data.onyx_embedding_providers.all.providers[*].provider_type }数据源通过ListEmbeddingProviders即GET /admin/embedding/embedding-provider拉取数据详细 Schema 见 embedding_providers.md。七、导入已有资源如果 Onyx 平台上已存在手工创建的嵌入提供商可以通过terraform import将其纳入 Terraform 管理官方导入脚本见 import.sh#!/bin/sh # 按提供商类型API 的自然键导入 terraform import onyx_embedding_provider.cohere cohere导入 ID 就是provider_type。ImportState 实现会把它同时写入id与provider_type两个属性见 embedding_provider_resource.go。导入后建议立即执行terraform plan对照你的配置确认api_url、api_version、deployment_name等字段与远端一致。八、最佳实践与常见陷阱综合文档与源码总结以下可直接落地的实践要点优先使用api_key_woapi_key_wo_version密钥不进 State安全性最高轮换时记得同步递增计数器否则 Apply 不会触发密钥重发始终在配置中保留密钥Onyx 的 Upsert 是全量替换任何一次不带密钥的 Apply 都会清空服务端密钥且这种清空不可逆、无告警Provider 只会给出 Warning不会阻断删除活跃提供商前先切换搜索设置Onyx 后端强制拒绝删除当前搜索设置正在使用的提供商报错为 HTTP 400Terraform 会将其包装为明确的诊断信息。正确的操作顺序是先把 Search Settings 指向其他提供商再执行terraform destroy不要把api_key与api_key_wo混用二者互斥混用会直接导致 Plan 校验失败provider_type变更会重建资源由于它是 API 的自然主键Terraform 会先销毁再创建请确认没有其他模块引用旧类型后再修改Read 阶段不回填密钥不要依赖terraform refresh或state show来恢复丢失的密钥配置——远端只返回打码值密钥的唯一权威来源是你的配置文件。结语onyx_embedding_provider是 Onyx Terraform Provider 中一个小而深的资源属性不多却集中体现了密钥安全write-only 机制、API 语义映射全量替换、天然键、活跃保护与 IaC 状态管理导入、漂移自愈、轮换计数器等 Terraform Provider 开发的核心议题。掌握了它的 Schema 语义与底层 API 行为你便能在 Onyx 的嵌入能力自动化管理上少踩坑、更安全——建议在仓库中进一步阅读 embedding_provider_resource.go 与 write_only.go 的完整实现以理解每个属性背后的设计决策。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考