“Deep Learning” sobre Spring AI: RAG, Embeddings y Vector Databases.

Como ya hemos comentado, los LLMs son modelos preentrenados hasta una cierta fecha y con datos públicos (se supone que no tienen acceso a datos de una empresa o de nuestros dispositivos, por ejemplo). También es popular la importancia de los tokens en aspectos como la facturación o la context-window (no podemos enviar todo lo que queramos en el input ni el output, aunque hay LLMs que tienen context-window de millones de tokens como Gemini).

El patrón RAG se enfoca en ayudarnos con estas limitaciones de los LLMs de cara a tener unos mejores resultados, con menos alucinaciones y reduciendo el coste por uso.

Antes de entrar en detalle, puedes echarle un vistazo al resto de contenidos de la serie de Spring AI en los siguientes enlaces por si te has perdido alguno de los artículos anteriores:

• "Deep Learning" sobre Spring AI: primeros pasos
• “Deep Learning” sobre Spring AI: multimodularidad, prompts y observabilidad
• "Deep Learning" sobre Spring AI: Advisors, Structured Output y Tool Calling

Algunas de las bases de RAG ya las hemos visto en el post de los Advisors, Tool-Calling o el tema de aumentar el contexto, pero en este post nos centraremos más en la esencia del propio RAG y en qué tecnologías y abstracciones está apoyado.

RAG

Retrieval Augmented Generation (RAG) es una técnica muy empleada para abordar las limitaciones que existen en los modelos lingüísticos con contenidos grandes, precisión y conocimiento del contexto. El enfoque se basa en un procesamiento batch en donde primero se leen datos desestructurados desde los documentos (u otros orígenes de datos), se transforman y luego se escriben en una Vector Database (a grandes rasgos es un proceso ETL).

Una de las transformaciones en este flujo es la división del documento original (u origen de datos) en piezas más pequeñas, existiendo dos pasos clave:

• División en partes más pequeñas preservando la semántica. Por ejemplo, en un documento con párrafos y tablas intentamos evitar la división en la mitad de uno de ellos. En el caso de código, evitar la división en mitad de un método.
• División en partes cuyo tamaño es menor que el límite de tokens del modelo.

La siguiente fase en RAG ya sería el procesamiento del input del usuario, empleando la búsqueda por similitud para enriquecer el contexto con documentos similares a enviar al modelo.

Spring AI soporta RAG proporcionando una arquitectura modular que permite crear flujos RAG personalizados o usar los creados a través del uso del API de Advisor.

• QuestionAnswerAdvisor: realiza queries a la bbdd vectorial para obtener documentos relacionados con el input del usuario, cuya respuesta se incluye en el contexto enviado al modelo.

String rag() {
    return ChatClient.builder(chatModel)
        .build().prompt()
        .advisors(new QuestionAnswerAdvisor(vectorStore))
        .user("que me puedes decir de los aranceles de EEUU en el año 2025")
        .call()
        .content();
}

En el ejemplo, QuestionAnswerAdvisor realizará una búsqueda por similitud sobre los documentos en la base de datos, pudiendo filtrar los documentos por los que se busque con la clase SearchRequest (también en tiempo de ejecución).

• RetrievalAugmentationAdvisor (en pruebas): advisor experimental que proporciona los flujos RAG más comunes (Naive RAG y Advanced RAG).

Módulos

Spring AI implementa una arquitectura modular RAG basada en el documento Modular RAG: Transforming RAG Systems into LEGO-like Reconfigurable Frameworks. Esto todavía está en fase experimental, por lo que es susceptible a cambios. Los módulos que se pueden encontrar son:

• Pre-Recuperación: módulos responsables para procesar la query del usuario para mejorar los resultados. Clases como CompressionQueryTransformer, RewriteQueryTransformer, TranslationQueryTransformer, MultiQueryExpander permiten transformar las queries del usuario para comprimir el contexto, transformar contenido ambiguo o irrelevante, traducir o dar distintas perspectivas semánticas.

Query query = new Query("Hvad er Danmarks hovedstad?");

QueryTransformer queryTransformer = TranslationQueryTransformer.builder()
        .chatClientBuilder(chatClientBuilder)
        .targetLanguage("english")
        .build();

Query transformedQuery = queryTransformer.transform(query);

• Recuperación: módulos responsables para obtener los documentos más relevantes de la base de datos. Las clases que se pueden emplear son VectorStoreDocumentRetriever y ConcatenationDocumentJoiner.

