innit

.dockerignore

@@ -0,0 +1,12 @@
+# .dockerignore
+.git
+__pycache__/
+*.pyc
+.DS_Store
+.vscode/
+.idea/
+# Môi trường ảo cục bộ
+.venv/
+venv/
+env/
+# Các file hoặc thư mục khác không muốn copy vào Docker image

.gitattributes

@@ -33,3 +33,11 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+models/lora_model_base/tokenizer.json filter=lfs diff=lfs merge=lfs -text
+models/**/*.bin filter=lfs diff=lfs merge=lfs -text
+models/**/*.safetensors filter=lfs diff=lfs merge=lfs -text
+models/**/*.pt filter=lfs diff=lfs merge=lfs -text
+models/**/*.onnx filter=lfs diff=lfs merge=lfs -text
+models/**/*.json filter=lfs diff=lfs merge=lfs -text
+data/**/*.index filter=lfs diff=lfs merge=lfs -text
+data/my_law_faiss_flatip_normalized.index filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,65 @@
+# Dockerfile
+
+# Bước 1: Chọn base image
+# Sử dụng Miniconda làm base. Image này đã bao gồm Conda.
+FROM continuumio/miniconda3:latest
+
+# Thiết lập biến môi trường để tránh các prompt tương tác không cần thiết
+# trong quá trình cài đặt các package (thường dùng cho các lệnh apt-get, nhưng để đây cũng không sao)
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Bước 2: Thiết lập thư mục làm việc bên trong container
+WORKDIR /app
+
+# Bước 3: Sao chép file định nghĩa môi trường Conda
+# File environment.yml này nên được đặt cùng cấp với Dockerfile trong repo của bạn.
+COPY environment.yml .
+
+# Bước 4: Tạo môi trường Conda từ file environment.yml
+# Thay "myapp-env" bằng tên môi trường bạn đã đặt trong environment.yml nếu khác.
+# Thêm --force để đảm bảo ghi đè môi trường cũ nếu có (hữu ích khi build lại).
+RUN conda env create -f environment.yml --force && \
+    # Dọn dẹp cache của Conda để giảm kích thước image cuối cùng
+    conda clean -afy
+
+# Bước 5: Kích hoạt môi trường Conda cho tất cả các lệnh RUN, CMD, ENTRYPOINT tiếp theo
+# Tên môi trường "myapp-env" phải khớp với tên trong environment.yml
+SHELL ["conda", "run", "-n", "myapp-env", "/bin/bash", "-c"]
+
+# Bước 6: Cài đặt PyTorch, torchvision, torchaudio với GPU bằng pip và index URL cụ thể
+# QUAN TRỌNG: XÁC MINH LẠI URL VÀ HẬU TỐ CUDA (ví dụ: `cu121` thay vì `cu126` nếu đó là chuẩn).
+# URL bạn cung cấp: --index-url https://download.pytorch.org/whl/cu126
+# Lệnh này sẽ tìm các wheel phù hợp với Python và kiến trúc trên index đó.
+RUN echo "Bắt đầu cài đặt PyTorch, torchvision, torchaudio với GPU..." && \
+    pip install --no-cache-dir torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126 && \
+    echo "Đã cài đặt PyTorch, torchvision, torchaudio."
+
+# Bước 7: Bước xác thực cài đặt (RẤT QUAN TRỌNG để gỡ lỗi trên Spaces)
+# Bước này sẽ in ra thông tin về môi trường, giúp bạn kiểm tra xem mọi thứ có đúng không.
+RUN echo "--- KIỂM TRA MÔI TRƯỜNG SAU KHI CÀI ĐẶT ---" && \
+    echo "Đường dẫn Conda:" && which conda && \
+    echo "Đường dẫn Python:" && which python && \
+    echo "Phiên bản Python:" && python --version && \
+    echo "--- Thông tin PyTorch: ---" && \
+    python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'CUDA available for PyTorch: {torch.cuda.is_available()}'); print(f'PyTorch built with CUDA version: {torch.version.cuda if torch.cuda.is_available() else 'N/A'}'); print(f'cuDNN version: {torch.backends.cudnn.version() if torch.cuda.is_available() and torch.backends.cudnn.is_available() else 'N/A'}'); print(f'Number of GPUs available to PyTorch: {torch.cuda.device_count()}')" && \
+    echo "--- Thông tin Faiss: ---" && \
+    python -c "import faiss; print(f'Faiss version: {faiss.__version__}'); print(f'Number of GPUs available to Faiss: {faiss.get_num_gpus()}')" && \
+    echo "--- Danh sách một số gói pip quan trọng: ---" && \
+    pip list | grep -E 'gradio|torch|faiss|unsloth|sentence-transformers|transformers|numpy|rank_bm25|huggingface_hub' && \
+    echo "--- KẾT THÚC KIỂM TRA MÔI TRƯỜNG ---"
+
+# Bước 8: Sao chép toàn bộ code ứng dụng của bạn (app.py, retrieval.py, v.v.)
+# và các thư mục con (data/, models/ - nếu bạn tải model lên trực tiếp)
+# vào thư mục /app bên trong container.
+# Hãy tạo file .dockerignore để loại bỏ các file không cần thiết (ví dụ: .git, __pycache__, .venv)
+COPY . .
+
+# Bước 9: (Tùy chọn) Thiết lập các biến môi trường mà ứng dụng của bạn có thể cần
+# Ví dụ:
+# ENV MY_VARIABLE="my_value"
+# ENV GRADIO_SERVER_NAME="0.0.0.0" # Thường Gradio tự xử lý
+# ENV GRADIO_SERVER_PORT="7860"   # Thường Gradio tự xử lý
+
+# Bước 10: Thiết lập lệnh mặc định để chạy ứng dụng của bạn
+# Điều này giả định rằng app.py của bạn khởi chạy server Gradio.
+CMD ["python", "app.py"]

app.py

@@ -0,0 +1,144 @@
+import gradio as gr
+import torch # Cần cho việc kiểm tra CUDA và device
+# Import các hàm và lớp từ các file của bạn
+from retrieval import (
+    process_law_data_to_chunks,
+    # VEHICLE_TYPE_MAP, # Có thể không cần import trực tiếp nếu chỉ dùng trong retrieval.py
+    # get_standardized_vehicle_type, # Tương tự
+    # analyze_query, # Được gọi bởi search_relevant_laws
+    tokenize_vi_for_bm25_setup, # Cần cho BM25
+    search_relevant_laws
+)
+from llm_handler import generate_response # Giả sử hàm này đã được điều chỉnh để nhận model, tokenizer, etc.
+from sentence_transformers import SentenceTransformer
+import faiss
+from rank_bm25 import BM25Okapi
+import json
+from unsloth import FastLanguageModel # Từ llm_handler.py hoặc import trực tiếp nếu logic tải model ở đây
+
+# --- KHỞI TẠO MỘT LẦN KHI APP KHỞI ĐỘNG ---
+# Đường dẫn (điều chỉnh nếu cần, có thể dùng os.path.join)
+JSON_FILE_PATH = "data/luat_chi_tiet_output_openai_sdk_final_cleaned.json"
+FAISS_INDEX_PATH = "data/my_law_faiss_flatip_normalized.index"
+LLM_MODEL_PATH = "models/lora_model_base" # Hoặc đường dẫn cục bộ
+EMBEDDING_MODEL_PATH = "models/embedding_model"
+
+# 1. Tải và xử lý dữ liệu luật
+print("Loading and processing law data...")
+try:
+    with open(JSON_FILE_PATH, 'r', encoding='utf-8') as f:
+        raw_data_from_file = json.load(f)
+    chunks_data = process_law_data_to_chunks(raw_data_from_file)
+    print(f"Loaded {len(chunks_data)} chunks.")
+    if not chunks_data:
+        raise ValueError("Chunks data is empty after processing.")
+except Exception as e:
+    print(f"Error loading/processing law data: {e}")
+    chunks_data = [] # Hoặc xử lý lỗi khác
+
+# 2. Tải mô hình embedding
+print(f"Loading embedding model: {EMBEDDING_MODEL_PATH}...")
+device = "cuda" if torch.cuda.is_available() else "cpu"
+try:
+    embedding_model = SentenceTransformer(EMBEDDING_MODEL_PATH, device=device)
+    print("Embedding model loaded successfully.")
+except Exception as e:
+    print(f"Error loading embedding model: {e}")
+    embedding_model = None # Xử lý lỗi
+
+# 3. Tải FAISS index
+print(f"Loading FAISS index from: {FAISS_INDEX_PATH}...")
+try:
+    faiss_index = faiss.read_index(FAISS_INDEX_PATH)
+    print(f"FAISS index loaded. Total vectors: {faiss_index.ntotal}")
+except Exception as e:
+    print(f"Error loading FAISS index: {e}")
+    faiss_index = None # Xử lý lỗi
+
+# 4. Tạo BM25 model
+print("Creating BM25 model...")
+bm25_model = None
+if chunks_data:
+    try:
+        corpus_texts_for_bm25 = [chunk.get('text', '') for chunk in chunks_data]
+        tokenized_corpus_bm25 = [tokenize_vi_for_bm25_setup(text) for text in corpus_texts_for_bm25]
+        bm25_model = BM25Okapi(tokenized_corpus_bm25)
+        print("BM25 model created successfully.")
+    except Exception as e:
+        print(f"Error creating BM25 model: {e}")
+else:
+    print("Skipping BM25 model creation as chunks_data is empty.")
+
+
+# 5. Tải mô hình LLM và tokenizer (sử dụng Unsloth)
+print(f"Loading LLM model: {LLM_MODEL_PATH}...")
+try:
+    # Nên đặt logic tải model LLM vào llm_handler.py và gọi hàm đó ở đây
+    # Hoặc trực tiếp:
+    llm_model, llm_tokenizer = FastLanguageModel.from_pretrained(
+        model_name=LLM_MODEL_PATH, # Đường dẫn tới model đã fine-tune
+        max_seq_length=2048,
+        dtype=None, # Unsloth sẽ tự động chọn
+        load_in_4bit=True, # Sử dụng 4-bit quantization
+    )
+    FastLanguageModel.for_inference(llm_model) # Tối ưu cho inference
+    print("LLM model and tokenizer loaded successfully.")
+except Exception as e:
+    print(f"Error loading LLM model: {e}")
+    llm_model = None
+    llm_tokenizer = None
+# --- KẾT THÚC KHỞI TẠO MỘT LẦN ---
+
+# Hàm respond mới sẽ sử dụng các model và data đã tải ở trên
+def respond(message, history: list[tuple[str, str]]):
+    if not all([chunks_data, embedding_model, faiss_index, bm25_model, llm_model, llm_tokenizer]):
+        # Ghi log chi tiết hơn ở đây nếu cần để biết thành phần nào bị thiếu
+        missing_components = []
+        if not chunks_data: missing_components.append("chunks_data")
+        if not embedding_model: missing_components.append("embedding_model")
+        if not faiss_index: missing_components.append("faiss_index")
+        if not bm25_model: missing_components.append("bm25_model")
+        if not llm_model: missing_components.append("llm_model")
+        if not llm_tokenizer: missing_components.append("llm_tokenizer")
+        error_msg = f"Lỗi: Một hoặc nhiều thành phần của hệ thống chưa được khởi tạo thành công. Thành phần thiếu: {', '.join(missing_components)}. Vui lòng kiểm tra logs của Space."
+        print(error_msg) # In ra console log của Space
+        return error_msg # Trả về cho người dùng
+
+    try:
+        response_text = generate_response(
+            query=message,
+            llama_model=llm_model,
+            tokenizer=llm_tokenizer,
+            faiss_index=faiss_index,
+            embed_model=embedding_model,
+            chunks_data_list=chunks_data,
+            bm25_model=bm25_model,
+            search_function=search_relevant_laws  # << RẤT QUAN TRỌNG: Đã thêm tham số này
+            # Bạn có thể truyền thêm các tham số search_k, search_multiplier,
+            # rrf_k_constant, max_new_tokens, temperature, etc. vào đây
+            # nếu bạn muốn ghi đè giá trị mặc định trong llm_handler.generate_response
+            # Ví dụ:
+            # search_k=5,
+            # max_new_tokens=768
+        )
+        yield response_text
+
+    except Exception as e:
+        # Ghi log lỗi chi tiết hơn
+        import traceback
+        print(f"Error during response generation for query '{message}': {e}")
+        print(traceback.format_exc()) # In stack trace để debug
+        yield f"Đã xảy ra lỗi nghiêm trọng khi xử lý yêu cầu của bạn. Vui lòng thử lại sau hoặc liên hệ quản trị viên."
+
+# Giao diện Gradio
+# Bỏ các additional_inputs không cần thiết nếu chúng được xử lý bên trong generate_response
+# hoặc nếu bạn không muốn người dùng cuối thay đổi chúng.
+demo = gr.ChatInterface(
+    respond,
+    # additional_inputs=[ # Bạn có thể thêm lại nếu muốn người dùng tùy chỉnh
+    #     gr.Textbox(value="You are a helpful Law Chatbot.", label="System message"), # Ví dụ
+    # ]
+)
+
+if __name__ == "__main__":
+    demo.launch()

