Claude API のレスポンスキャッシュが「古い答え」と「似て非なる誤答」を返すとき — 鮮度管理と誤ヒット抑制の実装メモ

import Redis from "ioredis";
const redis = new Redis(process.env.REDIS_URL as string);
 
// 保存時: 回答が依存している文書IDをタグとして登録する
async function setWithTags(
  key: string,
  value: string,
  ttlSeconds: number,
  docTags: string[]
): Promise<void> {
  const pipe = redis.pipeline();
  pipe.set(key, value, "EX", ttlSeconds);
  // 各タグ（文書ID）から、それに依存するキャッシュキーを逆引きできるようにする
  for (const tag of docTags) {
    pipe.sadd(`tag:${tag}`, key);
    pipe.expire(`tag:${tag}`, ttlSeconds + 60);
  }
  await pipe.exec();
}
 
// 文書が更新されたら、その文書に依存する全キャッシュを即時に消す
async function invalidateByDoc(docId: string): Promise<number> {
  const keys = await redis.smembers(`tag:${docId}`);
  if (keys.length === 0) return 0;
  const pipe = redis.pipeline();
  pipe.del(...keys);
  pipe.del(`tag:${docId}`);
  await pipe.exec();
  return keys.length;
}

// セマンティック近傍が見つかった後の「採否」を決める検証層。
// 類似度が高くても、否定の有無やエンティティがずれていれば不採用にする。
interface VerifyInput {
  query: string;
  candidateQuery: string;  // キャッシュに入っていた元の質問
  similarity: number;      // 0..1
}
 
const NEGATIONS = ["ない", "できない", "不可", "却下", "拒否", "未対応", "非対応"];
 
function extractEntities(text: string): Set<string> {
  // 実運用では固有表現抽出に置き換える。ここでは簡易に英数字トークンと
  // カタカナ語をエンティティ候補として拾う。
  const tokens = text.match(/[A-Za-z0-9_]+|[゠-ヿ]{2,}/g) ?? [];
  return new Set(tokens.map((t) => t.toLowerCase()));
}
 
export function acceptSemanticHit(input: VerifyInput): boolean {
  const { query, candidateQuery, similarity } = input;
  if (similarity < 0.86) return false; // 一次しきい値
 
  // 否定ガード: 片方だけが否定文なら結論が反転している可能性が高い
  const qNeg = NEGATIONS.some((n) => query.includes(n));
  const cNeg = NEGATIONS.some((n) => candidateQuery.includes(n));
  if (qNeg !== cNeg) return false;
 
  // エンティティガード: 主要エンティティの重なりが乏しければ別の問い
  const qe = extractEntities(query);
  const ce = extractEntities(candidateQuery);
  const overlap = [...qe].filter((e) => ce.has(e)).length;
  const denom = Math.max(1, Math.min(qe.size, ce.size));
  if (overlap / denom < 0.5) return false;
 
  return true;
}

// 本番トラフィックの数%だけ、キャッシュ採用と並行して実APIも叩き、
// 両者の差分を記録する。コストは sampleRate に比例して抑える。
async function shadowCompare(
  key: string,
  cached: string,
  freshFetch: () => Promise<string>,
  sampleRate = 0.02
): Promise<void> {
  if (Math.random() > sampleRate) return;
  const fresh = await freshFetch();
  const drifted = normalize(cached) !== normalize(fresh);
  await redis.hincrby("cache:audit", drifted ? "poisoned" : "clean", 1);
  if (drifted) {
    // 差分が出たキーは TTL を待たず失効させ、原因調査用にサンプルを残す
    await redis.del(key);
    await redis.lpush("cache:drift_samples", JSON.stringify({ key, cached, fresh }));
    await redis.ltrim("cache:drift_samples", 0, 199);
  }
}
 
function normalize(s: string): string {
  return s.replace(/\s+/g, " ").trim();
}