{ "id": "php", "title": "Redis semantic cache with Predis", "url": "https://redis.io/docs/latest/develop/use-cases/semantic-cache/php/", "summary": "Build a Redis-backed semantic cache for LLM responses in PHP with Predis and transformers-php", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc" ], "last_updated": "2026-06-01T09:32:08+01:00", "children": [], "page_type": "content", "content_hash": "67b3fa5d00b8b99ecacbec9df6526de2be887c891d9a0d43506a69ca1be08dfa", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "This guide shows you how to build a small Redis-backed semantic cache for LLM responses in PHP with [Predis](https://redis.io/docs/latest/develop/clients/php) and [TransformersPHP](https://transformers.codewithkyrian.com/) running the [`sentence-transformers/all-MiniLM-L6-v2`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) encoder locally on ONNX Runtime. It includes a local web server built with PHP's built-in development HTTP server so you can send paraphrased prompts at a mock LLM, watch the cache decide hit or miss, sweep the cosine-distance threshold, and see the cumulative latency and token savings build up." }, { "id": "overview", "title": "Overview", "role": "overview", "text": "Each cache entry is stored as a single Redis [Hash](https://redis.io/docs/latest/develop/data-types/hashes) at `cache:`. The hash holds the original prompt, the LLM's response, the raw `float32` bytes of a 384-dimensional embedding of the prompt, and metadata fields — tenant, locale, model version, safety flag — plus a `created_ts` and a `hit_count`. A single [Redis Search](https://redis.io/docs/latest/develop/ai/search-and-query) index covers the embedding field and every metadata field, so one [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) call with a `KNN` clause does the vector lookup *and* the TAG pre-filter in the same round trip — no cross-store joins.\n\nThe lookup is thresholded: [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) always returns the nearest entry that satisfies the filters, but the application only serves it as a hit when the reported cosine distance is at or below `distanceThreshold`. Anything further away is treated as a miss; the caller runs the LLM and writes the new prompt, response, and embedding back to the same key pattern with a TTL.\n\nThe embedder is [TransformersPHP](https://transformers.codewithkyrian.com/) running the [`Xenova/all-MiniLM-L6-v2`](https://huggingface.co/Xenova/all-MiniLM-L6-v2) ONNX export — the same 384-dimensional encoder the [Node.js example](https://redis.io/docs/latest/develop/use-cases/semantic-cache/nodejs) uses. The library is the established choice for vector embeddings in PHP (see [Index and query vectors](https://redis.io/docs/latest/develop/clients/php/vecsearch) for the precedent). Cosine distances differ from the Python and Jedis ports by only a few thousandths because of small numerical differences between ONNX Runtime and PyTorch, so a cache populated by one demo can be queried by another against the same Redis instance with very nearly the same hit/miss behaviour.\n\nThat gives you:\n\n* A single round trip for lookup — vector KNN + metadata pre-filter in one [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search).\n* Tens of milliseconds on a hit vs. a multi-second LLM call on a miss; the embedding step is the bottleneck either way, and that's a model-side cost, not a Redis one.\n* Tenant, locale, and model-version isolation enforced inside the query, not in application code — a write under one tenant cannot be served to another.\n* Bounded memory: every entry has an [`EXPIRE`](https://redis.io/docs/latest/commands/expire) TTL, and a database-level [eviction policy](https://redis.io/docs/latest/develop/reference/eviction) (LRU / LFU) caps the cache size under pressure." }, { "id": "how-it-works", "title": "How it works", "role": "content", "text": "A query goes through three stages: **embed**, **lookup**, and (on a miss) **call the LLM and write back**." }, { "id": "hit-path-the-goal", "title": "Hit path (the goal)", "role": "content", "text": "1. The application calls `$embedder->encodeOne($prompt)` to turn the incoming text into a 384-element `float` array.\n2. `$cache->lookup($queryVec, tenant: ..., locale: ..., modelVersion: ...)` runs [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) with a TAG pre-filter and a `KNN 1` clause. Redis returns the closest cached prompt that satisfies the filters along with its cosine distance.\n3. If the distance is at or below the threshold, the cache returns a `CacheHit` containing the cached response. The helper also issues an [`HINCRBY`](https://redis.io/docs/latest/commands/hincrby) on `hit_count` and an [`EXPIRE`](https://redis.io/docs/latest/commands/expire) refresh inside a [`MULTI/EXEC`](https://redis.io/docs/latest/commands/multi), so a frequently used answer keeps its TTL and the demo UI can see which entries are load-bearing.\n4. The LLM is not called at all. The application returns the cached response to the user." }, { "id": "miss-path", "title": "Miss path", "role": "content", "text": "When the distance is above the threshold — or there is no candidate in scope at all — the helper returns a `CacheMiss` instead, carrying the distance of the nearest candidate (if any) for logging. The application then:\n\n1. Calls the LLM with the prompt.\n2. Calls `$cache->put($prompt, $response, $embedding, tenant: ..., locale: ..., modelVersion: ...)`. The same embedding the lookup used is reused — no re-encode. The helper writes the Hash with [`HSET`](https://redis.io/docs/latest/commands/hset) and an [`EXPIRE`](https://redis.io/docs/latest/commands/expire) TTL inside a single [`MULTI/EXEC`](https://redis.io/docs/latest/commands/multi) so the entry never lands without a TTL on a partial failure.\n3. Returns the LLM's response to the user. The next semantically similar prompt under the same metadata scope will be a hit." }, { "id": "the-cache-helper", "title": "The cache helper", "role": "content", "text": "The `RedisSemanticCache` class wraps the Redis Search index and the lookup / write flow\n([source](https://github.com/redis/docs/blob/main/content/develop/use-cases/semantic-cache/php/src/RedisSemanticCache.php)):\n\n[code example]" }, { "id": "data-model", "title": "Data model", "role": "content", "text": "Each cache entry is one Redis Hash. The vector field is raw little-endian `float32` bytes — no JSON wrapping — because the Redis Search vector encoding expects exactly that. The helper packs the embedding with PHP's [`pack('g*', ...)`](https://www.php.net/manual/en/function.pack.php) (the `g` format is a little-endian single-precision IEEE-754 float), matching the encoding the Python, Node.js, Go, and Jedis ports write.\n\n[code example]\n\nThe Redis Search index schema treats every field as queryable in its natural type:\n\n[code example]" }, { "id": "the-query", "title": "The query", "role": "content", "text": "The lookup is a hybrid query: a TAG pre-filter expression in parentheses, then `=>[KNN 1 @embedding $vec]`. With `DIALECT 2`, Redis applies the filter first and KNN-ranks only the matching documents. In Predis:\n\n[code example]\n\n`distance` is the cosine *distance* (0 means identical, 2 means opposite). The result is sorted ascending, so the top row is the closest candidate. The application inspects `distance` against the threshold and decides hit or miss in user code — Redis returns the row either way, and treating it as a hit or a miss is a policy decision the cache helper owns, not a server-side filter.\n\nPredis 3.x defaults to query dialect 2; the cache helper sets it explicitly so the code reads correctly against earlier versions too. See [Index and query vectors](https://redis.io/docs/latest/develop/clients/php/vecsearch) for more on Predis's vector-search helpers." }, { "id": "the-mock-llm", "title": "The mock LLM", "role": "content", "text": "To make the latency and token savings visible without requiring an API key, `MockLLM.php` provides a deterministic stand-in\n([source](https://github.com/redis/docs/blob/main/content/develop/use-cases/semantic-cache/php/src/MockLLM.php)):\n\n[code example]\n\nThe mock sleeps for the configured latency, then keyword-matches against a small FAQ table to produce an answer. The deliberate slowness is what makes a hit visibly cheaper than a miss in the demo. In production code, you would replace `MockLLM` with your real client of choice — an HTTP call to OpenAI, Anthropic, a self-hosted vLLM endpoint, anything — without changing the cache helper." }, { "id": "pre-seeding-the-cache", "title": "Pre-seeding the cache", "role": "content", "text": "In a real deployment the cache fills up organically: a first-time question is a miss, the LLM answers, and the response is written back. For the demo, `SeedCache.php` pre-loads a small set of canonical FAQ prompts so the very first query lands on a hit\n([source](https://github.com/redis/docs/blob/main/content/develop/use-cases/semantic-cache/php/src/SeedCache.php)):\n\n[code example]\n\nThe seed list stores the canonical phrasing of each question (\"What is your return policy?\"). Paraphrases of any of these prompts (\"How do I return an item?\", \"Can I get a refund?\") embed close to the canonical entry, so the cache lookup serves the stored response without ever calling the model.\n\nThe seed helper embeds the prompts one at a time rather than as a single batched `encodeMany` call. TransformersPHP's attention-mask handling produces slightly different mean-pooled vectors for variable-length inputs inside a batch versus single-input calls, and that 0.01-cosine-distance drift would otherwise make a self-lookup of a seeded prompt look like a near-match instead of a clean zero-distance hit." }, { "id": "the-interactive-demo", "title": "The interactive demo", "role": "content", "text": "`public/index.php` is a front controller for PHP's built-in HTTP server — no Slim, no Symfony, no embedded framework. The HTML page lets you:\n\n* Type a prompt and toggle metadata: tenant, locale, model version. Each combination is a separate cache namespace inside the same index.\n* Slide the cosine-distance threshold and see hits flip to misses (and back) on the same prompt, with the actual distance reported on each query.\n* Submit with **Ask** to run the full hit-or-miss path (calls the LLM on a miss, writes the answer back). Submit with **Lookup only (no LLM)** to sweep the threshold against a fixed prompt without polluting the cache.\n* Watch the cumulative panel build up: total queries, cache hits, cache misses, hit ratio, tokens not spent, LLM milliseconds not waited.\n* Inspect every cached entry, including remaining TTL and total hit count, and drop individual entries to simulate eviction.\n\nThe front controller rebuilds a `LocalEmbedder`, a `RedisSemanticCache`, and a `MockLLM` on every request because PHP's built-in server is single-process and does not share user-land objects between requests. The first request is therefore slow (the embedder reloads the tokenizer and ONNX session); subsequent requests reuse the cached model files on disk and are fast. The HTML page is shared with the Python, Node.js, Go, and Jedis demos; the same `index.html` works against any of the language ports without modification. Endpoints:\n\n| Endpoint | What it does |\n|-----------------|-------------------------------------------------------------------------------|\n| `GET /state` | Index info and the full list of cached entries. |\n| `POST /query` | Embed the prompt, run `FT.SEARCH`, on miss call the LLM and write back. |\n| `POST /reset` | Drop every cached entry and re-seed from the FAQ list. |\n| `POST /drop` | Delete a single cached entry by id. |" }, { "id": "configuration", "title": "Configuration", "role": "configuration", "text": "PHP's CLI flag parsing is awkward, so the demo reads configuration from environment variables rather than `--`-style flags. All variables have defaults; override only what you need.\n\n| Variable | Default | Purpose |\n|-----------------------------|----------------|----------------------------------------------------|\n| `SEMCACHE_PORT` | `8093` | TCP port for the dev server |\n| `SEMCACHE_REDIS_HOST` | `localhost` | Redis host |\n| `SEMCACHE_REDIS_PORT` | `6379` | Redis port |\n| `SEMCACHE_INDEX_NAME` | `semcache:idx` | Redis Search index name |\n| `SEMCACHE_KEY_PREFIX` | `cache:` | Prefix for cache entry hashes |\n| `SEMCACHE_TTL_SECONDS` | `3600` | TTL on each cache entry |\n| `SEMCACHE_THRESHOLD` | `0.5` | Default cosine-distance threshold |\n| `SEMCACHE_LLM_LATENCY_MS` | `1500` | Mock LLM sleep, milliseconds |\n| `SEMCACHE_RESEED` | `true` | Re-seed FAQ entries on the first request |" }, { "id": "run-the-demo-locally", "title": "Run the demo locally", "role": "content", "text": "1. Clone the [`redis/docs`](https://github.com/redis/docs) repository and change into the example\n directory:\n\n [code example]\n\n2. Make sure a Redis instance with the Redis Search module is running locally on\n port 6379. [Redis Stack](https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack) or\n [Redis 8 with Search](https://redis.io/docs/latest/develop/ai/search-and-query) both work.\n\n3. Install the PHP dependencies with [Composer](https://getcomposer.org/). This step also\n downloads the prebuilt TransformersPHP native libraries (ONNX Runtime, OpenBLAS, Rindow's matlib FFI shim) for your platform — about 90 MB on macOS arm64:\n\n [code example]\n\n The example requires PHP 8.2 or later and uses [Predis](https://github.com/predis/predis) for Redis access, with no PHP extensions required beyond the standard `ffi` shipped with most builds.\n\n4. Start the demo. The included `run.sh` sets the PHP `ffi.enable=true` directive that\n TransformersPHP needs at runtime, caps `post_max_size` at 1 MiB to match the demo's\n body-size budget, and silences PHP 8.4 deprecation notices that `codewithkyrian/transformers`\n 0.5.x emits on the latest PHP — the underlying inference is unaffected. The first run\n downloads the `Xenova/all-MiniLM-L6-v2` ONNX weights (~30 MB) into the local Hugging\n Face cache; every subsequent run is offline:\n\n [code example]\n\n To pick a different port or threshold, set the corresponding environment variable\n before invoking the script:\n\n [code example]\n\n5. Open and try some queries:\n\n * **\"What is your return policy?\"** — exact match against the seed, distance ≈ 0,\n hit at any threshold.\n * **\"How fast is delivery?\"** — paraphrase of the shipping seed; distance\n around 0.30, hit at the default threshold of 0.5.\n * **\"How do I return an item?\"** — slightly looser paraphrase of the returns\n seed; distance around 0.49, still a hit at the default threshold. Slide\n the threshold down to 0.4 to see this one flip to a miss.\n * **\"What payment methods do you accept?\"** — unrelated to anything in the\n seed, but the embedding model still finds shallow surface-form similarity\n with the canonical \"What ___ do you ___?\" phrasing of the seeds, so the\n distance lands around 0.66. At the default threshold of 0.5 you will see\n a miss, the mock LLM kicks in for ~1.5 s, the new answer is cached, and\n a follow-up of the same question is now an immediate hit. At threshold\n 0.7 the same query is a borderline hit — that's the cosine-distance\n cutoff working exactly as advertised.\n * Switch the **Tenant** dropdown to `globex` or `initech` and re-ask any\n seeded question — the result flips to a miss because the cache entries\n live under `acme`. That's the metadata pre-filter at work inside `FT.SEARCH`.\n\nThe server is read/write against your local Redis. The default index name is `semcache:idx` and entry keys live under `cache:`. Set `SEMCACHE_RESEED=false` to keep an existing cache across restarts, `SEMCACHE_THRESHOLD` to change the default cosine-distance cutoff, `SEMCACHE_LLM_LATENCY_MS` to make the mock LLM faster or slower for the demo, or `SEMCACHE_PORT` to listen on a different port." } ], "examples": [ { "id": "the-cache-helper-ex0", "language": "php", "code": "use Predis\\Client;\nuse Redis\\SemanticCache\\{RedisSemanticCache, LocalEmbedder, CacheHit};\n\n$client = new Client(['host' => 'localhost', 'port' => 6379]);\n$embedder = LocalEmbedder::create(); // sentence-transformers/all-MiniLM-L6-v2\n\n$cache = new RedisSemanticCache(\n client: $client,\n indexName: 'semcache:idx',\n keyPrefix: 'cache:',\n distanceThreshold: 0.5, // cosine distance, lower = stricter\n defaultTtlSeconds: 3600, // one hour\n);\n\n// One-time index setup (idempotent).\n$cache->createIndex();\n\n// 1) Embed the prompt.\n$prompt = 'How do I return an item?';\n$queryVec = $embedder->encodeOne($prompt);\n\n// 2) Look up under a metadata scope. The TAG filter and the KNN\n// travel together in one FT.SEARCH.\n$result = $cache->lookup(\n queryVec: $queryVec,\n tenant: 'acme',\n locale: 'en',\n modelVersion: 'gpt-4.5-2026',\n);\n\nif ($result instanceof CacheHit) {\n $response = $result->response;\n printf(\"hit (%.3f): %s\\n\", $result->distance, $response);\n} else {\n // 3a) Miss — call the LLM. (Use your real client here.)\n $response = call_llm($prompt);\n\n // 3b) Cache the new entry. Reuses the same embedding bytes the\n // lookup used, so we don't pay the encoder twice.\n $cache->put(\n prompt: $prompt,\n response: $response,\n embedding: $queryVec,\n tenant: 'acme',\n locale: 'en',\n modelVersion: 'gpt-4.5-2026',\n );\n}", "section_id": "the-cache-helper" }, { "id": "data-model-ex0", "language": "text", "code": "cache:7c3f8a1b9e02\n prompt=How do I return an item?\n response=You can return any unworn item within 30 days...\n tenant=acme\n locale=en\n model_version=gpt-4.5-2026\n safety=ok\n created_ts=1715990400.123\n hit_count=4\n embedding=<384 × float32 little-endian bytes>", "section_id": "data-model" }, { "id": "data-model-ex1", "language": "text", "code": "FT.CREATE semcache:idx\n ON HASH PREFIX 1 cache:\n SCHEMA\n prompt TEXT\n response TEXT\n tenant TAG\n locale TAG\n model_version TAG\n safety TAG\n created_ts NUMERIC SORTABLE\n hit_count NUMERIC SORTABLE\n embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 384 DISTANCE_METRIC COSINE", "section_id": "data-model" }, { "id": "the-query-ex0", "language": "php", "code": "use Predis\\Command\\Argument\\Search\\SearchArguments;\n\n$arguments = (new SearchArguments())\n ->addReturn(7, 'prompt', 'response', 'tenant', 'locale',\n 'model_version', 'hit_count', 'distance')\n ->sortBy('distance', 'asc')\n ->limit(0, 1)\n ->dialect('2')\n ->params(['vec', pack('g*', ...$queryVec)]);\n\n$raw = $client->ftsearch(\n 'semcache:idx',\n '(@tenant:{acme} @locale:{en} @model_version:{gpt\\-4\\.5\\-2026} @safety:{ok})'\n . '=>[KNN 1 @embedding $vec AS distance]',\n $arguments,\n);", "section_id": "the-query" }, { "id": "the-mock-llm-ex0", "language": "php", "code": "use Redis\\SemanticCache\\MockLLM;\n\n$llm = new MockLLM(latencyMs: 1500.0);\n$response = $llm->complete('What is your return policy?');\n// $response['response'] — the templated answer text\n// $response['latency_ms'] — wall-clock time the call took\n// $response['total_tokens'] — estimated prompt + completion tokens", "section_id": "the-mock-llm" }, { "id": "pre-seeding-the-cache-ex0", "language": "php", "code": "use Redis\\SemanticCache\\SeedCache;\n\n$cache->createIndex();\nSeedCache::seed($cache, $embedder, tenant: 'acme', locale: 'en');", "section_id": "pre-seeding-the-cache" }, { "id": "run-the-demo-locally-ex0", "language": "bash", "code": "git clone https://github.com/redis/docs.git\n cd docs/content/develop/use-cases/semantic-cache/php", "section_id": "run-the-demo-locally" }, { "id": "run-the-demo-locally-ex1", "language": "bash", "code": "composer install", "section_id": "run-the-demo-locally" }, { "id": "run-the-demo-locally-ex2", "language": "bash", "code": "./run.sh", "section_id": "run-the-demo-locally" }, { "id": "run-the-demo-locally-ex3", "language": "bash", "code": "SEMCACHE_PORT=8093 SEMCACHE_THRESHOLD=0.4 ./run.sh", "section_id": "run-the-demo-locally" } ] }