dive-into-spring-ai: A Hands-On Spring AI Tutorial with RAG, Agents, and Graph RAG

What dive-into-spring-ai Teaches and Who It Is For

dive-into-spring-ai is a teaching repository, not a library or a production application. Its purpose is to provide working Java code for each major Spring AI capability so that developers can study the implementation, not just read the API reference. The target reader is a Java engineer who knows Spring Boot and wants to move from reading the Spring AI documentation to seeing actual service classes, configuration files, and frontend code working together.

The repository title translates roughly as 'Hands-On Spring AI', and the scope reflects that. It covers SSE streaming for real-time token output, Agent-based orchestration, function calling, history message handling, image generation, image understanding, embedding, vector database integration, RAG, and Graph RAG using Neo4j. Each of these is a distinct Spring AI subsystem, and the repository provides a runnable example for each one.

Infrastructure Dependencies and Why They Matter

Running any part of this project requires a specific set of services. The README lists Java 17, Node.js 18 or later, MySQL 8, Redis-Stack (Redis extended with vector query support), and Neo4j 5 or later. The Redis-Stack requirement is not optional: standard Redis does not support the vector similarity operations that the embedding and RAG examples use.

The README provides Docker commands for both services. To start Redis-Stack:

docker run -d \
--name redis-stack \
--restart=always \
-v redis-data:/data \
-p 6379:6379 \
-p 8001:8001 \
-e REDIS_ARGS="--requirepass 123456" redis/redis-stack:latest

For Neo4j:

docker run \
-d \
-p 7474:7474 -p 7687:7687 \
-v neo4j-data:/data -v neo4j-data:/plugins \
--name neo4j \
-e NEO4J_apoc_export_file_enabled=true \
-e NEO4J_apoc_import_file_enabled=true \
-e NEO4J_apoc_import_file_use__neo4j__config=true \
-e NEO4JLABS_PLUGINS=["apoc"] \
-e NEO4J_dbms_security_procedures_unrestricted=apoc.\* \
neo4j

Neo4j is accessed at localhost:7474 after startup, with default credentials neo4j and neo4j. These containers need to be running before the Spring Boot backend starts.

Cloning, Configuring, and Running the Project

Clone the repository:

git clone https://github.com/qifan777/dive-into-spring-ai

Open the project in IntelliJ IDEA. Before running, edit application.yml to fill in the API key, MySQL connection string, Redis-Stack credentials, and Neo4j credentials. The README shows two configuration paths for the AI model. The default uses DashScope, which requires a DashScope API KEY. If you prefer an OpenAI-protocol-compatible model instead, configure the spring.ai.openai section with base-url pointing to your provider and api-key set to your key.

To start the backend, run ServerApplication.java. After the server starts, right-click target/generated-sources/annotations and mark it as a generated source root. Then switch to the front-end directory and run the frontend:

npm run install

Once the install completes, generate the API client from the running backend:

npm run api

Then start the development server:

npm run dev

The frontend is a Node.js application and requires the backend to be running before the npm run api step executes.

Graph RAG and What Makes It Different from Standard RAG

Most RAG examples store chunks in a vector database and retrieve them by embedding similarity. Graph RAG goes further by storing entities and relationships in a graph, which lets the retrieval step follow relationship paths rather than relying solely on vector proximity. dive-into-spring-ai includes a Graph RAG example built on Neo4j.

The choice of Neo4j as the graph store requires the APOC plugin, which is why the Docker command enables it via NEO4JLABS_PLUGINS. APOC provides the extended procedures Neo4j uses for certain graph traversal and import operations. Without it, the Graph RAG feature will not function correctly. The repository does not document fallback options if Neo4j is unavailable.

Limitations of This Tutorial Repository

This is a teaching codebase, not a production-ready application. The README does not document which Spring AI version is pinned in pom.xml, which means readers who import the project after a major Spring AI release may encounter API changes. The front-end code uses npm run api to generate a typed client from the running backend, which creates a tight coupling between the frontend and backend startup order.

The last push was on 2026-07-15. The project has no GitHub releases, so there is no mechanism to check out a historically known-good state. The README acknowledges that support for running or customizing the project is available via paid remote sessions or QQ group chat, which suggests the maintainer provides this as a tutorial resource rather than as a community-maintained framework.

Anyone who does not have access to a Chinese API provider should plan time to configure the OpenAI-protocol fallback before starting, since the default configuration references DashScope.

Comparison with LangChain4j Example Repositories

LangChain4j is the other widely used Java AI framework, and it has its own set of tutorial repositories. The key difference is the Spring integration model. dive-into-spring-ai is built entirely within Spring Boot conventions: configuration through application.yml, dependency injection through Spring beans, and frontend scaffolding through a standard Spring Boot project layout. Engineers who already work in Spring Boot will find the patterns familiar.

LangChain4j examples tend to be self-contained Java applications without a frontend layer. For engineers who want to see how the AI features connect to a full HTTP server with session management and a browser interface, dive-into-spring-ai provides a more complete picture. The trade-off is the infrastructure setup cost: MySQL, Redis-Stack, and Neo4j are all required even for the simpler examples.

License and Maintenance

The repository lists no license file in the top-level entries. Engineers who intend to use any of the code in a commercial product should verify the licensing situation directly with the repository maintainer before doing so.

The last push was on 2026-07-15, placing it roughly two months before this review. The project has no GitHub releases and no changelog. The homepage links to a documentation site at jarcheng.top and a video series on Bilibili, which may be more current than the repository itself for understanding recent changes.

Editorial conclusion

Engineers learning Spring AI who want runnable examples rather than conceptual documentation will get direct value from this repository. The setup cost is real: Java 17, Node.js 18, MySQL 8, a Redis-Stack container, a Neo4j container, and an API key are all required before a single feature can be tested. Anyone without a DashScope account should configure the OpenAI-protocol fallback at spring.ai.openai in application.yml before attempting to run. The last push was on 2026-07-15, which is within the past few months, so the dependencies are likely current but readers should check that the Spring AI version in pom.xml matches their intended use.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. qifan777/dive-into-spring-ai on GitHub
4. README