data/my_law_faiss_flatip_normalized.index

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:378937c6e14ac44d9602a831ce58c91176e2974ad82d3ff6179e6531d8cd2fb8
+size 7526445

environment.yml

@@ -0,0 +1,30 @@
+# environment.yml
+name: myapp-env
+channels:
+  - pytorch
+  - nvidia      # Quan trọng cho cudatoolkit
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.11.12 # Hoặc phiên bản Python của bạn
+  # --- Các gói Conda ---
+  # Yêu cầu faiss với hỗ trợ GPU cho Linux từ conda-forge
+  # Conda sẽ cố gắng tìm bản build faiss-gpu hoặc faiss kéo theo cudatoolkit
+  # có phiên bản CUDA tương thích với PyTorch bạn sẽ cài.
+  - conda-forge::faiss-gpu # Đây là cách gọi phổ biến cho Linux
+  # Hoặc bạn có thể thử chỉ 'conda-forge::faiss' và xem nó có tự động kéo cudatoolkit không.
+  # Để chắc chắn, bạn có thể chỉ định cudatoolkit:
+  # - conda-forge::faiss-gpu cudatoolkit=12.1 # Thay 12.1 bằng phiên bản CUDA PyTorch của bạn sẽ dùng
+  #                                          # (ví dụ, nếu pip install torch ... --index-url .../whl/cu121)
+  # ... các gói conda khác ...
+  - pip
+  - pip:
+    - gradio
+    - sentence-transformers
+    - numpy
+    - unsloth
+    - transformers
+    - rank_bm25
+    - huggingface_hub
+    # KHÔNG có torch ở đây, sẽ cài trong Dockerfile
+    # KHÔNG có faiss ở đây

llm_handler.py