Map<Query, List<List<Document>>> documentsForQuery = ...
DocumentJoiner documentJoiner = new ConcatenationDocumentJoiner();
List<Document> documents = documentJoiner.join(documentsForQuery);

• Post-recuperación: módulos para procesar los documentos recuperados para mejorar la generación de resultados. Clases como DocumentRanker, DocumentSelector y DocumentCompressor para clasificar, seleccionar, eliminar o comprimir documentos innecesarios.
• Generación: módulos para generar la respuesta final al usuario. La clase ContextualQueryAugmenter para añadir datos adicionales útiles para el modelo.

Embeddings

Los embeddings son representaciones numéricas de texto, imágenes o vídeos que capturan la relación entre los datos de entrada. Funcionan transformando texto, imágenes o vídeos en arrays de números llamados vectores, que están diseñados para capturar el significado de estos recursos. Esto se hace calculando la distancia numérica entre dos vectores de, por ejemplo, dos textos, pudiendo así determinar su similitud.

La interfaz EmbeddingModel está diseñada para la integración con los modelos, cuya función principal es convertir los recursos en vectores numéricos que son usados para análisis semántico y clasificación de textos, entre otros. La interfaz se centra principalmente en:

• Portabilidad: la interfaz asegura la adaptabilidad entre distintos modelos con cambios de código mínimos.
• Simplicidad: proporciona métodos que simplifican el proceso de transformar los recursos a embeddings con métodos como embed(String text) sin necesidad de conocer las transformaciones internas.

API Overview

La interfaz EmbeddingModel extiende de la interfaz Model, así como EmbeddingRequest y EmbeddingResponse de sus correspondientes ModelRequest y ModelResponse. En la siguiente imagen se puede observar las relaciones entre el Embedding API, la Model API y los Embedding Models:

Ya más en profundidad:

• EmbeddingModel: se pueden ver las distintas opciones proporcionadas para transformar texto en embeddings, además de incluir un método dimensions, importante para conocer el tamaño o dimensionalidad del vector.

public interface EmbeddingModel extends Model<EmbeddingRequest, EmbeddingResponse> {

    @Override
    EmbeddingResponse call(EmbeddingRequest request);
    float[] embed(Document document);
    default float[] embed(String text) {...}
    default List<float[]> embed(List<String> texts) {...}
    default EmbeddingResponse embedForResponse(List<String> texts) {...}
    default int dimensions() {...}
}

• EmbeddingRequest: es una ModelRequest que contiene una lista de textos, así como unas opciones de embedding.

public class EmbeddingRequest implements ModelRequest<List<String>> {
    private final List<String> inputs;
    private final EmbeddingOptions options;
    ...
}

• EmbeddingResponse: contiene la salida del modelo con Embeddings, que contiene el vector de respuesta además de metadatos sobre la misma.

public class EmbeddingResponse implements ModelResponse<Embedding> {
    private List<Embedding> embeddings;
    private EmbeddingResponseMetadata metadata = new EmbeddingResponseMetadata();
    ...
}

• Embedding: representa un embedding vector.

public class Embedding implements ModelResult<float[]> {
    private float[] embedding;
    private Integer index;
    private EmbeddingResultMetadata metadata;
    ...
}

Implementaciones disponibles

En esta página puedes encontrar las implementaciones disponibles. Siguiendo las premisas de posts anteriores nos centraremos en la implementación de Ollama.

Propiedades

De cara a la autoconfiguración, se proporcionan una serie de propiedades muy similares a las propiedades existentes en el modelo de chat, habilitando la autoconfiguración con la propiedad:

spring.ai.model.embedding

Implementación

A continuación mostramos distintos ejemplos de cómo hacer uso del OllamaEmbeddingModel y EmbeddingModel:

• Autoconfiguración: ya existe un bean EmbeddingModel en el contexto para poder ser usado directamente:

@Autowired
private EmbeddingModel autoEmbeddingModel;
...
@GetMapping("/auto")
public EmbeddingResponse embed() {
    return autoEmbeddingModel.embedForResponse(List.of("Tendencias tecnologicas 2025", "Tendencia tecnologica IA", "Tendencia tecnologica accesibilidad"));
}

• Configuración manual: en caso de no usar Spring Boot, o por otras necesidades, se puede configurar manualmente el OllamaEmbeddingModel. Para eso, en caso de ser necesario, se deberá añadir la dependencia:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
</dependency>

Para, posteriormente, crear la instancia correspondiente:

