Xây dựng một cơ sở tri thức công ty từ trang tài liệu của bạn

TL;DR

• Một trợ lý tài liệu công ty được xây dựng từ một tập hợp tài liệu được chọn lọc, phiên bản - không phải là một bản sao mù quáng của mọi URL dưới miền công ty.
• Thu thập tài liệu công khai vào Markdown, bảo tồn metadata sản phẩm/phiên bản/ngôn ngữ, sau đó chia nhỏ, nhúng, truy xuất và yêu cầu nguồn trích dẫn.
• Đối xử với tài liệu riêng tư như một ranh giới bảo mật riêng biệt: một công cụ thu thập không phải là nhà cung cấp danh tính hoặc hệ thống lọc quyền.
• Bắt đầu với một sản phẩm và một phiên bản tài liệu, xác thực với các câu hỏi hỗ trợ thực tế, và mở rộng chỉ sau khi các quy tắc truy cập và trích dẫn hoạt động.

---

Giới thiệu: Tại sao xây dựng một cơ sở tri thức từ một trang tài liệu?

Nstdata Crawl là lớp thu thập trong quy trình làm việc này; tổng quan sản phẩm của nó mô tả việc truy xuất trang và trang web cho các pipeline dữ liệu hạ nguồn.

Một trang tài liệu SaaS thường trả lời những câu hỏi giống nhau từ khách hàng, hỗ trợ, và các nhà phát triển: cách xác thực, phiên bản SDK nào cần cài đặt, tham số nào hoạt động, hoặc cách khắc phục một lỗi. Một trợ lý powered by retrieval có thể làm cho những trang đó dễ dàng truy vấn hơn bằng ngôn ngữ tự nhiên, với điều kiện chỉ mục bảo tồn sản phẩm và phiên bản của mỗi câu trả lời.

Mục tiêu là một lớp tìm kiếm có bằng chứng hỗ trợ, không phải là một hệ thống tự động chính xác. Hệ thống có thể truy xuất một trang lỗi thời hoặc hiểu sai bảng tham số nếu việc nạp và đánh giá yếu. Nstdata Crawl có thể cung cấp nội dung trang dưới dạng Markdown và hỗ trợ phát hiện trang giới hạn; ứng dụng của bạn vẫn có trách nhiệm về lựa chọn, quyền, chỉ mục, chính sách cập nhật, và hành vi trả lời. Tài liệu chính thức về Crawl mô tả lớp thu thập và định dạng đầu ra.

Những gì bạn sẽ xây dựng

Các trang tài liệu công khai
      ↓ thu thập và xác thực
Markdown + metadata nguồn gốc
      ↓ chuẩn hóa và chia nhỏ
Nhúng + bản ghi véc tơ
      ↓ truy xuất các đoạn liên quan
Trả lời của trợ lý với URL nguồn và nhãn phiên bản

Một người dùng có thể hỏi, “Tiêu đề nào xác thực API hiện tại?” Trợ lý nên truy xuất một trang từ phiên bản API hiện tại, trích dẫn bằng chứng liên quan, và hiển thị URL của nó. Nếu tập hợp chứa cả phiên bản cũ và hiện tại và câu hỏi không xác định phiên bản nào, trợ lý nên hỏi hoặc nhấn mạnh phiên bản mà nó đã sử dụng.

Bước 1: Kiểm tra trang tài liệu

Bắt đầu với kiến trúc thông tin của trang, không phải bộ thu thập dữ liệu. Xem lại sơ đồ trang, điều hướng, lựa chọn phiên bản, đường dẫn địa phương, liên kết chuẩn, và các ranh giới xác thực. Tạo bảng URL với quyết định và chủ sở hữu:

Xác định các trang tài liệu có giá trị cao

Một thử nghiệm nhỏ thường nên bao gồm Bắt đầu, Tham khảo API, Xác thực, hướng dẫn SDK, Giải quyết sự cố, và Câu hỏi thường gặp. Những danh mục này trả lời các câu hỏi hỗ trợ cụ thể và tiết lộ các vấn đề phân tích sớm. Giữ trang marketing ra ngoài trừ khi trợ lý cũng được dự định để trả lời các câu hỏi định vị sản phẩm.

Xử lý nhiều phiên bản và ngôn ngữ

