Spring AI 核心架构解析：构建企业级 AI 应用的 Java 新范式

+-------------------------------------------------------+
|                  应用层 (Applications)                 |
|   - 智能客服 / 文档问答 / 代码助手 / Agent 工作流     |
+----------------------+--------------------------------+
                       |
        +--------------v--------------+
        |       功能增强层 (Enhancements) |
        | - PromptTemplate              |
        | - Structured Output           |
        | - Function Calling            |
        | - RAG 流程编排                |
        +---------------+---------------+
                        |
         +--------------v--------------+
         |      模型抽象层 (Abstractions) |
         | - ChatClient / ChatModel      |
         | - EmbeddingModel              |
         | - ImageModel / AudioModel     |
         +---------------+---------------+
                         |
          +-------------v-------------+
          |     数据支撑层 (Data Layer)  |
          | - VectorStore (Milvus/Pinecone/Redis)|
          | - DocumentReader & TextSplitter    |
          +---------------+---------------+
                        |
           +------------v------------+
           |   外部服务与模型提供者     |
           | - OpenAI / Anthropic      |
           | - Alibaba Tongyi Qwen     |
           | - Ollama (Llama3, DeepSeek)|
           | - Hugging Face Inference API |
           +---------------------------+

graph TD
    A[Applications\n(智能客服/Agent/代码生成)] --> B[功能增强层]
    B --> C[模型抽象层]
    C --> D[数据支撑层]
    D --> E[外部模型服务]

    subgraph 功能增强层
        B1[PromptTemplate]
        B2[Structured Output]
        B3[Function Calling]
        B4[RAG 编排]
    end

    subgraph 模型抽象层
        C1[ChatClient / ChatModel]
        C2[EmbeddingModel]
        C3[ImageModel / AudioModel]
    end

    subgraph 数据支撑层
        D1[VectorStore\n(Milvus/Pinecone/Redis)]
        D2[DocumentReader]
        D3[TextSplitter]
    end

    subgraph 外部服务
        E1[OpenAI GPT-4o]
        E2[Alibaba Qwen]
        E3[Ollama (Llama3)]
        E4[HuggingFace]
    end

    B --> C
    C --> D
    D --> E

spring init --dependencies=ai,web,actuator my-ai-app

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.1.0-M3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

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

server:
  port: 8080

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        model: llama3.2
        options:
          temperature: 0.7
    openai:
      api-key: ${OPENAI_API_KEY:}
      chat:
        model: gpt-4o
    chat:
      default-model: ollama

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/ai/chat")
    public String chat(@RequestParam String message) {
        return chatClient.call(message);
    }
}

@Service
public class AdvancedChatService {

    private final ChatModel chatModel;

    public AdvancedChatService(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    public String generate(String prompt) {
        Prompt p = new Prompt(
            new SystemMessage("你是一个专业的技术顾问。"),
            new UserMessage(prompt)
        );
        return chatModel.call(p).getResult().getOutput().getContent();
    }
}

@Controller
public class StreamingController {

    private final ChatModel chatModel;

    public StreamingController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping(value = "/ai/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public SseEmitter stream(@RequestParam String message) {
        SseEmitter emitter = new SseEmitter(Long.MAX_VALUE);

        chatModel.stream(new Prompt(message))
            .doOnError(emitter::completeWithError)
            .doOnComplete(emitter::complete)
            .subscribe(response -> {
                try {
                    emitter.send(response.getResult().getOutput().getContent());
                } catch (IOException e) {
                    emitter.completeWithError(e);
                }
            });

        return emitter;
    }
}

public class WeatherInfo {
    private String city;
    private double temperature;
    private String condition;
    private String unit = "Celsius";
    // getters & setters
}

@Service
public class WeatherService {

    private final ChatModel chatModel;

    public WeatherInfo getWeather(String city) {
        PromptTemplate template = new PromptTemplate(
            "查询 {city} 的当前天气，返回 JSON 格式，包含 city, temperature, condition"
        );
        Prompt prompt = template.create(Map.of("city", city));

        return chatModel.call(prompt)
            .getResult()
            .getOutput()
            .getContentAs(WeatherInfo.class); // 自动反序列化
    }
}

@Service
public class WeatherTool {

