Chuyển đổi tài liệu Office sang Markdown với anydoc

anydoc là gì?

anydoc là thư viện Rust tốc độ cao để chuyển đổi tài liệu thành Markdown sạch theo chuẩn GitHub-Flavored Markdown. Thư viện hỗ trợ Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV và các tệp PDF dạng văn bản. Dự án cũng cung cấp giao diện dòng lệnh cùng các liên kết cho Node.js, Python và WebAssembly chạy trên trình duyệt.

Thư viện được thiết kế cho các quy trình nhận nhiều định dạng tài liệu nhưng cần một biểu diễn Markdown nhất quán. Mỗi định dạng văn phòng được hỗ trợ sẽ được phân tích thành một mô hình tài liệu dùng chung, sau đó đi qua cùng một bộ tuần tự hóa Markdown. Nhờ đó, bảng, ký tự escape, tiêu đề, chú thích cuối trang, liên kết, danh sách và các cấu trúc khác vẫn nhất quán giữa các định dạng.

Quá trình chuyển đổi diễn ra cục bộ, không sử dụng mô hình máy học hay dịch vụ bên ngoài. README báo cáo thời gian chuyển đổi trung vị dưới năm mili giây cho mỗi tài liệu trong bài đo hiệu năng. PDF dạng văn bản được xử lý cục bộ thông qua pdf-inspector.

anydoc không thực hiện OCR. Các tệp PDF chỉ chứa hình ảnh hoặc tài liệu scan không có văn bản đọc được có thể được báo cáo là không được hỗ trợ. Firecrawl Parse là giải pháp máy chủ thay thế được dự án đề cập cho các quy trình cũng yêu cầu OCR.

Tính năng chính

• Markdown nhất quán: Tất cả định dạng văn phòng đều sử dụng mô hình tài liệu và bộ tuần tự hóa dùng chung.
• Đầu ra có cấu trúc: Các cấu trúc được hỗ trợ gồm tiêu đề và mỏ neo, liên kết, tham chiếu nội bộ, danh sách, bảng, trích dẫn khối, chú thích cuối trang, chú thích cuối tài liệu, ghi chú diễn giả, mã nội tuyến và khối mã.
• Bảo toàn định dạng: Có thể biểu diễn chữ đậm, chữ nghiêng, chữ gạch ngang, danh sách nhiệm vụ, danh sách lồng nhau, đánh số nguồn, ô bảng gộp và các hàng tiêu đề.
• Tài nguyên nhúng: Hình ảnh và đối tượng được nhúng sẽ xuất hiện dưới dạng văn bản thay thế trong Markdown, trong khi byte thô và loại phương tiện của chúng vẫn có thể được truy cập thông qua mô hình tài liệu.
• Nhận diện dựa trên nội dung: Các định dạng tài liệu dựa trên PDF, RTF, OLE và ZIP được nhận diện từ byte của chúng thay vì chỉ dựa vào phần mở rộng tệp.
• Liên kết không chặn: Việc chuyển đổi trên Node.js sử dụng nhóm luồng libuv, còn Python giải phóng Global Interpreter Lock trong khi chuyển đổi.
• Gói có kiểu: Các kiểu TypeScript và tệp stub Python được tích hợp sẵn.
• Tích hợp tác nhân: Dự án bao gồm Agent Skill, hướng dẫn các coding agent tương thích sử dụng CLI của anydoc.

Định dạng tệp được hỗ trợ

• Word: .doc, .docx và .docm
• PowerPoint: .ppt, .pps, .pot, .pptx, .pptm, .ppsx và .ppsm
• Excel: .xls, .xlsx, .xlsm và .xlsb
• OpenDocument: .odt, .ods và .odp
• Các định dạng khác: .rtf, .epub, .csv và .pdf

Chọn phương thức cài đặt

Sử dụng CLI cho các tập lệnh shell và những lần chuyển đổi đơn lẻ. Chọn Node.js hoặc Python khi việc chuyển đổi tài liệu là một phần của ứng dụng, Rust cho tích hợp gốc, hoặc WebAssembly khi tệp cần được chuyển đổi trực tiếp trong trình duyệt.

Cài đặt CLI

Bạn có thể chạy CLI dựng sẵn mà không cần cài đặt cố định bằng cách sử dụng npx:

npx @firecrawl/anydoc report.docx

Tệp nhị phân dựng sẵn cho nền tảng của bạn sẽ được tải xuống trong lần chạy đầu tiên. Để cung cấp anydoc dưới dạng một lệnh cố định, hãy cài đặt trên toàn cục:

