在 Linux 上用 google-genai 1.8 给一份 30 页产品手册建 cachedContents，模型写 gemini-2.5-flash，请求回 400 INVALID_ARGUMENT，原文是 Cached content is too small. total_token_count=612, min_total_token_count=1024。手册转成纯 txt 再传结果一样，改回不建缓存直接调用就能通。
一开始怀疑是「只把 system 指令放进了缓存，正文没进 contents」，查了一圈，方向不对。
这类报错背后常见的原因有几处，逐个排除就行。显式缓存对内容有最小 token 门槛，短文档会被直接拒。另一种情况是按字符估的 token 和接口算的差一倍，实际没到门槛。
少数情况下是模型档位不同门槛不同，flash 与 pro 的阈值并不一样。
数清内容真实 token，再判断差多少
python -c "from google import genai;c=genai.Client();print(c.models.count_tokens(model='gemini-2.5-flash',contents=open('manual.txt').read()))"随后把多次请求共用的长前置内容合成一个缓存对象
python build_cache.py --file manual.txt --ttl 3600 --model gemini-2.5-flash缓存建好后只引用 name，不要再把原文贴进请求
python -c "print(open('cache_name.txt').read().strip())"内容确实太短就改用隐式缓存，省掉建缓存这一步
python call_gemini.py --no-explicit-cache --model gemini-2.5-flash恢复的判定其实很直接。cachedContents.create 返回带 name 的对象，后续 generateContent 的用量里 cached_content_token_count 大于零。
缓存按时长计费而不是按命中次数，TTL 给太长在低频任务上反而更贵。监控比日志更早给出信号，事后回看经常能提前半小时发现异常。