ran
日本語

TokenMeter

会話がコンテキストウィンドウをどれだけ使っているか。

使いどころ：コンテキスト上限のあるモデルに対してチャット UI を作っているとき。これを見せないクライアントは最初こそ動きますが、やがて壊れます。ターンごとに履歴全体を送り直すのでリクエストは大きくなる一方で、いずれプロバイダーが上限超過として拒むからです。このコンポーネントは、拒まれる前にその成長を見せます。

クイックスタート

基本的な使い方

<r-token-meter limit="65536" used="12800"></r-token-meter>
const meter = document.createElement('r-token-meter');
meter.limit = 65536;
meter.used = 41200; // 次のリクエストが運ぶコンテキスト
meter.spent = 128431; // 会話全体で課金されたトークン、任意
composer.append(meter);

バーは used / limit まで満ち、三つの段階を上がっていきます：ok、warn（上限の 80% から）、 over。level はホストに反映されるので、ページもバーと同じ段階に反応できます。

r-token-meter[level='warn'] ~ .composer-hint {
  display: block;
}

used と spent は別の数です

  • used：次のリクエスト が運ぶ量、つまり履歴であって会話全体ではありません。上限が適用され、バーが描くのはこの数です。
  • spent：これまでに会話全体で課金された量。増える一方で、ウィンドウの大きさに縛られません。

会話を切り詰めると used は下がりますが spent はそのままです。どちらか一方だけを見せると、ユーザーが持つ二つの問い（「次のメッセージは入るのか」「これまでいくらかかったのか」）の片方にしか答えられません。

上限がない場合

limit が未設定またはゼロならバーは消え、数だけが残ります。ウィンドウの大きさが分からないあいだに便利です。

ラベルの付け替え

<r-token-meter label="コンテキスト" limit="65536" used="41200"></r-token-meter>
<!-- label="" にすると数だけが残ります -->

API リファレンス

プロパティ

プロパティ 属性 型 既定値 説明
limit limit number 0 コンテキストウィンドウの大きさ（トークン数）。ゼロまたは未設定でバーを隠します。
used used number 0 次のリクエストが運ぶトークン数。
spent spent number 0 これまでに会話全体で課金されたトークン数。
label label string 'Context' 表示の接頭辞。'' にすると数だけが残ります。
level level 'ok' | 'warn' | 'over' 導出 ウィンドウの埋まり具合。要素が設定します：書き込んでも次の更新で上書きされます。
sheet sheet string '' shadow root に注入する CSS。

数は素早く読めるように整形されます。千未満は正確に（847 は正確に読めるほど短い）、それ以上は略記で（41.2k、128k）。128,431 の三桁目は、読み手の行動を何も変えません。

Part

Part 要素
meter 要素全体
track バーの背景
fill 満ちた部分
text ラベルと数

アクセシビリティ

この要素は常に数値を述べる title を持ちます。したがって色が警告の唯一の担い手になることはありません。バーが琥珀色になるのは二つ目の合図であって、唯一の合図ではありません。段階の見た目を変えるときも、この性質は保ってください。

スタイリング

<r-token-meter> は自前の CSS カスタムプロパティを 9 個、そしてテーマから読むセマンティックトークンを公開しています。継承が届く場所ならどこにでも設定できます（:root、外側のコンテナ、要素そのもの）。

r-token-meter {
  --ran-token-meter-fill-background: var(--ran-color-bg-subtle);
}

Part：fill · meter · text · track

一覧はスタイルトークンに、どのトークンを選ぶかはデザインシステムにあります。

ベストプラクティス

  • used はリクエストを組み立てるのと同じ場所から更新する、描画のパスからではなく。人が信じるのは次のリクエストが実際に送る数だからです。
  • 段階への対応はメーターの外で。 level="over" のときに役立つ UI は提案（要約する、新しいスレッドを始める）であり、それはアプリの仕事です。
  • テーマ切り替えで満ち具合をアニメーションさせない：デザインガイドライン を参照。