90 lines
4.2 KiB
Markdown
90 lines
4.2 KiB
Markdown
---
|
||
id: devops.k8s.scenario.agent-rollout
|
||
title: AI Agent 服务上 K8s:发布时流式回答不中断、慢启动、密钥管理和按负载扩容
|
||
type: scenario
|
||
domain: devops
|
||
stack: [k8s, docker, nginx, cicd]
|
||
tags: [滚动更新, 优雅退出, SSE, 探针, HPA, Secret, 回滚]
|
||
level: intermediate
|
||
prerequisites: [devops.k8s.core-objects, devops.docker.image-dockerfile]
|
||
est_hours: 2.5
|
||
related: [devops.k8s.interview, devops.cicd.release-rollback]
|
||
week: [14]
|
||
---
|
||
|
||
# AI Agent 服务上 K8s:发布时流式回答不中断、慢启动、密钥管理和按负载扩容
|
||
|
||
## 业务背景与问题
|
||
|
||
Agent API 从虚拟机迁移到公司的 K8s 集群后:
|
||
|
||
1. 每次发布,正在进行中的流式回答被切断,用户看到“网络错误”;
|
||
2. 新版本启动需要预热(加载提示词模板、建立连接池),偶尔被重启循环;
|
||
3. 有人把模型 API Key 直接写在 Deployment 的环境变量里提交到了仓库;
|
||
4. 高峰期响应变慢,但 CPU 使用率并不高,HPA 没有扩容。
|
||
|
||
## 约束
|
||
|
||
- 集群由平台团队维护,应用团队只能修改自己的清单。
|
||
- 回答可能持续 60 秒以上。
|
||
|
||
## 方案设计
|
||
|
||
1. **优雅退出**:
|
||
- 应用收到 SIGTERM 后:就绪检查立即返回失败、不再接受新请求、等待进行中的流结束(最长 80 秒)后退出;
|
||
- `preStop` 短暂等待,给 Ingress / Service 摘除端点的时间;
|
||
- `terminationGracePeriodSeconds: 90` 大于最长回答时间;
|
||
- 滚动更新 `maxUnavailable: 0`。
|
||
2. **慢启动**:startupProbe 给足启动时间;就绪探针在预热完成后才返回成功。
|
||
3. **密钥**:轮换已泄露的 Key;清单中只引用 Secret;Secret 由密钥管理系统同步(或平台提供的方案);CI 中加密钥扫描。
|
||
4. **扩容指标**:AI 服务主要在等待模型返回,CPU 低但并发连接数高。改用“每个 Pod 的进行中请求数”作为自定义指标(需要平台支持指标适配器),或者先按经验提高副本下限。
|
||
5. **发布与回滚**:镜像固定版本;CI 中先 `kubeconform` + 规范测试;发布后观察错误率和首 token 延迟,异常时 `kubectl rollout undo`。
|
||
|
||
## 关键代码
|
||
|
||
FastAPI 应用的优雅退出(示意):
|
||
|
||
```python
|
||
import asyncio, signal
|
||
|
||
active_streams = 0
|
||
shutting_down = False
|
||
|
||
@app.get("/readyz")
|
||
async def readyz():
|
||
if shutting_down:
|
||
raise HTTPException(503) # 让 K8s 尽快摘除这个 Pod
|
||
return {"ok": True}
|
||
|
||
async def drain(timeout: float = 80):
|
||
global shutting_down
|
||
shutting_down = True
|
||
loop = asyncio.get_running_loop()
|
||
deadline = loop.time() + timeout
|
||
while active_streams > 0 and loop.time() < deadline:
|
||
await asyncio.sleep(0.5) # 等待进行中的流式回答结束
|
||
```
|
||
|
||
(Uvicorn 自身也会在收到 SIGTERM 后停止接收新连接并等待请求完成,具体参数如 `--timeout-graceful-shutdown` 以官方文档为准。)
|
||
|
||
完整清单:[examples/agent-api](../examples/agent-api/)。SSE 在 Nginx 层的配置见 [AI 网关场景](../../nginx/scenarios/ai-gateway-sse-canary.md)。
|
||
|
||
## 取舍
|
||
|
||
| 选择 | 优点 | 缺点 |
|
||
| --- | --- | --- |
|
||
| **优雅退出 + 长宽限期(本方案)** | 用户无感知 | 发布时间变长 |
|
||
| 前端断线自动续传(从断点继续) | 对任何中断都有效 | 后端要保存生成进度,复杂 |
|
||
| 发布时间放在低峰期 | 简单 | 治标不治本 |
|
||
|
||
## 易错点
|
||
|
||
- 宽限期比最长回答时间短,SIGKILL 依然切断。
|
||
- 应用作为 shell 脚本的子进程启动,收不到 SIGTERM(使用 exec 形式的启动命令)。
|
||
- 就绪探针在退出阶段仍然返回成功,新请求继续进来。
|
||
- 以为 Secret 是加密的。
|
||
|
||
## 面试怎么讲
|
||
|
||
> “迁移到 K8s 后发布会切断流式回答。我做了优雅退出:收到 SIGTERM 后就绪探针立即失败,停止接新请求,等进行中的流结束;preStop 留出摘除端点的时间,宽限期设为 90 秒,大于最长回答;滚动更新不减少可用副本。慢启动用 startupProbe。泄露的 Key 立即轮换,清单只引用 Secret,CI 加密钥扫描。扩容方面,AI 服务 CPU 不高但并发高,改用进行中请求数作为指标。”
|