Spring AI Project - Demo

Este proyecto es una demostración de una aplicación construida con Spring Boot 4 y Spring AI 2.0, utilizando las últimas versiones disponibles a Enero de 2026.

🚀 Versiones Utilizadas

Este proyecto utiliza el stack tecnológico más reciente del ecosistema Spring:

• Java: 21 (LTS)
• Spring Boot: 4.0.1
• Spring AI: 2.0.0-M1 (Milestone 1)

Nota: Al utilizar una versión Milestone (M1), es necesario configurar repositorios adicionales de Spring (spring-milestones) en el pom.xml, ya que estas versiones no están en Maven Central estándar.

🛠️ Cómo crear este proyecto

Para recrear este proyecto desde cero, sigue estos pasos:

1. Generar el proyecto base: Puedes usar Spring Initializr o curl. Dado que Spring Boot 4 es muy reciente, generamos un proyecto web básico primero:

   curl -G https://start.spring.io/starter.zip \
       -d dependencies=web \
       -d type=maven-project \
       -d javaVersion=21 \
       -d bootVersion=3.4.1 \
       -o project.zip
   unzip project.zip

   (Nota: Si Spring Boot 4 no se puede seleccionar directamente, edita el pom.xml tras generar).

2. Configurar pom.xml:

   • Actualizar versión padre: Cambiar spring-boot-starter-parent a 4.0.1.
   • Añadir Repositorio Milestone:

     <repositories>
         <repository>
             <id>spring-milestones</id>
             <name>Spring Milestones</name>
             <url>https://repo.spring.io/milestone</url>
             <snapshots>
                 <enabled>false</enabled>
             </snapshots>
         </repository>
     </repositories>

   • Configurar BOM (Bill of Materials) de Spring AI:

     <dependencyManagement>
         <dependencies>
             <dependency>
                 <groupId>org.springframework.ai</groupId>
                 <artifactId>spring-ai-bom</artifactId>
                 <version>2.0.0-M1</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
         </dependencies>
     </dependencyManagement>

   • Añadir Dependencias:

     <dependency>
         <groupId>org.springframework.ai</groupId>
         <artifactId>spring-ai-starter-model-openai</artifactId>
     </dependency>

🌟 Capacidades de Spring AI (Actualizado 2026)

Spring AI ofrece una API portable y unificada para interactuar con diversos modelos de IA. Las capacidades actuales incluyen:

1. Modelos de IA (Model Client API)

• Chat Models: Interfaz unificada para OpenAI, Azure OpenAI, Amazon Bedrock, Google Vertex AI, Ollama, Anthropic Claude, etc.
• Image Generation: Generación de imágenes (DALL-E, Stability AI).
• Audio: Transcripción (Speech-to-Text) y Texto a Voz (Text-to-Speech) usando modelos como Whisper.
• Embeddings: Conversión de texto a vectores para búsqueda semántica.

2. RAG (Retrieval Augmented Generation)

• Vector Stores: Abstracción para bases de datos vectoriales. Actualmente soporta:
  • PGVector (PostgreSQL)
  • Redis
  • Neo4j
  • MongoDB Atlas
  • Chroma, Weaviate, Milvus, Qdrant, etc.
• Document Readers: Utilidades para leer PDFs, JSON, Texto, Markdown.
• Document Transformers: División de documentos (TokenTextSplitter) para indexación.

3. Herramientas Avanzadas

• Function Calling: Permite a los modelos de IA invocar funciones Java propias (ej. consultar tu base de datos o API externa) de forma transparente.
• Chat Memory: Gestión del historial de conversación para mantener el contexto.
• Evaluation: Framework para evaluar la calidad de las respuestas de la IA.

⚙️ Configuración

Para ejecutar este proyecto, necesitas configurar tu API Key (en este caso para OpenAI) en src/main/resources/application.properties:

spring.ai.openai.api-key=${OPENAI_API_KEY}

O exportarla como variable de entorno:

export SPRING_AI_OPENAI_API_KEY=tu-clave-aqui

📖 Guía de Aprendizaje y Filosofía del Proyecto

Este proyecto es una plantilla técnica diseñada para construir sistemas de producción robustos en Java desde el inicio. Es la opción recomendada cuando la integración empresarial, la escalabilidad y la mantenibilidad a largo plazo son requisitos críticos del caso de uso. A continuación, se resume la hoja de ruta para que desarrolladores se capaciten y comprendan las decisiones de diseño.

🏛️ Filosofía: Colaboración entre Ecosistemas

Este proyecto reconoce el valor inmenso de Python en ciencia de datos y entrenamiento de modelos (Heavy AI).

Aunque el ecosistema Java evoluciona rápidamente integrando capacidades avanzadas (como visión y multimodalidad), Python sigue siendo una herramienta excelente para exploración, entrenamiento y casos de uso "bleeding edge" donde las herramientas JVM aún puedan estar madurando.

Nuestro objetivo es ofrecer un estándar robusto para la IA empresarial, donde Java destaca por su integración con sistemas legacy, concurrencia masiva y tipado fuerte, complementando la agilidad creativa de otros ecosistemas.

