Modern AI applications do more than generate text. They need to understand your application's own documents, products, knowledge bases, support articles, PDFs, and database content.
This is where vector search + embeddings + Retrieval-Augmented Generation (RAG) becomes useful. Laravel 13 introduces a first-party AI SDK that provides APIs for embeddings, agents, similarity search, reranking, and vector stores, making these workflows much easier to integrate into a Laravel application. :contentReference[oaicite:2]{index=2}
In this tutorial, we will build the foundation of a Laravel 13 semantic search system and, more importantly, understand how text chunking affects search quality.
What You Will Build
By the end of this tutorial, you will understand this complete AI search pipeline:
Document
↓
Clean & Normalize Text
↓
Split Into Chunks
↓
Generate Embeddings
↓
Store Vectors
↓
Vector Similarity Search
↓
Retrieve Relevant Context
↓
AI / RAG Response
What Is Vector Search?
Traditional search usually looks for matching words. If a user searches for "Laravel authentication", keyword search mainly looks for documents containing words related to Laravel and authentication.
Vector search works differently. An embedding model converts text into a numerical vector that represents semantic meaning. The application can then compare the query vector with stored document vectors and retrieve content that is semantically similar, even when the exact words are different.
For example, a document containing "protect your application with login credentials and authorization" can potentially be relevant to a query such as "How do I secure Laravel login?" even though the wording is different.
Laravel 13 AI SDK and Vector Search
Laravel 13 includes the first-party Laravel AI SDK. The SDK provides a unified API for AI providers and supports capabilities including text generation, embeddings, agents, reranking, files, and vector-store integrations. :contentReference[oaicite:3]{index=3}
The SDK can generate embeddings and Laravel provides vector-column support for PostgreSQL with the pgvector extension. Laravel's documentation also supports vector indexes for faster similarity searches. :contentReference[oaicite:4]{index=4}
Step 1: Install Laravel AI SDK
Install the official Laravel AI package with Composer.
Laravel's current documentation uses the laravel/ai package for the AI SDK. :contentReference[oaicite:5]{index=5}
Step 2: Configure Your AI Provider
The exact environment variables depend on the provider you use. Keep API credentials in environment configuration rather than committing them to source control.
Always verify the provider and model configuration against the current Laravel AI SDK documentation and the provider's embedding-model requirements.
Step 3: Prepare PostgreSQL + pgvector
For database-backed semantic vector search, Laravel supports vector columns with PostgreSQL and the pgvector extension. The embedding dimensions stored in your database must match the dimensions produced by the embedding model you select. :contentReference[oaicite:6]{index=6}
For example, if your embedding model produces 1536-dimensional vectors, the vector column should be configured for 1536 dimensions.
Step 4: Create a Documents Table
A simple document table can contain the original text, metadata, and its embedding.
Laravel's documentation shows Schema::ensureVectorExtensionExists(), vector columns with a defined dimension, and vector indexes. Laravel can create an HNSW index with cosine distance when a vector column is indexed this way. :contentReference[oaicite:7]{index=7}
Step 5: Create the Document Model
The model should cast the embedding column using Laravel's vector cast.
Why Text Chunking Is So Important
One of the most common mistakes in RAG systems is embedding an entire large document as one vector.
Imagine a 100-page documentation file. A user asks one small question about database transactions. If the entire document is represented by one embedding, the retrieved context can be too broad.
Instead, the document can be divided into smaller meaningful sections called chunks. Each chunk receives its own embedding.
Simple Chunking Example
Suppose the original document contains:
Laravel queues allow developers to defer the processing of a time-consuming task...
Jobs can be dispatched to different queues depending on their priority...
Failed jobs can be retried using Laravel's queue retry mechanisms...
Instead of embedding the entire document, you can create chunks such as:
Chunk 1: Laravel queue fundamentals
Chunk 2: Queue priority and dispatching
Chunk 3: Failed jobs and retries
Now the vector database can retrieve the specific section related to the user's question.
Chunking Technique #1: Fixed-Size Chunking
The simplest approach is to split text after a fixed number of characters or tokens.
Good: Easy to implement and predictable.
Bad: It can cut a sentence, paragraph, code example, or logical section in the middle.
Fixed-size chunking can be useful for a first prototype, but production RAG systems often benefit from structure-aware chunking.
Chunking Technique #2: Paragraph-Based Chunking
Instead of cutting text at an arbitrary character position, split it using paragraph boundaries.
This approach usually preserves more natural semantic boundaries than blindly splitting every N characters.
Chunking Technique #3: Sentence-Based Chunking
Sentence-based chunking attempts to keep complete sentences together.
This is useful when your documents are primarily prose, such as help-center articles, documentation, policies, and knowledge-base articles.
The important principle is simple: do not sacrifice semantic boundaries just to reach an arbitrary chunk size.
Chunking Technique #4: Recursive Chunking
Recursive chunking uses multiple separators and progressively smaller boundaries.
For example:
1. Split by headings
2. Then split by paragraphs
3. Then split by sentences
4. Finally split large remaining sections
This is particularly useful for technical documentation because a document often has a natural hierarchy.
Chunking Technique #5: Overlapping Chunks
Chunk overlap means the end of one chunk is repeated at the beginning of the next chunk.
For example:
Chunk 1: Sentences 1–10
Chunk 2: Sentences 8–17
Chunk 3: Sentences 15–24
The overlap helps preserve context when an important sentence sits near a chunk boundary.
However, too much overlap creates duplicate embeddings, increases storage, increases embedding cost, and can produce repetitive retrieval results.
Good vs Bad Chunking
| Approach | Result |
|---|---|
| Entire 100-page document = 1 vector | Poor retrieval granularity |
| Random character splitting | May break semantic meaning |
| Paragraph-aware chunks | Better semantic boundaries |
| Heading + paragraph hierarchy | Useful for technical documentation |
| Reasonable overlap | Preserves boundary context |
Bad Practice: One Huge Chunk
A common beginner implementation is:
This technically generates an embedding, but it does not give your retrieval system fine-grained control over individual sections.
Better Practice: Embed Individual Chunks
After chunking the document, generate embeddings for the individual chunks.
Laravel's AI SDK supports generating embeddings for multiple inputs, returning an embedding for each input. :contentReference[oaicite:8]{index=8}
Store Chunks Instead of Only Documents
For serious RAG applications, it is often useful to create a separate document_chunks table rather than storing only one vector on the original document.
A practical structure can contain:
document_id — Parent document
content — Chunk text
embedding — Vector representation
chunk_index — Original order
metadata — Category, language, permissions, source, etc.
This gives your retrieval system much more control.
Example Document Chunks Migration
Generate a Query Embedding
At search time, the user's question also needs to be converted into an embedding.
Laravel's AI SDK provides the toEmbeddings() method on Laravel's Stringable implementation for generating embeddings from strings. :contentReference[oaicite:9]{index=9}
Similarity Search with Laravel AI SDK
Laravel's AI SDK includes a SimilaritySearch tool that can search an Eloquent model containing vector embeddings. It can also accept a minimum similarity threshold, result limit, and query customization. :contentReference[oaicite:10]{index=10}
The similarity threshold should not be treated as a universal magic number. The useful threshold depends on the embedding model, data quality, chunking strategy, query type, and application requirements.
Metadata Filtering Is a Major Best Practice
Vector similarity alone is not always enough.
Suppose your application contains documents for multiple companies. A user from Company A should not retrieve private documents belonging to Company B simply because the text is semantically similar.
Store relevant metadata and apply authorization and filtering rules before returning context to the AI model.
The Laravel AI SDK supports customizing similarity-search queries, including additional database conditions. :contentReference[oaicite:11]{index=11}
Vector Search vs Keyword Search
| Feature | Keyword Search | Vector Search |
|---|---|---|
| Exact terms | Strong | Not required |
| Semantic meaning | Limited | Strong |
| Typo handling | Depends on implementation | Not its primary purpose |
| AI/RAG context retrieval | Possible | Designed for semantic retrieval |
Laravel's search documentation distinguishes traditional full-text search from semantic/vector search and also documents reranking as a second-stage technique for improving relevance. :contentReference[oaicite:12]{index=12}
Hybrid Search: Keyword + Vector
A production search system does not always have to choose between keyword and vector search.
Hybrid search can combine lexical matching with semantic similarity. This can be particularly useful when users search for exact identifiers, product codes, error messages, version numbers, or technical terms.
For example:
User: "Laravel 13 queue worker timeout"
Keyword search: Finds exact Laravel, 13, queue and timeout matches.
Vector search: Finds semantically related queue-worker documentation.
Reranking: Can reorder retrieved results according to semantic relevance.
Laravel's current search documentation describes reranking as a second-stage process that can reorder retrieved results based on semantic relevance. :contentReference[oaicite:13]{index=13}
Reranking Can Improve Retrieval Quality
A common architecture is:
Query
↓
Retrieve top 20–50 candidates
↓
Rerank candidates
↓
Select top relevant chunks
↓
Send context to the LLM
This two-stage architecture can reduce the amount of irrelevant context sent to the generation model.
Good RAG Practice: Keep Metadata With Every Chunk
Do not store only the raw text and embedding. Metadata can become extremely valuable when your knowledge base grows.
Useful metadata can include:
- Document ID
- Chunk index
- Document type
- Category
- Tenant ID
- Language
- Published status
- Source URL or source identifier
- Access-control information
- Created and updated timestamps
Bad Practice: Ignoring Access Control
One of the most dangerous mistakes in RAG systems is assuming that vector similarity automatically provides authorization.
It does not.
Your application still needs to enforce authentication, tenant isolation, roles, permissions, and document-level access rules.
A semantically relevant private document must never become available simply because its embedding is similar to the user's query.
Good Practice: Queue Embedding Generation
Generating embeddings for thousands of documents can be expensive and time-consuming. Do not make a user wait for an HTTP request while your application processes an entire knowledge base.
A better architecture is:
Upload document
↓
Save document
↓
Dispatch background job
↓
Extract and clean text
↓
Chunk text
↓
Generate embeddings
↓
Store chunks + vectors
Laravel's AI platform also supports queued AI workloads, which is useful for moving heavy processing away from the request path. :contentReference[oaicite:14]{index=14}
Good Practice: Cache Embeddings
If the same content is embedded repeatedly, you can waste API calls and increase processing cost.
Use caching or content hashing so unchanged content does not need to be embedded again.
For example, calculate a hash from normalized content and use it to determine whether a chunk has changed.
The Laravel AI SDK also documents embedding caching as a supported optimization. :contentReference[oaicite:15]{index=15}
How Large Should a Chunk Be?
There is no universal chunk size that is correct for every application.
A useful starting point is to experiment with relatively focused chunks and evaluate retrieval quality using your real queries.
The correct size depends on:
- Document structure
- Embedding model
- Question length
- Amount of context required to answer
- Overlap strategy
- Retrieval limit
- LLM context window
Instead of asking "What is the perfect chunk size?", ask:
"Does this chunk contain enough context to answer a realistic user question without containing a large amount of unrelated information?"
Chunking Example for Laravel Documentation
Imagine a Laravel documentation page containing:
## Queues
Queue basics...
## Creating Jobs
Job creation...
## Dispatching Jobs
Dispatch examples...
## Failed Jobs
Retry configuration...
A good chunking strategy should preserve the heading with its associated content.
Instead of:
Prefer a structure such as:
Production RAG Architecture
A production Laravel AI application can be organized into separate stages.
1. Ingestion Layer
Upload PDFs, HTML, Markdown, database records, or other content.
2. Processing Layer
Extract, clean, normalize, and chunk text.
3. Embedding Layer
Generate vectors using the selected embedding model.
4. Storage Layer
Store chunks, metadata, and vectors.
5. Retrieval Layer
Run vector or hybrid search.
6. Reranking Layer
Improve the order of candidate results when required.
7. Generation Layer
Send the most relevant context to the AI model.
Laravel AI SDK Vector Stores
The Laravel AI SDK also provides vector-store functionality for searchable collections of files. This can be useful when your application wants to work with provider-managed file/vector storage rather than maintaining every retrieval component directly in your own database. :contentReference[oaicite:16]{index=16}
Which architecture you use depends on whether you need application-controlled database retrieval, provider-managed file search, or a combination of both.
Common Vector Search Mistakes
1. Embedding Everything Without Cleaning It
Headers, navigation menus, duplicated footer text, cookie notices, and irrelevant HTML can pollute your chunks.
2. Using Huge Chunks
Large chunks can contain several unrelated topics, reducing retrieval precision.
3. Using Tiny Chunks
Very small chunks may lose the context required to understand the information.
4. Too Much Overlap
Large overlap can dramatically increase the number of stored vectors and cause repetitive search results.
5. No Metadata
Without metadata, filtering by tenant, category, language, permissions, or document type becomes harder.
6. No Evaluation Dataset
Do not judge your RAG system using only one or two questions. Create a collection of realistic questions and expected relevant documents or chunks.
7. Sending Too Much Context to the LLM
Retrieving 50 chunks does not mean the model needs all 50. Retrieve candidates, optionally rerank them, and provide only useful context.
RAG Evaluation Checklist
Before deploying your Laravel vector-search application, test it with real questions.
- Does the correct document appear?
- Does the correct chunk appear?
- Are irrelevant chunks appearing?
- Are duplicate chunks appearing?
- Does tenant filtering work?
- Does authorization work?
- What happens when no relevant result exists?
- Does the AI answer only from retrieved context?
- How much does each embedding operation cost?
- How long does retrieval take?
Best Practices Summary
| Practice | Why It Matters |
|---|---|
| Structure-aware chunking | Preserves semantic meaning |
| Reasonable overlap | Protects context at boundaries |
| Vector indexes | Improves similarity-search performance |
| Metadata filtering | Improves relevance and security |
| Embedding caching | Avoids unnecessary embedding work |
| Queues | Keeps heavy ingestion work out of HTTP requests |
| Hybrid retrieval | Combines exact and semantic matching |
| Evaluation dataset | Makes retrieval quality measurable |
Laravel 13 Vector Search: Recommended Workflow
For a new project, a practical workflow is:
Laravel 13
+
Laravel AI SDK
+
PostgreSQL + pgvector
+
Structure-aware chunking
+
Embedding generation
+
HNSW vector index
+
Metadata filtering
+
Optional reranking
+
RAG generation
Laravel's current documentation specifically supports PostgreSQL vector columns, pgvector, HNSW indexing, embeddings, similarity search, and vector stores as part of the AI stack. :contentReference[oaicite:17]{index=17}
Final Thoughts
Vector search is not just about putting embeddings into a database. The quality of a RAG application depends on the complete retrieval pipeline: document cleaning, chunking, embeddings, indexing, filtering, retrieval, reranking, and context construction.
The biggest lesson is that there is no universal chunk size or retrieval threshold that works for every application. Start with a sensible structure-aware strategy, measure results using real queries, and tune the system based on retrieval quality, latency, storage, and cost.
With Laravel 13 and the Laravel AI SDK, developers can build these AI workflows using Laravel-native APIs while keeping embeddings, vector search, agents, and retrieval functionality organized inside the application. :contentReference[oaicite:18]{index=18}
Frequently Asked Questions
What is vector search in Laravel?
Vector search allows a Laravel application to retrieve content based on semantic similarity rather than relying only on matching keywords. Text is converted into embeddings and stored as vectors, which can then be compared against a query embedding.
Does Laravel 13 support vector search?
Yes. Laravel 13's AI stack includes embeddings and vector-search functionality. Laravel provides vector-column support for PostgreSQL with pgvector, and the AI SDK includes similarity-search capabilities. :contentReference[oaicite:19]{index=19}
What is the best chunk size for RAG?
There is no single best chunk size for every RAG application. Test different chunk sizes against real queries and choose a strategy that preserves enough context while avoiding unrelated information.
Should I use chunk overlap?
Overlap can help preserve context around chunk boundaries, but excessive overlap creates duplicate content, increases embedding work, and can produce repetitive retrieval results.
Is PostgreSQL required for Laravel vector search?
Laravel's documented database vector-search implementation supports PostgreSQL with the pgvector extension. The Laravel AI SDK also provides vector-store integrations, so the exact architecture depends on which retrieval approach your application uses. :contentReference[oaicite:20]{index=20}
Can Laravel AI SDK generate embeddings?
Yes. The SDK provides embedding APIs, including generating embeddings for multiple inputs and generating an embedding from a string through Laravel's Stringable API. :contentReference[oaicite:21]{index=21}
Should embeddings be generated inside a controller?
For small interactive operations this can be acceptable, but large document ingestion should normally be processed asynchronously so that uploads and normal HTTP requests are not blocked by heavy embedding work.
Can vector search be combined with keyword search?
Yes. Hybrid retrieval can combine lexical matching with semantic similarity. This can be useful when an application needs both exact matching and meaning-based retrieval.
What is RAG?
Retrieval-Augmented Generation, or RAG, is an architecture where relevant information is retrieved from an external knowledge source and supplied to an AI model as context before generating an answer.
What causes poor RAG results?
Common causes include poor chunk boundaries, overly large or tiny chunks, irrelevant document content, missing metadata filters, weak retrieval configuration, duplicate chunks, and sending too much irrelevant context to the generation model.
Conclusion
Laravel 13 makes it practical to build modern AI applications with a Laravel-native approach. When vector embeddings are combined with thoughtful chunking, PostgreSQL/pgvector, similarity search, metadata filtering, and optional reranking, Laravel can provide a strong foundation for semantic search and RAG applications.
Next step: Build a small document-search prototype first, create a real evaluation dataset, and then optimize your chunking and retrieval strategy using measurable results.
Related topics to explore: Laravel AI Agents, RAG Chatbots, PostgreSQL pgvector, Embeddings, Hybrid Search, Reranking, Laravel Queues, and AI-powered document search.