ML 分類器サービス
概要
ML 分類器は、BAAI/bge-small-en-v1.5 と 3 クラスの分類ヘッドを実行する、自社運用の FastAPI サービスです。ルール層の V0 分類器より高い精度を提供します(約 75% 対 約 60%)。
クイックスタート
Docker Compose
classifier:
build:
context: .
dockerfile: deploy/classifier/Dockerfile
ports:
- "8082:8080"
deploy:
resources:
limits: { memory: 2G, cpus: "2.0" }
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 5s
retries: 3
手動実行
pip install fastapi uvicorn transformers torchsentencepiece
python deploy/classifier/server.py --port 8082
API エンドポイント
POST /v1/classify
プロンプトの複雑さのレベルを分類します。
リクエスト:
{
"text": "Debug this Python code:\n\ndef calculate_sum(numbers):\n total = 0\n for n in numbers:\n total += n\n return total",
"org_id": "org-123"
}
レスポンス:
{
"class_name": "hard",
"confidence": 0.87
}
GET /health
ヘルスチェックのエンドポイントです。
レスポンス: {"status": "healthy", "model": "BAAI/bge-small-en-v1.5"}
モデルの詳細
- ベースモデル:
BAAI/bge-small-en-v1.5(パラメータ数 137M、最大 512 トークン) - ヘッド: 3 クラスの線形分類器(easy/medium/hard)
- 推論レイテンシ: CPU 上で約 20ms(単一リクエスト)
- 埋め込み次元: 384(セマンティックキャッシュの検索に使用)
ファインチューニングのパイプライン
手順 1: データセットの構築
python scripts/build_dataset.py --output datasets/classifier/prompts_train.jsonl
# Generates 9k synthetic prompts (40% easy, 35% medium, 25% hard)
手順 2: ファインチューニング
python scripts/train_classifier.py \
--train datasets/classifier/prompts_train.jsonl \
--test datasets/classifier/prompts_test.jsonl \
--output artifacts/classifier-v1.pt \
--epochs 5 \
--batch-size 8
手順 3: ONNX へのエクスポート
pip install optimum onnxruntime
optimum export onnx \
--model artifacts/classifier-v1.pt \
--task text-classification \
classifier.onnx
手順 4: 導入
Docker イメージ内の model.pt を、新しい ONNX エクスポートに置き換えます。
性能ベンチマーク
| 指標 | ルール層 V0 | ML V1 |
|---|---|---|
| 精度(合成) | ~60% | ~75%+ |
| レイテンシ(p99) | <1ms | 20-50ms |
| 信頼度の整合 | N/A | Platt 校正済み |
| フォールバックチェーン | N/A | ルール層 V0 |
サーキットブレーカーとの統合
ML サービスはサーキットブレーカーで包まれています(pkg/classifier/circuit_breaker.go を参照)。サービスが連続して 3 回失敗すると、30 秒間 Open 状態になります。すべてのリクエストは HTTP 呼び出しなしでルール層へ即座に失敗します。30 秒後、プローブリクエスト 1 件が復旧を試験します。
スケーリングの注意
- CPU のみの推論で、約 100 RPS には十分です
- 1000 RPS を超える場合は、複数スレッドの ONNX Runtime、または GPU アクセラレーションを検討します
- 埋め込み出力(384 次元)は、pgvector でのセマンティックキャッシュ検索に使われます