【代码优化】AI：完善各种注释

YunaiV
1 parent 3e164121
Showing 17 changed files with 52 additions and 96 deletions
yudao-dependencies/pom.xml
yudao-module-ai/pom.xml
yudao-module-ai/yudao-module-ai-api/pom.xml
yudao-module-ai/yudao-module-ai-api/src/main/java/cn/iocoder/yudao/module/ai/enums/ErrorCodeConstants.java
yudao-module-ai/yudao-module-ai-biz/pom.xml
yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/controller/admin/image/vo/AiImagePageReqVO.java
yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/controller/admin/image/vo/midjourney/AiMidjourneyImagineReqVO.java
yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/controller/admin/model/vo/apikey/AiApiKeyPageReqVO.java
yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/controller/admin/model/vo/chatModel/AiChatModelPageReqVO.java
yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/controller/admin/model/vo/chatRole/AiChatRolePageReqVO.java
yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/controller/admin/music/vo/AiMusicPageReqVO.java
yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/service/image/AiImageServiceImpl.java
yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/service/model/AiApiKeyServiceImpl.java
yudao-module-ai/yudao-spring-boot-starter-ai/pom.xml
yudao-module-ai/yudao-spring-boot-starter-ai/src/main/java/cn/iocoder/yudao/framework/ai/core/model/package-info.java
yudao-module-ai/yudao-spring-boot-starter-ai/src/main/java/cn/iocoder/yudao/framework/ai/core/package-info.java
yudao-module-ai/yudao-spring-boot-starter-ai/src/main/java/cn/iocoder/yudao/framework/ai/package-info.java
@@ -75,7 +75,6 @@
         <jimureport.version>1.6.6-beta2</jimureport.version>
         <xercesImpl.version>2.12.2</xercesImpl.version>
         <weixin-java.version>4.6.0</weixin-java.version>
-        <ureport2.version>2.2.9</ureport2.version>
         <spring-ai-bom.version>0.8.0</spring-ai-bom.version>
     </properties>
@@ -2,28 +2,26 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
     <parent>
         <groupId>cn.iocoder.boot</groupId>
         <artifactId>yudao</artifactId>
         <version>${revision}</version>
     </parent>
-    <packaging>pom</packaging>
-    <artifactId>yudao-module-ai</artifactId>
-
+    <modelVersion>4.0.0</modelVersion>
     <modules>
         <module>yudao-module-ai-api</module>
         <module>yudao-module-ai-biz</module>
         <module>yudao-spring-boot-starter-ai</module>
     </modules>
+    <packaging>pom</packaging>
+    <artifactId>yudao-module-ai</artifactId>
-    <properties>
-        <maven.compiler.source>17</maven.compiler.source>
-        <maven.compiler.target>17</maven.compiler.target>
-        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    </properties>
-
-    <dependencies>
-    </dependencies>
+    <name>${project.artifactId}</name>
+    <description>
+        ai 模块下，接入 LLM 大模型，支持聊天、绘图、音乐、写作、思维脑图等功能。
+        目前已接入各种模型，不限于：
+          国内：通义千问、文心一言、讯飞星火
+          国外：OpenAI、Ollama、Midjourney、StableDiffusion、Suno
+    </description>
 </project>
 \ No newline at end of file
@@ -2,32 +2,26 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
     <parent>
         <groupId>cn.iocoder.boot</groupId>
         <artifactId>yudao-module-ai</artifactId>
         <version>${revision}</version>
     </parent>
-
+    <modelVersion>4.0.0</modelVersion>
     <artifactId>yudao-module-ai-api</artifactId>
+    <packaging>jar</packaging>
-    <properties>
-        <maven.compiler.source>17</maven.compiler.source>
-        <maven.compiler.target>17</maven.compiler.target>
-        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    </properties>
+    <name>${project.artifactId}</name>
+    <description>
+        ai 模块 API，暴露给其它模块调用
+    </description>
     <dependencies>
-        <!-- yudao-common -->
         <dependency>
             <groupId>cn.iocoder.boot</groupId>
             <artifactId>yudao-common</artifactId>
         </dependency>
