用SpringAI结构化输出，我花1小时就搭了个小说大纲生成器（附完整源码）

用SpringAI结构化输出快速构建小说大纲生成器1. 项目背景与需求分析小说创作过程中构思完整的大纲往往是最耗时的环节。传统方式需要作者手动规划主线情节、支线发展、人物设定和章节概要这个过程可能耗费数周时间。而借助AI技术我们可以将这一过程缩短到几分钟内完成。SpringAI的结构化输出功能为这类需求提供了完美解决方案。它允许开发者将AI生成的文本直接映射到Java对象省去了手动解析JSON的繁琐步骤。对于小说大纲生成这样的场景结构化输出能够确保返回的数据具有一致的格式便于后续处理和展示。这个项目的核心目标是利用SpringAI的BeanOutputConverter实现AI响应到Java对象的自动转换构建一个完整的Web应用接收用户输入并返回结构化小说大纲提供可扩展的架构方便后续添加更多创作辅助功能2. 技术栈选型与准备2.1 核心组件// 项目主要依赖 dependencies { implementation org.springframework.boot:spring-boot-starter-web implementation org.springframework.ai:spring-ai-core implementation org.projectlombok:lombok implementation com.fasterxml.jackson.core:jackson-databind }2.2 环境配置Spring Boot版本建议使用3.2.x及以上版本Java版本JDK 17或更高AI模型接入支持OpenAI、Azure OpenAI等主流模型本地部署的模型如Ollama也可使用提示不同模型对结构化输出的支持程度可能有所差异建议先进行小规模测试3. 核心实现步骤3.1 定义数据结构模型首先需要定义小说大纲的数据结构这将成为AI输出的目标格式Data public class NovelOutline { private String title; private String genre; private String mainPlot; private ListString subPlots; private ListChapter chapters; private ListCharacter characters; Data public static class Chapter { private int number; private String title; private String summary; } Data public static class Character { private String name; private String role; private String appearance; private String personality; private String development; } }3.2 配置SpringAI输出转换器创建BeanOutputConverter实例指定目标类型为我们的NovelOutline类Service public class OutlineGeneratorService { private final ChatClient chatClient; public NovelOutline generateOutline(String prompt, String genre, int chapterCount) { // 创建输出转换器 BeanOutputConverterNovelOutline converter new BeanOutputConverter(NovelOutline.class); // 构建系统提示词 String systemPrompt buildSystemPrompt(converter); // 调用AI模型 NovelOutline outline chatClient.prompt() .system(systemPrompt) .user(buildUserPrompt(prompt, genre, chapterCount)) .call() .entity(converter); return outline; } private String buildSystemPrompt(BeanOutputConverterNovelOutline converter) { return 你是一位专业的小说创作助手擅长根据用户输入生成结构完整的小说大纲。 请严格按照以下格式返回结果 converter.getFormat(); } }3.3 前端交互设计虽然核心功能在后端但一个简单的前端可以提升用户体验!-- 简化的HTML表单 -- form idoutlineForm div label小说主题:/label textarea nameprompt required/textarea /div div label类型:/label select namegenre option科幻/option option奇幻/option option悬疑/option /select /div div label章节数:/label input typenumber namechapterCount min1 max50 value10 /div button typesubmit生成大纲/button /form div idresultContainer/div4. 高级功能与优化4.1 提示词工程优化为了提高AI生成质量可以细化系统提示词private String buildSystemPrompt(BeanOutputConverterNovelOutline converter) { return 你是一位拥有20年经验的小说编辑擅长创作结构严谨、情节吸引人的小说大纲。 ## 创作要求 1. 主线情节必须逻辑连贯包含明确的冲突和解决 2. 支线情节应与主线相关增强故事深度 3. 人物设定需立体丰满包含外貌、性格和成长轨迹 4. 章节概要应推动故事发展每章有明确目的 ## 输出格式 请严格遵循以下JSON结构 converter.getFormat(); }4.2 结果缓存与版本控制Service public class OutlineCacheService { Cacheable(value outlines, key {#prompt,#genre,#chapterCount}) public NovelOutline getCachedOutline(String prompt, String genre, int chapterCount) { // 调用原始服务生成大纲 return outlineGeneratorService.generateOutline(prompt, genre, chapterCount); } public NovelOutline reviseOutline(NovelOutline original, String revisionInstructions) { // 实现大纲修订逻辑 } }4.3 性能监控与调优添加监控指标了解生成时间和质量Timed(value outline.generate.time, description 大纲生成耗时) Counted(value outline.generate.count, description 大纲生成次数) public NovelOutline generateOutlineWithMetrics(String prompt, String genre, int chapterCount) { return outlineGeneratorService.generateOutline(prompt, genre, chapterCount); }5. 部署与扩展建议5.1 容器化部署# Dockerfile示例 FROM eclipse-temurin:17-jdk-jammy WORKDIR /app COPY target/novel-outline-generator-*.jar app.jar ENTRYPOINT [java, -jar, app.jar]5.2 扩展可能性多模型支持同时接入多个AI模型比较生成结果风格控制添加参数控制生成风格如轻松、严肃、黑暗等协作功能允许多人编辑和评论生成的大纲导出格式支持导出为Word、Markdown等格式6. 实际应用案例假设我们要生成一部侦探小说的10章大纲NovelOutline outline outlineGenerator.generateOutline( 一位退休侦探被卷入一桩看似自杀的谋杀案, 悬疑, 10 ); // 输出示例结构 System.out.println(标题: outline.getTitle()); System.out.println(主线: outline.getMainPlot()); outline.getChapters().forEach(chapter - { System.out.printf(第%d章 %s: %s%n, chapter.getNumber(), chapter.getTitle(), chapter.getSummary()); });生成结果可能包含主线退休侦探发现死者留下的隐秘线索指向一桩20年前的悬案支线警察局内部的权力斗争侦探与记者之间的复杂关系人物固执但敏锐的老侦探野心勃勃的年轻警探神秘的酒吧老板章节从意外的访客到真相与代价的完整故事发展7. 开发中的经验分享在实际开发过程中有几个关键点值得注意字段设计要明确AI对模糊的字段名理解可能不一致比如development比growth更明确格式指令要简洁过长的格式说明反而可能干扰AI理解错误处理要完善AI可能返回不符合预期的结构需要健壮的解析逻辑温度参数调节创造性项目可以适当提高temperature值(0.7-0.9)获得更多样化的输出一个实用的调试技巧是在开发阶段先打印出完整的提示词和响应方便排查问题System.out.println(完整提示词:\n finalPrompt); System.out.println(原始响应:\n rawResponse);8. 前端展示优化对于生成结果的展示可以考虑以下增强// 动态渲染大纲内容 function displayOutline(outline) { // 渲染主线情节 $(#mainPlot).html(h3${outline.title}/h3p${outline.mainPlot}/p); // 渲染章节 let chaptersHtml ; outline.chapters.forEach(chapter { chaptersHtml div classchapter h4第${chapter.number}章 ${chapter.title}/h4 p${chapter.summary}/p /div; }); $(#chapters).html(chaptersHtml); // 渲染人物 let charactersHtml ; outline.characters.forEach(character { charactersHtml div classcharacter h4${character.name} (${character.role})/h4 pstrong外貌:/strong ${character.appearance}/p pstrong性格:/strong ${character.personality}/p /div; }); $(#characters).html(charactersHtml); }9. 安全与限制管理在实际部署时需要考虑API调用限制防止滥用可以添加速率限制内容过滤对生成内容进行适当审核用户隔离确保不同用户的数据不会混淆模型选择根据需求平衡成本和质量Configuration public class SecurityConfig { Bean public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(auth - auth .requestMatchers(/api/generate).authenticated() .anyRequest().permitAll() ) .formLogin(withDefaults()); return http.build(); } }10. 项目结构与源码组织一个清晰的包结构有助于长期维护src/main/java ├── config ├── controller ├── dto ├── model ├── repository ├── service │ ├── impl │ └── cache └── util关键实现类OutlineController处理HTTP请求OutlineGeneratorServiceImpl核心生成逻辑OutlineCacheServiceImpl缓存管理OutlineValidator结果验证11. 测试策略确保生成质量的几种测试方法单元测试验证核心逻辑集成测试检查完整流程人工评估抽样检查生成质量A/B测试比较不同提示词效果Test void testOutlineGeneration() { NovelOutline outline outlineGenerator.generateOutline( 科幻太空歌剧, 科幻, 12); assertNotNull(outline); assertEquals(12, outline.getChapters().size()); assertTrue(outline.getMainPlot().length() 50); }12. 性能优化技巧批量生成同时生成多个变体供选择预生成缓存热门题材的模板结果流式响应逐步返回生成内容模型量化使用更高效的模型版本public FluxNovelOutline generateVariants(String prompt, String genre, int chapterCount, int variantCount) { return Flux.range(1, variantCount) .parallel() .runOn(Schedulers.boundedElastic()) .flatMap(i - Mono.fromCallable(() - outlineGenerator.generateOutline(prompt, genre, chapterCount))) .sequential(); }13. 错误处理与降级方案健壮的系统需要处理各种异常情况ExceptionHandler(AIException.class) public ResponseEntityErrorResponse handleAIException(AIException ex) { ErrorResponse error new ErrorResponse( OUTLINE_GENERATION_FAILED, 大纲生成失败: ex.getMessage(), LocalDateTime.now() ); return ResponseEntity.status(500).body(error); } // 降级方案示例 public NovelOutline getFallbackOutline(String prompt, String genre, int chapterCount) { return new NovelOutline( 备用大纲, genre, 由于系统繁忙以下是简化版大纲..., List.of(备用支线), generateSimpleChapters(chapterCount), List.of() ); }14. 用户反馈与迭代收集用户反馈的几种方式评分系统让用户评价生成质量编辑功能记录用户修改点使用分析跟踪常用功能和参数问卷调查定期收集改进建议Entity public class OutlineFeedback { Id private String outlineId; private int rating; private String comments; private String modifiedPlot; private LocalDateTime createdAt; }15. 商业化考虑如果考虑产品化可以分层服务免费版与专业版团队协作多人协作功能专业模板特定类型小说模板出版对接与写作平台集成public enum SubscriptionPlan { FREE(10, false), PRO(100, true), TEAM(500, true); private int monthlyGenerations; private boolean advancedFeatures; }16. 技术债务管理随着项目发展需要注意DTO版本控制结构变更时的兼容性提示词版本化跟踪不同版本的生成效果依赖更新定期升级SpringAI等依赖文档维护保持文档与代码同步Version public class PromptTemplate { private Long id; private String content; private String version; private boolean active; }17. 监控与告警生产环境需要完善的监控生成时长超过阈值告警错误率跟踪失败请求内容质量异常结果检测资源使用CPU/内存监控Scheduled(fixedRate 60000) public void checkHealth() { double errorRate meterRegistry.get(outline.errors).totalTime(TimeUnit.MINUTES); if (errorRate 5) { alertService.sendAlert(大纲生成错误率过高: errorRate %); } }18. 本地开发技巧提高开发效率的几个建议测试数据集准备典型输入样例Mock服务减少真实API调用配置预设保存常用参数组合热重载利用Spring DevToolsProfile(dev) Service public class MockAIService { public String generateResponse(String prompt) { return mockResponses.get(prompt.hashCode() % mockResponses.size()); } }19. 团队协作规范多人开发时的最佳实践代码风格统一格式化规则提交信息清晰的变更描述文档标准一致的API文档评审流程严格的代码审查/** * 生成小说大纲 * param request 包含提示词、类型和章节数 * return 完整的小说大纲结构 * throws AIServiceException 当生成失败时抛出 */ PostMapping(/generate) public ResponseEntityNovelOutline generateOutline(RequestBody OutlineRequest request) { // 方法实现 }20. 持续学习与改进AI技术发展迅速保持更新的方法跟踪SpringAI更新新版本可能带来更好的结构化输出支持研究提示词技术如Chain-of-Thought等高级技巧参与社区分享经验学习他人做法实验文化定期尝试新方法Scheduled(cron 0 0 1 * * ?) public void checkForUpdates() { ListRelease releases githubClient.getReleases(spring-projects, spring-ai); Release latest releases.get(0); if (isNewer(latest.getVersion(), currentVersion)) { log.info(发现新版本SpringAI: {}, latest.getVersion()); } }