APPENDIX速查手册与排错表

A.0Spring AI 1.x → 2.0 破坏性变更速查表

这是全站最应该打印出来贴在显示器旁的一页。2.0 是架构级重构，下面每一行都是「照抄旧代码会出问题」的地方。左列是 1.x 的写法，右列是 2.0 的正确写法。考试/答辩里凡出现左列写法，直接判为使用了过时 API。

一、底座与依赖

二、工具调用（改动最大的一块）

三、结构化输出

四、会话记忆

五、配置与 Options

六、MCP

七、2.0 新增、值得专门学的三个能力

A.1命令速查

下面每条命令都可直接复制。每个小节后附一行「什么时候用」。注意：命令里的路径、密码、端口都是课程配套工程 springai-lab 的默认值，按你自己的环境替换。

Docker / 基础设施

# ---------- 启动与停止 ----------
cd D:/springai-lab
docker compose up -d                      # 后台启动全部服务
docker compose up -d mysql redis pgvector zipkin   # 只启动核心四个
docker compose ps                          # 查看状态（等 STATUS 变 healthy）
docker compose logs -f milvus              # 跟踪某个服务日志
docker compose restart app                 # 重启应用容器
docker compose down                        # 停止并删除容器（保留数据卷）
docker compose down -v                     # ★ 同时删除数据卷（数据全丢，慎用）

# ---------- 连通性验证 ----------
docker exec -it sai-mysql mysql -uroot -proot123456 -e "SELECT VERSION();"
docker exec -it sai-redis redis-cli -a redis123456 ping              # 期望 PONG
docker exec -it sai-pgvector psql -U ai -d vectordb -c "\dx"        # 看 vector 扩展
curl http://localhost:9411/health                                    # Zipkin
curl http://localhost:9091/healthz                                   # Milvus

# ---------- 清理（磁盘不够时） ----------
docker system df                           # 看磁盘占用
docker system prune -a                     # 清理无用镜像与容器（不会删卷）
docker volume ls                           # 列出数据卷

什么时候用 第 4/5/11 章用到 pgvector、redis、mysql、zipkin 等中间件时；启动后先用「连通性验证」三条确认服务 healthy，再跑应用，否则会卡在连接超时。

Maven

mvn -v                                              # 版本 + JDK 版本
mvn clean compile                                   # 编译
mvn clean package -DskipTests                       # 打包（跳过测试，快）
mvn spring-boot:run                                 # 直接运行

# 看 Spring AI 依赖树（排查"依赖没进来"）
mvn -q dependency:tree -Dincludes=org.springframework.ai

# 强制更新依赖（镜像换了之后用）
mvn -U clean package -DskipTests

# 清本地仓库里某个包的缓存（解决"jar 损坏"）
rm -rf ~/.m2/repository/org/springframework/ai

# 只跑某个测试类 / 某个方法
mvn test -Dtest=RagEvaluationTest
mvn test -Dtest=RagEvaluationTest#跑一遍RAG评测并输出报告

什么时候用 改了 pom.xml 或换了镜像后用 mvn -U 强制刷新；依赖冲突/版本不对先看 dependency:tree；jar 损坏先清本地仓库缓存再编译。

接口验证（curl）

# 普通 POST
curl -X POST http://localhost:8080/api/v1/chat/ask \
  -H "Content-Type: application/json" \
  -d '{"message":"退款要几天到账"}'

# 流式（-N 关闭缓冲才能看到逐字效果）
curl -N -X POST http://localhost:8080/api/v1/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message":"从1数到10"}'

# GET 带参数
curl "http://localhost:8080/api/v1/vector/search?q=退款&topK=5&threshold=0.5"

# 只看 HTTP 状态码
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/actuator/health

# 格式化 JSON 输出（装了 jq 的话）
curl -s ... | jq .

# 直连模型厂商 API 验证密钥（排除代码因素）
curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'

什么时候用 调通一个接口最快的方式不是开前端，而是 curl。先 -w "%{http_code}" 确认 200，再贴完整 body 看返回；报 401 先用最后那条直连厂商验证 key 是否有效，区分「密钥问题」还是「代码问题」。

数据库

