Metadata-Version: 2.4
Name: vietnamese-ai
Version: 27.0.0
Summary: Framework AI thuần tiếng Việt cho Python - Vietnamese AI Framework
Home-page: https://github.com/phonghhd/vietnamese-ai
Author: EvoNet AI Team
Author-email: EvoNet AI Team <huynhduongphong9@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/phonghhd/vietnamese-ai
Project-URL: Documentation, https://phonghhd.github.io/vietnamese-ai
Project-URL: Repository, https://github.com/phonghhd/vietnamese-ai
Project-URL: Issues, https://github.com/phonghhd/vietnamese-ai/issues
Project-URL: Changelog, https://github.com/phonghhd/vietnamese-ai/blob/main/CHANGELOG.md
Keywords: ai,machine-learning,vietnamese,nlp,deep-learning
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Natural Language :: Vietnamese
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: matplotlib>=3.4.0
Provides-Extra: nlp
Requires-Dist: underthesea>=6.0; extra == "nlp"
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: transformers
Requires-Dist: transformers>=4.30; extra == "transformers"
Requires-Dist: torch>=2.0; extra == "transformers"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: all
Requires-Dist: underthesea>=6.0; extra == "all"
Requires-Dist: torch>=2.0; extra == "all"
Requires-Dist: transformers>=4.30; extra == "all"
Requires-Dist: pytest>=7.0; extra == "all"
Requires-Dist: pytest-cov>=4.0; extra == "all"
Requires-Dist: black>=23.0; extra == "all"
Requires-Dist: ruff>=0.1.0; extra == "all"
Requires-Dist: mypy>=1.0; extra == "all"
Requires-Dist: mkdocs>=1.5; extra == "all"
Requires-Dist: mkdocs-material>=9.0; extra == "all"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<p align="center">
  <h1 align="center">Vietnamese AI Framework</h1>
  <p align="center">
    <strong>Framework AI thuần tiếng Việt cho Python</strong>
  </p>
  <p align="center">
    <em>Học máy đơn giản. API tiếng Việt. Production-ready.</em>
  </p>
</p>

<p align="center">
  <a href="#cài-đặt">Cài đặt</a> •
  <a href="#tính-năng">Tính năng</a> •
  <a href="#sử-dụng-nhanh">Sử dụng nhanh</a> •
  <a href="#cli">CLI</a> •
  <a href="#docker">Docker</a> •
  <a href="#api-reference">API Reference</a> •
  <a href="#đóng-góp">Đóng góp</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-27.0.0-blue.svg" alt="version">
  <img src="https://img.shields.io/badge/python-3.8%2B-blue.svg" alt="python">
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="license">
  <img src="https://img.shields.io/badge/tests-897%2F897-brightgreen.svg" alt="tests">
  <img src="https://img.shields.io/badge/language-Vietnamese-red.svg" alt="language">
</p>

