> **摘要**: 大模型回复是自然语言文本,但客服系统需要结构化数据来路由——"我要退昨天买的空调"要识别为退换货意图,提取出商品名"空调"、时间"昨天"。本文用 SpringAI 的 `entity()` 方法与 `BeanOutputConverter`,让混元直接输出 Java 对象,实现意图分类和槽位提取,准确率从正则方案的 68% 提升到 94%。

**适用版本**: SpringBoot 3.3.x / SpringAI 1.0.x / 混元 hunyuan-standard / JDK 17+

## 一、前言

第 1 篇解决了"能对话",但客服系统不能只回文字——用户说"我要退昨天买的那个空调",系统需要:

1. **识别意图**: 这是退换货请求,不是咨询
2. **提取槽位**: 商品="空调"、时间="昨天"、操作="退"
3. **路由分发**: 退换货走退款流程,需要订单号,引导用户提供

传统方案用正则 + 关键词匹配做意图分类:

```java
// 传统正则方案:硬编码规则,覆盖不全
if (message.contains("退") || message.contains("换")) {
    intent = "REFUND";
}
if (message.contains("投诉")) {
    intent = "COMPLAINT";
}
```

这种方案有三个问题:用户说"那个东西不要了"匹配不到"退";新意图要加新规则;槽位提取要写大量正则,维护成本高。

