# Deep Dive: AI Variant Generation

Để tăng cường độ chính xác cho bộ máy tìm kiếm (Hybrid Search), hệ thống FAQ không chỉ lưu trữ câu hỏi gốc mà còn tự động sinh ra các biến thể (variants) của câu hỏi. Module này được thiết kế nhằm lấp đầy khoảng trống ngữ nghĩa do các cách hỏi khác nhau của người dùng (viết tắt, từ lóng, emoji, sai chính tả có chủ đích) tạo ra.

## Phân tích Source Code (`faq_route.py`)

Hệ thống cung cấp hai phương thức tạo biến thể thông qua LLM (cụ thể là mô hình `gpt-4.1-mini`).

### 1. AI Configuration
Hệ thống sử dụng client bất đồng bộ `httpx.AsyncClient` để giao tiếp với OpenAI-compatible API thông qua URL `LITELLM_BASE_URL`/`v1/chat/completions`. Tham số `temperature` được thiết lập ở mức `0.8` nhằm gia tăng độ sáng tạo và đa dạng của các câu hỏi được sinh ra, tránh việc lặp đi lặp lại một mẫu câu.

### 2. Các phương thức Generation

#### a. Single FAQ Generation (`/api/faqs/generate-variants`)
- **Input:** Nhận vào `faq_id` và số lượng biến thể cần sinh `count` (mặc định: 20).
- **Prompt Logic:** Yêu cầu LLM đóng vai "chuyên gia ngôn ngữ" để sinh câu hỏi từ `question` và `category` hiện tại. Yêu cầu đặc tả tính đa dạng phong cách (formal, casual, viết tắt, có typo nhẹ, dùng emoji) nhưng giữ nguyên ý nghĩa.
- **Xử lý Response:** Các biến thể trả về được tách theo dòng (`split("\n")`), lọc bỏ các dòng trống hoặc quá ngắn (`len < 5` ký tự).
- **Database Insert:** Mỗi biến thể được gán một ID dạng `uuid` mới, kế thừa nội dung `answer` và `category` từ câu hỏi gốc. Đặc tả kỹ thuật quan trọng trong CSDL:
  - Cờ `is_variant = 1` được bật.
  - Trường `parent_id` được set bằng `id` của câu gốc. Việc này hỗ trợ cho tính nhất quán của dữ liệu (khi xóa FAQ gốc, backend sẽ thực thi truy vấn xóa toàn bộ các dòng có `parent_id` tương ứng).

#### b. Batch Generation (`/api/faqs/batch-generate`)
- **Input:** Nhận yêu cầu tùy chọn phân loại theo `category` và số lượng sinh mỗi FAQ `count_per_faq` (mặc định: 10).
- Hệ thống thực hiện truy vấn để quét qua toàn bộ các FAQ đang là bản gốc (`WHERE is_variant = 0`).
- Duyệt qua từng FAQ và gọi hàm `_call_ai` để sinh biến thể, áp dụng cơ chế bắt lỗi `try...except` trên cấp độ từng item. Thiết kế này nhằm mục đích để nếu một câu bị lỗi API timeout hoặc phản hồi không hợp lệ thì cũng không làm gián đoạn toàn bộ pipeline batch sinh dữ liệu.

## Ưu điểm của Kiến trúc
- **Tối ưu chi phí & Hiệu năng:** Kiến trúc này mở rộng (Expand) bề mặt từ khóa (surface area) cho phép thuật toán Text Search đơn giản (như Word Overlap) hoạt động cực kì hiệu quả mà không cần phải triển khai và duy trì các hệ thống Embedding Models, Vector Databases đắt đỏ, phức tạp.
