Content
<p align="left">
<a href="README.md" target="_blank"><img src="https://img.shields.io/badge/lang-中文-red?logo=googletranslate" alt="中文" style="vertical-align:middle; margin-right:4px;"/></a>
<a href="README_EN.md" target="_blank"><img src="https://img.shields.io/badge/lang-English-blue?logo=googletranslate" alt="English" style="vertical-align:middle; margin-right:4px;"/></a>
<a href="https://github.com/java-ai-tech/spring-ai-summary/wiki" target="_blank"><img src="https://img.shields.io/badge/doc-wiki-blue?logo=readthedocs" alt="document" style="vertical-align:middle; margin-right:4px;"/></a>
<img src="https://img.shields.io/badge/spring--ai--summary-v1.0.0-blue.svg" alt="Spring AI Summary" style="vertical-align:middle; margin-right:4px;"/>
<img src="https://visitor-badge.laobi.icu/badge?page_id=java-ai-tech.spring-ai-summary" alt="Visitors" style="vertical-align:middle; margin-right:4px;"/>
</p>
**Spring AI Summary** is a modular example project collection based on the native **Spring AI** framework. It helps developers quickly grasp the core functionalities of Spring AI through clear code examples and detailed documentation.
### 👥 Target Audience
Spring AI Summary is aimed at developers interested in the Spring AI framework. Whether you are a beginner or an experienced engineer, this project allows you to quickly understand the core features of the framework and apply them to real projects. With Spring AI Summary, you can:
- Master the core concepts and functionalities of Spring AI.
- Learn how to build efficient AI applications.
- Stay updated with the latest technological trends and practical experiences.
**Join the Community** 🎯 Scan the QR code to add the group owner's WeChat (Note: Spring AI) and explore the infinite possibilities of Spring AI together!
<p align="center">
<img width="189" alt="Community Group Chat" src="docs/statics/my_chat.png" />
</p>
## 📖 Learning Path
If you are new to Spring AI, it is recommended to first read the [Spring AI Official Documentation](https://spring.io/projects/spring-ai) to understand the basic concepts and usage of the framework. You can then practice through the various modules of this project to gradually deepen your understanding of the core functionalities of the framework.
**Recommended Learning Order**:
1. 📚 [Spring AI Official Documentation](https://spring.io/projects/spring-ai) - Understand the basic concepts
2. 💬 **spring-ai-chat** - Chat application development (essential starting point)
3. 🔧 **spring-ai-tool-calling** - Tool calling capabilities
4. 🧠 **spring-ai-vector** - Vector database integration
5. 🚀 **MCP/RAG/AGENT** - Advanced application patterns
👇 Let's start your journey with Spring AI～
## 🚀 Quick Start
### ⚙️ Environment Requirements
| Dependency | Version/Requirement | Description |
|------------------|----------------------------|---------------------|
| SpringBoot | 3.3.6 | - |
| Spring AI | 1.0.0 | - |
| JDK | 21+ | - |
| Maven | 3.6+ | Strongly recommended to use mvnd instead of mvn |
| Docker | (for running Milvus, Nacos, etc.) | |
### 1. 🧬 Clone the Project
```bash
# Clone the project to your local machine
git clone https://github.com/java-ai-tech/spring-ai-summary.git
# Navigate to the project and compile
cd spring-ai-summary && mvn clean compile -DskipTests
```
> If you encounter slow Maven dependency downloads, you can try using domestic Maven mirror sources, such as Alibaba Cloud or Tsinghua University; if you have any other issues during the process, feel free to scan the QR code above to join the WeChat group for consultation and discussion.
### 2. 🛠️ Configure Environment Variables
For each module's resource folder, configure the corresponding API keys in the `application.yml`/`application.properties` files according to your needs. For example, in the **spring-ai-chat-deepseek** module:
```properties
# Example: deepseek module configuration
spring.ai.deepseek.api-key=${spring.ai.deepseek.api-key}
spring.ai.deepseek.base-url=https://api.deepseek.com
spring.ai.deepseek.chat.completions-path=/v1/chat/completions
spring.ai.deepseek.chat.options.model=deepseek-chat
```
Replace your `spring.ai.deepseek.api-key` with the actual API key to start running. For information on how to apply for an API key, please refer to the project's [Wiki page](https://github.com/java-ai-tech/spring-ai-summary/wiki).
> 💡 **Security Tip**: Use environment variables to store API keys to avoid code exposure. [Key Application Guide](https://github.com/java-ai-tech/spring-ai-summary/wiki)
### 3. ▶️ Run the Example
After completing the above steps, you can choose to run different example modules to experience the functionalities of Spring AI. For instance, to start the **spring-ai-chat-deepseek** module (specific ports can be configured according to your setup):
```bash
2025-06-04T14:18:43.939+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] c.g.ai.chat.deepseek.DsChatApplication : Starting DsChatApplication using Java 21.0.2 with PID 88446 (/Users/glmapper/Documents/projects/glmapper/spring-ai-summary/spring-ai-chat/spring-ai-chat-deepseek/target/classes started by glmapper in /Users/glmapper/Documents/projects/glmapper/spring-ai-summary)
2025-06-04T14:18:43.941+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] c.g.ai.chat.deepseek.DsChatApplication : The following 1 profile is active: "deepseek"
2025-06-04T14:18:44.469+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port 8081 (http)
2025-06-04T14:18:44.475+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat]
2025-06-04T14:18:44.476+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] o.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/10.1.33]
2025-06-04T14:18:44.501+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
2025-06-04T14:18:44.502+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 533 ms
2025-06-04T14:18:44.962+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] o.s.b.a.e.web.EndpointLinksResolver : Exposing 14 endpoints beneath base path '/actuator'
2025-06-04T14:18:44.988+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port 8081 (http) with context path '/'
2025-06-04T14:18:44.997+08:00 INFO 88446 --- [spring-ai-chat-deepseek] [ main] c.g.ai.chat.deepseek.DsChatApplication : Started DsChatApplication in 1.215 seconds (process running for 1.637)
2025-06-04T14:18:45.175+08:00 INFO 88446 --- [on(2)-127.0.0.1] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring DispatcherServlet 'dispatcherServlet'
2025-06-04T14:18:45.175+08:00 INFO 88446 --- [on(2)-127.0.0.1] o.s.web.servlet.DispatcherServlet : Initializing Servlet 'dispatcherServlet'
2025-06-04T14:18:45.176+08:00 INFO 88446 --- [on(2)-127.0.0.1] o.s.web.servlet.DispatcherServlet : Completed initialization in 1 ms
```
If you see logs similar to the above, congratulations, the startup was successful 🎉🎉🎉🎉🎉.... You have opened the door to Spring AI, and you can now start exploring various functional modules. After startup, you can test using tools like cUrl, HTTPie, or Postman.
```bash
curl localhost:8081/api/deepseek/chatWithMetric?userInput="Who are you?"
```
The result is as follows:
**Success Indicator** 🎉: Seeing a response like this indicates a successful run!
```bash
# completion tokens
http://localhost:8081/actuator/metrics/ai.completion.tokens
# prompt tokens
http://localhost:8081/actuator/metrics/ai.prompt.tokens
# total tokens
http://localhost:8081/actuator/metrics/ai.total.tokens
```
Taking `ai.completion.tokens` as an example, the result is as follows:
```json
{
"name": "ai.completion.tokens",
"measurements": [
{
"statistic": "COUNT",
"value": 34
}
],
"availableTags": []
}
```
**For usage methods and configurations of other modules, please refer to the [Wiki page](https://github.com/java-ai-tech/spring-ai-summary/wiki) or the `README.md` files of each module.**
## 📚 Learning Resources (Continuously Updated)
Here are some recommended learning resources:
> The official community also has a [collection of learning resources](https://github.com/spring-ai-community/awesome-spring-ai), but it mainly aggregates foreign materials. This project focuses more on gathering domestic learning resources for reference.
#### Technical Community
- [Spring AI Official Documentation](https://spring.io/projects/spring-ai)
- [Spring AI Alibaba Official Documentation](https://github.com/alibaba/spring-ai-alibaba)
#### Project Series
- [MindMark is a RAG system based on SpringAI](https://gitee.com/mumu-osc/mind-mark)
- [My AI Agent is an intelligent agent service built on Spring Boot and Spring AI framework](https://github.com/Cunninger/my-ai-agent)
#### Blog Series
- [Coder's Diary -- Spring AI Series Column](https://cloud.tencent.com/developer/column/72423) The author has not managed the column, so it links to the homepage; this series of articles is great for learning some design ideas and implementation methods of Spring AI, but it is written based on the M series version, so some content may not be consistent with the latest version.
- [In-depth Analysis of Spring AI Series](https://www.cnblogs.com/guoxiaoyu/p/18666904)
- [How to Build MCP Client-Server Architecture with Spring AI](https://spring.didispace.com/article/spring-ai-mcp.html)
- [Building Effective Agents with Spring AI](https://spring.io/blog/2025/01/21/spring-ai-agentic-patterns) 🌟🌟🌟🌟🌟
- [Source Code Analysis and Simple Usage of Spring AI Large Model Return Content Formatting](https://juejin.cn/post/7378696051082199080)
- [Concept and Source Code Analysis of Spring AI EmbeddingModel](https://my.oschina.net/u/2391658/blog/18534829)
- [Full RAG Technology: A Simpler and More Practical Implementation Method ✨](https://www.readme-i18n.com/FareedKhan-dev/all-rag-techniques?lang=zh)
- [Principles and Practice of Spring AI Framework](https://juejin.cn/column/7375109287716372520) 🌟🌟🌟
- Popular Science on Large Model Technology
- [LLM Series (1): Development History](https://mp.weixin.qq.com/s/72omFtMqinJs4MMX41MCyw)
- [LLM Series (2): Basic Concepts](https://mp.weixin.qq.com/s/Fg0bczAxejgKs_65kWxWSg)
- [LLM Series (3): Architectural Patterns](https://mp.weixin.qq.com/s/d6Y76I_Vxfmj6wa5sAN3uQ)
- [LLM Series (4): Magical Numbers](https://mp.weixin.qq.com/s/tEozMs4QWDYx5vrhitA9uQ)
- [LLM Series (5): Model Training](https://mp.weixin.qq.com/s/TK8rTcrjS1pfigQxj2mq8A)
- [LLM Series (6): Model Inference](https://mp.weixin.qq.com/s/tjXme2CWnUxLmawDDiylWQ)
#### Video Series
- [How to Build Agents with Spring AI](https://www.youtube.com/watch?v=d7m6nJxfi0g)
- [Spring AI Video Tutorial Series](https://www.youtube.com/watch?v=yyvjT0v3lpY&list=PLZV0a2jwt22uoDm3LNDFvN6i2cAVU_HTH)
- [Mark's Technical Workshop](https://space.bilibili.com/1815948385) 🌟🌟🌟🌟🌟
If you have good articles or resources, feel free to submit a PR or Issue for supplementation and improvement. Below are the development and contribution guidelines.
## 🔧 Development Guidelines (Code, Documentation)
First of all, we warmly welcome any form of contributions, including but not limited to **code, documentation, tests, code comments**, etc. However, please follow the process below before submitting contributions:
### Contributing Code
1. **Fork the Project**
As shown in the image below, fork the repository to your personal repository.
2. **Clone Your Personal Repository Code**
```bash
# Fork the project on GitHub
# Clone your forked repository
git clone https://github.com/your-username/spring-ai-summary.git
cd spring-ai-summary
```
3. **Create a Feature Branch**
```bash
# Create and switch to a new feature branch
git checkout -b feature/your-feature-name
```
4. **Development Specifications**
- Follow the project's code style and naming conventions
- Ensure the code passes all tests (if any)
- Update relevant documentation
5. **Submit Code**
```bash
# Add modified files
git add .
# Commit code
git commit -m "feat: add new feature"
# Push to your forked repository
git push origin feature/your-feature-name
```
6. **Create a Pull Request**
- Create a Pull Request on GitHub
- Fill in the PR description, explaining the changes and reasons
- Wait for code review and merging
## 📝 Notes
1. **API Key Security**
- It is recommended to use environment variables to store API keys to avoid exposure risks
- Never hard-code keys in the code repository
- Regularly rotate keys to enhance security
2. **Token Usage**
- Continuously monitor token consumption to avoid exceeding limits
- Set reasonable token restrictions to prevent abuse
- It is recommended to implement caching mechanisms to improve response speed and cost control
## 📄 License & Disclaimer
* 1. This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. Additionally, this project is for learning and research purposes only and is not suitable for production environments. Please do not use the sample project directly in production. When using, please comply with the relevant terms and conditions of the models.
* 2. All code and documentation in this project are independently developed and maintained by [glmapper](https://github.com/glmapper). Feedback and suggestions are welcome. If this project has been helpful to you, please give it a star for support! If you have any questions or suggestions, please submit an Issue or PR on GitHub, or contact me [here](http://www.glmapper.com/about). I will also further publish related technical articles on **Spring AI** in this repository and my personal WeChat public account: **Uncle Lei's Technical Blog**, and you are welcome to scan and follow.
<p align="center">
<img src="docs/statics/wx-gzh.png" alt="WeChat Public Account" width="200"/>
</p>
## 🙏 Acknowledgments
- [Spring AI](https://github.com/spring-projects/spring-ai) - Provides a powerful AI integration framework
- [OpenAI](https://openai.com) - Provides the GPT series models
- [Tongyi Qianwen](https://qianwen.aliyun.com) - Provides the Qwen series models
- [Doubao](https://www.volcengine.com/docs/82379) - Provides the Doubao series models
- [Milvus](https://milvus.io) - Provides vector database support
This project is a fully open-source project aimed at gathering more high-quality learning resources related to Spring AI. Of course, **the related learning resources mainly come from the internet; if there is any infringement, please contact for removal!!!** I would also like to express my heartfelt thanks to all those who contribute to open source and share technology in the technical community!
## Star History
[](https://www.star-history.com/#java-ai-tech/spring-ai-summary&Date)
