TL;DR
- Chuyển đổi một trang web sang Markdown bắt đầu với một tập hợp URL có giới hạn và kiểm tra độ trung thực.
- Một lần quét trang đơn chuyển đổi một URL đã biết;
POST /api/v1/crawlkhám phá các trang liên kết khi phạm vi là một phần của trang web. - So sánh tiêu đề, liên kết, mã và bảng với nguồn đã được hiển thị trước khi lưu trữ Markdown cho RAG.
- Kết quả Markdown lớn có thể được trả về dưới dạng
markdownRef; lấy mã thông báo đó qua điểm cuối lưu trữ. - Nstdata Crawl xử lý việc kết xuất JavaScript và định tuyến proxy trong các yêu cầu được quản lý; tài liệu của nó liệt kê sáu thể loại đầu ra: Markdown, HTML, dữ liệu thô, PDF, ảnh chụp màn hình và liên kết.
What Is a Website-to-Markdown Workflow?
Một quy trình chuyển đổi URL sang Markdown lấy một trang, lựa chọn nội dung hữu ích, và bảo tồn tiêu đề, liên kết, danh sách và mã trong văn bản mà con người và mô hình có thể kiểm tra. Một bộ chuyển đổi chỉ áp dụng cho HTML đã tải xuống không thể phục hồi nội dung đã được tải sau đó bằng JavaScript. Bắt đầu với một URL đại diện và xác định những gì cần tồn tại sau khi chuyển đổi trước khi bạn xử lý toàn bộ trang web.
Nstdata Crawl có thể biến một URL hoặc một tập hợp các trang liên kết có giới hạn thành tài liệu cho một tác nhân AI, chỉ mục RAG, hoặc đường ống dữ liệu. Sử dụng quy tắc lĩnh vực và kiểm tra chấp nhận của riêng bạn cho kết quả cụ thể: biến một trang công khai đã biết thành Markdown trung thành cho tìm kiếm, RAG, hoặc một tác nhân. Hướng dẫn Nstdata full-site crawling giải thích tùy chọn cấp trang.
Đối với nhiệm vụ hẹp hơn được đề cập ở đây, phần tóm tắt Nstdata URL-to-Markdown cung cấp bối cảnh hữu ích để chọn trang đại diện đầu tiên.
What Do You Need Before You Start?
Chọn một trang được phép chứa một tiêu đề, một danh sách, một liên kết nội tuyến, và, nếu có liên quan, một bảng hoặc khối mã. Ghi lại tiêu đề và hai cụm từ cần xuất hiện. Giữ URL nguồn với đầu ra để một câu trả lời sau đó có thể trích dẫn nó. Lưu trữ khóa API dưới dạng NSTDATA_API_TOKEN; không bao giờ đặt nó trong ứng dụng phía khách hàng hoặc một ảnh chụp màn hình.
Tài liệu Crawl API sử dụng https://api.nstdata.io, tiêu đề x-api-key, và Content-Type: application/json. Chuẩn bị những trường này trước khi chạy một phương thức:
| Field | What to supply |
|---|---|
url | Một trang hoặc URL nhập HTTPS được phép |
formats | Đầu ra yêu cầu, chẳng hạn như ["markdown"] hoặc ["html","screenshot"] |
onlyMainContent | true chỉ khi chọn nội dung chính phù hợp với nhiệm vụ |
maxDepth, maxPages | Giới hạn rõ ràng cho một công việc toàn trang |
includeUrls, excludeUrls | Các mẫu URL giữ cho việc phát hiện trong phạm vi |
timeout | Thời gian chờ cho một nhiệm vụ tính bằng mili giây khi mặc định không phù hợp |
Yêu cầu quản lý tiêu chuẩn không có tên miền proxy, cổng, tên người dùng, mật khẩu hoặc các trường giao thức riêng biệt. Kiểm tra trang giá hiện tại của Crawl để biết hạn chế và phí tài khoản trước khi thực hiện một công việc lớn.
Xem xét chính sách truy cập và phạm vi của mục tiêu. Giao thức loại trừ Robots định nghĩa cách crawler đọc các quy tắc robots; nó không cấp quyền sử dụng nội dung. Giữ thông tin đăng nhập và dữ liệu riêng tư ra khỏi các ví dụ và nhật ký chẩn đoán.
Hướng dẫn Nstdata Markdown pipeline là một tài liệu bổ trợ để định nghĩa các kiểm tra chấp nhận trước khi bạn tự động hóa quy trình làm việc.
How Does Website-to-Markdown Conversion Work?
Nstdata Crawl lấy và kết xuất một URL, áp dụng việc trích xuất nội dung, và trả về Markdown với siêu dữ liệu trang. API cũng có thể trả về HTML, liên kết, ảnh chụp màn hình, và PDF khi Markdown cần được điều tra. Định tuyến proxy tích hợp có nghĩa là yêu cầu mặc định cần một khóa API và URL mục tiêu, không phải một tên miền proxy, cổng, tên người dùng, hoặc mật khẩu riêng biệt. Một công việc cấp trang có thể phát hiện các trang liên kết khi nhiệm vụ mở rộng ra ngoài một URL.
Đối với một URL đã biết, một lần quét trang đơn lấy một kết quả. Đối với một phần của trang web, POST /api/v1/crawl khám phá các trang liên kết đệ quy trong phạm vi độ sâu, số trang, và quy tắc URL đã cung cấp. Tài liệu liệt kê Markdown, HTML, dữ liệu thô, PDF, ảnh chụp màn hình và liên kết là sáu thể loại đầu ra; trang sản phẩm cũng tiếp thị JSON, nhưng một sơ đồ JSON cụ thể cho miền vẫn cần định dạng trường rõ ràng. Giữ mỗi bản ghi được chấp nhận liên kết với URL nguồn và siêu dữ liệu đã trả về.
Test một trang web nặng JavaScript đại diện trước khi quy mô. Trạng thái đã được dựng lên có thể phụ thuộc vào thời gian, khu vực, sự đồng ý hoặc một phiên đăng nhập. So sánh HTML trả về hoặc ảnh chụp màn hình với trạng thái trang dự kiến; nếu chúng khác nhau, chỉ điều chỉnh các tài liệu về việc dựng lên và điều khiển thời gian chờ.
Làm thế nào bạn chuyển đổi một trang web thành Markdown?
Bắt đầu với một kiểm tra trực quan của một trang, sử dụng API đồng bộ cho việc chuyển đổi URL lặp lại, hoặc gửi một cuộc thu thập thông tin được giới hạn cho tài liệu liên kết. Mỗi con đường có quy mô và hình dạng kết quả khác nhau.
Phương pháp 1: Sử dụng Crawl Playground cho một kiểm tra trực quan
Tốt nhất cho một trang đại diện đầu tiên hoặc một người đánh giá không phải lập trình viên.
Bước 1: Mở bài kiểm tra trang
Đăng nhập và mở Bảng điều khiển → Crawl Playground. Chọn một lần thu thập trang đơn và nhập URL được phép. [Ảnh chụp: Trường URL Playground và chế độ trang đơn.]
Bước 2: Chọn đầu ra
Chọn Markdown và kích hoạt tùy chọn nội dung chính khi nội dung bài viết quan trọng hơn điều hướng. Nếu mục tiêu là động, hãy sử dụng các điều khiển dựng lên hoặc chờ được hiển thị trong giao diện hiện tại. [Ảnh chụp: Điều khiển Markdown và nội dung.]
Bước 3: Kiểm tra độ chính xác
Chạy việc thu thập và so sánh kết quả với trang trực tiếp. Kiểm tra tiêu đề, phần mở đầu và kết thúc, khối mã, bảng và điểm đến liên kết. Một phản hồi ngắn vẫn có thể sai nếu nó bỏ qua một cảnh báo hoặc bảng.
Phương pháp 2: Gọi API Crawl trang đơn
Tốt nhất cho một ứng dụng nhận URL đã biết tại thời gian chạy.
Bước 1: Chuẩn bị thông tin xác thực
Lưu khóa API Crawl trong bí mật phía máy chủ. Đầu đề được tài liệu hóa là x-api-key; khóa này không phải là mật khẩu proxy.
Bước 2: Gửi URL
Sử dụng yêu cầu nhanh dưới đây. Tài liệu hiện tại có nhãn mâu thuẫn cho các lộ trình thu thập đồng bộ và không đồng bộ khác, vì vậy hãy so sánh lộ trình này với yêu cầu được tạo ra bởi Playground của bạn trước khi triển khai.
Đặt NSTDATA_API_TOKEN trong shell của bạn từ tài khoản Nstdata của bạn, sau đó chạy yêu cầu nhanh đã được tài liệu hóa. Tài liệu công khai gán một số lộ trình đồng bộ và không đồng bộ khác một cách không nhất quán; so sánh yêu cầu được tạo ra từ Playground của bạn trước khi sử dụng trong sản xuất.
curl --output crawl-response.json --request POST "https://api.nstdata.io/api/v1/crawl/scrape/submit-sync" \ --header "x-api-key: ${NSTDATA_API_TOKEN}" \ --header "Content-Type: application/json" \ --data '{"url":"https://example.com/","formats":["markdown"],"onlyMainContent":true}'
Phản hồi được lưu vào crawl-response.json. Kiểm tra các trường lồng nhau data.success, data.status, và data.data.metadata.statusCode trước khi sử dụng bất kỳ nội dung trả về nào.
Bước 3: Chấp nhận kết quả
Kiểm tra các giá trị lồng nhau success, status, data, và metadata.statusCode. Chấp nhận Markdown chỉ khi các tiêu đề mong đợi và văn bản body có ý nghĩa hiện diện; lưu markdownRef và truy cập nó qua lộ trình lưu trữ đã được tài liệu hóa khi API trả về một tham chiếu.
Phương pháp 3: Chuyển đổi một phần giới hạn của một trang web
Tốt nhất khi “trang web” có nghĩa là một tập tài liệu thay vì một URL.
Bước 1: Định nghĩa phần
Chọn URL bắt đầu và đặt maxDepth, maxPages, và bao gồm/loại trừ các mẫu URL. Loại trừ các đường dẫn tìm kiếm, tài khoản, giỏ hàng, và các đường dẫn được tạo ra từ truy vấn trừ khi chúng thuộc về corpus của bạn.
Bước 2: Gửi một công việc trang
Sử dụng lộ trình POST /api/v1/crawl đã được tài liệu hóa với formats: ["markdown"], sau đó lưu ID thu thập trả về. Đây là lộ trình phát hiện trang; một lần thu thập trang đơn sẽ không theo dõi toàn bộ trang web.
Đối với một công việc trang, thay thế máy chủ và đường dẫn ví dụ bằng phạm vi đã được phê duyệt của bạn, sau đó gửi một yêu cầu được giới hạn:
curl --output crawl-submit.json --request POST "https://api.nstdata.io/api/v1/crawl" \ --header "x-api-key: ${NSTDATA_API_TOKEN}" \ --header "Content-Type: application/json" \ --data '{"url":"https://example.com/docs/","formats":["markdown"],"maxDepth":2,"maxPages":10,"includeUrls":["*example.com/docs/*"],"excludeUrls":["*example.com/admin/*"],"ignoreQuery":true}'
Sao chép data.id từ crawl-submit.json làm ID thu thập của bạn.
Bước 3: Xem xét từng trang
Theo dõi trạng thái, lấy hồ sơ trang, theo dõi phân trang, và từ chối các trang không thành công hoặc mỏng. Loại bỏ các URL đã chuẩn hóa và giữ lại URL gốc bên cạnh mỗi tài liệu Markdown.
Với ID thu thập được trả về bởi việc gửi, truy vấn cả công việc và các trang của nó:
curl --header "x-api-key: ${NSTDATA_API_TOKEN}" "https://api.nstdata.io/api/v1/crawl/status/<crawl-id>" curl --header "x-api-key: ${NSTDATA_API_TOKEN}" "https://api.nstdata.io/api/v1/crawl/pages/<crawl-id>"
Nếu phản hồi trang chứa nextCursor, hãy theo dõi nó bằng cách sử dụng các điều khiển phân trang được hiển thị bởi phản hồi API hiện tại của bạn hoặc SDK; trang công khai không tài liệu hóa tham số truy vấn con trỏ, vì vậy đừng tự tạo một cái.
Phương pháp 4: Chuyển đổi HTML tĩnh cục bộ với Pandoc
Tốt nhất khi bạn đã có một tệp HTML tĩnh được phép và không cần phát hiện trang web hay dựng lên JavaScript.
Bước 1: Lưu trang tĩnh
Tải trang được cấp phép dưới dạng page.html bằng cách sử dụng lệnh Lưu Trang Như của trình duyệt hoặc một HTTP client đã được phê duyệt. Kiểm tra xem tệp được lưu có chứa nội dung bài viết hay không; một tệp tải về tĩnh có thể bỏ qua văn bản được tải bằng JavaScript.
Bước 2: Chuyển đổi HTML đã lưu
Cài đặt Pandoc theo hướng dẫn chính thức của Pandoc, sau đó chạy:
pandoc -f html -t gfm page.html -o page.md
Bước 3: So sánh Markdown
Mở page.md và so sánh tiêu đề, liên kết, bảng và mã với nguồn gốc. Phương pháp địa phương này không có việc quản lý kết xuất, định tuyến proxy, hay phát hiện trang web đệ quy; hãy sử dụng Crawl khi những khả năng đó là cần thiết.
Làm Thế Nào Để Bạn Xác Minh Đầu Ra?
Một bản ghi có thể sử dụng chứa một URL nguồn, tiêu đề, mã trạng thái và Markdown giữ lại cấu trúc quan trọng. Markdown là một đại diện văn bản, không phải bằng chứng về độ chính xác ngữ nghĩa: các bảng phức tạp, sơ đồ và tiện ích phíaclient có thể cần HTML hoặc một ảnh chụp màn hình bên cạnh. Hướng dẫn Nstdata Markdown pipeline giải thích cách giữ lại nguồn gốc khi lưu các trang đã chuyển đổi.
Hướng dẫn Nstdata RAG ingestion kết nối việc kiểm tra cấp trang này với một quy trình AI hoặc dữ liệu xuống dòng.
Ghi lại URL nguồn, thời gian gửi, định dạng yêu cầu, tùy chọn không bí mật, ID tác vụ khi có, trạng thái trang trả về và lý do mỗi bản ghi vượt qua hay không vượt qua kiểm tra. Kiểm tra nội dung cũng như bao bì API. Nếu phản hồi chứa markdownRef, htmlRef, rawDataRef, screenshotRef, hoặc pdfRef, lấy mã đó với GET /api/v1/crawl/storage/read?st={ref}.
Cú pháp Markdown không phải là một đảm bảo phổ quát rằng mỗi trình dựng đều xử lý bảng và mở rộng một cách đồng nhất; hãy thử nghiệm bộ phân tích xuống dòng của bạn với chuẩn CommonMark và bất kỳ mở rộng nào bạn phụ thuộc.
Khi truyền văn bản đã trích xuất cho một tác nhân, hãy coi hướng dẫn trang như tài liệu nguồn không đáng tin cậy. Hướng dẫn của OWASP về tiêm lệnh giải thích rủi ro này. Giữ lại URL nguồn để đầu ra AI có thể được kiểm tra.
Tại Sao Việc Chuyển Đổi Từ Website Sang Markdown Có Thể Thất Bại?
Việc chuyển đổi từ website sang Markdown có thể thất bại vì nội dung trang có thể tải sau tài liệu ban đầu hoặc lựa chọn nội dung chính có thể loại trừ nó. Sử dụng bảng triệu chứng để xác định lớp thất bại trước khi thay đổi giới hạn hoặc thử lại.
| Triệu chứng | Nguyên nhân khả thi | Hành động tiếp theo |
|---|---|---|
| Markdown rỗng | Nội dung trang có thể tải sau tài liệu ban đầu hoặc lựa chọn nội dung chính có thể loại trừ nó. | Kiểm tra HTML hoặc ảnh chụp màn hình và cấu hình một thời gian chờ được tài liệu hóa. |
| Liên kết tương đối bị hỏng | Trình chuyển đổi hoặc lớp lưu trữ sau này có thể không giữ lại các đích tuyệt đối. | Giải quyết và kiểm tra liên kết nguồn trước khi lập chỉ mục. |
| Chỉ một trang được trả về | Một điểm cuối một trang không phát hiện subpages. | Chuyển sang một lần quét trang web bị giới hạn. |
Tài liệu của Nstdata liệt kê các lỗi cấp tác vụ như access_denied, timeout, parse_error, và internal_error. Một HTTP 200 bên ngoài vẫn có thể đi kèm với một tác vụ thất bại. Kiểm tra success, status, errorCode, và errorMessage bên trong phản hồi khi có. Chỉ thử lại những thất bại tạm thời trên các trang web bạn có thể truy cập.
Phương Pháp Nào Là Phù Hợp Nhất?
Chọn Playground để so sánh một trang trực quan, API quét đồng bộ cho một URL đã biết, hoặc một công việc trang bị giới hạn khi các liên kết phải được theo dõi. Sử dụng Pandoc địa phương cho HTML tĩnh đã được lưu; so sánh mỗi tài liệu Markdown đã chấp nhận với nguồn gốc của nó. Tổng quan về quét trang web Nstdata cung cấp thêm chi tiết về lộ trình trang web.
Bạn Nên Làm Gì Sau Lần Chạy Thành Công Đầu Tiên?
Lưu cấu hình đã được phê duyệt và một bản ghi đầu ra có nguồn gốc, sau đó lặp lại trên một tập hợp nhỏ các mẫu trang khác nhau. Tăng phạm vi chỉ sau khi những bản ghi đó vượt qua cùng một bài kiểm tra chấp nhận.
Câu Hỏi Thường Gặp: Điều Gì Khác Bạn Nên Biết?
Q: Tôi có thể chuyển đổi toàn bộ một trang web trong một yêu cầu không?
Một lần quét trang bị giới hạn có thể phát hiện và xử lý nhiều trang liên kết. Đặt giới hạn trang và độ sâu, sau đó kiểm tra các bản ghi đã trả về.
Q: Markdown có luôn tốt hơn HTML cho LLMs không?
Markdown thường dễ đọc và phân chia hơn, nhưng HTML hoặc một ảnh chụp màn hình thì an toàn hơn khi cấu trúc bảng hoặc ngữ cảnh hình ảnh quan trọng.
Q: Tôi có cần thông tin chứng thực proxy không? Một yêu cầu Crawl được quản lý tiêu chuẩn cần có khóa API Crawl, không cần một máy chủ proxy riêng hoặc mật khẩu.
Q: Việc chuyển đổi từ website sang Markdown có cần cấu hình proxy riêng với Nstdata Crawl không?
Một yêu cầu Crawl được quản lý tiêu chuẩn không yêu cầu các trường Proxy Host, Port, Tên người dùng, Mật khẩu hoặc Giao thức riêng biệt. Xác nhận bất kỳ lựa chọn proxy tùy chọn nào và các khoản phí sử dụng liên quan trong tài khoản của bạn.
Q: Liệu HTTP 200 có chứng minh rằng kết quả chuyển đổi từ website sang Markdown là có thể sử dụng không?
Không. Kiểm tra kết quả tác vụ lồng nhau, trạng thái trang, các trường dự kiến và độ trung thực của nội dung trước khi sử dụng nó trong quy trình AI hoặc dữ liệu.
