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

11.1需求与业务场景

先讲一个真实的业务痛点

「智汇科技」有一支 20 人的客服团队，每天处理约 300 个用户咨询，典型的一天是这样的：

用户角色与核心诉求

11.2功能清单与验收标准

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

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

11.3总体架构设计

分层架构

模块划分（工程结构）

springai-lab/
├── docker-compose.yml
├── init/pgvector-init.sql
├── springai-common/              # 公共模块：配置、异常、工具类、Advisor
│   ├── ChatClientConfig
│   ├── ModelRouter
│   ├── ConversationIds
│   ├── TokenUsageAdvisor / SafeGuardAdvisor
│   └── GlobalExceptionHandler
├── springai-rag/                 # 知识检索模块
│   ├── KnowledgeIndexService
│   ├── KnowledgeQaService
│   └── docreader/ (多格式解析)
├── springai-agent/               # 智能体模块
│   ├── SimpleAgent（循环 + 刹车）
│   ├── PendingActionService（HITL）
│   └── TicketAgentService
├── springai-tools/               # 工具模块
│   ├── OrderTools / TicketTools
├── springai-eval/                # 评测模块
│   ├── EvalRunner / RagEvaluationTest
└── springai-app/                 # 启动模块（组装以上全部）
    ├── controller/
    └── SpringAiLabApplication

11.4数据模型设计

① MySQL：业务数据

-- ============================================================
-- 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;

② PostgreSQL + pgvector：向量表

沿用 0.4.4 节的初始化脚本，但生产版本要补上多租户与来源字段：

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'));

-- 排查用：看看每个租户灌了多少块
-- SELECT metadata->>'tenantId' AS tenant, COUNT(*) FROM vector_store GROUP BY 1;

11.5接口契约

统一响应格式

/**
 * 统一响应包装。所有接口返回这个结构，前端处理逻辑统一。
 * ★ 一定要带 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"));
    }
}

接口清单

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

// ==================== 请求 ====================
{
  "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 天。\n\n依据《超时发货处理规范》，可申请订单金额 5% 的补偿（899 × 5% = 44.95 元）。\n\n我准备创建一张【超时发货】工单，建议方案：催促仓库发货并申请 44.95 元补偿。\n\n请确认后继续。",
    "citations": [                         // ★ 引用来源，第三方可核对
      { "index": 1, "source": "refund-policy.md", "score": 0.82,
        "excerpt": "订单超过承诺发货日期 7 天未发货的，按订单金额 5% 补偿…" }
    ],
    "pendingAction": {                     // 待确认操作（有则返回）
      "actionId": "8f3a2b1c-...",
      "summary": "创建工单：订单 2024001，类型 超时发货，优先级 高",
      "riskLevel": "HIGH",
      "expiresAt": "2026-03-15T12:15:00"
    },
    "meta": {                              // 透明化：让前端能展示与统计
      "model": "deepseek-chat",
      "steps": 3,
      "elapsedMs": 8420,
      "tokens": { "prompt": 9482, "completion": 3391 },
      "costYuan": 0.0163
    }
  }
}

// ==================== 错误码约定 ====================
// 0     成功
// 1001  参数非法
// 2001  模型服务不可用（已降级）
// 2002  达到调用配额上限
// 3001  无权访问该资源（会话/订单/操作）
// 3002  待确认操作已过期
// 4001  知识库为空或索引未建立

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

编排层的职责：先判断用户想干什么，再交给对应的链路，最后统一组装结果。 这是整个项目最核心的 100 行代码。

① 意图识别：用结构化输出（第 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);

            // 置信度过低时降级为"再问一句"，而不是猜
            if (result.confidence() != null && result.confidence() < 0.6) {
                log.info("意图识别置信度较低：{}，将追问用户", result.confidence());
                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);
        }
    }
}

② 编排服务：路由 + 组装

@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;                    // 第 6 章
    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);
        log.info("意图识别：intent={} orderNo={} confidence={}",
                intent.intent(), intent.orderNo(), intent.confidence());

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

        switch (intent.intent()) {

            case "KNOWLEDGE" -> {
                // 知识问答链路：RAG + 引用溯源
                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" -> {
                // Agent 链路：多步决策 + 高风险操作挂起
                AgentTrace trace = ticketAgent.handle(message);
                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) {}
}

11.7部署上线

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

# ---------- 阶段一：构建 ----------
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

# ---------- 阶段二：运行 ----------
# 用 JRE 而非 JDK，用 alpine 变体，镜像从 ~700MB 降到 ~200MB
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"]

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

# 在 0.4.4 节的基础设施 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

③ 上线前检查清单

• 所有密钥通过环境变量注入，仓库里搜不到 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 次咨询估算）：

# 优化前的成本估算（用强模型 + 每次都走 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");
        String cached = redis.opsForValue().get(cacheKey);

        // 缓存过期则视为未命中（TTL 由写入时设置）
        return java.util.Optional.ofNullable(cached);
    }

    /**
     * ★ 注意：知识库内容更新后，必须清空语义缓存！
     *   否则用户会拿到基于旧制度的回答。
     *   做法：reindex 完成后调用 clearAll()。
     */
    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;

11.9交付清单与答辩要点

交付物清单

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

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

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

11.10自测与扩展方向

继续深入的方向