Không hợp nhất nội dung /v1/ và /v2/ thành một tập hợp không phân biệt. Lưu sản phẩm, phiên bản, ngôn ngữ, trạng thái (hiện tại/không còn sử dụng), và canonical_url. Áp dụng bộ lọc truy xuất từ sản phẩm và phiên bản đã chọn của người dùng. Giữ các trang đã địa phương hóa riêng biệt, vì sự khác biệt trong dịch thuật có thể ảnh hưởng đến các tham số và ví dụ.

Bước 2: Thu thập tài liệu công khai vào Markdown

Sử dụng Crawl cấp trang từ gốc tài liệu với giới hạn trang và chiều sâu. Chỉ bao gồm các đường dẫn tài liệu, loại trừ các tuyến đường đăng nhập/tìm kiếm và tài sản không liên quan, và kiểm tra danh sách URL đã phát hiện trước khi lập chỉ mục. Thực hiện một bài kiểm tra nhỏ đầu tiên với một trang tĩnh đại diện, một trang API nặng mã, và một trang sử dụng render phía khách hàng.

SDK Python được tài liệu hỗ trợ một CrawlRequestDto với các trường như url, formats, maxDepth, maxPages, includeUrls, excludeUrls, ignoreQuery, và onlyMainContent:

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=3,
        maxPages=250,
        includeUrls=["*docs.example.com/*"],
        excludeUrls=["*docs.example.com/search*", "*docs.example.com/login*"],
        ignoreQuery=True,
        onlyMainContent=True,
        timeout=60_000,
    ))
    crawl_id = task.id
    print(crawl_id)

Đây là bước gửi biểu; đừng nhầm lẫn ID tác vụ trả về với các trang đã hoàn thành. Kiểm tra trạng thái tác vụ, duyệt qua các kết quả, và lấy bất kỳ tài liệu Markdown nào đã được tham chiếu thông qua điểm cuối lưu trữ đã được tài liệu hóa. Giữ các URL thất bại trong báo cáo thực hiện. Để biết cách thực hiện thực tế việc thu thập dữ liệu và lưu trữ vector, xem hướng dẫn luồng công việc Pinecone.

Bước 3: Làm sạch và tổ chức nội dung

Xóa các thanh điều hướng hoặc biểu ngữ cookie lặp lại chỉ khi chúng rõ ràng là mẫu chung. Bảo tồn tiêu đề, nhãn ngôn ngữ mã, bảng tham số, lời khuyên, liên kết, và thông báo phiên bản. Một ví dụ trước/sau nên cho thấy tại sao quy tắc làm sạch tồn tại:

Before: [Docs Home] [API] [SDK] | Authentication | Use the x-api-key header... | Related: SDKs
After:  ## Authentication
        Send the API token in the `x-api-key` request header...

Hàng “Trước” chỉ mang tính minh họa, không phải kết quả thu thập dữ liệu. Đối với mỗi trang thực tế, lưu trữ nội dung đã trích xuất và siêu dữ liệu của nó trong một bản ghi có cấu trúc:

{
  "source_url": "https://docs.example.com/v2/authentication",
  "canonical_url": "https://docs.example.com/v2/authentication",
  "title": "Authentication",
  "section_path": "API Reference / Authentication",
  "product": "Example API",
  "version": "v2",
  "language": "en",
  "crawled_at": "2026-10-20T00:00:00Z",
  "content_hash": "sha256:..."
}

Điền crawled_at tại thời gian chạy; ngày ở trên là một ví dụ về sơ đồ. Sử dụng một băm ổn định của Markdown đã được chuẩn hóa để phân biệt sự thay đổi nội dung thực tế với một lần thu thập dữ liệu lặp lại.

Bước 4: Chia nhỏ và nhúng tài liệu kỹ thuật

Chia nhỏ theo tiêu đề trước tiên. Giữ lại một phương thức API, điểm cuối, bảng tham số, sơ đồ phản hồi, và mẫu mã liên quan lại với nhau khi chúng mô tả một thao tác. Nếu một phần vượt quá giới hạn đầu vào nhúng, chia nó tại ranh giới đoạn văn hoặc ví dụ mã và sao chép đường dẫn tiêu đề vào siêu dữ liệu của mỗi phần.

Sử dụng một mô hình nhúng cho việc tạo tập hợp và ghi lại tên của nó. Lưu trữ source_url, title, version, language, section_path, và crawled_at với mỗi bản ghi. Vector bản thân không thay thế cho văn bản hoặc siêu dữ liệu trích dẫn của nó. Xem hướng dẫn nhúng OpenAI cho hợp đồng yêu cầu nhúng.

