Dev.to AI 🤖 Ai 👁 0 📖 6 min read

Using Embeddings and Pinecone for Semantic Search in Laravel: A Production-Ready Guide

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 anyt

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.

📰 Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.