タスク分類器
概要
タスク分類器はユーザーのプロンプトを分析して複雑さの水準を決め、そのあとリクエストを適切なモデルティアへ経路付けします。単純なタスクには安価なモデルを、複雑なタスクにはプレミアムなモデルを使います。これは、Yabanin を汎用プロキシと差別化する第 1 の堀となる機能です。
アーキテクチャ
┌─────────────┐
Request ───────► │ Classifier │
│ Pipeline │
└──────┬──────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Easy │ │ Medium │ │ Hard │
│ ↓ │ │ ↓ │ │ ↓ │
│ Cheap │ │ Mid │ │ Premium │
│ Pool │ │ Pool │ │ Pool │
└─────────┘ └─────────┘ └─────────┘
コンポーネント
| コンポーネント | パッケージ | 説明 |
|---|---|---|
| 分類器インターフェース | pkg/classifier/classifier.go | Classify() と Name() メソッドを持つ Classifier インターフェース |
| ルールティア V0 | pkg/classifier/rule_tier.go | プロンプトの特徴(キーワード、長さ、コードフェンス)に基づく決定的な分類 |
| ML 分類器 V1 | pkg/classifier/ml_v1.go | 自社運用の bge-small-en-v1.5 モデルサービス向け HTTP クライアント |
| 分類器キャッシュ | pkg/classifier/registry_cached*.go | 4 段の検索: Redis の完全一致 → DB の完全一致 → DB のセマンティック(pgvector)→ 内部の分類器 |
| ティアルータ | pkg/router/tier_pool.go | 複雑さのクラスごとに、重み付きラウンドロビンでプールを選ぶ |
| サーキットブレーカ | pkg/classifier/circuit_breaker.go | ML サービスの健全性のための Closed/Open/HalfOpen 状態機械 |
| Evalgate ジャッジ | pkg/evalgate/judge.go | 安価な応答とプレミアムな応答を比べる、LLM をジャッジとする品質評価 |
| 較正 | pkg/classifier/calibration.go | 分類器の確信度を実際の精度に揃える Platt スケーリング |
| A/B 割り当て | pkg/classifier/ab_assigner.go | 分類器の実験のための、決定的な SHA-256 バケット分け |
| フィードバック収集 | pkg/feedback/collector.go | オンライン学習のために thumbs_up/down/regenerate のシグナルを記録する |
分類クラス
| クラス | 説明 | キーワード例 | 対応するティア |
|---|---|---|---|
| Easy | 意図が明確な、単純で短いプロンプト | summarize、translate、list、extract、name、what is | 安価プール(gpt-4o-mini) |
| Medium | 一般的な質問。中程度の複雑さ | 強い目印がない。200–2000 トークン | 中間プール |
| Hard | 複雑な推論、デバッグ、アーキテクチャ | debug、architect、step by step、code review、troubleshoot | プレミアムプール(gpt-4o) |
組織ごとの経路モード
各組織は、管理 API から経路の振る舞いを上書きできます。
| モード | 振る舞い | しきい値 |
|---|---|---|
auto(既定) | 分類器の確信度で経路を決める | 0.6 |
aggressive_cost | 積極的に安価な経路を選ぶ | 0.4 |
always_premium | すべてのリクエスト → プレミアムプール | 該当なし |
always_cheap | すべてのリクエスト → 安価プール | 該当なし |
classifier_only | 確信度が非常に高いときだけ経路を決める | 0.9 |
disabled | 分類器を完全にスキップする | 該当なし |
管理 API
GET /api/organizations/{id}/routing # Get org routing settings
PATCH /api/organizations/{id}/routing # Update routing_mode + threshold (root only)
POST /v1/feedback # Submit thumbs_up/down/regenerate feedback (Authorization: Bearer <org or agent API key>; the org is derived from the key)
設定
| 環境変数 | 既定 | 説明 |
|---|---|---|
YABANIN_CLASSIFIER_SERVICE_URL | "" | ML 分類器サービスの URL(空 = ルールティアのみ) |
YABANIN_EVALGATE_URL | "" | 品質評価 のためのジャッジのエンドポイント |
YABANIN_EVALGATE_API_KEY | "" | ジャッジのエンドポイント用 API キー |
YABANIN_EVALGATE_MODEL | gpt-4o-mini | ジャッジとして使うモデル |
YABANIN_EVALGATE_SAMPLE_RATE | 0.05 | サンプルする、Medium / 低確信度リクエストの割合 |
YABANIN_CLASSIFIER_CIRCUIT_ENABLED | true | ML サービス向けサーキットブレーカを有効にする |
YABANIN_CLASSIFIER_CIRCUIT_THRESHOLD | 3 | open 状態になるまでの連続失敗回数 |
YABANIN_CLASSIFIER_CIRCUIT_TIMEOUT | 30s | open 状態のまま留まる時間 |
メトリクス
| メトリクス | 型 | ラベル | 説明 |
|---|---|---|---|
classifier_class_total | カウンタ | class、source | クラスとソースごとの分類回数 |
classifier_confidence | ヒストグラム | — | 分類の確信度の分布 |
classifier_latency_seconds | ヒストグラム | source | 分類のレイテンシ |
tier_routing_total | カウンタ | class、from_model、to_model | モデル経路の決定 |
tier_routing_skipped_total | カウンタ | reason | スキップされた経路(low_confidence など) |
classifier_cache_hit_total | カウンタ | type | 種類ごとのキャッシュヒット(exact/semantic) |
classifier_circuit_breaker_state | ゲージ | classifier | サーキットブレーカの状態(0=closed、1=open、2=half-open) |
evalgate_verdict_total | カウンタ | should_upgrade | ジャッジ判定の回数 |
evalgate_latency_seconds | ヒストグラム | — | ジャッジ評価のレイテンシ |
新しいルールの追加
ルールは pkg/classifier/rule_tier.go の Classify メソッドで定義されます。ルールの順序は次のとおりです。
- Hard ルールを最初に確認する(プロンプトが 2000 トークン超、hard キーワード、コードフェンスが 50 行超、ツール呼び出し)
- Easy ルールを次に確認する(短いプロンプト + easy キーワード、コードフェンスなし)
- 既定 → Medium
新しいルールを追加するには、次のようにします。
features.goのキーワードリストに、キーワードまたはパターンを追加する- 既定の Medium を返す前に、
rule_tier.goへ判定を追加する - 適切な確信度の値を設定する(0.60–0.90)
rule_tier_test.goにテストケースを追加する
ML モデルの再学習
- データセットを生成する:
python scripts/build_dataset.py --output datasets/classifier/prompts_train.jsonl - ファインチューンする:
python scripts/train_classifier.py --train datasets/classifier/prompts_train.jsonl --test datasets/classifier/prompts_test.jsonl --output artifacts/classifier-v1.pt
サーブ用に ONNX へエクスポートします(optimum パッケージが必要です):
optimum export onnx --model artifacts/classifier-v1.pt --task text-classification classifier.onnx
- 新しいモデルの重みを分類器サービスへ導入し、再起動する
制限
- 英語のプロンプトのみ(bge-small-en-v1.5)
- 非常に 短いプロンプト(20 文字未満)は、誤って分類されることがあります
- マルチモーダルなプロンプト(画像、ファイル)は、テキストの内容だけが分析されます
- 分類器は、トークン数を超えて会話履歴の深さを考慮しません