CH 11综合项目：企业知识问答 + 工单辅助系统

11.1需求与业务场景

先讲一个真实的业务痛点

讲综合项目，先讲清楚「为谁解决什么问题」——学生最容易一上来就堆技术，却说不清业务价值。下面用「智汇科技」客服团队的真实困境与可量化目标，作为整个项目的需求锚点。

用户角色与核心诉求

为什么先列角色？因为不同角色关心的能力完全不同——知识库管理员关心「能不能一键重建索引」，运维关心「健康检查和成本」，客服主管关心「效果看板」。架构设计必须回应每个角色的核心诉求，否则做出来的系统没人用。

动手：用一句话画出项目边界（课前热身）

在动手写第一行代码之前，先用纸笔把「这个项目不做什么」写下来——边界比功能更重要，它决定了你后面不会被「再加个小功能」拖垮。

1. 打开一张纸，中间写「企业知识问答 + 工单辅助系统」。
2. 左侧列「做」：制度问答、多轮记忆、订单查询、工单辅助、知识库管理、可观测。
3. 右侧列「不做」：不替代人工最终决策（高风险必须确认）、不做多轮复杂谈判、不接第三方支付（只查不付）。
4. 把右侧三条念一遍——答辩时如果有人让你「顺手加个自动退款」，你就用这三条挡回去。

11.2功能清单与验收标准

功能模块（P0 必须做，P1 加分）

为什么用 P0/P1/P2 分级？因为期末项目时间有限，必须让学生先保证「核心闭环能跑通」，再谈加分项。P0 是经过裁剪的最小可用产品（MVP），覆盖「问答—记忆—查单—建单—可观测」主链路；P1/P2 是体现区分度的加分项。

验收标准（对应大纲「产物验收标准」）

成对概念：开发验收 vs 上线验收

为什么要把「验收」分成两道？很多学生认为「我本地能跑、答辩过了」就完了，结果一上线就崩。开发验收看的是「功能对不对」，上线验收看的是「扛不扛得住、出事会不会炸」——两者标准完全不同。

11.3总体架构设计

分层架构

为什么分层？分层把「请求如何进来」「如何决策路由」「如何执行各业务链路」「依赖哪些能力」「跑在什么基础设施上」解耦开。这样每一层都能独立测试、独立扩展——比如把 pgvector 换成 Milvus，只动基础设施层，编排层完全不用改。

模块划分（工程结构）

课堂作业用单模块 + 分包就够，不要一上来拆多模块。下面给出两种工程结构，先按「单模块分包」落地，等真的需要独立部署再拆。

springai-lab/                         # 推荐：单模块 + 分包
├── pom.xml
├── docker-compose.yml
├── init/pgvector-init.sql
└── src/main/java/com/example/springai/
    ├── SpringAiLabApplication.java
    ├── common/                       # 全局配置、异常、Advisor
    ├── orchestrator/                 # 编排层：意图识别 + 路由
    ├── rag/                          # 知识检索与问答
    ├── tools/                        # 本地工具：订单 / 工单
    ├── agent/                        # 智能体 + HITL
    ├── controller/                   # 网关层
    └── repo/                         # 数据访问

# 进阶（多人协作 / 独立部署时）才拆多模块：
springai-lab/
├── springai-common/   # 公共配置
├── springai-rag/      # 知识检索模块
├── springai-agent/    # 智能体模块
├── springai-tools/    # 工具模块
├── springai-eval/     # 评测模块
└── springai-app/      # 启动模块

动手：从零搭出工程骨架（先让应用跑起来）

本章无配套 lab 代码，按「自建」口径操作：所有包、类、配置文件都自己建，代码块照抄本节后面给出的源码。下面这一步的目标是先把空壳应用跑起来，后面每加一块能力都基于它验证。

1. 打开 start.spring.io，按下表选择并 Generate 下载 zip，解压后用 IDEA 打开：

   选项	选择
   Project / Language	Maven / Java
   Spring Boot	4.1.x（不要 3.x，不要 SNAPSHOT）
   Group / Artifact	com.example / springai-lab
   Java	17
   Dependencies	Spring Web + Spring AI Model Chat OpenAI + Spring Data JPA + Spring Data Redis + Actuator

2. 打开 pom.xml，在 <properties> 旁加入 spring-ai-bom 的 dependencyManagement 段（统一管理版本，避免各 starter 版本打架），并补上本项目的依赖。完整片段如下，直接覆盖 / 合并进你的 pom.xml：

   <?xml version="1.0" encoding="UTF-8"?>
   <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
            https://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <parent>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-parent</artifactId>
       <version>4.1.1</version>
       <relativePath/>
     </parent>
   
     <groupId>com.example</groupId>
     <artifactId>springai-lab</artifactId>
     <version>0.0.1-SNAPSHOT</version>
   
     <properties>
       <java.version>17</java.version>
       <spring-ai.version>2.0.1</spring-ai.version>
     </properties>
   
     <!-- ★ 统一锁死 Spring AI 版本，所有 ai starter 都从这里取 -->
     <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>org.springframework.ai</groupId>
           <artifactId>spring-ai-bom</artifactId>
           <version>${spring-ai.version}</version>
           <type>pom</type>
           <scope>import</scope>
         </dependency>
       </dependencies>
     </dependencyManagement>
   
     <dependencies>
       <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-web</artifactId>
       </dependency>
       <!-- ① 模型：DeepSeek 走 OpenAI 兼容协议 -->
       <dependency>
         <groupId>org.springframework.ai</groupId>
         <artifactId>spring-ai-starter-model-openai</artifactId>
       </dependency>
       <!-- ② RAG 召回顾问 QuestionAnswerAdvisor 所在包 -->
       <dependency>
         <groupId>org.springframework.ai</groupId>
         <artifactId>spring-ai-advisors-vector-store</artifactId>
       </dependency>
       <!-- ③ 向量库：PostgreSQL + pgvector -->
       <dependency>
         <groupId>org.springframework.ai</groupId>
         <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
       </dependency>
       <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-data-jpa</artifactId>
       </dependency>
       <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-data-redis</artifactId>
       </dependency>
       <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-actuator</artifactId>
       </dependency>
       <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-validation</artifactId>
       </dependency>
     </dependencies>
   </project>

   粘贴位置：整个文件以 <?xml ...> 开头，直接替换 Initializr 生成的 pom.xml 即可。