# ---------- PostgreSQL / pgvector ----------
docker exec -it sai-pgvector psql -U ai -d vectordb

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

-- 看某个来源的块数与内容预览
SELECT id, LEFT(content, 60) FROM vector_store
WHERE metadata->>'source' = 'refund-policy.md' LIMIT 5;

-- 清空某个租户的数据（重建索引前）
DELETE FROM vector_store WHERE metadata->>'tenantId' = 't1';

-- 看索引是否建上（HNSW）
SELECT indexname, indexdef FROM pg_indexes WHERE tablename = 'vector_store';

# ---------- MySQL ----------
docker exec -it sai-mysql mysql -uroot -proot123456 springai_lab

-- 看会话记忆（排查"记忆串味"）
SELECT conversation_id, type, LEFT(content, 50) AS preview, timestamp
FROM spring_ai_chat_memory
WHERE conversation_id = 't1|u1001|s1'
ORDER BY timestamp DESC LIMIT 10;

-- 成本归因：按意图统计
SELECT intent, COUNT(*), ROUND(AVG(cost_yuan), 4) AS avg_cost
FROM qa_audit GROUP BY intent ORDER BY avg_cost DESC;

-- 找出"检索没命中"的问题（知识盲区）
SELECT question, COUNT(*) FROM qa_audit
WHERE citation_count = 0
GROUP BY question ORDER BY COUNT(*) DESC LIMIT 20;

什么时候用 RAG/记忆相关 bug 排查时：检索为空先去 vector_store 看块数和索引；A 用户看到 B 用户对话去 spring_ai_chat_memory 看 conversation_id 是否串了；成本异常用 qa_audit 按意图归因。

应用运行 / 运维 / 提交

# ---------- 打好的 jar 直接跑（第 11 章部署用） ----------
java -jar target/springai-lab-0.0.1.jar
java -jar target/springai-lab-0.0.1.jar --spring.profiles.active=prod   # 指定环境

# ---------- 看进程与端口占用 ----------
jps                                       # 看 Java 进程 PID
netstat -ano | findstr :8080             # Windows 看谁占了 8080
lsof -i :8080                            # macOS/Linux 等价

# ---------- 指标端点（第 10 章） ----------
curl -s http://localhost:8080/actuator/prometheus | grep ai_   # 只看 AI 相关指标
curl -s http://localhost:8080/actuator/health              # 健康检查

# ---------- 容器 IP（容器间互访排错用） ----------
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' sai-pgvector

# ---------- 作业提交前（不要提交密钥！） ----------
git status                                # 确认没有 application-local.yml / .env 被加进来
git log --oneline -5                      # 确认提交记录干净

什么时候用 部署/排错时用 java -jar 而不是 IDEA 跑；端口被占先 netstat/lsof 找 PID 再结束；提交作业前必跑 git status 确认密钥文件没进暂存区。

A.2配置模板全家桶

这是一份可以直接用的完整 application.yml，把课程里所有章节需要的配置都收进来了。用不到的段落注释掉即可。下面先给「最小可跑版」，再给「全功能版」。

最小可跑版（第 1~3 章够用）

spring:
  application:
    name: springai-lab
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:}        # ★ 密钥走环境变量，绝不硬编码
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7               # ★ 2.0 默认温度已移除，必须显式给
          max-tokens: 2048
        connect-timeout: 30s
        read-timeout: 120s
      # ★ 2.0：embedding 没有 .options 层，直接写 model
      embedding:
        model: text-embedding-3-small

server:
  port: 8080

logging:
  level:
    root: info
    org.springframework.ai: warn

什么时候用 第 1 章刚跑通 ChatClient、第 2 章提示词、第 3 章结构化输出时，用这个最小版即可，别一上来把全功能版贴进去增加排查面。

全功能版（第 4~11 章逐段打开）

