Lặp theo phần tử (For each)

Chạy một nhóm bước con một lần cho mỗi phần tử trong danh sách — song song hoặc tuần tự.

Mục đích

Bước Lặp theo phần tử (For each) cho phép bạn xử lý một danh sách mà không cần thiết kế lại quy trình. Với mỗi phần tử trong danh sách, hệ thống tạo ra một phiên chạy con độc lập để thực hiện toàn bộ nhóm bước bên trong (gọi là "thân vòng lặp"). Các phiên chạy con hoàn toàn tách biệt: mỗi phiên có công việc, ngân sách và dữ liệu riêng.

Bên trong thân vòng lặp, bạn có thể dùng các biến:

input.item — phần tử hiện tại của danh sách.
input.index — chỉ số thứ tự (bắt đầu từ 0) của phần tử đó.

Khi nào dùng

Gửi email thông báo cho từng người trong danh sách người phê duyệt.
Trợ lý AI (Agent) xem xét từng dòng trong đơn đặt hàng và trích xuất thông tin.
Đẩy từng bản ghi từ kết quả tích hợp (Integration) lên hệ thống ngoài.
Yêu cầu xác nhận từng hạng mục mua sắm qua bước Công việc người dùng (Human task) riêng biệt.
Xử lý từng hồ sơ — hoặc từng tệp — trong một thư mục theo dõi (Watched folder), xem mục bên dưới.

Trong ví dụ quy trình Đề xuất mua sắm, bạn có thể thêm bước Lặp theo phần tử (For each) sau bước Trợ lý AI để xử lý từng dòng hàng hóa (nodes.ai-review.output.items) — Trợ lý AI xét duyệt riêng từng mặt hàng, sau đó kết quả tổng hợp được đưa vào bước tiếp theo.

Cài đặt chính

Cài đặt	Mô tả
Danh sách lặp (List to iterate)	Biến mảng từ bước trước hoặc dữ liệu đầu vào của quy trình. Chỉ chọn được biến kiểu mảng (array).
Kiểu thực thi (Execution)	Parallel — các phiên chạy con chạy đồng thời (mặc định). Sequential — chạy lần lượt theo thứ tự danh sách.
Số lượng đồng thời tối đa (Max concurrent)	Chỉ áp dụng khi chọn Parallel. Giới hạn số phiên chạy con hoạt động cùng lúc (từ 1 đến 16, mặc định 5).
Tiếp tục khi một phần tử lỗi (Keep going if an item fails)	Bật (mặc định): một phiên chạy con thất bại được ghi nhận và vòng lặp vẫn chạy tiếp những phần tử còn lại. Tắt: sau lỗi đầu tiên vòng lặp không tạo thêm phiên con nào nữa, chờ các phiên đang chạy kết thúc rồi tổng kết.
Đánh lỗi cả phiên chạy nếu có phần tử lỗi (Fail the run if any item fails)	Bật (mặc định): khi mọi phần tử đã xong, chỉ cần một phần tử lỗi là bước lặp bị coi là lỗi và quy trình cha dừng lại. Tắt: bước lặp vẫn đi tiếp, phần lỗi nằm trong kết quả để bước sau tự xử lý.
Thân vòng lặp (Loop body)	Nhóm các bước được xây dựng trực tiếp trên canvas bên trong khung container. Mỗi bước trong thân vòng lặp đọc được `input.item`, `input.index` và các biến của quy trình cha.

Hai ô đánh dấu về lỗi là độc lập với nhau: ô thứ nhất quyết định có chạy tiếp hay không, ô thứ hai quyết định kết luận cuối cùng sau khi mọi phần tử đã xong. Cả hai đều bật sẵn, nên theo mặc định một phần tử lỗi không chặn các phần tử còn lại, nhưng vẫn làm cả phiên chạy hỏng ở cuối.

