循环节点用于重复执行一系列任务。 ## 节点说明 循环是一种常见的控制机制，用于重复执行一系列任务，直到满足某个条件为止。扣子工作流提供循环节点，当需要重复执行一些操作，或循环处理一组数据时，可以使用循环节点实现。  例如，以下长文总结场景中，通过循环节点依次生成各个段落，并流式输出每个段落的内容。  ## 循环类型 循环节点的配置方式取决于循环类型。循环类型是循环节点的运行模式，支持设置为使用数组循环、指定循环次数和无限循环。 ### 使用数组循环 **使用数组循环**类似编程语言中的 for 语法结构。遍历循环用于遍历一个已知的序列，对序列中的每个元素执行一系列相同的步骤。遍历循环的典型场景如下： * 长文生成或长文总结：输入每个段落的主题，通过循环节点依次生成各个段落，将完整的文章打包输出。也可以通过消息节点实现每轮循环之后流式输出段落内容。长文总结的原理类似。 * 问卷调查：针对多个产品进行满意度、NPS 等问卷调查，每个产品的问卷题目相同，根据每一轮问题的用户评分算出各个产品的 NPS 得分。 在编程中，数组是一种数据结构，用于存储一系列元素。数组中的基础概念如下： * item：元素，即数组中的单个数据。数组由多个元素组成，每个元素可以是数字、字符、字符串等数据类型。 * index：索引，指数组中元素的位置。索引从 0 开始计数，表示第一次循环，1 表示第二次循环，2 表示第三次循环，以此类推。最后一次循环的索引为 n-1，其中 n 为循环次数。 * 数组长度：数组中元素的数量。 例如，在数组 arrayOfNumbers = [10, 20, 30, 40, 50] 中： * arrayOfNumbers[0] 的 item 是 10，index 是 0。 * arrayOfNumbers[1] 的 item 是 20，index 是 1。 * 数组长度为 5。 使用数组循环时，需要指定**循环数组**，此参数仅支持引用上游节点的输出，且必须为**数组**格式。**使用数组循环**模式下执行循环节点时，循环的次数取决于**循环数组**引用的数组长度。例如数组 [1,2,3,4,5] 的长度为 5，循环节点会循环 5 次完成遍历。如果**循环数组**参数引用了多个数组，则将最短的数组作为循环次数。 使用数组循环时，循环节点会遍历数组中的每个元素，每次循环都会将当前循环到的元素赋值给内置变量。内置变量仅限循环节点内部使用。目前支持的内置变量如下： * item：数组元素，即当前循环到的数组元素。 * index：数组索引，index+1 为当前循环的轮次。 例如在长文总结场景中，引用循环节点数组中的 item，指示模型节点总结 item 中传入的文章段落。  ### 指定循环次数 **指定循环次数**模式通常用于批量、顺序处理数据的场景，需要同时设置**循环次数。**循环次数默认为 10 次，支持设置为 1\~1000 次，你也可以引用上游节点数值类型的输出参数。 **循环次数**参数的引用值如果大于 1000，则设置为 1000，如果小于 1，则设置为 1。 ### 无限循环 **无限循环**类似编程语言中的 while等语法结构，需要通过**终止循环**节点停止循环。循环第一次运行之后，工作流对指定条件进行判断，满足一定条件时则结束循环，否则继续下一次循环。通常是基于循环节点的执行结果进行判断，例如循环调用插件获取数据，当插件执行失败时停止循环，否则持续执行循环只会得到同样的错误结果。 **无限循环**适用于以下场景： * 批量处理数据：例如通过自定义插件调用 API，查看多个用户 ID 的数据，如果插件执行失败，则停止循环。 * 增强搜索：基于第一次检索内容询问用户，收到用户回答后，结合用户问题进行第二次检索，循环执行多次检索，直至符合用户要求。增强检索可提高检索结果的精准度、用户满意度。 * 回合制游戏：游戏通常包含多轮，直到满足胜利条件或游戏结束条件，否则游戏回合反复进行。 **无限循环**需要通过**终止循环**节点停止循环。**终止循环**节点通常和条件判断节点关联使用，条件判断节点判断某个条件成立时，流转到终止循环节点，自动跳出循环。 例如批处理场景中，可以持续调用某个插件，如果插件返回报错，则停止循环。通过选择器节点判断插件的返回数据中是否存在 error\_code，如果 error\_code 不为空，说明插件执行报错，则流转到终止循环节点，主动跳出循环。  ## 配置循环节点 * 多轮循环之间是严格串行执行的，不支持并发执行循环。每个循环迭代完成后，才能启动下一个循环迭代。如需并行执行某些节点，可以使用批处理。 * 不支持嵌套循环，循环节点中不允许添加另一个循环节点，但你可以在循环节点中嵌套一个包含循环节点的工作流。 * 循环节点中不允许添加批处理节点。 ### **设置中间变量** 循环节点支持设置**中间变量**，此变量可作用于每一次循环。**中间变量**通常和循环体中的**设置变量**节点搭配使用，在每次循环结束后为**中间变量**设置一个新的值，并在下次循环中使用新值。 例如在长文生成场景中，通过**中间变量**将每一轮的段落总结作为变量传递到下次循环中，让大模型参考之前的段落内容和下一段的主题，生成一个上下文衔接更流畅的段落。  各个节点配置如下： * **循环节点**：将**中间变量**设置为 last\_paragraph，参数值设置为一个空格。首次循环中生成第一个段落时，不需要参考大纲以外的任何内容，所以将循环变量的值指定为一个空格，你也可以按需设置为其他内容。 * **循环体**中的**设置变量**节点：中间变量选择循环节点中设置的中间变量 last\_paragraph；设置值选择大模型的输出参数 output，表示开始下次循环前，将本次循环中大模型生成的段落赋值给循环变量。 * **循环体**中的**大模型节点**节点：添加 2 个输入参数，分别引用循环节点的内置变量 item 和循环变量，并在提示词中指定生成文章段落时参考上个段落的内容。 在**设置变量**节点中，中间变量的数据类型必须和设置值的数据类型一致，否则无法赋值。 ### 设置循环体 创建循环节点后，会生成一个循环节点和对应的循环体画布。循环体画布是循环节点的内部运行机制，用于编排循环的主逻辑，每个循环迭代中，工作流会依次执行画布内的各个节点。你需要在循环节点和上下游节点之间添加连线，但无需调整循环体和循环节点之间的连线。 选中循环体时，才能向循环体中添加新节点，或拖入新节点至循环体画布。循环体中无需设置开始节点或结束节点，默认按照连接线的箭头方向依次执行各个节点。 * 设置变量节点、继续循环节点和停止循环节点只能在循环体中使用。 * 不支持将循环体外部的节点拖动至循环体内，循环体中的节点也不可移动到循环体之外。 ### 设置输出 循环节点的输出参数可设置为循环体的执行结果集合，表示当数组中所有元素运行完毕之后，将所有循环的运行结果打包输出给下游。也支持设置为循环变量的取值。  ## 调试循环节点 配置循环节点之后，你还需要试运行这个节点，查看其输入输出是否符合预期。调试结束后，循环节点的运行结果中会显示循环节点在多轮循环之后汇总的输入输出内容。循环体中的每个节点也会展示每次循环中的输入输出、变量赋值内容。  ## 常见问题 ### 如何将文本内容转为数组？ 循环节点中的**循环数组**参数必须引用上游节点的输出参数，且参数类型为数组类型。大模型、代码等节点均支持数组格式的输出参数。如果你只能拿到文本格式的内容，可以通过代码节点将文本内容转为数组格式。 例如长文总结场景下，需要通过 LinkReaderPlugin 插件提取 PDF 内容，并将其作为循环节点的循环参数。LinkReaderPlugin 插件的输出参数 pdf\_content 为 String 类型，可以通过代码节点转为数组类型。 ### 如何结束循环？ 循环节点模式不同，结束循环的方式不同。 * 使用数组循环：循环节点依次对数组中的元素执行处理后，自动结束并跳出循环。例如长文生成场景中，上游节点生成一个数组格式的文档大纲，你可以将**循环数组**参数设置为这个数组，循环节点中的大模型节点对数组中每个段落进行扩写，直到所有段落扩写完毕。 * 指定循环次数：循环节点执行指定的次数后会自动终止循环。 * 无限循环：通过**终止循环**节点停止循环。条件判断节点判断某个条件成立时，流转到**终止循环**节点，自动跳出循环。 ### 如何在循环体中插入节点 选中循环体时，才能向循环体中添加新节点，或拖入新节点至循环体画布。不支持将循环体外部的节点拖动至循环体内，循环体中的节点也不可移动到循环体之外。