How ngothanhnam0910/vietnamese-law-question-answering-system works
Project type and purpose
• This is a full-stack Retrieval-Augmented Generation (RAG) Q&A chatbot system specialized on Vietnamese legal documents.
• It combines a Python-based frontend chat interface, a FastAPI backend with Celery tasks, vector and lexical search (Qdrant + Elasticsearch), OpenAI models for LLM inference, and separate pipelines for finetuning embedding/rerank models and the answer-generation LLM.
File structure
• Top-level directories:
• backend – FastAPI service, Celery configuration, retrieval logic, caching, database models/schemas.
• chatbot-ui – Python CLI or simple UI client that calls the backend API.
• retrieval – data creation & finetuning scripts for embedding and rerank models.
• finetune_llm – data generation and finetuning scripts for the answer-generation LLM.
• images – static assets for documentation.
• Architectural patterns:
• Separation of concerns: UI ↔ API ↔ background workers ↔ storage ↔ external AI services.
• Modular search_document package encapsulating multiple search strategies (Elastic, BGE, E5, ensemble, rerank).
• Celery for asynchronous tasks (e.g., batch retrieval, long-running finetune jobs).
• External state services: Qdrant (vector DB), Elasticsearch (inverted index), and a relational DB (SQLAlchemy models).
Extract insights from the README
• There is a two-phase retrieval pipeline: chunking → embedding via two models → Qdrant; and parallel Elasticsearch lookup → merge → rerank → top-k documents.
• RAG flow: intent detection → query rewriting → retrieval → reranking → answer generation → fallback “tool” search.
• Two finetuning subsystems: one for the rerank model in retrieval/; one for the base LLM in finetune_llm/.
a. Main components
1. Chatbot UI (chat_interface.py)
2. FastAPI Backend (app.py, agent.py, brain.py)
3. Celery Workers (celery_app.py + tasks.py)
4. Vector Storage (Qdrant)
5. Elasticsearch Cluster
6. Relational Database (Postgres/MySQL)
7. OpenAI API (gpt-4o-mini, Chat Completions)
8. Tavily Search Tool (external web search)
9. Rerank model service (BGE-v2-m3 finetuned)
10. Finetuning Pipelines (scripts in retrieval/ and finetune_llm/)
b. Relationships and data flows
• User → Chatbot UI → HTTP → FastAPI API
• API → “Intent Detection” via OpenAI → branch: Chitchat vs. Legal
• If Legal: API → Query Rewriting (OpenAI) → send rewritten query →
• Parallel: embed via BGE & E5 → Qdrant → top-n vectors
• Elasticsearch text search → top-n docs
• Merge results → send to Rerank model (Celery or sync) → top-k docs
• API → Assemble prompt with top-k docs + user query → OpenAI → answer
• If answer == “no”: trigger Tavily Search Tool → fetch web snippets → re-invoke LLM
• All API calls for retrieval/LLM can be dispatched to Celery for concurrency and rate-limiting.
• Persist chat history & metadata in relational DB; cache recent queries in Redis or in-memory.
c. Architectural patterns & principles
• Micro-service style modularity inside one containerized backend.
• CQRS-like separation: synchronous queries vs. asynchronous tasks (Celery).
• Pipeline orchestration: intent → rewrite → retrieve → rerank → generate.
• Ensemble and fallback for robustness (Elastic + vector + tool search).
d. Key technologies & frameworks
• Python 3.x, FastAPI, Celery, Pydantic (schemas.py), SQLAlchemy (models.py)
• Qdrant (vector DB), Elasticsearch
• OpenAI Python SDK, huggingface-trl for LLM finetuning
• BGE and Multilingual-e5 embedding models
• Docker / shell scripts for entrypoints (entrypoint.sh)
Detailed coverage
• Every file/folder with unique responsibility is reflected: search_document submodules, finetune_llm scripts, retrieval training scripts.
• Celery’s role in decoupling long-running tasks (e.g., rerank training, LLM finetune).