    @Tool(description = "根据城市获取实时天气")
    public String getCurrentWeather(String city) {
        // 调用真实天气 API
        return "{ \"temperature\": 25, \"condition\": \"Sunny\" }";
    }
}

@Service
public class KnowledgeQaService {

    private final VectorStore vectorStore;
    private final ChatModel chatModel;
    private final TextSplitter textSplitter;
    private final EmbeddingModel embeddingModel;

    public KnowledgeQaService(VectorStore vectorStore,
                            ChatModel chatModel,
                            TextSplitter textSplitter,
                            EmbeddingModel embeddingModel) {
        this.vectorStore = vectorStore;
        this.chatModel = chatModel;
        this.textSplitter = textSplitter;
        this.embeddingModel = embeddingModel;
    }

    // 文档注入
    public void ingest(String filePath) throws IOException {
        String content = Files.readString(Paths.get(filePath));
        Document doc = new Document(content);
        List<Document> chunks = textSplitter.split(List.of(doc));
        
        List<Embedding> embeddings = embeddingModel.embed(chunks);
        List<ScoredVector> vectors = IntStream.range(0, chunks.size())
            .mapToObj(i -> ScoredVector.of(embeddings.get(i).vector(), chunks.get(i).getContent()))
            .collect(Collectors.toList());

        vectorStore.add(vectors);
    }

    // 问答
    public String ask(String question) {
        List<Document> docs = vectorStore.similaritySearch(question);
        String context = docs.stream().map(Document::getContent).collect(Collectors.joining("\n\n"));

        String prompt = """
            基于以下知识回答问题，不要编造：
            <context>
            %s
            </context>
            问题：%s
            """.formatted(context, question);

        return chatModel.call(new Prompt(prompt)).getResult().getOutput().getContent();
    }
}

spring-ai-demo/
├── src/
│   ├── main/
│   │   ├── java/com/example/ai/
│   │   │   ├── controller/
│   │   │   │   └── AiController.java
│   │   │   ├── service/
│   │   │   │   ├── RagService.java
│   │   │   │   ├── WeatherTool.java
│   │   │   │   └── CodeAssistant.java
│   │   │   ├── config/
│   │   │   │   └── AiConfig.java
│   │   │   └── SpringAiDemoApplication.java
│   │   └── resources/
│   │       ├── application.yml
│   │       └── documents/knowledge.md
├── pom.xml
└── docker-compose.yml

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

    private final ChatClient chatClient;
    private final RagService ragService;
    private final CodeAssistant codeAssistant;

    public AiController(ChatClient chatClient,
                        RagService ragService,
                        CodeAssistant codeAssistant) {
        this.chatClient = chatClient;
        this.ragService = ragService;
        this.codeAssistant = codeAssistant;
    }

    @GetMapping("/chat")
    public String simpleChat(@RequestParam String msg) {
        return chatClient.call(msg);
    }

    @PostMapping("/rag/query")
    public String queryKnowledge(@RequestBody Map<String, String> request) {
        return ragService.ask(request.get("question"));
    }

    @PostMapping("/code/generate")
    public String generateCode(@RequestBody Map<String, String> request) {
        return codeAssistant.generateCode(request.get("requirement"));
    }
}

version: '3.8'

services:
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama:/root/.ollama
    environment:
      - OLLAMA_HOST=0.0.0.0:11434
    command: serve

  spring-ai-app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SPRING_AI_OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama

volumes:
  ollama:

FROM eclipse-temurin:17-jre-alpine
VOLUME /tmp
COPY target/spring-ai-demo.jar app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

# 构建 JAR
./mvnw clean package -DskipTests

# 启动服务
docker-compose up -d

# 加载模型
docker exec -it springaidemo-ollama-1 ollama pull llama3.2

# 简单对话
curl "http://localhost:8080/api/ai/chat?msg=讲个笑话"

# RAG 查询
curl -X POST http://localhost:8080/api/ai/rag/query \
-H "Content-Type: application/json" \
-d '{"question": "我们公司的核心技术是什么？"}'

# 代码生成
curl -X POST http://localhost:8080/api/ai/code/generate \
-H "Content-Type: application/json" \
-d '{"requirement": "创建一个带分页的用户查询接口"}'

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull llama3.2