An AI agent có thể xác minh các chú thích của mình bằng cách nhìn vào trang mà nó vừa đánh dấu. Với GroupDocs.Annotation.Mcp, LLM trong Claude, Cursor hoặc GitHub Copilot sẽ chú thích một tài liệu, yêu cầu máy chủ render trang dưới dạng PNG có bao gồm chú thích, và đánh giá xem vị trí có đúng không. Máy chủ thực hiện công việc trên máy cục bộ; lời nhắc chỉ một câu:

Highlight the payment clause on page 2, then show me the page.

Phiên bản từng bước với cấu hình và khắc phục sự cố có trong tài liệu: How to let an AI agent see the document page it annotated.

Lưu ý: generate_pages_preview hiện đang thất bại với các tệp PDF trên Linux, bao gồm cả hình ảnh Docker; xem mục Giới hạn trung thực trước khi bạn triển khai.

Tại sao một tác nhân không thể nhìn thấy đầu ra của mình lại báo cáo thành công một cách sai lệch?

Hầu hết các công cụ tài liệu chỉ hỗ trợ ghi. Tác nhân gọi chúng và nói “xong” vì lời gọi đã trả về. Đối với một chú thích, câu nói đó có thể sai mà không có thông báo lỗi nào: lời gọi thành công, nhưng phần tô sáng nằm ở đoạn sai. Các tọa độ x và y là tọa độ trong tài liệu, và một tác nhân được yêu cầu tô sáng “điều khoản thanh toán” phải đoán vị trí của điều khoản đó trừ khi có thông tin nào đó chỉ dẫn.

Sự khác biệt nằm giữa “Tôi đã thêm một phần tô sáng” và “phần tô sáng nằm trên điều khoản thanh toán”. Chỉ câu thứ hai có giá trị, và chỉ việc nhìn vào trang mới có thể xác nhận.

Tác nhân render hình ảnh trang đã chú thích và kiểm tra như thế nào?

Các công cụ tạo thành một vòng lặp ngắn.

  1. add_annotation ghi chú thích và lưu contract_annotated.pdf. Tệp gốc không bị thay đổi.
  2. generate_pages_preview render các trang của tệp đó thành hình ảnh PNG, với chú thích đã được nhúng, và trả về chúng nội tuyến. Gửi tham số pages là 2, 1-3 hoặc 1,3,5. Nếu bỏ qua, sẽ nhận trang 1.
  3. Tác nhân nhìn vào hình ảnh. Nếu phần tô sáng bao phủ văn bản sai, update_annotation sẽ thay đổi thông điệp hoặc vị trí và kích thước mà không cần bắt đầu lại.

Xem trước trả về một khối văn bản mô tả những gì đã được render, tiếp theo là một khối hình ảnh cho mỗi trang. Một lời gọi tối đa render năm trang.

Đặt GROUPDOCS_MCP_OUTPUT_PATH thành một thư mục khác với thư mục lưu trữ trước khi thực hiện chuỗi chỉnh sửa trên tệp đã tạo. Với mặc định (kết quả lưu trong thư mục lưu trữ) lần ghi thứ hai sẽ thất bại với lỗi being used by another process; với thư mục đầu ra riêng, các lệnh add_reply, update_annotation và remove_annotations trên tệp đã tạo đều thành công. Với hình ảnh Docker, truyền -e GROUPDOCS_MCP_OUTPUT_PATH=/data/output. Phiên làm việc dưới đây giả định cài đặt này, vì vậy tệp đã tạo nằm trong output/.

Tác nhân cần gì để điều này hoạt động?

  • Một client hiển thị nội dung hình ảnh. Claude Desktop có khả năng này. Một client terminal có thể chỉ báo rằng một hình ảnh đã được trả về. Công cụ hoạt động giống nhau; hình ảnh có thể không được hiển thị.
  • Một mô hình có khả năng xử lý hình ảnh. Hình ảnh chỉ hữu ích cho mô hình chấp nhận đầu vào hình ảnh.
  • Một phạm vi trang nhỏ. Render là lời gọi tốn kém nhất mà máy chủ này thực hiện. Yêu cầu chỉ những trang bạn cần, không phải một tệp năm mươi trang.

