环境搭建

本章介绍如何搭建 Spring AI 开发环境，包括项目创建、依赖配置和基本设置。

系统要求

要求	版本
JDK	17+
Spring Boot	3.4.x / 3.5.x
Maven	3.6+ 或 Gradle 8+
Spring AI	1.0.0+

创建项目

方式一：Spring Initializr

访问 start.spring.io
选择项目配置：
- Project: Maven
- Language: Java
- Spring Boot: 3.4.x
- Packaging: Jar
- Java: 17
添加依赖：
- Spring AI (选择所需模型提供商)
点击 Generate 下载项目

方式二：手动创建

Maven 配置

<?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>3.4.0</version>
        <relativePath/>
    </parent>
    
    <groupId>com.example</groupId>
    <artifactId>spring-ai-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>spring-ai-demo</name>
    
    <properties>
        <java.version>17</java.version>
        <spring-ai.version>1.0.0</spring-ai.version>
    </properties>
    
    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- Spring AI BOM -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        
        <!-- OpenAI (根据需要选择) -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Gradle 配置

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.4.0'
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '17'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation platform('org.springframework.ai:spring-ai-bom:1.0.0')
    
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
    
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

模型提供商配置

Spring AI 支持多种模型提供商，根据需求选择配置：

OpenAI

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

# application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com  # 可选，自定义 API 端点
      chat:
        options:
          model: gpt-4o
          temperature: 0.7

Ollama（本地模型）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        model: llama3.2
        options:
          temperature: 0.7

Azure OpenAI

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
</dependency>

spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}
        chat:
          options:
            deployment-name: gpt-4

Anthropic Claude

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
</dependency>

spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
      chat:
        options:
          model: claude-3-5-sonnet-20241022

阿里云通义千问

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-alibaba-starter</artifactId>
</dependency>

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-plus

环境变量配置

方式一：系统环境变量

# Linux/macOS
export OPENAI_API_KEY=sk-your-api-key

# Windows (PowerShell)
$env:OPENAI_API_KEY="sk-your-api-key"

方式二：.env 文件

# .env
OPENAI_API_KEY=sk-your-api-key
ANTHROPIC_API_KEY=sk-ant-your-api-key

方式三：application.yml 引用

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:default-key}  # 可设置默认值

向量数据库配置

PGVector

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId>
</dependency>

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/vectordb
    username: postgres
    password: postgres
  ai:
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1536

Chroma

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-chroma-store-spring-boot-starter</artifactId>
</dependency>

spring:
  ai:
    vectorstore:
      chroma:
        client:
          host: http://localhost:8000

Redis

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-redis-store-spring-boot-starter</artifactId>
</dependency>

spring:
  data:
    redis:
      host: localhost
      port: 6379
  ai:
    vectorstore:
      redis:
        uri: redis://localhost:6379
        index: spring-ai-index
        prefix: "doc:"

验证配置

创建测试控制器验证配置是否正确：

@RestController
@RequestMapping("/api/ai")
public class AiTestController {

    @Autowired
    private ChatClient chatClient;

    @GetMapping("/test")
    public String test() {
        return chatClient.prompt()
                .user("说'你好，Spring AI！'")
                .call()
                .content();
    }
}

启动应用并访问 http://localhost:8080/api/ai/test，如果返回 AI 响应则配置成功。

常见问题

1. API Key 无效

Error: Invalid API Key

解决方案：

检查环境变量是否正确设置
确认 API Key 未过期
验证 API Key 格式正确

2. 网络连接失败

Error: Connection refused

解决方案：

检查网络连接
如使用代理，配置代理设置
对于国内用户，可能需要配置 API 代理

spring:
  ai:
    openai:
      base-url: https://your-proxy-url.com

3. Ollama 连接失败

Error: Cannot connect to Ollama

解决方案：

确保 Ollama 服务已启动：ollama serve
检查端口是否正确（默认 11434）
拉取所需模型：ollama pull llama3.2

4. 依赖冲突

Error: NoSuchMethodError / ClassNotFoundException

解决方案：

使用 Spring AI BOM 管理版本
检查依赖树：mvn dependency:tree
排除冲突依赖

小结

本章我们学习了：

项目创建：使用 Spring Initializr 或手动配置
依赖管理：配置 Spring AI BOM
模型配置：OpenAI、Ollama、Azure 等多种提供商
向量数据库：PGVector、Chroma、Redis 等配置
问题排查：常见配置问题解决方案

下一步

ChatClient API - 学习聊天客户端 API
提示词模板 - 掌握提示词工程

系统要求​

创建项目​

方式一：Spring Initializr​

方式二：手动创建​

Maven 配置​

Gradle 配置​

模型提供商配置​

OpenAI​

Ollama（本地模型）​

Azure OpenAI​

Anthropic Claude​

阿里云通义千问​

环境变量配置​

方式一：系统环境变量​

方式二：.env 文件​

方式三：application.yml 引用​

向量数据库配置​

PGVector​

Chroma​

Redis​

验证配置​

常见问题​

1. API Key 无效​

2. 网络连接失败​

3. Ollama 连接失败​

4. 依赖冲突​

小结​

下一步​

系统要求

创建项目

方式一：Spring Initializr

方式二：手动创建

Maven 配置

Gradle 配置

模型提供商配置

OpenAI

Ollama（本地模型）

Azure OpenAI

Anthropic Claude

阿里云通义千问

环境变量配置

方式一：系统环境变量

方式二：.env 文件

方式三：application.yml 引用

向量数据库配置

PGVector

Chroma

Redis

验证配置

常见问题

1. API Key 无效

2. 网络连接失败

3. Ollama 连接失败

4. 依赖冲突

小结

下一步