-        <!-- lombok -->
-        <dependency>
-            <groupId>org.projectlombok</groupId>
-            <artifactId>lombok</artifactId>
-        </dependency>
+
         <!-- 参数校验 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
@@ -12,6 +12,9 @@ public interface ErrorCodeConstants {
     // ========== API 密钥 1-040-000-000 ==========
     ErrorCode API_KEY_NOT_EXISTS = new ErrorCode(1_040_000_000, "API 密钥不存在");
     ErrorCode API_KEY_DISABLE = new ErrorCode(1_040_000_001, "API 密钥已禁用！");
+    ErrorCode API_KEY_MIDJOURNEY_NOT_FOUND = new ErrorCode(1_040_000_900, "Midjourney 模型不存在");
+    ErrorCode API_KEY_SUNO_NOT_FOUND = new ErrorCode(1_040_000_901, "Suno 模型不存在");
+    ErrorCode API_KEY_IMAGE_NODE_FOUND = new ErrorCode(1_040_000_902, "平台({}) 图片模型未配置");
     // ========== API 聊天模型 1-040-001-000 ==========
     ErrorCode CHAT_MODEL_NOT_EXISTS = new ErrorCode(1_040_001_000, "模型不存在!");
@@ -2,21 +2,21 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
     <parent>
         <groupId>cn.iocoder.boot</groupId>
         <artifactId>yudao-module-ai</artifactId>
         <version>${revision}</version>
     </parent>
-
+    <modelVersion>4.0.0</modelVersion>
     <artifactId>yudao-module-ai-biz</artifactId>
-    <properties>
-        <maven.compiler.source>8</maven.compiler.source>
-        <maven.compiler.target>8</maven.compiler.target>
-        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    </properties>
-
+    <name>${project.artifactId}</name>
+    <description>
+        ai 模块下，接入 LLM 大模型，支持聊天、绘图、音乐、写作、思维脑图等功能。
+        目前已接入各种模型，不限于：
+        国内：通义千问、文心一言、讯飞星火
+        国外：OpenAI、Ollama、Midjourney、StableDiffusion、Suno
+    </description>
     <dependencies>
         <dependency>
@@ -24,44 +24,36 @@
             <artifactId>yudao-module-ai-api</artifactId>
             <version>${revision}</version>
         </dependency>
+
+        <!-- 业务组件 -->
         <dependency>
             <groupId>cn.iocoder.boot</groupId>
             <artifactId>yudao-spring-boot-starter-ai</artifactId>
             <version>${revision}</version>
         </dependency>
-        <!--  yudao framwork  -->
-        <dependency>
-            <groupId>cn.iocoder.boot</groupId>
-            <artifactId>yudao-common</artifactId>
-        </dependency>
+
+        <!-- Web 相关 -->
         <dependency>
             <groupId>cn.iocoder.boot</groupId>
             <artifactId>yudao-spring-boot-starter-security</artifactId>
         </dependency>
+
+        <!-- DB 相关 -->
         <dependency>
             <groupId>cn.iocoder.boot</groupId>
             <artifactId>yudao-spring-boot-starter-mybatis</artifactId>
         </dependency>
-        <!--  测试  -->
+
+        <!-- Job 相关 -->
         <dependency>
             <groupId>cn.iocoder.boot</groupId>
-            <artifactId>yudao-spring-boot-starter-test</artifactId>
+            <artifactId>yudao-spring-boot-starter-job</artifactId>
         </dependency>
+
+        <!-- Test 测试相关 -->
         <dependency>
             <groupId>cn.iocoder.boot</groupId>
-            <artifactId>yudao-spring-boot-starter-job</artifactId>
+            <artifactId>yudao-spring-boot-starter-test</artifactId>
         </dependency>
     </dependencies>
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-                <configuration>
-                    <source>17</source>
-                    <target>17</target>
-                </configuration>
-            </plugin>
-        </plugins>
-    </build>
 </project>
 \ No newline at end of file
@@ -13,8 +13,6 @@ import static cn.iocoder.yudao.framework.common.util.date.DateUtils.FORMAT_YEAR_
 @Schema(description = "管理后台 - AI 绘画分页 Request VO")
 @Data
-@EqualsAndHashCode(callSuper = true)
-@ToString(callSuper = true)
 public class AiImagePageReqVO extends PageParam {
     @Schema(description = "用户编号", example = "28987")
@@ -5,8 +5,6 @@ import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
 import lombok.Data;
-import java.util.List;
-
 @Schema(description = "管理后台 - AI 绘画生成（Midjourney） Request VO")
 @Data
 public class AiMidjourneyImagineReqVO {
@@ -31,7 +29,7 @@ public class AiMidjourneyImagineReqVO {
     @NotEmpty(message = "版本号不能为空")
     private String version;
-    @Schema(description = "参考图")
+    @Schema(description = "参考图", example = "https://www.iocoder.cn/x.png")
     private String referImageUrl;
 }
@@ -11,8 +11,6 @@ import static cn.iocoder.yudao.framework.common.util.date.DateUtils.FORMAT_YEAR_
 @Schema(description = "管理后台 - AI API 密钥分页 Request VO")
 @Data
-@EqualsAndHashCode(callSuper = true)
-@ToString(callSuper = true)
 public class AiApiKeyPageReqVO extends PageParam {
     @Schema(description = "名称", example = "文心一言")
@@ -6,8 +6,6 @@ import cn.iocoder.yudao.framework.common.pojo.PageParam;
 @Schema(description = "管理后台 - API 聊天模型分页 Request VO")
 @Data
-@EqualsAndHashCode(callSuper = true)
-@ToString(callSuper = true)
 public class AiChatModelPageReqVO extends PageParam {
     @Schema(description = "模型名字", example = "张三")
@@ -6,8 +6,6 @@ import cn.iocoder.yudao.framework.common.pojo.PageParam;
 @Schema(description = "管理后台 - AI 聊天角色分页 Request VO")
 @Data
-@EqualsAndHashCode(callSuper = true)
-@ToString(callSuper = true)
 public class AiChatRolePageReqVO extends PageParam {
     @Schema(description = "角色名称", example = "李四")
@@ -16,8 +16,6 @@ import static cn.iocoder.yudao.framework.common.util.date.DateUtils.FORMAT_YEAR_
 @Schema(description = "管理后台 - AI 音乐分页 Request VO")
 @Data
-@EqualsAndHashCode(callSuper = true)
-@ToString(callSuper = true)
 public class AiMusicPageReqVO extends PageParam {
     @Schema(description = "用户编号", example = "12212")
@@ -35,7 +35,6 @@ import org.springframework.scheduling.annotation.Async;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
-import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -192,10 +191,8 @@ public class AiImageServiceImpl implements AiImageService {
         imageMapper.insert(image);
         // 2. 调用 Midjourney Proxy 提交任务
-        List<String> base64Array = new ArrayList<>(8);
-        if (StrUtil.isNotBlank(reqVO.getReferImageUrl())) {
-            base64Array.add("data:image/jpeg;base64,".concat(Base64.encode(HttpUtil.downloadBytes(reqVO.getReferImageUrl()))));
-        }
+        List<String> base64Array = StrUtil.isBlank(reqVO.getReferImageUrl()) ? null :
+                Collections.singletonList("data:image/jpeg;base64,".concat(Base64.encode(HttpUtil.downloadBytes(reqVO.getReferImageUrl()))));
         MidjourneyApi.ImagineRequest imagineRequest = new MidjourneyApi.ImagineRequest(
                 base64Array, reqVO.getPrompt(),null,
                 MidjourneyApi.ImagineRequest.buildState(reqVO.getWidth(),
@@ -108,7 +108,7 @@ public class AiApiKeyServiceImpl implements AiApiKeyService {
     public ImageModel getImageClient(AiPlatformEnum platform) {
         AiApiKeyDO apiKey = apiKeyMapper.selectFirstByPlatformAndStatus(platform.getName(), CommonStatusEnum.ENABLE.getStatus());
         if (apiKey == null) {
-            return null;
+            throw exception(API_KEY_IMAGE_NODE_FOUND, platform.getName());
         }
         return clientFactory.getOrCreateImageClient(platform, apiKey.getApiKey(), apiKey.getUrl());
     }
@@ -117,9 +117,8 @@ public class AiApiKeyServiceImpl implements AiApiKeyService {
     public MidjourneyApi getMidjourneyApi() {
         AiApiKeyDO apiKey = apiKeyMapper.selectFirstByPlatformAndStatus(
                 AiPlatformEnum.MIDJOURNEY.getPlatform(), CommonStatusEnum.ENABLE.getStatus());
-        // todo @芋艿 这些地方直接抛异常会好点，不然调用到的地方都需要做判断
         if (apiKey == null) {
-            return null;
+            throw exception(API_KEY_MIDJOURNEY_NOT_FOUND);
         }
         return clientFactory.getOrCreateMidjourneyApi(apiKey.getApiKey(), apiKey.getUrl());
     }
@@ -129,7 +128,7 @@ public class AiApiKeyServiceImpl implements AiApiKeyService {
         AiApiKeyDO apiKey = apiKeyMapper.selectFirstByPlatformAndStatus(
                 AiPlatformEnum.SUNO.getPlatform(), CommonStatusEnum.ENABLE.getStatus());
         if (apiKey == null) {
-            return null;
+            throw exception(API_KEY_SUNO_NOT_FOUND);
         }
         return clientFactory.getOrCreateSunoApi(apiKey.getApiKey(), apiKey.getUrl());
     }
@@ -8,8 +8,9 @@
         <version>${revision}</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
-
     <artifactId>yudao-spring-boot-starter-ai</artifactId>
+    <packaging>jar</packaging>
+
     <name>${project.artifactId}</name>
     <description>AI 大模型拓展，接入国内外大模型</description>
     <properties>
@@ -58,6 +59,7 @@
             <version>2.14.0</version>
         </dependency>
+        <!-- Test 测试相关 -->
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>
-/**
- * model 包，接入各种大模型，对标 https://github.com/spring-projects/spring-ai/tree/main/models
- *
- * 1. yiyan 包：【百度】文心一言
- * 2. tongyi 包：【阿里】通义千问，对标 spring-cloud-alibaba 提供的 ai 包 TODO 芋艿：未来直接使用它
- * 3. xinghuo 包：【讯飞】星火，自己实现
- * 4. midjourney 包：Midjourney，接入 https://github.com/novicezk/midjourney-proxy 实现
- * 5. suno 包：TODO 芋艿：
- */
-package cn.iocoder.yudao.framework.ai.core.model;
 \ No newline at end of file
-/**
- * 芋道 AI Starter，整体参考 spring-ai 拓展
- */
-package cn.iocoder.yudao.framework.ai.core;
 \ No newline at end of file
@@ -6,10 +6,8 @@
  * 包路径：
  * 1. chat、parser、model、parser 包：https://github.com/spring-projects/spring-ai/tree/main/spring-ai-core 拷贝
  * 2. models 包：对标 https://github.com/spring-projects/spring-ai/tree/main/models 拷贝
- *  2.1 tongyi 包：【阿里】通义千问，对标 spring-cloud-alibaba 提供的 ai 包
- *  2.2 yiyan 包：【百度】文心一言，自己实现
- *  2.3 xinghuo 包：【讯飞】星火，自己实现
- *  2.4 openai 包：【OpenAI】ChatGPT，拷贝 spring-ai 提供的 models/openai 包
- *  2.5 midjourney 包：Midjourney，参考 https://github.com/novicezk/midjourney-proxy 实现
+ *  2.1 xinghuo 包：【讯飞】星火，自己实现
+ *  2.2 midjourney 包：Midjourney API，对接 https://github.com/novicezk/midjourney-proxy 实现
+ *  2.3 suno 包：Suno API，对接 https://github.com/gcui-art/suno-api 实现
  */
 package cn.iocoder.yudao.framework.ai;
 \ No newline at end of file