Spring AI 实战：搭建 SaaS 模式多租户 AI 客服平台

/**
 * 租户上下文（核心类）
 * 基于 ThreadLocal 实现租户信息隔离，支持动态切换
 */
@Component
public class TenantContext {
    // 存储当前线程的租户 ID
    private static final ThreadLocal<String> TENANT_ID = new ThreadLocal<>();
    
    // 存储租户 ID -> 模型配置的映射（本地缓存，减轻 DB 压力）
    private static final LoadingCache<String, AiModelConfig> MODEL_CONFIG_CACHE = CacheBuilder.newBuilder()
            .expireAfterWrite(30, TimeUnit.MINUTES)
            .maximumSize(1000)
            .build(new CacheLoader<String, AiModelConfig>() {
                @Override
                public AiModelConfig load(String tenantId) {
                    // 从数据库加载租户的模型配置
                    return aiModelConfigService.getByTenantId(tenantId);
                }
            });

    @Autowired
    private AiModelConfigService aiModelConfigService;

    /**
     * 设置当前租户 ID
     */
    public static void setTenantId(String tenantId) {
        TENANT_ID.set(tenantId);
    }

    /**
     * 获取当前租户 ID
     */
    public static String getTenantId() {
        return TENANT_ID.get();
    }

    /**
     * 获取当前租户的模型配置
     */
    public AiModelConfig getCurrentModelConfig() {
        String tenantId = getTenantId();
        if (tenantId == null) {
            throw new BusinessException("租户 ID 不能为空");
        }
        try {
            return MODEL_CONFIG_CACHE.get(tenantId);
        } catch (Exception e) {
            throw new BusinessException("加载租户模型配置失败：" + e.getMessage());
        }
    }

    /**
     * 清除当前线程的租户上下文（关键：防止内存泄漏）
     */
    public static void clear() {
        TENANT_ID.remove();
    }
}

2.1.3 拦截器自动注入租户上下文

在请求入口拦截器中，从请求头 / Token 中解析租户 ID 并注入上下文：

/**
 * 租户拦截器：所有请求先解析租户 ID，注入 TenantContext
 */
@Component
public class TenantInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        // 从请求头获取租户 ID（实际项目中可从 JWT Token 解析）
        String tenantId = request.getHeader("X-Tenant-Id");
        if (StringUtils.isBlank(tenantId)) {
            response.setStatus(HttpStatus.UNAUTHORIZED.value());
            return false;
        }
        // 注入租户上下文
        TenantContext.setTenantId(tenantId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        // 关键：请求结束后清除上下文，防止 ThreadLocal 内存泄漏
        TenantContext.clear();
    }
}

// 注册拦截器
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Autowired
    private TenantInterceptor tenantInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(tenantInterceptor)
                .addPathPatterns("/api/**") // 拦截所有 API 请求
                .excludePathPatterns("/api/public/**"); // 排除公开接口
    }
}

2.1.4 Spring AI 动态切换模型配置

基于租户上下文的配置，动态构建 AI 客户端，实现多租户模型切换：

/**
 * AI 模型工厂：根据租户配置动态创建不同的 AI 客户端
 */
@Service
public class AiModelFactory {
    @Autowired
    private TenantContext tenantContext;

    /**
     * 获取当前租户的 AI 客户端
     */
    public AiClient getCurrentAiClient() {
        AiModelConfig config = tenantContext.getCurrentModelConfig();
        // 根据租户配置的模型类型，创建不同的 AI 客户端
        switch (config.getModelType()) {
            case "OPENAI":
                return createOpenAiClient(config);
            case "ERNIE":
                return createErnieClient(config);
            case "QIANWEN":
                return createQianWenClient(config);
            default:
                throw new BusinessException("不支持的模型类型：" + config.getModelType());
        }
    }

    // 创建 OpenAI 客户端
    private AiClient createOpenAiClient(AiModelConfig config) {
        OpenAiApi api = new OpenAiApi(config.getApiBaseUrl(), config.getApiKey());
        OpenAiChatClient client = new OpenAiChatClient(api);
        // 设置租户自定义的模型参数
        client.setTemperature(config.getTemperature());
        client.setTopP(config.getTopP());
        client.setModel(config.getModelName());
        return client;
    }

    // 文心一言客户端创建（略）
    private AiClient createErnieClient(AiModelConfig config) {
        // 实际项目中实现文心一言的客户端适配
        return null;
    }

