Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

refactor(canvas): preserve parallel item state across resumes (#20440)

Sbaaoui Idriss043d21deca11
diff --git a/internal/agent/canvas/parallel_subgraph.go b/internal/agent/canvas/parallel_subgraph.go
index f018d45da8..9389960361 100644
--- a/internal/agent/canvas/parallel_subgraph.go
+++ b/internal/agent/canvas/parallel_subgraph.go
@@ -41,6 +41,14 @@ type parallelExpansion struct {
OutputRefs map[string]string
}
+type parallelItemState struct {
+ Canvas *runtime.CanvasState
+}
+
+func init() {
+ _ = compose.RegisterSerializableType[parallelItemState]("canvas.parallelItemState")
+}
+
func buildParallelExpansion(ctx context.Context, c *Canvas, parallelID string) (*parallelExpansion, error) {
if c == nil {
return nil, fmt.Errorf("agent: nil canvas")
@@ -139,7 +147,14 @@ func buildParallelItemWorkflow(
return nil, err
}
- wrapper := compose.NewWorkflow[map[string]any, map[string]any]()
+ // Persist the item-local context state alongside Eino's per-item graph
+ // checkpoint; completed body nodes are skipped on resume.
+ wrapper := compose.NewWorkflow[map[string]any, map[string]any](
+ compose.WithGenLocalState(func(ctx context.Context) *parallelItemState {
+ state, _ := GetStateFromContext(ctx)
+ return &parallelItemState{Canvas: state}
+ }),
+ )
inNode := wrapper.AddLambdaNode(
parallelItemInputNodeKey,
@@ -220,6 +235,27 @@ func buildParallelOuterWorkflow(
if maxConcurrency > 0 {
parOpts = append(parOpts, workflowx.WithParallelMaxConcurrency(maxConcurrency))
}
+ parOpts = append(parOpts, workflowx.WithParallelRunOptions(compose.WithStateModifier(
+ func(ctx context.Context, _ compose.NodePath, state any) error {
+ saved, ok := state.(*parallelItemState)
+ if !ok || saved == nil || saved.Canvas == nil {
+ return fmt.Errorf("agent: parallel %q: invalid item checkpoint state %T", key, state)
+ }
+ current, err := GetStateFromContext(ctx)
+ if err != nil || current == nil {
+ return fmt.Errorf("agent: parallel %q: no item state in context", key)
+ }
+ data, err := json.Marshal(saved.Canvas)
+ if err != nil {
+ return fmt.Errorf("agent: parallel %q: marshal item state: %w", key, err)
+ }
+ if err := json.Unmarshal(data, current); err != nil {
+ return fmt.Errorf("agent: parallel %q: restore item state: %w", key, err)
+ }
+ saved.Canvas = current
+ return nil
+ },
+ )))
parOpts = append(parOpts, workflowx.WithParallelContextBuilder(func(
ctx context.Context, item any, index int,
) (context.Context, error) {
diff --git a/internal/agent/canvas/parallel_subgraph_test.go b/internal/agent/canvas/parallel_subgraph_test.go
index 61e6b88191..dabd3e8f00 100644
--- a/internal/agent/canvas/parallel_subgraph_test.go
+++ b/internal/agent/canvas/parallel_subgraph_test.go
@@ -1,39 +1,143 @@
package canvas
import (
+ "context"
"errors"
"strings"
"testing"
-)
+ "time"
-type failingParallelCloneValue struct{}
+ _ "ragflow/internal/agent/component"
-func (failingParallelCloneValue) MarshalJSON() ([]byte, error) {
- return nil, errors.New("clone failure")
-}
+ "github.com/cloudwego/eino/compose"
+)
-func TestParallelCloneFailureStopsItemBeforeInvocation(t *testing.T) {
- c := &Canvas{Components: map[string]CanvasComponent{
- "Message:body": {Obj: CanvasComponentObj{ComponentName: "Message", Params: map[string]any{"content": []any{"done"}}}},
- }}
- sub, err := buildParallelItemWorkflow(t.Context(), c, "parallel", map[string]bool{"Message:body": true})
+func TestParallelResumePreservesProducerState(t *testing.T) {
+ c := &Canvas{
+ Components: map[string]CanvasComponent{
+ "parallel": {Obj: CanvasComponentObj{ComponentName: "Parallel", Params: map[string]any{
+ "items_ref": "sys.items",
+ "outputs": map[string]any{"results": map[string]any{"ref": "consumer@result"}},
+ }}},
+ "producer": {Obj: CanvasComponentObj{ComponentName: "VariableAssigner", Params: map[string]any{
+ "variables": []any{map[string]any{"variable": "env.saved", "operator": "set", "parameter": "prepared"}},
+ }}, Upstream: []string{"parallel"}, Downstream: []string{"input"}},
+ "input": {Obj: CanvasComponentObj{ComponentName: "UserFillUp", Params: map[string]any{
+ "inputs": map[string]any{"value": map[string]any{"type": "line"}},
+ }}, Upstream: []string{"producer"}, Downstream: []string{"consumer"}},
+ "consumer": {Obj: CanvasComponentObj{ComponentName: "StringTransform", Params: map[string]any{
+ "method": "merge", "script": "{{env.saved}}:{{input@value}}", "delimiters": []any{"|"},
+ }}, Upstream: []string{"input"}},
+ },
+ NodeParents: map[string]string{"producer": "parallel", "input": "parallel", "consumer": "parallel"},
+ }
+ store, _ := newTestStore(t, time.Minute)
+ compiled, err := Compile(t.Context(), c, WithCheckPointStore(store))
if err != nil {
- t.Fatal(err)
+ t.Fatalf("Compile: %v", err)
}
- outer, err := buildParallelOuterWorkflow(t.Context(), "parallel", "sys.items", 1, nil, sub)
+ const checkpoint = "parallel-state-regression"
+ events := make(chan RunEvent, 64)
+ newContext := func() context.Context {
+ state := NewCanvasState("run-parallel", "session-parallel")
+ state.Sys["items"] = []any{"one"}
+ return WithRunMeta(WithState(t.Context(), state), &RunMeta{Events: events})
+ }
+ ctx := newContext()
+ _, err = compiled.Workflow.Invoke(ctx, map[string]any{}, compose.WithCheckPointID(checkpoint))
+ if !IsInterruptError(err) {
+ t.Fatalf("first run: want UserFillUp interrupt, got %v", err)
+ }
+ interruptID := FirstInterruptID(ExtractInterruptContexts(err))
+ if interruptID == "" {
+ t.Fatalf("interrupt contexts: %v", ExtractInterruptContexts(err))
+ }
+ resumedCtx := compose.ResumeWithData(newContext(), interruptID, "answer")
+ out, err := compiled.Workflow.Invoke(resumedCtx, map[string]any{}, compose.WithCheckPointID(checkpoint))
if err != nil {
- t.Fatal(err)
+ t.Fatalf("resume: %v", err)
}
- runnable, err := outer.Compile(t.Context())
+ started, _ := collectLifecycleEvents(t, events)
+ if started["producer"] != 1 {
+ t.Fatalf("producer invoked %d times, want once", started["producer"])
+ }
+ parallel, _ := out["parallel"].(map[string]any)
+ result, _ := parallel["results"].([]any)
+ if len(result) != 1 || result[0] != "prepared:answer" {
+ t.Fatalf("results = %#v, want [prepared:answer]", out)
+ }
+}
+
+func TestParallelResumePreservesStateAcrossTwoInterrupts(t *testing.T) {
+ c := &Canvas{
+ Components: map[string]CanvasComponent{
+ "parallel": {Obj: CanvasComponentObj{ComponentName: "Parallel", Params: map[string]any{
+ "items_ref": "sys.items",
+ "outputs": map[string]any{"results": map[string]any{"ref": "consumer@result"}},
+ }}},
+ "producer": {Obj: CanvasComponentObj{ComponentName: "VariableAssigner", Params: map[string]any{
+ "variables": []any{map[string]any{"variable": "env.before", "operator": "set", "parameter": "initial"}},
+ }}, Upstream: []string{"parallel"}, Downstream: []string{"first"}},
+ "first": {Obj: CanvasComponentObj{ComponentName: "UserFillUp", Params: map[string]any{
+ "inputs": map[string]any{"value": map[string]any{"type": "line"}},
+ }}, Upstream: []string{"producer"}, Downstream: []string{"between"}},
+ "between": {Obj: CanvasComponentObj{ComponentName: "VariableAssigner", Params: map[string]any{
+ "variables": []any{map[string]any{"variable": "env.after", "operator": "set", "parameter": "first@value"}},
+ }}, Upstream: []string{"first"}, Downstream: []string{"second"}},
+ "second": {Obj: CanvasComponentObj{ComponentName: "UserFillUp", Params: map[string]any{
+ "inputs": map[string]any{"value": map[string]any{"type": "line"}},
+ }}, Upstream: []string{"between"}, Downstream: []string{"consumer"}},
+ "consumer": {Obj: CanvasComponentObj{ComponentName: "StringTransform", Params: map[string]any{
+ "method": "merge", "script": "{{env.before}}:{{env.after}}:{{second@value}}", "delimiters": []any{"|"},
+ }}, Upstream: []string{"second"}},
+ },
+ NodeParents: map[string]string{
+ "producer": "parallel", "first": "parallel", "between": "parallel", "second": "parallel", "consumer": "parallel",
+ },
+ }
+ store, _ := newTestStore(t, time.Minute)
+ compiled, err := Compile(t.Context(), c, WithCheckPointStore(store))
if err != nil {
- t.Fatal(err)
+ t.Fatalf("Compile: %v", err)
}
- state := NewCanvasState("run", "session")
- state.Sys["items"] = []any{"one"}
- state.Sys["broken"] = failingParallelCloneValue{}
- _, err = runnable.Invoke(withState(t.Context(), state), map[string]any{})
- if err == nil || !strings.Contains(err.Error(), "clone failure") {
- t.Fatalf("Invoke error = %v; want clone failure", err)
+ const checkpoint = "parallel-double-interrupt"
+ events := make(chan RunEvent, 64)
+ newContext := func() context.Context {
+ state := NewCanvasState("run-parallel", "session-parallel")
+ state.Sys["items"] = []any{"one"}
+ return WithRunMeta(WithState(t.Context(), state), &RunMeta{Events: events})
+ }
+ ctx := newContext()
+ _, err = compiled.Workflow.Invoke(ctx, map[string]any{}, compose.WithCheckPointID(checkpoint))
+ if !IsInterruptError(err) {
+ t.Fatalf("first run: want interrupt, got %v", err)
+ }
+ firstID := FirstInterruptID(ExtractInterruptContexts(err))
+ if firstID == "" {
+ t.Fatalf("first interrupt contexts: %v", ExtractInterruptContexts(err))
+ }
+ ctx = compose.ResumeWithData(newContext(), firstID, "answer-one")
+ _, err = compiled.Workflow.Invoke(ctx, map[string]any{}, compose.WithCheckPointID(checkpoint))
+ if !IsInterruptError(err) {
+ t.Fatalf("first resume: want second interrupt, got %v", err)
+ }
+ secondID := FirstInterruptID(ExtractInterruptContexts(err))
+ if secondID == "" {
+ t.Fatalf("second interrupt contexts: %v", ExtractInterruptContexts(err))
+ }
+ ctx = compose.ResumeWithData(newContext(), secondID, "answer-two")
+ out, err := compiled.Workflow.Invoke(ctx, map[string]any{}, compose.WithCheckPointID(checkpoint))
+ if err != nil {
+ t.Fatalf("second resume: %v", err)
+ }
+ started, _ := collectLifecycleEvents(t, events)
+ if started["producer"] != 1 || started["between"] != 1 {
+ t.Fatalf("producer/between runs = %d/%d, want once each", started["producer"], started["between"])
+ }
+ parallel, _ := out["parallel"].(map[string]any)
+ result, _ := parallel["results"].([]any)
+ if len(result) != 1 || result[0] != "initial:answer-one:answer-two" {
+ t.Fatalf("results = %#v, want [initial:answer-one:answer-two]", out)
}
}
@@ -124,3 +228,34 @@ func TestBuildParallelExpansion_PrefersGroupedMembersOverDescendants(t *testing.
t.Fatalf("lines output ref = %q, want StringTransform:FmtItem@result", exp.OutputRefs["lines"])
}
}
+
+type failingParallelCloneValue struct{}
+
+func (failingParallelCloneValue) MarshalJSON() ([]byte, error) {
+ return nil, errors.New("clone failure")
+}
+
+func TestParallelCloneFailureStopsItemBeforeInvocation(t *testing.T) {
+ c := &Canvas{Components: map[string]CanvasComponent{
+ "Message:body": {Obj: CanvasComponentObj{ComponentName: "Message", Params: map[string]any{"content": []any{"done"}}}},
+ }}
+ sub, err := buildParallelItemWorkflow(t.Context(), c, "parallel", map[string]bool{"Message:body": true})
+ if err != nil {
+ t.Fatal(err)
+ }
+ outer, err := buildParallelOuterWorkflow(t.Context(), "parallel", "sys.items", 1, nil, sub)
+ if err != nil {
+ t.Fatal(err)
+ }
+ runnable, err := outer.Compile(t.Context())
+ if err != nil {
+ t.Fatal(err)
+ }
+ state := NewCanvasState("run", "session")
+ state.Sys["items"] = []any{"one"}
+ state.Sys["broken"] = failingParallelCloneValue{}
+ _, err = runnable.Invoke(withState(t.Context(), state), map[string]any{})
+ if err == nil || !strings.Contains(err.Error(), "clone failure") {
+ t.Fatalf("Invoke error = %v; want clone failure", err)
+ }
+}