spring:
  application:
    name: springai-lab
  profiles:
    active: dev              # dev / local / prod

  # ==================== 模型配置 ====================
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:}
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7
          max-tokens: 2048
        connect-timeout: 30s
        read-timeout: 120s
      embedding:
        # ★ 2.0 移除了 .options 这一层，直接写 model
        model: text-embedding-3-small
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5:7b
      embedding:
        model: nomic-embed-text
      init:
        pull-model-strategy: never

    # ==================== 2.0：工具调用循环与工具检索 ====================
    chat:
      client:
        tool-calling:
          # 默认 true：ChatClient 自动注册 ToolCallingAdvisor 处理工具循环。
          # 自研 Agent 要自己驱动循环时设为 false，或单次调用用
          # AdvisorParams.toolCallingAdvisorAutoRegister(false)。
          enabled: true
          # advisor-order: 100   # 默认 HIGHEST_PRECEDENCE + 300
        tool-search-advisor:
          # 工具 > 50 个（尤其接了多个 MCP Server）时打开，省 34%~64% token
          enabled: false
          tool-index-type: regex        # regex / lucene / vector
    tools:
      limits:
        # 2.0 新增的默认保护：单工具每轮 40 次、合计 150 次
        max-calls-per-tool-default: 40
        max-total-tool-calls: 150
        on-limit-exceeded: THROW      # 或 RETURN_ERROR_RESPONSE
      resolution:
        fallback:
          # 默认 false：只有本次请求显式附带的工具可执行。
          # 打开会让"模型报出任何工具名就能执行"，放大越权风险，生产保持 false。
          enabled: false

    # ==================== 重试（第 6 章） ====================
    retry:
      max-attempts: 3
      on-client-errors: false       # ★ 4xx 不重试
      backoff:
        initial-interval: 2s
        multiplier: 2
        max-interval: 10s

    # ==================== 会话记忆（第 6 章） ====================
    chat:
      memory:
        repository:
          jdbc:
            initialize-schema: always
          # redis:
          #   time-to-live: 24h

    # ==================== 向量库（第 4 章） ====================
    vectorstore:
      pgvector:
        initialize-schema: true
        table-name: vector_store
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1536            # ★ 必须等于模型输出维度
        max-document-batch-size: 10000
      # milvus:
      #   client: { host: localhost, port: 19530 }
      #   collection-name: vector_store
      #   embedding-dimension: 1536
      #   index-type: IVF_FLAT
      #   metric-type: COSINE
      #   initialize-schema: true

    # ==================== MCP 客户端（第 8 章） ====================
    mcp:
      client:
        enabled: true
        name: springai-lab
        version: 1.0.0
        initialized: true
        toolcallback:
          enabled: true             # ★ 自动把 MCP 工具注册为 ToolCallback
        stdio:
          servers-configuration: classpath:mcp-servers.json
          request-timeout: 60s

    # ==================== 可观测性（第 10 章） ====================
    chat:
      observations:
        log-prompt: false           # 生产必须 false！
        log-completion: false

  # ==================== 数据源 ====================
  datasource:
    url: jdbc:mysql://localhost:3306/springai_lab?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&useSSL=false
    username: root
    password: root123456
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 5000
      max-lifetime: 1200000

  data:
    redis:
      host: localhost
      port: 6379
      password: redis123456
      timeout: 3s

  # ==================== 上传限制（知识库文档） ====================
  servlet:
    multipart:
      max-file-size: 50MB
      max-request-size: 100MB

server:
  port: 8080
  shutdown: graceful             # 优雅停机，避免正在处理的请求被中断
  tomcat:
    threads:
      max: 200
    connection-timeout: 10s

# ==================== 管理端点 ====================
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: always
  tracing:
    sampling:
      probability: 0.2           # 生产 0.1~0.2；开发用 1.0
  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans

# ==================== Resilience4j（第 6 章） ====================
resilience4j:
  retry:
    instances:
      aiChat:
        max-attempts: 3
        wait-duration: 1s
        retry-exceptions:
          - org.springframework.web.client.ResourceAccessException
  circuitbreaker:
    instances:
      aiChat:
        sliding-window-size: 20
        failure-rate-threshold: 50
        wait-duration-in-open-state: 30s

