> Source: https://clickhouse.github.io/loom/zh-CN/architecture/provider-reconfiguration/ (Markdown: https://clickhouse.github.io/loom/zh-CN/architecture/provider-reconfiguration.md)

<!-- i18n: source=docs/architecture/provider-reconfiguration.md blob=71fa716069549df892dd0ea521757421e0539568 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://clickhouse.github.io/loom/architecture/provider-reconfiguration/)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/architecture/provider-reconfiguration/), which is authoritative.

<a id="provider-reconfiguration"></a>

# Provider 重新配置

Loom 将控制台的模型配置以加密、带版本的行存储在 `loom.provider_configuration` 中。每个配置只有一个已提交的前序版本，过期的保存请求会被拒绝。控制台的覆盖设置优先于服务器启动时的环境变量。重置为环境配置时，恢复的是启动时的快照，而不是重新编辑过的 dotenv 文件。

<a id="activation-and-admission"></a>

## 激活与准入

密钥轮换和仅涉及 LLM 的变更可以在不重建向量的情况下激活。更改 embedding provider、endpoint、model 或 dimensions 会创建一个排队中的转换。该转换不得针对来自先前向量空间的向量激活。

当运行时观察到未完成的转换（包括失败的转换）时，会关闭其本地的模型工作准入闸门。已被准入的工作可以完成；新的数据平面请求会收到可重试的维护响应，worker 轮次会等待，且等待期间不消耗其执行期限。健康检查、模型配置和控制台控制路由仍然可以访问。一个已提交的匹配转换允许重新校准并重新开放准入。之后仅更换密钥的修订版本，可以通过其已提交的前序链满足这一检查。

该闸门只统计单个进程内的工作。它**不是分布式写入屏障**，也不能证明延迟写入或其他副本已经排空。

刷新循环在该闸门之外运行协调器。每个服务器进程和原生数据平面 CLI 命令，在加载已提交的设置或准入工作之前，都会先在 `loom._provider_participants` 中登记。转换要求每个现有参与者在请求、worker 轮次、已注册的有限子任务和缓冲写入都已排空之后，确认同一个配置 ID。新启动的进程在提供服务之前，会加载处于待定状态的已关闭闸门，或加载已提交的替换配置。

每个参与者从自己的线程每 10 s 写入一次自己的行，并且它打开的每个 ClickHouse 客户端都在 User-Agent 中写明其 id。只有在参与者自行退出（正常关闭）、其所在主机上的后续进程证明它已不存在，或运维人员将其退出时，才算该参与者已停止。心跳过期不能作为证明：被暂停的进程可能在 ClickHouse 之外持有已准入的工作，并在恢复后以旧配置写入，因此转换会等待它再次发送心跳并完成排空。每一行都记录其主机名、内核启动标识、容器 id（Docker 的容器 id，或 Kubernetes pod 及容器名称）、pid 命名空间、pid 和启动时间；每个进程每 10 s 会退出同一主机、同一次启动中的参与者，条件是其 pid 已不再运行该进程，或者它曾运行在自己的容器中而该容器已重启进入新的 pid 命名空间，并且它们已没有正在运行的查询。这涵盖了被终止的进程，其容器或 worker 原地重启的情形；共享同一主机名的两个容器（主机网络、同一 pod 的两个容器）不会相互退出对方。确认其进程已不存在的运维人员，可以使用 `loom participant retire --participant <id> --yes` 将其退出，该命令会拒绝处理心跳仍然新鲜或查询仍在运行的参与者。workers leader 的 `/v1/health` 会把转换将要等待的每个参与者列为 `provider_participants_stale`（`heartbeat_expired` 或 `queries_running`）。`system.processes` 通过 `clusterAllReplicas(LOOM_CH_CLUSTER)` 读取；没有该集群的服务器只回答自身的情况，读取发生任何其他失败时，都将该参与者视为仍在运行。

每个有界的重建步骤都持有共享的配置 Keeper 键，该键每 20 s 续期一次（TTL 为 60 s）。只有当持有者对应的参与者被视为已停止时，竞争者才会接管已过期的键；仅仅 TTL 已过不能作为证明。`loom provider-lock clear --holder <holder>` 会释放持有者没有参与者行的键，并在持有者仍在续期、发送心跳或有查询在运行时拒绝执行。启动时的迁移从不在该键下运行：启动过程只在登记之后持有它，用于检查没有未完成的重建，因此在其迁移期间开始的重新配置会等待它。冻结超过 60 s 的参与者可能被视为已停止；它会在下一次心跳时重新登记，并在下一次刷新时关闭其闸门。