private OllamaApi ollamaApi;
private OllamaEmbeddingModel embeddingModel;

public EmbeddingController() {
    ollamaApi = new OllamaApi();
    embeddingModel = 
OllamaEmbeddingModel.builder().ollamaApi(ollamaApi).defaultOptions(OllamaOptions.builder().model(OllamaModel.LLAMA3_2_1B).build()).build();
}

@GetMapping("/plain")
public EmbeddingResponse embedd() {
    return embeddingModel.call(new EmbeddingRequest(List.of("Tendencias tecnologicas 2025", "Tendencia tecnologica IA", "Tendencia tecnologica accesibilidad"), 
        OllamaOptions.builder()
            .model(OllamaModel.LLAMA3_2_1B)
            .truncate(false)
            .build()));
}

Vector Databases

Son un tipo de bases de datos especializadas que, en vez de realizar coincidencias exactas, se apoyan en las búsquedas por similitud, es decir, cuando se indica como entrada un vector, el resultado son vectores “similares”. En primer lugar, se cargan los datos en la base de datos vectorial. Posteriormente, cuando se envía una petición al modelo, primero se recuperan unos vectores similares que luego son usados como contexto para la pregunta del usuario y enviados también al modelo.

API Overview

Para trabajar con las bases de datos vectoriales se hace uso de la interfaz Vector Store:

public interface VectorStore extends DocumentWriter {
    default String getName() {...}
    void add(List<Document> documents);
    void delete(List<String> idList);
    void delete(Filter.Expression filterExpression);
    default void delete(String filterExpression) {...};
    List<Document> similaritySearch(String query);
    List<Document> similaritySearch(SearchRequest request);
    default <T> Optional<T> getNativeClient() {...}
}

Además de la clase SearchRequest:

public class SearchRequest {
    public static final double SIMILARITY_THRESHOLD_ACCEPT_ALL = 0.0;
    public static final int DEFAULT_TOP_K = 4;
    private String query = "";
    private int topK = DEFAULT_TOP_K;
    private double similarityThreshold = SIMILARITY_THRESHOLD_ACCEPT_ALL;
    @Nullable
    private Filter.Expression filterExpression;
    public static Builder from(SearchRequest originalSearchRequest) {...}
    public static class Builder {...}
    public String getQuery() {...}
    public int getTopK() {...}
    public double getSimilarityThreshold() {...}
    public Filter.Expression getFilterExpression() {...}
}

Para insertar datos en la base de datos vectorial es necesario encapsular dichos datos en un objeto Document. Al insertarse en la bbdd, el texto se transforma en un array de números conocido como embedding vector (la función de la bbdd vectorial es realizar búsquedas por similitud, no para generar los embeddings en sí). Los métodos similaritySearch permiten obtener documentos similares a una petición, pudiendo ajustarse con los siguientes parámetros:

• k: número entero que indica el número máximo de documentos similares a retornar. Se conoce habitualmente como búsqueda “top K” o “K nearest neighbors” (KNN).
• threshold: número entre 0 y 1 en donde los valores más cercanos a 1 indican más similitud.
• Filter.Expression: una clase usada para indicar una expresión DSL (Domain-Specific Language) que funciona similar a la cláusula “where” en SQL, pero que solo aplica a los metadatos de un Document. Puedes encontrar algunos ejemplos en esta página.

FilterExpressionBuilder builder = new FilterExpressionBuilder();
Expression expression = builder.eq("tendencia", "cloud").build();

• filterExpression: una expresión DSL que permite expresiones de filtrado como Strings. Por ejemplo, con metadatos como país, año e isActive se podría crear una expresión como “country == 'UK' && year >= 2020 && isActive == true”.

Schema Initialization

Algunas bases de datos necesitan que se inicialice el esquema antes de usarlo. Con Spring Boot se puede configurar la propiedad …initialize-schema a true, aunque lo adecuado es contrastar esta información con cada una de las implementaciones.

Batching Strategy

Es común cuando se trabaja con este tipo de bbdd tener que embeber muchos documentos.

Aunque la primera idea que se nos ocurre es intentar embeber todos estos documentos al mismo tiempo, puede llevar a ciertos problemas. Esto se debe sobre todo a los límites de tokens en los modelos (window size), lo que provocaría errores o embedings truncados.

Para eso precisamente se usa la estrategia batch, en donde se dividen conjuntos grandes de documentos en conjuntos más pequeños que cuadren con la window size. Esto no solo soluciona el problema de los límites de tokens, sino que además puede mejorar el rendimiento y los límites de peticiones existentes en las distintas APIs.

