智能体应用部署前别漏掉这些配置

[示例场景/基准压测演练数据] 在基准压测与云原生环境部署演练中，观察到 Agent Pod 在长文本推理阶段频繁触发 CrashLoopBackOff 循环重启，通过 kubectl get pods 查看提示退出码为 137。调出 kubectl logs -p 审计上一代容器的输出，发现日志停留在 Agent 调起向量数据库进行 Hybrid Search 并等待大模型返回流式 Token 的瞬间。容器内部并未抛出 Python 堆栈异常，而是由操作系统内核或 Kubelet 直接终止进程。这种现象源于直接套用传统 Web 服务的 Helm 部署模板，未能适配 AI Agent 长生命周期与异步推理特征导致的配置冲突。

为什么长文本推理会让 Pod 频繁重启？

传统 Web API 请求的生命周期通常在 200 毫秒以内完成，而 AI Agent 的单次 Task 可能包含多轮 Tool Call、向量检索以及长文本 Chain-of-Thought 推理。单个 HTTP 连接的挂起时间拉长到数十秒甚至数分钟。

当 Kubelet 按照常规配置对 Agent Pod 执行 HTTP livenessProbe 探针测试时，探针发出的 GET/POST 探测请求会排在 Agent 当前处理的单线程 Event Loop 队列后面。Python FastAPI / Uvicorn 服务底层依赖 asyncio 事件循环，如果 Agent 在处理长上下文或执行密集 Token 编排时混入了同步阻塞代码或 CPU 密集型计算，事件循环主线程将被完全锁定。探针发起的 HTTP 探测报文无法在指定的 timeoutSeconds 预算内得到响应。一旦连续超时次数达到 failureThreshold 临界值，Kubelet 会判定容器死锁，发起强行杀进程操作。

另一个导致 137 错误的因素是 Python 进程在加载 PyTorch 或 Tokenizer 时的内存峰值。Agent 服务启动时会将大量词表和 Embeddings 权重载入内存，在处理长文本上下文时，KV Cache 与中间张量会随序列长度线性增长。如果 resources.limits.memory 仅按平时运行时的 2GB 设置，容器在突发并发或解压大文本时就会瞬间触发操作系统 Linux Kernel 的 OOM Killer。在工程实践中，必须将内存分配与 CPU 算力限制进行合理配比，避免资源抢占引发系统级中断。

探针分离与异步健康检查的工程改造方案：

要避免探针误判，应让存活检查足够轻量，且不要在其中访问外部 LLM 或向量数据库。若业务与探针共用同一事件循环，CPU 密集或同步阻塞仍可能让探针超时；应进一步评估多进程、任务隔离或独立健康检查路径。

在 Python FastAPI 框架中实现异步无阻塞健康检查，通过单独的 Background Thread 维护 Pod 内部的指标，避免主线程阻塞导致探针失效：

import time
import threading
from fastapi import FastAPI, Response, status
from pydantic import BaseModel

app = FastAPI(title="Cloud Native Agent Service")

class AgentState:
    def __init__(self):
        self.last_heartbeat = time.time()
        self.is_healthy = True
        self.active_tasks = 0
        self._lock = threading.Lock()

    def update_heartbeat(self):
        with self._lock:
            self.last_heartbeat = time.time()

    def set_unhealthy(self):
        with self._lock:
            self.is_healthy = False

state = AgentState()

# 独立线程守护，监控 Agent 引擎底层指标
def background_checker():
    while True:
        time.sleep(5)
        # 检查内部任务队列是否爆满或死锁
        now = time.time()
        with state._lock:
            if now - state.last_heartbeat > 120 and state.active_tasks > 50:
                state.is_healthy = False

checker_thread = threading.Thread(target=background_checker, daemon=True)
checker_thread.start()

@app.get("/healthz/liveness", status_code=status.HTTP_200_OK)
async def liveness_probe(response: Response):
    """
    Liveness 探针：仅检查进程本身是否存活，绝不上锁或等待模型返回。
    """
    if not state.is_healthy:
        response.status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
        return {"status": "unhealthy", "reason": "background checker flagged worker stall"}
    return {"status": "alive"}

