> ## 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. 配置目标版本

在服务列表中单击 **更新 > 灰度发布**。进入灰度发布页面后，**版本变更** 区域只允许修改与目标版本相关的字段。

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

| 配置区域 | 配置说明 |
| - | - |
| **推理引擎** | 选择目标版本使用的引擎，并按需调整 **引擎参数** 和 **执行方式**。修改后需要确认与模型、角色配置和服务端口兼容。 |
| **角色配置** | 按角色配置 **实例配置**、镜像和 **Command**。多角色服务需要逐个核对各角色的运行配置。 |
| **模型配置** | 选择目标版本使用的模型及版本；如需使用 LoRA 模型，按页面提供的配置项启用。 |
| **服务配置** | 按页面支持的范围配置目标版本的服务参数。 |
| **高级配置** | 配置环境变量和存储挂载。容器本地盘容量有限，需要持久保存或共享的数据应挂载 Volume。 |

页面另有 **灰度发布不可修改** 区域。展开后可查看本次灰度不能变更的字段；需要修改这些字段时，按页面提示使用直接发布或对应的独立运维入口。

### 2. 选择灰度策略

| 模式 | 配置方式 | 适合场景 |
| - | - | - |
| **简单模式** | 设置 **初始灰度比例**。提交后，平台按该比例分配目标版本的初始流量和实例。 | 先使用少量流量验证目标版本。 |
| **自定义模式** | 分别设置旧版本和目标版本的目标实例数。 | 需要独立控制两侧容量。 |

选择容量策略：

* **先启后停**：先启动目标版本实例，再停止旧版本实例。可以降低过渡期容量下降的风险，但需要额外资源。
* **先停后启**：先停止旧版本实例，再启动目标版本实例。适合资源紧张且可以接受过渡期容量变化的场景。

### 3. 预览并启动灰度

在 **灰度预览** 中核对以下信息：

* 旧版本和目标版本的流量比例。
* 两侧目标实例数和实例合计。
* 当前容量策略。

确认资源和流量安排符合预期后，单击 **创建并启动灰度**。

## 验证目标版本

灰度启动后，先确认目标版本可以稳定运行，再继续发布：

1. 查看 **事件** 和 **实例列表**，确认目标实例已就绪且没有持续重启。
2. 查看 **日志**，确认模型加载、推理引擎启动和请求处理正常。
3. 在 **服务网关** 页签确认访问入口，发送最小请求并核对响应内容。
4. 查看资源和引擎监控，确认错误、延迟、吞吐及 GPU、显存等资源表现符合预期。

如果目标版本尚未稳定，不要继续扩大其承载范围。

## 推进灰度

确认目标版本符合预期后，根据验证结果逐步推进灰度。

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

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

## 回滚和清理旧版本

目标版本异常时，在当前灰度流程中使用回滚操作，将流量恢复到旧版本。回滚前，确认旧版本的实例和容量可以继续承接请求。

回滚后，等待服务恢复到 **运行中**，并重新检查 **事件**、**实例列表** 和 **日志**。最后在 **服务网关** 页签确认访问入口，发送最小请求，确认服务已恢复。

全量切换到目标版本后，旧版本仍会保留用于观察期回退，并继续占用相应资源。确认目标版本稳定后，执行 **清理旧版本** 释放资源并结束本轮灰度。清理后，不能再通过当前灰度流程快速回滚。

## 回滚历史版本

历史版本回滚用于恢复曾经正式生效的服务配置，与撤回当前灰度不是同一操作。

1. 在服务的版本历史中选择曾经正式生效的版本，核对模型、推理引擎、镜像、启动命令和相关依赖。
2. 确认当前没有进行中的灰度流程，并确认资源配额、模型和存储权限仍能满足旧版本配置。
3. 按页面提示提交回滚，等待实例更新并就绪。
4. 重新验证访问入口、最小请求和必要依赖。

<Warning>
  历史版本回滚只恢复对应版本的服务配置，不恢复数据库或 Volume 中的数据。未正式生效的灰度目标版本不能作为历史版本回滚点。
</Warning>

## 常见问题

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

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

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

## 相关文档

* [管理大模型推理服务](./manage-llm-inference-services)
* [对大模型推理服务进行功能测试](./test-llm-inference-service-functionality)
* [对大模型推理服务进行性能压测](./load-test-llm-inference-services)