Spring ofrece esta funcionalidad a través de la interfaz BatchingStrategy:

public interface BatchingStrategy {
    List<List<Document>> batch(List<Document> documents);
}

La implementación por defecto es TokenCountBatchingStrategy que basa la división según el número de tokens existentes en cada batch, asegurándose que no se supere el límite de input de tokens. Los puntos importantes de esta implementación serían:

• Se usa el max input token limit de OpenAI (8191) por defecto.
• Se incluye un porcentaje de reserva (por defecto el 10%) para un buffer de overhead.
• Se calcula el límite máximo del token como: actualMaxInputTokenCount = originalMaxInputTokenCount * (1 - RESERVE_PERCENTAGE).

La estrategia estima el número de tokens por documento, los agrupa en batch sin exceder el límite de tokens, lanzando una excepción si alguno de los documentos lo excediera. También se puede personalizar la estrategia creando una nueva instancia a través de una clase @Configuration:

@Configuration
public class EmbeddingConfig {
    @Bean
    public BatchingStrategy customTokenCountBatchingStrategy() {
        return new TokenCountBatchingStrategy(
            EncodingType.CL100K_BASE,  // Specify the encoding type
            8000,                      // Set the maximum input token count
            0.1                        // Set the reserve percentage
        );
    }
}

Una vez definido este bean, será usado automáticamente por las implementaciones del EmbeddingModel en vez de la estrategia por defecto. Adicionalmente, se permite incluir las implementaciones propias de TokenCountEstimator (clase que calcula los tokens del documento), además de parámetros para formatear contenido y metadatos o incluso nuestra propia implementación custom. Y, como en otras ocasiones, además se permite crear la implementación completamente personalizada:

@Configuration
public class EmbeddingConfig {
    @Bean
    public BatchingStrategy customBatchingStrategy() {
        return new CustomBatchingStrategy();
    }
}

Implementaciones disponibles

En esta página se pueden encontrar las implementaciones disponibles. En este caso, nos centraremos en la implementación PGvector para bases de datos PostgreSQL, que no es más que una extensión open source para PostgreSQL que permite guardar y buscar sobre embeddings.

Prerrequisitos

En primer lugar, se necesita acceso a PostgreSQL con las extensiones vector, hstore y uuid-ossp. Al iniciarse PgVectorStore intentará instalar las extensiones necesarias sobre la bbdd y crear la tabla vector_store con un índice. Se puede hacer lo mismo de forma manual con:

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS hstore;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE IF NOT EXISTS vector_store (
    id uuid DEFAULT uuid_generate_v4() PRIMARY KEY,
    content text,
    metadata json,
    embedding vector(1536) // 1536 is the default embedding dimension
);

CREATE INDEX ON vector_store USING HNSW (embedding vector_cosine_ops);

Configuración

Empezamos por incluir la dependencia correspondiente:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
</dependency>

La implementación de vector store puede inicializar el schema automáticamente, pero se debe indicar el initializeSchema en el constructor correspondiente o mediante la propiedad …​initialize-schema=true.

Evidentemente, también será necesario un EmbeddingModel, debiendo incluir su correspondiente dependencia en el proyecto. Y, como en muchas ocasiones, también habrá que indicar los valores para la conexión a través de properties:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/postgres
    username: postgres
    password: postgres
  ai:
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1024
        max-document-batch-size: 10000
        initialize-schema: true

Además, existen otras properties para mayor personalización de la Vector Store. Recordemos que tal y como nos tiene acostumbrados Spring, también se puede crear una configuración manual.

Ejecución local

Se puede ejecutar una instancia de PGVector a través del siguiente comando Docker:

docker run -it --rm --name postgres -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres pgvector/pgvector:pg16

Y conectándose a la instancia con el comando:

psql -U postgres -h localhost -p 5432

Ejemplos de uso

Como es de esperar, se debe seleccionar un modelo embedding en conjunción con el modelo general empleado. Un ejemplo de carga de Documents en la Vector Store (esta operación de carga realmente se ejecutaría de forma batch) sería:

Document document1 = new Document("Tendencia tecnologica 2025: La voz y los vídeos en la IA", Map.of("tendencia", "ia"));
...
List<Document> documents = Arrays.asList(document1, document2, document3, document4, document5, document6, document7, document8, document9, document10);
vectorStore.add(documents);

