Kotaemon就绪探针与存活探针配置（K8s环境）

Kotaemon就绪探针与存活探针配置（K8s环境）

在构建企业级AI智能体系统时，一个常被忽视的问题是：即使模型推理准确、功能完整，服务仍可能因为“刚启动就接流量”或“卡住却不重启”而频繁报错。尤其像Kotaemon这类依赖大型语言模型加载和复杂插件初始化的RAG框架，在Kubernetes中部署时，若缺乏合理的健康检查机制，用户体验很容易大打折扣。

我们曾遇到这样一个场景：某客户上线智能客服后，前几轮对话总是超时失败。排查发现，并非代码逻辑问题，而是Pod刚启动就被注入了用户请求——此时LLM尚未加载完毕，向量库连接也未建立。更糟的是，某次高并发下服务出现死锁，进程仍在运行但不再响应任何请求，监控却显示“一切正常”，直到人工介入才发现异常。

这正是Kubernetes中就绪探针（Readiness Probe）和存活探针（Liveness Probe）要解决的核心问题。它们虽只是YAML中的几行配置，却是保障AI服务稳定性的隐形防线。

探针的本质：让系统学会“判断状态”而非“盲目转发”

很多人把探针当成简单的“ping一下看通不通”，但实际上，它的设计哲学在于精细化状态管理。

就绪探针不是问“你活着吗？”，而是问“你现在能干活吗？”
存活探针也不是问“你能处理请求吗？”，而是问“你还清醒吗？”

这种区分看似细微，但在Kotaemon这类组件异步初始化、长期运行易积压任务的系统中，至关重要。

举个例子：

• 当Kotaemon启动时，它需要：
• 加载数GB的HuggingFace模型；
• 连接Chroma或FAISS向量数据库；
• 注册多个工具插件（如搜索、计算器、API调用）；
• 构建内部缓存结构。

这个过程可能耗时数十秒甚至上百秒。如果此时就有流量涌入，轻则返回空结果，重则触发OOM崩溃。

而另一方面，一旦服务进入运行期，Python的GIL竞争、异步协程阻塞、第三方API无响应等问题可能导致主线程“假死”——进程没退出，但再也无法处理新请求。传统的进程心跳检测对此无能为力，但存活探针可以。

就绪探针：别急着接活，先让自己准备好

就绪探针的作用很简单：控制流量入口。

只有当Pod通过就绪探测，才会被加入Service的Endpoint列表，进而接收来自Ingress或kube-proxy的请求。否则，哪怕容器已经运行，也不会分到哪怕一个请求。

这意味着你可以从容地完成初始化工作，而不必担心“边开工边装修”。

实践建议

readinessProbe: httpGet: path: /health/ready port: 8000 scheme: HTTP initialDelaySeconds: 60 periodSeconds: 10 timeoutSeconds: 5 successThreshold: 1 failureThreshold: 3

关键参数解读：

• initialDelaySeconds: 60：给足时间加载模型。建议基于实测P99启动时间设置，再加20%冗余。例如实测最长需75秒，则设为90秒更稳妥。
• periodSeconds: 10：太频繁会增加系统负担，太稀疏则反应迟钝。10秒是一个平衡点。
• timeoutSeconds: 5：避免在网络抖动或GC暂停期间误判为失败。
• successThreshold: 1：只要一次成功就标记为就绪，尽快接入流量。
• failureThreshold: 3：连续三次失败才移除，防止短暂波动造成服务震荡。

📌 特别提醒：/health/ready接口必须真实反映服务能力。不能简单返回200，而应检查以下状态：
- LLM引擎是否已加载并可生成文本；
- 向量数据库客户端是否连通且能执行查询；
- 所有必需插件是否注册完成；
- 内部状态机是否处于ACTIVE状态。

示例实现（FastAPI风格）：

from fastapi import FastAPI import time from kotaemon.core.status import ( is_llm_ready, is_vector_store_connected, are_plugins_registered ) app = FastAPI() @app.get("/health/ready") def readiness_check(): checks = { "llm": is_llm_ready(), "vector_store": is_vector_store_connected(), "plugins": are_plugins_registered() } if all(checks.values()): return {"status": "ready", "timestamp": time.time()} else: return { "status": "not ready", "details": checks }, 503

这样做的好处是，运维人员可以通过日志或直接访问该端点快速定位哪个环节卡住了。

存活探针：当你“晕过去”时，让我来帮你重启

如果说就绪探针是为了防止“过早使用”，那存活探针就是为了应对“长期失能”。

