Gộp tệp (Group files)

Gom tệp của một trường tệp thành từng hồ sơ, để bước Lặp theo phần tử chạy một lần cho mỗi hồ sơ thay vì mỗi tệp.

Mục đích

Bước Gộp tệp (Group files) trả lời đúng một câu hỏi: một đơn vị công việc gồm những gì?

Bước này nhận một trường tệp trên biểu mẫu bắt đầu và trả về một danh sách hồ sơ — mỗi hồ sơ là một thư mục con kèm toàn bộ tệp nằm trong đó. Cho một bước Lặp theo phần tử (For each) phía sau đọc kết quả ấy, vòng lặp sẽ chạy một lần cho mỗi hồ sơ, và input.item chính là danh sách tệp của hồ sơ đang xét.

Bản thân bước này rất nhẹ: nó không mở tệp, không tải tệp về, không đọc nội dung. Nó chỉ mô tả cách chia nhóm.

Nếu không có bước này mà cho vòng lặp đọc thẳng trường tệp, quy trình sẽ chạy một lần cho mỗi tệp. Cả hai cách đều hợp lệ — chọn theo nghiệp vụ:

Cách xếp bước	Mỗi phiên chạy con xử lý
Trường tệp → Gộp tệp → Lặp theo phần tử	Một hồ sơ gồm nhiều trang
Trường tệp → Lặp theo phần tử	Một tài liệu đơn lẻ

Khi nào dùng

Tiếp nhận hồ sơ đã quét: mỗi thư mục là một bộ hồ sơ nhiều trang, Trợ lý AI phải đọc cả bộ mới kết luận được.
Bộ chứng từ đi kèm nhau (hợp đồng + phụ lục + biên bản) cần xét chung một lần, không tách rời.
Nguồn tệp là một thư mục theo dõi do bên ngoài đổ vào, mỗi lần một thư mục con.

Không cần bước này khi mỗi tệp tự nó là một tài liệu độc lập — ví dụ mỗi ảnh là một phiếu riêng. Khi đó cho Lặp theo phần tử (For each) đọc thẳng trường tệp là đủ.

Cài đặt chính

Cài đặt	Mô tả
Tệp cần gộp (Files to group)	Trường tệp trên biểu mẫu bắt đầu. Danh sách chỉ hiện các trường kiểu tệp. Người khởi chạy có thể đính kèm tệp thủ công, hoặc — nếu trường cho phép chọn nhiều tệp — trỏ trường đó vào một thư mục theo dõi.
Độ sâu thư mục (Folder depth)	Số cấp thư mục, tính từ thư mục mà trường tệp trỏ tới, để xác định ranh giới một hồ sơ. Nhận giá trị từ 0 đến 10, mặc định là 1.

Kết quả của bước là biến Folders trong trình chọn biến, đường dẫn nodes.<mã bước>.output.groups. Đây chính là biến bạn đưa vào ô Danh sách lặp (List to iterate) của bước Lặp theo phần tử.

Hiểu độ sâu thư mục

Độ sâu được đo từ thư mục mà trường tệp trỏ tới, không phải từ đường dẫn tuyệt đối trên máy chủ. Nhờ vậy cùng một quy trình dùng được cho nhiều đơn vị có cách đặt thư mục gốc khác nhau.

Độ sâu 1 — mỗi thư mục ngay dưới thư mục gốc là một hồ sơ. Đây là cách xếp thông dụng nhất.
Độ sâu 0 — toàn bộ những gì được chọn là một hồ sơ duy nhất.
Độ sâu 2 trở lên — ranh giới hồ sơ lùi xuống thêm một cấp nữa.

Tệp nằm sâu hơn độ sâu đã đặt sẽ được gom ngược lên hồ sơ chứa nó, nên bên gửi vẫn được tự do sắp xếp bên trong một hồ sơ.

Tệp nằm rời ngay ở thư mục gốc thì không thuộc hồ sơ nào và bị loại khỏi lần chạy. Chúng không bị ghép bừa vào hồ sơ bên cạnh: màn hình khởi chạy đếm riêng chúng trong mục Chưa lấy, dưới dạng "N tệp rời, không nằm trong thư mục nào".

Bước này bắt buộc phải chọn được trường tệp. Nếu để trống, quy trình không Xuất bản được — hệ thống báo bước đó cần một trường tệp để gộp.

Độ sâu được đọc tại thời điểm khởi chạy. Sửa độ sâu trên bản nháp không làm thay đổi những phiên chạy đang chạy dở; thay đổi chỉ có hiệu lực với các lần khởi chạy sau khi xuất bản.

Khi trường tệp trỏ vào một thư mục theo dõi, màn hình khởi chạy đọc thư mục ngay lúc đó và cho biết lần chạy sẽ nhận bao nhiêu hồ sơ, trên bao nhiêu tệp — kèm mục Chưa lấy liệt kê những gì bị loại và vì sao. Hãy đọc những con số đó trước khi bắt đầu: đặt sai độ sâu không báo lỗi, nó chỉ tạo ra một lần chạy trông như đã thành công. Xem chi tiết màn hình này ở Bắt đầu (Start).

Khi trường tệp được trỏ vào một thư mục theo dõi, sơ đồ chỉ được có đúng một đường đi từ trường tệp tới vòng lặp: đúng một bước Gộp tệp đọc trường đó, đúng một bước Lặp theo phần tử đọc kết quả gộp, và không bước nào khác đọc trường tệp hay kết quả gộp. Nếu sai — hai bước Gộp tệp cùng đọc một trường (chúng có thể khai hai độ sâu khác nhau), gộp xong mà không bước nào lặp qua, hoặc một bước khác cũng đọc trường đó — lần khởi chạy bị từ chối, kèm lời giải thích nêu đích danh bước gây ra vấn đề. Ràng buộc này chỉ áp dụng cho thư mục theo dõi; đính kèm tệp thủ công thì không.

Bạn không phải đợi tới lúc khởi chạy mới biết: trình thiết kế báo trước ở dải kiểm tra bằng một trong bốn cảnh báo — This field cannot come from a watched folder (một bước khác cũng đọc trường hay kết quả gộp), Two steps group the same field, Two loops iterate the same field, và Nothing runs on these folders (gộp xong mà không vòng lặp nào đọc Folders). Đó là cảnh báo chứ không phải lỗi: quy trình vẫn xuất bản và chạy bình thường với tệp đính kèm thủ công — chỉ riêng thư mục theo dõi là không dùng được.

Ví dụ

Quy trình Tiếp nhận hồ sơ tài liệu: máy quét đổ từng bộ hồ sơ vào một thư mục trên máy chủ, mỗi bộ một thư mục con.

Thư mục theo dõi trỏ vào incoming/HSTL và đang có:

incoming/HSTL/
├── HS-481/
│   ├── trang01.pdf
│   ├── trang02.pdf
│   └── trang03.pdf
├── HS-482/
│   └── ban-scan/
│       └── trang01.pdf
└── ghi-chu.txt

Cách dựng quy trình:

Bắt đầu (Start) — biểu mẫu bắt đầu có một trường tệp cho phép chọn nhiều tệp, ví dụ bo_ho_so.
Gộp tệp (Group files):

Cài đặt Giá trị
Tệp cần gộp input.bo_ho_so
Độ sâu thư mục 1
Lặp theo phần tử (For each) — ô Danh sách lặp chọn biến Folders của bước Gộp tệp.
Trong thân vòng lặp, bước Trợ lý AI (Agent) đính kèm input.item vào lời nhắc để đọc toàn bộ các trang của hồ sơ đó và trích xuất thông tin.

Cài đặt	Giá trị
Tệp cần gộp	`input.bo_ho_so`
Độ sâu thư mục	`1`

Kết quả ở độ sâu 1: 2 hồ sơ. HS-481 có 3 tệp; HS-482 có 1 tệp — ban-scan/trang01.pdf nằm sâu hơn nên được gom ngược lên HS-482. Riêng ghi-chu.txt là tệp rời nên bị loại và được đếm trong mục Chưa lấy.

Nếu đặt độ sâu 0, cả ba đường dẫn trên sẽ trở thành một hồ sơ duy nhất và Trợ lý AI nhận toàn bộ tệp trong một lần chạy — gần như chắc chắn không phải điều bạn muốn ở đây.

Khi trường tệp được đính kèm thủ công lúc khởi chạy (không dùng thư mục theo dõi), mọi tệp vừa tải lên được coi là một hồ sơ duy nhất — vì lúc đó hệ thống chỉ nhận được danh sách tệp, không còn cấu trúc thư mục. Trường chỉ nhận một tệp cũng cho ra một hồ sơ, chứa đúng tệp đó, nên hình dạng dữ liệu đưa vào vòng lặp luôn như nhau. Nếu trường tệp bị bỏ trống, bước này trả về danh sách rỗng và vòng lặp chạy 0 lần, quy trình vẫn đi tiếp bình thường.

Nếu thư mục theo dõi có đặ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. Tệp báo hoàn tất là lời cam kết về một thư mục, nên nó vô nghĩa với cách chạy từng tệp một: gặp trường hợp đó lần khởi chạy bị từ chối, và màn hình nói rõ hai lối ra — hoặc gộp tệp lại thành hồ sơ, hoặc bỏ tệp báo hoàn tất và để hệ thống chờ thư mục ngừng thay đổi.

Xem thêm cách khai báo biểu mẫu bắt đầu tại Bắt đầu (Start), cách cấu hình vòng lặp tại Lặp theo phần tử (For each), cách thiết lập chính thư mục tại Thư mục theo dõi, và cách đính kèm tệp cho mô hình tại Trợ lý AI (Agent).