Tài liệu tìm kiếm trang web cho ngữ cảnh LLM (Thực hành tốt nhất)
TL;DR
Việc thu thập tài liệu cần bảo tồn mã, bảng tham số, ngữ cảnh tiêu đề, ngôn ngữ và phiên bản; chỉ số trang không đủ để đo lường chất lượng.
Sử dụng sơ đồ trang và phát hiện điều hướng cùng nhau, lọc các tuyến đường không liên quan, và so sánh đầu ra từ các trang tĩnh và trang được kết xuất bằng JavaScript trước khi mở rộng.
Xác thực Markdown để tìm các tiêu đề còn thiếu, hàng rào mã bị hỏng, bảng không đầy đủ, đường dẫn trùng lặp, nội dung trống và sự biến động phiên bản.
Chỉ thu thập nội dung được phép. Một API thu thập công cộng không cho phép truy cập tài liệu riêng tư hoặc vượt qua chính sách của một trang web.
Giới thiệu: Tài liệu là dữ liệu có cấu trúc, ngay cả khi nó được công bố dưới dạng HTML
Nstdata Crawl là lớp thu thập dữ liệu trong quy trình làm việc này; tổng quan sản phẩm của nó mô tả cách thu thập trang và trang web cho các đường ống dữ liệu phía dưới.
Một trang web tài liệu được xây dựng cho người đọc điều hướng giữa các trang, phiên bản và ví dụ mã. Một LLM cần Các mối quan hệ tương tự để sống sót qua việc trích xuất. Nếu một trình thu thập dữ liệu trả về một tham số API mà không có điểm cuối, mã mà không có nhãn ngôn ngữ của nó, hoặc một trang v1 cũ bên cạnh một trang v2 hiện tại mà không có siêu dữ liệu phiên bản, ngữ cảnh thu được có thể gây hiểu lầm ngay cả khi từng URL đều được trả về thành công.
Hướng dẫn này bao gồm việc phát hiện tài liệu, thu thập dữ liệu, xác thực Markdown và siêu dữ liệu. Nó không cố gắng dạy một hệ thống tìm kiếm vector hoàn chỉnh. Đối với giai đoạn nhúng sau đó, xem hướng dẫn riêng website-to-Pinecone walkthrough. Nstdata Crawl hỗ trợ Markdown, HTML, dữ liệu thô, liên kết, PDF và đầu ra ảnh chụp màn hình; tài liệu Crawl hiện tại mô tả các phương pháp và giao diện nhiệm vụ.
Điều gì làm cho tài liệu sẵn sàng cho LLM?
Một hồ sơ tài liệu hữu ích bao gồm nội dung đầy đủ, hệ thống tiêu đề có ý nghĩa, mã và bảng không bị hỏng, URL nguồn ổn định, phiên bản, ngôn ngữ, thời gian thu thập dữ liệu và băm nội dung. “Chuyển đổi Markdown thành công” không giống với “LLM có thể trả lời câu hỏi dự kiến.” Xác thực thông tin cụ thể mà trường hợp sử dụng của bạn cần.
Trải nghiệm Nstproxy Crawl - Bắt Đầu Dùng Thử Miễn Phí Hôm Nay
Đối với các trang tham khảo API, giữ lại phương pháp, điểm cuối, thông tin xác thực, tên tham số, loại, giá trị mặc định, trường phản hồi và hành vi lỗi trong cùng một ngữ cảnh địa phương. Đối với hướng dẫn, bảo tồn trình tự các bước và cảnh báo. Đối với nhật ký thay đổi, bảo tồn ngày phát hành và nhãn trạng thái.
Cách thu thập tài liệu khác với việc cào web chung
Tài liệu thường sử dụng các khung như Docusaurus, Nextra, VitePress hoặc MkDocs, nhưng các chế độ kết xuất của chúng khác nhau theo triển khai. Đừng giả định rằng một trình duyệt JavaScript luôn được yêu cầu. Kiểm tra đầu ra từ trang bạn cần: nếu văn bản chính thiếu trong kết quả thu được, thì hãy kiểm tra kết xuất trình duyệt hoặc một thời gian chờ được ghi lại. Tài liệu công khai cho Docusaurus, VitePress, và MkDocs mô tả các hệ thống xuất bản của họ; hành vi của trang web đã triển khai vẫn cần được kiểm tra trực tiếp.
Bước 1: Khám phá các URL tài liệu
Sử dụng sơ đồ trang như một nguồn và liên kết trang web như một nguồn khác. Sơ đồ trang có thể bao gồm các trang mà điều hướng tài liệu không còn hiển thị, trong khi phát hiện liên kết có thể bỏ lỡ các trang mồ côi chỉ được liệt kê trong sơ đồ trang. So sánh các tập hợp URL dẫn đến và phân loại mỗi đường dẫn trước khi thu thập dữ liệu.
Khám phá sơ đồ trang so với thu thập liên kết
Phương pháp
Hữu ích cho
Điểm mù cần kiểm tra
Sơ đồ trang
danh sách trang đã công bố và gợi ý lastmod
mục mục cũ hoặc bị bỏ qua
Phát hiện liên kết
các trang có thể truy cập từ điều hướng tài liệu
các trang mồ côi hoặc liên kết sâu
Danh sách URL được chọn lọc
một bộ thí điểm hoặc phát hành có kiểm soát
gánh nặng bảo trì thủ công
Giao thức Sitemaps định nghĩa định dạng XML, nhưng trường lastmod là siêu dữ liệu do nhà xuất bản cung cấp, không phải là một đảm bảo độc lập về sự thay đổi nội dung. Sử dụng nó để ưu tiên kiểm tra, sau đó so sánh nội dung trang.
Loại trừ các URL không liên quan và trùng lặp
Chuẩn hóa tên miền, loại bỏ các đoạn và quyết định các tham số truy vấn nào ảnh hưởng đến danh tính của trang. Loại trừ kết quả tìm kiếm, trang đăng nhập, các biến theo dõi, các tuyến in, đường dẫn ngôn ngữ trùng lặp, tài nguyên và các trang marketing không liên quan. Giữ cả tài liệu phiên bản và các trang được địa phương hóa chỉ khi chúng nằm trong phạm vi. Ghi lại lý do một trang bị loại trừ để có thể giải thích khoảng trống trong phạm vi.
Bước 2: Thu thập các trang tài liệu vào Markdown
Chạy một thí điểm nhỏ trước. Đối với một trang đã biết, thu thập một trang đơn giúp tránh các biến số phát hiện trang. Đối với một phần tài liệu, một cuộc thu thập dữ liệu trang có giới hạn có thể phát hiện các liên kết với độ sâu và giới hạn trang. Ví dụ SDK Python hiện tại sử dụng NstDataClient, CrawlRequestDto, và Format.MARKDOWN:
import os
from nstdata_ai_crawl import CrawlRequestDto, Format, NstDataClient
with NstDataClient(os.environ["NSTDATA_API_TOKEN"])as client: task = client.submit_crawl_task(CrawlRequestDto( url="https://docs.example.com/", formats=[Format.MARKDOWN], maxDepth=2, maxPages=80, includeUrls=["*docs.example.com/*"], excludeUrls=["*docs.example.com/search*","*docs.example.com/login*"], ignoreQuery=True, onlyMainContent=True, timeout=60_000,))print("task id:", task.id)
Mã này gửi công việc; nó không hiển thị bộ sưu tập trang đã hoàn thành. Kiểm tra trạng thái, truy xuất danh sách trang, theo dõi con trỏ của nó và đọc các tài liệu Markdown được tham chiếu như được tài liệu hóa. Hướng dẫn Crawl hiện tại liệt kê GET /api/v1/crawl/status/{crawlId} và /pages/{crawlId}; webhooks hiện không được hỗ trợ, vì vậy hãy làm cho việc kiểm tra trạng thái trở thành một phần của thiết kế thử nghiệm và thời gian chờ của công nhân của bạn.
Tài liệu được render bằng JavaScript
Kiểm tra xem một cụm từ, khối mã, hoặc tiêu đề trang đã biết có xuất hiện trong Markdown được trả về không. So sánh với trang đã được render trong trình duyệt. Nếu nội dung vắng mặt, hãy kiểm tra việc render JavaScript và chờ chọn lọc khi được hỗ trợ. Tránh bật render toàn cầu mà không có lý do: điều này có thể mất thời gian và khiến bạn khó xác định được nguyên nhân thất bại đến từ việc khám phá, render, hay trích xuất.
Bước 3: Bảo tồn tiêu đề, khối mã, và bảng
Markdown nên bảo tồn H1/H2/H3, khối mã có nhãn ngôn ngữ, bảng, danh sách, cảnh báo, và liên kết nội bộ. Một mẫu xác minh hữu ích có thể chứa:
## Tạo một tokenGửi token trong header `x-api-key`.
| Trường | Loại | Bắt buộc ||---|---|---||`project_id`| chuỗi | có |```python
client = Client(token=token)
Đây là một cấu trúc tổng hợp để kiểm tra định dạng, không phải là đầu ra được ghi lại từ một trang trực tiếp. Sau khi thu thập dữ liệu, hãy kiểm tra xem các khối mã mở và đóng có khớp và số lượng tiêu đề bảng và ô vẫn nhất quán.
### Bảo tồn bối cảnh điểm cuối và tham số
Một phương pháp API trở nên khó sử dụng nếu bảng tham số bị tách rời khỏi điểm cuối. Lưu trữ các tiêu đề cha gần nhất với từng đoạn. Bảo tồn các cảnh báo như “không còn sử dụng” hoặc “bắt buộc cho phiên bản này”; chúng thường thay đổi xem một ví dụ có an toàn để sao chép hay không.
### Xử lý mẫu mã trong nhiều ngôn ngữ
Giữ lại nhãn ngôn ngữ mã, SDK/phiên bản, tên điểm cuối hoặc tính năng, và văn bản giải thích xung quanh. Không nối các ví dụ Python và Node.js vào một khối không phân biệt. Nếu một khối mã rất dài, hãy chia nó tại các ranh giới ví dụ hoặc chức năng hợp lý và lặp lại con đường tiêu đề liên quan.
## Bước 4: Xử lý các phiên bản tài liệu và địa phương hóa
Xem xét `/v1/`, `/v2/`, “mới nhất,” và các tuyến đã lưu trữ là các trạng thái rõ ràng. Lưu trữ `version`, `status`, `language`, và `canonical_url` riêng biệt với văn bản thân. `latest` là một con trỏ di động; thu thập phiên bản đã được xác định nếu trang web nhận biết nó. Giữ lại các bản dịch riêng biệt và tránh hợp nhất các ví dụ giữa các vùng địa lý mà không có đánh giá.
## Bước 5: Chuẩn hóa siêu dữ liệu
Đối với mỗi trang, giữ lại:
```json
{
"source_url": "https://docs.example.com/v2/reference/users",
"canonical_url": "https://docs.example.com/v2/reference/users",
"title": "Users API",
"section_path": "API Reference / Users",
"version": "v2",
"language": "en",
"crawled_at": "runtime timestamp",
"content_hash": "hash of normalized body"
}
Chuẩn hóa danh tính URL một cách nhất quán và băm nội dung đã chuẩn hóa thay vì toàn bộ HTML, để một thay đổi định dạng không buộc phải tái nhúng không cần thiết. Không bao giờ tạo ra ngày cập nhật nguồn khi một trang không công bố chúng.
Bước 6: Xác thực chất lượng thu thập dữ liệu
Tạo các kiểm tra tự động cho thân trống, văn bản ngắn bất ngờ, nội dung lặp lại, thiếu tiêu đề, các khối mã không được đóng, bảng bị sai cấu trúc, URL chính thất bại, nội dung đã chuẩn hóa trùng lặp, và thiếu siêu dữ liệu phiên bản. Sau đó, lấy mẫu thủ công các trang theo loại: tổng quan, tài liệu API, hướng dẫn mã nặng, và một trang động nếu tài liệu sử dụng một.
Một kiểm tra đầy đủ nội dung nên gắn liền với nhiệm vụ: đối với một trang API, so sánh tên điểm cuối kỳ vọng và các trường quan trọng; đối với một hướng dẫn, kiểm tra rằng các tiêu đề và khối mã có sẵn. Trạng thái HTTP xanh không chứng minh rằng nội dung trích xuất đầy đủ.
Bước 7: Lưu trữ tài liệu cho sử dụng LLM
Lưu trữ các tài liệu thu thập dữ liệu dưới dạng các tệp Markdown hoặc JSONL trong quá trình thử nghiệm để người đánh giá có thể kiểm tra chúng. Một cơ sở dữ liệu trở nên hữu ích khi bạn cần cập nhật từng phần, trạng thái cấp trang, quyền truy cập, hoặc truy vấn. Một bản ghi JSONL nên giữ văn bản trang và siêu dữ liệu cùng nhau, với các bản ghi đoạn tham chiếu đến ID trang. Xem triển khai Crawl-to-Pinecone cho giai đoạn nhập liệu tiếp theo.
Các trang lớn, giám sát, và truy cập có trách nhiệm
Ràng buộc lần thu thập đầu tiên với độ sâu, giới hạn trang và bộ lọc URL. Theo dõi trạng thái nhiệm vụ và các lỗi theo trang; tiếp tục từ một điểm kiểm tra thay vì khởi động lại mỗi trang sau một lỗi. Sử dụng tốc độ hợp lý và tôn trọng các điều khoản của trang, hướng dẫn robot và quyền truy cập. Không cố gắng vượt qua các đăng nhập hoặc điều khiển cho nội dung bạn không có quyền thu thập.
Đo lường:
Phạm vi URL: các trang tài liệu hợp lệ được phát hiện / các trang tài liệu dự kiến trong phạm vi.
Độ hoàn chỉnh nội dung: các trang mẫu với các phần cần thiết / các trang mẫu.
Bảo tồn mã: các khối mã liên quan nguyên vẹn / các khối liên quan được mẫu.
Tỷ lệ trùng lặp: tài liệu đã chuẩn hóa trùng lặp / tài liệu được chấp nhận.
Độ hoàn chỉnh siêu dữ liệu: các bản ghi với các trường nguồn/phiên bản cần thiết / các bản ghi được chấp nhận.
Những số liệu này hữu ích hơn so với việc chỉ đếm các yêu cầu thành công. Giữ một danh sách mẫu và chạy lại sau khi thay đổi bộ thu thập dữ liệu, trang tài liệu hoặc quy trình xuất.
Những sai lầm phổ biến và danh sách kiểm tra cuối cùng
Những sai lầm phổ biến bao gồm chỉ thu thập trang chính, loại trừ mối quan hệ phiên bản cũ/hiện tại, lập chỉ mục các trang tìm kiếm, mất nhãn mã, trộn các ngôn ngữ, chấp nhận các trang được kết xuất trống, và coi các yêu cầu thất bại là nội dung đã xóa.
Trước khi gửi tài liệu cho LLM, xác minh việc phát hiện URL, phạm vi truy cập, thành công theo trang, cấu trúc nội dung, siêu dữ liệu phiên bản và ngôn ngữ, xử lý trùng lặp, và hành vi cập nhật. Giữ URL gốc kèm theo qua việc phân đoạn để mọi câu trả lời có thể trích dẫn nó.
Việc thu thập tài liệu cho ngữ cảnh LLM là một nhiệm vụ đảm bảo chất lượng dữ liệu có cấu trúc. Khám phá các trang từ nhiều tín hiệu, ràng buộc việc thu thập, bảo tồn các mối quan hệ kỹ thuật bên trong mỗi trang, và xác minh kết quả với các câu hỏi API đại diện. Khi Markdown vượt qua những kiểm tra đó, nó có thể cung cấp phân đoạn, tìm kiếm, RAG, hoặc một công cụ đại diện.
Q: Làm thế nào để tôi thu thập một trang web tài liệu?
Bắt đầu với một bảng định vị và danh sách điều hướng, lọc đến các đường dẫn tài liệu được phép, nộp một lần thu thập giới hạn, lấy từng kết quả, và xác minh Markdown trước khi lưu trữ nó.
Q: Định dạng tốt nhất cho tài liệu LLM là gì?
Markdown là một định dạng văn bản thực tiễn khi nó bảo tồn các tiêu đề, mã, bảng, liên kết và siêu dữ liệu nguồn; HTML có thể tốt hơn khi cần phân tích tùy chỉnh.
Q: Làm thế nào để tôi chuyển đổi tài liệu sang Markdown?
Sử dụng một công cụ trích xuất trang trả về Markdown, sau đó kiểm tra kết quả cho các phần bị thiếu, bảng bị lỗi hình thức, và tính toàn vẹn của khối mã.
Q: Tài liệu Docusaurus có cần kết xuất JavaScript không?
Không nhất thiết; kiểm tra đầu ra của trang mục tiêu trước và bật kết xuất chỉ khi nội dung cần thiết thiếu trong kết quả không được kết xuất.
Q: Làm thế nào để tôi bảo tồn các khối mã cho RAG?
Giữ các khối được phân cách với nhãn ngôn ngữ và ngữ cảnh tiêu đề gần đó, và chia nhỏ các ví dụ dài chỉ ở các ranh giới hợp lý.
Best practices for discovering and crawling documentation URLs, preserving code and tables, managing versions, and validating LLM-ready Markdown. It includes a practical validation checklist for Markdown output and page coverage.
Ivy Lin
Oct. 20th 2026
Thu thập toàn bộ trang web chỉ với một yêu cầu API
Tỷ lệ thành công 99,8% với kết xuất JavaScript
Nhận dữ liệu sạch, sẵn sàng cho LLM ở nhiều định dạng
Chuyển mọi trang web thành Markdown, HTML, JSON, liên kết, PDF và hơn thế nữa mà không cần quản lý hạ tầng thu thập dữ liệu.
