Skip to content

SeqChain 串行思维链

SeqChain（SeqChains 类）用于把多个 Chain 或嵌套的 Chains 串联起来执行，前一个链的输出会成为后一个链的输入补充信息，最终以最后一个链的结果作为整体输出。与基础 Chain 相比，它更关注流程编排：将多个具备明确职责的链按照顺序组合，避免在单个链内部写过长的提示词或工具逻辑。

类概览

  • 定义位置：tfrobot.brain.chain.chain_structures.sequence_chains.SeqChains
  • 继承关系：继承自 Chains，沿用 run / async_run 接口
  • 核心能力：顺序调用子链，决定是否共享中间消息
  • 输出规范：output_json_schema 始终对齐最后一个子链的 output_json_schema

配置参数

参数 类型 说明 默认值
name ClassVar[str] 类名常量，用于注册链类型 "SeqChain"
description ClassVar[str] 类描述常量，说明串行链的能力 SeqChain allow multichain work together...
abilities_purpose Optional[str] 描述链的职责与目标，展示给 LLM 作为上下文补充 “当前的思维链是串行链...”
chains list[Chain \| Chains] 串行执行的链条列表，支持继续嵌套 Chains []
pass_intermediate_msgs bool 是否在子链之间共享 intermediate_msgs（即中间系统消息、工具返回等） True

参数细化说明

  1. chains 列表：
  2. 会按照列表顺序依次执行。
  3. 每个子链调用的入参与单独运行时一致：current_input、conversation、elements、knowledge、tools、intermediate_msgs。

  4. 子链既可以是基础 Chain，也可以是其它结构化链（例如再次嵌套 SeqChains）。

  5. pass_intermediate_msgs：

  6. 为 True 时，前一个链生成的 intermediate_msgs 会传递给下一个链，帮助共享工具输出或系统提示。

  7. 为 False 时，每次子链执行完都会把 intermediate_msgs 恢复为初始快照，只让子链影响自身输出，适合希望隔离链间上下文的场景。

  8. abilities_purpose：

  9. 默认描述会列出串行链的基本行为，可在实例化时覆写成更贴近业务的说明，帮助 LLM 理解链路意图。

运行流程

  1. 初始化上下文：
  2. SeqChains._run 会先把会话、元素、知识、工具、中间消息等统一打包成 ChainContext。

  3. 同时创建 ChainResult，用于收集整个串行流程的输出与 Token 统计。

  4. 顺序执行子链：

  5. 依次调用 chain.run(...) 或 chain.async_run(...)，将每次结果累加到同一个 ChainResult 对象中。

  6. 如果开启 pass_intermediate_msgs，后续链可以基于前序链生成的工具输出继续推理。

  7. 中间消息回滚：

  8. 当 pass_intermediate_msgs=False 时，系统会在每个子链执行后把 intermediate_msgs 清空并恢复为初始备份，确保后续链从相同的上下文开始执行。

  9. 结果归并：

  10. 每个子链的 ChainResult 会通过 += 累积到父级结果中。
  11. 最终返回值的结构与最后一个子链保持一致，包括 content、usage、intermediate_msgs 等字段。

Chain 运行结果的缓存与传递

  1. ChainResult 累积策略：
  2. chain_res += chain.run(...) 会调用 ChainResult.__iadd__，合并子链的主体输出（content / origin）、Token 使用量以及中间状态。

  3. 累积后的 chain_res.origin 会记录最新一次子链原始输出；content 则保留最后一个链的标准化结果，便于 SeqChain 直接作为最终返回。

  4. Token 与中间消息：

  5. ChainResult.usage 中的 Token 统计会通过 merge_usages 合并，便于调用方了解整个串行流程的资源开销。

  6. 当 pass_intermediate_msgs=True 时，子链在执行过程中向 intermediate_msgs 追加的工具返回、系统提示会留在列表中，后续子链也能访问；否则会在每次子链结束后恢复为初始快照，避免干扰下一链。

  7. 跨链缓存：

  8. 若子链是 Chain 实例且启用了 catch_intermediate_chain_result，当其 condition_succeed 通过校验后，会把结构化输出写入 current_input.additional_kwargs[_CHAINS_INTERMEDIATE_RESULTS]。这些缓存随着同一个 current_input 在 SeqChain 中流转，使后续子链无需重复调用工具即可读取前序链结果。

  9. 对于字符串输出的子链，可配合 result_cache_key 把文本封装成键值对，同样写入 _CHAINS_INTERMEDIATE_RESULTS，在 SeqChain 内实现显式的数据传递。

  10. 失败场景记录：

  11. 如果某个子链触发 TFChainError 或 TFProtocolError，异常会被立即抛出并终止 SeqChain；当前 chain_res 会保留已完成子链的运行记录，方便上线后排查问题。

使用建议

  1. 拆分长流程：当单个 Chain 的提示词或工具分支过多时，将流程拆成多个职责清晰的子链有助于调试与复用。
  2. 控制上下文污染：若子链之间不需要共享工具输出，可将 pass_intermediate_msgs 置为 False，避免中间消息导致后续链误判上下文状态。
  3. 保持输出一致性：最后一个子链应与整体流程的期望输出保持一致；如需统一结构，可在末尾添加一个专门的汇总链负责格式化。
  4. 错误处理策略：当前设计不会因为某个子链失败自动回滚已完成的链，建议在关键链条中使用 validate_result 或在 Chain 内部自行捕获并修正异常。
  5. 监控 Token：ChainResult 会合并各子链的 Token 使用量，建议结合 Chain 与 LLM 的 max_tokens 设置，避免串行链超出整体预算。

异步支持

SeqChains._async_run 与同步版本逻辑一致，唯一差异是调用 async_run 并在异步环境中执行。若子链内部也采用异步 LLM 或工具调用，优先使用该接口以提升吞吐与响应速度。

与基础 Chain 的关系

  • 上下文复用：SeqChains 与基础 Chain 共用 ChainContext 与 ChainResult 机制，因而可以方便地在串行链内重用已有的 Chain 实例。
  • 组合互补：一个典型模式是先使用基础 Chain 获取结构化信息，再用第二个 Chain 基于该结构化数据生成最终文本。
  • DSL 集成：若结合 TFChainInterpreter 等 DSL 运行器，可以把 SeqChains 注册为脚本中的函数，进一步拓展自动化编排能力。