@@ -0,0 +1,296 @@
+# llm_handler.py
+
+import torch
+import re
+import json
+from unsloth import FastLanguageModel
+# from transformers import TextStreamer # Bỏ comment nếu bạn muốn dùng TextStreamer để stream token
+
+# Giả định rằng hàm search_relevant_laws được import từ file retrieval.py
+# Nếu file retrieval.py nằm cùng cấp, bạn có thể import như sau:
+# from retrieval import search_relevant_laws
+# Hoặc nếu bạn muốn hàm này độc lập hơn, bạn có thể truyền retrieved_results vào generate_response
+# thay vì truyền tất cả các thành phần của RAG.
+# Tuy nhiên, dựa theo code gốc, generate_response gọi search_relevant_laws.
+
+# --- HÀM TẢI MÔ HÌNH LLM VÀ TOKENIZER ---
+def load_llm_model_and_tokenizer(
+    model_name_or_path: str,
+    max_seq_length: int = 2048,
+    load_in_4bit: bool = True,
+    device_map: str = "auto" # Cho phép Unsloth tự quyết định device map
+):
+    """
+    Tải mô hình ngôn ngữ lớn (LLM) đã được fine-tune bằng Unsloth và tokenizer tương ứng.
+
+    Args:
+        model_name_or_path (str): Tên hoặc đường dẫn đến mô hình đã fine-tune.
+        max_seq_length (int): Độ dài chuỗi tối đa mà mô hình hỗ trợ.
+        load_in_4bit (bool): Có tải mô hình ở dạng 4-bit quantization hay không.
+        device_map (str): Cách map model lên các device (ví dụ "auto", "cuda:0").
+
+    Returns:
+        tuple: (model, tokenizer) nếu thành công, (None, None) nếu có lỗi.
+    """
+    print(f"Đang tải LLM model: {model_name_or_path}...")
+    try:
+        model, tokenizer = FastLanguageModel.from_pretrained(
+            model_name=model_name_or_path,
+            max_seq_length=max_seq_length,
+            dtype=None,  # Unsloth sẽ tự động chọn dtype tối ưu
+            load_in_4bit=load_in_4bit,
+            device_map=device_map, # Thêm device_map
+            # token = "hf_YOUR_TOKEN_HERE" # Nếu model là private trên Hugging Face Hub
+        )
+        FastLanguageModel.for_inference(model)  # Tối ưu hóa mô hình cho inference
+        print("Tải LLM model và tokenizer thành công.")
+        return model, tokenizer
+    except Exception as e:
+        print(f"Lỗi khi tải LLM model và tokenizer: {e}")
+        return None, None
+
+# --- HÀM TẠO CÂU TRẢ LỜI TỪ LLM ---
+def generate_response(
+    query: str,
+    llama_model, # Mô hình LLM đã tải
+    tokenizer,   # Tokenizer tương ứng
+    # Các thành phần RAG được truyền từ app.py (đã được tải trước đó)
+    faiss_index,
+    embed_model,
+    chunks_data_list: list,
+    bm25_model,
+    # Các tham số cho search_relevant_laws
+    search_k: int = 5,
+    search_multiplier: int = 10, # initial_k_multiplier
+    rrf_k_constant: int = 60,
+    # Các tham số cho generation của LLM
+    max_new_tokens: int = 768, # Tăng lên một chút cho câu trả lời đầy đủ hơn
+    temperature: float = 0.4, # Giảm một chút để câu trả lời bớt ngẫu nhiên, tập trung hơn
+    top_p: float = 0.9,       # Giữ nguyên hoặc giảm nhẹ
+    top_k: int = 40,
+    repetition_penalty: float = 1.15, # Tăng nhẹ để tránh lặp từ
+    # Tham số để import hàm search_relevant_laws
+    search_function # Đây là hàm search_relevant_laws được truyền vào
+):
+    """
+    Truy xuất ngữ cảnh bằng hàm search_relevant_laws (được truyền vào)
+    và tạo câu trả lời từ LLM dựa trên ngữ cảnh đó.
+
+    Args:
+        query (str): Câu truy vấn của người dùng.
+        llama_model: Mô hình LLM đã tải.
+        tokenizer: Tokenizer tương ứng.
+        faiss_index: FAISS index đã tải.
+        embed_model: Mô hình embedding đã tải.
+        chunks_data_list (list): Danh sách các chunk dữ liệu luật.
+        bm25_model: Mô hình BM25 đã tạo.
+        search_k (int): Số lượng kết quả cuối cùng muốn lấy từ hàm search.
+        search_multiplier (int): Hệ số initial_k_multiplier cho hàm search.
+        rrf_k_constant (int): Hằng số k cho RRF trong hàm search.
+        max_new_tokens (int): Số token tối đa được tạo mới bởi LLM.
+        temperature (float): Nhiệt độ cho việc sinh văn bản.
+        top_p (float): Tham số top-p cho nucleus sampling.
+        top_k (int): Tham số top-k.
+        repetition_penalty (float): Phạt cho việc lặp từ.
+        search_function: Hàm thực hiện tìm kiếm (ví dụ: retrieval.search_relevant_laws).
+
+    Returns:
+        str: Câu trả lời được tạo ra bởi LLM.
+    """
+    print(f"\n--- [LLM Handler] Bắt đầu xử lý query: '{query}' ---")
+
+    # === 1. Truy xuất ngữ cảnh (Sử dụng hàm search_function được truyền vào) ===
+    print("--- [LLM Handler] Bước 1: Truy xuất ngữ cảnh (Hybrid Search)... ---")
+    try:
+        retrieved_results = search_function(
+            query_text=query,
+            embedding_model=embed_model,
+            faiss_index=faiss_index,
+            chunks_data=chunks_data_list,
+            bm25_model=bm25_model,
+            k=search_k,
+            initial_k_multiplier=search_multiplier,
+            rrf_k_constant=rrf_k_constant
+            # Các tham số boost có thể lấy giá trị mặc định trong search_function
+            # hoặc truyền vào đây nếu muốn tùy chỉnh sâu hơn từ app.py
+        )
+        print(f"--- [LLM Handler] Truy xuất xong, số kết quả: {len(retrieved_results)} ---")
+        if not retrieved_results:
+            print("--- [LLM Handler] Không tìm thấy ngữ cảnh nào. ---")
+    except Exception as e:
+        print(f"Lỗi trong quá trình truy xuất ngữ cảnh: {e}")
+        retrieved_results = [] # Xử lý lỗi bằng cách trả về danh sách rỗng
+
+    # === 2. Định dạng Context từ retrieved_results ===
+    print("--- [LLM Handler] Bước 2: Định dạng context cho LLM... ---")
+    context_parts = []
+    if not retrieved_results:
+        context = "Không tìm thấy thông tin luật liên quan trong cơ sở dữ liệu để trả lời câu hỏi này."
+    else:
+        for i, res in enumerate(retrieved_results):
+            metadata = res.get('metadata', {})
+            article_title = metadata.get('article_title', 'N/A') # Lấy tiêu đề Điều
+            article = metadata.get('article', 'N/A')
+            clause = metadata.get('clause_number', 'N/A') # Sửa key cho khớp với process_law_data_to_chunks
+            point = metadata.get('point_id', '')
+            source = metadata.get('source_document', 'N/A')
+            text_content = res.get('text', '*Nội dung không có*')
+
+            # Header rõ ràng cho mỗi nguồn
+            header_parts = [f"Trích dẫn {i+1}:"]
+            if source != 'N/A':
+                header_parts.append(f"(Nguồn: {source})")
+            if article != 'N/A':
+                header_parts.append(f"Điều {article}")
+                if article_title != 'N/A' and article_title != article: # Chỉ thêm tiêu đề nếu khác số điều
+                    header_parts.append(f"({article_title})")
+            if clause != 'N/A':
+                header_parts.append(f", Khoản {clause}")
+            if point: # point_id có thể là None hoặc rỗng
+                header_parts.append(f", Điểm {point}")
+
+            header = " ".join(header_parts)
+
+            # Bổ sung thông tin phạt/điểm vào header nếu query có đề cập
+            # và metadata của chunk có thông tin đó (lấy từ logic boosting của search_relevant_laws)
+            query_analysis = metadata.get("query_analysis_for_boost", {}) # Giả sử search_relevant_laws có thể trả về
+            # Hoặc phân tích lại query ở đây (ít hiệu quả hơn)
+            mentions_fine_in_query = bool(re.search(r'tiền|phạt|bao nhiêu đồng|mức phạt', query.lower()))
+            mentions_points_in_query = bool(re.search(r'điểm|trừ điểm|bằng lái|gplx', query.lower()))
+
+            fine_info_text = []
+            if metadata.get("has_fine") and mentions_fine_in_query:
+                if metadata.get("individual_fine_min") is not None and metadata.get("individual_fine_max") is not None:
+                    fine_info_text.append(f"Phạt tiền: {metadata.get('individual_fine_min'):,} - {metadata.get('individual_fine_max'):,} VND.")
+                elif metadata.get("overall_fine_note_for_clause_text"):
+                     fine_info_text.append(f"Ghi chú phạt tiền: {metadata.get('overall_fine_note_for_clause_text')}")
+
+            points_info_text = []
+            if metadata.get("has_points_deduction") and mentions_points_in_query:
+                if metadata.get("points_deducted_values_str"):
+                    points_info_text.append(f"Trừ điểm: {metadata.get('points_deducted_values_str')} điểm.")
+                elif metadata.get("overall_points_deduction_note_for_clause_text"):
+                    points_info_text.append(f"Ghi chú trừ điểm: {metadata.get('overall_points_deduction_note_for_clause_text')}")
+
+
+            penalty_summary = ""
+            if fine_info_text or points_info_text:
+                penalty_summary = " (Liên quan: " + " ".join(fine_info_text + points_info_text) + ")"
+
+            context_parts.append(f"{header}{penalty_summary}\nNội dung: {text_content}")
+
+        context = "\n\n---\n\n".join(context_parts)
+        # print("\n--- [LLM Handler] Context đã định dạng ---\n", context[:1000] + "...") # Xem trước context
+
+    # === 3. Xây dựng Prompt ===
+    # Sử dụng định dạng prompt mà mô hình của bạn được fine-tune (ví dụ: Alpaca)
+    # Dưới đây là một ví dụ, bạn có thể cần điều chỉnh cho phù hợp với `lora_model_base`
+    prompt = f"""Bạn là một trợ lý AI chuyên tư vấn về luật giao thông đường bộ Việt Nam.
+Nhiệm vụ của bạn là dựa vào các thông tin luật được cung cấp dưới đây để trả lời câu hỏi của người dùng một cách chính xác, chi tiết và dễ hiểu.
+Nếu thông tin không đủ hoặc không có trong các trích dẫn được cung cấp, hãy trả lời rằng bạn không tìm thấy thông tin cụ thể trong tài liệu được cung cấp.
+Tránh đưa ra ý kiến cá nhân hoặc thông tin không có trong ngữ cảnh. Hãy trích dẫn điều, khoản, điểm nếu có thể.
+
+### Thông tin luật được trích dẫn:
+{context}
+
+### Câu hỏi của người dùng:
+{query}
+
+### Trả lời của bạn:"""
+
+    # print("\n--- [LLM Handler] Prompt hoàn chỉnh (một phần) ---\n", prompt[:1000] + "...")
+
+    # === 4. Tạo câu trả lời từ LLM ===
+    print("--- [LLM Handler] Bước 3: Tạo câu trả lời từ LLM... ---")
+    device = llama_model.device # Lấy device từ model đã tải
+    inputs = tokenizer(prompt, return_tensors="pt").to(device) # Chuyển inputs lên cùng device với model
+
+    generation_config = dict(
+        max_new_tokens=max_new_tokens,
+        temperature=temperature,
+        top_p=top_p,
+        top_k=top_k,
+        repetition_penalty=repetition_penalty,
+        do_sample=True if temperature > 0 else False, # Chỉ sample khi temperature > 0
+        pad_token_id=tokenizer.eos_token_id, # Quan trọng cho batch generation và padding
+        eos_token_id=tokenizer.eos_token_id,
+    )
+
+    try:
+        # # Tùy chọn: Sử dụng TextStreamer nếu bạn muốn stream từng token (cần sửa đổi hàm này để yield)
+        # text_streamer = TextStreamer(tokenizer, skip_prompt=True, skip_special_tokens=True)
+        # output_ids = llama_model.generate(**inputs, streamer=text_streamer, **generation_config)
+        # response_text = "" # TextStreamer sẽ in ra, không cần decode lại nếu chỉ để hiển thị
+
+        # Generate bình thường để trả về chuỗi hoàn chỉnh
+        output_ids = llama_model.generate(**inputs, **generation_config)
+
+        # Lấy phần token được tạo mới (sau prompt)
+        input_length = inputs.input_ids.shape[1]
+        generated_ids = output_ids[0][input_length:]
+        response_text = tokenizer.decode(generated_ids, skip_special_tokens=True).strip()
+
+        print("--- [LLM Handler] Tạo câu trả lời hoàn tất. ---")
+        # print(f"--- [LLM Handler] Response text: {response_text[:300]}...")
+        return response_text
+
+    except Exception as e:
+        print(f"Lỗi trong quá trình LLM generating: {e}")
+        return "Xin lỗi, đã có lỗi xảy ra trong quá trình tạo câu trả lời từ mô hình ngôn ngữ."
+
+
+# --- (Tùy chọn) Hàm main để test nhanh file này ---
+if __name__ == '__main__':
+    # Phần này chỉ để test, bạn cần mock các đối tượng hoặc tải thật
+    print("Chạy test cho llm_handler.py (chưa có mock dữ liệu)...")
+
+    # # Ví dụ cách mock (bạn cần dữ liệu thật hoặc mock phức tạp hơn để chạy)
+    # mock_llm_model, mock_tokenizer = load_llm_model_and_tokenizer(
+    #     "unsloth/Phi-3-mini-4k-instruct-bnb-4bit", # Thay bằng model bạn dùng hoặc một model nhỏ để test
+    #     # model_name_or_path="path/to/your/lora_model_base" # Nếu test với model đã tải
+    # )
+    #
+    # if mock_llm_model and mock_tokenizer:
+    #     # Mock các thành phần RAG
+    #     class MockFAISSIndex:
+    #         def __init__(self): self.ntotal = 0
+    #         def search(self, query, k): return ([], []) # Trả về không có gì
+    #
+    #     class MockEmbeddingModel:
+    #         def encode(self, text, convert_to_tensor, device): return torch.randn(1, 10) # Vector dummy
+    #
+    #     class MockBM25Model:
+    #         def get_scores(self, query_tokens): return []
+    #
+    #     def mock_search_relevant_laws(**kwargs):
+    #         print(f"Mock search_relevant_laws called with query: {kwargs.get('query_text')}")
+    #         # Trả về một vài kết quả giả để test formatting
+    #         return [
+    #             {
+    #                 "text": "Người điều khiển xe máy không đội mũ bảo hiểm sẽ bị phạt tiền.",
+    #                 "metadata": {
+    #                     "source_document": "Nghị định 100/2019/NĐ-CP",
+    #                     "article": "6", "clause_number": "2", "point_id": "i",
+    #                     "article_title": "Xử phạt người điều khiển xe mô tô, xe gắn máy",
+    #                     "has_fine": True, "individual_fine_min": 200000, "individual_fine_max": 300000,
+    #                 }
+    #             }
+    #         ]
+    #
+    #     test_query = "Không đội mũ bảo hiểm xe máy phạt bao nhiêu?"
+    #     response = generate_response(
+    #         query=test_query,
+    #         llama_model=mock_llm_model,
+    #         tokenizer=mock_tokenizer,
+    #         faiss_index=MockFAISSIndex(),
+    #         embed_model=MockEmbeddingModel(),
+    #         chunks_data_list=[{"text": "dummy chunk", "metadata": {}}],
+    #         bm25_model=MockBM25Model(),
+    #         search_function=mock_search_relevant_laws, # Truyền hàm mock
+    #         search_k=1
+    #     )
+    #     print("\n--- Câu trả lời Test ---")
+    #     print(response)
+    # else:
+    #     print("Không thể tải mock LLM model để test.")
+    pass # Bỏ qua phần test nếu không có mock