@app.get("/healthz/readiness", status_code=status.HTTP_200_OK)
async def readiness_probe(response: Response):
    """
    Readiness 探针：检查当前 Pod 是否有能力承载新 Request。
    如果并发 Agent 任务达到上限，临时切断流量入口。
    """
    if state.active_tasks >= 20:
        response.status_code = status.HTTP_530_SITE_FROZEN
        return {"status": "busy", "active_tasks": state.active_tasks}
    return {"status": "ready", "active_tasks": state.active_tasks}

Liveness 用于判断进程是否需要重启，Readiness 用于决定是否接收新流量。负载过高时，让 Readiness 失败通常比让 Liveness 失败更合适。文中的 120 秒和 50 个任务只是示例，实际边界需要结合并发模型、排队时长和容量压测确定。

显存与内存双重限制下的 Pod 规约配比指导：

在 Kubernetes 中部署 Agent 编排服务时，YAML 配置必须针对 AI 负载的运行特性进行专门修剪。配置生产就绪的 Deployment 描述文件，重点在于优雅退出超时时间（terminationGracePeriodSeconds）与探针阈值的重调：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-agent-orchestrator
  namespace: ai-platform
  labels:
    app.kubernetes.io/name: agent-orchestrator
spec:
  replicas: 3
  selector:
    matchLabels:
      app: agent-orchestrator
  template:
    metadata:
      labels:
        app: agent-orchestrator
    spec:
      # 给长执行 Task 留足 SIGTERM 信号处理与上下文持久化时间
      terminationGracePeriodSeconds: 120
      containers:
      - name: agent-runner
        image: registry.internal/ai/agent-runner:v1.4.2
        imagePullPolicy: IfNotPresent
        env:
        - name: PYTHONUNBUFFERED
          value: "1"
        - name: MAX_CONCURRENT_TASKS
          value: "20"
        resources:
          requests:
            cpu: "2000m"
            memory: "4Gi"
          limits:
            cpu: "4000m"
            memory: "8Gi"
        livenessProbe:
          httpGet:
            path: /healthz/liveness
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 6
        readinessProbe:
          httpGet:
            path: /healthz/readiness
            port: 8000
          initialDelaySeconds: 15
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 2

在这个 Deployment 规约中，将 terminationGracePeriodSeconds 设置为 120 秒非常关键。当 Agent 正在执行长推理任务时，Kubelet 发出 SIGTERM 信号后，应用程序拥有两分钟缓冲时间将当前 Agent 的上下文状态持久化至 Redis 或数据库中，避免出现客户端连接无故中断的情况。对于 requests 和 limits 的内存配比，基准推荐保持 1:2 的缓冲空间，给长上下文推理过程中的临时张量分配预留足够的安全红线。

命令行排错与运行时配置核验诊断流程：

部署完毕后，应当在真实高并发压测下通过一系列命令行诊断工具抽查 Pod 内部的实际表现，确认配置是否达到设计目标。

使用 kubectl top 观测进程在并发推理时的内存增长趋势：

kubectl top pod -n ai-platform -l app=agent-orchestrator --containers

[示例场景/基准压测演练数据] 内存长期接近 limit 时，应结合工作集、OOM 事件、请求形态和扩容能力评估余量；90% 不是通用的扩容或改规格阈值。

随后，使用命令检查 API 网关（如 Nginx Ingress 或 Envoy）与 Agent Pod 之间的超时配置是否匹配：

kubectl exec -it -n ai-platform deployment/ai-agent-orchestrator -- curl -v http://localhost:8000/healthz/readiness

[示例场景/基准压测演练数据] 如果业务入口网关的 proxy_read_timeout 设置的是 30 秒，而 Agent 执行复杂 Tool 链条需要 45 秒，网关会在中途切断 HTTP 连接返回 504 Gateway Timeout。此时必须修改 Ingress Annotation 延长保持时间：

kubectl annotate ingress agent-gateway -n ai-platform nginx.ingress.kubernetes.io/proxy-read-timeout="180" --overwrite
kubectl annotate ingress agent-gateway -n ai-platform nginx.ingress.kubernetes.io/proxy-send-timeout="180" --overwrite

长任务接口可以按交互需求选择同步、SSE、WebSocket 或异步任务查询。心跳频率、网关超时和空闲连接策略必须与入口代理及客户端能力一致；先通过端到端演练验证取消、重连和资源释放，再固化为配置。