npm install -g @firecrawl/anydoc
anydoc --help

Cài đặt cho Node.js

npm install @firecrawl/anydoc

Cài đặt cho Python

pip install firecrawl-anydoc

Cài đặt WebAssembly cho trình duyệt

npm install @firecrawl/anydoc-wasm

Bạn cũng có thể dùng thử bản demo trên trình duyệt. Bản demo chạy thư viện WebAssembly cục bộ, vì vậy các tệp đã chọn không rời khỏi máy.

Cài đặt cho Rust

cargo add anydoc

Cài đặt Agent Skill

Để hướng dẫn một agent tương thích chuyển đổi tài liệu bằng CLI của anydoc, hãy cài đặt skill đi kèm:

npx skills add firecrawl/anydoc

README liệt kê Claude Code, Codex, Cursor và OpenCode trong số các ứng dụng khách tương thích.

Chuyển đổi tệp bằng CLI

Ghi Markdown vào đầu ra tiêu chuẩn

Truyền tài liệu nguồn làm đối số đầu tiên. Markdown được tạo sẽ được in ra đầu ra tiêu chuẩn:

npx @firecrawl/anydoc report.docx

Cách này thuận tiện khi bạn muốn kiểm tra kết quả hoặc chuyển kết quả vào một lệnh khác.

Lưu Markdown vào tệp

Sử dụng -o để chọn tệp đầu ra:

npx @firecrawl/anydoc slides.pptx -o slides.md

Chuyển đổi dữ liệu từ đầu vào tiêu chuẩn

Sử dụng - làm đường dẫn đầu vào để đọc byte từ đầu vào tiêu chuẩn. CSV không có chữ ký đáng tin cậy trong nội dung, vì vậy hãy chỉ định rõ định dạng:

npx @firecrawl/anydoc - --format csv < data.csv

Sử dụng anydoc trong Node.js

Gói Node.js cung cấp các hàm riêng cho đường dẫn tệp, mảng byte và mô hình tài liệu dùng chung.

Chuyển đổi đường dẫn tệp

import { toMarkdown } from '@firecrawl/anydoc';

const markdown = await toMarkdown('report.docx');
console.log(markdown);

Chuyển đổi byte

Sử dụng toMarkdownBytes khi tệp đã được tải lên, tải xuống hoặc đọc vào bộ nhớ:

import { toMarkdownBytes } from '@firecrawl/anydoc';

const markdown = await toMarkdownBytes(bytes);

Với các định dạng có chữ ký dễ nhận biết, anydoc sẽ phát hiện định dạng từ nội dung. CSV không có chữ ký như vậy, vì thế hãy truyền tên định dạng:

const markdown = await toMarkdownBytes(bytes, 'csv');

Giữ mô hình tài liệu và các tài sản nhúng

Nếu bạn cần nhiều hơn chuỗi Markdown cuối cùng, hãy dừng ở mô hình tài liệu dùng chung với toDocument:

import { toDocument } from '@firecrawl/anydoc';

const document = await toDocument(bytes);

Mô hình tài liệu chứa cấu trúc đã phân tích và các tài sản nhúng. Byte của tài sản nhúng vẫn có sẵn cùng với kiểu phương tiện, dù biểu diễn Markdown sử dụng văn bản thay thế của chúng.

Sử dụng anydoc trong Python

Chuyển đổi đường dẫn tệp

import anydoc

markdown = anydoc.to_markdown("report.docx")
print(markdown)

Chuyển đổi byte trong bộ nhớ

import anydoc

markdown = anydoc.to_markdown_bytes(data)

Hãy chỉ rõ tên của đầu vào không có chữ ký như CSV:

markdown = anydoc.to_markdown_bytes(data, "csv")

Truy cập mô hình tài liệu

document = anydoc.to_document(data)

Cách tiếp cận này hữu ích khi ứng dụng của bạn cần tài liệu đã phân tích và các tài sản nhúng của nó, thay vì chỉ Markdown đã tuần tự hóa.

Chuyển đổi tài liệu trong trình duyệt

Gói WebAssembly chuyển đổi các mảng byte cục bộ trong trình duyệt. Hãy khởi tạo mô-đun trước khi gọi các hàm chuyển đổi:

import init, { toMarkdownBytes, toDocument } from '@firecrawl/anydoc-wasm';

await init();

const markdown = toMarkdownBytes(bytes);

Tương tự các binding khác, hãy cung cấp định dạng cho CSV:

const markdown = toMarkdownBytes(bytes, 'csv');

Để giữ lại mô hình tài liệu và các tài sản nhúng, hãy sử dụng toDocument:

