luvox-ai/llm-intent

Language inference

Bộ inference độc lập cho head phân loại vietnamese / english đã train trên hidden states của nvidia/Muse-Glimmer-30B-NVFP4. Có thể copy toàn bộ thư mục language sang nơi khác để sử dụng; chỉ cần Python và PyTorch.

Đây là checkpoint classifier MLP, nhận hidden states đã trích xuất từ model nguồn. Bộ này không chứa trọng số LLM 30B hay tokenizer và không nhận trực tiếp chuỗi văn bản để tự sinh hidden states.

Nội dung

• model.py: kiến trúc TokenMLPClassifier, giữ nguyên từ model.py gốc.
• inference.py: API LanguagePredictor và CLI, không import code ở thư mục gốc.
• checkpoints/language/, checkpoints/hyphen/, checkpoints/slash/: mỗi thư mục chứa best_model.pt, split.json, train_summary.json của model tương ứng.
• checkpoints/labels.json: nhãn của cả 3 model dưới dạng mảng chuỗi, theo đúng thứ tự nhãn trong checkpoint.
• smoke_data/token_000353.pt: một record gốc, sample_id=6, thuộc split test.
• smoke_data/manifest.json: nguồn dữ liệu, SHA-256, nhãn và xác suất tham chiếu.
• smoke_test.py: kiểm tra nhãn, xác suất hợp lệ và độ khớp với model gốc trên CPU.

Nhãn của các model

Preset dán nhãn/train của ứng dụng hiện dùng ["vietnamese", "english", "unknown", "number"] (ID 0, 1, 2, 3). Checkpoint language đóng gói bên dưới vẫn là bản hai lớp. Sau khi dán nhãn thêm dữ liệu unknown, number và train lại, cần thay checkpoint và cập nhật labels.json theo checkpoint mới.

Nội dung checkpoints/labels.json:

{
  "hyphen": ["thang", "nam", "den", "tru", "silent"],
  "language": ["vietnamese", "english"],
  "slash": ["thang", "nam", "tren", "silent"]
}

Vị trí phần tử trong mỗi mảng là label ID, bắt đầu từ 0. Ví dụ: hyphen[2] = "den", language[1] = "english", slash[2] = "tren". Tra tên nhãn bằng labels[model_name][label_id]; giữ nguyên thứ tự mảng khi ánh xạ đầu ra logits hoặc xác suất sang tên nhãn. Danh sách này đã được đối chiếu với trường labels và config.num_classes trong cả 3 file best_model.pt.

Chạy từ thư mục gốc dự án

.venv/bin/python inference_script/language/smoke_test.py
.venv/bin/python inference_script/language/inference.py
.venv/bin/python inference_script/language/inference.py \
  --input annotated_data/language/offline/nvidia-muse-glimmer-30b-nvfp4/tokens/token_000361.pt \
  --device cpu --output /tmp/language_prediction.json

CLI mặc định dùng checkpoint và smoke data đi kèm, đường dẫn được xác định theo vị trí file nên không phụ thuộc thư mục làm việc. Có thể chọn checkpoint khác bằng --checkpoint và GPU bằng --device cuda:0.

Khi copy sang môi trường khác:

python -m pip install -r /path/to/language/requirements.txt
python /path/to/language/smoke_test.py
python /path/to/language/inference.py --input /path/to/token_record.pt

Mẫu smoke dự đoán " Công" → vietnamese, xác suất khoảng 0.576093. Một mẫu smoke chỉ xác nhận đường chạy inference; số liệu đánh giá đầy đủ của lần train được giữ trong train_summary.json.

API Python

import torch
from inference_script.language.inference import LanguagePredictor

predictor = LanguagePredictor(device="cpu")  # Load một lần, dùng lại nhiều lần.
result = predictor.predict_file("path/to/token_record.pt")

# Hoặc truyền hidden states đã trích xuất từ đúng model nguồn.
# states: torch.Tensor [3, N, 6656], theo thứ tự layer IDs bên dưới.
# predictions = predictor.predict(states, layer_indices=[3, 25, 51])

predict_record() / predict_file() nhận record có layer_embeddings, layer_indices, label_names (đúng thứ tự nhãn của checkpoint). word, token_ids, sample_id, token_index, label là metadata tùy chọn; khi có label, kết quả có thêm expected_label, expected_label_name, correct. predict() nhận tensor và layer IDs trực tiếp, trả một dự đoán cho mỗi token, gồm nhãn số, tên nhãn, confidence và xác suất của cả hai lớp.

Kiến trúc và hợp đồng đầu vào

• Layer IDs của nguồn offline: [3, 25, 51], hidden size 6656 mỗi layer. Đầu vào có thể chứa thêm layer hoặc đổi thứ tự nếu khai báo đúng layer_indices.
• Ghép feature → 19968 chiều → LayerNorm → Linear(19968, 64) → GELU → Dropout(0.9) → Linear(64, 2). Inference gọi eval() nên dropout tắt.
• Nhãn theo checkpoint: 0=vietnamese, 1=english.
• Alignment: previous_token_hidden_state_v1. Hidden state phải là trạng thái tại vị trí sinh ra token cần phân loại. Các shard offline đã căn đúng hàng; không dịch thêm một hàng đối với token record đi kèm. Nếu tự trích từ LLM, phải tái tạo đúng ngữ nghĩa layer và alignment của nguồn offline; không mặc định layer ID của shard bằng index trong tuple hidden_states của backend khác.
• Token record cũ không lưu trường alignment; loader dùng hợp đồng của nguồn offline cho trường hợp này và từ chối alignment khác nếu được khai báo.
• Tính toán classifier bằng float32 trong torch.inference_mode().

Smoke test kiểm tra so với xác suất tham chiếu lấy từ model.py và checkpoint gốc, không dùng xác suất do bộ inference mới tạo làm chuẩn.