---
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20357082.svg)](https://doi.org/10.5281/zenodo.20357082)
## 🚀 Các Tính Năng Nổi Bật

- **Lõi C++ & Rust Tối Ưu**: Framework sử dụng kết hợp C++ (`onnxruntime`, `llama.cpp`) và Rust (`PyO3`) để tăng tốc xử lý văn bản, lập lịch và inference lên tối đa.
- **Agentic Swarm & MemGPT**: Hỗ trợ Multi-Agent (Swarm, MoA, MCTS) và trí nhớ dài hạn không giới hạn (Long-Term Memory).
- **Edge-Cloud Continuum (DePIN)**: Kiến trúc tự động định tuyến (Routing) giữa thiết bị Edge và Cloud API. 
- **GraphRAG & Multi-modal RAG**: Mạng tri thức đồ thị và tìm kiếm văn bản-hình ảnh.
- **Extreme Efficiency**: Trang bị mô phỏng PagedAttention, Speculative Decoding và mạng 1.58-bit (BitNet).
- **AutoML & NAS**: Tự động tìm kiếm kiến trúc và siêu tham số tốt nhất.
- **Bảo mật & An Toàn**: Tích hợp Guardrails AI để kiểm soát nội dung và chống Prompt Injection.
- **EvoNet-Studio Super Core (v21.0)**: Kiến trúc Zero-Dependency độc quyền hỗ trợ điều phối cụm (Orchestrator), giám sát GPU/Cost (Monitor), DataLake đánh version, DAG Workflow, Hộp cát (Sandbox) và hệ thống Plugin Hot-Swap, kết nối chặt chẽ với toàn bộ các tính năng Agent và RAG có sẵn.

---

## Giới thiệu

**Vietnamese AI Framework** là framework học máy mã nguồn mở, được thiết kế đặc biệt cho cộng đồng phát triển AI tại Việt Nam. Toàn bộ API, thông báo lỗi, tài liệu và ví dụ đều sử dụng tiếng Việt.

### Tại sao lại là Vietnamese AI?

| Vấn đề hiện tại | Giải pháp của chúng tôi |
|---|---|
| Framework AI lớn quá phức tạp cho người mới | API đơn giản, học trong 5 phút |
| Tài liệu toàn bằng tiếng Anh | Tài liệu và ví dụ 100% tiếng Việt |
| Thiếu toolkit xử lý văn bản tiếng Việt | Tích hợp sẵn underthesea + TF-IDF + stopwords |
| Không có framework "all-in-one" cho người Việt | Models + Preprocessing + CV + Tuning + API + CLI + Docker + SaaS + Studio + LLM |

---

## Cài đặt

### Cơ bản

```bash
pip install vietnamese-ai
```

### Từ source

```bash
git clone https://github.com/phonghhd/vietnamese-ai.git
cd vietnamese-ai
python -m venv venv
source venv/bin/activate
pip install -e .
```

### Với NLP tiếng Việt (underthesea)

```bash
pip install -e ".[nlp]"
```

### Với Deep Learning (PyTorch)

```bash
pip install -e ".[torch]"
```

### Tất cả tính năng

```bash
pip install -e ".[all]"
```

---

## Tính năng

### Models

| Mô hình | Thuật toán |
|---|---|
| `PhanLoai` | logistic, knn, svm, cay_quyet_dinh, rung_ngau_nhien, gradient_boosting, naive_bayes |
| `HoiQuy` | tuyen_tinh, ridge, lasso, elastic_net, svm, cay_quyet_dinh, rung_ngau_nhien, gradient_boosting |
| `PhanCum` | kmeans, dbscan, hierarchical |
| `MangNron` | Custom MLP (ReLU, Sigmoid, Tanh) - không cần TensorFlow/PyTorch |
| `MoHinhTapHop` | voting, bagging, boosting |

### Core

| Module | Chức năng |
|---|---|
| `Engine` | Điều phối huấn luyện, đánh giá, quản lý lịch sử |
| `Pipeline` | Chuỗi tiền xử lý + mô hình, hỗ trợ save/load |
| `KiemDinhCheo` | K-Fold, Stratified K-Fold, Repeated K-Fold |
| `TimKiemThamSo` | GridSearch, RandomSearch |

### NLP & Embeddings

| Module | Chức năng |
|---|---|
| `Word2VecTiengViet` | Word2Vec Skip-gram/CBOW tự cài đặt |
| `FastTextTiengViet` | Character n-gram embeddings (xử lý OOV) |
| `PhanTichCamXuc` | Sentiment: underthesea, từ điển, tự huấn luyện |

### AutoML & Experiment Tracking

| Module | Chức năng |
|---|---|
| `AutoML` | Tự động chọn mô hình + thuật toán tốt nhất |
| `TimKiemKienTruc` | Neural Architecture Search (NAS) - tìm kiến trúc MLP tối ưu |
| `TheoDoiThiNghiem` | Theo dõi thí nghiệm (tương thích MLflow) |

### Mobile/Edge & Federated Learning

| Module | Chức năng |
|---|---|
| `TriKhaiDiDong` | Triển khai TFLite, CoreML, ONNX Mobile + quantization INT8 |
| `HocLienKet` | Federated Learning (FedAvg, Differential Privacy, Client Sampling) |

### Real-time ML Pipeline

| Module | Chức năng |
|---|---|
| `PipelineThoiGianThuc` | Real-time pipeline: Message Queue, Feature Store, latency tracking |

### Cloud Platform & No-code Studio

| Module | Chức năng |
|---|---|
| `NenTangDichVu` | SaaS platform: multi-tenant workspace, API keys, quota, model deploy |
| `StudioKeoTha` | No-code Studio: kéo thả pipeline, templates, save/load JSON |

### Vietnamese LLM

| Module | Chức năng |
|---|---|
| `VietnameseLLM` | N-gram language model: text generation, completion, perplexity, templates |

### Multi-Agent System (v12.0)

| Module | Chức năng |
|---|---|
| `TacTu` | Tác tử AI (Agent) dùng vòng lặp ReAct, lập kế hoạch và thực thi |
| `CongCu` & `@cong_cu` | Tool Calling: tích hợp Python function, tìm kiếm web, đọc file |
| `BoNhoTacTu` | Quản lý buffer memory theo role (system, user, assistant, tool) |
| `HeThongDaTacTu` | Điều phối tương tác giữa nhiều tác tử để giải quyết task phức tạp |

### PyTorch Training & Fine-tuning (Phase 7-8)

| Module | Chức năng |
|---|---|
| `HuanLuyenPyTorch` | PyTorch trainer: GPU, mixed precision, gradient accumulation, early stopping, checkpoint |
| `UnslothWrapper` | Unsloth integration: 2x faster fine-tune, LoRA, QLoRA, quantization |
| `XuatGGUF` | GGUF export/import: Q4_K, Q5_K, Q8_0 quantization cho llama.cpp |
| `HuggingFaceWrapper` | HuggingFace: load pretrained, fine-tune, push to Hub |
| `TransformerModel` | Transformer: Multi-Head Attention, Encoder, Decoder |
| `VietnameseTokenizer` | Tokenizer: BPE, WordPiece cho tiếng Việt |

### PEFT & Instruction Tuning (Phase 6)

| Module | Chức năng |
|---|---|
| `PEFTConfig` | Cấu hình LoRA, QLoRA, Prefix Tuning, Prompt Tuning |
| `LoRAPeft` | Enhanced LoRA PEFT: auto-detect layers, merge/unmerge, save/load adapter |
| `InstructionTuningTrainer` | Instruction tuning: Alpaca/ShareGPT, warmup + cosine decay |

### SFT, DPO & RLHF (Phase 7)

| Module | Chức năng |
|---|---|
| `SFTTrainer` | Supervised Fine-Tuning: cross-entropy, gradient accumulation, mixed precision |
| `DPOTrainer` | Direct Preference Optimization: Bradley-Terry loss, beta annealing |
| `RewardModel` | Reward model: Bradley-Terry training, score normalization |
| `RLHFPipeline` | Full RLHF: SFT → Reward Model → DPO end-to-end |

### GPT Pre-training (Phase 8)

| Module | Chức năng |
|---|---|
| `GPTModel` | GPT decoder-only: causal attention, GELU, pre-norm, weight tying |
| `PreTrainer` | Pre-training trainer: causal LM, warmup + cosine, checkpointing |
| `TextDataset` | Text dataset: sliding window, character-level vocab, batch iterator |

### Vietnamese LLM & Evaluation (Phase 9)

| Module | Chức năng |
|---|---|
| `ModelConfig` | Model presets: tiny(10M), small(125M), medium(350M), large(1.3B), xl(2.7B), 7B |
| `LMEvalHarness` | LM evaluation: perplexity, classification, generation, QA, cloze, few-shot |
| `BenchmarkRunner` | Benchmark runner: perplexity, generation, sentiment, speed, QA |

### Interpretability & Augmentation

| Module | Chức năng |
|---|---|
| `GiaiThichMoHinh` | Feature Importance, Permutation Importance, LIME |
| `TangCuongVanBan` | Tăng cường dữ liệu văn bản (đồng nghĩa, xóa từ, hoán vị, thiếu dấu) |

### Preprocessing

| Module | Chức năng |
|---|---|
| `XuLyVanBan` | Tách từ (underthesea), TF-IDF, stopwords, sentiment, POS tagging |
| `XuLySo` | Min-Max, Z-Score, missing values, one-hot, chia dữ liệu |
| `TaoDacTrung` | Polynomial, interaction, PCA, variance selection |

### RAG Pipeline (v10.0)

| Module | Chức năng |
|---|---|
| `CSDLVector` | Vector database: cosine/L2/inner_product, save/load, metadata |
| `CatVanBan` | Text chunking: theo câu/đoạn/từ/ký tự, sliding window |
| `TrichXuat` | Retriever: semantic, keyword (BM25), hybrid search |
| `SapXepLai` | Reranker: MMR, cross-encoder, keyword, position-aware |
| `RAGPipeline` | Full RAG: chunk → embed → retrieve → rerank → generate |

### Serving & Streaming (v10.0)

| Module | Chức năng |
|---|---|
| `MayChuBatch` | Dynamic batching server: multi-worker, latency tracking |
| `MayChuStream` | SSE streaming: token-by-token, multi-client |
| `BoGioiHanTocDo` | Rate limiter: token bucket, sliding window, per-client |

### Prompt Engineering (v10.0)

| Module | Chức năng |
|---|---|
| `MauPrompt` | Prompt templates: {{biến}}, conditional, 6 built-in templates |
| `ChuoiPrompt` | Chain-of-thought, few-shot, sequential chains |
| `LuongAnToan` | Guardrails: content filter, PII detection, format validation |
| `PhanTichDauRa` | Output parser: JSON, markdown tables, code blocks, lists |

### NLP Extensions (v10.0)

| Module | Chức năng |
|---|---|
| `NhanDienThucThe` | NER: regex + dictionary + underthesea, 8 entity types |
| `HoiDapTiengViet` | QA: extractive, TF-IDF ranking, knowledge base |
| `TomTatVanBan` | Summarization: extractive (TF-IDF + position) + abstractive |
| `DichThuat` | Translation: dictionary + LLM + hybrid, en/vi |
| `KiemTraChinhTa` | Spell check: edit distance, tone marks, auto-learn |

### Model Compression (v10.0)

| Module | Chức năng |
|---|---|
| `HocRutGon` | Knowledge Distillation: soft labels, temperature, ensemble |
| `CatTiaMoHinh` | Pruning: magnitude, structured, iterative, random |

### Production Hardening (v10.0)

| Module | Chức năng |
|---|---|
| `KiemTraSucKhoe` | Health check: readiness/liveness probes, system monitoring |
| `MachCat` | Circuit breaker: 3 states, auto-recovery, fallback |
| `LoggerCauTruc` | Structured logging: JSON, timing, context, request tracking |
| `QuanLyMetrics` | Metrics: counter, gauge, histogram, Prometheus export |
| `LamNongModel` | Model warm-up: pre-load, auto-refresh, pool management |

### CLI

```
vai info                              Thông tin framework
vai train --data FILE --model M       Huấn luyện mô hình
vai predict --model M --input FILE    Dự đoán
vai evaluate --model M --data FILE    Đánh giá
vai serve --model M --port 8080       API server
vai web --port 5000                   No-code web interface
```

---

## Sử dụng nhanh

### Phân loại

```python
from vietnamese_ai import PhanLoai, XuLySo, DuLieuMau

X, y = DuLieuMau.phan_loai_don_gian(so_mau=400)
X_train, X_test, y_train, y_test = XuLySo.chia_du_lieu(X, y)

pl = PhanLoai(thuat_toan="rung_ngau_nhien")
pl.huan_luyen(X_train, y_train)
print(pl.bao_cao(X_test, y_test))
```

### Cross-Validation

```python
from vietnamese_ai import KiemDinhCheo, PhanLoai

kdc = KiemDinhCheo(so_fold=5)
ket_qua = kdc.chay(PhanLoai(thuat_toan="logistic"), X, y)
print(f"Điểm CV: {ket_qua['diem_trung_binh']:.4f} (+/- {ket_qua['do_lech_chuan']:.4f})")
```

### AutoML

```python
from vietnamese_ai import AutoML

auto = AutoML(so_fold=5)
ket_qua = auto.fit(X_train, y_train)
print(f"Mô hình tốt nhất: {ket_qua['thuat_toan_tot_nhat']}")
du_doan = auto.predict(X_test)
```

### Pipeline + Save/Load

```python
from vietnamese_ai import Pipeline, XuLySo, PhanLoai

pipe = Pipeline()
pipe.them_buoc("chuan_hoa", XuLySo())
pipe.them_buoc("phan_loai", PhanLoai(thuat_toan="gradient_boosting"))
pipe.fit(X_train, y_train)

pipe.luu("models/pipe.pkl")
pipe2 = Pipeline.tai("models/pipe.pkl")
du_doan = pipe2.predict(X_test)
```

### Xử lý văn bản tiếng Việt

```python
from vietnamese_ai import XuLyVanBan

xl = XuLyVanBan()
xl.tach_tu("Trí tuệ nhân tạo rất hay")
# → ['trí_tuệ_nhân_tạo', 'rất', 'hay']

xl.phan_tich_cam_xuc("Sản phẩm rất tốt, tôi rất hài lòng")
# → 'positive'

tfidf = xl.ma_hoa_tfidf(["văn bản 1", "văn bản 2"])
```

### No-code Studio

```python
from vietnamese_ai import StudioKeoTha

studio = StudioKeoTha()
studio.tai_template("phan_loai_co_ban")
ket_qua = studio.chay()
print(ket_qua['trang_thai'])  # 'thanh_cong'
```

### Vietnamese LLM & Agents

```python
from vietnamese_ai import VietnameseLLM
from vietnamese_ai.agents import TacTu, cong_cu

llm = VietnameseLLM(bac=3)

@cong_cu(ten="may_tinh", mo_ta="Tính toán biểu thức")
def tinh_toan(bieu_thuc: str):
    return eval(bieu_thuc)

tac_tu = TacTu(llm=llm, danh_sach_cong_cu=[tinh_toan])
ket_qua = tac_tu.chay("Tính giúp tôi 15 nhân 8")
```

### Federated Learning

```python
from vietnamese_ai import HocLienKet, PhanLoai

hl = HocLienKet(so_client=5, so_vong=10)
ket_qua = hl.huan_luyen(PhanLoai, X, y, thuat_toan="logistic")
print(f"Điểm global: {ket_qua['diem_toan_cuc']:.4f}")
```

---

## CLI

Sau khi cài đặt, sử dụng lệnh `vai`:

```bash
vai info
vai train --data data.csv --model logistic --output model.pkl --test-size 0.2
vai predict --model model.pkl --input new_data.csv --output results.csv
vai evaluate --model model.pkl --data test.csv
vai serve --model model.pkl --port 8080
vai web --port 5000
```

---

## Docker

```bash
docker build -t vietnamese-ai .
docker run -p 8080:8080 -v ./models:/app/models vietnamese-ai serve --model /app/models/model.pkl --port 8080
```

### Docker Compose

```bash
mkdir -p data models
docker-compose run vai-train
docker-compose up vai-serve
```

---

## API Server

```bash
vai serve --model model.pkl --port 8080

curl -X POST http://localhost:8080/du_doan \
  -H "Content-Type: application/json" \
  -d '{"du_lieu": [[1.0, 2.0, 3.0, 4.0, 5.0]]}'

curl http://localhost:8080/suc_khoe
```

---

## API Reference

### PhanLoai(thuat_toan, ten, **kwargs)

| Phương thức | Mô tả |
|---|---|
| `huan_luyen(X, y)` | Huấn luyện mô hình |
| `du_doan(X)` | Dự đoán nhãn |
| `du_doan_xac_suat(X)` | Dự đoán xác suất |
| `danh_gia(X, y)` | Độ chính xác (0-1) |
| `bao_cao(X, y)` | accuracy, precision, recall, f1 |
| `luu(duong_dan)` | Lưu mô hình |
| `BaseModel.tai(duong_dan)` | Tải mô hình |

### KiemDinhCheo(so_fold, lap_lai, seed)

| Phương thức | Mô tả |
|---|---|
| `chay(mo_hinh, X, y, chi_so)` | Chạy K-Fold CV |

### TimKiemThamSo(so_fold, seed)

| Phương thức | Mô tả |
|---|---|
| `tim_kiem_luoi(lop_mo_hinh, luoi_tham_so, X, y)` | Grid Search |
| `tim_kiem_ngau_nhien(lop_mo_hinh, pham_vi_tham_so, X, y, so_lan)` | Random Search |

### AutoML(so_fold, chuan_hoa)

| Phương thức | Mô tả |
|---|---|
| `fit(X, y)` | Tự động tìm mô hình tốt nhất |
| `predict(X)` | Dự đoán với mô hình tốt nhất |
| `danh_gia(X, y)` | Đánh giá |
| `bao_cao()` | Báo cáo so sánh thuật toán |

### Pipeline(ten)

| Phương thức | Mô tả |
|---|---|
| `them_buoc(ten, bo_xu_ly)` | Thêm bước |
| `fit(X, y)` | Huấn luyện pipeline |
| `predict(X)` | Dự đoán |
| `luu(duong_dan)` | Lưu pipeline |
| `Pipeline.tai(duong_dan)` | Tải pipeline |

### TriKhaiDiDong()

| Phương thức | Mô tả |
|---|---|
| `xuat_tflite(mo_hinh, duong_dan, kich_thuoc_dau_vao)` | Xuất TFLite |
| `xuat_coreml(mo_hinh, duong_dan, kich_thuoc_dau_vao)` | Xuất CoreML |
| `xuat_onnx_mobile(mo_hinh, duong_dan, kich_thuoc_dau_vao)` | Xuất ONNX Mobile |
| `luong_hoa_int8(duong_dan_goc, duong_dan_moi)` | Quantize INT8 |
| `benchmark_edge(mo_hinh, kich_thuoc_dau_vao, so_lan)` | Benchmark |

### HocLienKet(so_client, so_vong, ty_le_client, rieng_tu_differntial)

| Phương thức | Mô tả |
|---|---|
| `huan_luyen(lop_mo_hinh, X, y, **tham_so)` | Federated Learning |
| `du_doan(lop_mo_hinh, X, **tham_so)` | Dự đoán global model |
| `lay_lich_su()` | Lịch sử rounds |
| `bao_cao()` | Báo cáo FL |

### StudioKeoTha(ten)

| Phương thức | Mô tả |
|---|---|
| `them_node(loai, ten, vi_tri, tham_so)` | Thêm node |
| `ket_noi(tu_node, den_node)` | Kết nối nodes |
| `chay()` | Chạy pipeline |
| `tai_template(ten)` | Tải template |
| `luu(duong_dan)` | Lưu config |
| `StudioKeoTha.tai(duong_dan)` | Tải config |

### VietnameseLLM(bac, lam_mo)

| Phương thức | Mô tả |
|---|---|
| `huan_luyen(cac_van_ban, so_vong)` | Huấn luyện LLM |
| `sinh_van_ban(khoi_dau, do_dai, nhiet_do)` | Sinh văn bản |
| `hoan_thanh_cau(dau_vao, so_lua_chon)` | Hoàn thành câu |
| `tinh_perplexity(text)` | Tính perplexity |
| `lay_tu_ke_tiep(text, top_n)` | Gợi ý từ tiếp theo |
| `sinh_theo_template(ten, tham_so)` | Sinh theo template |
| `luu(duong_dan)` / `VietnameseLLM.tai(duong_dan)` | Save/Load |

### NenTangDichVu(duong_dan)

| Phương thức | Mô tả |
|---|---|
| `tao_workspace(ten, chu_so_huu, goi_dich_vu)` | Tạo workspace |
| `tao_api_key(ma_workspace)` | Tạo API key |
| `dang_ky_model(ma_workspace, ten, mo_hinh)` | Đăng ký model |
| `deploy_model(ma_workspace, ma_model)` | Deploy model |
| `du_doan(ma_workspace, ma_deployment, du_lieu)` | Dự đoán |
| `thong_ke_usage(ma_workspace)` | Thống kê sử dụng |

### XuLyVanBan(tu_dung, su_dung_underthesea)

| Phương thức | Mô tả |
|---|---|
| `tach_tu(text)` | Tách từ tiếng Việt (underthesea) |
| `phan_tich_cam_xuc(text)` | Sentiment: positive/negative/neutral |
| `gan_nhan_tu_loai(text)` | POS tagging |
| `ma_hoa_tfidf(cac_van_ban)` | TF-IDF matrix |
| `trich_xuat_tu_khoa(text, top_n)` | Keyword extraction |

---

## Cấu trúc thư mục

```
├── rust_core/             # (v16.0) Lõi C++/Rust siêu tốc bằng PyO3
├── evonet_os/             # (v26.0) Hệ điều hành Web-based UI giao diện kéo thả (DAG Visual Builder)
├── vietnamese_ai/
│   ├── extreme/           # (v27.0) The Hardware Extreme (C++ JIT, Kernel Fusion, CPU Kernel)
│   ├── agents/            # (v12.0) Agentic Swarm, (v16.0) MemGPT, (v18.0) Experience Memory (HITL)
│   ├── edge/              # (v13.0) DePIN Routing, (v17.1) ZKP, (v19.0) P2PTracker & TokenLedger
│   ├── core/              # Engine, Pipeline, KiemDinhCheo, TimKiemThamSo
│   ├── models/            # PhanLoai, HoiQuy, PhanCum, MangNron, MoHinhTapHop
│   ├── preprocessing/     # XuLyVanBan, XuLySo, TaoDacTrung
│   ├── automl/            # AutoML, TimKiemKienTruc (NAS)
│   ├── nlp/               # PhanTichCamXuc, PhoBERTWrapper
│   ├── embeddings/        # Word2VecTiengViet, FastTextTiengViet
│   ├── fine_tuning/       # HuanLuyenPyTorch, UnslothWrapper, HuggingFaceWrapper, PEFT, SFT, DPO, RLHF
│   ├── transformer/       # MultiHeadAttention, TransformerModel, GPTModel, PreTrainer, TextDataset, VietnameseTokenizer
│   ├── vision/            # PhanLoaiHinhAnh
│   ├── timeseries/        # DuDoanChuoiThoiGian
│   ├── mobile/            # TriKhaiDiDong (TFLite, CoreML, ONNX Mobile)
│   ├── federated/         # HocLienKet (FedAvg, Differential Privacy)
│   ├── realtime/          # PipelineThoiGianThuc (Message Queue, Feature Store)
│   ├── rag/               # (v10.0) VectorDB, Chunking, Retriever, (v20.0) Agentic Realtime RAG
│   ├── ui/                # (v20.0) V-UI Zero-Dependency Web Native (PWA, WebGPU, WebXR, WebBluetooth)
│   ├── studio/            # StudioKeoTha (No-code Studio)
│   ├── llm/               # VietnameseLLM (Tích hợp Tường lửa v17.1), ModelConfig, LMEvalHarness, BenchmarkRunner
│   ├── security/          # (v17.0) AI Firewall, Agent Sandbox, Identity-Aware RAG, DLP, (v17.1) Red Teaming, Watermarking
│   ├── export/            # XuatONNX, XuatGGUF
│   ├── registry/          # QuanLyMoHinh (Model Registry)
│   ├── distributed/       # PhanTanHuanLuyen, MultiGPUTrainer
│   ├── enterprise/        # HeThongXacThuc, NhatKyHoatDong
│   ├── orchestrator/      # (v21.0) V-Orchestrator: Điều phối Cụm (Zero-Dependency)
│   ├── monitor/           # (v21.0) V-Monitor: Theo dõi GPU và Tính Cost
│   ├── datalake/          # (v21.0) V-DataLake: Quản lý version dữ liệu & Streaming
│   ├── sandbox/           # (v21.0) V-Sandbox: Hộp cát bảo mật phân tích AST
│   ├── workflow/          # (v21.0) V-Workflow: Động cơ DAG & Thực thi song song
│   ├── plugin/            # (v21.0) V-Plugin: Hệ thống nạp gỡ nóng Plugin (Hot-Swap)
│   ├── interpretability/  # GiaiThichMoHinh
│   ├── experiment_tracking/ # TheoDoiThiNghiem
│   ├── utils/             # Logger, Metrics, Validator, LuuTai
│   ├── visualization/     # BieuDo
│   ├── api/               # ServerDonGian
│   └── cli/               # CLI (vai command)
├── tests/                 # 270 tests
├── examples/              # Ví dụ sử dụng
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── setup.py
├── requirements.txt
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE
└── MANIFEST.in
```

---

## Chạy test

```bash
# Chạy toàn bộ test
pytest tests/ -v

# Chạy với coverage
pytest tests/ -v --cov=vietnamese_ai --cov-report=html

# Chạy lint
ruff check vietnamese_ai/ tests/
```

```
============================= 897 passed ==============================
```

---

## Roadmap

### Đã hoàn thành (v1.0 - v9.0)

| Version | Tính năng |
|---|---|
| v1.0 | Models, Preprocessing, NLP, AutoML, CV, Tuning, Pipeline, CLI, Docker, API |
| v1.1 | Deep Learning, CNN, Time Series, PhoBERT |
| v1.2 | Web UI, Model Registry, Streaming, ONNX Export |
| v2.0 | Multi-GPU, Distributed, Model Hub, Plugin System, Cloud Deploy, Marketplace, Enterprise |
| v3.0 | Mobile/Edge, NAS, Federated Learning, Real-time Pipeline |
| v4.0 | Cloud Platform SaaS, No-code Studio, Vietnamese LLM |
| v5.0 | PyTorch Trainer, Unsloth, GGUF, HuggingFace, Transformer, Tokenizer |
| v6.0 | PEFTConfig, LoRAPeft, Instruction Tuning (Alpaca/ShareGPT) |
| v7.0 | SFT, DPO, Reward Model, RLHF Pipeline |
| v8.0 | GPT Decoder-Only Pre-training, TextDataset, PreTrainer |
| v9.0 | Vietnamese LLM Configs (125M-7B), LM Eval Harness, Benchmark Runner |
| v10.0 | RAG Pipeline, Serving & Streaming, Prompt Engineering, NLP Extensions (NER/QA/Summarization/Translation/Spelling), Knowledge Distillation, Model Pruning, Production Hardening (Health Check, Circuit Breaker, Structured Logging, Metrics, Warm-up) |
| v11.0 | Self-Adapting Language Models (SALM): Self-Refinement, Self-Consistency, Adaptive LoRA, Self-Generated Data, Test-Time Training |
| v12.0 | Hệ thống Đa Tác Tử (Multi-Agent System): Agentic Swarm, Mixture of Agents (MoA), MCTS Planning |
| v13.0 | Edge AI & DePIN: NodeLlamaEngine, Intelligent EdgeRouter |
| v14.0 | Advanced RAG: GraphRAG (Knowledge Graph), Multi-modal RAG (Image-Text Embeddings) |
| v15.0 | Extreme Efficiency: 1.58-bit LLMs (BitLinear), Speculative Decoding Engine |
| v16.0 | Ultimate Performance: PagedAttention BlockManager, MemGPT Architecture (Long-term Memory), Rust Core Migration |
| v17.0 | Enterprise Security: AI Firewall, Agent Sandbox, Identity-Aware RAG, Data Sanitization (DLP), API Security Middleware |
| v17.1 | State-of-the-Art Security: Automated Red Teaming, Zero-Width Text Watermarking, TEE/ZKP (Cryptographic Proof) cho mạng lưới DePIN Edge AI, Tích hợp Tường lửa sâu vào LLM Core |
| v18.0 | Agentic Evolution: Human-in-the-Loop (HITL), Agent Memory 2.0 (Experience Memory) lưu trữ kinh nghiệm bằng VectorDB |
| v19.0 | Web3 DePIN & Hybrid Execution: Mạng lưới P2P (P2PTracker), Tokenomics (TokenLedger), Speculative Race Execution (Edge vs Cloud) |
| v20.0 | Real-time Agentic RAG: Cập nhật tài liệu thời gian thực (Event Bus), Tác tử RAG đa công cụ (Multi-step Reasoning RAG) |
| v21.0 | EvoNet-Studio Super Core: Zero-Dependency Orchestrator (Điều phối cụm), Monitor (Đo lường GPU), DataLake (DVC), Sandbox (Phân tích AST), DAG Workflow (Định tuyến song song), V-Plugin (Hot-Swap). Các lõi này được thiết kế tích hợp hoàn hảo với hệ sinh thái v12 (Agents) và v7 (Fine-Tuning) giúp framework vận hành mạnh mẽ như một nền tảng SaaS thực thụ. |
| v22.0 | Advanced Agentic Evolution & Self-Healing: Triển khai Knowledge Graph ngầm (GraphMemory) cho Agent, Hỗ trợ Cross-Modal RAG (Text-Image), Đối kháng bảo mật RedTeam/BlueTeam và đặc biệt là hệ thống Self-Healing (Tự vá lỗi Sandbox) và DevOps Agent (An toàn tự viết code qua AST & Dry-Run Pipeline). |
| v24.0 | Decentralized Swarm (Mạng lưới Tác tử Phi tập trung): Triển khai hệ sinh thái Swarm tự trị (MCTS Planning, Tokenomics) kết hợp cùng Edge Nodes trên nền tảng mạng P2P, biến AI thành một cụm siêu trí tuệ phi tập trung toàn cầu. |
| v25.0 | Web-Native & Cross-Platform: Đóng gói Framework thành các SDK đa nền tảng (C++ FFI, Node.js, PHP, WebAssembly, WebGPU), giải phóng Python backend để nhúng trực tiếp AI vào trình duyệt web và mọi ứng dụng thương mại. |
| v26.0 | EvoNet OS - Kỷ nguyên Kéo thả: Hệ điều hành trên nền Web thuần Vanilla JS/CSS. Cung cấp Visual Builder giao diện đồ họa DAG (Directed Acyclic Graph) để người dùng nối dây lắp ráp Logic AI, xuất file JSON tự động biên dịch sang code Python. Tích hợp Live Terminal Console. |
| v27.0 | The Hardware Extreme: Tối ưu lõi Máy tính tột đỉnh. Tích hợp bộ 9 công nghệ Datacenter: MLA (Nén RAM 90%), DeepSeekMoE (Giảm FLOPs 75%), Quantized KV Cache (INT8), FlashAttention Tiling, C++ JIT Compiler (Bypass GIL), Speculative Decoding (Rejection Sampling), Continuous Batching, Kernel Fusion và Ring Attention. |

### Tính liên kết của v21.0 - v27.0 với các phiên bản cũ
Rất nhiều nhà phát triển lo ngại kiến trúc mở rộng liên tục sẽ bị phân mảnh. Sự thật là chúng được thiết kế theo dạng vòng lặp (Organic Loop):
- **EvoNet OS (v26)** là lớp áo khoác trực quan cho tất cả các **Tác tử (v12)** và **RAG Pipeline (v10)**.
- **The Hardware Extreme (v27)** đập tan rào cản tốc độ cho các mô hình Toán học gốc (v2) và tự động tương thích với mạng phân tán **DePIN (v13)** thông qua Ring Attention.
- **C++ JIT Engine** biên dịch tự động các mã vòng lặp chậm chạp bằng cách gọi `g++` on-the-fly, giải phóng hoàn toàn sức mạnh đa nhân CPU mà không làm suy yếu nguyên tắc Zero-Dependency.

### Tính liên kết của v21.0 - v23.0 với các phiên bản cũ
Rất nhiều nhà phát triển lo ngại các lõi mới của v21.0 sẽ bị phân mảnh. Sự thật là chúng được thiết kế để bao bọc và cường hóa hệ thống hiện có:
- **V-Workflow** chịu trách nhiệm kết nối và định tuyến luồng thực thi của các **Tác tử (v12)** và **RAG Pipeline (v10)**.
- **V-Sandbox** được tích hợp thẳng vào **Agent Sandbox (v17)** để kiểm duyệt mã Python do Agent sinh ra.
- **V-DataLake** cung cấp luồng dữ liệu khổng lồ (OOM-free) cho các module **PyTorch Trainer (v15)** và **SFT/RLHF (v7)**.
- **V-Plugin** cho phép nạp động các **Tools (v12)** và **Models (v1)** vào runtime mà không cần khởi động lại.

### Tech Stack tương lai

- **Fine-tuning**: Unsloth (2x nhanh), LoRA, QLoRA, PEFT
- **Quantization**: GGUF (llama.cpp), GPTQ, AWQ
- **Training**: DeepSpeed ZeRO, FSDP, Gradient Checkpointing
- **Inference**: vLLM, TGI, llama.cpp
- **Models**: Llama, Mistral, Qwen, Gemma, PhoGPT

---

## Đóng góp

Xem [CONTRIBUTING.md](CONTRIBUTING.md) để biết quy trình đóng góp.

---

## Giấy phép

MIT License - xem [LICENSE](LICENSE)

---

<p align="center">
  <strong>Vietnamese AI Framework</strong> - Được xây dựng với ❤️ cho cộng đồng AI Việt Nam
</p>
