この記事は、Worksi の AI エージェントが英語の原文をもとに日本語で書き直し、別の AI エージェントが内容を事実確認したものです。原文(英語)へのリンクは末尾にあります。
Adapted into Japanese by Worksi's AI agents from the English original (linked at the end), and fact-checked by a separate AI agent.
プロンプトキャッシュを有効にすると、Claudeのユーザー別トークンクォータには正反対の2通りの誤り方があります。キャッシュのバケットを落として過少に数えることもあれば、内訳をすでに含んでいる合計の上にその内訳を足し、キャッシュを二重に数えることもあります。どちらももっともらしい数字になり、ユーザーごとに1行のダッシュボードではどちらも見えません。両方を捕まえるのは、答えがわかっている合成のusageレコードを1つ用意し、台帳(ledger)に書き込むすべての経路に通し、それをテストとして実行することです。
クォータの単位はプロダクト上の判断でもあります。Anthropicのレート制限のルールと価格は別々の問いに答えるもので、どちらかをユーザー別クォータに流用すると、別の意味を持つ数字になります。
ID、プラン、どこでリクエストを拒否するかについては、記事「per-user AI token quotas」で扱っています。本記事では計算とテストだけを扱います。
Anthropicは1つのリクエストを3通りに報告します
Anthropicのレート制限のページによると、input_tokensには最後のキャッシュブレークポイント以降のトークンだけが入ります。入力の合計は次のとおりです。
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
同ページ自身の例では、200kトークンのキャッシュ済みドキュメントと50トークンの質問で、入力トークン200,050に対してinput_tokens: 50と報告されます。
同じページでも、レート制限では数え方が異なります。1分あたりの入力トークン(ITPM)はinput_tokensとcache_creation_input_tokensを数えます。キャッシュ読み取りは数えず、ランプ制限(ramp limits)も同じルールに従います。プロンプトキャッシュのページは、バケットにさらに別の価格を付けています。5分のキャッシュ書き込みはベース入力価格の1.25倍、1時間の書き込みは2倍、キャッシュ読み取りは0.1倍で、一部のモデルにはより低い読み取り倍率が記載されています。
つまり1つのリクエストには3つの読み方があります。
- 入力全体+出力: このユーザーのためにモデルが処理した量。
- プロバイダーのレート制限の消費量: AnthropicのITPMとOTPMの制限が見た量。対象は組織全体です。
- 支出: 各バケット×その価格。価格はモデル、キャッシュ期間、プラットフォームによって変わります。
ユーザー別クォータはどれを使ってもかまいませんが、どれか1つを明示する必要があります。本記事では入力全体+出力を使います。長い会話を送るユーザーは、プレフィックスがキャッシュから来たかどうかに関係なく、短い会話を送るユーザーより多く割り当てを使います。
この選択には帰結があります。キャッシュされたプレフィックスは、それを読むリクエストのたびに改めて数えられます。キャッシュから読まれる10,000トークンのシステムプロンプトは、毎回同じテキストであっても、呼び出しのたびにユーザーのカウントに10,000を加えます。入力全体による計上が測るのは処理されたトークンであり、一意のテキストではありません。共有プレフィックスをユーザーに課金したくない場合は、明示的なポリシーとして除外するか、ユーザー間で按分してください。Anthropicのusageフィールドはリクエスト単位であり、そのドキュメントは按分を求めていません。
過去の2つのバグ報告は、逆方向に誤っています
CrewAI issue 6788(2026年8月3日起票、現在はクローズ)は、CrewAIのネイティブAnthropicプロバイダーがtotal_tokensをinput_tokens + output_tokensとして計算し、両方のキャッシュバケットを除外していると報告しました。起票者は、キャッシュなし入力100、キャッシュ作成20、キャッシュ読み取り30、出力50トークンをモックし、合計150をアサートしているユニットテストを指摘しました。そのリクエストが動かしたのは200です。起票者の読みでは、そのテストは過少計上を仕様として記録していました。
LangChain.js issue 10249(2026年3月3日起票)は、ストリーミングで逆のことを報告しました。起票者によると、Anthropicのmessage_startイベントとmessage_deltaイベントはどちらもキャッシュのカウントを持ち、message_deltaの値は累積値で、@langchain/anthropicは2つのチャンクを足し合わせてマージしていました。最終的なキャッシュ読み取りとキャッシュ作成の内訳は、APIの値の2倍になりました。このissueは、2026年3月9日にリンクされたプルリクエストによってcompletedとしてクローズされました。
どちらも過去の、起票者が報告した故障モードであり、本記事はどちらのライブラリの現行バージョンについても何も主張しません。CrewAIのテストの数値は良いフィクスチャになります。
フィクスチャには、試行ごとに正解が1つあります
以下はすべて合成データです。バックエンドが認証済みセッションから解決した仮名ユーザーu_7f3aに対する1回のプロバイダー試行が、次のusageを返すとします。
| フィールド | 値 |
|---|---|
input_tokens |
100 |
cache_creation_input_tokens |
20 |
cache_read_input_tokens |
30 |
output_tokens |
50 |
入力全体+出力のクォータでは、この試行は200トークンを加算します。入力を全体の150に正規化し、キャッシュのフィールドをその150の内訳として公開するフレームワークでも、加算は200です。150 + 20 + 30 + 50と足すと250になり、内訳が二重に数えられます。生の100 + 50と足すと150になり、キャッシュが落ちます。
両方を防ぐルールは次のとおりです。プロバイダーのフィールドをクォータの単位にマッピングするのは、ビューごとに1つのアダプターで1回だけにし、同じ試行について生のビューと正規化されたビューを比較します。2つのビューを、独立したusageであるかのように足し合わせてはいけません。
最小限の台帳の行と2つのアダプターを、SDKを使わない素のPythonで示します。正規化側のフィールド名は仮のものなので、お使いのフレームワークのものに置き換えてください。
from dataclasses import dataclass
from typing import Optional
RAW_FIELDS = ("input_tokens", "cache_creation_input_tokens",
"cache_read_input_tokens", "output_tokens")
@dataclass(frozen=True)
class LedgerRow:
attempt_id: str # one row per provider attempt; a retry is a new attempt
end_user: str # resolved by your backend from the session, never from the request body
status: str # "observed", "estimated" or "unknown"
provenance: str # which view and event the numbers came from
uncached_input: Optional[int] = None
cache_write: Optional[int] = None
cache_read: Optional[int] = None
output: Optional[int] = None
def buckets(self):
return (self.uncached_input, self.cache_write, self.cache_read, self.output)
def quota_tokens(self) -> Optional[int]:
"""Full input plus output. None means unknown, never zero."""
if self.status != "observed" or None in self.buckets():
return None
return sum(self.buckets())
def from_raw(attempt_id, end_user, usage, provenance):
"""usage: the Messages API usage object as a dict, or None."""
if usage is None or any(usage.get(f) is None for f in RAW_FIELDS):
return LedgerRow(attempt_id, end_user, "unknown", provenance)
return LedgerRow(attempt_id, end_user, "observed", provenance,
usage["input_tokens"],
usage["cache_creation_input_tokens"],
usage["cache_read_input_tokens"],
usage["output_tokens"])
def from_normalized(attempt_id, end_user, n, provenance):
"""n["input"] already includes both cache buckets; the details break it down."""
details = n.get("input_details") or {}
values = (n.get("input"), details.get("cache_write"),
details.get("cache_read"), n.get("output"))
if None in values:
return LedgerRow(attempt_id, end_user, "unknown", provenance)
total_in, cw, cr, out = values
if cw + cr > total_in:
raise ValueError(f"{attempt_id}: cache breakdown {cw + cr} exceeds input {total_in}")
return LedgerRow(attempt_id, end_user, "observed", provenance,
total_in - cw - cr, cw, cr, out)
アダプターは推測を拒否します。フィールドが欠けていれば行はunknownになり、クォータへの加算はNoneです。getattr(usage, "cache_read_input_tokens", 0) or 0のようなイディオムは、「報告されていない」と「ゼロ」を同じ数字にしてしまいます。台帳においては、それは記事「missing OpenAI streaming usage」で述べた故障、つまり不明をゼロとして記録することです。cache_controlを送らなかったリクエストでクライアントがキャッシュのフィールドを省略し、それを0と読みたい場合は、デフォルト値としてではなく、理由を添えた明示的なルールとして書いてください。推定値、たとえばusageが返ってこなかったときに自分で数えたリクエストの入力などには、ステータスestimatedと独自のprovenanceを持たせ、推定値で制限を執行するかどうかをプランごとに決められるようにします。
テストは合計だけでなくバケットを確認します
import pytest
USER = "u_7f3a" # pseudonymous id from your session, not from the client
RAW = {"input_tokens": 100, "cache_creation_input_tokens": 20,
"cache_read_input_tokens": 30, "output_tokens": 50}
NORMALIZED = {"input": 150, "output": 50,
"input_details": {"cache_write": 20, "cache_read": 30}}
def raw(i, w, r, o):
return {"input_tokens": i, "cache_creation_input_tokens": w,
"cache_read_input_tokens": r, "output_tokens": o}
def test_views_agree_bucket_by_bucket():
a = from_raw("att-1", USER, RAW, "messages response")
b = from_normalized("att-1", USER, NORMALIZED, "framework usage")
assert a.buckets() == b.buckets() == (100, 20, 30, 50)
assert a.quota_tokens() == b.quota_tokens() == 200
@pytest.mark.parametrize("usage", [
raw(150, 0, 0, 50), # no-cache control
raw(100, 50, 0, 50), # cache write
raw(100, 0, 50, 50), # cache read
])
def test_controls_all_total_200(usage):
assert from_raw("att-c", USER, usage, "fixture").quota_tokens() == 200
def test_missing_usage_is_unknown_not_zero():
row = from_raw("att-2", USER, None, "stream cancelled before usage")
assert row.status == "unknown"
assert row.quota_tokens() is None
def test_partial_usage_is_unknown_not_zero():
partial = {"input_tokens": 100, "output_tokens": 50} # cache fields absent
assert from_raw("att-3", USER, partial, "partial usage").quota_tokens() is None
def test_doubled_breakdown_is_caught():
# LangChain.js #10249 shape: details doubled, normalized input unchanged
doubled = {"input": 150, "output": 50,
"input_details": {"cache_write": 40, "cache_read": 60}}
a = from_raw("att-1", USER, RAW, "messages response")
b = from_normalized("att-1", USER, doubled, "merged stream chunks")
assert b.quota_tokens() == 200 # the total alone looks fine
assert a.buckets() != b.buckets() # the buckets do not
def test_breakdown_larger_than_input_is_rejected():
cache_heavy = {"input": 150, "output": 50,
"input_details": {"cache_write": 0, "cache_read": 280}}
with pytest.raises(ValueError):
from_normalized("att-4", USER, cache_heavy, "merged stream chunks")
3つの対照ケースは、意図的にすべて合計200になっています。台帳がこれらに対して異なる合計を出すなら、明示したクォータ単位を実装できていません。落ちているバケットがないか、ITPMや価格の重み付けが誤って適用されていないかを確認してください。
test_doubled_breakdown_is_caughtは、合計だけのチェックでは見逃すテストです。内訳だけが2倍になった場合、正規化された入力は150のままで、クォータも200のままです。その内訳から計算した支出は誤りになります。from_normalizedの不変条件が2倍化を捕まえるのは、2倍になったキャッシュ分が正規化された入力を超える場合だけです。バケットの比較なら、同じ試行について両方のビューがあるときは毎回捕まえます。フィクスチャは、ストリーミングと非ストリーミングの経路で別々に通してください。LangChain.jsの報告はストリーミングでのみ起きるものでした。
不一致の読み方
| 生の内訳(入力 / 書き込み / 読み取り / 出力) | 正規化された合計 | 台帳の合計 | 解釈 | 次のテスト |
|---|---|---|---|---|
| 100 / 20 / 30 / 50 | 200 | 200 | ビューが一致 | 3つの対照ケースと欠落ケースを実行する |
| 100 / 20 / 30 / 50 | 150 | 150 | キャッシュのバケットが落ちている。過少計上で、CrewAI 6788の形 | アダプターがどの生フィールドを入力にマッピングしているか確認する |
| 100 / 20 / 30 / 50 | 200 | 250 | すでに内訳を含んでいる入力に内訳を加算している | 内訳を合計に足しているコードを探す |
| 100 / 20 / 30 / 50 | 200、内訳 40 / 60 | 200 | 合計は正しいが内訳が2倍。支出が誤り。LangChain.js 10249の形 | ストリーミングと非ストリーミングでバケットを比較する |
| なし | なし | 0 | 欠けたusageがゼロとして保存されている |
unknownステータスとprovenanceをアサートする |
| 100 / 20 / 30 / 50 | 200 | 400 | 同じ試行が2回記帳されている | 試行IDのユニークキーを確認する |
試行ごとに1行を、1回だけ記帳します
- 試行IDはプロバイダーを呼ぶ前に生成します。リトライやフォールバックモデルは独自のIDを持つ新しい試行なので、ユーザーから見て1つのリクエストが複数の行を持つことがあります。失敗した試行がユーザーのクォータを使うかどうかは、文書化しておくポリシーです。
- 行は試行が終わったときに記帳します。つまり、完全なレスポンスか頼りにする最終usageが届いたとき、あるいはusageなしで試行が終わったとき(
unknownとして)です。最終usageをどのストリーミングイベントが運ぶかはプロバイダーとクライアントによって異なるので、テストしてください。クライアントが累積カウンターを報告する場合、LangChain.js issue 10249がmessage_deltaについて説明しているように、後の値は前の値に足すのではなく、前の値を置き換えるべきです。 - 試行IDにユニークキーを付けて書き込みます。キューやWebhookがat-least-once(少なくとも1回)で配信する場合、2回目の配信はキーにぶつかり、何も加算しません。2つ目のコピーが異なる数値を持っている場合は、どちらかを選ぶのではなく、両方をレビュー用に残してください。どのトランスポートについても、exactly-onceの配信を前提にしないでください。
-
unknownの行が後で突合(reconciliation)によって数値を得た場合は、2行目を作らず、新しいprovenanceとともにその行をその場で更新します。
呼び出し前のチェックはハードリミットではありません
呼び出し前の残高チェックと呼び出し後の台帳への記帳で得られるのは、観測ベースの計上です。台帳は事後には正しくなりますが、その間に制限を超えることがあります。例として、1人のユーザーからの10件の同時リクエストが、それぞれ残り1,000トークンと見えるチェックを通過し、その後それぞれ2,000トークンを記帳することがありえます。
予約(reservation)はこのギャップを狭めます。呼び出し前に、その試行が使いうる量を予約して残高と照らし合わせ、収まらなければ拒否します。呼び出し後に、予約を観測された行で置き換えます。よく使われる予約量である「推定した入力全体+max_tokens」も、やはり推定です。Anthropicのトークンカウントのページは、自社の呼び出し前のカウントは推定であり、実際の入力トークンはわずかに異なりうると述べています。このエンドポイントは、サーバーツールなど、Messages APIが受け付ける一部の入力も拒否します。推定にもとづく予約は超過を減らしますが、なくしはしません。
保証されたハードキャップには2つのことが必要です。1つは、受け入れのステップがチェックと予約をアトミックに行うこと。もう1つは、予約量が、クォータが数えるすべて(入力と出力)について根拠を示せる上限であることです。そうではなく推定入力+max_tokensを予約するなら、推定が外した分だけ制限を超えうると明記し、観測された行が予約より大きかった場合にどうするか(超過分をマイナスになっても課金するか、帳消しにするか)を文書化してください。
予約には別のコストもあります。収まったはずのリクエストを拒否することがあります。unknownの試行は予約を残すので、保持するか、解放するか、推定で精算するかのルールが必要です。そして、チェックと予約のステップは、それを置くストアがアトミックである程度にしかアトミックになりません。前提にせず、検証してください。
プランごとに1つを選び、どれを選んだかを明示してください。私たちの見解では、「観測ベースで、処理中の分だけ超過しうる」は無料枠として誠実なポリシーです。推定による予約を使う場合、有料プランに対する誠実な約束は「決して超えない」ではなく「推定誤差の分だけ超過しうる」です。
どの合成リクエストが数えられるか
-
A1: セッションのユーザーは
u_7f3a、usageは完全。加算は200。 - A2: A1のレコードがキューによって2回目に配信されたもの。試行IDのキーにぶつかり、何も加算されない。
-
A3:
u_7f3aの別の試行で、usageが届く前にストリームがキャンセルされたもの。provenanceとともにunknownとして記録する。0としては数えない。その後どうするかは、不明な試行についてのプランのルールで決まる。 -
A4: リクエストボディが
user: "u_other"とplan: "pro"を主張しているもの。どちらも無視する。IDは認証済みセッションから、プランは課金記録から取るので、この試行はu_7f3aに、そのユーザーの実際のプランで帰属される。
支出には合計ではなくバケットが必要です
トークンの合計からは支出を再現できません。2026年11月14日に読んだプロンプトキャッシュのページにあるClaude Haiku 4.5の定価(100万トークンあたり、入力$1、出力$5、5分の書き込み$1.25、1時間の書き込み$2、キャッシュ読み取り$0.10)を使うと、次のようになります。
| ケース | 入力 / 書き込み / 読み取り / 出力 | クォータのトークン | 支出 |
|---|---|---|---|
| キャッシュなし | 150 / 0 / 0 / 50 | 200 | $0.000400 |
| キャッシュ書き込み(5分) | 100 / 50 / 0 / 50 | 200 | $0.0004125 |
| キャッシュ読み取り | 100 / 0 / 50 / 50 | 200 | $0.000355 |
| フィクスチャ(5分の書き込み) | 100 / 20 / 30 / 50 | 200 | $0.000378 |
| フィクスチャ(1時間の書き込み) | 100 / 20 / 30 / 50 | 200 | $0.000393 |
同じ200トークンが5つの異なる金額になります。金額の台帳は、試行ごとに4つのバケット、モデル、プラットフォーム、リクエストしたキャッシュ期間、使用した価格のバージョンを保持します。価格は変わり、読み取り倍率はモデルによって異なり、さらにページによれば、倍率はバッチ、ロングコンテキスト、データレジデンシーの修飾子と重ねて適用されます。そのため、保存したトークン合計に1つのレートを掛けたものは、よくても推定にすぎません。
原文(英語): A Claude token quota can undercount cache reads or count them twice
