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

Yabanin — ワンコマンドデモ

make demo は、クリーンなクローンから、手動の手順なしで約 25 秒のうちに、0 ではない支出、0 ではないキャッシュヒット率、分類器の分布、削減額を示すブラウザタブまで進みます。これは営業向けの資産です。他のドキュメントを読まずに実行できなければなりません。

ローカルで何かを実行する時間がない場合は、運用者が管理する公開スタンド https://yabanin.ai が、評価用に同じスタックを提供しています。公開スタンドを参照してください。このページの残りは、ワンコマンドのローカルデモについてです。

デモは最小のスタック(postgres、redis、マイグレーション、モックプロバイダ、モックエンベッダ、ゲートウェイ、ロガー、admin、ダッシュボード)を起動し、重い部分(Prometheus、Grafana、Alertmanager、ML 分類器、ローカル LLM)は起動しません。ゲートウェイの経路はスタック内のモックプロバイダであり、エンベッダはモックエンベッダです。そのため、モデルのダウンロードも、実際のプロバイダ資格情報も不要です。

前提条件​

  • Docker と Docker Compose v2(docker compose version)
  • make(macOS では Xcode Command Line Tools に同梱)
  • curl と shasum(どちらも macOS に同梱。リプレイとシードの手順で必要です)
  • コンテナ一式のために、約 2 GB の空き Docker メモリ
  • リポジトリのクリーンなクローン(deploy/secrets/* ファイルが存在している必要があります。これらはローカル開発用のシークレットであり、git では追跡されません)

ホストに psql、Go ツールチェーン、Node は不要です。シードは postgres コンテナ自身の psql を通して実行され、サービスイメージは Docker がビルドします。

実行​

make demo

成功すると、コマンドは URL、デモの API キー、admin のログイン情報を出力します。

Demo is live.
Dashboard : http://localhost:3000
Admin : http://localhost:9091 (log in at /auth/login)
Gateway : http://localhost:8082 (POST /v1/chat/completions)
API key : demo-key-1234567890
Admin in : demo@local / demo-admin-123

http://localhost:3000 を開き、demo@local / demo-admin-123 で /auth/login にログインすると、ダッシュボードにデータが入っています。

シャドウモードあり(make demo SHADOW=1)​

デモのトラフィック全体を、任意で 2 つ目のモデルへミラーし、プライマリ対シャドウの比較に実データを持たせることができます。シャドウはデフォルトでオフであり、クライアントの応答は変えません(shadow-mode.mdを参照)。

make demo SHADOW=1

変更点:

ゲートウェイは YABANIN_SHADOW_ENABLED=true で起動し、ストリーミングではないデモリクエストをすべて、同じモックプロバイダ上の gpt-4o へミラーします(デモのサンプルレートは 1.0、1 日の予算上限は 100 USD。モックなので、実際の支出はありません)。

リプレイのあと、スクリプトはシャドウの行数と、request_logs からのプライマリ対シャドウの、リクエストあたり平均コストの行を出力します(シャドウ行は ab_group='shadow' を持ち、プライマリ行と同じ request_id です)。

比較エンドポイントは、その後 insufficient_data ではなく判定を返します。

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:9091/api/analytics/shadow?days=1"

# runtime kill switch (gateway admin listener, bearer-protected).
# The gateway admin listener (container :9090) is published on host
# :9092 — host :9090 is taken by Prometheus in this stack.
curl -H "Authorization: Bearer demo-shadow-key" \
http://localhost:9092/admin/shadow/status
curl -X POST -H "Authorization: Bearer demo-shadow-key" \
-d '{"enabled": false}' http://localhost:9092/admin/shadow/toggle

シャドウダッシュボード(任意、フルスタック)​

最小のデモ一式には Prometheus と Grafana は含まれません。yabanin_shadow_* メトリクスをライブで見るには、可観測性サービスも起動します。

docker compose -f deploy/docker-compose.yml up -d prometheus grafana

次に http://localhost:3001(Grafana、admin / yabanin)を開き、Yabanin — Shadow Mode ダッシュボードを選びます。表示されるのは、シャドウの有効状態、支出レート(USD/s)、消費した予算(24 時間)、予算枯渇イベント(1 時間)、結果別のリクエスト、理由別のスキップ、モデル別のレイテンシ P95、モデル別の支出です。

ダッシュボードには 2 つの Prometheus アラートが付きます(deploy/prometheus/alert-rules.yml、グループ yabanin-shadow)。

  • ShadowHighErrorRate(警告)— シャドウのトラフィックが流れている間、15 分間でシャドウ呼び出しの 50% 超が失敗している。エラーが続く場合、ターゲットの設定が誤っているか、到達できません。
  • ShadowBudgetBurn(情報)— 1 日の予算上限が、新しいシャドウ呼び出しをブロックしています。YABANIN_SHADOW_DAILY_BUDGET_USD またはサンプルレートを調整します。

生成されるもの​

  • 300 件のチャットリクエストがゲートウェイ経由でリプレイされます。簡単、中程度、難しいプロンプトの混合、共有のシステムプレフィックス、意図的な繰り返しにより、セマンティックキャッシュが平坦な 0 ではなく本物のヒットを出します。
  • デモの組織 + チーム + API キー + admin ユーザーに加え、クレジットウォレットとチームの予算。これにより、ゲートウェイのクレジットガードと予算エンフォーサがリクエストを通過させます。
  • ロガーがデータベースへ書き込む支出、キャッシュ、分類器、削減のデータ。ダッシュボードはこれを読み取ります。

期待される画面の状態(ページごと)​

ログイン後、すべてのページに 0 ではないデータが表示されます。

  1. 概要 — 合計リクエスト(約 300)、合計支出(0 ではないドル)、キャッシュと経路を合わせた削減額。リクエスト数と支出の合計を指し示します。
  2. コスト — モデル別の支出内訳。gpt-4o と gpt-4o-mini は、それぞれ 0 ではないリクエスト数とコストを持ちます。モデルの行とドルの列を指し示します。
  3. キャッシュ — 0 ではないキャッシュヒット数(繰り返されたプロンプトがセマンティックキャッシュにヒットします)とヒット率。ヒット数と、回避されたコストの数値を指し示します。
  4. 分類器 — リプレイされたプロンプトの簡単 / 中程度 / 難しい分布。クラスの件数を指し示します。

これらのページの背後にある削減 API は GET /api/analytics/savings?days=7 です。total_requests、actual_cost_usd、cache_hits、top_models_by_cost を返し、リプレイ後はいずれも 0 ではありません。

リセット​

ボリュームも含めてすべてを停止するには(次の make demo がクリーンな状態から始まるようにします)、次を実行します。

make demo-down

リセットして、1 つの手順で再実行するには、次を実行します。

make demo-down && make demo

トラブルシューティング​

症状想定される原因対処
demo FAIL: <service> did not become ready ... within Nsサービスが起動しなかった、またはポートがすでに使用中です。docker compose -f deploy/docker-compose.yml ps と、失敗したサービスのログ(... logs <service>)を確認します。ポート(3000、8082、9091、5432、6379)が別のプロセスに使われている場合は、解放するか、先に make demo-down を実行します。
コンテナは起動するが、ゲートウェイが 502/unsupported protocol scheme を返すゲートウェイがモックプロバイダに到達できません。ゲートウェイに YABANIN_PROVIDER_ADDR: http://mock-openai:8081 があること(Compose ファイルで設定)と、mock-openai が正常であることを確認します。
demo FAIL: migrations did not create org_credits within 120s古いボリューム、または途中まで実行されたマイグレーションです。make demo-down(ボリュームを削除します)のあと、再度 make demo を実行します。
ダッシュボードが空白 / unauthorizedログインしていない、または admin セッションの期限が切れています。/auth/login で demo@local / demo-admin-123 を使ってログインします。デモは admin ユーザーを冪等に再シードするため、資格情報は安定しています。
Docker のメモリが不足し、コンテナが OOM になるコンテナ一式に対して Docker のメモリ上限が低すぎます。Docker Desktop のメモリ割り当てを 4 GB 以上に上げてから、make demo-down && make demo を実行します。
再実行で古いデータまたは重複データが表示される前回の実行のボリュームが残っています。クリーンな状態にするには、make demo の前に必ず make demo-down(ボリュームを削除します)を実行します。

デモ動画の収録​

次のものをこの順で、挙げられた数値を指しながら収録します。

  1. ターミナル — 実行中の make demo、続いて Demo is live ブロック(URL と API キーを見せます)。
  2. ダッシュボード → 概要 — 合計リクエスト数と合計支出。
  3. ダッシュボード → コスト — モデル別の行(gpt-4o、gpt-4o-mini)とそのコスト。
  4. ダッシュボード → キャッシュ — キャッシュヒット数と、回避されたコストの数値。
  5. ダッシュボード → 分類器 — 簡単 / 中程度 / 難しいの分布。
  6. ターミナル(任意) — リクエストログに対する yb audit。オフライン解析器が合算した削減額を示します(docs/audit.md を参照)。

バイナリのスクリーンショットをリポジトリにコミットしないでください。動画、または外部のアセットストアへ収録してください。