# springAiProject

**Repository Path**: oxtop/springAiProject

## Basic Information

- **Project Name**: springAiProject
- **Description**: Spring Ai 学习 阿里巴巴AI大模型学习
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-06-05
- **Last Updated**: 2025-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# springAiProject

一个基于 Spring Boot 与 Spring AI 的多模块学习与实践项目，用于系统掌握大模型在 Java 生态的常见接入方式与应用模式：基础对话、函数调用（Tool Calling）、RAG 检索增强、本地模型（Ollama）、阿里云百炼/通义，以及图片/音频等多模态能力。

### 目录结构（模块总览）

- `springai_hello`：入门与最小可用示例
- `springai_chat`：对话与多轮会话，模型参数演示
- `springai_function`：函数调用（工具调用）与结构化输出
- `springai_all`：综合示例与统一入口（含简单 RAG 整合）
- `springai_rag`：检索增强生成（向量化/检索/生成）
- `springai_ollama`：本地 Ollama 模型调用
- `springai_alibaba`：阿里云百炼/通义平台对接
- `springai_other`：图片/音频等其他模型能力

提示：各模块下的 `controller` 和 `config` 可快速定位接口与配置；`target/` 为构建产物，已在 `.gitignore` 忽略。

### 环境与准备

- JDK 17（或兼容版本）
- Maven 3.8+（项目根目录统一构建）
- Spring Boot + Spring AI（按模块 `pom.xml` 管理）
- 可选：本地 Ollama（如需跑本地模型）
- 可选：阿里云百炼/通义平台 API Key（如需在线模型）

常用配置示例（按需放入各模块 `application.properties`/`application.yml`）：

```properties
# OpenAI/兼容类（示例）
spring.ai.openai.api-key=YOUR_OPENAI_OR_COMPATIBLE_KEY

# Ollama（本地）
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.model=llama3

# 阿里云百炼/通义（DashScope）
spring.ai.dashscope.api-key=YOUR_ALIBABA_DASHSCOPE_API_KEY
```

### 快速开始

1) 在项目根目录构建：

```bash
mvn -U -T 1C clean package -DskipTests
```

2) 进入目标模块运行（以 `springai_chat` 为例）：

```bash
cd springai_chat
mvn spring-boot:run
# 或
java -jar target/springai_chat-*.jar
```

3) 浏览器或 `curl` 调用模块接口，详见下方“各模块快速使用”。

---

## 模块知识总结与快速使用

### 1) `springai_hello`（入门示例）

- 功能：以最小代码展示如何通过 Spring AI 调用基础模型（简单问答）。
- 技术要点：Spring Boot、Spring AI Starter、`@RestController`、`ChatClient/ChatModel` 基本用法。
- 快速使用：启动后访问如 `GET /hello` 或存在的 `GET /deepseek/hello`（以实际 `controller` 为准），传 `q` 参数得到回复。

### 2) `springai_chat`（对话与参数演示）

- 功能：单轮/多轮对话；演示不同提供方与模型参数（温度、最大 Token、system 指令等）。
- 技术要点：Spring AI `ChatClient`、`Prompt`/`Message`、流式输出（可选）。
- 快速使用：`POST /chat` 或 `POST /chat/stream`（以 `ChatController`/`ChatAiController`/`ChatModelController` 实际映射为准），请求包含 `prompt`/`messages`，可带 `model`、`temperature`。

### 3) `springai_function`（函数调用 / Tool Calling）

- 功能：让模型按需调用后端函数（如 `CalculatorService` 的 `AddOperation`、`MulOperation`），并返回结构化结果。
- 技术要点：Spring AI Function/Tool-Calling、`@Bean` 暴露工具、强类型入参出参映射、`FunctionController` 调用链。
- 快速使用：`POST /function/call`，输入“计算 3×7+2”等自然语言任务，查看函数调用轨迹与最终计算结果。

### 4) `springai_all`（综合入口）

- 功能：统一出口聚合聊天、函数调用、（简单）RAG 等能力，便于一处对比与演示。
- 技术要点：统一 `ChatClient` 封装、可插拔工具与 RAG 组件、配置切换。
- 快速使用：`POST /all/chat`、`POST /all/ask`，可在请求中指定提供方/模型或开关 RAG。

### 5) `springai_rag`（检索增强生成）

- 功能：对文档进行分块与向量化，写入向量库；查询时先检索相关片段再给模型生成，提升可控性与依据。
- 技术要点：分块（Chunking）、Embedding 生成、`VectorStore`/`Retriever`、`RagConfig`、Prompt 模板化。
- 快速使用：先调用如 `POST /rag/ingest` 导入文档，再 `POST /rag/ask` 提问，响应包含引用片段（参考 `RagController`）。

### 6) `springai_ollama`（本地模型）

- 功能：连接本地 Ollama（默认 `http://localhost:11434`）调用如 `llama3`、`qwen` 等模型。
- 技术要点：Ollama 服务、Spring AI Ollama 客户端、流式/非流式响应。
- 快速使用：`ollama pull llama3` 后，配置 `spring.ai.ollama.*`，启动模块，访问如 `POST /ollama/chat`（见 `OllamaController`）。

### 7) `springai_alibaba`（阿里云百炼/通义）

- 功能：通过百炼平台调用通义等模型完成对话/补全/多模态（按接口支持）。
- 技术要点：DashScope OpenAPI、鉴权 `spring.ai.dashscope.api-key`、模型与参数选择。
- 快速使用：配置 API Key 后启动，访问如 `POST /alibaba/chat`（见 `AlibabaController`），请求体传入 `prompt/messages`。

### 8) `springai_other`（图片/音频等）

- 功能：图片生成/解析、音频转写/合成等演示能力。
- 技术要点：Spring AI `ImageModel`、`AudioModel` 抽象；`ImageModelController`、`AudioModelController`。
- 快速使用：
  - `POST /image/generate`：描述词、尺寸等参数 → 返回图片链接/Base64；
  - `POST /audio/transcribe`：上传音频文件 → 返回转写文本；
  - 具体参数以各 `controller` 为准。

---

## 常见问题（FAQ）

- 端口冲突：模块并行运行可能冲突，修改 `server.port` 或单独运行。
- 鉴权失败：确认 API Key/网络可达性与区域/模型名正确。
- 本地模型不可用：需先 `ollama pull <model>` 并确保服务运行。
- RAG 效果一般：调节分块大小/相似度/检索条数，优化 Prompt 与上下文拼接，核验向量库写入与召回。

## 建议

- 每个模块可补充独立 `README.md`，记录接口样例与截图。
- 将常用请求样例（cURL/Postman）放入仓库，便于复现与演示。