workflow编排教程

模型能跑通 demo，不代表工作流能上线。多数人卡在编排这一段：节点怎么切、失败怎么退、并发怎么控、线上坏了从哪看。这篇不讲协议也不讲客户端配置，只给一套可照着走的搭建顺序，以及每一步对应的判断标准和排查动作；哪些做法不适用，也会一并说清。

模型能跑通 demo，不代表工作流能上线。多数人卡住的不是模型能力，而是编排这一段：节点怎么切、失败怎么退、并发怎么控、线上坏了从哪看。这篇只给一套能照着走的搭建顺序，每一步带判断标准和排查动作，顺带说清哪些做法不适用。

先说前提：这里讲的编排是应用侧的业务流程，不是协议选型，也不是客户端接入配置。如果你还在纠结用哪套协议、哪个 SDK，那是另一件事，跟本文不冲突，先把业务流拆清楚再回头选接入方式反而更快。

第一步：把业务拆成节点，而不是拆成函数

判断一个节点切得对不对，只问一句：这个节点能不能单独重试、能不能单独换模型。如果一次调用里塞了取数、拼提示词、调模型、解析结果四件事，失败之后你既定位不到原因，也没法只重跑其中一环，只能整段重来。

• 取数节点：只负责拿到原始数据，不做清洗也不做判断
• 构造提示词节点：输入是结构化字段，输出是最终发给模型的文本
• 模型调用节点：只负责发和收，不负责解释返回内容
• 结构化解析节点：把模型输出转成程序能用的结构，解析失败要单独标记
• 条件分支节点：写清判定字段是什么、默认走哪条分支
• 落库或回写节点：只负责持久化，不做业务判断

输入字段

这个节点依赖上游给的哪些字段，缺一个就报错而不是静默取空

输出字段

下游能用到的字段清单，改输出等于改接口，要同步改下游

失败归属

失败时算上游的错、本节点的错还是模型的问题，这决定重试和告警挂在哪

第二步：超时、重试与降级，先把失败路径定下来

失败路径要在写主流程之前定好，而不是上线前临时拍。连接超时和整体超时分开设，模型节点通常比取数节点给得更宽；具体分几档，到 /tools/speed-test 量出自己的延迟基线再定，别照抄别人的数值。

1. 先定整体超时给整个工作流设一个总时长上限，超过就中止并记日志，避免请求挂死不放
2. 再定节点超时按节点类型分档，取数节点短、模型节点长，各自独立配置
3. 配置重试策略只对可自愈的错误开重试，退避间隔和次数都做成配置，不要写死在代码里
4. 写降级顺序换备用模型、换简化提示词、降成规则兜底、直接返回暂时处理不了，哪一级能接受要写进需求文档
5. 验证失败路径上线前人为触发一次超时和一次解析失败，确认降级真的走了，而不是只在代码里存在

排查顺序固定下来：先看是超时还是报错码，再看这个节点是否属于可重试类型，最后确认降级分支有没有被真实触发过。很多所谓「偶发失败」，其实是降级代码从来没跑到过。

第三步：并发、排队与成本边界

并发上限取决于你上游的额度口径，不是本地想开多少就开多少。编排层先设一个可调的总闸，再按节点分池，这样任一节点出问题都能单独收紧，不至于整个工作流被限流拖垮。

• 批量任务分批投递，有限并发加失败重投，节奏参数做成配置
• 给一次完整工作流设步数上限或调用次数上限，防止循环分支越跑越深
• 超出上限直接中止并记日志，不要让它悄悄继续耗额度
• 并发参数保留一个实时可调的开关，出问题能马上降下来
• 成本口径统一到同一套计量方式，方便事后对账

哪些情况不适用这套保守策略：内部离线跑批、对延迟不敏感的任务，可以把并发放高，但总闸仍然要留，否则限流会在某个时间点集中爆发，排查起来更麻烦。想做长期观察的话，可以到 /price-watch 看当时的调用口径变化，再决定要不要调整节奏。

第四步：日志、回放与上线前的小评测

编排出问题，十有八九死在日志字段太少。每个节点至少记这几样，缺一项事后复盘就只能靠猜。结构化输出解析失败要单独统计，它是工作流里最常见的静默故障，混在普通报错里根本看不出来。

上线前准备一小批固定输入跑回归，改提示词或换模型之后重跑同一批，对着输出差异看。用例不用多，但每次都得是同一批，否则比不出变化。具体用哪批、覆盖哪些边界情况，参考站内 /guides 里已有的评测方法，不要每次临时现编。

1. 确认是哪个节点按日志里的节点名和错误码缩小范围，不要一上来就怀疑模型
2. 看该节点输入输入摘要是否为空、字段是否齐全，很多时候问题在这
3. 看模型返回返回是报错、超时，还是内容本身不符合预期
4. 看解析结果如果模型返回正常但下游报错，多半是结构化解析这一环

工作流上线前真正该问的不是「模型行不行」，而是「失败的时候它退到哪里」。