Embeddings e Recuperação em Armazenamentos Vetoriais

Keyword search matches literal tokens. Semantic search matches meaning. The bridge between the two is an embedding: a fixed-length vector of floats that captures the semantic content of a piece of text.

• Texts with similar meaning produce vectors that are close together in vector space.
• Closeness is measured by cosine similarity or Euclidean distance.
• A query like "how do I reset my password" can match a document titled "account recovery steps" even with zero shared keywords.

In Spring AI, you generate embeddings with an EmbeddingModel and store/query them with a VectorStore. This lesson wires both together into a Retrieval-Augmented pipeline.

Spring AI exposes EmbeddingModel as a provider-agnostic interface. Add the starter (for example spring-ai-starter-model-openai) and Spring Boot auto-configures a bean you can inject.

• embed(String) returns a single float[].
• embed(List<String>) batches multiple texts efficiently.
• dimensions() tells you the vector size (for example 1536 for text-embedding-3-small).

Configure the model in application.yml so the bean is ready for injection.

Inject EmbeddingModel and call embed. The result is a dense vector you can inspect or persist. The richer embedForResponse call also returns token usage metadata.

• Always log dimensions() once at startup so a model swap that changes vector size is caught early.
• A vector store column must match this dimension exactly, or inserts fail.

To build intuition, here is the math a vector store does for you. Cosine similarity is the dot product of two vectors divided by the product of their magnitudes. It ranges from -1 (opposite) to 1 (identical direction).

• A value near 1.0 means the texts are semantically very close.
• Vector stores usually expose a similarity score derived from this metric.

This standalone program computes cosine similarity for two toy vectors.

A VectorStore persists Document objects together with their embeddings and supports similarity queries. Spring AI ships implementations for PGVector, Redis, Chroma, Milvus, Qdrant, and a SimpleVectorStore for tests.

• add(List<Document>) embeds and stores documents.
• similaritySearch(SearchRequest) embeds the query and returns the nearest documents.
• delete(...) removes documents by id or filter.

Critically, add calls the EmbeddingModel for you, so you rarely embed manually when using a store.

For production, PGVector (the Postgres extension) is a common choice because it co-locates vectors with your relational data. Add spring-ai-starter-vector-store-pgvector and configure the schema initialization.

• index-type: HNSW gives fast approximate nearest-neighbor search.
• dimensions must equal your embedding model's output size.
• initialize-schema: true lets Spring create the vector_store table on startup.

Wrap each chunk of source text in a Document. You can attach arbitrary metadata (source, author, tenant id) which becomes filterable at query time. Calling vectorStore.add(...) embeds and persists in one step.

• Use a stable id when you want to upsert rather than duplicate.
• Keep chunks small (a few hundred tokens) so retrieved context is focused.

Real corpora arrive as PDFs, Markdown, or JSON. Spring AI's ETL pipeline provides DocumentReader sources and DocumentTransformer splitters. The TokenTextSplitter breaks large documents into embedding-sized chunks while preserving metadata.

• TikaDocumentReader reads PDFs, Word, HTML.
• TokenTextSplitter splits by token count with configurable overlap.
• The output feeds straight into vectorStore.add(...).

SearchRequest is a builder that controls retrieval. The key knobs are topK (how many results) and similarityThreshold (drop weak matches below a cutoff).

• A higher similarityThreshold (for example 0.75) reduces noise but may return fewer hits.
• topK caps how much context you feed to the LLM, controlling token cost.

Semantic relevance alone is not enough for multi-tenant or scoped data. SearchRequest accepts a filter expression evaluated against document metadata, combining vector similarity with structured constraints.

• Use FilterExpressionBuilder or a portable string expression.
• The store applies the filter and the similarity ranking together.
• This is how you enforce tenant isolation: tenantId == 'acme'.

Retrieval is the first half of RAG (Retrieval-Augmented Generation). The second half stuffs retrieved chunks into the prompt so the LLM answers grounded in your data. Spring AI's QuestionAnswerAdvisor wires the vector store directly into a ChatClient call.

• The advisor runs a similarity search per request and injects results as context.
• You pass the same SearchRequest tuning (topK, threshold) into the advisor.
• This keeps the answer faithful to your indexed documents and reduces hallucination.

You built a complete semantic retrieval pipeline in Spring AI:

• EmbeddingModel turns text into dense vectors; dimensions() must match your store's column size.
• VectorStore (PGVector, Redis, Qdrant, etc.) stores Documents and embeds them automatically on add().
• Use the ETL pipeline (TikaDocumentReader + TokenTextSplitter) to chunk real-world files before ingestion.
• SearchRequest controls retrieval via topK, similarityThreshold, and metadata filterExpression for scoping and tenant isolation.
• QuestionAnswerAdvisor turns retrieval into full RAG by injecting matched context into a ChatClient prompt.

Tune topK for cost and similarityThreshold for precision to balance grounding against token budget.