Bước 5: Lưu trữ và truy xuất với bộ lọc phiên bản

Ví dụ này sử dụng Chroma cho một thí điểm tại chỗ; thư viện Python và tham chiếu tập hợp của nó mô tả quy trình làm việc với tập hợp tại chỗ và bền vững. Triển khai sản xuất cần kế hoạch sao lưu và phân quyền rõ ràng. Đối với một lựa chọn được quản lý, xem xét tài liệu upsert bản ghi của Pinecone. Upsert các khối với các ID ổn định, rồi lọc các truy vấn theo sản phẩm và phiên bản đã chọn.

import chromadb

client = chromadb.PersistentClient(path="./docs-index")
collection = client.get_or_create_collection("company_docs")
collection.upsert(
    ids=["auth-v2-001"],
    documents=["Send the API token in the x-api-key header."],
    embeddings=[embedding],  # generated by your chosen embedding model
    metadatas=[{
        "source_url": "https://docs.example.com/v2/authentication",
        "title": "Authentication",
        "product": "Example API",
        "version": "v2",
        "language": "en",
        "section_path": "API Reference / Authentication",
    }],
)

Tại thời điểm truy vấn, chỉ truy xuất sản phẩm/phiên bản được phép và truyền liên kết nguồn vào lời nhắc trả lời. Kiểm tra các câu hỏi API trực tiếp, các câu hỏi đặc thù phiên bản, và các câu hỏi không thể trả lời. Khi không có đủ bằng chứng được truy xuất, trợ lý nên từ chối đoán.

Bước 6: Xây dựng trợ lý Q&A tài liệu

Luồng ứng dụng là: phân loại yêu cầu, áp dụng bộ lọc cho phép người dùng, truy xuất các đoạn văn, xây dựng ngữ cảnh với các URL và phiên bản, hỏi mô hình về một câu trả lời có căn cứ, rồi xác minh các trích dẫn trả về. Phản hồi nên hiển thị một câu trả lời ngắn gọn, liên kết tới các phần nguồn, và nhãn phiên bản. Ghi lại các ID đã truy xuất và phiên bản lời nhắc để có thể truy tìm câu trả lời sai.

Sử dụng các câu hỏi xác thực API, câu hỏi cài đặt SDK, và câu hỏi mã lỗi trong bộ thử nghiệm. Đối với mỗi bài thử, một người xem xét nên xác nhận rằng trang đã trích dẫn chứa thông tin yêu cầu. Một URL phù hợp không đủ nếu nó trỏ tới một phiên bản cũ.

Xử lý tài liệu thiếu, mâu thuẫn, và lỗi thời

Nếu không có trang nào đề cập đến một câu hỏi, hãy nói rằng các tài liệu được lập chỉ mục không xác nhận câu trả lời. Nếu các phiên bản không đồng ý, lấy phiên bản được người dùng chọn hoặc hỏi một câu hỏi làm rõ. Nếu một trang đã bị thay thế, đánh dấu nó là đã hết hạn và lọc nó ra khỏi bộ sưu tập tài liệu hiện tại mặc định trong khi giữ lại để truy vấn lịch sử rõ ràng.

Bước 7: Giữ cho chỉ mục tài liệu được cập nhật

Chạy phát hiện theo lịch trình hoặc kích hoạt nó từ hệ thống xây dựng tài liệu, sau đó so sánh các băm nội dung đã chuẩn hóa. Gắn lại các trang đã thay đổi và loại bỏ ID khối cũ chỉ sau khi phiên bản mới được xác thực. Xem xét các lỗi tạm thời như là thất bại, không phải là xóa bỏ. Giữ một phiên bản cuối cùng đã biết là tốt trong khi một lần thu thập mới đang được xử lý.

Bảo mật và kiểm soát truy cập

Tài liệu công khai và nội bộ cần các kiểm soát truy cập khác nhau. Đừng giả định rằng khóa API của một công cụ thu thập dữ liệu áp đặt quyền truy cập tài liệu cho người dùng cuối. Đối với các trang riêng tư, xác nhận rằng chủ sở hữu nguồn đã cho phép thu thập, bảo vệ thông tin xác thực, tách các chỉ mục hoặc thực hiện các bộ lọc ACL cấp tài liệu, và ghi lại các quyết định truy cập. Không bao giờ lập chỉ mục thông tin bí mật hoặc dữ liệu khách hàng vào một bộ sưu tập chung theo mặc định. Tham khảo đội ngũ bảo mật của tổ chức bạn trước khi tiếp nhận tài liệu mật.