    // 通义千问客户端创建（略）
    private AiClient createQianWenClient(AiModelConfig config) {
        // 实际项目中实现通义千问的客户端适配
        return null;
    }
}

2.1.5 实战踩坑与解决方案

2.2 租户级缓存：Redis 多数据库隔离方案

2.2.1 缓存隔离痛点

多租户场景下，若所有租户的缓存共用一个 Redis 库，会出现缓存 key 冲突、数据泄露、清理困难等问题。核心解决方案是 Redis 多数据库隔离：每个租户分配独立的 Redis DB（如租户 1 用 DB1，租户 2 用 DB2），同时保证缓存操作的透明化。

2.2.2 Redis 多库隔离设计

2.2.3 核心代码实现

1. 自定义 Redis 连接工厂，支持动态切换 DB：

/**
 * 动态 Redis 连接工厂：支持根据租户 ID 切换 Redis DB
 */
@Component
public class DynamicRedisConnectionFactory extends JedisConnectionFactory {
    /**
     * 切换 Redis DB
     * @param dbIndex DB 索引
     */
    public void switchDb(int dbIndex) {
        // 校验 DB 索引范围（Redis 默认 0-15）
        if (dbIndex < 0 || dbIndex > 15) {
            throw new BusinessException("Redis DB 索引超出范围：" + dbIndex);
        }
        // 关闭当前连接
        if (super.isActive()) {
            super.destroy();
        }
        // 设置新的 DB 索引
        super.setDatabase(dbIndex);
        // 重新初始化连接
        super.afterPropertiesSet();
    }
}

2. 租户缓存工具类，封装 DB 切换逻辑：

/**
 * 租户级 Redis 缓存工具类
 * 自动根据租户 ID 切换 Redis DB，对业务层透明
 */
@Component
public class TenantRedisTemplate {
    @Autowired
    private DynamicRedisConnectionFactory redisConnectionFactory;
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;

    // 租户 ID -> Redis DB 索引的映射规则（简单取模，可自定义）
    private int getDbIndex(String tenantId) {
        // 避免使用 DB0（默认库），从 DB1 开始分配
        return Math.abs(tenantId.hashCode()) % 15 + 1;
    }

    /**
     * 执行缓存操作（内部自动切换 DB）
     */
    public <T> T execute(RedisCallback<T> callback) {
        String tenantId = TenantContext.getTenantId();
        if (tenantId == null) {
            throw new BusinessException("租户 ID 为空，无法执行缓存操作");
        }
        // 切换 Redis DB
        int dbIndex = getDbIndex(tenantId);
        redisConnectionFactory.switchDb(dbIndex);
        // 执行缓存操作
        return redisTemplate.execute(callback);
    }

    // 封装常用缓存方法（示例：设置缓存）
    public void set(String key, Object value, long timeout, TimeUnit unit) {
        execute(connection -> {
            RedisSerializer<String> serializer = redisTemplate.getStringSerializer();
            byte[] keyBytes = serializer.serialize(key);
            byte[] valueBytes = redisTemplate.getValueSerializer().serialize(value);
            connection.setEx(keyBytes, unit.toSeconds(timeout), valueBytes);
            return null;
        });
    }

    // 封装获取缓存方法（略）
    public Object get(String key) {
        return execute(connection -> {
            RedisSerializer<String> serializer = redisTemplate.getStringSerializer();
            byte[] keyBytes = serializer.serialize(key);
            byte[] valueBytes = connection.get(keyBytes);
            return redisTemplate.getValueSerializer().deserialize(valueBytes);
        });
    }

    // 其他方法：del、expire 等（略）
}

3. 业务层使用示例：

// 业务层调用缓存，无需关心 DB 切换，工具类自动处理
@Service
public class PromptTemplateService {
    @Autowired
    private TenantRedisTemplate tenantRedisTemplate;

    public PromptTemplate getTemplate(String templateId) {
        // 从缓存获取
        String cacheKey = "prompt:template:" + templateId;
        PromptTemplate template = (PromptTemplate) tenantRedisTemplate.get(cacheKey);
        if (template != null) {
            return template;
        }
        // 缓存未命中，从 DB 加载
        template = promptTemplateMapper.selectById(templateId);
        // 存入缓存（过期时间 1 小时）
        tenantRedisTemplate.set(cacheKey, template, 1, TimeUnit.HOURS);
        return template;
    }
}