Concepto	Enfoque Dinámico (Python)	Enfoque Empresarial (Java/Este Proyecto)
Prompting	F-strings (Rápido y flexible)	Templates versionados (Gobernable y escalable).
Salidas	Diccionarios dinámicos	Tipado Fuerte con Records (Seguridad en tiempo de compilación).
RAG	Ideal para experimentación rápida	ETL Robusto con Apache Tika y Bases de Datos Vectoriales gestionadas.
Agentes	Frameworks de alto nivel (AutoGen)	Patrones Composables (Control granular del flujo).
Orquestación	LangGraph (Potente para grafos)	Temporal.io / Spring State Machine (Resiliencia transaccional).

🎓 Ruta de Aprendizaje Recomendada (2026)

Para dominar el stack tecnológico de este proyecto, se recomienda la siguiente progresión de recursos educativos:

1. Fundamentos de Spring AI:

   • Curso: "Spring AI: Beginner to Guru" (John Thompson en Udemy).
   • Objetivo: Asentar bases de ChatClient, inyección de dependencias y conexión básica con LLMs.

2. Ingeniería de Datos y RAG:

   • Curso: "Mastering Spring AI: Build AI with Java" (Pritesh Mistry en Udemy).
   • Objetivo: Profundizar en ingestión de documentos, bases de datos vectoriales y transformación de consultas.

3. Arquitectura Avanzada e Interoperabilidad:

   • Curso: "Build AI Apps with Spring AI... MCP, AI Testing" (Madan Reddy en Udemy).
   • Objetivo: Aprender Model Context Protocol (MCP) para conectar herramientas y Testing automatizado de IA.

4. Teoría de Agentes:

   • Curso: "AI Agents in Java..." (Vanderbilt University en Coursera).
   • Objetivo: Comprender la arquitectura cognitiva de los agentes (Planificación, Memoria) más allá del código.

🤖 Asistente de GitHub Copilot

Este repositorio incluye instrucciones especializadas para el agente, ubicadas en .github/instructions/springai.instructions.md.

Estas pautas aseguran que cualquier código generado por la IA respete la arquitectura de referencia:

• Enfoque Java-Nativo: Preferencia por tipado fuerte (Records, POJOs) y conversión estructurada (BeanOutputConverter) frente a JSON crudo.
• Arquitectura Spring AI: Uso de ChatClient fluente, Advisors recursivos y abstracciones oficiales en lugar de ports directos de librerías de Python.
• Calidad de Ingeniería: Integración obligatoria de Testcontainers y Evaluators para pruebas robustas.

📚 Documentación Oficial

Para más detalles, consulta la documentación oficial, que se actualiza constantemente con nuevas integraciones:

• Documentación de Referencia de Spring AI
• Repositorio de GitHub
• Spring AI Alibaba GitHub (Graph Core)

🌊 Patrones Asíncronos con Spring AI Alibaba Graph

Esta demostración implementa patrones de ejecución de grafos asíncronos inspirados en LangGraph, utilizando la librería spring-ai-alibaba-graph-core.

Dependencia

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-graph-core</artifactId>
    <version>1.1.0.0</version>
</dependency>

1. Escenario 1: Fan-out / Fan-in (Paralelismo)

Ejecución en paralelo de ramas independientes que convergen en un nodo de sincronización.

• Merge Pattern: El nodo D fusiona los resultados parciales de B y C para evitar condiciones de carrera.

graph LR
    Start((Start)) --> A[Node A]
    A --> B[Node B]
    A --> C[Node C]
    B --> D["Node D (Merge)"]
    C --> D
    D --> End((End))
    style B fill:#e1f5fe
    style C fill:#e1f5fe
    style D fill:#fff9c4

Loading

2. Escenario 2: Modificación de Topología (Cadenas Paralelas)

Simulación de ramas con diferente "profundidad".

• Debido a restricciones de la versión actual para bloques paralelos, se utiliza el patrón Node Collapsing: La cadena B -> B2 se encapsula en un único nodo lógico B_Chain para mantener la simetría del grafo paralelo.

graph LR
    Start((Start)) --> A[Node A]
    A --> B_Chain["Node B_Chain (B+B2)"]
    A --> C[Node C]
    B_Chain --> D["Node D (Merge)"]
    C --> D
    D --> End((End))
    style B_Chain fill:#e1f5fe,stroke-dasharray: 5 5

Loading

3. Escenario 3: Enrutamiento Condicional (Conditional Branching)

Decisión dinámica del camino de ejecución basada en el estado del grafo.

• Un Conditional Edge evalúa la salida de A y decide activar el router "BC" o "CD".

graph LR
    Start((Start)) --> A[Node A]
    A -- "Choice: 'RouterBC'" --> RBC{"Router BC"}
    A -- "Choice: 'RouterCD'" --> RCD{"Router CD"}
    
    RBC --> B[Node B]
    RBC --> C[Node C]
    
    RCD --> C[Node C]
    RCD --> D[Node D]
    
    B --> E["Node E (Merge)"]
    C --> E
    D --> E
    E --> End((End))
    
    style RBC fill:#ffccbc
    style RCD fill:#ffccbc

Loading

Referencias

• Spring AI Alibaba GitHub - Repositorio oficial del proyecto Graph.