Ô Danh sách lặp bắt buộc phải có giá trị. Để trống thì quy trình không Xuất bản được — hệ thống báo bước đó cần một danh sách để lặp.

Thân vòng lặp để trống thì vẫn xuất bản được, và hệ thống không cảnh báo: mỗi phần tử chỉ sinh ra một phiên chạy con không làm gì rồi kết thúc ngay. Hãy tự kiểm lại thân vòng lặp trước khi xuất bản.

Ví dụ

Trong quy trình Đề xuất mua sắm, giả sử Trợ lý AI trả về danh sách các mặt hàng cần duyệt riêng (nodes.ai-review.output.items). Bạn thêm bước Lặp theo phần tử (For each) để xét từng mặt hàng:

Cài đặt	Giá trị
Danh sách lặp	`nodes.ai-review.output.items`
Kiểu thực thi	Parallel
Số lượng đồng thời tối đa	5
Tiếp tục khi một phần tử lỗi	Bật

Bên trong thân vòng lặp:

Bước Trợ lý AI (Agent) — đánh giá mặt hàng dựa trên input.item.name và input.item.price.
Bước Công việc người dùng (Human task) — người phụ trách xác nhận kết quả đánh giá.

Kết quả của bước lặp

Sau khi mọi phiên chạy con kết thúc, các bước tiếp theo của quy trình cha đọc được bốn biến sau — trong trình chọn biến chúng nằm dưới tên bước lặp:

Biến	Nội dung
Items — `nodes.<mã bước>.output.items`	Một mục cho mỗi phần tử, kèm chỉ số thứ tự, trạng thái, và dữ liệu mà phiên chạy con trả về (hoặc thông báo lỗi, nếu phần tử đó hỏng).
Succeeded — `…output.succeeded`	Số phần tử chạy thành công.
Failed — `…output.failed`	Số phần tử thất bại.
Total — `…output.total`	Tổng số phần tử đã chạy.

Với danh sách rất lớn — trên khoảng một nghìn phần tử — Items chỉ giữ lại một phần, ưu tiên đưa các phần tử lỗi lên trước, trong khi Succeeded / Failed / Total luôn đếm đủ. Hãy dựa vào ba con số đó, đừng đếm số dòng trong Items.

Lặp trên một thư mục theo dõi (Watched folder)

Danh sách mà vòng lặp duyệt không nhất thiết phải là kết quả của một bước trước đó. Nếu biểu mẫu bắt đầu có một trường tệp cho phép chọn nhiều tệp, người khởi chạy có thể bấm Dùng thư mục theo dõi thay cho Đính kèm tệp và chỉ định một thư mục theo dõi. Khi đó vòng lặp chạy trên chính nội dung của thư mục ấy — hàng nghìn tài liệu vào quy trình mà không ai phải kéo thả qua trình duyệt.

Có hai cách nối, và mỗi cách cho input.item một dạng dữ liệu khác nhau:

Cách nối	Mỗi phiên chạy con xử lý	`input.item` là
Danh sách lặp trỏ vào kết quả của một bước Gộp tệp (Group files) — biến hiện với tên Folders, đường dẫn `nodes.<mã bước>.output.groups`	một hồ sơ (một thư mục con)	danh sách các tệp của hồ sơ đó
Danh sách lặp trỏ thẳng vào trường tệp của biểu mẫu bắt đầu — đường dẫn `input.<tên trường>`	một tệp	một tài liệu duy nhất

Điều quyết định là có hay không một bước Gộp tệp nằm giữa trường tệp và vòng lặp. Có thì vòng lặp chạy theo hồ sơ; không thì chạy theo từng tệp. Đây không phải một tùy chọn khi khởi chạy — sơ đồ quy trình quyết định, còn màn hình khởi chạy chỉ cho biết kết quả: chạy theo hồ sơ thì hiện số hồ sơ kèm số tệp tương ứng, chạy theo tệp thì hiện số tệp.

