官方的串流文件裡有個查天氣的例子：使用者問舊金山的天氣，Claude 先回了一句話（index 0 的文字區塊），接著開了 index 1 的工具區塊，呼叫 get_weather。下面是事件：

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

仔細看這六段字串，第一段是空的，第二段是 {"location":，只有左大括號和一個 key； "San 開了引號沒有關， Francisc 則斷在單字的中間。每段都不能單獨拿去給 JSON 解析器，那肯定會錯，因為它們只是同一串文字切開後的段落。要等到 CA"} 送來，頭尾符號都有了，接著 content_block_stop 表示這個區塊結束；這時把六段照順序接起來，才會是 {"location": "San Francisco, CA"}。

所以程式在收參數的時候，要做的事情其實很簡單。fine-grained tool streaming 文件把它寫成三步：收到 tool_use 的 content_block_start 時準備一個空字串，每個 input_json_delta 來就把 partial_json 接到後面，等到 content_block_stop 再解析，解析要包在 try 裡。如果用的是 Python、TypeScript 或 Go 的 SDK，裡面已經有 helper 會把片段接好；但如果是直接處理事件，或是想自己決定怎麼處理的時候，才需要照這三步驟。

eager_input_streaming

查天氣的參數只有一個城市名，很短也很快就送完了。如果參數很長，像是整份文件或整段程式碼，預設的做法就會讓人等比較久：API 會先把每個參數值緩衝起來、驗證過之後才送出。

在自己定義的工具上把 eager_input_streaming 設成 true，請求本身也記得要設成串流，這個參數就不經過伺服器端的緩衝跟 JSON 驗證，Claude 開始的同時，片段也就跟著跑出來。fine-grained tool streaming 文件的範例就打開了這個設定，片段一到就印出來，讓人看到參數寫到哪裡；不過要知道此時印出來的是還沒接完的字串，還不能當參數用。接的方式跟前面一樣，但是伺服器沒有先驗證，所以到了 content_block_stop，接完的字串不保證是合法的 JSON。

因此，我們在使用時，要不要替某個工具打開 eager_input_streaming，可以確認情境，有時候很長再空等待那也許是個可以考慮的方向。 總之這篇提供個 Claude 的不同小用法，有任何討論和想法歡迎提供。

The prompt caching docs list one prompt as a common mistake. Its large system context is split over five blocks that are the same on every request. A sixth block holds a timestamp and the user’s message, so it is different every time. cache_control sits on block 6, the last block in the prompt.

On the first request nothing is cached yet. The API processes the whole prompt and writes one entry, at block 6. The docs describe that entry as “a hash of the prefix ending at that block,” and the hash is cumulative, so it covers blocks 1 through 6 with the timestamp inside it. The five static blocks are part of that hash, but none of them gets an entry of its own, because the API writes nothing at positions before the breakpoint.

The second request arrives with the same five blocks and a new timestamp. The API computes the hash at block 6, and since the timestamp changed, the hash changed, and there is no entry to match. It then walks backward a block at a time, from block 5 down to block 1, checking the prefix hash at each position against the cache. Those five blocks are word for word what the first request sent. But the API is looking for an entry that some earlier request wrote at that position, and no request has ever written one at block 5 or anywhere before it. The walk comes back empty. The second request writes its own entry at block 6, with its own timestamp in the hash, and the third request will miss that one in the same way, because its timestamp will be different again.

So with the breakpoint on block 6, every request is a cache write and none is a read. That shows up on the bill, because a write is not priced like ordinary input. On the pricing page, a write to the five-minute cache costs 1.25 times the base input price, and a read costs a tenth of it on most models (a few, Opus 5.5 among them, read for less). The same page says the five-minute cache “pays off after one cache read.” Since that read never comes, every request pays the write price on everything up to block 6, which costs more than sending the same prompt with no cache_control at all.

Switching to automatic caching doesn’t get around this, since automatic caching puts the breakpoint on the last cacheable block, and in this prompt that is block 6 again. The fix is an explicit breakpoint one block up, on block 5, the last block that stays the same from one request to the next:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {"type": "text", "text": context_1},
        # context_2 through context_4, unchanged
        {
            "type": "text",
            "text": context_5,
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {"role": "user", "content": f"[{timestamp}] {user_message}"},
    ],
)

Now the first request writes its entry at block 5, and that hash ends before the timestamp, which means a new timestamp no longer changes it. When the second request computes the hash at block 5, it gets the same value and finds the entry the first request left right there, so it never needs the walk back described above. It reads blocks 1 through 5 from the cache. Only the timestamp and the message go through as ordinary input. The docs put the rule this way: place cache_control “on the last block whose prefix is identical across the requests you want to share a cache.” If anything in blocks 1 through 5 changes between two requests, even slightly, the second request writes instead of reading.

