If you've ever built a search feature with LIKE '%query%' and watched it completely miss what the user obviously meant, you already understand the problem. Keyword search is brittle. It fails on synonyms, typos, and anything requiring conceptual understanding. Semantic search — powered by embeddings — solves this at the model level, not the application level. And it's more accessible to integrate into Laravel than most developers expect.
This guide walks through building a real semantic search pipeline: generating embeddings with OpenAI, storing and querying them in Pinecone, and wiring it all up in a Laravel application. No hand-waving — actual code you can adapt.
What Embeddings Actually Are (The 30-Second Version)
An embedding is a high-dimensional vector — an array of floats — that represents the meaning of a piece of text. OpenAI's text-embedding-3-small model outputs 1536-dimensional vectors. Texts with similar meaning produce vectors that are geometrically close to each other. That's the whole trick.
When a user searches for "affordable places to eat near the marina", the embedding of that query will be close to the embedding of a restaurant listing that says "budget-friendly dining, waterfront location" — even though no keywords match.
Setting Up Pinecone
Pinecone is a managed vector database. You create an index, specify the dimension (must match your embedding model's output), and choose a similarity metric. For OpenAI embeddings, use cosine.
Create a free Pinecone account, make an index called laravel-search with dimension 1536 and metric cosine, then grab your API key.
Add these to your .env:
OPENAI_API_KEY=sk-... PINECONE_API_KEY=pcsk_... PINECONE_HOST=https://laravel-search-xxxx.svc.aped-xxxx.pinecone.io Pinecone's REST API is straightforward, so we'll use Guzzle directly rather than adding another package dependency.
The Embedding Service
Create a dedicated service class to generate embeddings:
<?php namespace App\Services; use Illuminate\Support\Facades\Http; class EmbeddingService { public function generate(string $text): array { $response = Http::withToken(config('services.openai.key')) ->post('https://api.openai.com/v1/embeddings', [ 'model' => 'text-embedding-3-small', 'input' => $this->sanitize($text), ]); if ($response->failed()) { throw new \RuntimeException('OpenAI embedding request failed: ' . $response->body()); } return $response->json('data.0.embedding'); } private function sanitize(string $text): string { // Strip excessive whitespace, truncate to stay within token limits return mb_substr(trim(preg_replace('/\s+/', ' ', $text)), 0, 8000); } } Add to config/services.php:
'openai' => [ 'key' => env('OPENAI_API_KEY'), ], 'pinecone' => [ 'key' => env('PINECONE_API_KEY'), 'host' => env('PINECONE_HOST'), ], The Pinecone Service
<?php namespace App\Services; use Illuminate\Support\Facades\Http; class PineconeService { private string $baseUrl; public function __construct() { $this->baseUrl = config('services.pinecone.host'); } private function client() { return Http::withHeaders([ 'Api-Key' => config('services.pinecone.key'), 'Content-Type' => 'application/json', ])->baseUrl($this->baseUrl); } public function upsert(string $id, array $vector, array $metadata = []): void { $this->client()->post('/vectors/upsert', [ 'vectors' => [ [ 'id' => $id, 'values' => $vector, 'metadata' => $metadata, ], ], ])->throw(); } public function query(array $vector, int $topK = 10, array $filter = []): array { $payload = [ 'vector' => $vector, 'topK' => $topK, 'includeMetadata' => true, ]; if (!empty($filter)) { $payload['filter'] = $filter; } $response = $this->client()->post('/query', $payload)->throw(); return $response->json('matches', []); } public function delete(string $id): void { $this->client()->post('/vectors/delete', ['ids' => [$id]])->throw(); } } Indexing Your Content
Let's say you have a listings table. Create a command to index existing records:
<?php namespace App\Console\Commands; use App\Models\Listing; use App\Services\EmbeddingService; use App\Services\PineconeService; use Illuminate\Console\Command; class IndexListings extends Command { protected $signature = 'search:index-listings {--fresh : Delete all vectors first}'; protected $description = 'Generate embeddings and push to Pinecone'; public function handle(EmbeddingService $embeddings, PineconeService $pinecone): void { Listing::query()->chunk(50, function ($listings) use ($embeddings, $pinecone) { foreach ($listings as $listing) { // Build a rich text representation for embedding $text = implode(' ', [ $listing->title, $listing->description, $listing->category, $listing->location, ]); try { $vector = $embeddings->generate($text); $pinecone->upsert( id: 'listing-' . $listing->id, vector: $vector, metadata: [ 'listing_id' => $listing->id, 'category' => $listing->category, 'location' => $listing->location, ] ); $this->line("Indexed listing #{$listing->id}"); } catch (\Throwable $e) { $this->error("Failed listing #{$listing->id}: " . $e->getMessage()); } // Respect OpenAI rate limits usleep(200000); // 200ms } }); $this->info('Indexing complete.'); } } For ongoing indexing, hook into Eloquent model events in your AppServiceProvider or use an observer:
Listing::created(fn ($l) => IndexListingJob::dispatch($l)); Listing::updated(fn ($l) => IndexListingJob::dispatch($l)); Listing::deleted(fn ($l) => RemoveListingFromIndexJob::dispatch($l->id)); The Search Controller
Here's where it comes together. The user query gets embedded, Pinecone returns matching IDs, and you hydrate them from your database:
<?php namespace App\Http\Controllers; use App\Models\Listing; use App\Services\EmbeddingService; use App\Services\PineconeService; use Illuminate\Http\Request; class SearchController extends Controller { public function __construct( private EmbeddingService $embeddings, private PineconeService $pinecone, ) {} public function __invoke(Request $request) { $request->validate(['q' => 'required|string|min:2|max:500']); $queryVector = $this->embeddings->generate($request->q); // Optional: filter by category from request $filter = []; if ($request->filled('category')) { $filter['category'] = ['$eq' => $request->category]; } $matches = $this->pinecone->query( vector: $queryVector, topK: 20, filter: $filter ); // Extract DB IDs and preserve Pinecone's relevance order $listingIds = collect($matches) ->filter(fn ($m) => $m['score'] > 0.70) // Tune this threshold ->pluck('metadata.listing_id'); $listings = Listing::whereIn('id', $listingIds) ->get() ->sortBy(fn ($l) => $listingIds->search($l->id)); // Preserve vector ranking return response()->json([ 'query' => $request->q, 'results' => $listings, 'count' => $listings->count(), ]); } } The 0.70 score threshold is worth paying attention to. Cosine similarity returns values between -1 and 1; in practice, anything below 0.65-0.70 for general content is likely noise. Tune it against real queries from your domain.
Production Considerations Worth Knowing
Cache Embeddings for Common Queries
Embedding API calls add latency and cost. Cache vectors for frequently searched terms:
$vector = Cache::remember( 'embedding:' . md5($request->q), now()->addHours(24), fn () => $this->embeddings->generate($request->q) ); Hybrid Search
Pure semantic search occasionally whiffs on exact matches — a product SKU, a proper noun, a very specific phrase. The pattern that works well in production is running both a semantic search and a traditional MySQL fulltext or Meilisearch query in parallel, then merging and re-ranking results using Reciprocal Rank Fusion (RRF). It's more complexity, but the quality jump is real.
Cost at Scale
text-embedding-3-small costs $0.02 per million tokens. For most applications, that's negligible. Pinecone's free tier gives you one index with 100K vectors. Plan your namespace and batching strategy before hitting those limits.
Embedding Drift
If you switch models (say, from ada-002 to text-embedding-3-small), you must re-index everything. Vectors from different models are not comparable. Version your index name accordingly.
Closing Thoughts
Semantic search is one of those features that genuinely changes how users experience search — not incrementally, but qualitatively. The engineering overhead is surprisingly manageable once you've got the embedding and vector store services abstracted cleanly. The Laravel HTTP client, chunked Eloquent queries, and queued jobs give you everything you need to build this production-ready without reaching for heavyweight packages.
If you're curious how this kind of AI-powered search gets implemented in real client projects, the work coming out of HanzWeb Agency shows practical applications across search, recommendations, and content matching built on exactly this stack.
Start with one content type, pick a meaningful score threshold, and ship it. The iteration is fast once the pipeline exists.