3. 在 src/main/resources/ 下新建 application.yml，粘贴以下配置（密钥一律占位符，绝不硬编码）：

   server:
     port: 8080
   
   spring:
     application:
       name: springai-lab
     ai:
       openai:
         # DeepSeek 兼容 OpenAI 协议；密钥从环境变量读，冒号后留空表示无默认值
         api-key: ${DEEPSEEK_API_KEY:}
         base-url: https://api.deepseek.com
         chat:
           # ★ 只有 chat 下才有 options 层级，embedding 没有
           options:
             model: deepseek-chat
             temperature: 0.7
     datasource:
       url: jdbc:mysql://localhost:3306/springai_lab?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&useSSL=false
       username: root
       password: root123456
     data:
       redis:
         host: localhost
         port: 6379
   
   management:
     endpoints:
       web:
         exposure:
           include: health, prometheus, info
     zipkin:
       tracing:
         endpoint: http://localhost:9411/api/v2/spans

   粘贴位置：src/main/resources/application.yml。若文件已存在同名项，以这一段为准。

4. 在 com.example.springai 包下确认启动类存在（Initializr 已生成 SpringAiLabApplication）。右键 com.example.springai → New → Package，依次新建 common、orchestrator、rag、tools、agent、controller、repo 七个空包，先不用填内容。

5. 确保环境变量 DEEPSEEK_API_KEY 已设置（见第 0 章 0.6 节），重开 IDEA 使之生效。然后启动应用：

   # 在终端进入项目根目录（pom.xml 所在目录）
   mvn spring-boot:run

运行验证 ①：空壳应用能起来

# 另开一个终端，确认健康检查返回 UP
curl -s http://localhost:8080/actuator/health
# 期望输出（节选）：
# {"status":"UP","components":{"db":{"status":"UP"},"redis":{"status":"UP"},
#  "discoveryComposite":{"status":"UP"} ...}}

看到什么算通过：终端打印 Started SpringAiLabApplication，且 /actuator/health 返回 status: "UP"（数据库 / Redis 此时若未起，先只验证应用进程起来了也行，但后续章节需要它们）。

知识点揉碎：分模块组装顺序

成对概念：RAG 链路 vs 工单链路

为什么把它们放在一起对比？因为这两条是项目里最典型的两类链路，一个「只读不写」，一个「写且要人确认」，理解差异才能正确设计安全边界。

11.4数据模型设计

① MySQL：业务数据

为什么设计这么细的表？因为综合项目要「可验收、可审计」——每一张表背后都对应一个验收点：ticket 表对应「工单可复查」、pending_action 表对应「HITL 安全」、qa_audit 表对应「成本核算」、agent_trace 表对应「Agent 可观测」。下面逐表给出建表 SQL，注意索引是为查询场景服务的，不是随手加的。