Xem trước còn có những công dụng nào khác?

  • Xác định vị trí trước khi chú thích. Đầu tiên render, cho mô hình đọc trang, sau đó đặt chú thích với tọa độ mà nó suy ra thay vì đoán.
  • Kiểm tra việc hợp nhất. Sau khi import_annotations vào bản nháp đã tái bố trí, xem trước cho thấy các ghi chú đã nhập vẫn nằm đúng vị trí hay không.
  • Hiển thị kết quả cho người xem xét trong cuộc trò chuyện mà không cần mở tệp.
  • Phát hiện huy hiệu đánh giá. Trong chế độ đánh giá, một huy hiệu dùng thử được dán lên mỗi trang, vì vậy nó hiển thị trong hình ảnh đã render.

Phiên làm việc mẫu (rút gọn)

Đây là một minh hoạ được xây dựng dựa trên hành vi được tài liệu mô tả của các công cụ, không phải một ảnh chụp màn hình thực tế. Nó giả định một nền tảng mà bộ render xem trước hoạt động với các tệp PDF, chẳng hạn Windows với dnx.

You:   Highlight the payment clause on page 2 of contract.pdf, then show me the page.

Agent: [calls add_annotation: type=highlight, page=2, x=100, y=250,
        text="Payment clause"]
       Added highlight annotation to contract.pdf on page 2.
       [calls generate_pages_preview on output/contract_annotated.pdf, pages="2"]
       (image: page 2, rendered with the highlight)
       The highlight sits on the "Delivery" paragraph, one block above the
       payment clause. Moving it down.
       [calls get_annotations, then update_annotation: y=330]
       Updated annotation 1 in output/contract_annotated.pdf.
       (The agent passes the saved file name from each result to the next call.)

Quá trình render chạy ở đâu, và gì rời khỏi máy?

Động cơ tạo PNG trên máy của bạn. Hình ảnh sau đó được truyền tới nhà cung cấp mô hình của bạn giống như bất kỳ nội dung tin nhắn nào khác, vì vậy với mô hình được lưu trữ trên đám mây, một bản xem trước sẽ gửi một bức ảnh của trang đó. Đối với tài liệu nhạy cảm, hãy sử dụng mô hình được lưu trữ cục bộ.

Giới hạn trung thực

  • Xem trước trên Linux. generate_pages_preview hiện đang thất bại với các tệp PDF trên Linux, bao gồm cả hình ảnh Docker (TypeInitializationException cho Gdip: System.Drawing.Common không được hỗ trợ trên nền tảng không phải Windows); các tài liệu Word và các tài liệu Office khác vẫn được render, và trên Windows với dnx mọi định dạng đều được render. Mười công cụ còn lại không bị ảnh hưởng.
  • Chế độ đánh giá. Một huy hiệu dùng thử được dán lên đầu mỗi trang của tệp đã chú thích và của các bản xem trước. Kiểm tra get_license_status trước khi dựa vào kết quả.
  • Vị trí ước tính vẫn là ước tính. Xem trước cho phép mô hình nhận ra một chú thích bị đặt sai; nó không biến các tọa độ đoán thành các tọa độ chính xác.
  • Mô hình chỉ văn bản không thể kiểm tra. Nó vẫn nhận được khối văn bản, nhưng không thể cho bạn biết trang trông như thế nào.

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

AI có thể kiểm tra vị trí của một bình luận trên trang không?
Có, nếu mô hình chấp nhận hình ảnh. Tác nhân render trang đã chú thích bằng generate_pages_preview và xem xét bức ảnh, sau đó điều chỉnh chú thích bằng update_annotation nếu cần.

Làm thế nào để xem trước một trang PDF đã chú thích cho tác nhân?
Yêu cầu trang theo số, ví dụ “Render các trang 1-3 của hợp đồng đã chú thích để tôi có thể kiểm tra các bình luận”. Tác nhân truyền pages là 1-3 và các PNG được trả về nội tuyến.

Tại sao bản xem trước lại thất bại trong container Docker của tôi?
Đối với các tệp PDF, công cụ thất bại trên Linux, bao gồm cả hình ảnh Docker, với lỗi khởi tạo kiểu Gdip. Các tài liệu Word và các tài liệu Office khác vẫn được render, và trên Windows với dnx mọi định dạng đều được render.

Tìm hiểu sâu hơn