fewshotkit 0.0.1

Embedding-based few-shot learning library for keyword spotting and related tasks

fewshotkit

fewshotkit là thư viện Python cho bài toán few-shot learning dựa trên embedding (đặc biệt phù hợp với Keyword Spotting).

Mục tiêu của thư viện:

• Nhẹ, dễ dùng, API gần giống sklearn.
• Không chứa encoder (bạn tự tạo embedding từ pipeline khác).
• Chạy offline, deterministic, tập trung vào suy luận few-shot.

---

1. fewshotkit giải quyết bài toán gì?

Bạn đã có embedding vector (NumPy) và muốn:

• Huấn luyện nhanh từ ít mẫu support (fit).
• Dự đoán class cho query (predict).
• Lấy xác suất cho từng class (predict_proba).
• Đánh giá bằng episodic few-shot (evaluate_n_way_k_shot).

fewshotkit không trích xuất đặc trưng từ audio thô, chỉ làm việc trên embedding đầu vào.

---

2. Cài đặt

Cài đặt cơ bản

cd /home/ngocan/Projects/KWS_Project/Fewshot
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Cài đặt cho phát triển (test/lint/benchmark)

pip install -e .[dev]

---

3. Kiểm tra nhanh môi trường

Đảm bảo python và pip cùng một virtualenv:

which python
python -c "import sys; print(sys.executable)"

Cả 2 lệnh nên trỏ về: /home/ngocan/Projects/KWS_Project/Fewshot/.venv/bin/python

---

4. Định dạng dữ liệu đầu vào

Input chuẩn cho model

• X_support: np.ndarray, shape (N, D)
• y_support: np.ndarray, shape (N,)
• X_query: np.ndarray, shape (M, D)

Output

• predict(X_query): shape (M,)
• predict_proba(X_query): shape (M, num_classes)

Lưu ý

• D (embedding dimension) phải nhất quán giữa support/query.
• y_support có thể là số hoặc chuỗi.
• Nếu shape sai, thư viện sẽ raise ValueError rõ ràng.

---

5. API chính

Import public API:

from fewshotkit import (
    ProtoNet,
    SiameseKNN,
    MatchingNet,
    evaluate_n_way_k_shot,
)

Tất cả model đều hỗ trợ:

• fit(X, y)
• predict(X)
• predict_proba(X)
• score(X, y)
• add_class(label, embeddings)
• remove_class(label)

---

6. Dùng từng model

6.1 ProtoNet (khuyên dùng để bắt đầu)

import numpy as np
from fewshotkit import ProtoNet

x_support = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [1.1, 1.0]])
y_support = np.array(["off", "off", "on", "on"], dtype=object)
x_query = np.array([[0.05, 0.0], [1.05, 1.0]])

model = ProtoNet(metric="cosine")  # hoặc metric="euclidean"
model.fit(x_support, y_support)

pred = model.predict(x_query)
proba = model.predict_proba(x_query)

Cơ chế: tính centroid cho từng class rồi so sánh query với centroid.

6.2 SiameseKNN

from fewshotkit import SiameseKNN

model = SiameseKNN(metric="euclidean", k=3)
model.fit(x_support, y_support)
pred = model.predict(x_query)

Cơ chế: so similarity tới toàn bộ support, voting theo top-k.

6.3 MatchingNet

from fewshotkit import MatchingNet

model = MatchingNet(metric="cosine")
model.fit(x_support, y_support)
pred = model.predict(x_query)

Cơ chế: attention softmax giữa query và support để tính xác suất lớp.

---

7. Unknown detection (phát hiện ngoài tập lớp)

Bạn có thể set ngưỡng để trả về nhãn unknown khi độ tương đồng thấp:

from fewshotkit import ProtoNet

model = ProtoNet(metric="cosine", threshold=0.8, unknown_label="unknown")
model.fit(x_support, y_support)
pred = model.predict(x_query)

Nếu score tốt nhất < threshold thì output là unknown_label.

---

8. Thêm/Xóa class động

model.add_class("maybe", np.array([[0.5, 0.5], [0.6, 0.5]]))
model.remove_class("maybe")

Hữu ích khi cần enroll class mới mà không train lại pipeline encoder.

---

9. Đánh giá episodic few-shot

import numpy as np
from fewshotkit import ProtoNet, evaluate_n_way_k_shot

x = np.random.randn(300, 64)
y = np.repeat(np.arange(10), 30)

model = ProtoNet(metric="euclidean")
result = evaluate_n_way_k_shot(
    model,
    x,
    y,
    n_way=5,
    k_shot=5,
    n_query=10,
    n_episodes=100,
    random_state=42,
)

print(result["accuracy_mean"], result["accuracy_std"])

Kết quả trả về gồm:

• accuracy_mean
• accuracy_std
• episode_accuracies
• metadata episode (n_way, k_shot, n_query, n_episodes, random_state)

---