Tài liệu về kiểm soát truy cập của NIST là một điểm khởi đầu hữu ích để thiết kế các ranh giới chính sách; xem hướng dẫn Hệ thống Kiểm soát Truy cập. Các kiểm soát áp dụng phụ thuộc vào triển khai và phân loại dữ liệu của bạn.

Chi phí, bảo trì và các vấn đề phổ biến

Dự trù ngân sách cho các yêu cầu thu thập dữ liệu, sử dụng proxy nếu áp dụng, các mã nhúng, lưu trữ vector, truy vấn mô hình và bảo trì kỹ thuật. Tần suất thu thập lại và các thay đổi tài liệu thường quan trọng hơn so với lần nhập đầu tiên. Đừng báo giá một tổng chi phí theo trang mà không đo lường số khối mà mỗi trang tạo ra và bao lâu thì nó thay đổi; kiểm tra Giá cả thu thập dữ liệu hiện tại trước khi dự báo.

Các vấn đề thông thường bao gồm các phiên bản API hỗn hợp, các khối điều hướng lặp lại, các đoạn mã lỗi, các bản ghi lỗi thời vẫn còn sau một lần cập nhật, các trích dẫn dẫn đến một trang chính tài liệu chung, và nội dung mà người dùng không thể truy cập. Sửa đổi hợp đồng dữ liệu trước: ID ổn định, URL chuẩn, siêu dữ liệu phiên bản, danh sách cho phép và một công việc cập nhật.

Danh sách kiểm tra ra mắt

• Định nghĩa ranh giới nguồn công khai so với riêng tư.
• Giữ một danh sách URL hiện tại và chính sách phiên bản rõ ràng.
• Bảo tồn mã, bảng, cảnh báo, URL và siêu dữ liệu phiên bản.
• Xác thực câu trả lời với các câu hỏi hỗ trợ và phát triển thực tế.
• Thực thi quyền của người dùng trước khi trả lại ngữ cảnh đã thu thập.
• Giám sát phát hiện thay đổi, các khối lỗi thời, URL thất bại và tính chính xác của các trích dẫn.

Đối với một phần khác của quy trình làm việc, tiếp tục với hướng dẫn về ngăn xếp dữ liệu web và hướng dẫn về khung tác nhân AI.

Kết luận

Một cơ sở tri thức công ty từ một trang tài liệu thành công khi vẫn giữ nguyên ngữ cảnh nguồn. Bắt đầu với một tập hợp công khai nhỏ, mô hình hóa siêu dữ liệu sản phẩm và phiên bản một cách rõ ràng, và yêu cầu trợ lý trích dẫn trang mà nó đã sử dụng. Thêm nội dung riêng tư hoặc đa người thuê chỉ sau khi các bộ lọc thu thập và kiểm soát truy cập đã được kiểm tra độc lập.

Thử Nstdata miễn phí →

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

Q: Làm thế nào để xây dựng một cơ sở tri thức từ một trang web?

Chọn và thu thập các trang được phép, bảo tồn siêu dữ liệu nguồn, làm sạch và chia nhỏ nội dung, nhúng nó, lưu trữ nó trong một chỉ mục có thể tìm kiếm, và xác thực câu trả lời với các trích dẫn.

Q: Một cơ sở tri thức AI có thể sử dụng một trang web tài liệu không?

Có, nếu tài liệu có thể được truy cập hợp pháp và phiên bản, ngôn ngữ, và URL nguồn của nó vẫn gắn với các đoạn đã được lập chỉ mục.

Q: Làm thế nào để tạo một trợ lý AI cho tài liệu công ty?

Kết nối một trình thu thập với một chỉ mục tài liệu được chọn lọc, áp dụng quyền của người dùng và bộ lọc phiên bản, và chỉ dẫn mô hình trả lời từ các đoạn đã thu thập với các trích dẫn.

Q: Tôi nên xử lý các phiên bản API trong RAG như thế nào?

Lưu trữ phiên bản API như siêu dữ liệu, giữ các phiên bản riêng biệt, và lọc thu thập tới phiên bản liên quan đến câu hỏi của người dùng.

Q: Tôi có thể thu thập tài liệu nội bộ bên trong đăng nhập không?

Chỉ với sự ủy quyền rõ ràng của nguồn và một thiết kế mà thực thi cùng một ranh giới truy cập cho mọi người dùng của chỉ mục kết quả.