第一个协调器检查点会冻结 endpoint/model 标识和有效的已配置前缀宽度。重启不会采用更改后的前缀设置。重建客户端使用带有显式凭据的原始 provider 请求，绕过进程缓存和共享的服务缓存。在失败的批次释放所有权之前，同级请求会先完成取消。激活会清除进程缓存中的向量和旧的已探测宽度，然后再重建服务校准。

<a id="rebuild-staging"></a>

## 重建暂存

重建清单涵盖所有已知的在线向量列。历史向量会被保留；缓存和派生的代码前缀有各自独立的操作。未知的向量表面会导致预检失败，而不会被悄悄遗漏。

已实现的暂存原语要求持有独占的协调器租约，并且写入方已排空：

- 快照阶段的预检会在任何写入之前，按回执、源 schema 和 UUID 对账部分拷贝。未完成的源拷贝可以计入清单，但会被重建，绝不会被当作已完成而接受。没有已完成的匹配源的目标表，以及意外出现的私有表，会使恢复停止。
- 源拷贝保留每一个可写列，并分配稳定的分页序号。完成回执将一次成功的拷贝与其源 UUID 和 schema 指纹绑定。未经确认的拷贝会被重建，而不是依据其行数被接受。
- 以模型为键的替换表，会在旧的 embedding 标签之间，为每个逻辑键选择最高的修订版本。修订版本相同时优先选择墓碑，随后由旧模型标签提供确定性的决胜规则。较晚的活动修订版本会保留显式的恢复。选择时保留被选中的完整行，而不是把各自独立聚合的字段混合在一起。源策略版本是快照指纹的一部分，因此旧回执无法悄悄沿用已变更的方案。
- 快照清理会检查所有权、UUID 和本地查询状态。查询检查必须使用与创建时相同的固定 ClickHouse 节点；它不是整个集群范围的确认。恢复之前必须先隔离旧的协调器。
- 目标表是以源序号为键的私有 `ReplacingMergeTree` 表。重复的批次在 `FINAL` 下只有一个逻辑行。它们的所有权标记将其绑定到某个源快照和 embedding 空间指纹。
- 向量生成使用显式提供的目标 embedder。它在写入前校验完整批次，并且不会更改进程范围的 provider。
- 缓存操作只会使自己拥有的私有缓存目标失效，并验证其为空，不会调用 embedding provider。当模型标签不变时，这也会使旧的、特定于端点的条目失效。在替换缓存发布之前，在用的缓存保持不动。
- Tracker 页面通过命名空间已有的源门控和常规索引方案来填充标题和正文文本。匹配条件包括租户、类型、条目编号、仓库源 ID 和已存储的文本摘要。墓碑无需读取源。若源仍然存在但文本已变化，则用发送给目标 provider 的、经过授权的确切文本来刷新其暂存的文本摘要。所有权和所有其他元数据保持冻结；快照行不变。源缺失或无法访问时，会在调用 provider 或写入暂存之前使该页面停止。快照墓碑绝不会触发源读取或 provider 调用。
- 前缀派生使用已验证的重建后的完整代码向量，在 ClickHouse 内部保留其元数据，并应用常规的前缀归一化规则。稳定的序号用于区分各个已配置的投影。验证会逐标签比较完整的行多重集，而不仅仅是行数。空的冻结前缀策略会清除过时的孪生行。清单会持久化该策略；与之不一致的请求会在更改暂存之前失败。运行时激活会根据已完成的方案重建代码搜索标签和表路由，包括之后的密钥轮换。provider/端点指纹不匹配时，准入保持关闭。若某个已启用的前缀默认宽度已被重建，则保留该宽度；不存在的宽度则被禁用。向量能力缓存会在准入重新开放之前刷新。
- 暂存插入直接在 ClickHouse 内部，从源拷贝中选取未变化的元数据。Python 只传输与 embedding 相关的更新，从而避免元数据往返时的时区重新解释和时间戳精度丢失。
- 验证会检查行覆盖、对空值安全的元数据相等性、模型身份、向量维度、有限且非零的向量，以及墓碑上已清除的向量。缺失或格式错误的验证结果不算成功。
- 验证还会检查最终在线表的排序键。当旧模型的行被改写为同一个模型并发布到替换或聚合引擎时，不同的暂存序号不得被悄悄合并。在选定规范输入之后仍然存在的冲突会使验证失败。

步骤运行器仅在某个效果完成之后才持久化进度。这些效果必须是幂等的，因为进程可能在数据库写入之后、检查点保存之前停止。失败会保留最后的游标，并暴露一个固定的错误码；管理员的重试操作会让同一个转换重新入队。

