一、前言

        前段时间写了一些调用 通义千问各个模型 and 豆包大模型 的一些文章，接下来我将把整个项目分享出来，有什么问题的同学都可以在评论区或者私信给我。我也将项目开源了，有想要一起完善调用示例代码的同学可以来私聊我聊一聊。

        仓库地址：雾里小笔/mandirAi - Gitee.com

        接下来我简单的讲解一下我的项目结构。

二、项目结构

1.提交历史

📊 整体概览

        整个就是一个 AI 多模态应用的提交历史，时间从下往上推进（最下面是最早的 V1.0，最上面是最新的提交）。整个项目的演进可以分成 5 个阶段，每一步都在扩展能力边界。

---

🚀 阶段 1：V1.0 基础能力搭建（底层对话与工具）

• 起点：V1.0 单智能体 → 项目初始，实现最基础的单轮对话能力。
• 核心升级：
  • V1.1 多轮问答 → 支持上下文关联，让对话更连贯。
  • V1.2 上下文缓存 → 优化多轮对话的性能和体验。
  • V1.3 Function Calling → 引入工具调用能力，让 AI 能执行外部函数。
  • V1.4 java代码编译器 + V1.4 高德地图MCP → 扩展工具生态，支持代码编译和地图服务。
• 目标：把智能体的「基础交互 + 工具调用」能力打扎实，为后续扩展铺路。

---

🎨 阶段 2：V2.0~V3 视觉能力突破

• 核心升级：
  • V2.0 视觉理解 → 首次引入视觉能力，让 AI 能看懂图片。
  • V2.0.1/V2.0.2 → 优化视觉输入方式，支持 Base64 和本地路径的图片文件。
  • V3 视觉推理 → 从 “看懂图片” 升级到 “理解图片中的逻辑”，比如分析图表、识别物体关系。
• 目标：让项目从「纯文本对话」迈向「多模态交互」，视觉能力成为新的核心竞争力。

---

🖥️ 阶段 3：V4.0 界面交互与体验优化

• 核心升级：
  • V4.0 界面交互 → 把之前的能力封装成可视化界面，让用户能直接操作。
  • V4.0 文字提取 → 支持从图片 / 文档中提取文字，丰富交互场景。
  • V4.1/V4.2 → 优化界面交互细节，比如本地图片输出优化、定位功能、机器人交互适配。
• 目标：让项目从「后台能力」走向「可落地的前端产品」，提升用户体验。

---

🎭 阶段 4：V5.0~V7.0 多模态全面扩展

• 核心升级：
  • V5.0 音频识别 → 加入语音转文字能力。
  • V6.0 视频生成 → 扩展到视频模态，支持 AI 生成视频。
  • V7.0 Owen-MT翻译 → 引入机器翻译能力，支持多语言场景。
• 目标：打造「文本 + 视觉 + 音频 + 视频 + 翻译」的全模态 AI 系统，覆盖更多业务场景。

---

🛠️ 阶段 5：后期优化与工程化

• 核心动作：
  • fix 0001 → 修复功能 Bug，提升稳定性。
  • Merge remote-tracking branch 'origin/master' → 分支合并，规范开发流程。
  • add README.md + add LICENSE → 完善项目文档，开源合规。
  • 语音合成 / 复刻迭代 + 图片生成 → 持续优化现有能力，补充新模态。
• 目标：让项目更稳定、更规范，具备长期维护和开源的基础。

        以上基本都是调用的 通义千问大模型 系列的各个模型，在，也有我自己搞的一些 agent 具体的操作步骤大家可以在 AI_独自归家的兔的博客-CSDN博客 专栏中查看到具体的操作步骤。

2、项目框架

        下面是我的项目框架，Springboot2

---

📂 根目录核心文件 / 文件夹

Maven 工程结构，这些文件是项目工程化的基础：

