Skip to content

PHP Embeddings: How 384 Numbers Find a Product

5 min read Notes

PHP Embeddings: How 384 Numbers Find a Product

A search box that matches substrings fails the moment a shopper types “warm jacket for rain” on a catalogue that calls the item “water-resistant parka”. The words share nothing, so the index returns zero rows and the page suggests a different category.

Code: FerryAI, MIT licensed.

PHP embeddings fix that by turning text into 384 numbers and comparing the numbers. A sentence and a product description that mean similar things end up close together, even when they share no vocabulary.

The mechanic is worth knowing in detail, because most semantic search failures come from one of four steps being skipped, not from the model being too small.

Step 1: the model, not the framework

An embedding model is a small neural network with one job: read a fixed slice of text, output a vector. all-MiniLM-L6-v2 is the common starting point at 384 dimensions, small enough to run on a CPU core and good enough for text shorter than a paragraph.

In PHP the model runs through ONNX Runtime loaded with FFI. There is no HTTP call, no socket, no serialisation between the caller and the model. The input is tokenised in PHP, the tokens become a tensor, and the runtime returns the vector.

Useful detail: pooling matters. Mean pooling over the token vectors is the usual choice, and using the CLS token instead gives different numbers for the same model. Whichever the model card names, use that one, or queries and documents will occupy two different spaces and every result will be nonsense.

Step 2: store vectors where you can query them

Two workable options, and the choice is about concurrency.

SQLite with sqlite-vec gives a native nearest-neighbour index in a single file. It suits a demo, a small catalogue, or a single-server site where the database already lives on disk. Without the extension the store falls back to brute force, which is honest and fast enough below a few hundred thousand vectors.

PostgreSQL with pgvector gives HNSW and IVFFlat indexes with concurrent writes. The operators <=>, <-> and <#> cover cosine, Euclidean and inner product distance, so the ranking call is one ORDER BY with a LIMIT.

The mistake at this step is storing the vector as a JSON string. It parses, it looks like it works, and every search reads every row.

Step 3: filter before you rank

Metadata filtering is what separates a demo from a search box. A shopper who selected size 42 should not receive 38s because the vector distance was closer.

Store the filterable fields next to the vector, as a small document or as columns, and apply them inside the query. On SQLite the filters run in the same statement; on pgvector they go in the WHERE clause before the index scan. Doing the filter afterwards in PHP means fetching ten results, discarding six, and showing four.

Step 4: rewrite the query, not the corpus

The weakest link is usually the query, not the index. “jacket for rain” embeds differently from “water-resistant parka”, and one sentence of rewriting closes most of the gap. A small model can expand the query with two or three synonyms in the language of the catalogue before embedding.

Cache those embeddings. A query repeated by a hundred visitors should cost one inference, and the same goes for product descriptions, which change when someone edits the page and never in between.

What breaks quietly

Dimension mismatch is the first silent failure. Changing the model without re-embedding the corpus returns results that look random, and nothing in the code complains.

Language drift is the second. A multilingual model and a monolingual model produce different spaces, so a catalogue with English descriptions and Russian queries needs either a multilingual model or two stores. Detecting the query language first is cheaper than reading bad results later. The text language detection guide shows how short a sample can be before the guess becomes unreliable.

Normalisation is the third. Cosine similarity expects unit vectors, so skipping normalisation turns the dot product into a score that grows with text length, and long descriptions win every query.

The cost on a real request

Inference for a 20-token query on a CPU core is measured in single-digit milliseconds, and the vector query adds a few more. That fits inside a page request. A batch job that embeds forty thousand products is the opposite case: run it from the CLI, keep the model warm, and write in chunks so a failure does not mean starting over.

Model files stay outside the web root and outside the repository. They are large, they are cached once, and they are replaced deliberately.

For teams checking whether the extracted text is readable before it goes into a knowledge base, the readability metrics guide covers the thresholds.

Background: ONNX Runtime and the all-MiniLM-L6-v2 model card.

Custom work

Need an API that does not exist yet?

Describe the task and the response format. We will estimate the endpoint, the integration and the maintenance.

Start a conversation