进度检查点还携带一份带版本的恢复清单，其中包含配置 ID、embedding 空间指纹、冻结的前缀维度，以及有序的完整表清单。缺失的前缀策略不会被解释为空策略；旧版本的清单会以关闭方式失败，而不是沿用运行时默认值。每个条目记录原始的 schema 和 UUID，以及快照和目标的 UUID。验证会补充已准备好的 UUID 和已验证的行数，而不改变这些冻结的身份。运行器在发布之前持久化该清单，并将其传给发布和清理步骤。清单缺失、版本未知、清单不完整以及 UUID 被重复使用，都会以关闭方式失败；恢复不会根据名称推断表的身份。清单只包含元数据，不包含凭据、向量或源内容。

只有当私有拷贝的确切名称和物理 UUID 都与清单匹配时，恢复清单才会将其排除。未知的向量表、其他作业的拷贝以及同名的替换表仍然会使预检失败。未记入日志的拷贝需要先进行回执对账，然后才能执行此检查；仅凭暂存前缀绝不会绕过清单。此清单检查并不能证明所有已记入日志的拷贝仍然存在。

向量补丁以带类型的 JSONEachRow multipart 文件数据传输，而不是单个 HTTP 参数字段。即使 SQL 本身很小，整页大小的数据也可能超过 ClickHouse 的表单字段限制。只有序号和与 embedding 相关的字段会经过这条写入路径；未变化的元数据在 ClickHouse 内部从快照联接而来，保留 DateTime64 精度。上传不会创建持久的补丁表，同步写入保留常规的重试和去重设置。

<a id="publication-primitives"></a>

## 发布原语

候选表准备会把线上表结构克隆到一张私有表中，并且只从已验证的 staging 复制可写列。在记录完成之前，它会在 ClickHouse 内部同时检查逻辑行数和整行多重集相等性，包括 null 和重复计数。恢复一个已完成的候选表时会重复这些检查；仅行数相等并不能证明副本完整。该辅助函数目前只接受本地 MergeTree 引擎：复制引擎和共享引擎需要单独的复制路径方案。