Más tarde, cuando un usuario envíe una pregunta, se realizará una búsqueda por similitud para obtener documentos similares que se pasarán como contexto del prompt.

List<Document> similarDocuments = vectorStore.similaritySearch("Dime las tendencias tecnologicas actuales");

Eliminar documentos

Se proporcionan múltiples métodos para eliminar documentos:

• Borrado por IDs: como su nombre indica, se borran los documentos que concuerden con los IDs indicados, ignorando los no encontrados.
• Borrado por Filter.Expression: mediante un objeto Filter.Expression se indican los criterios de los documentos para ser borrados, siendo especialmente útil para eliminar documentos según sus metadatos:

Filter.Expression filterExpression = new Filter.Expression(Filter.ExpressionType.EQ, new Filter.Key("tendencia"), new Filter.Value("dragdrop"));
vectorStore.delete(filterExpression);

FilterExpressionBuilder builder = new FilterExpressionBuilder();
Expression expression = builder.eq("tendencia", "cloud").build();

try {
    vectorStore.delete(filterExpression);
    vectorStore.delete(expression);
} catch (Exception e) {
    log.error("Invalid filter expression", e);
}

Nota: según la documentación, se recomienda envolver estas llamadas de delete en bloques try-catch.

• Borrado por String Filter Expression: en este caso, se transformaría el String a una Filter.Expression.

Además, también hay que tener en cuenta las siguientes consideraciones en cuanto a rendimiento:

• Borrar por IDs es más rápido cuando se sabe exactamente qué Documents hay que borrar.
• El borrado basado en filtros puede requerir escanear el índice para encontrar los Documents a borrar.
• El borrado de muchos Documents se debería ejecutar en operaciones batch.
• Considerar el borrado de Documents basado en filtrados en vez de obtener previamente los IDs correspondientes.

Demo

Para ver en acción los componentes que hemos visto en este post, creamos una app. Una vez iniciamos la aplicación con la propiedad …initialize-schema: true se puede ver cómo se ha creado la tabla vector_store con un cliente de base de datos:

Para comprobar la funcionalidad contamos con los siguientes endpoints:

• /embedding/plain: endpoint que devuelve los embeddings generados a partir de unos textos. El embeddingModel se ha creado manualmente.

• /embedding/auto: endpoint similar al anterior que devuelve los embeddings generados a partir de unos textos. En este caso, el embeddingModel se ha inyectado a través de Spring.
• /vector-store/load: endpoint de carga de Documents en la Vector Store. Se pueden ver los datos cargados con un cliente de bbdd:

• /vector-store/similar-search: endpoint para realizar una búsqueda por similitud sobre los Documents cargados en el endpoint anterior. Para asegurar que solo se devuelven estos documentos, es importante tener en la bbdd solo los datos cargados en el endpoint anterior, puesto que como el modelo no es muy fiable, se pueden mezclar otros documentos en la respuesta:

• /vector-store/delete-filtered: endpoint que borra dos Documents y devuelve los restantes con una búsqueda por similitud. También se puede comprobar con un cliente de bbdd al que se han borrado los documentos correspondientes. Igualmente, se debe intentar solo tener los documentos correspondientes en la bbdd a la hora de a lanzar esta petición:

• /rag/load-data: endpoint con el que cargamos los datos del pdf en la vector store. En este caso, es un pdf sobre los aranceles de EEUU en el año 2025 teniendo en cuenta que el modelo tiene una cutoff date de marzo del año 2023.

• /rag/no-rag: endpoint para consultar datos de los aranceles de EEUU del 2025 sin consultar los embeddings. Se puede ver que no tiene información concreta sobre lo que le preguntamos:

• /rag/rag: endpoint para realizar la consulta anterior aplicando el QuestionAnswerAdvisor con los embeddings incluidos en el contexto, devolviendo información con alusiones al documento original:

En este enlace se puede descargar el código de la aplicación de ejemplo.

Conclusión

En esta ocasión hemos visto en qué consiste y cómo se implementa el patrón RAG en Spring AI, además de las funcionalidades que lo soporta (embeddings y las bbdd vectoriales), así como los ejemplos de las implementaciones correspondientes (Ollama y PGVector).

En el siguiente capítulo abordaremos la parte offline del patrón RAG (fase ETL) además de centrarnos en el auge de MCP y cómo lo resuelve Spring AI. ¡Te leo en comentarios!

Referencias

• Documentación de SpringAI
• Tutoriales de Dan Vega