名称	作用
.idea	IntelliJ IDEA 的专属配置目录，存储编辑器的个性化设置，无需关注。
.mvn	Maven Wrapper 的配置目录，保证不同开发环境使用统一的 Maven 版本。
src	项目源码的主目录，所有业务代码和资源文件都在这里。
target	Maven 编译、打包后的输出目录，包含编译后的 class 文件、可执行 Jar 包等。
.gitattributes	Git 的属性配置文件，用于统一不同平台的文件换行符、编码等规则。
.gitignore	Git 忽略规则文件，指定哪些文件 / 目录不需要提交到 Git（如 target、.idea）。
mvnw/mvnw.cmd	Maven Wrapper 脚本，无需本地安装 Maven，直接通过脚本执行构建命令（跨平台支持）。
pom.xml	Maven 的核心配置文件，管理项目依赖、插件、打包方式、项目信息等，是项目的 “依赖清单”。
README.md	项目说明文档，用于介绍项目功能、启动方式、技术栈等，是团队协作和开源的必备文档。

---

🧩 src/main/java/gzj/spring.ai 核心业务包

这是项目的业务代码核心目录，采用了分层架构，职责清晰：

• controller（控制层）是前端与后端的交互入口，负责接收 HTTP 请求、校验请求参数、调用 service 层处理业务，最后封装响应结果返回给前端。

• entity（实体类层）对应数据库表的 POJO（Plain Old Java Object），也可以是业务场景中的数据模型，用来封装业务数据。

• R（统一响应封装类）项目的全局响应格式封装，所有接口返回结果都通过这个类统一格式（比如包含 code 状态码、message 提示信息、data 响应数据），让前后端交互更规范。
   

  

• req（请求参数封装类）专门封装前端传来的请求参数，比如 UserLoginReq、CreateOrderReq，避免 controller 方法参数过多，同时方便参数校验（搭配 @Valid 注解）。

• res（响应数据封装类）专门封装要返回给前端的业务数据，比如 UserInfoRes、OrderListRes，和 req 包对应，实现 “请求参数” 与 “响应数据” 的模型分离，更易维护。

• service（业务逻辑层）处理具体的业务逻辑，是 controller 和数据访问层（如 Mapper）的中间层。通常会拆分为接口（UserService）和实现类（UserServiceImpl，一般放在 service/impl 子包），负责复杂业务逻辑的编排、事务控制等。

• util（工具类包）封装项目中通用的工具方法，比如日期格式化、加密解密、字符串处理、文件操作等，避免代码重复，提升复用性。

• AiApplication（项目启动类）Spring Boot 的入口类，带有 @SpringBootApplication 注解，启动时会自动扫描包下的所有 Spring 组件，初始化 Spring 容器。

---

📁 src/main/resources（资源文件目录）

这个目录主要存放配置文件、静态资源等，常见内容包括：

• application.yml/application.properties：Spring Boot 的核心配置文件，配置端口、数据库连接、日志级别、第三方服务密钥等。
• mapper（如果用 MyBatis）：存放 MyBatis 的 XML 映射文件，定义 SQL 语句。
• static：存放静态资源（HTML、CSS、JS、图片等），供前端直接访问。
• templates：存放模板引擎文件（如 Thymeleaf），用于渲染动态页面。

---

✨ 整体架构特点

这个项目采用了分层架构，严格遵循 “高内聚、低耦合” 原则：

• 分层清晰：控制层（接收请求）→ 业务层（处理逻辑）→ 数据层（操作数据库，若后续添加 Mapper 包），各层职责明确。
• 模型分离：请求（req）、响应（res）、实体（entity）模型分离，避免数据混乱。
• 统一规范：全局响应封装（R）保证前后端交互格式统一，工具类（util）提升代码复用性。

---

3.pom

        关于我使用的依赖类目，大家可以直接去项目中拉取，我就不贴上来了。

  pom.xml 是 Maven 项目的核心配置文件，负责定义项目坐标、依赖、构建规则等，这份配置是典型的 Spring Boot + AI 能力 + 外部服务整合 架构，下面分模块讲解：