-- ============================================================
-- 1. 知识库文档（记录文档元信息与索引状态）
-- ============================================================
CREATE TABLE kb_document (
    id            BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id     VARCHAR(64)  NOT NULL,
    file_name     VARCHAR(255) NOT NULL,
    category      VARCHAR(64)  DEFAULT '未分类',
    file_hash     CHAR(64)     NOT NULL COMMENT 'SHA-256，用于判断内容是否变化',
    chunk_count   INT          DEFAULT 0,
    status        VARCHAR(20)  DEFAULT 'PENDING' COMMENT 'PENDING/INDEXED/FAILED',
    indexed_at    DATETIME     NULL,
    created_at    DATETIME     DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_tenant_file (tenant_id, file_name),
    KEY idx_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 2. 会话（用于会话列表、归属校验、统计）
CREATE TABLE chat_session (
    id            BIGINT AUTO_INCREMENT PRIMARY KEY,
    session_id    VARCHAR(64)  NOT NULL COMMENT '服务端生成的 UUID',
    tenant_id     VARCHAR(64)  NOT NULL,
    user_id       VARCHAR(64)  NOT NULL,
    title         VARCHAR(128) COMMENT '由首轮问题自动生成',
    message_count INT          DEFAULT 0,
    last_active   DATETIME     DEFAULT CURRENT_TIMESTAMP,
    created_at    DATETIME     DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_session (session_id),
    -- ★ 查询"我的会话列表"时用这个索引
    KEY idx_user_active (tenant_id, user_id, last_active DESC)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 3. 工单（业务核心表）
CREATE TABLE ticket (
    id            BIGINT AUTO_INCREMENT PRIMARY KEY,
    ticket_no     VARCHAR(32)  NOT NULL COMMENT '工单号，如 T20260315001',
    tenant_id     VARCHAR(64)  NOT NULL,
    order_no      VARCHAR(32)  NOT NULL,
    user_id       VARCHAR(64)  NOT NULL,
    type          VARCHAR(32)  NOT NULL COMMENT '超时发货/质量问题/退款/其他',
    priority      VARCHAR(10)  NOT NULL COMMENT '低/中/高',
    status        VARCHAR(20)  DEFAULT '待处理',
    suggested_action VARCHAR(500) COMMENT 'AI 建议的处理方案',
    created_by    VARCHAR(20)  COMMENT 'AI / 人工',
    trace_id      VARCHAR(32)  COMMENT '★ 关联到生成它的那次 Agent 执行',
    created_at    DATETIME     DEFAULT CURRENT_TIMESTAMP,
    updated_at    DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_ticket_no (ticket_no),
    -- ★ 幂等关键：同一订单同一类型 24 小时内不允许重复建单
    KEY idx_order_type (tenant_id, order_no, type, created_at),
    KEY idx_status (tenant_id, status, created_at DESC)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 4. 待人工确认的操作（HITL，第 9 章）
CREATE TABLE pending_action (
    id            BIGINT AUTO_INCREMENT PRIMARY KEY,
    action_id     VARCHAR(64)  NOT NULL,
    trace_id      VARCHAR(32)  NOT NULL,
    tenant_id     VARCHAR(64)  NOT NULL,
    user_id       VARCHAR(64)  NOT NULL COMMENT '★ 用于确认时的归属校验',
    tool_name     VARCHAR(64)  NOT NULL,
    arguments     TEXT         NOT NULL COMMENT 'JSON 字符串',
    summary       VARCHAR(500),
    risk_level    VARCHAR(20)  NOT NULL,
    status        VARCHAR(20)  DEFAULT 'PENDING',
    expires_at    DATETIME     NOT NULL COMMENT '★ 过期时间，防止长期悬挂',
    created_at    DATETIME     DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_action (action_id),
    KEY idx_user_status (tenant_id, user_id, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 5. Agent 执行轨迹（第 9、10 章）
CREATE TABLE agent_trace (
    id            BIGINT AUTO_INCREMENT PRIMARY KEY,
    trace_id      VARCHAR(32)  NOT NULL,
    tenant_id     VARCHAR(64)  NOT NULL,
    user_id       VARCHAR(64),
    scene         VARCHAR(64)  COMMENT 'ticket-agent / kb-qa …',
    task          VARCHAR(500) COMMENT '原始任务',
    steps_json    JSON         COMMENT '完整步骤数组',
    final_answer  TEXT,
    step_count    INT,
    total_tokens  INT,
    elapsed_ms    BIGINT,
    success       TINYINT(1),
    created_at    DATETIME     DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_trace (trace_id),
    KEY idx_scene_time (scene, created_at DESC)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 6. 问答审计（用于成本核算与效果分析）
CREATE TABLE qa_audit (
    id             BIGINT AUTO_INCREMENT PRIMARY KEY,
    trace_id       VARCHAR(32)  NOT NULL,
    tenant_id      VARCHAR(64)  NOT NULL,
    user_id        VARCHAR(64),
    session_id     VARCHAR(64),
    question       VARCHAR(1000),
    intent         VARCHAR(32)  COMMENT 'KNOWLEDGE/ORDER/TICKET/CHITCHAT',
    answer_len     INT,
    citation_count INT          COMMENT '引用数，0 表示可能没检索到',
    retrieval_hits INT,
    top_score      DECIMAL(6,4),
    model          VARCHAR(64),
    prompt_tokens  INT,
    completion_tokens INT,
    cost_yuan      DECIMAL(10,6),
    elapsed_ms     BIGINT,
    feedback       TINYINT      COMMENT '1=点赞 -1=点踩 0=无',
    created_at     DATETIME     DEFAULT CURRENT_TIMESTAMP,
    KEY idx_tenant_time (tenant_id, created_at DESC),
    KEY idx_feedback (feedback),
    KEY idx_intent (intent)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

动手：把建表 SQL 落到数据库

1. 在 init/ 目录下新建文件 mysql-schema.sql，把上面 6 张表的 SQL 整段粘进去保存。
2. 登录本地 MySQL，先建库：CREATE DATABASE springai_lab DEFAULT CHARSET utf8mb4;
3. 执行脚本：在 MySQL 客户端里 USE springai_lab; 然后 SOURCE /绝对路径/init/mysql-schema.sql;
4. 验证表是否建好：SHOW TABLES; 应看到 6 张表。

运行验证 ②：6 张表存在

mysql -uroot -proot123456 springai_lab -e "SHOW TABLES;"
# 期望输出（节选）：
# Tables_in_springai_lab
# agent_trace
# chat_session
# kb_document
# pending_action
# qa_audit
# ticket

看到什么算通过：列出 agent_trace、chat_session、kb_document、pending_action、qa_audit、ticket 共 6 张表，无报错。

② PostgreSQL + pgvector：向量表

向量表存的是文档切片与它们的 embedding。注意 维度必须与 embedding 模型一致——这是学生最易踩的坑：换了 embedding 模型，维度对不上就写入失败或检索全错。

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS vector_store (
    id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    content   TEXT,
    metadata  JSON,
    -- ★ 维度必须与 embedding 模型一致（1536 = text-embedding-3-small）
    embedding VECTOR(1536)
);

-- HNSW 索引：余弦距离，与 Spring AI 的 COSINE_DISTANCE 对应
CREATE INDEX IF NOT EXISTS idx_vs_hnsw
    ON vector_store USING hnsw (embedding vector_cosine_ops);

-- ★ 元数据索引：加速按租户/来源过滤（过滤条件是先于向量计算执行的）
CREATE INDEX IF NOT EXISTS idx_vs_tenant
    ON vector_store ((metadata->>'tenantId'));
CREATE INDEX IF NOT EXISTS idx_vs_source
    ON vector_store ((metadata->>'source'));

动手：初始化 pgvector

1. 在 init/ 下新建 pgvector-init.sql，粘贴上面向量表的 SQL。

2. 快速起一个带 pgvector 的 PostgreSQL（推荐用容器，避免本机装扩展麻烦）：

   docker run -d --name pgvector \
     -e POSTGRES_USER=ai -e POSTGRES_PASSWORD=ai123456 \
     -e POSTGRES_DB=vectordb -p 5432:5432 \
     ankane/pgvector

3. 执行初始化：cat init/pgvector-init.sql | docker exec -i pgvector psql -U ai -d vectordb

运行验证 ③：向量表与扩展就位

docker exec -i pgvector psql -U ai -d vectordb -c "\dt"
# 期望看到 vector_store 表
docker exec -i pgvector psql -U ai -d vectordb -c "SELECT 1 FROM pg_extension WHERE extname='vector';"
# 期望返回一行（扩展已装）

看到什么算通过：\dt 列出 vector_store，且 vector 扩展查询有返回行。

11.5接口契约

统一响应格式

为什么强制统一响应 + 带 traceId？因为前端只写一套解析逻辑；traceId 是用户反馈问题时定位故障的钥匙——用户报一个 id，你 3 秒就能在 Zipkin 捞出那次请求。

/**
 * 统一响应包装。所有接口返回这个结构，前端处理逻辑统一。
 * ★ 一定要带 traceId——用户反馈问题时，报这个就能精确定位。
 */
public record ApiResponse<T>(
        int code,            // 0=成功，非 0=业务错误码
        String message,
        T data,
        String traceId
) {
    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(0, "ok", data,
                org.slf4j.MDC.get("traceId"));
    }

    public static <T> ApiResponse<T> fail(int code, String msg) {
        return new ApiResponse<>(code, msg, null,
                org.slf4j.MDC.get("traceId"));
    }
}

动手：落统一响应与全局异常

1. 右键 com.example.springai.common → New → Java Class，名字填 ApiResponse，Kind 选 Record。
2. 把上面 ApiResponse 整段代码粘贴进去，保存。
3. 同样在 common 包新建 GlobalExceptionHandler（用 @RestControllerAdvice 包裹，所有异常统一转成 ApiResponse.fail(...)），保证任何报错都走统一结构、绝不把堆栈直接抛给用户。
4. 在 controller 包新建 ChatController，其方法返回类型统一写成 ApiResponse<ChatResult>（ChatResult 在 11.6 编排层给出）。

接口清单

成对概念：同步接口 vs 流式接口

为什么同时给两套？同步接口实现简单、便于测试与评测（拿完整 JSON 断言）；流式接口体验好（首字快、打字机效果）。生产里通常「内部逻辑一套，对外暴露同步 + 流式两种入口」。

核心接口契约：统一问答入口

// ==================== 请求 ====================
{
  "sessionId": "web-20260315-a3f2",     // 可空：为空则服务端新建会话
  "message": "订单 2024001 一直没发货，怎么处理？",
  "stream": false
}
// 注意：没有 userId！由服务端从 JWT 解析——这是安全底线

// ==================== 响应（摘要） ====================
{
  "code": 0, "message": "ok", "traceId": "a3f2b1c9",
  "data": {
    "sessionId": "web-20260315-a3f2", "intent": "TICKET",
    "answer": "已查明订单 2024001 自 3 月 1 日起超期未发货 14 天……请确认后继续。",
    "citations": [ { "index": 1, "source": "refund-policy.md", "score": 0.82, "excerpt": "…" } ],
    "pendingAction": { "actionId": "8f3a2b1c-...", "summary": "创建工单…", "riskLevel": "HIGH", "expiresAt": "2026-03-15T12:15:00" },
    "meta": { "model": "deepseek-chat", "steps": 3, "elapsedMs": 8420, "tokens": { "prompt": 9482, "completion": 3391 }, "costYuan": 0.0163 }
  }
}

11.6核心编排实现（项目的「大脑」）

编排层的职责：先判断用户想干什么，再交给对应的链路，最后统一组装结果。这是整个项目最核心的 100 行代码，把前面第 3、6、7、9 章的能力缝在一起。

① 意图识别：用结构化输出（第 3 章）

package com.example.springai.orchestrator;

import com.fasterxml.jackson.annotation.JsonPropertyDescription;

/**
 * 意图识别的结果。用 record + 字段描述，让模型输出稳定可控。
 * 注意：意图枚举值要少（4~6 个），多了模型容易判错。
 */
public record IntentResult(

    @JsonPropertyDescription("""
            意图类型，只能取以下四个值之一：
            - KNOWLEDGE：询问公司制度、流程、政策等知识性问题
            - ORDER_QUERY：查询具体订单的状态、物流、金额等信息
            - TICKET_HANDLE：需要处理投诉、创建工单、申请补偿等操作
            - CHITCHAT：打招呼、闲聊、与业务无关的问题
            """)
    String intent,

    @JsonPropertyDescription("从用户问题中提取的订单号，纯数字；未提及则返回 null")
    String orderNo,

    @JsonPropertyDescription("用户的核心诉求，一句话概括，20 字以内")
    String coreDemand,

    @JsonPropertyDescription("判断置信度，0.0~1.0；低于 0.6 时系统会追问用户")
    Double confidence
) {}

@Slf4j
@Component
public class IntentClassifier {

    private final ModelRouter router;

    public IntentClassifier(ModelRouter router) { this.router = router; }

    private static final String PROMPT = """
            你是一个意图分类器。请分析用户的问题，判断它属于哪一类意图。
            分类规则：
            1. 问"怎么做""是什么" → KNOWLEDGE
            2. 问"我的订单怎么样了"，且提到了具体订单号 → ORDER_QUERY
            3. 包含"投诉""催""退款""赔偿""处理一下" → TICKET_HANDLE
            4. 打招呼、感谢、与业务无关 → CHITCHAT
            注意：如果同时涉及查询和处理，归为 TICKET_HANDLE。
            不要输出解释，只输出 JSON。
            用户问题：{question}
            最近对话（用于理解指代）：{recentHistory}
            """;

    public IntentResult classify(String question, String recentHistory) {
        try {
            // ★ 用便宜的小模型做分类：这类任务占总调用量的大头（第 6 章）
            IntentResult result = router.route(ModelRouter.TaskType.CLASSIFY)
                    .prompt()
                    .user(u -> u.text(PROMPT)
                               .param("question", question)
                               .param("recentHistory", recentHistory == null ? "（无）" : recentHistory))
                    .options(OpenAiChatOptions.builder().temperature(0.0).build())
                    .call()
                    .entity(IntentResult.class);   // ★ 结构化输出，2.0 用 entity()

            // 置信度过低时降级为"再问一句"，而不是猜
            if (result.confidence() != null && result.confidence() < 0.6) {
                return new IntentResult("UNCLEAR", null, result.coreDemand(), result.confidence());
            }
            return result;
        } catch (Exception e) {
            // 分类失败不影响主流程：兜底成 KNOWLEDGE，走知识问答链路
            log.warn("意图识别失败，兜底为 KNOWLEDGE", e);
            return new IntentResult("KNOWLEDGE", null, question, 0.5);
        }
    }
}

动手：先让「意图识别」单独跑通（分阶段第 1 步）

不要等整个编排器写好才验证。先把意图识别这个小模块独立跑通——它只依赖一个能返回结构化结果的 ChatClient，最容易单点验证。

1. 右键 com.example.springai.orchestrator → New → Java Class，名字 IntentResult，Kind 选 Record，粘贴上面的 IntentResult 代码。
2. 同包新建 IntentClassifier（Kind Class），粘贴上面代码。注意它依赖 ModelRouter——这是你自己封装的多模型路由（分类走便宜模型）。先建一个最简版：注入 ChatModel，route(...) 直接返回 ChatClient.Builder 构建的 client 即可，重点是把 .entity(IntentResult.class) 跑通。
3. 同包新建一个临时 @SpringBootTest 或直接在 CommandLineRunner 里写一行：log.info(classifier.classify("退款几天到账", null).toString());
4. 启动应用，观察控制台。

运行验证 ④：意图识别单点

# 控制台期望看到类似：
# IntentResult[intent=KNOWLEDGE, orderNo=null, coreDemand=咨询退款到账时间, confidence=0.97]
# 再试：classifier.classify("订单 2024001 一直没发货，帮我处理", null)
# 期望：intent=TICKET_HANDLE, orderNo=2024001

看到什么算通过：返回的结构里 intent 取值正确、orderNo 能从问题中提取出来、confidence 在 0.6 以上。说明「结构化输出 + 小模型分类」这一环已经打通。

② 编排服务：路由 + 组装

@Slf4j
@Service
public class ChatOrchestrator {

    private final IntentClassifier classifier;
    private final KnowledgeQaService knowledgeQa;      // 第 5 章
    private final OrderAssistantService orderAssistant; // 第 7 章
    private final TicketAgentService ticketAgent;        // 第 9 章
    private final ModelRouter router;
    private final QaAuditRepository auditRepository;
    private final ChatMemory chatMemory;                 // 第 2、6 章

    public ChatResult ask(String tenantId, String userId, String sessionId, String message) {
        long t0 = System.currentTimeMillis();
        String conversationId = ConversationIds.of(tenantId, userId, sessionId);
        String traceId = org.slf4j.MDC.get("traceId");

        // ---------- 第 1 步：取最近对话（理解"它""这个单"等指代）----------
        String recentHistory = chatMemory.get(conversationId).stream()
                .map(m -> m.getMessageType() + ": " + m.getText())
                .limit(6)
                .collect(java.util.stream.Collectors.joining("\n"));

        // ---------- 第 2 步：意图识别 ----------
        IntentResult intent = classifier.classify(message, recentHistory);

        // ---------- 第 3 步：路由分发 ----------
        String answer;
        List<Citation> citations = List.of();
        PendingAction pending = null;

        switch (intent.intent()) {
            case "KNOWLEDGE" -> {
                KnowledgeQaService.RagAnswer rag = knowledgeQa.ask(message, tenantId);
                answer = rag.answer();
                citations = rag.citations();
                if (rag.citations().isEmpty()) {
                    auditRepository.markKnowledgeGap(message, tenantId);  // ★ 记录知识盲区
                }
            }
            case "ORDER_QUERY" -> answer = orderAssistant.ask(message);
            case "TICKET_HANDLE" -> {
                AgentTrace trace = ticketAgent.handle(message);   // ★ 走 Agent 链路
                answer = trace.finalAnswer();
                pending = pendingActionService.findLatestPending(tenantId, userId);
            }
            case "CHITCHAT" -> {
                // 闲聊：用便宜模型直接回答，不检索不调用工具，省钱省时
                answer = router.route(ModelRouter.TaskType.CLASSIFY)
                        .prompt()
                        .system("你是友好的企业助手。简短应答，并引导用户提出业务问题。")
                        .user(message).call().content();
            }
            default -> answer = "抱歉，我没太理解您的意思。您是想：① 咨询政策；② 查询订单；③ 提交售后？";
        }

        // ---------- 第 4 步：写审计（成本与效果分析的数据来源）----------
        long elapsed = System.currentTimeMillis() - t0;
        auditRepository.save(QaAudit.builder()
                .traceId(traceId).tenantId(tenantId).userId(userId)
                .sessionId(sessionId).question(message).intent(intent.intent())
                .answerLength(answer.length()).citationCount(citations.size())
                .elapsedMs(elapsed).build());

        // ---------- 第 5 步：统一组装返回 ----------
        String newSessionId = sessionId != null ? sessionId
                : sessionService.create(tenantId, userId).sessionId();
        return new ChatResult(newSessionId, intent.intent(), answer, citations, pending, traceId);
    }

    public record ChatResult(String sessionId, String intent, String answer,
                               List<Citation> citations, PendingAction pendingAction, String traceId) {}
}

动手：把编排器接进 Controller（分阶段第 2 步：串问答链路）

1. 在 orchestrator 包新建 ChatOrchestrator，粘贴上面代码。注意它依赖 KnowledgeQaService、OrderAssistantService、TicketAgentService、ConversationIds、Citation、PendingAction、AgentTrace、QaAudit 等——这些在本阶段先建「最小桩」：返回写死的示例值，让编排器能编译运行，后面逐步替换真实现。
2. 在 common 包新建 ConversationIds，提供一个静态方法 of(tenantId, userId, sessionId) 拼成唯一字符串（如 tenantId + "|" + userId + "|" + sessionId）——这是传给记忆的 conversationId。
3. 在 controller 包让 ChatController 注入 ChatOrchestrator，把 /api/v1/chat/ask 的请求转成 orchestrator.ask(...) 调用，用 ApiResponse.ok(result) 包装返回。
4. 本阶段先把 KNOWLEDGE 分支接通到真实的 KnowledgeQaService（见下一段「运行验证 ⑤」），其余分支先返回桩数据。

运行验证 ⑤：问答链路跑通（先验证 KNOWLEDGE 分支）

curl -s -X POST http://localhost:8080/api/v1/chat/ask \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"demo-001","message":"我买的东西不想要了，钱什么时候能退给我？"}'
# 期望 data.intent = "KNOWLEDGE"，answer 是一句基于制度文档的话，
# data.citations 非空（带 source / score / excerpt）

看到什么算通过：返回 code:0、intent:KNOWLEDGE，answer 像「根据《退款政策》第 3 条，退款将在 3 个工作日内原路返回…」且 citations 里有出处。说明「意图识别 → 路由 → 知识问答 → 组装」整条链路打通。

知识点揉碎：链路编排

11.7部署上线

① Dockerfile（多阶段构建，镜像更小）

为什么多阶段 + 非 root + 时区？多阶段把「构建用的 Maven/JDK」和「运行用的 JRE」分开，镜像从约 700MB 降到约 200MB；非 root 运行是安全基线；时区错会让日志和业务时间差 8 小时，排障时对不上时间线。

# ---------- 阶段一：构建 ----------
FROM maven:3.9-eclipse-temurin-21 AS builder
WORKDIR /build

# 先只拷贝 pom，利用 Docker 层缓存：依赖不变时不会重新下载
COPY pom.xml .
RUN mvn dependency:go-offline -B

COPY src ./src
RUN mvn clean package -DskipTests -B

# ---------- 阶段二：运行 ----------
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app

# 时区：日志和业务时间必须准确
RUN apk add --no-cache tzdata curl && \
    ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

# ★ 非 root 用户运行（安全基线要求）
RUN addgroup -S app && adduser -S app -G app
USER app

COPY --from=builder /build/target/*.jar app.jar

# JVM 参数：容器感知 + 虚拟线程友好 + OOM 时 dump 便于排查
ENV JAVA_OPTS="-XX:MaxRAMPercentage=75 -XX:+UseZGC \
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/logs -Dfile.encoding=UTF-8"

EXPOSE 8080

# 健康检查：容器编排系统据此判断是否重启
HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8080/actuator/health || exit 1

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

动手：写 Dockerfile + 一键编排（分阶段第 3 步：可部署）

1. 在项目根目录（与 pom.xml 同级）右键 → New → File，文件名 Dockerfile（无扩展名），粘贴上面多阶段构建内容。
2. 同目录新建 docker-compose.yml（见下一段），把 MySQL / Redis / pgvector / zipkin 与 app 一起编排。
3. 构建镜像并起服务：docker compose up -d --build（首次会下载依赖并打包，约几分钟）。
4. 等 app 容器 healthy 后，用宿主机端口 8080 访问。

② docker-compose（应用 + 全部依赖，一键起）

services:
  # ……（mysql / redis / pgvector / milvus / zipkin 保持原样，此处省略）

  app:
    build: .
    container_name: sai-app
    ports: ["8080:8080"]
    environment:
      # ★ 密钥从宿主机环境变量透传，绝不写进 compose 文件
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      DASHSCOPE_API_KEY: ${DASHSCOPE_API_KEY}
      # ★ 容器内访问其他服务要用 service 名，不是 localhost！
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/springai_lab?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&useSSL=false
      SPRING_DATASOURCE_USERNAME: root
      SPRING_DATASOURCE_PASSWORD: root123456
      SPRING_DATA_REDIS_HOST: redis
      SPRING_AI_VECTORSTORE_PGVECTOR_DATASOURCE_URL: jdbc:postgresql://pgvector:5432/vectordb
      SPRING_AI_VECTORSTORE_PGVECTOR_DATASOURCE_USERNAME: ai
      SPRING_AI_VECTORSTORE_PGVECTOR_DATASOURCE_PASSWORD: ai123456
      MANAGEMENT_ZIPKIN_TRACING_ENDPOINT: http://zipkin:9411/api/v2/spans
      # 生产环境：关闭 Prompt 日志，降低采样率
      SPRING_AI_CHAT_OBSERVATIONS_LOG_PROMPT: "false"
      MANAGEMENT_TRACING_SAMPLING_PROBABILITY: "0.2"
      SPRING_PROFILES_ACTIVE: prod
    depends_on:
      mysql:    { condition: service_healthy }
      redis:    { condition: service_started }
      pgvector: { condition: service_started }
    restart: unless-stopped

运行验证 ⑥：新机器一键起

# 在一台干净机器上（已装 docker），克隆工程后执行：
docker compose up -d --build
# 等约 1~3 分钟，检查所有容器健康
docker compose ps
# 期望 app 状态为 healthy / running
curl -s http://localhost:8080/actuator/health
# 期望 status: "UP"

看到什么算通过：docker compose ps 里 app 与依赖都 healthy/running，/actuator/health 返回 UP，且能复现验证 ⑤ 的问答请求。即「新环境 5 分钟内系统可用」的验收点达成。

③ 上线前检查清单

• 所有密钥通过环境变量注入，仓库里搜不到 sk- 开头的字符串
• spring.profiles.active=prod，且 prod profile 里日志级别为 info
• Prompt 与响应内容不写入日志（或已脱敏）
• 追踪采样率降到 0.1~0.2
• 所有外部调用都有超时设置（模型 60~120s、数据库 5s、工具 3~15s）
• 降级方法已验证（人为断开模型网络，确认返回友好话术而非 500）
• 数据库连接池上限合理（不要超过数据库 max_connections / 实例数）
• 健康检查接口能正确反映依赖状态
• 评测集跑过一遍，指标达标
• 有一个"应急开关"：能一键关闭 AI 功能、退回纯人工（feature.ai.enabled=false）

知识点揉碎：故障降级

11.8性能与成本优化

① 延迟优化：从 12 秒降到 3 秒

② 成本优化：从每月 1800 元降到 400 元

为什么先算基线？因为优化前必须先知道「钱花在哪」。下面用「每天 300 次咨询」估算，把每次调用的 Token 与单价相乘，得到月成本。注意模型选型对成本影响极大——把 gpt-4o 级换成 deepseek-chat 级，单次成本可能从 0.6 元降到 0.027 元。

# 优化前的成本估算（用强模型 + 每次都走 Agent）
每次咨询：
  · 意图分类      800 token   × 0.8 元/百万 = 0.00064 元
  · RAG 检索生成  6000 token  × 1.0 元/百万 = 0.00600 元
  · Agent 3 步    20000 token × 1.0 元/百万 = 0.02000 元
  合计约 0.027 元/次

月成本 = 0.027 × 300 × 30 ≈ 243 元
# 但如果全部用 gpt-4o 级别（输入 18 元/百万、输出 72 元/百万）
# 单次成本会涨到 0.6 元以上 → 月成本 5400 元

/**
 * 语义缓存：比"完全相同才命中"更聪明的缓存。
 * "退款几天到账" 和 "钱多久能退回来" 语义相同 → 命中同一条缓存。
 */
@Component
public class SemanticCache {

    private static final double SIMILARITY_THRESHOLD = 0.92;

    private final VectorStore cacheStore;      // 独立的缓存向量表
    private final RedisTemplate<String, String> redis;

    public java.util.Optional<String> get(String question, String tenantId) {
        List<Document> hits = cacheStore.similaritySearch(
                SearchRequest.builder()
                        .query(question).topK(1)
                        .similarityThreshold(SIMILARITY_THRESHOLD)   // ★ 阈值必须高
                        .filterExpression("tenantId == '" + tenantId + "'")
                        .build());
        if (hits.isEmpty()) return java.util.Optional.empty();
        String cacheKey = (String) hits.get(0).getMetadata().get("cacheKey");
        return java.util.Optional.ofNullable(redis.opsForValue().get(cacheKey));
    }

    /** ★ 注意：知识库内容更新后，必须清空语义缓存！否则用户会拿到基于旧制度的回答。 */
    public void clearAll(String tenantId) {
        cacheStore.delete("tenantId == '" + tenantId + "'");
    }
}

③ 成本看板：让花钱看得见

-- 每天按意图统计成本（直接查 qa_audit，做成本归因）
SELECT
    DATE(created_at)                            AS 日期,
    intent                                      AS 意图,
    COUNT(*)                                    AS 次数,
    SUM(prompt_tokens + completion_tokens)      AS 总Token,
    ROUND(SUM(cost_yuan), 2)                    AS 成本元,
    ROUND(AVG(elapsed_ms))                      AS 平均耗时ms
FROM qa_audit
WHERE tenant_id = 't1'
  AND created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY DATE(created_at), intent
ORDER BY 日期 DESC, 成本元 DESC;

-- 找出最"贵"的问题类型——这些是优化的重点
SELECT intent, ROUND(AVG(prompt_tokens)) AS 平均输入Token,
       ROUND(AVG(cost_yuan), 4) AS 平均成本元, COUNT(*) AS 次数
FROM qa_audit
GROUP BY intent
ORDER BY 平均成本元 DESC;

动手：先量后优化（加分项，但验收里要能说清楚）

1. 先把系统跑一周（或压一批模拟请求），让 qa_audit 表里积攒足够数据。
2. 执行上面的两条 SQL，导出「按意图的成本 / 延迟」报表。
3. 找出成本最高的意图（通常是 TICKET_HANDLE，因为走 Agent 步数多），优先对它做优化：压 topK、精简上下文、把固定流程改成工作流。
4. 优化后再跑一遍 11.10 的 30 条评测集，对比准确率——只有准确率没掉，优化才算有效。

运行验证 ⑦：成本报表能跑出数

mysql -uroot -proot123456 springai_lab -e "SELECT intent, ROUND(SUM(cost_yuan),2) 成本元, COUNT(*) 次数 FROM qa_audit GROUP BY intent;"
# 期望输出（示例）：
# intent       成本元   次数
# KNOWLEDGE    1.23     180
# ORDER_QUERY  0.45     60
# TICKET_HANDLE 2.10    30
# CHITCHAT     0.12     30

看到什么算通过：报表按意图分组有数据，能直接指出「哪类问题最贵、最慢」——这就是「让花钱看得见」的验收点。若为空，说明审计没落库，回头检查编排层第 4 步的 auditRepository.save(...) 是否真的执行。

11.9交付清单与答辩要点

交付物清单

演示脚本（建议按这个顺序，5 分钟内完成）

为什么规定演示顺序？因为答辩时间有限，必须把「最能体现系统价值」和「最能体现工程严谨性」的环节放在前面。拒答演示和越权拦截演示一定要主动做——它们直接证明你的系统「安全、不编造」，这是评委最看重的。

1. 开场（30 秒）：一句话讲清业务背景与目标。「客服团队每天处理 300 个咨询，60% 是重复问题。我们用 Spring AI 做了知识问答与工单辅助系统，目标是把常见问题自动化率做到 50%。」
2. 知识问答（1 分钟）：用口语化问题提问（不要用文档里的原话）。演示：「我买的东西不想要了，钱什么时候能退给我？」★ 重点展示引用出处。
3. 拒答能力（30 秒）：问一个知识库里没有的问题。「公司年会在哪天举办？」→ 系统回答"资料中未提及"。★ 主动演示，说明"我们不编造"。
4. 订单查询与越权拦截（1 分钟）：① 问自己的订单 → 正确返回；② 问别人的订单 → 返回"未查询到"。★ 展示 ToolContext 传身份的设计。
5. 工单处理与人工确认（1.5 分钟）：① 输入「订单 2024001 一直没发货，帮我处理」；② 展示 Agent 三步决策链；③ 系统提示"请确认后执行"，此时数据库里还没有工单；④ 点击确认 → 工单生成；⑤ 再确认一次 → 提示"已处理"，证明幂等。
6. 可观测性（1 分钟）：① 打开 Zipkin，用刚才的 traceId 查出完整链路；② 打开 Grafana，展示 Token 成本曲线与检索命中率；③ 打开评测报告，展示 30 条评测的通过率。
7. 收尾（30 秒）：给出成本测算与后续规划。「当前单次平均成本 0.012 元，按每天 300 次计算月成本约 108 元。下一步计划补充 200 条评测集，把准确率从 80% 提到 88%。」

答辩常见问题（提前准备）

11.10自测与扩展方向

继续深入的方向

11.11实操作业与本章验收

知识点揉碎：验收标准（开发验收 vs 上线验收的落地）

• 项目能在一台新机器上 docker compose up 5 分钟内启动并可用。
• 知识问答带引用来源，且知识库外问题 100% 拒答不编造。
• 越权订单查询 100% 拦截；高风险操作 100% 人工确认，挂起期间数据库无副作用。
• 服务重启后会话记忆不丢失；全链路可在 Zipkin 查看；评测报告指标达标。
• 交付物齐全（源码、建表脚本、评测报告、接口文档、部署文档、演示脚本）。
• 答辩能讲清架构分层、意图识别位置、HITL 安全设计与成本测算。