const document = toDocument(bytes);

Không giống API Node.js được trình bày trước đó, các lệnh gọi chuyển đổi WebAssembly trong README là đồng bộ sau khi khởi tạo.

Sử dụng anydoc từ Rust

Chuyển đổi đường dẫn tệp

let markdown = anydoc::to_markdown("report.docx")?;

Chuyển đổi byte với tính năng tự động phát hiện

let markdown = anydoc::to_markdown_bytes(&bytes, None)?;

Chỉ rõ CSV

let markdown = anydoc::to_markdown_bytes(
    &bytes,
    anydoc::Format::Csv,
)?;

Trả về mô hình tài liệu

let document = anydoc::to_document(&bytes, None)?;

Tìm hiểu tính năng phát hiện định dạng

anydoc kiểm tra các dấu hiệu trong nội dung như phần đầu PDF, nhóm mở đầu RTF, tên luồng OLE và siêu dữ liệu gói ZIP. Điều này có nghĩa là một tệp bị gắn nhãn sai vẫn có thể được chuyển đổi khi định dạng thực tế của tệp có thể được xác định từ các byte của nó.

Rust cung cấp các hàm hỗ trợ để kiểm tra byte, phần mở rộng và đường dẫn:

Format::from_bytes(&bytes);
Format::from_extension("pptm");
Format::from_path(Path::new("report.odt"));

Lệnh gọi đầu tiên trả về một định dạng được phát hiện như Some(Format::Docx), hoặc None khi không có dấu hiệu nội dung đã biết nào khớp. Các hàm hỗ trợ tương đương có sẵn trong Node.js với những tên như formatFromBytes và trong Python với những tên như anydoc.format_from_bytes.

Tại sao CSV cần được xử lý đặc biệt

CSV là văn bản thuần túy và không có chữ ký byte tiêu chuẩn để xác định duy nhất định dạng này. Khi chuyển đổi byte CSV không có tên hoặc đầu vào tiêu chuẩn, hãy cung cấp rõ csv. Nếu đường dẫn tệp có phần mở rộng .csv, phần mở rộng này có thể được dùng để xác định định dạng.

Xử lý lỗi chuyển đổi

Quá trình chuyển đổi trả về lỗi khi không thể tạo ra Markdown có ý nghĩa. Rust cung cấp các trường hợp này thông qua ConvertError:

• Unsupported: Định dạng không xác định hoặc không thể chuyển đổi, bao gồm PDF chỉ chứa hình ảnh.
• Malformed: Tệp có cấu trúc không thể sử dụng và không thể trích xuất nội dung có ý nghĩa.
• Encrypted: Tài liệu được mã hóa hoặc bảo vệ bằng mật khẩu.
• ResourceLimit: Quá trình chuyển đổi vượt quá giới hạn an toàn cố định liên quan đến giải nén, mức lồng nhau hoặc số lượng nút.
• MissingPart: Thiếu một thành phần tài liệu bắt buộc.
• Io: Không thể đọc tệp được truyền vào to_markdown.

Một quy trình xử lý hàng loạt có thể ghi lại các tệp bị mã hóa hoặc không được hỗ trợ, rồi tiếp tục với các đầu vào còn lại:

match anydoc::to_markdown(path) {
    Ok(markdown) => Some(markdown),
    Err(error @ (ConvertError::Encrypted | ConvertError::Unsupported(_))) => {
        unconverted.push((path, error));
        None
    }
    Err(error) => return Err(error),
}

Trong Node.js và WebAssembly, tên biến thể lỗi có sẵn thông qua error.code. Python phát sinh một lớp con anydoc.ConvertError chuyên biệt cho từng biến thể chuyển đổi và phát sinh OSError khi không thể đọc tệp.

Mẹo tích hợp nâng cao

Ưu tiên chuyển đổi byte cho quy trình tải lên

Nếu ứng dụng của bạn đã nhận byte tài liệu từ một lượt tải lên, kho lưu trữ đối tượng hoặc phản hồi HTTP, hãy sử dụng toMarkdownBytes hoặc to_markdown_bytes. Cách này không yêu cầu đường dẫn tệp và cho phép anydoc kiểm tra nội dung thực tế thay vì tin tưởng tên tệp do người dùng cung cấp.

Sử dụng mô hình tài liệu khi tài sản nhúng quan trọng

Markdown không chứa byte thô của các đối tượng nhúng. Hãy sử dụng toDocument hoặc to_document khi bạn cần lưu trữ, kiểm tra hoặc xử lý riêng các tài sản nhúng và kiểu phương tiện của chúng.

