Flamehaven Tensor-Canon v0.1.4 - trình kiểm tra nhẹ cho shape tensor PyTorch/NumPy + drift (MMD)

Xin chào.
Tuần này tôi muốn chia sẻ Flamehaven Tensor-Canon (v0.1.4).

---

Khi phát triển bằng PyTorch, vấn đề shape của tensor luôn cần được chú ý.
Ví dụ, với đầu vào hình ảnh thì thường là dạng NCHW
(batch N, kênh C, chiều cao H, chiều rộng W).

Nhưng trong vận hành (production) thực tế, những vấn đề dưới đây còn đáng sợ hơn.

• shape thì đúng, nhưng phân phối dữ liệu âm thầm thay đổi
• mô hình vẫn tiếp tục chạy, nhưng hiệu năng/chỉ số chỉ từ từ sụp đổ

Vì vậy, tôi đã tạo ra Tensor-Canon không chỉ để kiểm tra shape, mà còn để kiểm tra một cách nhẹ và nhanh xem phân phối đầu vào có thay đổi hay không.

---

Các công cụ hiện có vốn đã rất mạnh, nhưng vai trò thì khác nhau

• Einops
  Biến đổi/thao tác shape trực quan dựa trên chuỗi
  → Tối ưu cho phép toán/chuyển đổi hơn là kiểm chứng

• Jaxtyping
  Kiểm chứng dựa trên type hint (thân thiện với IDE)
  → Tuy nhiên cú pháp generic của Python dễ trở nên dài dòng

• Torchtyping
  Kiểm chứng shape gọn nhẹ
  → Phạm vi chủ yếu xoay quanh shape

• Pydantic
  Tiêu chuẩn cho kiểm chứng dữ liệu nói chung
  → Nhưng với việc kiểm chứng mảng đa chiều như tensor thì hơi nặng và bất tiện

---

Nhưng “guardrail cho đầu vào” của Flamehaven Tensor-Canon thì khác

Tensor-Canon không phải là framework,
mà là guardrail nhẹ dùng tại ranh giới đầu vào của mô hình.

• ✅ Kiểm chứng shape (cơ bản)
• ✅ Resonance (phát hiện drift)
  • Phát hiện thay đổi phân phối dựa trên MMD
  • Dùng mà không cần công cụ MLOps nặng nề
• ✅ Covenant DSL (hợp đồng dạng chuỗi)
  • Thay vì generic kiểu phức tạp như Typing[Float, ...]
  • Dùng đặc tả dễ đọc ngay như "batch channels 224 224"
• ✅ Dual Backend
  • Tiền xử lý bằng NumPy, suy luận bằng PyTorch
    bảo vệ pipeline thực tế bằng một cú pháp thống nhất
  • Áp dụng hợp đồng nhất quán từ data loader tới đầu vào mô hình

---

🔹 Thử Tensor-Canon chỉ trong 3 phút (PyTorch)

1️⃣ Cài đặt (30 giây)

pip install flamehaven-tensor-canon  

---

2️⃣ Kiểm chứng shape (1 phút)

import torch  
from tensor_canon import validate  
  
# Đặc tả đầu vào mong đợi (NCHW)  
spec = "batch channels 224 224"  
  
x = torch.randn(32, 3, 224, 224)  
  
# Nếu shape không khớp sẽ phát sinh ValueError  
validate(x, spec, key="image_input")  
  
print("OK: thỏa mãn hợp đồng shape")  

---

3️⃣ Phát hiện phân phối (Drift) (1 phút 30 giây)

import torch  
from tensor_canon import TensorCanonPrime  
  
engine = TensorCanonPrime(drift_threshold=0.05)  
  
# Đăng ký chuẩn tham chiếu từ dữ liệu huấn luyện  
train = torch.randn(100, 512)  
engine.register_golden("embedding", train)  
  
# Kiểm tra dữ liệu production  
prod = torch.randn(10, 512) + 0.5  # dịch chuyển phân phối nhẹ  
score = engine.check_resonance("embedding", prod)  
  
print("drift score:", score)  
  
if score > 0.05:  
    print("⚠️ phát hiện drift")  

---

Khi nào nên dùng

• Pipeline tiền xử lý NumPy → đầu vào mô hình PyTorch
• Sanity check cho đầu vào DataLoader
• Khi “shape thì đúng nhưng chỉ số lại giảm”
• Guardrail tối thiểu trước khi đưa vào các hệ MLOps nặng

---

🔹 Chính sách triển khai / phát hành (tham khảo)

• Có thể cài đặt trực tiếp từ gói PyPI
• GitHub release được quản lý theo kiểu tag-based
• Chỉ với các tag đã được kiểm chứng, CI mới build wheel / sdist
  để đính kèm vào GitHub Release
• Để đảm bảo tính ổn định và khả năng tái lập,
  thay vì phát hành tự động và thường xuyên, dự án duy trì cách chỉ phát hành các bản build đã được kiểm chứng

---

Hoan nghênh feedback / issue / PR

Đặc biệt nếu bạn từng gặp trường hợp “shape thì đúng nhưng lại hỏng ở production”,
tôi muốn cùng phát triển thêm các pattern hợp đồng (DSL) dựa trên những ví dụ đó.

Và ⭐ một ngôi sao thực sự là nguồn động lực rất lớn.
Dự án này đang được phát triển mỗi tuần với động lực từ từng ngôi sao một.
Nếu bạn dùng thử và thấy ổn, tôi sẽ rất cảm kích nếu bạn nhấn star để ủng hộ!