Gemini API の応答キャッシュを 3 段で重ねた話 — メモリ・Redis・Context Cache の役割分担

// l1-memory-cache.ts
import { LRUCache } from "lru-cache";
 
type CacheEntry = {
  body: string;
  storedAt: number;
};
 
const cache = new LRUCache<string, CacheEntry>({
  max: 1024,                  // エントリ数の上限
  maxSize: 4 * 1024 * 1024,   // 4 MB
  sizeCalculation: (e) => e.body.length,
  ttl: 30_000,                // 30 秒
  // Isolate コールドスタート直後に L1 が空になるのは想定内
});
 
// ジッタを入れて「TTL 同時切れ」によるサンダリングハード現象を避ける
const jittered = (base: number) =>
  base + Math.floor(Math.random() * (base * 0.2));
 
export function getL1(key: string): string | null {
  const hit = cache.get(key);
  if (!hit) return null;
  // 古すぎるエントリは念のため捨てる
  if (Date.now() - hit.storedAt > jittered(30_000)) {
    cache.delete(key);
    return null;
  }
  return hit.body;
}
 
export function setL1(key: string, body: string) {
  cache.set(key, { body, storedAt: Date.now() });
}

// l2-redis-cache.ts
import { Redis } from "@upstash/redis/cloudflare";
import { createHash } from "node:crypto";
 
const redis = Redis.fromEnv();
 
type CacheKeyInput = {
  prompt: string;
  model: string;
  temperature: number;
  topP: number;
  thinkingBudget: number;
  responseMimeType: string;
};
 
export function buildL2Key(input: CacheKeyInput): string {
  const canonical = JSON.stringify(input, Object.keys(input).sort());
  const hash = createHash("sha256").update(canonical).digest("hex");
  return `gem:v3:${input.model}:${hash.slice(0, 32)}`;
}
 
export async function getL2(key: string): Promise<string | null> {
  return (await redis.get<string>(key)) ?? null;
}
 
export async function setL2(key: string, body: string, ttlSec = 86_400) {
  // EX で TTL 24h. 課金記事や個人情報の入った応答は対象外
  await redis.set(key, body, { ex: ttlSec });
}

// l3-context-cache.ts
import { GoogleGenAI } from "@google/genai";
 
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });
 
type ContextCacheRecord = {
  cacheId: string;
  expiresAt: number;
};
 
// 個人開発スケールでは Upstash 上にメタデータを置いておくのが楽
async function getOrCreateContextCache(
  cacheKey: string,
  systemPrompt: string,
  reference: string,
): Promise<string> {
  const existing = await redis.get<ContextCacheRecord>(`l3:${cacheKey}`);
  if (existing && existing.expiresAt > Date.now()) {
    return existing.cacheId;
  }
 
  // Context Cache は最低 32,768 トークン必要。
  // 小さいシステムプロンプトしかないなら L3 は使わず L2 で済ませる
  const cache = await ai.caches.create({
    model: "gemini-2.5-flash",
    config: {
      systemInstruction: systemPrompt,
      contents: [{ role: "user", parts: [{ text: reference }] }],
      ttl: "3600s",
    },
  });
 
  const record: ContextCacheRecord = {
    cacheId: cache.name!,
    expiresAt: Date.now() + 3_600_000,
  };
  await redis.set(`l3:${cacheKey}`, record, { ex: 3_600 });
  return record.cacheId;
}
 
export async function generateWithL3(
  cacheKey: string,
  systemPrompt: string,
  reference: string,
  userPrompt: string,
): Promise<string> {
  const cacheId = await getOrCreateContextCache(cacheKey, systemPrompt, reference);
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userPrompt,
    config: { cachedContent: cacheId },
  });
  return result.text ?? "";
}

// invalidate-all.ts
type InvalidationResult = {
  l1: "ok" | "skip" | "error";
  l2: "ok" | "skip" | "error";
  l3: "ok" | "skip" | "error";
};
 
export async function invalidateAll(cacheKey: string): Promise<InvalidationResult> {
  const result: InvalidationResult = { l1: "skip", l2: "skip", l3: "skip" };
 
  // L1 は Isolate ローカルなので broadcast キーを Durable Object 経由で配信
  try {
    await broadcastInvalidate(cacheKey);
    result.l1 = "ok";
  } catch {
    result.l1 = "error";
  }
 
  // L2 は単純削除
  try {
    await redis.del(`gem:v3:*:${cacheKey}`);
    result.l2 = "ok";
  } catch {
    result.l2 = "error";
  }
 
  // L3 は明示的に Gemini 側のキャッシュエンティティを削除
  try {
    const meta = await redis.get<ContextCacheRecord>(`l3:${cacheKey}`);
    if (meta) {
      await ai.caches.delete({ name: meta.cacheId });
      await redis.del(`l3:${cacheKey}`);
    }
    result.l3 = "ok";
  } catch {
    result.l3 = "error";
  }
 
  // どこかが error なら DLQ へ。後続のバッチで再試行
  if (Object.values(result).includes("error")) {
    await redis.lpush("invalidation-dlq", JSON.stringify({ cacheKey, result, at: Date.now() }));
  }
 
  return result;
}