Bộ máy Vector hóa Văn bản TF-IDF & Truy vấn Tương đồng Cosine

Mục tiêu kiến thức

• Xây dựng hoàn chỉnh thuật toán trích xuất đặc trưng văn bản TF-IDF (Term Frequency - Inverse Document Frequency) từ nguyên lý toán học nền tảng.
• Tự động tách từ (Tokenization) và xây dựng từ điển từ vựng (Vocabulary) có lọc ngưỡng tần suất tài liệu tối thiểu (min_df).
• Áp dụng công thức Smooth IDF: IDF(t) = ln(1 + N1 + DF(t)) + 1.0.
• Chuẩn hóa vector đặc trưng theo chuẩn Euclidean L₂ và xếp hạng tài liệu liên quan bằng Cosine Similarity.

Mô tả bài toán

Trong các hệ thống Tìm kiếm thông tin (Information Retrieval) và RAG (Retrieval-Augmented Generation) cho AI, việc chuyển đổi tài liệu dạng văn bản tự nhiên thành không gian vector số học là bước đi tiên quyết.

Hãy xây dựng lớp:

class TfidfSearchEngine:
    def __init__(self, min_df: int = 1):
        ...
    def fit(self, corpus: list[str]) -> "TfidfSearchEngine":
        ...
    def transform(self, documents: list[str]) -> np.ndarray:
        ...
    def fit_transform(self, corpus: list[str]) -> np.ndarray:
        ...
    def query(self, query_text: str, top_k: int = 5) -> list[tuple[int, float]]:
        ...

Yêu cầu chi tiết:

• Khởi tạo (__init__):
• min_df: số tài liệu tối thiểu chứa từ khóa để từ khóa đó được đưa vào bộ từ vựng (min_df ≥ 1). Nếu min_df < 1, ném ValueError("min_df must be >= 1").
• Học từ vựng & IDF (fit):
• Tách từ: chuyển văn bản về chữ thường (lower()), dùng re.findall(r'\b\w+\b', text) để lấy danh sách từ.
• Tính tần suất xuất hiện trong tài liệu DF(t) (số tài liệu chứa từ t).
• Giữ lại các từ có DF(t) ≥ min_df. Sắp xếp từ vựng theo thứ tự từ điển (Alphabetical).
• Với N là tổng số tài liệu trong corpus, tính vector IDF:

IDF(t) = ln(1 + N1 + DF(t)) + 1.0

• Lưu trữ ma trận vector hóa của tập corpus để phục vụ truy vấn.
• Trả về chính đối tượng self.
• Chuyển đổi văn bản sang Vector (transform):
• Nhận vào danh sách documents: list[str].
• Với mỗi văn bản, tính tần suất thô (Raw Count) của từng từ trong từ điển đã học.
• Nhân với vector IDF tương ứng: v_t = TF(t, d) × IDF(t).
• Chuẩn hóa L₂ (L2 Normalization): Chia vector cho chuẩn |v|₂ = √(∑ v_i²). Nếu |v|₂ == 0, giữ nguyên vector 0.
• Trả về mảng 2D np.ndarray kích thước (M, V) với kiểu np.float64.
• Truy vấn tài liệu tương đồng (query):
• Chuyển query_text thành vector đặc trưng bằng hàm transform([query_text]).
• Tính độ tương đồng Cosine giữa query vector và toàn bộ tài liệu trong corpus (vì cả hai đã được chuẩn hóa L₂, Cosine Similarity chính là tích vô hướng: sim(d) = q · d).
• Lấy ra top_k tài liệu có điểm số cao nhất. Nếu có các tài liệu cùng điểm số, ưu tiên chỉ số tài liệu nhỏ hơn.
• Trả về danh sách các bộ [(doc_index, similarity_score), ...] với similarity_score làm tròn 4 chữ số thập phân (round(score, 4)).

Ràng buộc

• Kích thước tập văn bản: 1 ≤ N ≤ 5000.
• Độ dài văn bản: mỗi tài liệu chứa tối đa 10⁴ từ.
• Tuyệt đối không import thư viện sklearn hay scipy. Chỉ sử dụng Python Standard Library và numpy.