1. 基础配置（项目标识与父工程）

这部分是 Maven 项目的 “身份信息” 和基础依赖管理：

<!-- 父工程：Spring Boot 官方父工程，提供依赖版本自动管理、默认配置等核心能力 -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.9-SNAPSHOT</version> <!-- 快照版，开发中版本，正式环境建议用RELEASE版 -->
    <relativePath/>
</parent>

<!-- Maven 坐标：唯一标识你的项目 -->
<groupId>gzj.spring</groupId> <!-- 组织/公司标识 -->
<artifactId>ai</artifactId>    <!-- 项目名称 -->
<version>0.0.1-SNAPSHOT</version> <!-- 版本：快照版，开发阶段使用 -->

<!-- 可选元信息：开源/团队协作时用，当前为空不影响项目运行 -->
<name>ai</name>
<description>ai</description>
<licenses>/<developers>/<scm> <!-- 许可证、开发者、代码仓库信息，空值不影响功能 -->

        关键说明：Spring Boot 父工程是核心，它帮你统一管理大部分依赖的版本，无需手动指定（比如 spring-boot-starter-web 不用写版本）；3.5.9-SNAPSHOT 是快照版本，适合开发阶段，正式环境建议替换为稳定版（如 3.2.0）

2. 全局属性（Properties）

<properties>
    <java.version>17</java.version> <!-- JDK版本，Spring Boot 3.x 强制要求JDK 17+ -->
    <java.json>2.0.32</java.json>   <!-- fastjson版本变量，统一管理便于升级 -->
</properties>

        核心价值：用变量统一管理版本号，后续升级时只需改这里，不用逐个依赖修改，降低维护成本。

3. 核心依赖（Dependencies）

        这是项目的 “技术栈清单”，每个依赖对应一个具体能力，按功能分类讲解：

依赖名称	核心作用
spring-boot-starter-web	Web 开发核心依赖：包含 Tomcat（内置服务器）、Spring MVC、HTTP 请求 / 响应处理
spring-boot-starter-data-redis	整合 Redis：提供RedisTemplate等工具，实现 Redis 缓存 / 数据存储
commons-pool2	Redis 连接池：提升 Redis 连接复用率和性能，是 Redis 依赖的 “性能优化补充”
fastjson	阿里 JSON 工具：快速实现 Java 对象和 JSON 字符串互转（AI 接口交互常用）
spring-ai-model	Spring AI 核心：对接 AI 大模型的基础封装，统一 AI 模型调用接口
rxjava	响应式编程：支持流式数据处理（比如 AI 接口的 “流式返回结果”）
commons-io	Apache IO 工具：简化文件读写、流操作（比如处理音频 / 图片文件）
okhttp	HTTP 客户端：替代原生 Java HTTP 工具，更易用、性能更好（调用外部 AI / 云服务）
springfox-boot-starter	Swagger3：自动生成接口文档，支持在线调试（开发阶段必备）
jaudiotagger	音频解析：读取音频文件的元数据（歌名、歌手、时长等，适配音频 AI 场景）
esdk-obs-java-bundle	华为云 OBS SDK：操作华为云对象存储（上传 / 下载 AI 所需的音频 / 图片文件）
volcengine-java-sdk-ark-runtime	火山引擎方舟 AI SDK：对接火山引擎的大模型服务（核心 AI 能力依赖）
lombok	简化代码：通过@Data等注解自动生成 getter/setter，减少模板代码
spring-retry	重试机制：接口调用失败时自动重试（比如 AI 接口超时 / 网络波动）
spring-boot-starter-aop	AOP 编程：实现日志、权限、重试的切面逻辑（非侵入式扩展）

