Local embeddings for WordPress semantic search means generating vector representations of your posts, pages, and media on hardware you control, then storing those vectors somewhere WordPress can query. The generation half is largely a solved problem — small open models run comfortably on a CPU — but the storage half is where most implementations stall, because WordPress’s default MySQL/MariaDB database has no native vector index. The practical pattern is a custom table or an external vector store, plus a cosine-similarity query path.
This guide is for a technically curious WordPress developer or site owner who wants semantic search without routing every piece of content through a cloud embedding API. It covers the pipeline, the local runtimes worth considering, the storage options, and the tradeoffs that decide whether the approach survives contact with a real content catalog.
Why generate embeddings locally at all
WordPress’s built-in search is a LIKE '%term%' match against post_title and post_content. As the Wavise OpenLLM guide puts it, that approach cannot match “stop login guessing” to “brute force protection,” cannot rank by meaning, and collapses on synonyms. Embeddings fix the relevance problem by placing text in a shared vector space where semantically similar phrases land near each other.
The open question is where those vectors come from. A cloud API is the shortest path to a working index, and it is what most published WordPress plugins use. A local model changes three things: content never leaves your infrastructure, there is no per-token cost, and the pipeline keeps working offline. The costs are real too — you own the model download, the memory footprint, and the re-indexing work when you change models.
The four-stage pipeline
The Wavise guide breaks semantic search over WordPress into four moving parts, and the same decomposition applies whether the embedding step is local or remote:
| Stage | Job | Where |
|---|---|---|
| Embed | Turn post chunks into vectors | transformers.js (local) or OpenAI/Cohere API |
| Store | Persist vectors + chunk text | SQLite + vector ext, or Postgres pgvector |
| Retrieve | Cosine search top-k chunks | SQL, or a small PHP wrapper |
| Ground | Build an answer with citations | LLM call with retrieved context |
The data flow is wp-content → chunk → embed → store on publish, and query → embed → cosine top-k → LLM → cited answer on search. The grounding stage is optional: pure semantic search stops after retrieval and returns ranked posts or chunks.
Choosing a local embedding runtime
Three families of local runtime are practical for a WordPress integration. The right choice depends mostly on what you already operate.
transformers.js
The Wavise guide lists transformers.js as the local embedding option in its architecture table. It runs ONNX-format models in a browser or a Node process, which means no Python dependency and no separate model server if you already have a Node toolchain. For WordPress, the realistic deployment is a small Node sidecar that exposes an HTTP endpoint and is called from PHP with wp_remote_post().
Python with sentence-transformers
This is the most common local embedding path in the wider ecosystem. You load a sentence-transformers model, embed chunks in batches, and expose the result over a local HTTP endpoint. It adds a Python service to operate and monitor, but it gives you the widest selection of models and the most mature batching behavior.
Local model servers such as Ollama or llama.cpp
If you already run a local server for text generation, it may also expose an embedding endpoint. Reusing it keeps everything behind one local address and one set of operational habits, at the cost of coupling your search index to the lifecycle of a process you may restart for other reasons.
Model size is the variable that drives everything downstream. Small models such as all-MiniLM-L6-v2 produce 384-dimensional vectors and run acceptably on CPU. Larger models improve retrieval quality on nuanced queries but increase memory use, indexing time, and storage per chunk. That last point matters more than it first appears: 384 floats per chunk multiplied by tens of thousands of chunks is a real table.
Where to store the vectors
This is the part WordPress does not give you. MySQL and MariaDB, the databases WordPress targets, do not provide a general-purpose approximate-nearest-neighbor index comparable to pgvector. Two patterns are common.
A custom WordPress table
Create a table such as wp_embeddings with columns for post_id, chunk_index, chunk_text, model, and a vector column stored as JSON or a packed binary blob. Index post_id so deletion and re-indexing stay cheap. This is the approach taken by the reference plugin described below: it stores embeddings in a WordPress database table and provides semantic search for posts, pages, and image media without an external vector database.
One distinction is worth keeping straight. That plugin generates its embeddings with OpenAI — text-embedding-3-small by default — so it is a storage-and-retrieval reference, not a local-generation one. You can reuse its schema, queue, and query pattern while swapping the embedding call for a local runtime.
An external vector store
The Wavise guide lists SQLite with a vector extension and Postgres with pgvector as storage options. This scales better, gives you an approximate-nearest-neighbor index instead of a full scan, and keeps vector workloads out of the WordPress database. The cost is a second datastore to run, back up, and keep in sync with post lifecycle events.
A reference implementation to study
WP Native Vector Search (wokamoto/wp-native-vector-search) is a PHP plugin, first published in May 2026, that demonstrates the full storage-and-retrieval loop. Its documented features include generating text embeddings, storing vectors in a custom WordPress database table, queueing post indexing when a post is saved or its status changes, generating natural-language descriptions for uploaded images, storing those descriptions in wp_postmeta, indexing image descriptions for semantic media search, exposing search through a custom REST API endpoint, providing a Gutenberg search block, providing WP-CLI commands for bulk indexing, and adding a settings screen under Settings > Vector Search. Its stated requirements are WordPress 6.5 or later, PHP 8.0 or later, an OpenAI API key, and WordPress HTTP API access to api.openai.com.
The plugin’s own README is unusually candid about the limit of the approach: it is intended for technical evaluation, using it on sites with a large amount of data may cause severe performance degradation, and a production site should replace the cosine similarity search currently performed in PHP with a dedicated vector database. That warning is the single most useful thing in the repository for anyone planning a local build. Generating and storing vectors is straightforward; querying them at scale is where the design breaks.
Step-by-step: wiring local embeddings into WordPress
Prerequisites: WordPress 6.5 or later and PHP 8.0 or later, matching the floor set by the reference plugin; a local embedding runtime reachable over HTTP or in-process; and a way to run bulk jobs, for which WP-CLI is the practical choice.
- Decide a chunking strategy. Split
post_contentinto overlapping chunks — by heading, or by a token budget — and store the chunk text next to the vector so you can render a snippet in results. - Stand up the embedding runtime. Start a local service that accepts text and returns a float array. Verify it independently with a curl call before touching WordPress.
- Create the storage table. Use
dbDelta()in an activation hook so the schema is created and upgraded cleanly. - Hook indexing to save events. On
save_postand on status transitions, enqueue a job rather than embedding inline. The reference plugin does exactly this — it queues post indexing when a post is saved or when its status changes. - Process the queue with WP-CLI. A bulk command lets you re-index the whole site after a model change without tying up the admin interface.
- Expose a search endpoint. Register a REST route that embeds the incoming query locally, loads candidate vectors, computes cosine similarity, and returns the top-k chunks.
- Build the front end. A Gutenberg block or a shortcode that calls the endpoint and renders ranked results.
To verify the pipeline, embed a known post, then run a query using a synonym that does not appear anywhere in the post text. If the post does not rank near the top, check that the query is being embedded with the same model that produced the index — mismatched models produce similarity scores that are effectively meaningless.
Keeping the index fresh
Three maintenance rules prevent silent corruption of results. First, re-index whenever the embedding model changes; vectors from different models are not comparable, even if the dimensions match. Second, store the model name and version on every row so drift is detectable rather than invisible. Third, delete rows on post deletion and on chunk-boundary changes, and version your chunker so a chunking change triggers a re-index rather than leaving orphaned vectors behind.
Performance and tradeoffs
The dominant cost in a PHP-based implementation is the similarity scan. Computing cosine similarity across every stored vector is linear in the number of chunks. That is fine for a few hundred chunks and painful for a few hundred thousand — exactly the failure mode the reference plugin warns about. If your catalog is large, plan to move retrieval to pgvector, Qdrant, or a comparable store and keep WordPress as the front end and the content source of truth.
Memory and storage scale with embedding dimension. A 384-dimensional model keeps the table small; a 1024-dimensional model roughly triples the vector payload and slows every scan. Retrieval quality is the other axis: small local models are competitive for topical retrieval but may lag larger hosted models on nuanced or multi-hop queries. The only reliable way to decide is to test candidate models against your own content and queries, not against a public leaderboard.
Finally, account for operations. A local embedding service is another process to monitor, restart, and keep in sync with the WordPress deployment. That overhead is the price of keeping content on your own infrastructure, and it should be weighed honestly against the convenience of a hosted embedding API.
Next steps
Start narrow. Pick one post type, index a few hundred chunks, and measure query latency and result quality before expanding. If latency holds and the results are useful, widen the scope and add media descriptions. If the PHP similarity scan becomes the bottleneck, move the vectors to an external store and leave the WordPress-side queue and REST endpoint in place. Readers working through this can share their WordPress version, embedding runtime, model choice, and any errors encountered in the community discussion so others can compare setups.
FAQ
Can WordPress store embedding vectors in its own database?
Yes, in a custom table, typically with the vector stored as JSON or a packed binary blob. MySQL and MariaDB do not provide a general-purpose vector index comparable to pgvector, so similarity is computed in PHP or in SQL rather than through an ANN index.
Do I need a GPU to generate embeddings locally?
No. Small embedding models such as all-MiniLM-L6-v2 produce 384-dimensional vectors and run acceptably on CPU. Larger models improve retrieval quality on nuanced queries but increase memory use, indexing time, and storage per chunk.
What happens if I change the embedding model?
You must re-index. Vectors produced by different models are not comparable, even when their dimensions match, so mixing them produces similarity scores that carry no meaning.
How do I keep embeddings in sync when content changes?
Enqueue re-indexing jobs on save and status-change events rather than embedding inline, delete rows when a post is deleted, and store the model name and chunker version on each row so drift is detectable.