Skip to content

Bui-Tung-Hung/The-Documents-Manager

BranchesTags

Repository files navigation

🔍 AI-Powered Document Search Engine

Docker FastAPI Python License AWS LocalStack

🎯 Dự Án Cá Nhân Showcase

Một hệ thống tìm kiếm tài liệu . Dự án này showcase thực hành DevOps, kiến trúc microservices, và tích hợp AI/ML

🏆 Thành Tựu Kỹ Thuật Chính

  • 🏗️ Microservices: Mẫu provider modular với dependency injection
  • ☁️ Cloud-Native: Tích hợp AWS S3 + SQS với LocalStack (Giả lập AWS) cho phát triển local
  • 🤖 AI/ML: Tìm kiếm ngữ nghĩa sử dụng BGE-M3 embeddings và vector databases Qdrant
  • � RAG System: Chat với tài liệu sử dụng Ollama models và retrieval augmented generation
  • �🔧 DevOps: Multi-stage Docker builds, quản lý cấu hình, giám sát Healths
  • 📊 Production: Xử lý async, xử lý lỗi, logging, và mẫu khả năng mở rộng

Dự án này mô phỏng hệ thống quản lý tài liệu doanh nghiệp thực tế:

  • Backend services gửi yêu cầu xử lý tài liệu qua AWS SQS
  • Tài liệu được truy xuất từ AWS S3 sử dụng secure file keys
  • Tìm kiếm ngữ nghĩa được hỗ trợ AI cho phép khám phá tài liệu thông minh
  • Kiến trúc có thể mở rộng

🌟 Mô Phỏng Workflow

Dự án này tái tạo pipeline xử lý tài liệu doanh nghiệp thực tế:

graph LR
    A[Backend Services] --> B[LocalStack S3]
    B --> C[AWS SQS Queue]
    C --> D[Document Processor]
    D --> E[AI Processing]
    E --> F[Vector Database]
    F --> G[Search API]
    G --> H[End Users]
Loading

Luồng Kỹ Thuật:

  1. 🔄 Message Queue: Backend services gửi metadata tài liệu qua SQS
  2. 📄 Truy Xuất Tài Liệu: Hệ thống lấy tài liệu từ S3 sử dụng secure file keys
  3. 🤖 Xử Lý AI: Embeddings đa ngôn ngữ được tạo bằng BGE-M3 model
  4. 🗄️ Lưu Trữ Vector: Tài liệu được đánh index trong Qdrant cho similarity search
  5. 🔍 Search Engine: RESTful API cung cấp khả năng tìm kiếm ngữ nghĩa
  6. 💬 RAG Chat: Chat với tài liệu sử dụng Ollama models (qwen2.5:1.5b)

📋 Mục Lục

🚀 Quick Start

Yêu Cầu Tiên Quyết

  • Docker & Docker Compose đã cài đặt
  • Tối thiểu 4GB RAM có sẵn (khuyến nghị 8GB)
  • Port 8001 có sẵn
  • Kết nối Internet (để tải Qdrant Cloud & models)
  • Tùy chọn: LocalStack cho mô phỏng S3/SQS

Tùy Chọn 1: Docker (Khuyến Nghị)

# Clone repository
git clone https://github.com/Bui-Tung-Hung/The-Documents-Manager.git
cd The-Documents-Manager/docker

# Thiết lập environment variables
cp .env.example .env
# Chỉnh sửa .env với cấu hình của bạn

# Chạy với Docker Compose
docker-compose up -d

# Kiểm tra health
curl http://localhost:8001/health

Tùy Chọn 2: Enterprise Development Setup (LocalStack)

Mô phỏng workflow doanh nghiệp đầy đủ với AWS services:

# 1. Khởi động LocalStack cho mô phỏng AWS
docker run --rm -d \
  -p 4566:4566 \
  -e SERVICES=s3,sqs \
  localstack/localstack

# 2. Thiết lập môi trường local
export QDRANT_URL=http://localhost:6333
export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

# 3. Chạy với local Qdrant
docker-compose --profile local up -d

# 4. Test enterprise workflow
python scripts/upload_to_s3.py      # Upload documents
python scripts/send.py              # Send SQS messages
python scripts/receive.py           # Process documents

Tùy Chọn 3: Phát Triển Local

# Clone và setup
git clone https://github.com/Bui-Tung-Hung/The-Documents-Manager.git
cd The-Documents-Manager/The-Document-Manager-v2

# Tạo virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac

# Cài đặt dependencies
pip install -r requirements.txt

# Cấu hình environment
cp .env.example .env
# Chỉnh sửa .env với settings của bạn

# Kiểm tra cấu hình
python tools/check_config.py

# Chạy API
python -m app.main

Test Workflow Doanh Nghiệp Nhanh

# Health check
curl http://localhost:8001/health

# Tìm kiếm tài liệu (mô phỏng end-user query)
curl -X POST "http://localhost:8001/search-files" \
     -H "Content-Type: application/json" \
     -d '{"query": "machine learning"}'

# Chat với tài liệu (RAG - Retrieval Augmented Generation)
curl -X POST "http://localhost:8001/chat-with-files" \
     -H "Content-Type: application/json" \
     -d '{
       "file_ids": ["doc_123", "doc_456"], 
       "message": "Tóm tắt nội dung chính",
       "max_chunks": 5
     }'

# Tài liệu API (Swagger UI cấp doanh nghiệp)
open http://localhost:8001/docs

