「今日の天気は?」と「本日の天気を教えて」。
人間から見たら、この2つはまったく同じ質問です。でも、多くのLLMアプリはこの2つを 別々の質問 として扱って、両方ともフルでAPIを叩いて、両方ともお金を払っています。
正直に言うと、これってめっちゃもったいない気がするんです。
意味は同じなのに、文字が1文字違うだけで、キャッシュが1ミリも効かない。同じような問い合わせが1日に何百件も来るFAQボットで、毎回フルでモデルを叩いていたら、API代もレイテンシ(応答の待ち時間)も、静かに膨らんでいきます。
今日は、その「意味が近い質問には、過去の答えを使い回す」を実装する セマンティックキャッシュ(Semantic Cache) の話をします。10分で動く最小コードから、本番で事故らないための運用の型まで、そのまま試せるレベルで書いていきます。
先に結論
- 同じ意味の質問には、過去のLLM応答を再利用する。これだけでコストとレイテンシがまとめて下がる。
- ただし「意味が近い」を判定するのは機械なので、ときどき間違える(誤ヒット)。ここを測らずにhit率だけ自慢すると、ユーザーに堂々と間違った答えを返す事故になる。
- だから hit率(キャッシュが効いた割合)と false positive率(誤ヒット率)は、必ずセットで測る。これが今日いちばん持って帰ってほしい鉄則です。
⚠️ 最初に:Prompt Caching とは別の話です
「キャッシュ」と聞くと、以前書いた Prompt Caching(プロンプトキャッシュ) を思い出す方もいると思います。でも、この2つはレイヤーが違います。ここを混ぜると事故るので、先に線引きしておきますね。
| Prompt Caching(プレフィックスキャッシュ) | セマンティックキャッシュ(今日の話) | |
|---|---|---|
| キャッシュする対象 | プロンプトの先頭が完全一致した部分の内部計算(KVキャッシュ) | 意味が近い質問への、LLMの最終応答そのもの |
| 効く範囲 | 同じプロバイダ内・自分のリクエスト内 | アプリ層で、ユーザーをまたいで再利用できる |
| 一致の判定 | バイト単位の完全一致 | 埋め込みベクトルの近さ(あいまい一致) |
| どこが実装するか | プロバイダ(自動 or breakpoint指定) | 自分のアプリ側で作り込む |
ざっくり言うと、Prompt Cachingは「長い共通の前置きを毎回計算し直さない」仕組み。セマンティックキャッシュは「意味が同じ質問なら、そもそもモデルを呼ばない」仕組みです。両方使えます。今日は後者だけを深掘りします。
役割分担を先に決めておく(ここが一番大事)
セマンティックキャッシュは「AIに任せていい部分」と「人間が決めないと危険な部分」がハッキリ分かれます。手を動かす前に、ここを固定しておきましょう。
| 誰がやる | 内容 |
|---|---|
| 人間が決める | しきい値(どれくらい似てたら同じ扱いにするか)/許容できる誤ヒット率/そもそもキャッシュしていい質問か(後述の禁止領域)/本番投入の最終承認 |
| AI・ツールに任せる | 埋め込みの計算/類似検索/hit率・誤ヒット率のレポート生成/しきい値候補の提案 |
「どこまで似てたらOKにするか」は、ビジネス上の許容リスクの話です。ここだけは機械に丸投げしちゃダメで、人間が数字で決めます。
セマンティックキャッシュって、そもそも何をしてるの?
図書館の司書さんをイメージしてください。
完全一致のキャッシュは、一字一句まったく同じ質問が来たときだけ、過去の回答メモを渡す司書です。融通が利かない。「今日の天気は?」と「本日の天気を教えて」を別物として扱います。
セマンティックキャッシュの司書は違います。新しい質問が来たら、過去の質問棚から「意味が近いもの」を探して、十分近ければその回答を渡します。近いのが無ければ、そのときだけモデル(本を書く人)に頼みに行く。
この「意味が近い」を機械で測るために、3つの道具を使います。初めての方向けに、ひとつずつ噛み砕きますね。
- 埋め込み(Embedding): 文章を「意味の座標(数百〜数千個の数字の並び=ベクトル)」に変換したもの。意味が近い文章は、座標も近くなります。
- コサイン類似度(Cosine Similarity): 2つのベクトルの「向きの近さ」を -1〜1 の数字で表したもの。1に近いほど意味が近い、という指標です。
- しきい値(Threshold): 「これ以上似てたら同じ質問とみなす」の境界線。たとえば 0.95 と決めたら、類似度が 0.95 以上のときだけキャッシュを返します。
やることはシンプルで、「新しい質問を埋め込み → 過去の質問の中でいちばん近いものを探す → しきい値を超えてたらその回答を返す。超えてなければモデルを呼んで、結果を棚にしまう」。これだけです。
コード例1:10分で動く、最小のセマンティックキャッシュ
まずは雰囲気をつかむために、外部サービスをできるだけ使わない最小版です。Python + OpenAIのembedding APIで、約60行。ベクトルストアも使わず、メモリ上の配列を総当たりで比較します(数千件までならこれで十分動きます)。
import numpy as np
from openai import OpenAI
client = OpenAI()
EMBED_MODEL = "text-embedding-3-small" # 埋め込みモデル名(後で"鍵"に使う)
THRESHOLD = 0.95 # これ以上似てたらキャッシュを返す
# キャッシュ本体(本番ではRedis等に置く。ここでは説明用にメモリ配列)
# 1件 = {"q": 質問文, "vec": 埋め込み, "a": 回答}
_cache: list[dict] = []
def embed(text: str) -> np.ndarray:
"""文章を意味ベクトルに変換する"""
resp = client.embeddings.create(model=EMBED_MODEL, input=text)
return np.array(resp.data[0].embedding, dtype=np.float32)
def cosine(a: np.ndarray, b: np.ndarray) -> float:
"""コサイン類似度(向きの近さ)を返す。1に近いほど意味が近い"""
return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))
def ask(question: str) -> str:
q_vec = embed(question)
# 1) 過去の質問から、いちばん意味が近いものを探す
best_sim, best_item = 0.0, None
for item in _cache:
sim = cosine(q_vec, item["vec"])
if sim > best_sim:
best_sim, best_item = sim, item
# 2) しきい値を超えていれば、モデルを呼ばずにキャッシュを返す
if best_item is not None and best_sim >= THRESHOLD:
print(f"[cache HIT] 類似度={best_sim:.3f} 元の質問=「{best_item['q']}」")
return best_item["a"]
# 3) 近いものが無ければ、モデルを呼んで結果を棚にしまう
print(f"[cache MISS] 最も近くて 類似度={best_sim:.3f}")
completion = client.chat.completions.create(
model="gpt-5.4",
messages=[{"role": "user", "content": question}],
)
answer = completion.choices[0].message.content
_cache.append({"q": question, "vec": q_vec, "a": answer})
return answer
if __name__ == "__main__":
print(ask("日本の首都はどこ?")) # MISS:モデルを呼ぶ
print(ask("にほんの首都を教えてください")) # HIT:意味が近いのでキャッシュ
10分の初回成功はここです。 これを自分の環境で動かすと、2回目の「にほんの首都を教えてください」で [cache HIT] が出ます。文字は全然違うのに、意味が近いからモデルを呼ばずに返せている。この瞬間が、セマンティックキャッシュの気持ちよさです。
ただし、この最小版はあくまで理解用。本番に出すには、あと4つだけ足りないものがあります。
コード例2:本番で事故らないための「しきい値ゲート+TTL+バージョンキー」
最小版に足すべきは、(1)しきい値を厳しめから始める (2)キャッシュに賞味期限(TTL)をつける (3)埋め込みモデル名を"鍵"に混ぜる の3つです。とくに(3)は、知らないと静かに事故る落とし穴なので、あとで独立して説明します。
import time
import hashlib
# 埋め込みモデル名をキャッシュの"名前空間"にする。
# → モデルを変えたら、古いキャッシュとは別の棚になる(後述のドリフト対策)
CACHE_NAMESPACE = hashlib.sha256(EMBED_MODEL.encode()).hexdigest()[:8]
TTL_SECONDS = 60 * 60 * 24 # 24時間で賞味期限切れ
THRESHOLD_SAFE = 0.97 # 最初は保守的に。誤ヒットを最優先で避ける
def ask_v2(question: str, user_id: str) -> str:
q_vec = embed(question)
now = time.time()
best_sim, best_item = 0.0, None
for item in _cache:
# 名前空間 と ユーザースコープ が違うものは比較対象にしない
if item["ns"] != CACHE_NAMESPACE:
continue
if item["user"] != user_id: # 他人のキャッシュを混ぜない(PII対策)
continue
if now - item["ts"] > TTL_SECONDS: # 期限切れは無視
continue
sim = cosine(q_vec, item["vec"])
if sim > best_sim:
best_sim, best_item = sim, item
if best_item is not None and best_sim >= THRESHOLD_SAFE:
return best_item["a"]
answer = _call_model(question)
_cache.append({
"q": question, "vec": q_vec, "a": answer,
"ns": CACHE_NAMESPACE, "user": user_id, "ts": now,
})
return answer
ポイントは3つです。
- しきい値は 0.97 から始める。 一次情報でも、初回デプロイは 0.97 が推奨されています。hit率は低め(5〜10%程度)ですが、誤ヒット率を 0.5% 未満に抑えられる。まず「間違えない」を優先して、あとから測りながら 0.92〜0.95 へ下げていく順番が安全です。最初から攻めない、これが鉄則。
- TTL(賞味期限)をつける。 「今日のキャンペーンは?」みたいな回答は、1日経てば古くなります。永久キャッシュは、古い答えを配り続ける事故のもと。
- ユーザースコープを切る。 「私の残高は?」の答えを他人に返したら、それは事故どころか情報漏洩です。個人に紐づく回答は、ユーザー単位でキャッシュを分けます。
コード例3:いちばん大事な「誤ヒット率(false positive)」の計測
ここが今日の心臓部です。hit率だけ見て喜ぶのは、いちばんやってはいけないこと なんです。
なぜなら、しきい値を下げればhit率はいくらでも上がるけど、その裏で「似てるけど実は違う質問」に過去の答えを返す 誤ヒット が増えるから。たとえば「パスワードを再設定するには?」と「メールアドレスを変更するには?」は、埋め込み上はけっこう近い。しきい値が甘いと、片方の答えをもう片方に返してしまう。
なので、正解ペアと不正解ペアを用意して、しきい値ごとにhit率と誤ヒット率の両方を測ります。これを golden set(お手本セット)と呼びます。
# (質問A, 質問B, 同じ意味か) のお手本セット
# 本番では、実際のトラフィックから人間がラベル付けして作る
golden = [
("日本の首都は?", "にほんの首都を教えて", True),
("パスワードを再設定したい", "メールアドレスを変えたい", False), # 近いが別物
("返品はできますか", "返品の方法を教えてください", True),
("送料はいくら", "配送にかかる日数は", False), # 近いが別物
]
def evaluate(threshold: float) -> dict:
tp = fp = fn = tn = 0
for a, b, same in golden:
sim = cosine(embed(a), embed(b))
hit = sim >= threshold # キャッシュが「同じ」と判定したか
if same and hit:
tp += 1
elif not same and hit:
fp += 1 # ← 誤ヒット(これが怖い)
elif same and not hit:
fn += 1 # 本当は使えたのに逃した
else:
tn += 1
hit_rate = tp / (tp + fn) if (tp + fn) else 0.0
fp_rate = fp / (fp + tn) if (fp + tn) else 0.0
return {"threshold": threshold, "hit_rate": round(hit_rate, 3),
"false_positive_rate": round(fp_rate, 3)}
for t in (0.90, 0.93, 0.95, 0.97):
print(evaluate(t))
この表を見て、「誤ヒット率が自分たちの許容ライン(たとえば 0.5% 未満)に収まる範囲で、いちばんhit率が高いしきい値」 を人間が選びます。しきい値は、どこかから借りてくるグローバルな正解値ではなくて、自分たちのトラフィックで決めるチューニングつまみ なんです。運用のおすすめは「まず 0.97 で出す → 48時間、誤ヒットを監視 → 0.01刻みで慎重に下げる」。
コード例4:実運用ラッパ(FastAPI + Redis のイメージ)
自前配列は数千件が限界です。本番でユーザー横断・大量トラフィックを捌くなら、ベクトル検索ができるストア(Redis Stack など)に載せ替えます。構造は最小版とまったく同じで、「探す場所」がメモリからRedisに変わるだけ。
from fastapi import FastAPI
import redis
from redis.commands.search.query import Query
app = FastAPI()
# Redis Stack はベクトル類似検索(KNN)に対応している
r = redis.Redis(host="localhost", port=6379)
@app.post("/ask")
def ask_endpoint(question: str, user_id: str):
q_vec = embed(question).tobytes()
# 名前空間(埋め込みモデル)+ユーザーで絞り、上位1件をベクトル近傍検索
q = (
Query(f"(@ns:{{{CACHE_NAMESPACE}}} @user:{{{user_id}}})=>[KNN 1 @vec $v AS score]")
.sort_by("score")
.return_fields("answer", "score")
.dialect(2)
)
res = r.ft("semcache").search(q, query_params={"v": q_vec})
if res.docs:
# Redisのvector distanceは「距離」なので、1 - distance で類似度に直す
sim = 1 - float(res.docs[0].score)
if sim >= THRESHOLD_SAFE:
return {"answer": res.docs[0].answer, "cached": True, "sim": sim}
answer = _call_model(question)
# ここでRedisにhash(vec, answer, ns, user, TTL)を保存する
return {"answer": answer, "cached": False}
「自前で組むのはしんどい」という場合は、GPTCache(Zilliz製のOSSライブラリ)という選択肢もあります。埋め込みモデル・ベクトルストア(Milvus / Faiss / Redis / Qdrant)・類似度評価・キャッシュ保存が、それぞれ差し替え可能なモジュールになっていて、しきい値やeviction(追い出し)ポリシーの設定も細かくできます。まずGPTCacheで感触をつかんで、要件が固まったら自前に寄せる、という進め方も現実的です。
| 選択肢 | 向いている場面 | 注意点 |
|---|---|---|
| 自前実装(配列) | 数千件まで・学習/PoC | 件数が増えると総当たりが重い |
| Redis Stack など | 本番・大量トラフィック | ベクトルインデックス設計が要る |
| GPTCache | Python中心・最短で試す | 依存が増える/中身の理解は別途必要 |
キャッシュしてはいけない回答(反証:ここは効きません)
セマンティックキャッシュは万能ではありません。むしろ使ってはいけない領域 があります。ここを外すと、コスト削減どころか信頼を失うので、正直にお伝えします。
- 個別・時系列に依存する回答: 「私の今の残高は?」「今日の株価は?」。同じ聞き方でも答えが毎回違うものは、キャッシュした瞬間に嘘になります。
- 権限・コンテキストで答えが変わる回答: 見る人の役割やアクセス権で内容が変わるものは、ユーザースコープを切っても危うい。原則キャッシュ対象外に。
- 誤ヒットが1件も許されない領域: 医療・法務・金融の個別判断など。ここは 0.97 でも攻めすぎです。
- そもそも同じ質問がほとんど来ないアプリ: hit率が数%しか出ないなら、キャッシュの運用コストのほうが高くつきます。
見分け方はシンプルで、「その質問への正解は、いつ・誰が聞いても同じか?」 を人間が最初に仕分けます。同じならキャッシュ候補、変わるなら対象外。この仕分けはAIに丸投げせず、ドメインを知っている人間がやるべき部分です。
静かに事故る最大の罠:埋め込みドリフト
最後に、知らないと必ず踏む落とし穴を1つ。
埋め込みモデルを別のものに変えた瞬間(たとえば text-embedding-ada-002 から text-embedding-3-small へ)、古い埋め込みと新しい埋め込みの間のコサイン類似度は、ほぼランダムな値になります。つまり、古いキャッシュに対して新しい質問を照らすと、まるで見当違いのものが「近い」と判定されて、自信満々に間違った答えを返し始める。しかもエラーは出ないので、気づきにくい。
対策はコード例2でやった通り、埋め込みモデル名をキャッシュの"名前空間(鍵)"に混ぜておく こと。モデルを変えたら名前空間が変わるので、古い棚とは自動的に別扱いになり、混線が起きません。地味ですが、これがあるかないかで運用の安全性が段違いです。
そのまま使えるプロンプト例3本
人間が判断する部分を、AIに壁打ち相手として手伝ってもらうためのプロンプトです。ダミーの前提で書いているので、自分の文脈に置き換えて使ってください。
プロンプト1:キャッシュ可否のトリアージ
あなたはLLMアプリの設計レビュアーです。
以下の想定質問リストについて、セマンティックキャッシュの対象にしてよいか、
1件ずつ「可 / 条件付き可 / 不可」で判定し、理由を1行で書いてください。
判定基準:
- いつ・誰が聞いても答えが同じか(時系列・個別・権限に依存しないか)
- 誤って別の答えを返したときの被害の大きさ
質問リスト:
1. 返品の方法を教えて
2. 私の直近の注文状況は?
3. 営業時間は何時から?
4. 私の契約プランの料金は?
プロンプト2:しきい値レビュー
セマンティックキャッシュのしきい値を検討しています。
以下は golden set で各しきい値を評価した結果です。
許容できる誤ヒット率(false positive rate)を 0.5% 未満とする前提で、
推奨しきい値と、その理由、監視すべき指標を提案してください。
安全側に倒す判断も明記してください。
[ここに evaluate() の出力表を貼る]
プロンプト3:誤ヒット監査レポート
本番ログから、キャッシュHITなのにユーザーが直後に言い直した
(=誤ヒットの疑いがある)ケースを抽出しました。
以下の「元の質問 / 新しい質問 / 返したキャッシュ回答」の組を見て、
本当に誤ヒットか、しきい値を上げるべきか、
それとも特定ドメインをキャッシュ対象外にすべきかを分類してください。
[ここに疑わしいペアを貼る]
今日からの4ステップ
- コード例1を自分の環境で動かす(10分)。「意味が近い質問」が2回目にHITするのを、自分の目で見る。
- キャッシュしていい質問と、ダメな質問を10個ずつ仕分ける(人間の仕事)。プロンプト1を使うと速い。
- golden setを20〜30ペア作って、しきい値を 0.97 → で評価(コード例3)。誤ヒット率が許容内で、hit率が最大のしきい値を選ぶ。
- 埋め込みモデル名を名前空間に入れて、TTLとユーザースコープを付けて本番へ(コード例2・4)。まず 0.97 で出して、48時間監視してから慎重に下げる。
一気に全部やらなくて大丈夫です。今日はステップ1だけでも、「意味で使い回す」の感覚がつかめます。
キャッシュって、地味なんですよね。誰も褒めてくれない。でも、同じ質問に毎回お金と時間を払っていた自分を助けてくれるのは、この地味な仕組みだったりします。
しきい値を測って、誤ヒットを監視して、埋め込みモデル名を鍵に混ぜておく。この小さな積み重ねが、来月の請求書と、ユーザーの待ち時間に、静かに効いてきます。未来の自分が「あのとき仕込んどいてよかった」と思える設計を、今日ちょっとだけ足しておく。そういう話でした。
明日の自分にあざっす、ですね。
参考リンク(一次情報・事実確認に使用):
- GPTCache(Zilliz / OSS): https://github.com/zilliztech/GPTCache
- GPT Semantic Cache(arXiv:2411.05276): https://arxiv.org/abs/2411.05276
- From Exact Hits to Close Enough: Semantic Caching for LLM Embeddings(arXiv): https://arxiv.org/abs/2603.03301
- Redis Vector Search ドキュメント: https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/
- OpenAI Embeddings ドキュメント: https://platform.openai.com/docs/guides/embeddings
(コード例は説明用の最小構成です。キャッシュの中核ロジック(コサイン類似度・しきい値ゲート・HIT/MISS判定・コード例3の混同行列計算)は、埋め込みをモックした状態でローカル実行し、期待通りに動くことを確認済みです。一方で embed() が呼ぶ埋め込みAPIやコード例4のRedis接続部分は筆者環境では未実行=「動作未確認」です。本番投入前に、ご自身の環境・実データでの動作確認としきい値チューニングを必ず行ってください。)
生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています → X: https://x.com/akira_papa_AI