对于带编码的表，准备过程会保留规范 DDL 以及现有的 Quantized 方法和编解码器链，只替换表标识、所有权注释和向量宽度。候选表按服务器接受编解码器设置的方式创建（[受限设置](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#gated-clickhouse-settings)）：如果编解码器无法启用，则在 `CREATE` 之前拒绝（已有的、归属于本任务的过期候选表会先被删除）；如果 `allow_suspicious_codecs` 无法启用，则不带该编解码器链创建。已清除的 staging 向量在这些物理列中会变成定宽的零占位符；维度标志、墓碑标记和其他元数据保持不变。整行校验比较的是这一显式的物理投影，而不是仅比较行数。Rabitq 和 TurboQuant 的宽度必须是 8 的倍数。未知的编解码器参数，以及由操作员创建的向量索引或约束，需要单独的维度方案；准备过程会以失败告终（fail closed），而不会丢弃编解码器或发布不兼容的布局。

发布辅助函数接收持久化的原始表 UUID 和准备好的表 UUID。它先把线上表移到一个归属于本任务的备份名称，再把准备好的表移到线上名称。重试时会通过 UUID 识别之前、中间和已完成这几种状态。它不使用 `EXCHANGE`：共享客户端的自动网络重试可能在响应丢失后重复执行交换，从而意外恢复旧表。

冻结的方案还会记录依赖这些表的显式 TO 物化视图及其替换 UUID。视图 DDL 是加密的，因为操作员编写的定义可能包含机密。在所有替换表都上线之后，发布过程会重新创建这些视图，使后续插入绑定到替换后的源表，而不是它的备份 UUID。丢失 DROP/CREATE 响应时，会依据已记录的标识继续执行；遇到未知标识则中止整个预检。带隐式内部数据的视图不受支持：删除它们会丢弃数据。显式 TO 视图的目标表会被保留，视图重新绑定在备份清理之前完成。发现过程依据源表的 `dependencies_database` 和 `dependencies_table` 数组，而不是它们的异步加载依赖。缺失视图元数据以及跨数据库依赖都会以失败告终。

这些单向重命名会在线上名称处留下一段临时空档。在所有表都发布并验证完成之前，所有读取方和写入方都必须保持排空状态。准备好的表必须已经具有预期的线上表结构、索引和约束；以序号为键的 staging 目标表本身不是可发布的替换表。备份清理和 provider 激活是协调器中单独的步骤。

清理会先对照已记录的替换 UUID 校验每张线上表，然后才删除任何私有副本。它会拒绝未知的或已被替换的副本，并检查本地查询和未完成的 mutation。已记录的快照、目标表和备份会通过可安全重试的 drop 精确删除；副本缺失时，被中断的清理可以继续执行。最后的标识普查必须确认本任务不再有任何残留副本。调用方仍然负责分布式围栏，并在整个过程中保持准入关闭。

<a id="recovery-and-erasure"></a>

## 恢复与擦除

本地运行时在激活前，会等待已准入的请求和已注册的 `TaskSet` 工作完成，然后才更换 embedding 客户端并重新开放准入。该检查不会取消延迟写入。它也不是分布式确认：未注册的任务、缓冲的写入以及服务端查询需要单独进行排空检查，而且仅凭任务完成并不能证明写入已成功。

具体的存储后端将快照清单、按表重建、验证、替换准备、发布和清理与持久化步骤运行器连接起来。它接收显式指定的 embedder、冻结的策略和屏障回调，但自身不会创建协调器租约，也不能证明分布式静默。

引导迁移在提供方配置栅栏的表存在后，与其共用该栅栏。当转换处于待处理状态时，相同 schema 的重启会跳过迁移 DDL；存在待执行迁移的升级必须等待该转换完成。保留策略 DDL 通过模型工作闸门准入，在维护重启时会被跳过。若修改了保留策略的环境变量，请在重建完成后再次重启使其生效。维护期间，MCP 空闲运行清扫不会启动新的摘要工作。

<a id="docker-verification"></a>

## Docker 验证

`scripts/gates/docker_quickstart_smoke.py` 会把生成的发布包安装到一个全新的、用完即弃的 Compose 项目中。它通过默认的生产入口检查控制台加载、记忆、随发布附带的编译器工具链、持久化的编译器结果、重启，以及文档中描述的环境更新/重建路径。

其 provider 阶段使用 Chromium 提交真实的 Models & keys 表单、轮换密钥、更改 embedding 维度、重试失败的重建，并通过确认界面恢复环境配置。它会检查非空的记忆/代码向量与保留下来的元数据、两个 web worker 之间的协调、维护响应、崩溃恢复、容器重建，以及私有重建副本的清除。provider 阶段只在仅用于测试的 Compose 入口中重定向上游 LLM 的 HTTP 端点；embedding 请求使用仅限网络的兼容 provider 测试替身。服务端的校验、授权、加密、协调器和 ClickHouse 存储均保持真实。测试替身的凭据和输出并不能证明可以访问付费 provider，也不能证明模型质量或生产集群的行为。CI 在 amd64 和 arm64 上运行此检查。

本地运行时，先安装前端依赖和 Chromium（`cd frontend && npm ci && npx playwright install chromium`），构建生产镜像，然后使用 `--image <repository:tag>` 运行该检查。它只会删除所生成项目的容器和卷。单元测试使用模拟的存储副作用来演练这套编排，并不覆盖完整的 Docker provider 变更流程。

协调器会推动排队的作业依次经过快照、重建、验证、发布、清理和激活。失败的作业保持关闭状态，直到显式重试；重试时会从其持久化的游标处继续。控制台的进度展示阶段、表和计数器，不会暴露私有的恢复清单或配方。

在转换期间到达的擦除请求，会收到与其他数据平面写入相同的可重试维护响应。此前已启动的分离式擦除 saga 是已登记的有限任务，必须在快照之前完成。残留普查还会检查每一个重建源、目标、已准备的副本和备份。它统计物理行，包括旧的 replacing 版本和墓碑；没有可用范围列的副本会保守地跨所有范围计数。未知的副本或无法读取的计数会导致验证失败，而不会被当作零。副本由重建清理移除，而不会在其冻结的配方之下被编辑。因此，被中断的重建不会让快照游离于擦除统计之外，也不会在副本仍可能恢复该主体数据的情况下报告已删除。

<a id="current-implementation-boundary"></a>

## 当前实现边界

发布目前只支持单个固定 ClickHouse 节点上的本地 MergeTree 引擎。复制/共享引擎的准备工作以及集群范围内的残余查询检查，仍需要各自受支持的方案。因此，只有当任一重建表使用其他引擎，并且任一重新嵌入表中存在数据行时，更改嵌入空间的保存或重置操作才会在转换入队或停止接收写入之前被拒绝，并返回 409。状态响应会在 `embedding_change_blocked` 中给出相同的原因。没有已存储的向量时，无论使用何种存储，都无需重建：该更改直接以 active 状态提交，各进程先排空，再通过各自的配置刷新完成切换。进程在切换之前写入的行仍保留旧模型的向量。Loom 已注册的服务器/CLI 路径之外的直接数据库写入方必须由运维人员停止；对 Loom 进程的统计无法拦截任意的外部 SQL 客户端。若远程参与方丢失且没有死亡证明，这属于明确的恢复边界，不能据此忽略该参与方。完整的 Docker 提供方变更与崩溃恢复 E2E 验证仍是合并的前置条件；单元编排测试和存储层测试并不等同于该流程。