2.3 流量控制：Resilience4j 实现限流与降级

2.3.1 流量控制需求

AI 模型调用成本高、QPS 有限，需对每个租户进行限流（如单租户最大 QPS 10），同时在模型服务不可用时降级（返回预设话术），避免平台整体雪崩。

2.3.2 Resilience4j 核心配置

1. 引入依赖：

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-spring-boot3</artifactId>
    <version>2.1.0</version>
</dependency>
<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-ratelimiter</artifactId>
    <version>2.1.0</version>
</dependency>
<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-circuitbreaker</artifactId>
    <version>2.1.0</version>
</dependency>

2. 配置文件（application.yml）：

resilience4j:
  ratelimiter:
    instances:
      aiCallRateLimiter:
        limit-for-period: 10 # 单租户每周期最大请求数
        limit-refresh-period: 1s # 周期时间
        timeout-duration: 0 # 超出限流直接拒绝
        register-health-indicator: true
  circuitbreaker:
    instances:
      aiCallCircuitBreaker:
        failure-rate-threshold: 50 # 失败率阈值 50%
        wait-duration-in-open-state: 60s # 熔断后 60 秒尝试恢复
        sliding-window-size: 100 # 滑动窗口大小
        register-health-indicator: true

3. 自定义租户限流管理器：

/**
 * 租户级限流管理器：每个租户独立的限流计数器
 */
@Component
public class TenantRateLimiterManager {
    // 存储租户 ID -> 限流器的映射
    private final Map<String, RateLimiter> rateLimiterMap = new ConcurrentHashMap<>();

    @Autowired
    private RateLimiterRegistry rateLimiterRegistry;

    /**
     * 获取当前租户的限流器
     */
    public RateLimiter getCurrentRateLimiter() {
        String tenantId = TenantContext.getTenantId();
        // 不存在则创建
        return rateLimiterMap.computeIfAbsent(tenantId, key -> {
            // 基于配置创建限流器
            RateLimiterConfig config = rateLimiterRegistry.getConfiguration("aiCallRateLimiter")
                    .orElse(RateLimiterConfig.ofDefaults());
            return RateLimiter.of(key, config);
        });
    }

    /**
     * 执行限流操作
     */
    public <T> T executeRateLimitedSupplier(Supplier<T> supplier) {
        RateLimiter rateLimiter = getCurrentRateLimiter();
        // 限流包装
        return RateLimiter.decorateSupplier(rateLimiter, supplier).get();
    }
}

4. 限流 + 熔断实战代码：

/**
 * AI 客服核心服务：整合限流、熔断、动态模型调用
 */
@Service
public class AiCustomerService {
    @Autowired
    private AiModelFactory aiModelFactory;
    @Autowired
    private TenantRateLimiterManager rateLimiterManager;
    @Autowired
    private CircuitBreakerRegistry circuitBreakerRegistry;

    /**
     * 调用 AI 模型生成回复（核心方法）
     */
    public String generateReply(String userQuestion) {
        // 1. 限流控制（租户级）
        return rateLimiterManager.executeRateLimitedSupplier(() -> {
            // 2. 熔断控制
            CircuitBreaker circuitBreaker = circuitBreakerRegistry.circuitBreaker("aiCallCircuitBreaker");
            return CircuitBreaker.decorateSupplier(circuitBreaker, () -> {
                // 3. 获取当前租户的 AI 客户端
                AiClient aiClient = aiModelFactory.getCurrentAiClient();
                // 4. 构建 Prompt（后续模板管理会详细讲）
                Prompt prompt = new Prompt(new UserMessage(userQuestion));
                // 5. 调用 AI 模型
                AiResponse response = aiClient.generate(prompt);
                return response.getGeneration().getText();
            }).get();
        });
    }

    /**
     * 降级方法：限流/熔断/模型调用失败时触发
     */
    public String fallback(String userQuestion, Exception e) {
        if (e instanceof RequestNotPermitted) {
            return "当前咨询人数过多，请稍后再试（租户限流）";
        } else if (e instanceof CircuitBreakerOpenException) {
            return "AI 服务暂时不可用，请稍后再试（服务熔断）";
        } else {
            return "非常抱歉，暂时无法为您解答，请联系人工客服";
        }
    }
}

三、核心功能实现