# ==================== 业务自定义配置 ====================
app:
  ai:
    enabled: true                # ★ 应急开关：false 则 AI 功能整体关闭
  knowledge:
    docs-path: classpath:docs/*.md
    top-k: 5
    similarity-threshold: 0.5
    chunk-size: 600
  agent:
    max-steps: 8
    max-tokens: 30000
    max-millis: 120000
    pending-action-expire-minutes: 15
    high-risk-tools: submitRefund,createTicket,sendEmail,cancelOrder
  pricing:
    models:
      deepseek-chat: { input: 1.0, output: 2.0 }
      qwen-plus:     { input: 0.8, output: 2.0 }
      ollama-local:  { input: 0.0, output: 0.0 }

# ==================== 日志 ====================
logging:
  level:
    root: info
    com.example.springai: info
    org.springframework.ai: warn        # 生产用 warn，开发用 debug
  pattern:
    console: "%d{HH:mm:ss.SSS} [%thread] %-5level [%X{traceId:-}] %logger{36} - %msg%n"
  file:
    name: logs/springai-lab.log
  logback:
    rollingpolicy:
      max-file-size: 100MB
      max-history: 30
      total-size-cap: 5GB

什么时候用 第 4 章起逐段打开对应配置（向量库、记忆、MCP、可观测）。每开一段先确认依赖 starter 已引入，再贴配置；dimensions 必须与 embedding 模型输出维度一致，否则建表直接报错。

A.3异常排查对照表（按报错关键词找）

每行的「现象」是学生真实会看到的报错原文。遇到红色堆栈，先按关键词 Ctrl+F 本表，再动手。找不到就往上翻 A.0 看是不是 1.x 写法。

A.4核心 API 速查

2.0 写法速查。每个类后加一行「什么时候用」。★ 标记的是 2.0 与 1.x 差异点，答辩前必背。

A.5提示词模板库（直接抄）

六套可直接套用的提示词骨架，每段都标注「什么时候用」。变量用 {name} 占位，调 PromptTemplate.create(Map) 填。

① 通用系统提示骨架

你是{公司}{角色}，服务于{服务对象}。

## 你的职责
{用 2~3 条列出能做的事}

## 硬性规则
1. {最重要的一条：什么绝对不能做}
2. {信息不足时怎么办}
3. {越界问题时怎么办}

## 输出风格
{长度限制、语气、格式要求}

## 兜底
如果{无法处理的情况}，请{具体动作}。

什么时候用 任何对话机器人/客服机器人的 defaultSystem，先搭这个骨架再填业务。

② RAG 问答模板

请严格依据下方【参考资料】回答用户问题。

【参考资料】
{question_answer_context}

【回答要求】
1. 只使用参考资料中的信息；资料不足时回答"根据现有资料无法确定"。
2. 结论后用 [序号] 标注来源。
3. 用自己的话组织，不要照抄原文。
4. 回答不超过 300 字。

【用户问题】
{query}

什么时候用 接了知识库的问答（QuestionAnswerAdvisor 的 promptTemplate）。防幻觉全靠「只使用资料」这条。

③ 信息抽取模板

你是一名信息抽取助手。请从下面的文本中提取结构化信息。

【抽取规则】
1. 找不到的字段返回 null（列表返回 []），严禁编造或推测。
2. {字段级特殊规则，如"金额只输出数字，不带单位"}。
3. 只输出 JSON 对象本身，不要解释，不要代码块标记。

【待抽取文本】
{input}

{format}

什么时候用 配 .entity(Class) 使用：从合同/工单/邮件里抽字段。格式约束写死能大幅减少「899元」这类反序列化失败。

④ 意图分类模板

你是一个意图分类器。请判断用户问题属于哪一类。

【分类规则】
1. {类别 A 的特征} → CATEGORY_A
2. {类别 B 的特征} → CATEGORY_B
3. {类别 C 的特征} → CATEGORY_C

【注意】
- {歧义情况的判定规则，如"同时涉及 A 和 B 时归为 B"}。
- 不要输出解释，只输出 JSON。

【用户问题】
{question}

【最近对话】
{recentHistory}

什么时候用 多路路由：先分类再决定走哪个 Agent / 工具 / 知识库。

⑤ Agent 任务规划模板

你是任务规划专家。请把用户需求拆解成可执行的步骤。

【可用工具】
{toolList}

【输出格式】
严格输出 JSON 数组：step / action / args / desc / risk
risk 取值 low（查询）medium（修改数据）high（删除·付款·发信）

【规则】
1. 步骤控制在 2~6 步，不要过度拆分。
2. 只使用列出的工具，禁止编造。
3. 不要输出 JSON 以外的内容。

【用户需求】
{requirement}

什么时候用 Planner 模式（先规划再执行）的 Agent；risk=high 的步骤要接 HITL 人工确认。

⑥ 对话摘要模板

请把下面的对话压缩成结构化摘要。

摘要必须保留（如果存在）：
- 用户身份关键信息
- 涉及的所有编号、金额、日期
- 用户核心诉求与已承诺方案
- 尚未解决的问题

摘要不超过 150 字，要点式，不要客套话。

【已有摘要】
{previousSummary}

【新增对话】
{historyText}

什么时候用 长对话压缩后写回记忆，避免 context window 爆掉、省 token。

⑦ 工具选择说明模板（给模型的工具说明）

你是一个能调用工具的助手。可用工具如下，请按需调用：
- getWeather(city): 查某城市天气，仅用于天气类问题
- queryOrder(id): 查订单状态，需要订单号
- submitRefund(id, reason): 提交退款，属于高风险操作，调用前必须先向用户确认

规则：
1. 不相关的工具不要调用。
2. submitRefund 必须先获得用户明确确认再调用。

什么时候用 工具太多导致模型用错/不用工具时，把职责边界写进系统提示（配合 @Tool 的 description 双保险）。

A.6术语表

每个术语先给一句大白话（像跟同学解释），再给一句准确定义（像写进文档）。带 ★ 的是 2.0 重点术语。

A.7学习资源地图

A.8上线自检清单（打印出来贴在工位）

A.9快速决策表（什么时候选哪个）

做方案选型和答辩时说不清「为什么这么选」时，回这里。每张表给判断依据，不是死规则。

① 知识方案：RAG vs 长上下文 vs 微调

什么时候用 有「会变的资料库」→ RAG；只是临时分析一份能塞进窗口的文档 → 长上下文；想让模型长期具备某种专业口吻且样本充足 → 才考虑微调。

② 调用入口：ChatClient vs ChatModel

③ 工具实现：@Tool bean vs FunctionToolCallback vs MCP

④ 记忆实现：InMemory vs JDBC vs Redis

⑤ 向量库选型

⑥ Advisor 顺序与组合

⑦ 输出方式：结构化 entity() vs 流式 vs 普通文本

⑧ 记忆位置：循环内 vs 循环外

A.10附录使用说明（实验 / 答辩前自查）

本附录是「随身手册」，不是用来从头读到尾的。下面告诉你在三个关键时刻怎么用它。

① 写代码时：防「抄成 1.x」

1. 动手前先翻 A.0，确认你要写的 API 在 2.0 里长什么样（尤其记忆、工具、MCP、embedding 配置）。
2. 代码里若出现 PromptChatMemoryAdvisor、.toolNames(...)、internalToolExecutionEnabled(...)、embedding.options 任一，立刻停手——这是 1.x，编译/运行会出问题。
3. 拿不准方法名，回 A.4 按类名查「关键方法」与「什么时候用」。

② 报错时：按关键词定位

1. 复制红色堆栈里的关键报错串，Ctrl+F 本页：先在 A.3 按「现象」找；
2. 若 A.3 没有，去 A.0 看是不是「1.x 写法在 2.0 被删/改」；
3. 还不明白，去 A.7 的官方文档/Examples 按排查顺序查，最后才搜博客。

③ 答辩 / 上线前：对照清单

• API 合规：代码里没有 A.0 列出的任何 1.x 写法（重点查记忆/工具/MCP/配置）。
• 排错准备：能口头说出 A.3 里三类最高频报错（conversationId、工具重复执行、MCP 空列表）的原因与解决。
• 方案有据：对 RAG/长上下文/微调、ChatClient/ChatModel、工具实现方式的选择，能用 A.9 讲清理由。
• 安全稳定：过一遍 A.8 四张卡（安全/稳定性/可观测/效果），至少打勾 80%。
• 术语过关：A.6 里带 ★ 的 2.0 术语（ToolCallingAdvisor、FunctionToolCallback、@McpTool、SyncMcpToolCallbackProvider、ConversationId、entity）能用自己的话解释。