Metadata-Version: 2.4
Name: cos_rag_son_humg
Version: 0.1.5
Summary: High Performance Vector Engine for RAG using AVX2 SIMD and Zero-copy
Author-email: le_bao_son <sonbuwin@gmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/sonbuwin-beep

# 🚀 CosRAG Son HUMG - High Performance Vector Engine

Engine tính toán Cosine Similarity hiệu năng cao được viết bằng **Rust**, tối ưu hóa sâu cho các hệ thống RAG (Retrieval-Augmented Generation).

## 🛠 Kỹ thuật tối ưu hóa (Technical Stack)

### 1. AVX2 SIMD Kernel
Sử dụng tập lệnh xử lý song song dữ liệu (Single Instruction, Multiple Data). Thay vì tính toán từng phần tử, engine xử lý đồng thời 8 số thực `f32` trong một chu kỳ xung nhịp, giúp tăng tốc độ lên gấp nhiều lần so với code Python/C++ truyền thống.

### 2. Tail Processing Logic
Giải quyết vấn đề nan giải của SIMD khi số chiều không chia hết cho 8 (ví dụ: 771 dims). Engine tự động tách phần dư để xử lý bằng Scalar logic, đảm bảo độ chính xác tuyệt đối mà không cần padding dữ liệu.

### 3. Zero-copy Memory Access
Thông qua PyO3, Rust truy cập trực tiếp vào vùng nhớ (buffer) của NumPy mảng. Điều này giúp loại bỏ hoàn toàn việc sao chép dữ liệu (copy overhead), cực kỳ quan trọng khi làm việc với Big Data (hàng chục triệu vector) để tối ưu RAM.

## ⚡ Hiệu năng thực tế (Benchmarks)

Thử nghiệm trên môi trường Google Colab (CPU Intel Xeon):
- **Tốc độ quét**: ~3.500.000 vector/giây (với chiều 768).
- **Khả năng mở rộng**: Xử lý mượt mà 10 triệu vector (~15GB RAM) mà không gây tràn bộ nhớ nhờ cơ chế quản lý bộ nhớ của Rust.
- **Độ trễ**: Cực thấp, phù hợp cho các ứng dụng chatbot yêu cầu phản hồi thời gian thực.

## 🚀 Hướng dẫn sử dụng

### Cài đặt
```bash
pip install cos_rag_son_humg
```

### Cách dùng cơ bản
```python
import numpy as np
import cos_rag_son_humg as sl

dim = 768
db = np.random.rand(1000000, dim).astype(np.float32)
query = np.random.rand(dim).astype(np.float32)

# Lưu ý: Cần .ravel() mảng database để tối ưu hóa SIMD
scores = sl.vecto(query, db.ravel(), dim)
idx, best_score = sl.cos_vecto(scores)

print(f"Kết quả: Index {idx}, Score {best_score}")
```

## 🌟 Ưu điểm
- **Chính xác**: Giữ nguyên định dạng `f32`, không gây mất mát thông tin như Quantization.
- **Nhẹ**: Thư viện nhỏ gọn, không phụ thuộc vào các framework nặng nề.
- **Nhanh**: Tận dụng tối đa sức mạnh phần cứng CPU hiện đại.

--- 
*Phát triển bởi Son HUMG - Đam mê tốc độ và sự chính xác!* 🦀