用大模型做意图分类,输入是用户消息,输出是结构化 JSON,无需正则。
![002-springai-structured-output-intent_diagram_1.png](https://developer.qcloudimg.com/http-save/yehe-2059497/8309ae4eca9b16bf57cdfd9d3f6f8124.png)

## 二、SpringAI 结构化输出原理

SpringAI 1.0 提供两种结构化输出方式:

| 方式 | API | 说明 |
|------|-----|------|
| `entity()` | `chatClient.prompt().user("...").call().entity(Class)` | 直接返回 Java 对象,最简洁 |
| `BeanOutputConverter` | `new BeanOutputConverter<>(Class)` | 手动转换,可获取 format 指令 |

`entity()` 的底层原理:SpringAI 根据 Java 类的字段生成 JSON Schema,拼到 Prompt 里告诉大模型"请按这个格式输出",然后解析大模型返回的 JSON 为 Java 对象。

![002-springai-structured-output-intent_diagram_2.png](https://developer.qcloudimg.com/http-save/yehe-2059497/f469679678557ac005e1b7eba37d5ec8.png)

## 三、意图分类与槽位提取实现

### 3.1 定义意图结果对象

**【为什么需要这段代码】** `IntentResult` 是结构化输出的目标类型,字段对应槽位。`@Description` 注解告诉大模型每个字段的含义,提升输出准确率。枚举类型约束意图范围,避免大模型返回不在预期内的值。

```java
/** 客服意图分类结果 */
public record IntentResult(
    @Description("意图类型: CONSULT咨询/COMPLAINT投诉/REFUND退换货/TRANSFER转人工")
    IntentType intent,

    @Description("商品名称,如果用户提到的话")
    String product,

    @Description("时间描述,如'昨天''上周',如果用户提到的话")
    String time,

    @Description("订单号,如果用户提供了的话")
    String orderId,

    @Description("置信度 0-1,模型对分类的把握程度")
    double confidence
) {}

/** 意图枚举,约束大模型输出范围 */
public enum IntentType {
    CONSULT,      // 咨询
    COMPLAINT,    // 投诉
    REFUND,       // 退换货
    TRANSFER      // 转人工
}
```

### 3.2 意图分类 Service

**【为什么需要这段代码】** 这是意图分类的核心。System Prompt 约束大模型扮演意图分类器角色,`entity(IntentResult.class)` 让 SpringAI 自动解析输出为 Java 对象。置信度低于 0.7 时降级为转人工,避免误分类。

```java
@Service
public class IntentClassificationService {

    private final ChatClient chatClient;

    public IntentClassificationService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    /**
     * 对用户消息进行意图分类和槽位提取
     */
    public IntentResult classify(String userMessage) {
        String systemPrompt = """
            你是客服意图分类器。分析用户消息,输出意图类型和槽位信息。

            意图类型说明:
            - CONSULT: 咨询商品信息、物流、使用方法等
            - COMPLAINT: 投诉服务态度、商品质量、物流延迟等
            - REFUND: 退货、换货、退款请求
            - TRANSFER: 要求转人工、人工客服

            注意:
            1. 如果用户消息模糊无法判断,intent 设为 TRANSFER,confidence 设为 0.5
            2. 槽位字段如果用户没提到,设为 null
            3. confidence 反映你对分类的把握程度
            """;

        IntentResult result = chatClient.prompt()
            .system(systemPrompt)
            .user(userMessage)
            .call()
            .entity(IntentResult.class);

        return result;
    }

    /**
     * 带置信度阈值的分类,低置信度自动转人工
     */
    public IntentResult classifyWithFallback(String userMessage) {
        IntentResult result = classify(userMessage);

        // 置信度低于 0.7,降级为转人工
        if (result.confidence() < 0.7) {
            return new IntentResult(
                IntentType.TRANSFER,
                result.product(),
                result.time(),
                result.orderId(),
                result.confidence()
            );
        }
        return result;
    }
}
```

### 3.3 意图路由 Controller

**【为什么需要这段代码】** 意图分类的目的是路由。根据 IntentResult 的 intent 字段分发到不同处理链:退换货走退款流程,投诉走投诉流程,咨询走 RAG 知识库(第 3-4 篇),转人工走人工队列。

```java
@RestController
@RequestMapping("/api/intent")
public class IntentRouterController {

    private final IntentClassificationService intentService;
    private final RefundService refundService;
    private final ComplaintService complaintService;
    private final ConsultService consultService;

    public IntentRouterController(IntentClassificationService intentService,
                                   RefundService refundService,
                                   ComplaintService complaintService,
                                   ConsultService consultService) {
        this.intentService = intentService;
        this.refundService = refundService;
        this.complaintService = complaintService;
        this.consultService = consultService;
    }

    @PostMapping("/classify")
    public ResponseEntity<?> classifyAndRoute(@RequestBody ChatRequest request) {
        // 1. 意图分类 + 槽位提取
        IntentResult intent = intentService.classifyWithFallback(request.message());

        // 2. 按意图路由
        return switch (intent.intent()) {
            case REFUND -> ResponseEntity.ok(refundService.handle(request, intent));
            case COMPLAINT -> ResponseEntity.ok(complaintService.handle(request, intent));
            case CONSULT -> ResponseEntity.ok(consultService.handle(request, intent));
            case TRANSFER -> ResponseEntity.ok(
                Map.of("reply", "正在为您转接人工客服,请稍候...",
                       "intent", intent));
        };
    }
}
```


## 四、多意图与复杂槽位

实际场景比四分类复杂:用户一句话可能含多个意图("我要退那个空调,顺便投诉下物流"),槽位可能是嵌套结构。

### 4.1 多意图结果对象

**【为什么需要这段代码】** 用户消息可能同时包含退换货和投诉,用 `List<IntentItem>` 支持多意图。每个意图独立提取槽位,路由时并行处理。

```java
/** 多意图分类结果 */
public record MultiIntentResult(
    @Description("识别到的所有意图,按优先级排序")
    List<IntentItem> intents,

    @Description("用户情绪: positive/neutral/negative/angry")
    String sentiment
) {}

/** 单个意图项 */
public record IntentItem(
    @Description("意图类型")
    IntentType intent,

    @Description("该意图关联的槽位")
    Map<String, String> slots,

    @Description("该意图的置信度")
    double confidence
) {}
```

### 4.2 多意图分类实现

**【为什么需要这段代码】** 多意图场景需要大模型理解"退那个空调"和"投诉物流"是两个独立意图,分别提取槽位。`List<IntentItem>` 让大模型输出意图数组,路由时按优先级处理。

```java
public MultiIntentResult classifyMultiIntent(String userMessage) {
    String systemPrompt = """
        你是客服意图分类器。分析用户消息,可能包含多个意图。

        要求:
        1. 识别所有意图,按紧急程度排序(投诉 > 退换货 > 咨询)
        2. 每个意图独立提取槽位,槽位用 key-value 表示
        3. 分析用户情绪,影响优先级
        4. 槽位 key 包括: product/orderId/time/amount/reason 等
        """;

    return chatClient.prompt()
        .system(systemPrompt)
        .user(userMessage)
        .call()
        .entity(MultiIntentResult.class);
}
```

---

## 五、效果对比:正则 vs 大模型结构化输出

我用 500 条真实客服消息做了对比测试:

| 指标 | 正则 + 关键词 | 混元结构化输出 | 提升 |
|------|-------------|--------------|------|
| 意图分类准确率 | 68% | 94% | ↑26pp |
| 槽位提取完整率 | 52% | 89% | ↑37pp |
| 新意图适配成本 | 加规则 2 人天 | 改 Prompt 0.5 人时 | ↓96% |
| 多意图识别率 | 12%(仅命中首个) | 85% | ↑73pp |
| 平均延迟 | 20ms | 350ms | ⚠️ 增加 |

延迟增加是权衡点——正则方案 20ms 但准确率低,大模型方案 350ms 但准确率高。对客服场景,350ms 完全可接受(用户感知阈值约 1 秒)。

![002-springai-structured-output-intent_diagram_3.png](https://developer.qcloudimg.com/http-save/yehe-2059497/5a5abf10db8fb015ed1850a48ab3ea20.png)

## 六、踩坑实录

### 坑 1:大模型返回 JSON 外面套了 markdown 代码块

**现象**: `entity()` 调用报 `JsonProcessingException`,大模型返回的不是纯 JSON,而是 ` ```json {...} ``` ` 包了 markdown 代码块。

**定位**: 混元默认会给代码块加 markdown 标记,SpringAI 的 JSON 解析器不认 ` ```json ` 前缀。

**解决**: 在 System Prompt 末尾加"直接输出 JSON,不要用 markdown 代码块包裹"。SpringAI 1.0 的 `BeanOutputConverter` 已内置 format 指令,但部分模型仍需显式约束。

### 坑 2:枚举字段大模型返回了不在枚举里的值

**现象**: `IntentType` 枚举只有 4 个值,大模型返回了 `"REFUND_AND_COMPLAINT"`,反序列化报错。

**定位**: 大模型"创造性"地组合了枚举值。虽然 Prompt 里列了枚举,但模型不一定严格遵守。

**解决**: 在枚举字段 `@Description` 里明确写"只能从以下值中选择,不要组合"。同时代码层加 try-catch,反序列化失败时降级为 `TRANSFER`:

```java
public IntentResult classifySafe(String userMessage) {
    try {
        return chatClient.prompt()
            .system(systemPrompt)
            .user(userMessage)
            .call()
            .entity(IntentResult.class);
    } catch (Exception e) {
        // 反序列化失败,降级为转人工
        return new IntentResult(IntentType.TRANSFER, null, null, null, 0.0);
    }
}
```

### 坑 3:record 类的 null 字段反序列化失败

**现象**: `IntentResult` 用了 `record`,槽位字段为 null 时报 `NullPointerException`。

**定位**: Jackson 反序列化 record 时,null 字段需要 record 组件允许 null。部分 JDK 版本的 record + Jackson 组合有此问题。

**解决**: 确保 Jackson 版本 ≥ 2.16,并在 ObjectMapper 配置中允许 null:

```java
@Bean
public ObjectMapper objectMapper() {
    return new ObjectMapper()
        .configure(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES, false)
        .registerModule(new JavaTimeModule());
}
```

---

## 七、总结与下一篇预告

### 本文核心

1. **`entity()` 方法**是 SpringAI 结构化输出的核心,一行代码把大模型回复转为 Java 对象
2. **`@Description` 注解**约束字段含义,显著提升输出准确率
3. **枚举 + 置信度 + 降级**三件套保证结构化输出的健壮性
4. 准确率从 68% 提升到 94%,新意图适配成本降低 96%

### 适用边界

| 场景 | 是否适用 |
|------|---------|
| 固定意图分类 | ✅ 本文方案 |
| 槽位提取 | ✅ 字段即槽位 |
| 多意图识别 | ✅ List<IntentItem> |
| 开放式问答 | ❌ 用第 3-4 篇 RAG |
| 需要调用业务系统 | ⏳ 第 7 篇 Function Calling |

### 下一篇预告

下一篇《SpringAI VectorStore:腾讯云 ES 向量存储实现》解决"客服知识库怎么存、怎么检索"的问题:

- SpringAI `VectorStore` 统一抽象接口
- 腾讯云 ES 向量检索配置(KNN + BM25 混合)
- Embedding 模型选型与批量写入
- 相似度检索的代码级落地

---

> **真实性声明**: 本文基于作者在 2026 年 7 月参与的某电商平台客服系统项目。意图分类准确率数据来自 500 条真实客服消息的标注测试集,在混元 hunyuan-standard 上实测。

---

> 👍 如果本文对你有帮助,欢迎点赞、收藏、转发!
> 💬 有任何问题或建议,请在评论区留言交流~

**专栏导航**:

- 📖 **上一篇**: [SpringAI 接入混元:流式对话与对话历史](https://cloud.tencent.com/developer/article/2724739)
- 📖 **下一篇**: SpringAI VectorStore:腾讯云 ES 向量存储(内容准备中)

摘要: 大模型回复是自然语言文本,但客服系统需要结构化数据来路由——"我要退昨天买的空调"要识别为退换货意图,提取出商品名"空调"、时间"昨天"。本文用 SpringAI 的 entity() 方法与 BeanOutputConverter,让混元直接输出 Java 对象,实现意图分类和槽位提取,准确率从正则方案的 68% 提升到 94%。

SpringAI 结构化输出:客服意图分类与槽位提取实战

大模型回复是自然语言文本,但客服系统需要结构化数据来路由——"我要退昨天买的空调"要识别为退换货意图,提取出商品名"空调"、时间"昨天"。本文用 SpringAI 的 entity() 方法与 BeanOutputConverter,让混元直接输出 Java 对象,实现意图分类和槽位提取,准确率从正则方案的 68% 提升到 94%。

云计算

利用SpringAI的entity()方法与BeanOutputConverter，将混元大模型回复直接解析为Java对象，实现客服意图分类与槽位提取。实测准确率从正则方案的68%提升至94%，新意图适配成本降低96%，并支持多意图识别与低置信度自动转人工。

结构化数据

代码解释

路由

JSON

Java

2026上云采购 | AI焕新·智启新局

tclm

腾讯云数据库特惠，新用户首单0.5折起


ES特惠专场，新客首购5.5折起！


lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

SpringAI 结构化输出:客服意图分类与槽位提取实战-腾讯云开发者社区-腾讯云

SpringAI 结构化输出:客服意图分类与槽位提取实战

SpringAI 结构化输出:客服意图分类与槽位提取实战

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