spring-ai

Q: How do I install spring-ai?

Run npx skills add https://github.com/full-stack-skills/spring-skills --skill spring-ai in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/spring-ai/ (personal) or .claude/skills/spring-ai/ (project).

by full-stack-skillsBackend & APIs

Provides comprehensive guidance for Spring AI including AI model integration, prompt templates, vector stores, and AI applications. Use when the user asks about Spring AI, needs to integrate AI models, implement RAG applications, or work with AI services in Spring.

Installs: 196
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/full-stack-skills/spring-skills --skill spring-ai

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads spring-ai automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Spring AI 开发指南

概述

Spring AI 是 Spring 官方提供的 AI 应用开发框架，简化了与各种大语言模型（LLM）的集成，包括 OpenAI、Anthropic、Azure OpenAI 等。

核心功能

1. 项目创建

依赖：

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

或使用 Gradle：

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
}

2. Chat Client

配置：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4
          temperature: 0.7

使用 ChatClient：

@Service
public class ChatService {
    private final ChatClient chatClient;

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

    public String chat(String message) {
        return chatClient.call(message);
    }

    public String chatWithPrompt(String userMessage) {
        Prompt prompt = new Prompt(new UserMessage(userMessage));
        ChatResponse response = chatClient.call(prompt);
        return response.getResult().getOutput().getContent();
    }
}

流式响应：

@Service
public class ChatService {
    private final StreamingChatClient streamingChatClient;

    public ChatService(StreamingChatClient streamingChatClient) {
        this.streamingChatClient = streamingChatClient;
    }

    public Flux<String> streamChat(String message) {
        return streamingChatClient.stream(message)
            .map(response -> response.getResult().getOutput().getContent());
    }
}

3. Prompt Template

定义模板：

@Service
public class PromptService {
    private final PromptTemplate promptTemplate;

    public PromptService() {
        this.promptTemplate = new PromptTemplate(
            "请用{style}风格回答以下问题：{question}"
        );
    }

    public String generatePrompt(String style, String question) {
        Map<String, Object> variables = Map.of(
            "style", style,
            "question", question
        );
        return promptTemplate.render(variables);
    }
}

使用 ChatClient：

@Service
public class ChatService {
    private final ChatClient chatClient;
    private final PromptTemplate promptTemplate;

    public ChatService(ChatClient chatClient) {
        this.chatClient = chatClient;
        this.promptTemplate = new PromptTemplate(
            "请用{style}风格回答以下问题：{question}"
        );
    }

    public String chatWithStyle(String style, String question) {
        Prompt prompt = promptTemplate.create(Map.of(
            "style", style,
            "question", question
        ));
        ChatResponse response = chatClient.call(prompt);
        return response.getResult().getOutput().getContent();
    }
}

4. Embedding

配置：

spring:
  ai:
    openai:
      embedding:
        options:
          model: text-embedding-ada-002

使用 EmbeddingClient：

@Service
public class EmbeddingService {
    private final EmbeddingClient embeddingClient;

    public EmbeddingService(EmbeddingClient embeddingClient) {
        this.embeddingClient = embeddingClient;
    }

    public List<Double> embed(String text) {
        EmbeddingResponse response = embeddingClient.embedForResponse(
            List.of(text)
        );
        return response.getResult().getOutput();
    }

    public List<List<Double>> embedBatch(List<String> texts) {
        EmbeddingResponse response = embeddingClient.embedForResponse(texts);
        return response.getResult().getOutput();
    }
}

5. Vector Store

配置：

spring:
  ai:
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE

使用 VectorStore：

@Service
public class VectorStoreService {
    private final VectorStore vectorStore;
    private final EmbeddingClient embeddingClient;

    public VectorStoreService(
        VectorStore vectorStore,
        EmbeddingClient embeddingClient
    ) {
        this.vectorStore = vectorStore;
        this.embeddingClient = embeddingClient;
    }