4. 构建配置（Build）

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

        核心作用：Spring Boot 打包插件，能将项目打包成可独立运行的 Jar 包（包含所有依赖），执行 mvn package 后可直接用 java -jar 启动项目。

5. 仓库配置（Repositories）

<repositories>
    <repository>
        <id>spring-snapshots</id>
        <name>Spring Snapshots</name>
        <url>https://repo.spring.io/snapshot</url>
        <releases><enabled>false</enabled></releases> <!-- 只拉快照版依赖 -->
    </repository>
</repositories>

4.运行环境

        我的 idea 版本：        IntelliJ IDEA 2025.1.3 (Ultimate Edition)

        JDK 版本：                JDK21 （没咋用到新特性，基本17或者8都可以）

        操作系统：                 windows10

各项文章内容链接：

​​

文章标题 + 链接列表（按原数据顺序）

1. 基于 Doubao-Seedream-4.5 的单张图片生成后端接口实战：https://blog.csdn.net/weixin_66243333/article/details/156513594https://blog.csdn.net/weixin_66243333/article/details/156513594
2. Doubao - 图片生成解析与试用 模型：Doubao-Seedream-4.5：https://blog.csdn.net/weixin_66243333/article/details/156512234https://blog.csdn.net/weixin_66243333/article/details/156512234
3. 从零到一：豆包大模型 API 获取与调用全指南（含多模型深度对比）：https://blog.csdn.net/weixin_66243333/article/details/156462848https://blog.csdn.net/weixin_66243333/article/details/156462848
4. 基于 豆包大模型 Doubao-Seed-1.6-thinking 的前后端分离项目 - 图文问答（后端）：https://blog.csdn.net/weixin_66243333/article/details/156461145https://blog.csdn.net/weixin_66243333/article/details/156461145
5. 基于 cosyvoice-v3-plus 的 个人音色复刻 （华为 OBS）：https://blog.csdn.net/weixin_66243333/article/details/156393173https://blog.csdn.net/weixin_66243333/article/details/156393173
6. 基于 cosyvoice-v3-plus 的简单语音合成：https://blog.csdn.net/weixin_66243333/article/details/156392659https://blog.csdn.net/weixin_66243333/article/details/156392659
7. 92 种语言通杀！通义千问 Qwen-MT 翻译模型深度解析 + 实战指南：https://blog.csdn.net/weixin_66243333/article/details/156232927https://blog.csdn.net/weixin_66243333/article/details/156232927
8. 通义万相 - 文生视频 Text2Video：https://blog.csdn.net/weixin_66243333/article/details/156226279https://blog.csdn.net/weixin_66243333/article/details/156226279
9. Qwen3-Omni-Captioner：通义千问 3-Omni 基座的智能音频描述开源模型：https://blog.csdn.net/weixin_66243333/article/details/156096972https://blog.csdn.net/weixin_66243333/article/details/156096972
10. 基于 GUI-PLUS 搭配 Java Robot 实现智能桌面操控：https://blog.csdn.net/weixin_66243333/article/details/156083404https://blog.csdn.net/weixin_66243333/article/details/156083404
11. 基于 GUI-PLUS 的桌面 GUI 交互全流程总结：https://blog.csdn.net/weixin_66243333/article/details/156056738https://blog.csdn.net/weixin_66243333/article/details/156056738
12. 通义千问 3-VL-Plus - 界面交互（坐标改进）：https://blog.csdn.net/weixin_66243333/article/details/156056380https://blog.csdn.net/weixin_66243333/article/details/156056380
13. 通义千问 3-VL-Plus - 界面交互（本地图片改进）：https://blog.csdn.net/weixin_66243333/article/details/156024853https://blog.csdn.net/weixin_66243333/article/details/156024853
14. 通义千问 3-VL-Plus - 界面交互（本地图片）：https://blog.csdn.net/weixin_66243333/article/details/156024412https://blog.csdn.net/weixin_66243333/article/details/156024412
15. 通义千问 3-VL-Plus - 界面交互：https://blog.csdn.net/weixin_66243333/article/details/156020450https://blog.csdn.net/weixin_66243333/article/details/156020450
16. 通义千问 3-VL-Plus - 文字提取（发票信息提取）：https://blog.csdn.net/weixin_66243333/article/details/155948164https://blog.csdn.net/weixin_66243333/article/details/155948164
17. 大模型通义千问 3-VL-Plus - 视觉推理（图像列表）：https://blog.csdn.net/weixin_66243333/article/details/155888893https://blog.csdn.net/weixin_66243333/article/details/155888893
18. 大模型通义千问 3-VL-Plus - 视觉推理（在线视频）：https://blog.csdn.net/weixin_66243333/article/details/155879247https://blog.csdn.net/weixin_66243333/article/details/155879247
19. 大模型通义千问 3-VL-Plus - 视觉推理（本地图片）：https://blog.csdn.net/weixin_66243333/article/details/155876620https://blog.csdn.net/weixin_66243333/article/details/155876620
20. 大模型通义千问 3-VL-Plus - 视觉理解：https://blog.csdn.net/weixin_66243333/article/details/155828824https://blog.csdn.net/weixin_66243333/article/details/155828824
21. 千问通义 plus - MCP 添加进智能体（高德地图）：https://blog.csdn.net/weixin_66243333/article/details/155712372https://blog.csdn.net/weixin_66243333/article/details/155712372
22. 通义 AI 工具之 联网搜索 和 Function（有免费接口）：https://blog.csdn.net/weixin_66243333/article/details/155617502https://blog.csdn.net/weixin_66243333/article/details/155617502
23. 通义千问 - plus 智能体的上下文缓存：https://blog.csdn.net/weixin_66243333/article/details/155539226https://blog.csdn.net/weixin_66243333/article/details/155539226
24. 通义千问 - plus 智能体的上下文缓存 - Caffeine（本地缓存）：https://blog.csdn.net/weixin_66243333/article/details/155613472https://blog.csdn.net/weixin_66243333/article/details/155613472
25. 君子性非异也，善假于物也：https://blog.csdn.net/weixin_66243333/article/details/155572518https://blog.csdn.net/weixin_66243333/article/details/155572518
26. 通义千问插件：IDEA 中 Java 开发的 AI 赋能实战录：https://blog.csdn.net/weixin_66243333/article/details/155543035https://blog.csdn.net/weixin_66243333/article/details/155543035
27. 通义千问 - plus 智能体的多轮对话：https://blog.csdn.net/weixin_66243333/article/details/155523688https://blog.csdn.net/weixin_66243333/article/details/155523688
28. Springboot 调用单智能体：https://blog.csdn.net/weixin_66243333/article/details/155495158https://blog.csdn.net/weixin_66243333/article/details/155495158
29. 千问通义 plus - 智能体应用基础使用：https://blog.csdn.net/weixin_66243333/article/details/155487991https://blog.csdn.net/weixin_66243333/article/details/155487991
30. 报错 EventSource‘s response has a MIME type (“text/html“) that is not “text/event-stream“：https://blog.csdn.net/weixin_66243333/article/details/155457298https://blog.csdn.net/weixin_66243333/article/details/155457298
31. Vue3+Springboot3 + 千问 plus 流式（前后端分离）：https://blog.csdn.net/weixin_66243333/article/details/155455582https://blog.csdn.net/weixin_66243333/article/details/155455582

END

        如果觉得这份基础知识点总结清晰，别忘了动动小手点个赞👍，再关注一下呀～ 后续还会分享更多有关人工智能问题的干货技巧，同时一起解锁更多好用的功能，少踩坑多提效！🥰 你的支持就是我更新的最大动力，咱们下次分享再见呀～🌟

        😺这是我第一次开源的项目，有许多不足之处请各位大佬同学们多多指出，希望能够认识到大家一起进步！