Caching has no effect on Claude’s reply, so the place to see whether a request hit the cache is the response’s usage object. It splits the input tokens three ways: cache_creation_input_tokens for tokens written to the cache on this request, cache_read_input_tokens for tokens read from it, and input_tokens for the tokens after the last breakpoint. That last one is worth keeping an eye on, because it is not the size of the prompt.

With the breakpoint on block 6, every response looks alike: nearly the whole prompt appears under cache_creation_input_tokens, and cache_read_input_tokens stays at 0. With the breakpoint on block 5, the first response looks much the same, since that request still has to write the entry, but the timestamp and message now show up under input_tokens.

The second response is the one that shows whether the move worked. When you test it, remember to send that request within five minutes of the first one, since by default an entry lasts five minutes counted from the start of the request that used it. It also can’t go out alongside the first, because the entry only becomes available once the first response begins. The static context should then appear under cache_read_input_tokens, cache_creation_input_tokens should be 0, and input_tokens should be just the last block. If both cache fields read 0, nothing was cached at all. That usually means the prefix is shorter than the minimum the model will cache (512 tokens on Opus 5.5, more on some other models), and the API returns no error when that happens.

This is just one small idea from prompt caching: where to put the breakpoint, and how to check that it worked. If you’ve seen the cache behave differently from what’s described here, I’d like to hear about it.

標上 cache_control 的區塊，官方文件稱為斷點（breakpoint）。快取只會在斷點寫入一筆資料，內容是整段前綴的雜湊。雜湊是累積的，所以斷點本身或它之前任何一個區塊有改動，下一次出來的值就會是另一個雜湊。不過讀取的時候，系統會先拿斷點位置的雜湊去找，沒找到就往回退一步，換位置的雜湊再找一次，這樣一步一步找。

規則放到實際的請求裡，有些要注意的地方。文件裡有個例子，請求前面五個區塊是固定的系統內容，每次送出去都完全相同；第六個區塊放的是這次的時間戳記，以及使用者剛打的訊息。如果把 cache_control 標在最後面，也就是第六個區塊上，第一次請求確實會寫進快取，只是寫進去的雜湊內容，是從第一個區塊一路到第六個區塊，也就是說，時間戳記也算在裡面。

但是到了第二次請求，時間戳記換了，第六個區塊的雜湊也當然會不同，因為時間不一樣了，系統找不到對應的紀錄，於是像剛剛說的開始往回找，第五、第四，一路到第一個區塊。但因為這幾個位置上一次都沒有寫過任何東西，因為寫入只發生在斷點，所以一直找到最前面，也不會讀到雜湊。前面五個區塊明明完全沒變，但是往回找只是查之前的請求已經寫過的紀錄，不會因為內容沒變就另外補存一筆。結果導致每一次請求都會再寫進一筆新的，到了下一次請求，又因為時間戳記不同而對不上。

如果把斷點往前移到第五個區塊，也就是最後一個每次都相同的區塊，第一次請求寫入的就會在這裡，而不是包含會改變的時間。到了第二次請求時，我們可以在第五個區塊上對應到雜湊，前面五個區塊就從快取讀取出來，會變的第六個區塊照一般的輸入處理，也就不會影響快取。

如果用的是自動快取，也就是把 cache_control 放在請求的最外層、讓系統自己決定斷點，在這個例子裡也會碰到相同的問題。自動快取會把斷點放在最後一個可以快取的區塊，而這裡的最後一個區塊剛好就是每次都會變的那一個，所以建議還是改用明確的斷點。

那放錯位置的影響是什麼呢？請求照樣會成功，回答也跟沒有開快取時一樣，但差別會出現在你的花費上，快取能有效地降低花費。5 分鐘快取的寫入價格是一般輸入的 1.25 倍，讀取則只要一般輸入的一點點。斷點放錯地方，每一次反而要多付一點快取的價格，讀取卻一次也沒發生過，實際比較下來比完全不開快取還多付一些。那關於寫入和讀取的價格差別怎麼影響整體的設計，可以參考之前寫的相關文章：Token 成本的真相：分級，但別分太細。

因為快取不會有錯誤訊息，要確認有沒有讀到，就要看回應裡的 usage。cache_creation_input_tokens 是這次寫進快取的 token，cache_read_input_tokens 是從快取讀出來的 token。第一次請求本來就只會有寫入，所以主要看第二次：同樣的開頭內容再送一次（兩次之間要在快取的有效時間內，預設是 5 分鐘），cache_read_input_tokens 應該會大於 0。如果第二次還是只有寫入、讀取是 0，就可以回頭看看斷點是不是標在每次都會變的區塊上，或是其他可能錯誤。另外如果沒有被快取，這種情況同樣不會回傳錯誤，原因可能是內容沒有達到該模型的最低長度。

最後說明，這篇是照 Anthropic 目前的 prompt caching 文件和價格頁整理的。各個模型的最低長度、快取設計以及讀取價格也不太一樣，而且會隨新模型更新，實際的數字以文件上的表格為準，這裡還是提供一個小概念和想法讓大家參考。