codelion/adaptive-classifier

Adaptive Classifier – 動態、持續學習的文字分類

簡介 – 一個基於 PyTorch 和 Hugging Face Transformers 的 Python 函式庫，讓您能訓練一個具備以下能力的文字分類器：

持續學習 – 即時新增範例，且不會發生災難性遺忘。
執行時期新增類別 – 無需重新訓練整個模型即可引入全新標籤。
保持線上 – 在生產環境中更新模型，實現零停機時間。
防禦對抗性或「遊戲化」輸入 – 具備博弈論「策略」模式，當使用者試圖操縱系統時，仍能保持預測的穩健性。
CPU 高速執行 – 自動 ONNX-Runtime 匯出，相較於原生 PyTorch 可獲得 2‑4 倍的速度提升。

核心組件

組件	角色
原型記憶體	基於 FAISS 的句子嵌入相似度搜尋；提供非參數化的「最近原型」訊號。
自適應神經頭	具備彈性權重鞏固 (EWC) 保護的可訓練分類層，避免新資料進入時發生遺忘。
混合預測	最終分數是原型相似度和神經頭輸出的加權混合（可透過 `prototype_weight` / `neural_weight` 設定）。
策略性分類	可選模式，增加成本感知對抗模型；您可以要求一般、策略性或穩健的預測。
多標籤支援	`MultiLabelAdaptiveClassifier` 增加基於 Sigmoid 的多標籤頭、自動閾值調整及各標籤閾值。
ONNX 匯出	內建轉換為量化 (INT8) 和全精度 ONNX；函式庫會自動在 CPU 上選擇最快版本。

快速入門 (30 秒)

from adaptive_classifier import AdaptiveClassifier

# 1️⃣ 使用任何 HuggingFace 模型初始化
clf = AdaptiveClassifier("bert-base-uncased")

# 2️⃣ 新增幾個標記範例
texts = ["The product works great!", "Terrible experience", "Neutral about this purchase"]
labels = ["positive", "negative", "neutral"]
clf.add_examples(texts, labels)

# 3️⃣ 進行預測
print(clf.predict("This is amazing!"))
# → [('positive', 0.85), ('neutral', 0.12), ('negative', 0.03)]

對於多標籤任務，請將 AdaptiveClassifier 替換為 MultiLabelAdaptiveClassifier 並呼叫 predict_multilabel。

安裝

pip install adaptive-classifier   # 自動拉取 ONNX Runtime

開發安裝：

git clone https://github.com/codelion/adaptive-classifier.git
cd adaptive-classifier
pip install -e .

重要基準測試 (README 報告)

場景	指標	一般模型	Adaptive (策略性)	Δ
對抗穩健性 (AI‑Secure/adv_glue)	清潔資料準確度	80.00 %	82.22 %	+2.22 %
	對抗資料準確度	60.00 %	82.22 %	+22.22 %
	穩健性下降	–20 %	0 %	perfect
幻覺偵測 (RAGTruth)	整體 F1	–	51.54 %	–
LLM 路由成本節省 (arena‑hard‑auto‑v0.1)	成本降低	25.60 %	32.40 %	+6.80 %
	效率比	1.00×	1.27×	+27 %

持續學習運作原理

新範例儲存在原型記憶體中，並可選擇用於微調神經頭。
new_class_example_threshold (預設 10) 控制新標籤何時獲得自己的原型權重；在此之前，神經頭主導預測。
彈性權重鞏固 (EWC) 對神經頭進行正規化，確保模型適應新資料時，舊類別仍能保持效能。

策略性 (反遊戲化) 模式

clf = AdaptiveClassifier(
    "bert-base-uncased",
    config={
        "enable_strategic_mode": True,
        "cost_function_type": "linear",
        "cost_coefficients": {
            "sentiment_words": 0.5,
            "length_change": 0.1,
            "word_substitution": 0.3,
        },
        "strategic_blend_regular_weight": 0.6,
        "strategic_blend_strategic_weight": 0.4,
    },
)

predict → 混合一般與策略性分數。
predict_strategic → 純策略性視角 (模擬攻擊者)。
predict_robust → 假設輸入可能已被操縱並回傳強化後的預測。

模型持久化與 Hub 整合

clf.save("./my_model")                     # 儲存 PyTorch + ONNX (量化與全精度)
AdaptiveClassifier.load("./my_model")      # 在 CPU 上自動載入量化 ONNX
clf.push_to_hub("adaptive-classifier/my-model")
clf2 = AdaptiveClassifier.from_pretrained("adaptive-classifier/my-model")

使用場景

客戶支援工單路由 – 持續新增問題類別，無需停機。
動態產品類別標記 – 出現新產品線時，可立即教導模型。
企業 LLM 管線 – 使用內建路由或幻覺偵測器來降低成本並提高可靠性。
任何必須在演進過程中保持線上的生產級文字分類服務。

社群與授權

Apache 2.0 授權 – 可免費商業使用。
PyPI 下載量顯示活躍採用；儲存庫設有討論區以提供支援。
預訓練模型與示範筆記本託管於專屬的 HuggingFace 組織。

總結 – Adaptive Classifier 是一個開箱即用、基於 PyTorch 的函式庫，結合了基於原型的相似度、持續學習頭以及可選的博弈論防禦，並具備開箱即用的 ONNX 加速功能，適用於生產級、零停機時間的文字分類。