SpringBoot 集成 Stable-Diffusion-3.5 微服务实践

引入 WebFlux 很重要，因为我们需要异步调用 AI 服务，避免阻塞线程影响系统性能。

核心集成架构设计

服务架构概览

整个集成架构分为三层：

• API 层：提供 RESTful 接口给前端调用
• 服务层：处理业务逻辑和异步任务调度
• 客户端层：封装与 Stable-Diffusion API 的通信

这种分层设计让代码更清晰，也更容易维护和扩展。

配置管理

首先在 application.yml 中配置 SD 服务地址：

stable-diffusion:
  api:
    base-url: http://localhost:7860
    timeout: 30000
    max-retries: 3

对应的配置类：

@Configuration
@ConfigurationProperties(prefix = "stable-diffusion.api")
public class StableDiffusionConfig {
    private String baseUrl;
    private int timeout;
    private int maxRetries;
    // getters and setters
}

RESTful 客户端实现

WebClient 配置

WebClient 是 Spring 推荐的 HTTP 客户端，比 RestTemplate 更适合响应式编程：

@Bean
public WebClient stableDiffusionWebClient(StableDiffusionConfig config) {
    return WebClient.builder()
            .baseUrl(config.getBaseUrl())
            .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
            .clientConnector(new ReactorClientHttpConnector(
                    HttpClient.create().responseTimeout(Duration.ofMillis(config.getTimeout()))
            ))
            .build();
}

API 请求封装

定义请求和响应的 DTO 类：

@Data
public class TextToImageRequest {
    private String prompt;
    private String negativePrompt;
    private int width = 512;
    private int height = 512;
    private int steps = 20;
    private double cfgScale = 7.5;
}

@Data
public class TextToImageResponse {
    private List<String> images;
    private Map<String, Object> parameters;
    private String info;
}

服务调用实现

创建服务类处理实际的 API 调用，注意增加重试机制：

@Service
@Slf4j
public class StableDiffusionService {
    private final WebClient webClient;
    private final StableDiffusionConfig config;

    public Mono<TextToImageResponse> generateImage(TextToImageRequest request) {
        return webClient.post()
                .uri("/sdapi/v1/txt2img")
                .bodyValue(request)
                .retrieve()
                .bodyToMono(TextToImageResponse.class)
                .retryWhen(Retry.backoff(config.getMaxRetries(), Duration.ofSeconds(1))
                        .doOnError(e -> log.error("调用 Stable-Diffusion API 失败", e)));
    }
}

异步任务处理与性能优化

异步控制器设计

图像生成可能比较耗时，适合用异步处理。在 WebFlux 环境下直接使用 Mono 返回即可：

@RestController
@RequestMapping("/api/images")
public class ImageGenerationController {
    private final StableDiffusionService sdService;

    @PostMapping("/generate")
    public Mono<ResponseEntity<TextToImageResponse>> generateImage(@Valid @RequestBody TextToImageRequest request) {
        return sdService.generateImage(request)
                .map(response -> ResponseEntity.ok().header("X-Request-ID", UUID.randomUUID().toString()).body(response))
                .onErrorResume(WebClientResponseException.class, e -> Mono.just(ResponseEntity.status(e.getStatusCode()).body(new TextToImageResponse())))
                .timeout(Duration.ofSeconds(30));
    }
}

连接池优化

在高并发场景下，需要优化 HTTP 连接池：

@Bean
public HttpClient httpClient(StableDiffusionConfig config) {
    return HttpClient.create()
            .connectionProvider(ConnectionProvider.builder("sd-pool")
                    .maxConnections(100)
                    .pendingAcquireMaxCount(200)
                    .build())
            .responseTimeout(Duration.ofMillis(config.getTimeout()));
}

负载均衡与高可用

多实例配置

如果有多個 Stable-Diffusion 服务实例，可以通过配置实现负载均衡：

stable-diffusion:
  instances:
    - url: http://sd-instance1:7860
      weight: 1
    - url: http://sd-instance2:7860
      weight: 1
    - url: http://sd-instance3:7860
      weight: 2

负载均衡策略

实现简单的加权轮询负载均衡：

@Service
public class LoadBalancer {
    private final List<Instance> instances;
    private AtomicInteger counter = new AtomicInteger(0);

    public Instance getNextInstance() {
        // 简化的加权轮询实现
        int index = counter.getAndIncrement() % instances.size();
        return instances.get(index);
    }
}

全局异常处理

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(TimeoutException.class)
    public ResponseEntity<ErrorResponse> handleTimeout(TimeoutException e) {
        return ResponseEntity.status(HttpStatus.REQUEST_TIMEOUT)
                .body(new ErrorResponse("请求超时", "请稍后重试"));
    }

    @ExceptionHandler(WebClientResponseException.class)
    public ResponseEntity<ErrorResponse> handleWebClientError(WebClientResponseException e) {
        return ResponseEntity.status(e.getStatusCode())
                .body(new ErrorResponse("AI 服务调用失败", e.getResponseBodyAsString()));
    }
}

部署与监控

健康检查配置

添加健康检查端点监控 SD 服务状态：

@Component
public class StableDiffusionHealthIndicator implements HealthIndicator {
    private final WebClient webClient;

    @Override
    public Health health() {
        try {
            webClient.get()
                    .uri("/sdapi/v1/options")
                    .retrieve()
                    .toBodilessEntity()
                    .block(Duration.ofSeconds(5));
            return Health.up().build();
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}

监控指标

添加 Prometheus 监控指标：

@Bean
public MeterRegistryCustomizer<MeterRegistry> metricsCommonTags() {
    return registry -> registry.config().commonTags("application", "springboot-sd-integration");
}

实际使用建议

在实际项目中集成时，有几点经验值得分享：

首先是做好超时控制，图像生成时间不确定，设置合理的超时很重要。一般建议前端超时设置为 60-90 秒，后端服务间超时设置为 30 秒。

其次是重试机制要合理，不是所有失败都需要重试。像参数错误这种，重试也没用。主要是网络超时或服务暂时不可用时才需要重试。

还有就是要做好限流保护，避免一个用户请求太多把服务拖垮。可以用 Spring 的@RateLimiter 注解或者 Redis 实现分布式限流。

监控也很重要，要记录每次调用的耗时、成功失败情况。这样出问题时能快速定位是模型服务的问题还是网络问题。

总结

集成 Stable-Diffusion-3.5 到 SpringBoot 项目其实没有想象中复杂，核心就是通过 HTTP API 进行通信。关键是要设计好异步处理机制，避免阻塞线程，同时做好错误处理和监控。

在实际项目中，你可能还需要考虑图像缓存、批量处理、进度查询等功能。这些都可以在现有架构基础上扩展。

代码中的配置参数比如图像尺寸、生成步数等，最好做成可配置的，这样不同业务场景可以灵活调整。记得要加上合适的日志，方便排查问题。