# Spring AI Alibaba Examples

## 项目概述
本仓库是 Spring AI Alibaba 官方提供的示例集合，使用 Java 语言编写，基于 Apache-2.0 许可证。仓库内包含多个独立模块，系统性地演示了 Spring AI 和 Spring AI Alibaba 从基础到高级的用法，以及构建 AI 项目的最佳实践。

## 核心功能
- 提供多种示例模块，覆盖基本聊天、图像生成、函数调用（Tool Calling）、RAG 检索增强生成、MCP 模型上下文协议等能力。
- 支持多种模型提供商，如 DashScope、OpenAI、DeepSeek、MiniMax、智谱等。
- 提供快速启动矩阵，方便开发者快速选择合适的示例并运行。
- 每个子项目包含独立的 README，详细介绍其用途与配置。

## 适用与不适用场景
**适用场景：**
- Java 开发者希望快速上手 Spring AI Alibaba 的集成方式。
- 需要使用 DashScope、OpenAI 等模型服务构建聊天、图像生成、RAG 等应用。
- 学习和参考官方推荐的项目结构与最佳实践。

**不适用场景：**
- 非 Java 技术栈（如 Python、Node.js）的项目。
- 不涉及 Spring Boot 或无法使用 Maven 构建的环境。
- 期望获得生产级部署配置的完整解决方案（本仓库仅为示例）。

## 技术架构与依赖
- 开发语言：Java
- 构建工具：Maven
- 核心依赖：Spring Boot、Spring AI、Spring AI Alibaba
- 可选外部服务：DashScope、OpenAI、DeepSeek 等模型 API，以及向量数据库、MCP 工具等。

## 安装与快速开始
1. 克隆仓库：
   ```bash
   git clone https://github.com/spring-ai-alibaba/examples.git
   cd examples
   ```
2. 设置必要的环境变量（如 `AI_DASHSCOPE_API_KEY`）。
3. 按需运行模块，例如：
   ```bash
   mvn -pl spring-ai-alibaba-helloworld spring-boot:run
   ```
   更多模块和命令参见 README 中的 "Quickstart Matrix"。

## 典型使用方法
- 运行基础聊天示例：`mvn -pl spring-ai-alibaba-helloworld spring-boot:run`
- 运行 DashScope 聊天示例：`mvn -pl spring-ai-alibaba-chat-example/dashscope-chat spring-boot:run`
- 运行图像生成示例：`mvn -pl spring-ai-alibaba-image-example/dashscope-image spring-boot:run`
- 运行 RAG 示例：`mvn -pl spring-ai-alibaba-rag-example spring-boot:run`
- 运行工具调用示例：`mvn -pl spring-ai-alibaba-tool-calling-example spring-boot:run`

## 配置与部署要点
- 必须配置模型 API 密钥，常用环境变量包括 `AI_DASHSCOPE_API_KEY`、`OPENAI_API_KEY`、`AI_DEEPSEEK_API_KEY` 等。
- 部分模块（如 RAG、MCP）需要预启动本地依赖服务（如向量数据库、MCP 服务器）。
- 若遇到端口冲突，可修改模块内 `application.yml` 中的 `server.port`。
- 具体配置请参考各子模块的 README 和 `.env.example` 文件。

## 限制、风险与许可证
- 本仓库仅提供示例，不保证生产环境下的完整性与安全性。
- 依赖外部 AI 服务的 API，使用前需自行申请并承担相应费用。
- 仓库许可证为 Apache-2.0，使用时请遵守相应条款。
- 部分示例模块可能需要额外的本地服务或中间件，运行前需确认环境就绪。

## 官方链接
- 仓库地址：https://github.com/spring-ai-alibaba/examples
- Spring AI Alibaba 主仓库：https://github.com/alibaba/spring-ai-alibaba
- 官方网站：https://java2ai.com
- 网站源码：https://github.com/springaialibaba/spring-ai-alibaba-website

## 信息来源和分析时间
- 信息来源：GitHub 仓库提供的 README 与元数据。
- 分析时间：2026-05-13