Dạng dữ liệu này được chốt lại tại thời điểm phiên chạy bắt đầu. Sửa sơ đồ sau đó không làm đổi dạng dữ liệu của một phiên đang chạy; thay đổi chỉ có hiệu lực với những lần khởi chạy sau.

Chỉ vòng lặp được đọc trường tệp

Ở cả hai cách nối, không bước nào khác được đọc trường tệp — và ở cách thứ nhất, cũng không bước nào khác được đọc kết quả của bước Gộp tệp. Khi trường được trỏ vào một thư mục theo dõi, thứ nó mang không phải một danh sách tệp, nên một bước khác đọc nó — một bước Mã lệnh (Code) phân tích tệp, hay một bước Gửi email (Send email) đính kèm các tệp ấy — sẽ không nhận được gì, mà cũng không báo lỗi. Vì vậy lần khởi chạy với thư mục theo dõi bị từ chối, kèm lời giải thích nêu đích danh bước đó.

Trình thiết kế báo trước điều này ở dải kiểm tra bằng cảnh báo This field cannot come from a watched folder. Cặp nút Dùng thư mục theo dõi vẫn hiện ra trong trường hợp này, nên đừng dựa vào nó để biết sơ đồ đã đúng — hãy nhìn dải kiểm tra. Muốn các bước ấy làm việc với tài liệu, hãy đặt chúng bên trong vòng lặp và cho đọc input.item.

Hai vòng lặp cùng đọc một trường (Two loops iterate the same field), hay hai bước Gộp tệp cùng gộp một trường (Two steps group the same field), cũng bị cảnh báo: mỗi lần chạy chỉ chốt một danh sách cho mỗi trường, nên hãy giữ lại một.

input.item là một danh sách tệp ở cách thứ nhất và một tài liệu đơn ở cách thứ hai, nên các bước trong thân vòng lặp phải được dựng đúng theo cách đang dùng. Thêm hoặc bỏ bước Gộp tệp (Group files) sẽ đổi dạng dữ liệu đó — hãy kiểm lại mọi bước có đọc input.item.

Nếu thư mục theo dõi được cấu hình chờ một tệp báo hoàn tất (ví dụ .done), quy trình bắt buộc phải có bước Gộp tệp. Cho vòng lặp đọc thẳng trường tệp thì lần khởi chạy bị từ chối — tệp báo hoàn tất là lời cam kết về một thư mục, mà chạy từng tệp một thì không có thư mục nào để cam kết.

Cặp nút Đính kèm tệp / Dùng thư mục theo dõi chỉ hiện ra khi ô Danh sách lặp — hoặc ô Tệp cần gộp (Files to group) của bước Gộp tệp — trỏ đúng vào đường dẫn input.<tên trường>. Viết thành {{ input.ho_so }} hay input.ho_so[0] thì không tính, và người khởi chạy sẽ không thấy tùy chọn thư mục theo dõi.

Một lần khởi chạy chốt luôn danh sách hồ sơ mà nó nhận. Tệp thêm vào thư mục sau khi phiên chạy đã bắt đầu không thuộc phiên đó — chúng dành cho lần khởi chạy sau. Ngược lại, một trang được sửa lại sau đó vẫn được đọc ở bản đã sửa: vòng lặp chờ hồ sơ ổn định trở lại rồi mới lấy. Hồ sơ thay đổi liên tục quá lâu sẽ được tính là một phần tử lỗi của vòng lặp, và hai ô đánh dấu về lỗi ở phần Cài đặt chính quyết định điều gì xảy ra tiếp theo.

Xem Gộp tệp (Group files) để biết cách đặt mức thư mục cho một hồ sơ, và Thư mục theo dõi để thiết lập chính thư mục đó.

Xem thêm cách đọc dữ liệu đầu vào tại Bắt đầu (Start) và cách cấu hình Trợ lý AI tại Trợ lý AI (Agent).