models/embedding_model/1_Pooling/config.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fb410fd9c2ed3e3b66206997397b0cf0eff574b2c690071481cf80a77d3c11fa
+size 305

models/embedding_model/README.md

@@ -0,0 +1,168 @@
+---
+pipeline_tag: sentence-similarity
+tags:
+- sentence-transformers
+- feature-extraction
+- sentence-similarity
+- transformers
+library_name: generic
+language:
+- vi
+widget:
+- source_sentence: Làm thế nào Đại học Bách khoa Hà Nội thu hút sinh viên quốc tế?
+  sentences:
+  - >-
+    Đại học Bách khoa Hà Nội đã phát triển các chương trình đào tạo bằng tiếng
+    Anh để làm cho việc học tại đây dễ dàng hơn cho sinh viên quốc tế.
+  - >-
+    Môi trường học tập đa dạng và sự hỗ trợ đầy đủ cho sinh viên quốc tế tại Đại
+    học Bách khoa Hà Nội giúp họ thích nghi nhanh chóng.
+  - Hà Nội có khí hậu mát mẻ vào mùa thu.
+  - Các món ăn ở Hà Nội rất ngon và đa dạng.
+license: apache-2.0
+---
+
+# bkai-foundation-models/vietnamese-bi-encoder
+
+This is a [sentence-transformers](https://www.SBERT.net) model: It maps sentences & paragraphs to a 768 dimensional dense vector space and can be used for tasks like clustering or semantic search.
+
+We train the model on a merged training dataset that consists of: 
+  - MS Macro (translated into Vietnamese)
+  - SQuAD v2  (translated into Vietnamese)
+  - 80% of the training set from the Legal Text Retrieval Zalo 2021 challenge
+
+We use [phobert-base-v2](https://github.com/VinAIResearch/PhoBERT) as the pre-trained backbone.
+
+Here are the results on the remaining 20% of the training set from the Legal Text Retrieval Zalo 2021 challenge:
+
+|     Pretrained Model          |     Training Datasets                  |     Acc@1    |     Acc@10    |     Acc@100    |     Pre@10    |     MRR@10    |
+|-------------------------------|---------------------------------------|:------------:|:-------------:|:--------------:|:-------------:|:-------------:|
+|     [Vietnamese-SBERT](https://huggingface.co/keepitreal/vietnamese-sbert)     |     -                                 |     32.34    |      52.97    |      89.84     |      7.05     |      45.30    |
+|     PhoBERT-base-v2           |     MSMACRO                           |     47.81    |      77.19    |      92.34     |      7.72     |      58.37    |
+|     PhoBERT-base-v2                            |     MSMACRO + SQuADv2.0 + 80% Zalo    |     73.28    |      93.59    |      98.85     |      9.36     |      80.73    |
+
+
+<!--- Describe your model here -->
+
+## Usage (Sentence-Transformers)
+
+Using this model becomes easy when you have [sentence-transformers](https://www.SBERT.net) installed:
+
+```
+pip install -U sentence-transformers
+```
+
+Then you can use the model like this:
+
+```python
+from sentence_transformers import SentenceTransformer
+
+# INPUT TEXT MUST BE ALREADY WORD-SEGMENTED!
+sentences = ["Cô ấy là một người vui_tính .", "Cô ấy cười nói suốt cả ngày ."]
+
+model = SentenceTransformer('bkai-foundation-models/vietnamese-bi-encoder')
+embeddings = model.encode(sentences)
+print(embeddings)
+```
+
+
+## Usage (Widget HuggingFace)
+The widget use custom pipeline on top of the default pipeline by adding additional word segmenter before PhobertTokenizer. So you do not need to segment words before using the API:
+
+An example could be seen in Hosted inference API.
+ 
+
+## Usage (HuggingFace Transformers)
+
+Without [sentence-transformers](https://www.SBERT.net), you can use the model like this: First, you pass your input through the transformer model, then you have to apply the right pooling-operation on-top of the contextualized word embeddings.
+
+```python
+from transformers import AutoTokenizer, AutoModel
+import torch
+
+
+#Mean Pooling - Take attention mask into account for correct averaging
+def mean_pooling(model_output, attention_mask):
+    token_embeddings = model_output[0] #First element of model_output contains all token embeddings
+    input_mask_expanded = attention_mask.unsqueeze(-1).expand(token_embeddings.size()).float()
+    return torch.sum(token_embeddings * input_mask_expanded, 1) / torch.clamp(input_mask_expanded.sum(1), min=1e-9)
+
+
+# Sentences we want sentence embeddings, we could use pyvi, underthesea, RDRSegment to segment words
+sentences = ['Cô ấy là một người vui_tính .', 'Cô ấy cười nói suốt cả ngày .']
+
+# Load model from HuggingFace Hub
+tokenizer = AutoTokenizer.from_pretrained('bkai-foundation-models/vietnamese-bi-encoder')
+model = AutoModel.from_pretrained('bkai-foundation-models/vietnamese-bi-encoder')
+
+# Tokenize sentences
+encoded_input = tokenizer(sentences, padding=True, truncation=True, return_tensors='pt')
+
+# Compute token embeddings
+with torch.no_grad():
+    model_output = model(**encoded_input)
+
+# Perform pooling. In this case, mean pooling.
+sentence_embeddings = mean_pooling(model_output, encoded_input['attention_mask'])
+
+print("Sentence embeddings:")
+print(sentence_embeddings)
+```
+
+## Training
+
+The model was trained with the parameters:
+
+**DataLoader**:
+
+`torch.utils.data.dataloader.DataLoader` of length 17584 with parameters:
+
+```
+{'batch_size': 32, 'sampler': 'torch.utils.data.sampler.RandomSampler', 'batch_sampler': 'torch.utils.data.sampler.BatchSampler'}
+```
+
+**Loss**:
+
+`sentence_transformers.losses.MultipleNegativesRankingLoss.MultipleNegativesRankingLoss` with parameters:
+
+```
+{'scale': 20.0, 'similarity_fct': 'cos_sim'}
+```
+
+Parameters of the fit()-Method:
+
+```
+{
+    "epochs": 15,
+    "evaluation_steps": 0,
+    "evaluator": "NoneType",
+    "max_grad_norm": 1,
+    "optimizer_class": "<class 'torch.optim.adamw.AdamW'>",
+    "optimizer_params": {
+        "lr": 2e-05
+    },
+    "scheduler": "WarmupLinear",
+    "steps_per_epoch": null,
+    "warmup_steps": 1000,
+    "weight_decay": 0.01
+}
+```
+
+## Full Model Architecture
+
+```
+SentenceTransformer(
+  (0): Transformer({'max_seq_length': 256, 'do_lower_case': False}) with Transformer model: RobertaModel
+  (1): Pooling({'word_embedding_dimension': 768, 'pooling_mode_cls_token': False, 'pooling_mode_mean_tokens': True, 'pooling_mode_max_tokens': False, 'pooling_mode_mean_sqrt_len_tokens': False, 'pooling_mode_weightedmean_tokens': False, 'pooling_mode_lasttoken': False})
+)
+```
+
+### Please cite our manuscript if this dataset is used for your work
+```
+  @article{duc2024towards,
+    title={Towards Comprehensive Vietnamese Retrieval-Augmented Generation and Large Language Models},
+    author={Nguyen Quang Duc, Le Hai Son, Nguyen Duc Nhan, Nguyen Dich Nhat Minh, Le Thanh Huong, Dinh Viet Sang},
+    journal={arXiv preprint arXiv:2403.01616},
+    year={2024}
+  }
+```

models/embedding_model/added_tokens.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6887f87ac991379ea91aedb4dd5e1af4f6ee38693ec0ca1c2b6209559ce283d8
+size 25

models/embedding_model/config.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3af0fd876ee0aaaef684c5a2ad27e3e280b1593b127ed9ccefa7b0d81326de75
+size 699

models/embedding_model/config_sentence_transformers.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8010f6b1a201d350cecd92317f85096a0b0e59ca922783bdb06a535c44638507
+size 214

models/embedding_model/model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e681accadaec87e79901db0c3f68e33d996cba334633b6dd0b2483dba4f398e0
+size 540015464

models/embedding_model/modules.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:27e3a229cecaf4d6ec90fb8e439d6bd2da7b2e22ff49a23e0b0a293a5f3e413c
+size 242

models/embedding_model/sentence_bert_config.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:01d1055f90dbf0425135dbb95d2ef43f77c49802faec5a20fea87637dda4ea51
+size 56

models/embedding_model/special_tokens_map.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:edd71739099fe63dc2f70815facad5253c70ded0e0d4df49ef883ce4511af365
+size 1016

models/embedding_model/tokenizer_config.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:55f35d28e4d476184f88ae52cca59389c50de91547f9fa2f31eec661080f6032
+size 1229

models/lora_model_base/README.md

@@ -0,0 +1,202 @@
+---
+base_model: unsloth/llama-3.2-3b-instruct-unsloth-bnb-4bit
+library_name: peft
+---
+
+# Model Card for Model ID
+
+<!-- Provide a quick summary of what the model is/does. -->
+
+
+
+## Model Details
+
+### Model Description
+
+<!-- Provide a longer summary of what this model is. -->
+
+
+
+- **Developed by:** [More Information Needed]
+- **Funded by [optional]:** [More Information Needed]
+- **Shared by [optional]:** [More Information Needed]
+- **Model type:** [More Information Needed]
+- **Language(s) (NLP):** [More Information Needed]
+- **License:** [More Information Needed]
+- **Finetuned from model [optional]:** [More Information Needed]
+
+### Model Sources [optional]
+
+<!-- Provide the basic links for the model. -->
+
+- **Repository:** [More Information Needed]
+- **Paper [optional]:** [More Information Needed]
+- **Demo [optional]:** [More Information Needed]
+
+## Uses
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+### Direct Use
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+
+[More Information Needed]
+
+### Downstream Use [optional]
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+
+[More Information Needed]
+
+### Out-of-Scope Use
+
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+
+[More Information Needed]
+
+## Bias, Risks, and Limitations
+
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+
+[More Information Needed]
+
+### Recommendations
+
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+
+Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+
+## How to Get Started with the Model
+
+Use the code below to get started with the model.
+
+[More Information Needed]
+
+## Training Details
+
+### Training Data
+
+<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+
+[More Information Needed]
+
+### Training Procedure
+
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+
+#### Preprocessing [optional]
+
+[More Information Needed]
+
+
+#### Training Hyperparameters
+
+- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+
+#### Speeds, Sizes, Times [optional]
+
+<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+
+[More Information Needed]
+
+## Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+<!-- This should link to a Dataset Card if possible. -->
+
+[More Information Needed]
+
+#### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+[More Information Needed]
+
+#### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+[More Information Needed]
+
+### Results
+
+[More Information Needed]
+
+#### Summary
+
+
+
+## Model Examination [optional]
+
+<!-- Relevant interpretability work for the model goes here -->
+
+[More Information Needed]
+
+## Environmental Impact
+
+<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+
+- **Hardware Type:** [More Information Needed]
+- **Hours used:** [More Information Needed]
+- **Cloud Provider:** [More Information Needed]
+- **Compute Region:** [More Information Needed]
+- **Carbon Emitted:** [More Information Needed]
+
+## Technical Specifications [optional]
+
+### Model Architecture and Objective
+
+[More Information Needed]
+
+### Compute Infrastructure
+
+[More Information Needed]
+
+#### Hardware
+
+[More Information Needed]
+
+#### Software
+
+[More Information Needed]
+
+## Citation [optional]
+
+<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+
+**BibTeX:**
+
+[More Information Needed]
+
+**APA:**
+
+[More Information Needed]
+
+## Glossary [optional]
+
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+
+[More Information Needed]
+
+## More Information [optional]
+
+[More Information Needed]
+
+## Model Card Authors [optional]
+
+[More Information Needed]
+
+## Model Card Contact
+
+[More Information Needed]
+### Framework versions
+
+- PEFT 0.15.0

models/lora_model_base/adapter_config.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8aeb2d2885fc709fb0e526d2cc01969910c0b284c151899369c0cb6b0d55a862
+size 914

models/lora_model_base/adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0528f0d3cff8cde7d2ac7cda02a9f50a384ad836eff4d60bff86fe3cbb9a6060
+size 97307544

models/lora_model_base/special_tokens_map.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8e4e823b62ca673865ac60b203c51d0d3f0f4e21f806323cd7d35616cb457e0d
+size 477

models/lora_model_base/tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6b9e4e7fb171f92fd137b777cc2714bf87d11576700a1dcd7a399e7bbe39537b
+size 17209920

models/lora_model_base/tokenizer_config.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d08d598958a22a2a5ea166e5e4e055e9c3caa9a52fae77c0f7fb45e835fad479
+size 56738

retrieval.py

@@ -0,0 +1,579 @@
+# retrieval.py
+
+import json
+import re
+import numpy as np
+import faiss # Thư viện này cần được cài đặt (faiss-cpu hoặc faiss-gpu)
+from collections import defaultdict
+from typing import List, Dict, Any, Tuple, Optional, Callable
+
+# --- 1. CÁC HẰNG SỐ VÀ MAP CHO LOẠI PHƯƠNG TIỆN ---
+VEHICLE_TYPE_MAP: Dict[str, List[str]] = {
+    "xe máy": ["xe máy", "xe mô tô", "xe gắn máy", "xe máy điện", "mô tô hai bánh", "mô tô ba bánh"],
+    "ô tô": ["xe ô tô", "ô tô con", "ô tô tải", "ô tô khách", "xe con", "xe tải", "xe khách", "ô tô điện"],
+    "xe cơ giới": ["xe cơ giới"], # Loại chung hơn
+    "xe thô sơ": ["xe thô sơ", "xe đạp", "xích lô", "xe đạp điện"], # Thêm xe đạp điện vào xe thô sơ
+    "người đi bộ": ["người đi bộ"],
+    # Thêm các loại khác nếu cần, ví dụ "xe chuyên dùng" nếu muốn tách riêng
+}
+
+# --- 2. HÀM TIỆN ÍCH ---
+
+def get_standardized_vehicle_type(text_input: Optional[str]) -> Optional[str]:
+    """
+    Suy luận và chuẩn hóa loại phương tiện từ một chuỗi text.
+    Ưu tiên các loại cụ thể trước, sau đó đến các loại chung hơn.
+    """
+    if not text_input or not isinstance(text_input, str):
+        return None
+    
+    text_lower = text_input.lower()
+    
+    # Ưu tiên kiểm tra "xe máy" và các biến thể trước "xe cơ giới"
+    # Cẩn thận với "xe máy chuyên dùng"
+    is_moto = any(re.search(r'\b' + re.escape(kw) + r'\b', text_lower) for kw in VEHICLE_TYPE_MAP["xe máy"])
+    if is_moto:
+        # Tránh trường hợp "xe máy chuyên dùng" bị tính là "xe máy"
+        # nếu "xe máy chuyên dùng" là một category riêng hoặc cần xử lý đặc biệt.
+        # Hiện tại, nếu có "chuyên dùng" và "xe máy", nó vẫn sẽ là "xe máy" nếu không có category "xe máy chuyên dùng".
+        if "chuyên dùng" in text_lower and "xe máy chuyên dùng" not in text_lower: # Logic này có thể cần review tùy theo định nghĩa
+             # Nếu bạn có category "xe máy chuyên dùng" trong VEHICLE_TYPE_MAP, nó sẽ được xử lý ở vòng lặp sau.
+             # Nếu không, "xe máy chuyên dùng" vẫn có thể bị coi là "xe máy".
+             pass # Để nó rơi xuống các kiểm tra khác nếu cần
+        else:
+            return "xe máy"
+            
+    # Kiểm tra "ô tô" và các biến thể
+    is_car = any(re.search(r'\b' + re.escape(kw) + r'\b', text_lower) for kw in VEHICLE_TYPE_MAP["ô tô"])
+    if is_car:
+        return "ô tô"
+        
+    # Kiểm tra các loại chung hơn hoặc khác
+    # Thứ tự này quan trọng nếu có sự chồng chéo (ví dụ: "xe cơ giới" bao gồm "ô tô", "xe máy")
+    # Đã xử lý ô tô, xe máy ở trên nên thứ tự ở đây ít quan trọng hơn giữa các loại còn lại.
+    for standard_type, keywords in VEHICLE_TYPE_MAP.items():
+        if standard_type in ["xe máy", "ô tô"]: # Đã xử lý ở trên
+            continue
+        if any(re.search(r'\b' + re.escape(kw) + r'\b', text_lower) for kw in keywords):
+            return standard_type
+            
+    return None # Trả về None nếu không khớp rõ ràng
+
+def tokenize_vi_for_bm25_setup(text: str) -> List[str]:
+    """
+    Tokenize tiếng Việt đơn giản cho BM25: lowercase, loại bỏ dấu câu, split theo khoảng trắng.
+    """
+    text = text.lower()
+    text = re.sub(r'[^\w\s]', '', text) # Loại bỏ các ký tự không phải chữ, số, hoặc khoảng trắng
+    return text.split()
+
+# --- 3. HÀM XỬ LÝ DỮ LIỆU LUẬT TỪ JSON SANG CHUNKS ---
+def process_law_data_to_chunks(structured_data_input: Any) -> List[Dict[str, Any]]:
+    """
+    Xử lý dữ liệu luật có cấu trúc (từ JSON) thành một danh sách phẳng các "chunks".
+    Mỗi chunk bao gồm "text" và "metadata".
+    """
+    flat_list: List[Dict[str, Any]] = []
+
+    if isinstance(structured_data_input, dict) and "article" in structured_data_input:
+        articles_list: List[Dict[str, Any]] = [structured_data_input]
+    elif isinstance(structured_data_input, list):
+        articles_list = structured_data_input
+    else:
+        print("Lỗi: Dữ liệu đầu vào không phải là danh sách các Điều luật hoặc một đối tượng Điều luật.")
+        return flat_list
+
+    for article_data in articles_list:
+        if not isinstance(article_data, dict):
+            # print(f"Cảnh báo: Bỏ qua mục không phải dict trong articles_list: {article_data}")
+            continue
+
+        raw_article_title = article_data.get("article_title", "")
+        article_metadata_base = {
+            "source_document": article_data.get("source_document"),
+            "article": article_data.get("article"), # Số điều, ví dụ "Điều 5"
+            "article_title": raw_article_title # Tiêu đề của Điều, ví dụ "Xử phạt người điều khiển..."
+        }
+        
+        article_level_vehicle_type = get_standardized_vehicle_type(raw_article_title) or "không xác định"
+
+        clauses = article_data.get("clauses", [])
+        if not isinstance(clauses, list):
+            # print(f"Cảnh báo: 'clauses' trong Điều {article_data.get('article')} không phải list.")
+            continue
+
+        for clause_data in clauses:
+            if not isinstance(clause_data, dict):
+                # print(f"Cảnh báo: Bỏ qua mục không phải dict trong 'clauses' của Điều {article_data.get('article')}")
+                continue
+
+            clause_metadata_base = article_metadata_base.copy()
+            clause_number = clause_data.get("clause_number") # Số khoản, ví dụ "1" hoặc "1a"
+            clause_metadata_base.update({"clause_number": clause_number})
+            
+            clause_summary_data = clause_data.get("clause_metadata_summary")
+            if isinstance(clause_summary_data, dict):
+                clause_metadata_base["overall_fine_note_for_clause_text"] = clause_summary_data.get("overall_fine_note_for_clause")
+                clause_metadata_base["overall_points_deduction_note_for_clause_text"] = clause_summary_data.get("overall_points_deduction_note_for_clause")
+
+            points_in_clause = clause_data.get("points_in_clause", [])
+            if not isinstance(points_in_clause, list):
+                # print(f"Cảnh báo: 'points_in_clause' trong Khoản {clause_number} của Điều {article_data.get('article')} không phải list.")
+                continue
+            
+            if points_in_clause: # Nếu có các Điểm trong Khoản
+                for point_data in points_in_clause:
+                    if not isinstance(point_data, dict):
+                        # print(f"Cảnh báo: Bỏ qua mục không phải dict trong 'points_in_clause'.")
+                        continue
+                        
+                    chunk_text = point_data.get("point_text_original")
+                    if not chunk_text: chunk_text = point_data.get("violation_description_summary") # Fallback
+                    if not chunk_text: continue # Bỏ qua nếu không có text
+
+                    current_chunk_metadata = clause_metadata_base.copy()
+                    current_chunk_metadata["point_id"] = point_data.get("point_id") # ID của điểm, ví dụ "a"
+                    current_chunk_metadata["violation_description_summary"] = point_data.get("violation_description_summary")
+                    
+                    # 1. Làm phẳng 'penalties_detail'
+                    current_chunk_metadata.update({
+                        'has_fine': False, 'has_points_deduction': False,
+                        'has_license_suspension': False, 'has_confiscation': False
+                    })
+                    penalty_types_for_this_point: List[str] = []
+                    points_values: List[Any] = []
+                    s_min_months: List[float] = [] # Sửa thành float để chứa giá trị tháng lẻ
+                    s_max_months: List[float] = []
+                    confiscation_items_list: List[str] = []
+
+                    penalties = point_data.get("penalties_detail", [])
+                    if isinstance(penalties, list):
+                        for p_item in penalties:
+                            if not isinstance(p_item, dict): continue
+                            p_type_original, p_details = p_item.get("penalty_type"), p_item.get("details", {})
+                            if p_type_original: penalty_types_for_this_point.append(str(p_type_original))
+                            if not isinstance(p_details, dict): continue
+                            
+                            p_type_lower = str(p_type_original).lower()
+                            if "phạt tiền" in p_type_lower:
+                                current_chunk_metadata['has_fine'] = True
+                                if p_details.get("individual_fine_min") is not None: current_chunk_metadata['individual_fine_min'] = p_details.get("individual_fine_min")
+                                if p_details.get("individual_fine_max") is not None: current_chunk_metadata['individual_fine_max'] = p_details.get("individual_fine_max")
+                            if "trừ điểm" in p_type_lower or "điểm giấy phép lái xe" in p_type_lower : # Mở rộng kiểm tra
+                                current_chunk_metadata['has_points_deduction'] = True
+                                if p_details.get("points_deducted") is not None: points_values.append(p_details.get("points_deducted"))
+                            if "tước quyền sử dụng giấy phép lái xe" in p_type_lower or "tước bằng lái" in p_type_lower:
+                                current_chunk_metadata['has_license_suspension'] = True
+                                if p_details.get("suspension_duration_min_months") is not None: s_min_months.append(float(p_details.get("suspension_duration_min_months")))
+                                if p_details.get("suspension_duration_max_months") is not None: s_max_months.append(float(p_details.get("suspension_duration_max_months")))
+                            if "tịch thu" in p_type_lower:
+                                current_chunk_metadata['has_confiscation'] = True
+                                if p_details.get("confiscation_item"): confiscation_items_list.append(str(p_details.get("confiscation_item")))
+                    
+                    if penalty_types_for_this_point: current_chunk_metadata['penalty_types_str'] = ", ".join(sorted(list(set(penalty_types_for_this_point))))
+                    if points_values: current_chunk_metadata['points_deducted_values_str'] = ", ".join(map(str, sorted(list(set(points_values)))))
+                    if s_min_months: current_chunk_metadata['suspension_min_months'] = min(s_min_months)
+                    if s_max_months: current_chunk_metadata['suspension_max_months'] = max(s_max_months)
+                    if confiscation_items_list: current_chunk_metadata['confiscation_items_str'] = ", ".join(sorted(list(set(confiscation_items_list))))
+
+                    # 2. Thông tin tốc độ
+                    if point_data.get("speed_limit") is not None: current_chunk_metadata['speed_limit_value'] = point_data.get("speed_limit")
+                    if point_data.get("speed_limit_min") is not None: current_chunk_metadata['speed_limit_min_value'] = point_data.get("speed_limit_min")
+                    if point_data.get("speed_type"): current_chunk_metadata['speed_category'] = point_data.get("speed_type")
+
+                    # 3. Thông tin loại xe/đường cụ thể từ point_data
+                    speed_limits_extra = point_data.get("speed_limits_by_vehicle_type_and_road_type", [])
+                    point_specific_vehicle_types_raw: List[str] = []
+                    point_specific_road_types: List[str] = []
+                    if isinstance(speed_limits_extra, list):
+                        for sl_item in speed_limits_extra:
+                            if isinstance(sl_item, dict):
+                                if sl_item.get("vehicle_type"): point_specific_vehicle_types_raw.append(str(sl_item.get("vehicle_type")).lower())
+                                if sl_item.get("road_type"): point_specific_road_types.append(str(sl_item.get("road_type")).lower())
+                    if point_specific_vehicle_types_raw: current_chunk_metadata['point_specific_vehicle_types_str'] = ", ".join(sorted(list(set(point_specific_vehicle_types_raw))))
+                    if point_specific_road_types: current_chunk_metadata['point_specific_road_types_str'] = ", ".join(sorted(list(set(point_specific_road_types))))
+                    
+                    # 4. Gán 'applicable_vehicle_type' chính
+                    derived_vehicle_type_from_point = "không xác định"
+                    if point_specific_vehicle_types_raw:
+                        normalized_types_from_point_data = set()
+                        for vt_raw in set(point_specific_vehicle_types_raw):
+                            standard_type = get_standardized_vehicle_type(vt_raw)
+                            if standard_type: normalized_types_from_point_data.add(standard_type)
+                        
+                        if len(normalized_types_from_point_data) == 1:
+                            derived_vehicle_type_from_point = list(normalized_types_from_point_data)[0]
+                        elif len(normalized_types_from_point_data) > 1:
+                            # Xử lý trường hợp có nhiều loại xe đã chuẩn hóa
+                            if "ô tô" in normalized_types_from_point_data and "xe máy" in normalized_types_from_point_data:
+                                derived_vehicle_type_from_point = "ô tô và xe máy"
+                            # Có thể thêm các logic ưu tiên khác nếu cần (ví dụ: nếu có "xe cơ giới" và "ô tô" -> "ô tô")
+                            elif "ô tô" in normalized_types_from_point_data: derived_vehicle_type_from_point = "ô tô"
+                            elif "xe máy" in normalized_types_from_point_data: derived_vehicle_type_from_point = "xe máy"
+                            else: # Nếu không có cặp ưu tiên rõ ràng
+                                derived_vehicle_type_from_point = "nhiều loại cụ thể" # Hoặc join các loại: ", ".join(sorted(list(normalized_types_from_point_data)))
+                    
+                    # Ưu tiên thông tin từ point, nếu không rõ ràng thì mới dùng từ article
+                    # Các loại được coi là rõ ràng: "ô tô", "xe máy", "xe cơ giới", "xe thô sơ", "người đi bộ", "ô tô và xe máy"
+                    clear_types = ["ô tô", "xe máy", "xe cơ giới", "xe thô sơ", "người đi bộ", "ô tô và xe máy"]
+                    if derived_vehicle_type_from_point not in clear_types and derived_vehicle_type_from_point != "không xác định":
+                         # Nếu là "nhiều loại cụ thể" mà không phải "ô tô và xe máy" hoặc các loại không rõ ràng khác
+                         current_chunk_metadata['applicable_vehicle_type'] = article_level_vehicle_type
+                    elif derived_vehicle_type_from_point == "không xác định":
+                         current_chunk_metadata['applicable_vehicle_type'] = article_level_vehicle_type
+                    else: # Các trường hợp còn lại (rõ ràng từ point)
+                         current_chunk_metadata['applicable_vehicle_type'] = derived_vehicle_type_from_point
+                         
+                    # 5. Các trường khác
+                    if point_data.get("applies_to"): current_chunk_metadata['applies_to_context'] = point_data.get("applies_to")
+                    if point_data.get("location"): current_chunk_metadata['specific_location_info'] = point_data.get("location")
+                    
+                    final_metadata_cleaned = {k: v for k, v in current_chunk_metadata.items() if v is not None}
+                    flat_list.append({ "text": chunk_text, "metadata": final_metadata_cleaned })
+            
+            else: # Nếu Khoản không có Điểm nào, thì text của Khoản là một chunk
+                chunk_text = clause_data.get("clause_text_original")
+                if chunk_text: # Chỉ thêm nếu có text
+                    current_clause_level_metadata = clause_metadata_base.copy()
+                    # Với chunk cấp độ Khoản, loại xe sẽ lấy từ article_level_vehicle_type
+                    current_clause_level_metadata['applicable_vehicle_type'] = article_level_vehicle_type
+                    # Kiểm tra xem có thông tin phạt tiền tổng thể ở Khoản không
+                    if current_clause_level_metadata.get("overall_fine_note_for_clause_text"):
+                        current_clause_level_metadata['has_fine_clause_level'] = True # Dùng để boost nếu cần
+                    
+                    final_metadata_cleaned = {k:v for k,v in current_clause_level_metadata.items() if v is not None}
+                    flat_list.append({ "text": chunk_text, "metadata": final_metadata_cleaned })
+    return flat_list
+
+# --- 4. HÀM PHÂN TÍCH QUERY ---
+def analyze_query(query_text: str) -> Dict[str, Any]:
+    """
+    Phân tích query để xác định ý định của người dùng (ví dụ: hỏi về phạt tiền, điểm, loại xe...).
+    """
+    query_lower = query_text.lower()
+    analysis: Dict[str, Any] = {
+        "mentions_fine": bool(re.search(r'tiền|phạt|bao nhiêu đồng|bao nhiêu tiền|mức phạt|xử phạt hành chính|nộp phạt', query_lower)),
+        "mentions_points": bool(re.search(r'điểm|trừ điểm|mấy điểm|trừ bao nhiêu điểm|bằng lái|gplx|giấy phép lái xe', query_lower)),
+        "mentions_suspension": bool(re.search(r'tước bằng|tước giấy phép lái xe|giam bằng|treo bằng|thu bằng lái|tước quyền sử dụng', query_lower)),
+        "mentions_confiscation": bool(re.search(r'tịch thu|thu xe|thu phương tiện', query_lower)),
+        "mentions_max_speed": bool(re.search(r'tốc độ tối đa|giới hạn tốc độ|chạy quá tốc độ|vượt tốc độ', query_lower)),
+        "mentions_min_speed": bool(re.search(r'tốc độ tối thiểu|chạy chậm hơn', query_lower)),
+        "mentions_safe_distance": bool(re.search(r'khoảng cách an toàn|cự ly an toàn|cự ly tối thiểu|giữ khoảng cách', query_lower)),
+        "mentions_remedial_measures": bool(re.search(r'biện pháp khắc phục|khắc phục hậu quả', query_lower)),
+        "vehicle_type_query": None, # Sẽ được điền bằng loại xe chuẩn hóa nếu có
+    }
+
+    # Sử dụng lại VEHICLE_TYPE_MAP để chuẩn hóa loại xe trong query
+    # Ưu tiên loại cụ thể trước
+    queried_vehicle_standardized = get_standardized_vehicle_type(query_lower)
+    if queried_vehicle_standardized:
+        analysis["vehicle_type_query"] = queried_vehicle_standardized
+    
+    return analysis
+
+# --- 5. HÀM TÌM KIẾM KẾT HỢP (HYBRID SEARCH) ---
+def search_relevant_laws(
+        query_text: str,
+        embedding_model, # Kiểu dữ liệu: SentenceTransformer model
+        faiss_index,     # Kiểu dữ liệu: faiss.Index
+        chunks_data: List[Dict[str, Any]],
+        bm25_model,      # Kiểu dữ liệu: BM25Okapi model
+        k: int = 5,
+        initial_k_multiplier: int = 10,
+        rrf_k_constant: int = 60,
+        # Trọng số cho các loại boost (có thể điều chỉnh)
+        boost_fine: float = 0.15,
+        boost_points: float = 0.15,
+        boost_both_fine_points: float = 0.10, # Boost thêm nếu khớp cả hai
+        boost_vehicle_type: float = 0.20,
+        boost_suspension: float = 0.18,
+        boost_confiscation: float = 0.18,
+        boost_max_speed: float = 0.15,
+        boost_min_speed: float = 0.15,
+        boost_safe_distance: float = 0.12,
+        boost_remedial_measures: float = 0.10
+    ) -> List[Dict[str, Any]]:
+    """
+    Thực hiện tìm kiếm kết hợp (semantic + keyword) với RRF và metadata re-ranking.
+    """
+    if k <= 0:
+        print("Lỗi: k (số lượng kết quả) phải là số dương.")
+        return []
+    if not chunks_data:
+        print("Lỗi: chunks_data rỗng, không thể tìm kiếm.")
+        return []
+
+    print(f"\n🔎 Đang tìm kiếm (Hybrid) cho truy vấn: '{query_text}'")
+
+    # === 1. Phân tích Query ===
+    query_analysis = analyze_query(query_text)
+    # print(f"   Phân tích query: {json.dumps(query_analysis, ensure_ascii=False, indent=2)}")
+
+    num_vectors_in_index = faiss_index.ntotal
+    if num_vectors_in_index == 0:
+        print("Lỗi: FAISS index rỗng.")
+        return []
+
+    # Số lượng ứng viên ban đầu từ mỗi retriever
+    num_candidates_each_retriever = max(min(k * initial_k_multiplier, num_vectors_in_index), min(k, num_vectors_in_index))
+    if num_candidates_each_retriever == 0:
+        print(f"   Không thể lấy đủ số lượng ứng viên ban đầu (num_candidates = 0).")
+        return []
+    
+    # === 2. Semantic Search (FAISS) ===
+    semantic_indices_raw: np.ndarray = np.array([[]], dtype=int) # Khởi tạo rỗng
+    try:
+        query_embedding_tensor = embedding_model.encode(
+            [query_text], convert_to_tensor=True, device=embedding_model.device
+        )
+        query_embedding_np = query_embedding_tensor.cpu().numpy().astype('float32')
+        faiss.normalize_L2(query_embedding_np) # Chuẩn hóa vector query
+        # print(f"   Đã tạo và chuẩn hóa vector truy vấn shape: {query_embedding_np.shape}")
+        # print(f"   Tìm kiếm {num_candidates_each_retriever} kết quả ngữ nghĩa (FAISS)...")
+        _, semantic_indices_raw = faiss_index.search(query_embedding_np, num_candidates_each_retriever)
+        # print(f"   ✅ Tìm kiếm ngữ nghĩa (FAISS) hoàn tất.")
+    except Exception as e:
+        print(f"Lỗi khi tìm kiếm ngữ nghĩa (FAISS): {e}")
+        # semantic_indices_raw đã được khởi tạo là rỗng
+
+    # === 3. Keyword Search (BM25) ===
+    # print(f"   Tìm kiếm {num_candidates_each_retriever} kết quả từ khóa (BM25)...")
+    tokenized_query_bm25 = tokenize_vi_for_bm25_setup(query_text)
+    top_bm25_results: List[Dict[str, Any]] = []
+    try:
+        if bm25_model and tokenized_query_bm25:
+            all_bm25_scores = bm25_model.get_scores(tokenized_query_bm25)
+            # Lấy chỉ số và score cho các document có score > 0
+            bm25_results_with_indices = [
+                {'index': i, 'score': score} for i, score in enumerate(all_bm25_scores) if score > 0
+            ]
+            # Sắp xếp theo score giảm dần
+            bm25_results_with_indices.sort(key=lambda x: x['score'], reverse=True)
+            top_bm25_results = bm25_results_with_indices[:num_candidates_each_retriever]
+            # print(f"   ✅ Tìm kiếm từ khóa (BM25) hoàn tất, tìm thấy {len(top_bm25_results)} ứng viên.")
+        else:
+            # print("   Cảnh báo: BM25 model hoặc tokenized query không hợp lệ, bỏ qua BM25.")
+            pass
+    except Exception as e:
+        print(f"Lỗi khi tìm kiếm từ khóa (BM25): {e}")
+
+    # === 4. Result Fusion (Reciprocal Rank Fusion - RRF) ===
+    # print(f"   Kết hợp kết quả từ FAISS và BM25 bằng RRF (k_const={rrf_k_constant})...")
+    rrf_scores: Dict[int, float] = defaultdict(float)
+    all_retrieved_indices_set: set[int] = set()
+
+    if semantic_indices_raw.size > 0:
+        for rank, doc_idx_int in enumerate(semantic_indices_raw[0]):
+            doc_idx = int(doc_idx_int) # Đảm bảo là int
+            if 0 <= doc_idx < len(chunks_data): # Kiểm tra doc_idx hợp lệ với chunks_data
+                rrf_scores[doc_idx] += 1.0 / (rrf_k_constant + rank)
+                all_retrieved_indices_set.add(doc_idx)
+
+    for rank, item in enumerate(top_bm25_results):
+        doc_idx = item['index']
+        if 0 <= doc_idx < len(chunks_data):
+            rrf_scores[doc_idx] += 1.0 / (rrf_k_constant + rank)
+            all_retrieved_indices_set.add(doc_idx)
+
+    fused_initial_results: List[Dict[str, Any]] = []
+    for doc_idx in all_retrieved_indices_set:
+        fused_initial_results.append({
+            'index': doc_idx,
+            'fused_score': rrf_scores[doc_idx]
+        })
+    fused_initial_results.sort(key=lambda x: x['fused_score'], reverse=True)
+    # print(f"   ✅ Kết hợp RRF hoàn tất, có {len(fused_initial_results)} ứng viên duy nhất.")
+
+    # === 5. Xử lý Metadata, Lọc và Tái xếp hạng cuối cùng ===
+    final_processed_results: List[Dict[str, Any]] = []
+    # Xử lý metadata cho số lượng ứng viên lớn hơn để có đủ lựa chọn sau khi lọc
+    num_to_process_metadata = min(len(fused_initial_results), num_candidates_each_retriever * 2 if num_candidates_each_retriever > 0 else k * 3)
+    
+    # print(f"   Xử lý metadata và tính điểm cuối cùng cho top {num_to_process_metadata} ứng viên lai ghép...")
+    for rank_idx, res_item in enumerate(fused_initial_results[:num_to_process_metadata]):
+        result_index = res_item['index']
+        base_score_from_fusion = res_item['fused_score']
+        metadata_boost_components: Dict[str, float] = defaultdict(float)
+        passes_all_strict_filters = True
+
+        try:
+            original_chunk = chunks_data[result_index]
+            chunk_metadata = original_chunk.get('metadata', {})
+            chunk_text_lower = original_chunk.get('text', '').lower()
+
+            # 5.1 & 5.2: Tiền phạt và Điểm phạt
+            has_fine_info_in_chunk = chunk_metadata.get("has_fine", False) or chunk_metadata.get("has_fine_clause_level", False)
+            has_points_info_in_chunk = chunk_metadata.get("has_points_deduction", False)
+
+            if query_analysis["mentions_fine"]:
+                if has_fine_info_in_chunk:
+                    metadata_boost_components["fine"] += boost_fine
+                elif not query_analysis["mentions_points"]: # Chỉ hỏi tiền mà chunk không có -> lọc
+                    passes_all_strict_filters = False
+            
+            if query_analysis["mentions_points"]:
+                if has_points_info_in_chunk:
+                    metadata_boost_components["points"] += boost_points
+                elif not query_analysis["mentions_fine"]: # Chỉ hỏi điểm mà chunk không có -> lọc
+                    passes_all_strict_filters = False
+            
+            if query_analysis["mentions_fine"] and query_analysis["mentions_points"]:
+                if not has_fine_info_in_chunk and not has_points_info_in_chunk: # Query hỏi cả hai mà chunk ko có cả hai
+                    passes_all_strict_filters = False
+                elif has_fine_info_in_chunk and has_points_info_in_chunk:
+                    metadata_boost_components["both_fine_points"] += boost_both_fine_points
+            
+            # 5.3. Loại xe
+            queried_vehicle = query_analysis["vehicle_type_query"]
+            if queried_vehicle:
+                applicable_vehicle_meta = chunk_metadata.get("applicable_vehicle_type", "").lower()
+                point_specific_vehicles_meta = chunk_metadata.get("point_specific_vehicle_types_str", "").lower()
+                article_title_lower = chunk_metadata.get("article_title", "").lower()
+
+                match_vehicle = False
+                if queried_vehicle in applicable_vehicle_meta: match_vehicle = True
+                elif queried_vehicle in point_specific_vehicles_meta: match_vehicle = True
+                # Kiểm tra xem queried_vehicle (đã chuẩn hóa) có trong article_title không
+                elif queried_vehicle in article_title_lower: match_vehicle = True # Đơn giản hóa, có thể dùng regex nếu cần chính xác hơn
+                # Kiểm tra xem queried_vehicle (đã chuẩn hóa) có trong chunk_text không
+                elif queried_vehicle in chunk_text_lower: match_vehicle = True
+
+
+                if match_vehicle:
+                    metadata_boost_components["vehicle_type"] += boost_vehicle_type
+                else:
+                    # Logic lọc: nếu query có loại xe cụ thể, mà applicable_vehicle_type của chunk là một loại khác
+                    # và không phải là "không xác định", "nhiều loại cụ thể", hoặc loại cha chung ("xe cơ giới" cho "ô tô")
+                    if applicable_vehicle_meta and \
+                       applicable_vehicle_meta not in ["không xác định", "nhiều loại cụ thể", "ô tô và xe máy"] and \
+                       not (applicable_vehicle_meta == "xe cơ giới" and queried_vehicle in ["ô tô", "xe máy"]):
+                        passes_all_strict_filters = False
+            
+            # 5.4. Tước quyền sử dụng GPLX
+            if query_analysis["mentions_suspension"] and chunk_metadata.get("has_license_suspension"):
+                metadata_boost_components["suspension"] += boost_suspension
+            
+            # 5.5. Tịch thu
+            if query_analysis["mentions_confiscation"] and chunk_metadata.get("has_confiscation"):
+                metadata_boost_components["confiscation"] += boost_confiscation
+            
+            # 5.6. Tốc độ tối đa
+            if query_analysis["mentions_max_speed"]:
+                if chunk_metadata.get("speed_limit_value") is not None or \
+                   "tốc độ tối đa" in chunk_metadata.get("speed_category","").lower() or \
+                   any(kw in chunk_text_lower for kw in ["quá tốc độ", "tốc độ tối đa", "vượt tốc độ quy định"]):
+                    metadata_boost_components["max_speed"] += boost_max_speed
+
+            # 5.7. Tốc độ tối thiểu
+            if query_analysis["mentions_min_speed"]:
+                if chunk_metadata.get("speed_limit_min_value") is not None or \
+                   "tốc độ tối thiểu" in chunk_metadata.get("speed_category","").lower() or \
+                   "tốc độ tối thiểu" in chunk_text_lower:
+                    metadata_boost_components["min_speed"] += boost_min_speed
+
+            # 5.8. Khoảng cách an toàn
+            if query_analysis["mentions_safe_distance"]:
+                if any(kw in chunk_text_lower for kw in ["khoảng cách an toàn", "cự ly an toàn", "cự ly tối thiểu", "giữ khoảng cách"]):
+                    metadata_boost_components["safe_distance"] += boost_safe_distance
+            
+            # 5.9. Biện pháp khắc phục
+            if query_analysis["mentions_remedial_measures"]:
+                if any(kw in chunk_text_lower for kw in ["biện pháp khắc phục", "khắc phục hậu quả"]):
+                    metadata_boost_components["remedial_measures"] += boost_remedial_measures
+
+            if not passes_all_strict_filters:
+                continue
+
+            total_metadata_boost = sum(metadata_boost_components.values())
+            final_score_calculated = base_score_from_fusion + total_metadata_boost
+
+            final_processed_results.append({
+                "rank_after_fusion": rank_idx + 1,
+                "index": int(result_index),
+                "base_score_rrf": float(base_score_from_fusion),
+                "metadata_boost_components": dict(metadata_boost_components), # Lưu lại để debug
+                "metadata_boost_total": float(total_metadata_boost),
+                "final_score": final_score_calculated,
+                "text": original_chunk.get('text', '*Không có text*'),
+                "metadata": chunk_metadata, # Giữ nguyên metadata gốc
+                "query_analysis_for_boost": query_analysis # (Tùy chọn) Lưu lại query analysis dùng cho boosting
+            })
+
+        except IndexError:
+            print(f"Lỗi Index: Chỉ số {result_index} nằm ngoài chunks_data (size: {len(chunks_data)}). Bỏ qua chunk này.")
+        except Exception as e:
+            print(f"Lỗi khi xử lý ứng viên lai ghép tại chỉ số {result_index}: {e}. Bỏ qua chunk này.")
+
+    final_processed_results.sort(key=lambda x: x["final_score"], reverse=True)
+    final_results_top_k = final_processed_results[:k]
+
+    print(f"   ✅ Xử lý, kết hợp metadata boost và tái xếp hạng hoàn tất. Trả về {len(final_results_top_k)} kết quả.")
+    return final_results_top_k
+
+
+# --- (Tùy chọn) Hàm main để test nhanh file này ---
+if __name__ == '__main__':
+    print("Chạy test cho retrieval.py...")
+
+    # --- Test get_standardized_vehicle_type ---
+    print("\n--- Test get_standardized_vehicle_type ---")
+    test_vehicles = [
+        "người điều khiển xe ô tô con", "xe gắn máy", "xe cơ giới", "xe máy chuyên dùng",
+        "xe đạp điện", "người đi bộ", "ô tô tải và xe mô tô", None, ""
+    ]
+    for tv in test_vehicles:
+        print(f"'{tv}' -> '{get_standardized_vehicle_type(tv)}'")
+
+    # --- Test analyze_query ---
+    print("\n--- Test analyze_query ---")
+    test_queries = [
+        "xe máy không gương phạt bao nhiêu tiền?",
+        "ô tô chạy quá tốc độ 20km bị trừ mấy điểm gplx",
+        "đi bộ ở đâu thì đúng luật",
+        "biện pháp khắc phục khi gây tai nạn là gì"
+    ]
+    for tq in test_queries:
+        print(f"Query: '{tq}'\nAnalysis: {json.dumps(analyze_query(tq), indent=2, ensure_ascii=False)}")
+
+    # --- Test process_law_data_to_chunks (cần file JSON mẫu) ---
+    # Giả sử bạn có file JSON mẫu 'sample_law_data.json' cùng cấp
+    # sample_data = {
+    #     "article": "Điều 5",
+    #     "article_title": "Xử phạt người điều khiển xe ô tô và các loại xe tương tự xe ô tô vi phạm quy tắc giao thông đường bộ",
+    #     "source_document": "Nghị định 100/2019/NĐ-CP",
+    #     "clauses": [
+    #         {
+    #             "clause_number": "1",
+    #             "clause_text_original": "Phạt tiền từ 200.000 đồng đến 400.000 đồng đối với người điều khiển xe thực hiện một trong các hành vi vi phạm sau đây:",
+    #             "points_in_clause": [
+    #                 {
+    #                     "point_id": "a",
+    #                     "point_text_original": "Không chấp hành hiệu lệnh, chỉ dẫn của biển báo hiệu, vạch kẻ đường, trừ các hành vi vi phạm quy định tại điểm a khoản 2, điểm c khoản 3, điểm đ khoản 4, điểm g khoản 5, điểm b khoản 6, điểm b khoản 7, điểm d khoản 8 Điều này;",
+    #                     "penalties_detail": [
+    #                         {"penalty_type": "Phạt tiền", "details": {"individual_fine_min": 200000, "individual_fine_max": 400000}}
+    #                     ],
+    #                     "speed_limits_by_vehicle_type_and_road_type": [{"vehicle_type": "xe ô tô con"}]
+    #                 }
+    #             ]
+    #         },
+    #         {
+    #             "clause_number": "12", # Khoản không có điểm
+    #             "clause_text_original": "Ngoài việc bị phạt tiền, người điều khiển xe thực hiện hành vi vi phạm còn bị áp dụng các hình thức xử phạt bổ sung sau đây: ...",
+    #             "clause_metadata_summary": {"overall_fine_note_for_clause": "Áp dụng hình phạt bổ sung"}
+    #         }
+    #     ]
+    # }
+    #
+    # print("\n--- Test process_law_data_to_chunks ---")
+    # chunks = process_law_data_to_chunks(sample_data)
+    # print(f"Số chunks được tạo: {len(chunks)}")
+    # if chunks:
+    #     print("Chunk đầu tiên:")
+    #     print(json.dumps(chunks[0], indent=2, ensure_ascii=False))
+    #     print("Chunk cuối cùng (nếu có nhiều hơn 1):")
+    #     if len(chunks) > 1:
+    #         print(json.dumps(chunks[-1], indent=2, ensure_ascii=False))
+
+    # Để test search_relevant_laws, bạn cần mock embedding_model, faiss_index, bm25_model
+    # và có chunks_data đã được xử lý.
+    print("\n--- Các test khác (ví dụ: search_relevant_laws) cần mock hoặc dữ liệu đầy đủ. ---")

utils.py

@@ -0,0 +1,48 @@
+# utils.py
+
+import re
+from typing import List
+
+def tokenize_vi_simple(text: str) -> List[str]:
+    """
+    Tokenizes Vietnamese text simply for tasks like BM25.
+    Converts to lowercase, removes basic punctuation, and splits by whitespace.
+
+    Args:
+        text (str): The input Vietnamese text.
+
+    Returns:
+        List[str]: A list of tokens.
+    """
+    if not isinstance(text, str):
+        # Or raise TypeError("Input must be a string")
+        return []
+    text = text.lower()
+    # Remove characters that are not alphanumeric or whitespace
+    text = re.sub(r'[^\w\s]', '', text)
+    return text.split()
+
+# You can add other general utility functions here as your project grows.
+# For example:
+# - Functions for logging
+# - Functions for path manipulation if they are used across multiple modules
+# - Simple data validation or cleaning routines not specific to law data or LLMs
+
+if __name__ == '__main__':
+    print("Testing utils.py...")
+
+    # Test tokenize_vi_simple
+    print("\n--- Test tokenize_vi_simple ---")
+    test_phrases = [
+        "Luật Giao thông Đường bộ Việt Nam 2023!",
+        "Xe ô tô con và xe máy.",
+        "  Phạt tiền từ 200.000đ đến 400.000đ.  ",
+        "",
+        None, # Test with None
+        123 # Test with non-string
+    ]
+    for phrase in test_phrases:
+        print(f"Input: '{phrase}' (type: {type(phrase).__name__})")
+        tokens = tokenize_vi_simple(phrase)
+        print(f"Tokens: {tokens}")
+        print("-" * 10)