OllamaにRedisセマンティックキャッシュを導入する方法｜同一質問の重複LLM呼び出しを削減してチームサーバーのレスポンスを高速化する手順

この記事のポイント

・RedisStackのHNSWベクターインデックスと nomic-embed-text でセマンティックキャッシュを実現できる
・類似度閾値0.92（コサイン距離0.08）を起点に調整すれば、意味が同じ質問を自動でキャッシュヒットに振り分けられる
・Pythonの redis-py 17行のクラスで既存Ollamaコードへの差し込みが可能
・TTL・DIM不一致・メモリ上限が本番でよく引っかかるポイントで、それぞれ具体的な対処がある

# Redisの公式GPGキーを取得してリポジトリを追加する
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor \
  -o /usr/share/keyrings/redis-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] \
  https://packages.redis.io/deb $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/redis.list

sudo apt update

sudo apt install -y redis-stack-server
sudo systemctl enable redis-stack-server
sudo systemctl start redis-stack-server

# 起動確認
redis-cli ping
# 期待する出力: PONG

# RediSearchモジュールがロードされているか確認
redis-cli MODULE LIST
# redis-search が表示されればOK

sudo systemctl stop redis-server
sudo systemctl disable redis-server
sudo systemctl start redis-stack-server

# ベクターインデックスをredis-cliから直接作成する例
redis-cli FT.CREATE llm-cache ON HASH PREFIX 1 "cache:" \
  SCHEMA \
    prompt TEXT \
    response TEXT \
    embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE

# 作成確認
redis-cli FT.INFO llm-cache | grep num_docs

pip install redis numpy requests

import json, struct, hashlib
import numpy as np
import requests
from redis import Redis
from redis.commands.search.query import Query

OLLAMA_URL    = "http://localhost:11434"
EMBED_MODEL   = "nomic-embed-text"
LLM_MODEL     = "llama3.3:70b-instruct-q4_0"
CACHE_TTL     = 3600          # キャッシュの有効期限（秒）
DISTANCE_THR  = 0.08          # コサイン距離の閾値（1-0.92=0.08 → 92%以上の類似度）
INDEX_NAME    = "llm-cache"

class SemanticCache:
    def __init__(self):
        self.r = Redis(host="localhost", port=6379)

    def _embed(self, text: str) -> list:
        res = requests.post(f"{OLLAMA_URL}/api/embeddings",
                            json={"model": EMBED_MODEL, "prompt": text})
        return res.json()["embedding"]

    def _vec_bytes(self, vec: list) -> bytes:
        return np.array(vec, dtype=np.float32).tobytes()

    def _search(self, query_vec: list) -> str | None:
        q = (Query("*=>[KNN 1 @embedding $vec AS dist]")
             .return_fields("response", "dist")
             .sort_by("dist")
             .dialect(2))
        results = self.r.ft(INDEX_NAME).search(
            q, query_params={"vec": self._vec_bytes(query_vec)})
        if results.docs and float(results.docs[0].dist) < DISTANCE_THR:
            return results.docs[0].response
        return None

    def ask(self, prompt: str) -> tuple[str, bool]:
        vec = self._embed(prompt)
        cached = self._search(vec)
        if cached:
            return cached, True      # (応答テキスト, キャッシュヒット)

        res = requests.post(f"{OLLAMA_URL}/api/generate",
                            json={"model": LLM_MODEL,
                                  "prompt": prompt, "stream": False})
        response = res.json()["response"]

        key = f"cache:{hashlib.sha256(prompt.encode()).hexdigest()[:16]}"
        self.r.hset(key, mapping={
            "prompt":    prompt,
            "response":  response,
            "embedding": self._vec_bytes(vec),
        })
        self.r.expire(key, CACHE_TTL)
        return response, False


if __name__ == "__main__":
    cache = SemanticCache()
    test_prompts = [
        "Linuxでディスク容量を確認するコマンドは？",
        "ディスク使用量を調べるLinuxコマンドを教えて",    # セマンティックに近い
        "Linuxのメモリ使用量を確認する方法は？",
    ]
    for p in test_prompts:
        ans, hit = cache.ask(p)
        print(f"[{'HIT ' if hit else 'MISS'}] {p[:30]}... => {ans[:60]}")

# 動作確認スクリプトを実行する
cd /opt/ollama-cache
python3 semantic_cache.py

# 期待する出力例:
# [MISS] Linuxでディスク容量を確認する... => dfコマンドを使います。...
# [HIT ] ディスク使用量を調べるLinux...   => dfコマンドを使います。...
# [MISS] Linuxのメモリ使用量を確認する... => freeコマンドまたはtopコマン...

# キャッシュエントリ数を確認する
redis-cli FT.INFO llm-cache | grep num_docs

# 例: num_docs 47 → 47件がインデックス済み

# Redisのキャッシュヒット・ミス統計
redis-cli INFO stats | grep -E "keyspace_hits|keyspace_misses"
# keyspace_hits:1284
# keyspace_misses:312

#!/bin/bash
# キャッシュあり・なしの応答時間を比較する
PROMPT="Linuxのcronジョブ設定方法を教えてください"

echo "--- キャッシュなし（直接Ollama呼び出し）---"
time curl -s -X POST http://localhost:11434/api/generate \
  -d "{\"model\":\"llama3.3:70b-instruct-q4_0\",\"prompt\":\"${PROMPT}\",\"stream\":false}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['response'][:80])"

echo ""
echo "--- キャッシュあり（2回目・HIT想定）---"
time python3 -c "
from semantic_cache import SemanticCache
ans, hit = SemanticCache().ask('${PROMPT}')
print(f'HIT={hit}  {ans[:80]}')
"

# 既存インデックスのDIM確認
redis-cli FT.INFO llm-cache | grep -A1 "dim"
# DIM が 768 であることを確認する

ローカルLLMのキャッシュ・チューニングを2日間のハンズオンで体験する

セマンティックキャッシュやRAGパイプラインの構築を、実機GPU環境で手を動かしながら習得したい方向けに、「ローカルAIマスターセミナー」を開催しています。
少人数（最大8名）ZOOMハンズオン形式で実施しています。