LightRAG/docs/VietnameseEmbedding_VI.md

Tích hợp Vietnamese Embedding cho LightRAG

Tài liệu này hướng dẫn sử dụng mô hình AITeamVN/Vietnamese_Embedding với LightRAG để tăng cường khả năng truy xuất thông tin tiếng Việt.

Thông tin Mô hình

• Mô hình: AITeamVN/Vietnamese_Embedding
• Mô hình gốc: BAAI/bge-m3
• Loại: Sentence Transformer
• Độ dài tối đa: 2048 tokens
• Số chiều embedding: 1024
• Hàm tương đồng: Dot product similarity
• Ngôn ngữ: Tiếng Việt (cũng hỗ trợ các ngôn ngữ khác từ BGE-M3)
• Dữ liệu huấn luyện: ~300,000 bộ ba (query, văn bản dương, văn bản âm) tiếng Việt

Tính năng

✅ Embedding tiếng Việt chất lượng cao - Được fine-tune đặc biệt cho văn bản tiếng Việt
✅ Hỗ trợ đa ngôn ngữ - Kế thừa khả năng đa ngôn ngữ từ BGE-M3
✅ Xử lý văn bản dài - Hỗ trợ tới 2048 tokens mỗi đầu vào
✅ Xử lý hiệu quả - Tự động phát hiện thiết bị (CUDA/MPS/CPU)
✅ Embedding chuẩn hóa - Sẵn sàng cho dot product similarity
✅ Tích hợp dễ dàng - Thay thế trực tiếp các hàm embedding khác

Cài đặt

1. Cài đặt LightRAG

cd LightRAG
pip install -e .

2. Cài đặt các thư viện cần thiết

Các thư viện sau sẽ được tự động cài đặt:

• transformers
• torch
• numpy

3. Thiết lập HuggingFace Token

Bạn cần token HuggingFace để truy cập mô hình:

export HUGGINGFACE_API_KEY=
# hoặc
export HF_TOKEN=

Lấy token tại: https://huggingface.co/settings/tokens

Bắt đầu nhanh

Ví dụ đơn giản

import os
import asyncio
from lightrag import LightRAG, QueryParam
from lightrag.llm.openai import gpt_4o_mini_complete
from lightrag.llm.vietnamese_embed import vietnamese_embed
from lightrag.kg.shared_storage import initialize_pipeline_status
from lightrag.utils import EmbeddingFunc

WORKING_DIR = "./vietnamese_rag_storage"

async def main():
    # Lấy HuggingFace token
    hf_token = os.environ.get("HUGGINGFACE_API_KEY")
    
    # Khởi tạo LightRAG với Vietnamese embedding
    rag = LightRAG(
        working_dir=WORKING_DIR,
        llm_model_func=gpt_4o_mini_complete,
        embedding_func=EmbeddingFunc(
            embedding_dim=1024,
            max_token_size=2048,
            func=lambda texts: vietnamese_embed(
                texts,
                model_name="AITeamVN/Vietnamese_Embedding",
                token=hf_token
            )
        ),
    )
    
    # Khởi tạo storage và pipeline
    await rag.initialize_storages()
    await initialize_pipeline_status()
    
    # Chèn văn bản tiếng Việt
    await rag.ainsert("Việt Nam là một quốc gia nằm ở Đông Nam Á.")
    
    # Truy vấn
    result = await rag.aquery(
        "Việt Nam ở đâu?",
        param=QueryParam(mode="hybrid")
    )
    print(result)
    
    await rag.finalize_storages()

if __name__ == "__main__":
    asyncio.run(main())

Sử dụng với file .env

Tạo file .env trong thư mục dự án:

# HuggingFace Token cho Vietnamese Embedding
HUGGINGFACE_API_KEY=

# Cấu hình LLM
OPENAI_API_KEY=your_openai_key_here
LLM_BINDING=openai
LLM_MODEL=gpt-4o-mini

# Cấu hình Embedding
EMBEDDING_MODEL=AITeamVN/Vietnamese_Embedding
EMBEDDING_DIM=1024

Các script ví dụ

1. Ví dụ đơn giản

python examples/lightrag_vietnamese_embedding_simple.py

Ví dụ tối thiểu về xử lý văn bản tiếng Việt.

