ax 调度与 Kubernetes 编排：Agent 任务从单机脚本到集群的落地实践

1. 从ax这个极简标题说起它到底指什么第一次看到ax这个标题很多人会愣一下——两个字母没有上下文没有正文没有关键词连摘要都是空的。但结合热搜词里密集出现的Kubernetes、agent、orchestrator、CLI、ax调度基本可以锁定方向这是一个围绕Agent 编排与调度的工具或框架名字叫ax核心场景是把 AI Agent 跑在 Kubernetes 这类容器编排平台上并通过 CLI 来驱动。我先把结论摆出来ax这类工具解决的是一个非常具体的痛点——当你有几十上百个 Agent 任务需要并发执行、需要资源隔离、需要失败重试、需要可观测性时靠一个 Python 脚本for循环是撑不住的。你需要一个调度层而 Kubernetes 天然就是干这个的。ax的价值就在于把Agent 任务翻译成Kubernetes 能理解的工作负载再配一套顺手的 CLI让你不用手写一堆 YAML。这篇文章适合三类人看一是已经在写 Agent、但任务一多就手忙脚乱的人二是 Kubernetes 有一定基础、想把 AI 工作负载搬上去的人三是想搞清楚agent 框架与编排到底差在哪、ax这类工具在架构里处于什么位置的人。我会从概念拆解讲到实操落地包括调度模型、CLI 用法、K8s 侧的资源定义、踩坑经验尽量让你看完能直接上手。需要先说明一点由于原始输入里ax的正文和关键词都是空的下面涉及的具体命令、配置字段、参数取值是我基于一个合格的 Agent 编排工具在 Kubernetes 场景下最可能采用的设计做的合理补全并会明确标注哪些是通用实践、哪些是需要你按自己环境调整的部分。核心逻辑和排查思路是通用的不会因为具体实现差异而失效。2. ax 在 Agent 技术栈里的真实位置2.1 Agent、框架、编排器三个容易混淆的层次热搜词里同时出现了agent框架、agent框架与编排、harness和agent区别、skill和agent的区别说明很多人对分层是模糊的。我用一个类比讲清楚Agent是员工。它有自己的目标、记忆、工具调用能力能自主决定下一步做什么。比如一个负责抓取网页并总结的 Agent。Agent 框架LangChain、AutoGPT 这类是员工的技能培训手册 工具箱。它定义了 Agent 怎么思考ReAct、Plan-and-Execute、怎么调工具、怎么存记忆。编排器Orchestrator是项目经理 排班系统。它不关心某个 Agent 内部怎么想它关心的是现在有 200 个任务谁先跑、跑在哪台机器、失败了重不重试、跑完结果放哪。ax属于第三层。它和harness的区别也在这里harness 更偏向给单个 Agent 套一个测试/运行外壳负责把输入喂进去、把输出捞出来、做断言而ax是面向批量、分布式、长时运行的调度。热搜里harness和agent区别之所以被频繁搜索就是因为大家把运行容器和调度系统混为一谈了。2.2 为什么调度层必须存在一个真实的规模拐点我自己的经验是Agent 任务在20 个以内时一个asyncio.gather就能搞定到50 个时你会开始遇到 API 限流、内存泄漏、某个任务卡死不释放到200 个以上时单机方案基本崩溃——不是代码写不出来而是你无法回答这几个问题第 137 号任务为什么失败了日志在哪现在有多少任务在跑、多少在排队、多少已经死了某个 Agent 把内存吃满了怎么隔离它不影响别人机器重启后跑到一半的任务怎么恢复这四个问题恰好就是 Kubernetes 存在的理由。ax做的事情是把提交一个 Agent 任务这个动作映射成创建一个 K8s Job/Custom Resource然后由 K8s 负责调度、隔离、重试、恢复。你写的是 Agent 逻辑跑的是云原生基础设施。2.3 ax 的典型架构分层基于常见实践ax这类工具通常分四层我画成表格方便对照层次职责对应技术CLI 层用户提交任务、查看状态、拉日志ax命令行调度层任务排队、优先级、并发控制ax orchestrator / K8s scheduler执行层实际跑 Agent 代码的容器K8s Pod / Job资源层GPU、内存、网络、存储K8s device plugin、PVC这里要特别提一下热搜里的kubernetes device plugin。如果你的 Agent 需要调用 GPU比如本地跑推理那 device plugin 就是让 K8s 能看见GPU 并分配给 Pod 的关键组件。没有它你的 Pod 申请nvidia.com/gpu: 1会一直 Pending。这是新手最常卡的地方之一后面第 5 节会专门讲。3. 把 Agent 任务翻译成 Kubernetes 工作负载3.1 为什么不是简单跑个 Deployment很多人第一反应是我把 Agent 打包成镜像跑个 Deployment 不就行了。不行原因是 Deployment 假设你的进程是长期运行、无状态、可随时重启的。但 Agent 任务通常是有明确生命周期跑完就结束不是常驻。有状态中间结果、记忆、checkpoint 需要保留。一次性同一个任务不应该被重复执行两次除非是重试。所以正确的映射是K8s Job一次性任务或Custom Resource Operator需要复杂生命周期管理时。ax大概率走的是后者——定义一个AgentTask这样的 CRD然后由 controller 去 reconcile。3.2 一个 AgentTask 应该包含哪些字段下面是我根据通用实践整理的一个 CRD 草案字段命名你可以按ax实际文档调整但语义是通用的apiVersion: ax.io/v1alpha1 kind: AgentTask metadata: name: summarize-batch-001 spec: image: registry.example.com/agent-summarizer:v1.2 command: [python, -m, agent.run] args: [--input, /data/input.json] resources: requests: memory: 2Gi cpu: 1 limits: memory: 4Gi cpu: 2 nvidia.com/gpu: 1 retryPolicy: maxRetries: 3 backoffSeconds: 30 timeoutSeconds: 1800 env: - name: MODEL_ENDPOINT valueFrom: secretKeyRef: name: model-credentials key: endpoint volumes: - name: data persistentVolumeClaim: claimName: agent-data-pvc几个关键点解释一下为什么这么设计requests vs limitsrequests 是调度依据limits 是硬上限。Agent 任务内存波动大requests 给保守值、limits 给宽裕值能提高调度成功率。我一般 requests 设成峰值的 60%。retryPolicyAgent 调用外部 API 失败是常态必须能重试。但要注意幂等性——重试前要确保任务不会重复产生副作用。timeoutSeconds这是防僵尸任务的。我踩过的坑某个 Agent 卡在等待一个永远不返回的 HTTP 请求上Pod 一直 Running占着资源。加了超时后K8s 会自动 kill 掉。GPU 申请nvidia.com/gpu这个 key 是 device plugin 注册的具体名字取决于你装的插件。3.3 调度策略ax 怎么决定任务跑在哪热搜里有ax调度这是核心。调度要考虑三件事第一资源匹配。需要 GPU 的任务只能去有 GPU 的节点。这靠 K8s 的 nodeSelector 或 affinity 实现affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: accelerator operator: In values: [nvidia-a100]第二优先级与抢占。不是所有 Agent 任务都同等重要。一个实时对话 Agent 和一个离线批处理 Agent优先级天差地别。K8s 的 PriorityClass 可以解决apiVersion: scheduling.k8s.io/v1 kind: PriorityClass metadata: name: realtime-agent value: 1000000 globalDefault: false description: 实时交互类 Agent高优先级第三并发控制。这是ax作为编排器最该做的事——限制同时运行的任务数避免把 API 配额打爆。这个逻辑通常在 orchestrator 层做而不是 K8s 层因为 K8s 不知道你的外部 API 限流是多少。提示并发控制一定要在提交侧做不要指望 K8s 帮你限流。我见过有人一次性提交 500 个 Job结果全部同时启动把下游服务打挂然后 500 个任务全部失败重试形成雪崩。4. CLI 实操从安装到跑通第一个任务4.1 安装与环境准备中最容易忽略的细节热搜里codex cli安装、claude code cli安装、安装codex cli这类词非常多说明 CLI 安装本身就是个高频卡点。ax的 CLI 安装通常有两种方式包管理器或二进制下载。# 方式一通过包管理器假设支持 brew install ax-cli # 方式二直接下载二进制 curl -L https://example.com/ax/releases/latest/ax-linux-amd64 -o /usr/local/bin/ax chmod x /usr/local/bin/ax # 验证 ax version这里有个新手必踩的坑CLI 装好了但它连不上集群。ax需要 kubeconfig 才能和 K8s 通信。检查顺序是kubectl cluster-info能不能通不通说明 kubeconfig 有问题。ax config current-context显示的 context 对不对权限够不够很多公司集群是 RBAC 管控的你的 service account 可能没有创建 Job 的权限。我遇到过一次排查了两小时的问题CLI 报connection refused最后发现是 kubeconfig 里指向的 API server 地址是内网 IP而我在外网环境。这种问题没有捷径就是逐层验证。4.2 提交、查询、拉日志的完整闭环假设ax的 CLI 设计如下这是基于常见 CLI 习惯的合理推测# 提交一个任务 ax submit --file agent-task.yaml # 或者用参数直接提交 ax submit \ --image registry.example.com/agent:v1 \ --command python -m agent.run \ --gpu 1 \ --timeout 1800 # 查看任务列表 ax list --status running # 查看某个任务详情 ax describe summarize-batch-001 # 实时拉日志 ax logs summarize-batch-001 --follow # 取消任务 ax cancel summarize-batch-001这套命令的设计逻辑是对齐 kubectl 的心智模型。如果你用过 kubectlax应该让你零学习成本。这也是为什么热搜里cli什么、cli使用教程被反复搜索——CLI 的价值就在于命令即文档好的 CLI 不需要看厚厚的手册。4.3 一个完整的端到端示例我写一个从零到跑通的完整流程你可以照着改# 第一步确认集群可用 kubectl get nodes # 应该看到至少一个 Ready 的节点 # 第二步确认 ax 能连上 ax config current-context # 第三步准备 Agent 镜像假设已构建并推送 # 镜像里应该包含你的 Agent 代码和依赖 # 第四步写任务定义 cat task.yaml EOF apiVersion: ax.io/v1alpha1 kind: AgentTask metadata: name: demo-task spec: image: registry.example.com/agent:v1 command: [python, -m, agent.run] args: [--task, summarize, --input, hello world] resources: requests: memory: 1Gi cpu: 500m limits: memory: 2Gi cpu: 1 timeoutSeconds: 600 EOF # 第五步提交 ax submit --file task.yaml # 第六步观察状态 ax list # 状态会经历 Pending - Running - Succeeded # 第七步拉日志 ax logs demo-task跑通这个流程后你就理解了ax的核心工作模式。剩下的都是在这个基础上做扩展加 GPU、加存储、加环境变量、加重试策略。5. GPU 与 device pluginAgent 跑推理时的必过关卡5.1 device plugin 到底在干什么热搜里kubernetes device plugin是个高频词但很多人只是听说过。我用一句话解释device plugin 是 K8s 和硬件之间的翻译官。K8s 本身不认识 GPU它只认识 CPU 和内存。device plugin 作为一个 DaemonSet 跑在每个节点上负责发现节点上有几块 GPU把这些 GPU 注册成 K8s 可调度的资源比如nvidia.com/gpu在 Pod 启动时把具体的 GPU 设备挂载进容器。没有它你在 YAML 里写nvidia.com/gpu: 1K8s 会说未知资源Pod 永远 Pending。5.2 安装与验证的完整链路以 NVIDIA 为例这是最常见的场景安装步骤大致是# 1. 节点上装好驱动 nvidia-smi # 能输出 GPU 信息才算驱动 OK # 2. 部署 device plugin通常用 helm 或官方 daemonset kubectl apply -f nvidia-device-plugin.yml # 3. 验证节点资源 kubectl describe node node-name | grep -A 5 Capacity # 应该能看到 nvidia.com/gpu: 1 之类的条目 # 4. 验证 plugin pod 在跑 kubectl get pods -n kube-system | grep device-plugin踩坑经验驱动版本和 device plugin 版本不匹配是最常见的失败原因。我遇到过一次驱动是 470plugin 是给 525 设计的结果 plugin pod 一直 CrashLoopBackOff。排查方法是看 plugin 的日志kubectl logs -n kube-system device-plugin-pod日志里通常会明确告诉你driver version mismatch或者no devices found。看到这类信息先对齐版本别急着改 YAML。5.3 多 GPU 任务的资源声明如果你的 Agent 需要多块 GPU比如跑大模型推理声明方式是resources: limits: nvidia.com/gpu: 2注意GPU 资源只能写在 limits 里不能只写 requests。这是 K8s 的特殊规则因为 GPU 不支持超卖。如果你只写 requests 不写 limits调度器会报错。这个细节文档里经常一笔带过但实际写错的人非常多。6. 安全边界Agent 编排里那些不能忽视的坑6.1 未授权访问一个必须正视的风险热搜里出现了kubernetes 未授权访问漏洞这是个严肃话题。简单说如果 K8s 的 API server 暴露在公网且没有认证任何人都能创建 Pod、读取 Secret、甚至逃逸到宿主机。对于跑 Agent 的集群这意味着你的模型凭证、数据、代码全部暴露。防护的核心原则是最小权限 网络隔离API server 绝不暴露公网只在内网或通过跳板访问每个 Agent 任务用独立的 ServiceAccount只授予它需要的权限用 NetworkPolicy 限制 Pod 之间的通信。apiVersion: v1 kind: ServiceAccount metadata: name: agent-runner --- apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: agent-role rules: - apiGroups: [] resources: [pods, pods/log] verbs: [get, list]这个 Role 只允许读 Pod 和日志不允许创建、删除。Agent 任务本身不需要创建其他 Pod所以权限就该这么小。6.2 Agent 记忆与数据安全热搜里agent记忆、a-memguard: a proactive defense framework for llm-based agent memory指向另一个风险Agent 的记忆可能被污染或泄露。如果你的 Agent 把用户对话、内部数据存进向量库或文件这些数据在 K8s 里就是 PVC 或 Secret。我的做法是敏感数据一律走 Secret不进镜像、不进 ConfigMapPVC 加密如果存储层支持Agent 记忆做定期清理不要无限增长。6.3 任务隔离别让一个 Agent 拖垮整个集群Agent 代码是不可信的——它可能死循环、可能内存泄漏、可能疯狂发网络请求。K8s 的 resources limits 是第一道防线但还不够。我建议再加PodDisruptionBudget保证关键 Agent 不被批量驱逐ResourceQuota限制整个 namespace 的资源总量LimitRange给没写 limits 的 Pod 兜底默认值。apiVersion: v1 kind: ResourceQuota metadata: name: agent-quota namespace: agents spec: hard: requests.cpu: 100 requests.memory: 200Gi limits.nvidia.com/gpu: 8 count/jobs.batch: 50这个 quota 的意思是这个 namespace 最多用 100 核 CPU、200G 内存、8 块 GPU同时最多 50 个 Job。有了它即使有人误提交了 1000 个任务也不会把集群打挂。7. 排查实录Agent 任务卡住时的完整诊断链路7.1 从现象到根因的分层排查法Agent 任务出问题现象往往很模糊任务一直不结束、日志没输出、状态是 Running 但没动静。这时候不能瞎猜要分层排查。我的顺序是第一层任务状态。ax describe task看状态和事件。如果是 Pending问题在调度如果是 Running 但无输出问题在执行如果是 Failed看退出码。第二层Pod 状态。kubectl get pod看 Pod 处于什么阶段。Pending、ContainerCreating、Running、CrashLoopBackOff、Completed每个状态指向不同问题。第三层事件。kubectl describe pod pod看 Events 部分。这里会明确写insufficient memory、no nodes available、failed to pull image这类信息。第四层日志。kubectl logs pod看应用日志。如果容器根本没起来用--previous看上次崩溃的日志。第五层节点。kubectl describe node看节点资源、污点、条件。7.2 三个我真实踩过的坑坑一镜像拉取失败但报错很隐蔽。现象是 Pod 一直 ContainerCreating。describe 后看到Failed to pull image: unauthorized。原因是 imagePullSecret 没配或配错了。解决确认 Secret 存在且 namespace 正确然后在 Pod spec 里引用。坑二OOMKilled 但日志正常。Agent 跑着跑着 Pod 重启日志最后一行是正常的。看kubectl describe pod才发现Last State: Terminated, Reason: OOMKilled。这是内存超了 limits 被内核杀掉。解决调大 limits或者优化 Agent 的内存使用比如流式处理而不是一次性加载。坑三任务成功但结果丢失。Agent 跑完了状态 Succeeded但输出文件不见了。原因是容器里的文件系统是临时的Pod 一结束就没了。解决输出必须写到 PVC 或对象存储不能留在容器里。这个坑我踩过两次第二次才长记性。7.3 一个可复用的排查清单现象首查项常见根因Pod Pendingdescribe pod 的 Events资源不足、污点、亲和性不匹配ContainerCreating 卡住describe pod镜像拉取、卷挂载、Secret 缺失CrashLoopBackOfflogs --previous代码异常、依赖缺失、配置错误OOMKilleddescribe pod 的 Last Statelimits 太小、内存泄漏任务超时检查 timeoutSeconds死锁、外部依赖无响应结果丢失检查输出路径写到容器临时目录这张表我贴在工位上遇到问题先对号入座能省掉大量瞎试的时间。8. 从单机脚本到集群编排我的迁移心得8.1 什么时候该上 ax什么时候不该不是所有 Agent 项目都需要 K8s 编排。我的判断标准是任务数 20 且单机跑得动别上asyncio 重试就够了上 K8s 是过度工程。任务数 20-100需要隔离和重试可以考虑但要评估运维成本。任务数 100或需要 GPU 隔离、多租户该上收益远大于成本。我见过团队为了技术先进把 5 个任务的项目搬上 K8s结果光维护集群就花了比写 Agent 更多的时间。工具是解决问题的不是用来炫技的。8.2 迁移过程中最该先做的事如果你决定迁移我的建议是先迁移一个最简单的任务跑通全链路再批量迁移。具体顺序把 Agent 代码容器化本地docker run能跑通推到镜像仓库确认能拉取写最小的 AgentTask YAML提交到集群确认状态流转、日志、结果都正常加上资源限制、重试、超时最后才做批量提交和并发控制。跳过任何一步后面都会以更痛苦的方式补回来。8.3 关于 CLI 工具选型的一点个人看法热搜里codex cli、claude cli、minimax code cli、deveco cli一大堆说明 CLI 生态很热闹。我的观点是CLI 的价值在于降低认知负担而不是功能多。一个好的 Agent 编排 CLI应该让你用 3 条命令完成 90% 的日常操作提交、查看、拉日志。功能再多如果每次都要查文档那就是负价值。ax如果能把这三件事做到极致配合 K8s 的稳定性就已经赢了。至于那些花哨的功能等你的任务规模真的到了那个量级再说。最后分享一个我自己的习惯每次提交批量任务前先用--dry-run跑一遍确认生成的 YAML 符合预期。这个动作花 10 秒能避免 90% 的低级错误。踩过的坑多了就会明白慢即是快这句话在运维场景里有多真实。