3.1 话术模板管理：租户自定义 Prompt 模板

3.1.1 需求分析

每个租户需要自定义 AI 客服的话术模板（如售前模板、售后模板），模板支持变量替换（如 {{tenantName}}、{{userName}}），同时支持模板的 CRUD 操作。

3.1.2 表结构设计

CREATE TABLE `prompt_template` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键',
  `tenant_id` varchar(64) NOT NULL COMMENT '租户 ID',
  `template_name` varchar(128) NOT NULL COMMENT '模板名称',
  `template_type` varchar(32) NOT NULL COMMENT '模板类型（售前/售后）',
  `template_content` text NOT NULL COMMENT '模板内容（FreeMarker 语法）',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  KEY `idx_tenant_id` (`tenant_id`) COMMENT '租户 ID 索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='租户 Prompt 模板表';

3.1.3 模板渲染核心代码

/**
 * Prompt 模板引擎：支持租户自定义模板 + 变量替换
 */
@Service
public class PromptTemplateEngine {
    @Autowired
    private FreeMarkerConfigurer freeMarkerConfigurer;
    @Autowired
    private PromptTemplateMapper promptTemplateMapper;

    /**
     * 渲染模板
     * @param templateType 模板类型
     * @param variables 变量（如 tenantName、userName 等）
     */
    public String renderTemplate(String templateType, Map<String, Object> variables) {
        String tenantId = TenantContext.getTenantId();
        // 1. 查询当前租户的模板
        PromptTemplate template = promptTemplateMapper.selectByTenantIdAndType(tenantId, templateType);
        if (template == null) {
            throw new BusinessException("租户未配置 [" + templateType + "] 类型的 Prompt 模板");
        }
        // 2. FreeMarker 渲染模板
        try {
            Template fmTemplate = new Template("promptTemplate", new StringReader(template.getTemplateContent()), freeMarkerConfigurer.getConfiguration());
            StringWriter writer = new StringWriter();
            fmTemplate.process(variables, writer);
            return writer.toString();
        } catch (Exception e) {
            throw new BusinessException("模板渲染失败：" + e.getMessage());
        }
    }

    // 模板 CRUD 方法（略）
    public void saveTemplate(PromptTemplate template) {
        template.setTenantId(TenantContext.getTenantId());
        promptTemplateMapper.insert(template);
    }
}

3.1.4 模板使用示例

// 业务层调用模板引擎
@Service
public class AiCustomerService {
    @Autowired
    private PromptTemplateEngine templateEngine;

    public String generateReply(String userQuestion, String userName) {
        // 1. 构建模板变量
        Map<String, Object> variables = new HashMap<>();
        variables.put("userQuestion", userQuestion);
        variables.put("userName", userName);
        variables.put("tenantName", "某电商企业"); // 从租户配置中获取
        // 2. 渲染售后模板
        String promptContent = templateEngine.renderTemplate("after_sale", variables);
        // 3. 调用 AI 模型
        Prompt prompt = new Prompt(new UserMessage(promptContent));
        AiClient aiClient = aiModelFactory.getCurrentAiClient();
        AiResponse response = aiClient.generate(prompt);
        return response.getGeneration().getText();
    }
}

3.2 对话记录分析：AI 驱动的客服质量评分

3.2.1 评分逻辑设计

基于用户与 AI 的对话记录，调用大模型对回复准确性、语气友好度、解决率三个维度进行评分（1-5 分），最终生成综合评分，帮助租户分析客服质量。

3.2.2 核心实现代码

/**
 * 对话质量评分服务：AI 驱动的多维度评分
 */
@Service
public class ConversationScoreService {
    @Autowired
    private AiModelFactory aiModelFactory;
    @Autowired
    private ConversationRecordMapper conversationRecordMapper;