    public void addDocument(String id, String content) {
        List<Double> embedding = embeddingClient.embed(content);
        Document document = new Document(id, content, Map.of());
        vectorStore.add(List.of(document));
    }

    public List<Document> searchSimilar(String query, int topK) {
        List<Double> queryEmbedding = embeddingClient.embed(query);
        return vectorStore.similaritySearch(
            SearchRequest.query(query)
                .withTopK(topK)
        );
    }
}

6. Function Calling

定义函数：

@Bean
public Function<WeatherRequest, WeatherResponse> weatherFunction() {
    return request -> {
        // 调用天气 API
        WeatherResponse response = weatherService.getWeather(
            request.getLocation()
        );
        return response;
    };
}

配置 Function Calling：

@Configuration
public class FunctionCallingConfig {
    @Bean
    public Function<WeatherRequest, WeatherResponse> weatherFunction() {
        return request -> {
            // 实现天气查询逻辑
            return new WeatherResponse(/* ... */);
        };
    }
}

使用 Function Calling：

@Service
public class ChatService {
    private final ChatClient chatClient;
    private final FunctionCallbackRegistry functionCallbackRegistry;

    public ChatService(
        ChatClient chatClient,
        FunctionCallbackRegistry functionCallbackRegistry
    ) {
        this.chatClient = chatClient;
        this.functionCallbackRegistry = functionCallbackRegistry;
    }

    public String chatWithFunction(String message) {
        Prompt prompt = new Prompt(
            new UserMessage(message),
            functionCallbackRegistry.getFunctionCallbacks()
        );
        ChatResponse response = chatClient.call(prompt);
        return response.getResult().getOutput().getContent();
    }
}

7. 多模型支持

配置多个模型：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}

使用特定模型：

@Service
public class MultiModelService {
    private final ChatClient openAiChatClient;
    private final ChatClient anthropicChatClient;

    public MultiModelService(
        @Qualifier("openAiChatClient") ChatClient openAiChatClient,
        @Qualifier("anthropicChatClient") ChatClient anthropicChatClient
    ) {
        this.openAiChatClient = openAiChatClient;
        this.anthropicChatClient = anthropicChatClient;
    }

    public String chatWithOpenAI(String message) {
        return openAiChatClient.call(message);
    }

    public String chatWithAnthropic(String message) {
        return anthropicChatClient.call(message);
    }
}

最佳实践

1. 配置管理

使用环境变量存储 API Key
区分开发和生产环境配置
配置合理的超时和重试策略

2. 错误处理

@Service
public class ChatService {
    private final ChatClient chatClient;

    public String chat(String message) {
        try {
            return chatClient.call(message);
        } catch (Exception e) {
            // 处理错误
            log.error("Chat error", e);
            return "抱歉，处理请求时出现错误";
        }
    }
}

3. 性能优化

使用流式响应提升用户体验
合理使用缓存减少 API 调用
批量处理 Embedding 请求

4. 成本控制

选择合适的模型（GPT-3.5 vs GPT-4）
限制 Token 使用量
监控 API 调用情况

常用依赖

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

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

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

<!-- Vector Store (PGVector) -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId>
</dependency>

示例 Prompt

"如何使用 Spring AI 集成 OpenAI？"
"Spring AI 中如何实现流式响应？"
"如何在 Spring AI 中使用 Embedding 和 Vector Store？"
"Spring AI 中如何实现 Function Calling？"
"如何配置 Spring AI 支持多个模型？"

FAQ

What does the spring-ai skill do?

How do I install spring-ai?

Run npx skills add https://github.com/full-stack-skills/spring-skills --skill spring-ai in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/spring-ai/ (personal) or .claude/skills/spring-ai/ (project).

Which AI agents can use spring-ai?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is spring-ai safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains spring-ai?

It is published by full-stack-skills in full-stack-skills/spring-skills. It has 196 recorded installs.