Semantic Search in Laravel with Embeddings and Pinecone: A Production-Readiness Checklist
Ship-blocking checklist for teams replacing LIKE '%query%' with embedding-based retrieval — with explicit pass/fail criteria at every gate.

Figure: Editorial context image from the source page (preview only; rights remain with the publisher) · Credit / further reading: dev.to
Keyword search fails at the model level, not the application level. LIKE '%query%' cannot know that "cancel my subscription" and "stop billing" are the same intent, and no amount of WHERE clauses fixes that. Embeddings fix it by moving the comparison into vector space. But semantic search also introduces a new class of production failure: silent relevance drift, dimension mismatches, runaway embedding spend, and a vector index that quietly disagrees with your Postgres rows.
This checklist is written for a Laravel team about to put that pipeline in front of real users. Treat every Fail as a blocker, not a warning.
1. Pin the Embedding Contract
Before writing a single query, lock down which model produces vectors and how many dimensions it returns.
// config/semantic.php
return [
'model' => env('EMBEDDING_MODEL', 'text-embedding-3-small'),
'dimensions' => (int) env('EMBEDDING_DIMENSIONS', 1536),
'index' => env('PINECONE_INDEX', 'documents-prod'),
];
- Model name and dimension count live in config, not inline in services.
- Dimensions are declared at index creation and never change without a full reindex.
- The same model generates vectors for both ingestion and query.
Pass: A test asserts count($vector) === config('semantic.dimensions') for a freshly generated embedding.
Fail: Different model or dimension used in the ingestion job vs. the search controller. This is the single most common cause of "search returns nothing" — Pinecone rejects or silently mismatches queries against a differently-shaped index.
2. Provision the Index Deliberately
- Index created via an idempotent artisan command, not the Pinecone dashboard by hand.
- Metric set to
cosine(default for OpenAI embeddings) and documented. - Namespaces used, at minimum
prodandstaging. Never share one namespace across environments. - Metadata fields (
tenant_id,model_version,source_id,updated_at) are declared upfront as the filterable set.
Pass: Running the provisioning command twice produces no errors and no duplicate index. Fail: Index created manually in the console with defaults nobody recorded. When it's rebuilt in a new region, dimensions and metric differ and nothing works.
3. Make Ingestion Idempotent
Chunking is a product decision disguised as a technical one. Pick 300–800 tokens with overlap, and store the chunk boundaries.
class IndexDocument implements ShouldQueue
{
public function handle(EmbeddingClient $embeddings, PineconeClient $pinecone): void
{
$chunks = $this->document->chunk(config('semantic.chunk_size'));
foreach ($chunks as $i => $chunk) {
$vector = $embeddings->embed($chunk->text);
$pinecone->upsert($this->document->namespace, [[
'id' => "doc_{$this->document->id}_chunk_{$i}",
'values' => $vector,
'metadata' => [
'source_id' => $this->document->id,
'tenant_id' => $this->document->tenant_id,
'model_version' => config('semantic.model'),
],
]]);
}
}
}
- Vector IDs are deterministic (
doc_{id}_chunk_{n}) so re-upserts overwrite instead of duplicate. - Deletes propagate: deleting a Document deletes its vectors, via observer or a queued cleanup job.
-
model_versionis written into metadata on every vector. - Queue is rate-limited against your embeddings provider.
Pass: Reindexing the same 100 documents twice leaves exactly 100×(chunks) vectors, verified by index stats. Fail: UUIDs generated per run. Your index now contains three copies of every document and stale content outranks fresh content.
Critical pass criterion: orphan rate. Run a weekly job comparing source_ids in Pinecone against live records. Pass: < 1% orphans. Fail: anything higher — deletes are not wired.
4. Harden the Query Path
- Query embedding generated once per request, cached on the query string hash.
-
topKbounded (10–20), then re-ranked or trimmed in PHP. -
tenant_idfilter always applied — derived from the authenticated user, never from request input. - Returned metadata hydrated back through Eloquent so authorization is re-checked.
- Empty index or zero matches returns a graceful empty state, not a 500.
Pass: A user from tenant A searching a term that exists only in tenant B receives zero results, and an automated test proves it.
Fail: tenant_id passed as a request parameter. That's an IDOR with extra steps — vector metadata is not an authorization boundary.

Figure: HEXOPS original illustration inspired by the topic (not a copy of the source article imagery) · Credit / further reading: dev.to
5. Design the Fallback Before You Need It
Every remote dependency here will time out eventually.
- Pinecone and embedding calls wrapped in a circuit breaker (Laravel's
Http::retry()plus a breaker package or a simple failure counter in cache). - On breaker open, search degrades to a keyword query over the same corpus.
- Timeouts explicit: 2–3 s for embeddings, 1–2 s for query.
- The degraded path is logged with a distinct channel so you can alert on it.
Pass: Kill network access to Pinecone in staging; search still returns keyword results in under 500 ms and the UI labels nothing as broken.
Fail: Uncaught ConnectionException bubbling into a 500 on your primary search page. Semantic search should be an enhancement, never a single point of failure.
6. Control Cost and Rate Limits
- Embedding spend tracked per day with a metric, not discovered on the invoice.
- Ingestion batched (16–100 texts per embeddings call), never one call per chunk.
- Cache keyed on
hash(text + model_version); re-ingesting unchanged text costs $0. - Hard budget alert at 80% of expected monthly spend.
Pass: Reindexing the full corpus a second time with unchanged content incurs near-zero embedding cost. Fail: No cache layer. A backfill of 200k chunks at one API call each will rate-limit, retry, and quadruple your bill.
7. Instrument Relevance, Not Just Uptime
Uptime dashboards will tell you the pipeline is healthy while users find nothing.
- Golden set of 50–100 real queries with expected document IDs, run in CI.
- Recall@10 measured on that set; a threshold is enforced (e.g. ≥ 0.80).
- Zero-result rate and click-through on results tracked per day.
- Index freshness metric: age of the newest vector vs. newest database row.
Pass: Golden-set recall ≥ 0.80, and a PR that changes chunking or model cannot merge if recall drops more than 5 points. Fail: No golden set. You are tuning relevance by vibes, and the first complaint you hear will be six weeks after the regression shipped.
8. Rollout Gate
- Behind a feature flag, at 5% → 25% → 100%.
- A/B against keyword search with click-through as the primary metric.
- Rollback path tested: flag off returns keyword results instantly with no deploy.
- Runbook documents reindex time for the full corpus.
Pass: You can explain to a stakeholder, in one sentence, what metric moved and by how much. Fail: Shipping straight to 100% because "it worked in staging." Staging has 200 documents; production has 200,000 and a different query distribution.
The Short Version
The failure modes that actually bite are dimension drift, non-idempotent ingestion, missing tenant filters, and unmeasured relevance — not the embedding math. Get deterministic vector IDs, a model_version in metadata, a keyword fallback, and a golden set in CI, and the rest is tuning.
Sources



