APPENDIX速查手册与排错表

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

这是全站最应该打印出来贴在显示器旁的一页。 2.0 是架构级重构，下面每一行都是"照抄旧代码会出问题"的地方。左列是 1.x 的写法，右列是 2.0 的正确写法。

一、底座与依赖

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

三、结构化输出

四、会话记忆

五、配置与 Options

六、MCP

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

A.1命令速查

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                           # 列出数据卷

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评测并输出报告

接口验证（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":"你好"}]}'

数据库

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

A.2配置模板全家桶

这是一份可以直接用的完整 application.yml，把课程里所有章节需要的配置都收进来了。 用不到的段落注释掉即可。

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

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

A.4核心 API 速查

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

① 通用系统提示骨架

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

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

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

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

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

② RAG 问答模板

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

【参考资料】
{question_answer_context}

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

【用户问题】
{query}

③ 信息抽取模板

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

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

【待抽取文本】
{input}

{format}

④ 意图分类模板

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

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

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

【用户问题】
{question}

【最近对话】
{recentHistory}

⑤ Agent 任务规划模板

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

【可用工具】
{toolList}

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

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

【用户需求】
{requirement}

⑥ 对话摘要模板

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

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

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

【已有摘要】
{previousSummary}

【新增对话】
{historyText}

A.6术语表

A.7学习资源地图

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