    /**
     * 对对话记录进行评分
     */
    public ConversationScore scoreConversation(Long conversationId) {
        String tenantId = TenantContext.getTenantId();
        // 1. 查询对话记录
        ConversationRecord record = conversationRecordMapper.selectById(conversationId);
        if (!tenantId.equals(record.getTenantId())) {
            throw new BusinessException("无权限访问该对话记录");
        }
        // 2. 构建评分 Prompt
        String scorePrompt = "请对以下 AI 客服对话进行质量评分，评分规则：\n" +
                "1. 回复准确性：1-5 分，回复是否准确解答用户问题\n" +
                "2. 语气友好度：1-5 分，回复语气是否友好、专业\n" +
                "3. 解决率：1-5 分，是否有效解决用户问题\n" +
                "输出格式为 JSON：{\"accuracy\": 5, \"friendliness\": 4, \"solveRate\": 5, \"totalScore\": 4.7}\n" +
                "对话内容：\n" +
                "用户问题：%s\n" +
                "AI 回复：%s".formatted(record.getUserQuestion(), record.getAiReply());
        // 3. 调用 AI 模型评分
        AiClient aiClient = aiModelFactory.getCurrentAiClient();
        Prompt prompt = new Prompt(new UserMessage(scorePrompt));
        AiResponse response = aiClient.generate(prompt);
        String scoreJson = response.getGeneration().getText();
        // 4. 解析评分结果
        ObjectMapper objectMapper = new ObjectMapper();
        ConversationScore score = objectMapper.readValue(scoreJson, ConversationScore.class);
        // 5. 保存评分结果
        score.setConversationId(conversationId);
        score.setTenantId(tenantId);
        conversationScoreMapper.insert(score);
        return score;
    }
}

3.3 性能压测：100 租户并发场景优化实践

3.3.1 压测环境与工具

• 压测工具：JMeter 5.6
• 压测场景：模拟 100 个租户，每个租户 10 个并发用户，持续调用 AI 客服接口 10 分钟
• 服务器配置：4 核 8G 云服务器，Redis 7.0（单机），MySQL 8.0（单机）

3.3.2 初始压测结果与瓶颈分析

3.3.3 核心优化方案

1. AI 回复缓存优化：

// 对相同问题的 AI 回复进行缓存（租户级）
@Service
public class AiCustomerService {
    @Autowired
    private TenantRedisTemplate tenantRedisTemplate;

    public String generateReply(String userQuestion) {
        // 1. 构建缓存 Key（租户级）
        String cacheKey = "ai:reply:" + DigestUtils.md5DigestAsHex(userQuestion.getBytes());
        // 2. 先查缓存
        Object cacheValue = tenantRedisTemplate.get(cacheKey);
        if (cacheValue != null) {
            return cacheValue.toString();
        }
        // 3. 调用 AI 模型（省略限流/熔断逻辑）
        String reply = doGenerateReply(userQuestion);
        // 4. 存入缓存（过期时间 5 分钟，兼顾性能和实时性）
        tenantRedisTemplate.set(cacheKey, reply, 5, TimeUnit.MINUTES);
        return reply;
    }
}

2. MySQL 分表优化：对话记录表按租户 ID 分表（conversation_record_${tenantId % 10}），减少单表数据量，提升查询性能。
3. 连接池优化：

# 数据库连接池优化
spring:
  datasource:
    hikari:
      maximum-pool-size: 50 # 最大连接数
      minimum-idle: 10 # 最小空闲连接
      idle-timeout: 300000 # 空闲超时时间
      connection-timeout: 20000 # 连接超时时间
# Redis 连接池优化
redis:
  jedis:
    pool:
      max-active: 100
      max-idle: 20
      min-idle: 5
      max-wait: 2000ms

3.3.4 优化后压测结果

四、实战踩坑与解决方案汇总

五、总结与进阶规划

5.1 核心总结

1. 多租户隔离：基于 ThreadLocal 实现 TenantContext 动态切换租户信息，Redis 多数据库隔离保证缓存安全，是 SaaS 平台的核心基础；
2. 流量管控：Resilience4j 实现租户级限流 + 熔断，避免单租户滥用资源导致平台雪崩；
3. 功能定制化：FreeMarker 模板引擎支持租户自定义 Prompt，满足不同行业的话术需求；
4. 性能优化：AI 回复缓存、MySQL 分表、连接池调优，是支撑 100 租户并发的关键；

5.2 进阶规划

1. 模型私有化部署：支持租户私有化部署 AI 模型，降低 API 调用成本，提升数据安全性；
2. 多模型融合：实现多模型调用结果融合，提升回复准确性（如 GPT + 文心一言）；
3. 监控可视化：基于 Prometheus+Grafana 搭建租户级监控面板，实时监控 QPS、响应时间、错误率；
4. 成本管控：统计每个租户的 AI 模型调用次数，实现按量计费；
5. 国际化支持：适配多语言模板，支持海外租户接入。