它的逻辑更粗暴：探测失败 → 重启容器。

但这恰恰是必要的。因为在某些情况下，应用进程并未退出，但实际已无法提供服务。比如：

• 异步事件循环被长时间阻塞；
• 线程池耗尽且无超时回收机制；
• 死锁导致主处理函数无法返回；
• 内存泄漏缓慢积累，最终导致响应极慢。

这些情况很难通过业务逻辑自动恢复，而人工干预又不现实。此时，存活探针就成了最后的“急救按钮”。

配置要点

livenessProbe: httpGet: path: /health/live port: 8000 scheme: HTTP initialDelaySeconds: 120 periodSeconds: 30 timeoutSeconds: 5 successThreshold: 1 failureThreshold: 3

注意几个细节：

• initialDelaySeconds必须大于最大预期启动时间。因为冷启动阶段本身就可能较慢，过早探测会导致不必要的重启。
• /health/live接口应尽可能轻量。理想情况下，它只验证主进程是否还能响应HTTP请求即可，不应检查外部依赖。

为什么？

设想你的向量数据库临时网络抖动，如果/health/live也依赖它，就会导致整个Pod被重启——而这完全没必要。毕竟，数据库恢复后服务本可自行恢复，但重启反而会造成更大中断。

正确的做法是：/health/live仅用于判断进程是否“还醒着”。只要主线程能响应，就不该重启。

@app.get("/health/live") def liveness_check(): # 只做最基础的响应测试 return {"status": "alive", "pid": os.getpid()}

这个接口甚至不需要查内存、不跑SQL、不调模型，就是“我能回你一句话”就够了。

协同工作：双探针如何构筑稳定防线

两者分工明确，共同构建起两层防护网：

在一个典型的滚动更新过程中，它们协同工作的流程如下：

1. 新Pod启动，旧Pod继续服务；
2. Kubelet开始执行探针：
   - 就绪探针等待60秒后开始探测；
   - 存活探针等待120秒后开始探测；
3. 当新Pod的/health/ready返回200，K8s将其加入负载均衡；
4. 更新策略逐步将旧Pod缩容，确保始终有足够副本在线；
5. 若某次GC停顿导致存活探针连续三次超时，立即触发重启；
6. Ingress自动将后续请求路由至其他健康实例，用户几乎无感。

这种机制不仅提升了SLA，也让CI/CD发布更加安全和平滑。

常见陷阱与最佳实践

尽管探针机制强大，但如果配置不当，反而会引入新的风险。

❌ 错误1：initialDelaySeconds设置过短

很多团队直接设为10秒，结果模型还没加载完就开始探测，导致反复失败又被踢出集群，形成“启动-失败-重启”的恶性循环。

✅建议：通过压测获取P99启动时间，再乘以1.2~1.5作为初始延迟值。例如平均启动70秒，P99为90秒，则设为110~120秒。

❌ 错误2：两个探针共用同一个路径

有人图省事，让/health/ready和/health/live指向同一接口。这等于把“能不能干活”和“还活着吗”混为一谈。

后果可能是：一次数据库抖动导致所有实例同时被判定为“死亡”，集体重启，引发雪崩。

✅建议：严格分离职责：
-/health/ready：可包含依赖检查；
-/health/live：仅检查进程可达性。

❌ 错误3：超时时间设得太短

设为1秒听起来很灵敏，但在高负载、频繁GC的Python服务中，偶尔一次请求超过1秒很正常。如果因此触发重启，得不偿失。

✅建议：timeoutSeconds至少设为3~5秒，failureThreshold设为3，允许一定程度的波动。

✅ 其他推荐实践

总结：小配置，大价值

在云原生时代，稳定性不再只是“服务器别宕机”，而是“服务始终可用”。

对于Kotaemon这样的AI智能体框架，其价值不仅体现在算法能力上，更体现在能否持续、可靠地交付高质量响应。而就绪探针与存活探针，正是实现这一目标的关键基础设施。

它们虽只是YAML中的几行配置，却承载着自动化运维的核心思想：
让系统自己判断状态，而不是靠人盯着日志去救火。

合理配置这两个探针，意味着：

• 用户不会再遇到“第一次提问总失败”的尴尬；
• 运维团队不必半夜被“服务无响应”告警惊醒；
• 滚动更新可以真正实现“零感知”；
• 整体SLA从99.5%迈向99.9%+成为可能。

所以，下次当你准备上线一个新的RAG应用时，别忘了问问自己：我的Pod，真的“准备好了”吗？