速查表：依赖坐标、配置与常用 API

1. 本节产出

一张能复制粘贴的速查表：Maven 依赖、application.yml 配置模板、常用 API 骨架、常用命令。写新项目时直接抄。

2. 前置依赖

00-03 版本矩阵：确认你的版本组合

3. 为什么需要单独一张速查表

写新模块时，你要从五六个章节里翻找依赖坐标和配置片段。这些内容是「高频低信息量」的——不需要理解，只需要准确。集中成一张表能省掉大量翻找时间。

4. 核心原理

版本统一由 BOM 管理，正文不写版本号——避免升级时改十几处。

5. 速查内容

5.1 Maven 依赖

xml

<!-- BOM：版本集中管理 -->
<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>

<!-- 模型（OpenAI 协议兼容，覆盖多数国内厂商） -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

<!-- 本地模型 -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>

<!-- 向量库 -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-vector-store-milvus</artifactId>
</dependency>

<!-- 记忆持久化 -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-model-chat-memory-repository-jdbc</artifactId>
</dependency>

<!-- 可观测 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

<!-- 熔断 -->
<dependency>
  <groupId>io.github.resilience4j</groupId>
  <artifactId>resilience4j-spring-boot3</artifactId>
</dependency>

5.2 application.yml 模板

yaml

spring:
  ai:
    openai:
      api-key: ${AI_API_KEY}
      base-url: ${AI_BASE_URL}
      chat:
        options:
          model: ${AI_MODEL}
          temperature: 0.7
          max-tokens: 2000
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5:7b
  datasource:
    url: jdbc:postgresql://localhost:5432/rag
    username: ${DB_USER}
    password: ${DB_PASS}

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  metrics:
    distribution:
      percentiles-histogram:            # 不开这个看不到 P95
        rag.query: true
        agent.run.duration: true

logging:
  level:
    org.springframework.ai: DEBUG       # 调试工具调用时打开

5.3 常用 API 骨架

java

// 1. ChatClient Bean
@Bean
ChatClient chatClient(ChatClient.Builder b) {
    return b.defaultSystem("...").defaultTools(tools).build();
}

// 2. 同步调用
String out = chatClient.prompt().user(text).call().content();

// 3. 流式
Flux<String> flux = chatClient.prompt().user(text).stream().content();

// 4. 结构化输出
var conv = new BeanOutputConverter<>(Ticket.class);
Ticket t = conv.convert(chatClient.prompt()
        .user(u -> u.text("{format}\n{q}")
                .param("format", conv.getFormat())
                .param("q", input))
        .options(OpenAiChatOptions.builder().temperature(0.0).build())
        .call().content());

// 5. 工具定义
@Tool(description = "做什么 + 参数格式 + 边界")
public String tool(@ToolParam(description = "参数说明") String p) { ... }

// 6. 记忆
chatClient.prompt()
    .user(text)
    .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, convId))
    .call().content();

// 7. 向量检索（带过滤）
vectorStore.similaritySearch(SearchRequest.builder()
        .query(q).topK(5).similarityThreshold(0.6)
        .filterExpression("tenantId == 'acme' && version == '2026'")
        .build());

// 8. Advisor
@Component
public class XAdvisor implements CallAroundAdvisor {
    @Override public AdvisedResponse aroundCall(AdvisedRequest r,
            CallAroundAdvisorChain c) { return c.nextAroundCall(r); }
    @Override public String getName() { return "x"; }
    @Override public int getOrder() { return 100; }
}

5.4 常用命令

bash

# 依赖与运行
mvn -o dependency:tree            # 看依赖冲突
mvn spring-boot:run
mvn -q test -Dtest=XxxTest

# 一键起依赖
docker compose up -d
docker compose logs -f pgvector

# 验证
curl -N -H "Accept: text/event-stream" "http://localhost:8080/api/chat/stream?message=hi"
curl http://localhost:8080/actuator/prometheus | grep rag_

# 代码锚点
git tag                            # 列出所有 tag
git checkout ch02-09-hybrid-retrieval

5.5 Advisor 顺序速记

审计(100) → 安全 → 记忆(200) → 检索 → 工具 → 成本(900)
口诀：审计在前、记忆在中、成本在后

5.6 参数经验值

参数	值	场景
temperature	0~0.2	抽取/分类/结构化
temperature	0.5~0.7	对话
temperature	0.8~1.0	创意
maxTokens	50 / 500 / 2000	分类 / 摘要 / 生成
similarityThreshold	0.6（起点，需实测）	RAG 检索
语义缓存阈值	0.95+	语义缓存
chunk 大小	500~800 Token	制度文档
chunk 重叠	10%~15%	通用
RRF k	60	融合排序
挂载工具数	≤ 8	Agent
maxIterations	10（预期 8）	Agent
上下文压缩触发	60% 窗口	Agent

6. 跑起来

复制粘贴即可。建议把本页加入浏览器书签。

检查项	通过标准
依赖坐标	能直接 pom 里用
配置模板	改环境变量即可启动
参数值	与正文一致（不一致以正文为准）

7. 生产避坑

速查表的参数值与正文冲突时，以正文为准。本页是摘要，正文有推导过程和适用条件。特别是阈值类参数（similarityThreshold 等），必须按 02-08 的方法实测标定。
版本号不要抄进 pom。统一由 BOM 管理，抄死版本号会导致升级时漏改，出现「部分依赖是新版、部分是旧版」的不一致状态。

8. 延伸与锚点

遇到诡异现象？看踩坑合集
有概念疑问？看 FAQ

速查表：依赖坐标、配置与常用 API ​

1. 本节产出 ​

2. 前置依赖 ​

3. 为什么需要单独一张速查表 ​

4. 核心原理 ​

5. 速查内容 ​

5.1 Maven 依赖 ​

5.2 application.yml 模板 ​

5.3 常用 API 骨架 ​

5.4 常用命令 ​

5.5 Advisor 顺序速记 ​

5.6 参数经验值 ​

6. 跑起来 ​

7. 生产避坑 ​

8. 延伸与锚点 ​