2. Demo đầy đủ

python examples/vietnamese_embedding_demo.py

Demo toàn diện bao gồm:

• Xử lý văn bản tiếng Việt
• Xử lý văn bản tiếng Anh (hỗ trợ đa ngôn ngữ)
• Xử lý văn bản hỗn hợp
• Nhiều ví dụ truy vấn

Tài liệu API

vietnamese_embed()

Tạo embeddings cho văn bản sử dụng mô hình Vietnamese Embedding.

async def vietnamese_embed(
    texts: list[str],
    model_name: str = "AITeamVN/Vietnamese_Embedding",
    token: str | None = None,
) -> np.ndarray

Tham số:

• texts (list[str]): Danh sách các văn bản cần embedding
• model_name (str): Tên mô hình trên HuggingFace
• token (str, optional): HuggingFace API token (đọc từ env nếu không cung cấp)

Trả về:

• np.ndarray: Mảng embeddings với shape (len(texts), 1024)

Ví dụ:

from lightrag.llm.vietnamese_embed import vietnamese_embed

texts = ["Xin chào", "Tạm biệt", "Cảm ơn"]
embeddings = await vietnamese_embed(texts)
print(embeddings.shape)  # (3, 1024)

Sử dụng nâng cao

Lựa chọn thiết bị

Mô hình tự động phát hiện và sử dụng thiết bị tốt nhất:

1. CUDA (nếu có)
2. MPS (cho Apple Silicon)
3. CPU (dự phòng)

Bật debug logging để xem thiết bị đang sử dụng:

from lightrag.utils import setup_logger

setup_logger("lightrag", level="DEBUG")

Xử lý batch

Hàm embedding hỗ trợ xử lý batch hiệu quả:

# Xử lý nhiều văn bản hiệu quả
large_batch = ["Văn bản 1", "Văn bản 2", ..., "Văn bản 1000"]
embeddings = await vietnamese_embed(large_batch)

Khắc phục sự cố

Vấn đề: "No HuggingFace token found"

Giải pháp: Thiết lập biến môi trường:

export HUGGINGFACE_API_KEY="your_token"
# hoặc
export HF_TOKEN="your_token"

Vấn đề: "Model download fails"

Giải pháp:

1. Kiểm tra kết nối internet
2. Xác thực token HuggingFace hợp lệ
3. Đảm bảo đủ dung lượng ổ đĩa (~2 GB)

Vấn đề: "Out of memory error"

Giải pháp:

1. Giảm kích thước batch
2. Sử dụng CPU thay vì GPU (chậm hơn nhưng dùng ít bộ nhớ hơn)
3. Đóng các ứng dụng khác đang dùng GPU/RAM

Vấn đề: "Embedding generation chậm"

Giải pháp:

1. Đảm bảo đang sử dụng GPU (kiểm tra logs)
2. Cài đặt PyTorch với CUDA: pip install torch --index-url https://download.pytorch.org/whl/cu118
3. Giảm max_token_size nếu văn bản ngắn hơn

So sánh với các mô hình embedding khác

Mô hình	Số chiều	Max Tokens	Ngôn ngữ	Fine-tuned cho tiếng Việt
Vietnamese_Embedding	1024	2048	Đa ngôn ngữ	✅ Có
BGE-M3	1024	8192	Đa ngôn ngữ	❌ Không
text-embedding-3-large	3072	8191	Đa ngôn ngữ	❌ Không
text-embedding-3-small	1536	8191	Đa ngôn ngữ	❌ Không

Hỗ trợ

Để báo cáo vấn đề về tích hợp Vietnamese embedding:

• Mở issue trên LightRAG GitHub
• Gắn tag vietnamese-embedding

Để báo cáo vấn đề về mô hình:

• Truy cập AITeamVN/Vietnamese_Embedding

Giấy phép

Tích hợp này tuân theo giấy phép của LightRAG. Mô hình Vietnamese_Embedding có thể có điều khoản giấy phép riêng - vui lòng kiểm tra trang mô hình để biết chi tiết.

Lời cảm ơn

• AITeamVN đã huấn luyện và phát hành mô hình Vietnamese_Embedding
• BAAI cho mô hình gốc BGE-M3
• Nhóm LightRAG cho framework RAG xuất sắc