メインコンテンツまでスキップ

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 エクスポートに置き換えます。

性能ベンチマーク​

指標ルール層 V0ML V1
精度(合成)~60%~75%+
レイテンシ(p99)<1ms20-50ms
信頼度の整合N/APlatt 校正済み
フォールバックチェーン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 でのセマンティックキャッシュ検索に使われます