> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用灰度发布更新推理服务

> 通过灰度发布逐步验证推理服务新版本，控制流量、容量、回滚和旧版本清理。

灰度发布用于对推理服务进行有风险的版本变更，例如更换模型、镜像、启动参数、环境变量或探针配置。灰度过程中，新版本和旧版本并行运行，您可以逐步调整流量或副本，观察新版本表现，再决定全量切换、回滚或清理旧版本。

## 选择发布方式

| 发布方式 | 适合场景                       | 关注点                            |
| ---- | -------------------------- | ------------------------------ |
| 直接发布 | 测试环境，或影响可控的小改动。            | 新版本就绪后承接全部流量，适合低风险变更。          |
| 灰度发布 | 模型、镜像、引擎参数或运行配置变更可能影响线上请求。 | 新旧版本并行运行，逐步放量；灰度未结束前会占用新旧两侧资源。 |

同一个服务同时只能存在一个进行中的灰度流程。灰度全量切到新版本后，仍需要清理旧版本才算结束；清理前可以回滚，清理后不再支持本轮灰度的快速回滚。

## 发起灰度发布

### 1. 发起灰度

在服务列表中，在目标服务的对应操作列中选择 **更新 > 灰度发布**。

<Note>
  服务需要处于 **运行中**，且没有进行中的灰度流程。发起灰度前，建议记录当前模型、镜像、版本、入口、目标副本和业务基线。
</Note>

### 2. 修改新版本配置

在当前服务配置基础上修改本次灰度要验证的内容。

| 可用于灰度的变更                   | 不建议或不支持通过灰度完成的变更                        |
| -------------------------- | --------------------------------------- |
| 模型、镜像、启动参数、环境变量、探针等版本相关配置。 | 资源池迁移、入口或网关配置、执行方式切换、增删角色、直接副本数和自动伸缩配置。 |

如果需要清空已有环境变量、挂载卷或探针配置，不建议通过灰度完成；这类清空操作更适合直接发布，避免灰度配置合并时被识别为未提交字段。

### 3. 选择放量模式

| 模式       | 适合场景                | 使用方式                         |
| -------- | ------------------- | ---------------------------- |
| **简单模式** | 大多数灰度场景，只需要按比例逐步放量。 | 按固定进度推进，通常从小流量开始，观察稳定后再继续放量。 |
| **高级模式** | 需要分别控制流量权重和新版本副本数。  | 可以先起新版本副本、将权重设为 0，验证后再逐步切流。  |

灰度提交后通常不能在同一次流程中切换模式。选择高级模式时，需要同时关注流量权重、新旧版本副本和资源峰值。

### 4. 提交灰度

提交后，进入灰度详情页观察新版本目标副本、就绪副本、事件、日志、监控和本次变更差异。

## 观察和推进灰度

| 操作          | 适用阶段                     | 结果                    |
| ----------- | ------------------------ | --------------------- |
| **调整目标**    | 灰度进行中，需要继续放量、收量或调整新版本容量。 | 平台按目标逐步调整新旧版本流量和副本。   |
| **全部切到新版本** | 新版本已验证稳定，准备承接全部流量。       | 流量切到新版本，旧版本保留用于观察期回退。 |
| **回滚**      | 新版本异常、容量不足或业务指标不符合预期。    | 流量回到旧版本，新版本资源按流程移除。   |
| **清理旧版本**   | 全量发布后，新版本稳定且不再需要快速回退。    | 删除旧版本资源，灰度流程结束。       |

每次调整目标后，等待实例就绪并观察错误率、延迟、业务结果和告警，再继续推进。小样本请求的实际比例可能与配置权重有偏差，应结合总体指标判断。

## 容量策略

灰度发布可能在一段时间内同时保留新旧版本，需要提前评估资源峰值。

| 策略       | 行为                 | 选择建议                   |
| -------- | ------------------ | ---------------------- |
| **先启后停** | 先拉起新版本，再缩减旧版本。     | 优先保证容量不下降，但需要额外临时资源。   |
| **先停后启** | 先释放部分旧版本容量，再拉起新版本。 | 适合配额紧张且可以接受短时间容量下降的场景。 |

如果推进卡住，优先查看灰度详情中的告警、事件和新旧版本就绪副本。常见原因包括资源不足、镜像拉取失败、探针配置不当或新版本启动失败。

## 回滚和清理旧版本

全量切到新版本后，旧版本通常仍会保留一段时间用于快速回滚。此时新旧两侧仍可能占用资源。

* 新版本异常时，确认旧版本容量可承接流量，再执行 **回滚**。
* 新版本稳定后，执行 **清理旧版本** 释放旧版本资源。
* 清理旧版本后，本轮灰度结束，不能再通过当前灰度流程快速回滚。

历史版本回滚只恢复服务版本配置，不恢复数据库或 Volume 数据。涉及持久化写入、外部依赖或数据结构变更时，需要单独规划数据恢复方案。

## 常见问题

<AccordionGroup>
  <Accordion title="为什么灰度期间其他操作被禁用？">
    灰度流程正在管理新旧版本的流量和副本。为避免直接更新、扩缩容、上下线或入口变更覆盖灰度目标，部分操作会被禁用。需要恢复常规操作时，先完成清理旧版本或回滚结束灰度。
  </Accordion>

  <Accordion title="全量发布后为什么还占用旧版本资源？">
    全量发布只把流量切到新版本，旧版本仍保留用于观察期回退。确认新版本稳定后，需要执行 **清理旧版本**。
  </Accordion>

  <Accordion title="灰度推进失败应该先看什么？">
    先查看灰度详情的告警、目标副本和就绪副本，再查看新版本事件和实例日志。资源不足时可降低新版本目标、调整容量策略或回滚。
  </Accordion>
</AccordionGroup>

## 相关文档

* [管理大模型推理服务](./manage-llm-inference-services)
* [管理通用服务](./manage-general-inference-services)