Xử lý riêng các PDF được quét

Khả năng hỗ trợ PDF tích hợp của anydoc dành cho các tệp PDF dựa trên văn bản và không bao gồm OCR. Hãy chuyển các tệp PDF chỉ chứa hình ảnh sang quy trình có khả năng OCR thay vì liên tục thử chuyển đổi cục bộ.

Làm rõ việc chọn định dạng CSV

Khi xử lý các đầu vào hỗn hợp trong bộ nhớ, hãy gắn các byte CSV với siêu dữ liệu định dạng rõ ràng. Các định dạng được hỗ trợ khác thường có thể được nhận diện từ nội dung, nhưng CSV cần tên, phần mở rộng hoặc đối số định dạng rõ ràng.

Tận dụng hành vi thời gian chạy

Việc chuyển đổi trong Node.js chạy trên nhóm luồng libuv thay vì chặn vòng lặp sự kiện. Python giải phóng GIL trong quá trình chuyển đổi, cho phép các luồng Python khác tiếp tục chạy. Những đặc tính này hữu ích khi tích hợp tính năng chuyển đổi vào các ứng dụng đồng thời.

Sử dụng đầu ra nhất quán ở các bước tiếp theo

Vì các định dạng văn phòng dùng chung một bộ tuần tự hóa, các hệ thống xử lý tiếp theo có thể sử dụng một cấu trúc Markdown duy nhất thay vì duy trì các quy tắc dọn dẹp riêng cho đầu vào Word, PowerPoint, Excel, RTF và OpenDocument. Điều này khiến anydoc đặc biệt phù hợp với việc lập chỉ mục tìm kiếm, các quy trình trích xuất và việc chuẩn bị văn bản có cấu trúc cho các mô hình ngôn ngữ.

Quy trình chuyển đổi hoạt động như thế nào

1. anydoc kiểm tra các byte của tài liệu hoặc thông tin tên tệp hiện có để xác định định dạng.
2. Bộ phân tích cú pháp dành riêng cho từng định dạng đọc nội dung Word, PowerPoint, Excel, OpenDocument, RTF, EPUB hoặc CSV.
3. Bộ phân tích cú pháp tạo một mô hình tài liệu dùng chung, chứa các khối, phần tử nội dòng, bảng, chú thích cuối trang và tài sản.
4. Bộ tuần tự hóa dùng chung chuyển đổi mô hình đó thành Markdown kiểu GitHub.
5. PDF được xử lý thông qua pdf-inspector và chuyển đổi trực tiếp sang Markdown.

Kiến trúc này có nghĩa là một cải tiến trong bộ tuần tự hóa có thể mang lại lợi ích cho nhiều định dạng cùng lúc. Ví dụ, một bản sửa lỗi xử lý ký tự thoát trong bảng không chỉ giới hạn ở một bộ phân tích cú pháp đầu vào.

Hiệu năng và trường hợp phù hợp nhất

Kho mã báo cáo một phép đo điểm chuẩn trên 100 tài liệu thực tế thuộc mười bốn định dạng đã kiểm thử. anydoc hỗ trợ cả mười bốn định dạng, đạt thời gian chuyển đổi trung vị 4,4 mili giây và nhận điểm chất lượng tổng thể là 81 trong phép so sánh đó. Chất lượng được đánh giá dựa trên tính đầy đủ, cấu trúc, định dạng và độ sạch.

Kết quả điểm chuẩn phụ thuộc vào tập dữ liệu, phần cứng và phương pháp luận, vì vậy hãy sử dụng phép đo điểm chuẩn đi kèm như bằng chứng dành riêng cho dự án thay vì xem đó là sự đảm bảo cho mọi khối lượng công việc. Trường hợp phù hợp nhất được dự án mô tả là một quy trình tiếp nhận một tập hợp hỗn hợp các tài liệu văn phòng và cần Markdown nhanh, có cấu trúc, nhất quán.

Kết luận

anydoc cung cấp một quy trình chuyển đổi duy nhất trên Rust, Node.js, Python, trình duyệt và dòng lệnh. Hãy bắt đầu với CLI để kiểm thử nhanh, sau đó chọn binding phù hợp với ứng dụng của bạn. Sử dụng chuyển đổi dựa trên byte cho các tệp tải lên, chỉ định CSV một cách rõ ràng, giữ lại mô hình tài liệu khi tài sản nhúng quan trọng và xử lý các tài liệu được mã hóa, không hợp lệ, không được hỗ trợ hoặc đã quét như những trường hợp riêng biệt.