🔧 Hướng Dẫn Chiến Lược Cấu Hình

Khi Nào Sử Dụng Cấu Hình Nào

Hệ thống yêu cầu lựa chọn cấu hình thủ công. Nó KHÔNG tự động chuyển đổi giữa các môi trường.

🐳 Phát Triển Local (Docker Qdrant)

Use Case: Testing, development, công việc offline, học kiến trúc microservices Cấu hình: config/config.dev.yaml

# Khởi động local Qdrant với full stack
docker-compose --profile local up -d

# Chạy với development config
CONFIG_PATH=config/config.dev.yaml python -m app.main

☁️ Production (Qdrant Cloud)

Use Case: Triển khai production, cộng tác team, kiến trúc có thể mở rộng Cấu hình: config/config.prod.yaml + environment variables

# Thiết lập production credentials
export QDRANT_URL=https://your-cluster.qdrant.tech
export QDRANT_API_KEY=your_secure_api_key

# Cấu hình Chat Models (Ollama)
export CHAT_PROVIDER=ollama
export CHAT_MODEL=qwen2.5:1.5b
export CHAT_BASE_URL=http://localhost:11434
export CHAT_MAX_CHUNKS=5

# Chạy với production config
CONFIG_PATH=config/config.prod.yaml python -m app.main

🔍 Xác Minh Cấu Hình

Luôn xác minh cấu hình của bạn trước khi triển khai:

# Kiểm tra cấu hình hiện tại
python tools/check_config.py

# Test cấu hình cụ thể
python tools/check_config.py --config config/config.prod.yaml

📚 Tài Liệu API

Base URL

http://localhost:8001

Endpoints

Health Check

GET /health

Tìm Kiếm Tài Liệu

POST /search-files
Content-Type: application/json

{
  "query": "machine learning algorithms"
}

Chat Với Tài Liệu (RAG)

POST /chat-with-files
Content-Type: application/json

{
  "file_ids": ["doc_123", "doc_456"],
  "message": "Tóm tắt nội dung chính của các tài liệu này",
  "max_chunks": 5
}

Response:

{
  "response": "Dựa trên các tài liệu được cung cấp...",
  "source_chunks": [
    {
      "file_id": "doc_123",
      "content": "Nội dung chunk liên quan...",
      "score": 0.85
    }
  ],
  "total_chunks": 3
}

Index Tài Liệu

POST /index-documents
Content-Type: application/json

{
  "documents": [
    {
      "content": "Document content here...",
      "file_id": "doc_456",
      "metadata": {"title": "My Document"}
    }
  ]
}

Tài Liệu Tương Tác

GET /docs

🏗️ Kiến Trúc

Enterprise Simulation Design

Dự án này thể hiện các mẫu doanh nghiệp thực tế với RAG (Retrieval Augmented Generation):

┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Backend       │    │   Message    │    │   Document      │
│   Services      │───►│   Queue      │───►│   Processor     │
│                 │    │   (SQS)      │    │                 │
└─────────────────┘    └──────────────┘    └─────────────────┘
                                                    │
┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Search API    │◄───│   Vector DB  │◄───│   File Storage  │
│   (FastAPI)     │    │   (Qdrant)   │    │   (S3)          │
│                 │    │              │    │                 │
│   Chat API      │◄───│   Chat Model │    │                 │
│   (RAG)         │    │   (Ollama)   │    │                 │
└─────────────────┘    └──────────────┘    └─────────────────┘

Hệ Thống Provider Modular

Kiến trúc linh hoạt cho phép dễ dàng thay đổi công nghệ:

┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
│   FastAPI       │    │  Embedding   │    │  Vector DB      │
│   Application   │◄──►│  Provider    │◄──►│  Provider       │
│                 │    │              │    │                 │
│                 │    ┌──────────────┐    │                 │
│                 │◄──►│  Chat        │    │                 │
│                 │    │  Provider    │    │                 │
└─────────────────┘    └──────────────┘    └─────────────────┘

Công Nghệ Doanh Nghiệp Được Hỗ Trợ

Vector Databases:

  • ✅ Qdrant (Cloud & Self-hosted)
  • 🔄 Chroma (Sắp có)
  • 🔄 Pinecone (Sắp có)
  • 🔄 Weaviate (Sắp có)
  • 🔄 Milvus (Sắp có)

Embedding Models:

  • ✅ Ollama (BGE-M3, khác)
  • 🔄 OpenAI (Sắp có)
  • 🔄 Hugging Face (Sắp có)
  • 🔄 Azure OpenAI (Sắp có)

Chat Models (RAG):

  • ✅ Ollama (qwen2.5:1.5b, llama3, khác)
  • 🔄 OpenAI GPT (Sắp có)
  • 🔄 Azure OpenAI (Sắp có)
  • 🔄 Anthropic Claude (Sắp có)

💻 Phát Triển

Enterprise Development Workflow

# Terminal 1: Khởi động LocalStack (AWS simulation)
docker run --rm -p 4566:4566 -e SERVICES=s3,sqs localstack/localstack

# Terminal 2: Upload documents to S3
python scripts/upload_to_s3.py

# Terminal 3: Send processing messages
python scripts/send.py

# Terminal 4: Process documents from queue
python scripts/receive.py

📧 Contact: Made with ❤️ by Bui-Tung-Hung - Showcasing enterprise software development skills

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages