Thư chào mừng cho bốn mươi khách hàng mới, một chứng chỉ cho mỗi người tham dự, một hoá đơn cho mỗi đơn hàng: cùng một tài liệu, mỗi lần một bản ghi khác nhau. Với GroupDocs.Assembly.Mcp chạy cục bộ (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor hoặc Copilot thực hiện nó bằng một lời gọi công cụ, assemble_per_record, công cụ này điền mẫu Word của bạn một lần cho mỗi phần tử của một mảng JSON, lưu mỗi kết quả dưới dạng PDF riêng được đặt tên theo một trường bạn chọn, và báo cáo các bản ghi thất bại thay vì dừng lại ở bản ghi đầu tiên:

Tạo PDF thư chào mừng cho mỗi khách hàng trong customers.json bằng cách sử dụng welcome-letter.docx, và đặt tên mỗi tệp theo tên khách hàng.

Phiên bản hướng dẫn từng bước với cấu hình và khắc phục sự cố có trong tài liệu: Cách tạo một tài liệu cho mỗi bản ghi (mail merge) với một AI agent.

Tại sao không để agent lặp lại?

Nó có thể, và với năm bản ghi thì ổn. Nhưng một vòng lặp gồm bốn mươi lời gọi công cụ là bốn mươi cơ hội để agent mất đếm, bỏ qua một bản ghi khi ngữ cảnh trở dài, hoặc “hữu ích” thay đổi cách diễn đạt một lá thư. Một công cụ per‑record đưa vòng lặp vào server: một lời gọi, một mẫu, một lần duyệt mảng, và một báo cáo cho biết chính xác có bao nhiêu tệp đã được ghi và bản ghi nào không thành công. Công việc của agent là chọn mẫu, tệp dữ liệu và trường đặt tên, sau đó đọc báo cáo trả lại cho bạn.

Agent kiểm tra gì đầu tiên?

Hai điều: dữ liệu trông như thế nào, và mẫu đọc gì. Trong thử nghiệm của chúng tôi, năm khách hàng trong customers.json và một lá thư chào mừng một trang:

-> get_document_info {"file":{"filePath":"customers.json"}}
<- { "dataKind": "json",
     "data": { "root": "array", "length": 5, "keys": null } }

-> get_template_fields {"template":{"filePath":"welcome-letter.docx"}}
<- { "dataSourceNames": [ "customer" ],
     "fields": [ "customer.Contact", "customer.Plan", "customer.Name",
                 "customer.Manager", "customer.FirstInvoice" ] }

Mẫu gọi một bản ghi là customer; server tự xác định điều này, vì vậy agent không cần truyền dataSourceName.

Một lời gọi, năm bản ghi, một lỗi

-> assemble_per_record {"template":{"filePath":"welcome-letter.docx"},
     "data":{"filePath":"customers.json"},"fileNameField":"Name",
     "format":"pdf"}
<- Assembled 4 of 5 document(s) from 'welcome-letter.docx' with
   'customers.json', one per record (each record as 'customer'), as PDF.
   Saved to:
   .../Contoso Pharma.pdf
   .../Fabrikam Logistics.pdf
   .../Tailspin Toys.pdf
   .../Litware Labs.pdf
   1 record(s) failed:
   record 4: InvalidOperationException: ... Can not get the value of
   member 'FirstInvoice' on type 'System.Data.DataRow'. The template
   reads 'FirstInvoice', which the data does not have. ...

Bản ghi 4, Wingtip Travel, không có ngày hoá đơn đầu tiên trong dữ liệu. Bốn lá thư còn lại đã được ghi, mỗi lá đặt tên theo khách hàng, và lỗi được trả về kèm số bản ghi và trường bị thiếu. Agent sẽ báo cáo như sau: “bốn lá thư đã xong; Wingtip Travel không có ngày hoá đơn đầu tiên, bạn muốn tôi để trống dòng này hay chờ ngày?”. Đó là cuộc trò chuyện bạn muốn, thay vì bốn mươi tệp mà không biết tệp nào sai.

Cách hoạt động của fan‑out

customers.json  [ {Name:"Contoso Pharma",...}, {Name:"Fabrikam ..."},
                  ... 5 records ]
        |
assemble_per_record {"template":{"filePath":"welcome-letter.docx"},
                     "data":{"filePath":"customers.json"},
                     "fileNameField":"Name","format":"pdf"}
        |
        +--> Contoso Pharma.pdf
        +--> Fabrikam Logistics.pdf     ... 2 more
        '--> "4 of 5 ... 1 record(s) failed: record 4 ..."

Ba tham số thực hiện công việc. fileNameField đặt tên mỗi đầu ra bằng một trường của bản ghi: ở đây là Name, hoặc một đường dẫn dạng chấm như order.Number khi mỗi bản ghi lồng một đối tượng. Đối với các bản ghi phẳng này, customer.Name sẽ thất bại cho tất cả (“bản ghi không có trường ‘customer.Name’ để đặt tên tệp”). Nếu không có tham số này, các tệp sẽ nhận số thứ tự, và một tên đã tồn tại sẽ không bị ghi đè: tệp mới sẽ có (1). recordsPath chỉ tới mảng khi JSON là một đối tượng chứa mảng, chẳng hạn "customers" hoặc "batch.items". Và maxDocuments là bộ phanh.

Điều gì ngăn chặn một batch chạy quá mức?

maxDocuments, mặc định là 100 và có thể lên tới 1000. Trước khi ghi bất kỳ thứ gì, server đếm số bản ghi; nếu vượt quá giới hạn, nó sẽ từ chối. Chúng tôi đặt nó thành 3 cho năm khách hàng của mình:

-> assemble_per_record {..., "maxDocuments":3}
<- Per-record assembly failed for 'welcome-letter.docx': there are 5
   records, more than maxDocuments=3. Raise 'maxDocuments' (up to 1000)
   or pass fewer records.

Không có gì được ghi. Đối với một chiến dịch gửi thư tới người thật, đây là mặc định hợp lý: một lời nhắc nhở khi vô tình trỏ tới toàn bộ xuất khẩu CRM sẽ nhận được câu hỏi trả lại, chứ không phải mười ngàn PDF.

Dữ liệu của tôi là bảng tính, không phải JSON

Việc tạo per‑record chỉ đọc JSON: một mảng các đối tượng, hoặc một đối tượng chứa một mảng. Khi danh sách nằm trong CSV hoặc bảng tính, agent sẽ chuyển các hàng sang JSON trước, việc mà các agent thực hiện tốt, và ghi tệp vào thư mục lưu trữ. Nếu bạn muốn một tài liệu liệt kê mọi hàng, như bảng giá hoặc sổ đăng ký, thì dùng assemble_document với <<foreach>> trong mẫu, và nó sẽ đọc trực tiếp CSV và bảng tính.

Giới hạn thực tế

  • Việc lắp ráp per‑record chỉ đọc JSON; dữ liệu CSV và bảng tính cần được chuyển đổi trước.
  • Chế độ Evaluation: mỗi tệp được tạo sẽ bắt đầu bằng “Evaluation Only. Created with GroupDocs.Assembly 26.7…”, và các mẫu email chỉ giữ phần thân văn bản thuần. Hãy cấp phép cho server trước khi thực hiện chiến dịch thực tế.
  • Trường bị thiếu sẽ làm bản ghi đó lỗi. allowMissingMembers: true sẽ ghi nó với dòng trống thay vì lỗi; bạn quyết định muốn cách nào.
  • Ngày: ghi dưới dạng 2026-12-01T00:00:00 và định dạng trong mẫu, như lá thư của chúng tôi dùng <<[customer.FirstInvoice]:"d MMMM yyyy">>. Một chuỗi chỉ ngày đã bị dịch một ngày trên máy UTC+2 trong thử nghiệm của chúng tôi.
  • Server chỉ ghi các tệp; nó không gửi chúng. Việc giao hàng là một bước riêng.

Câu hỏi thường gặp

Tôi có thể thực hiện mail merge với Claude mà không tải lên danh sách khách hàng không?
Có. Server chạy cục bộ và đọc customers.json từ thư mục lưu trữ của bạn; các PDF được tạo cũng sẽ được ghi vào đó.

Các tệp đầu ra được đặt tên như thế nào?
Bằng trường bản ghi bạn truyền vào fileNameField, ở đây là tên khách hàng, vì vậy Contoso Pharma.pdf. Nếu không có, sẽ dùng số thứ tự.

Mỗi tài liệu có thể là email thay vì PDF không?
Có, nếu mẫu là email: một mẫu EML hoặc MSG sẽ được lưu dưới dạng eml, emlx hoặc msg, một tin nhắn cho mỗi bản ghi. Một mẫu Word như lá thư này không thể lưu dưới dạng email; server sẽ trả lời “a WordProcessing template cannot be saved as ’eml’”. Trong chế độ Evaluation, phần thân HTML của email sẽ bị thay thế bằng dòng đánh giá, vì vậy hãy thử đầu ra email với giấy phép.

Đi sâu hơn