)
一、ChatModel 聊天模型核心1. 公共能力能力说明多模态文本/图片/PDF/音频/视频输入不同模型支持不一样Tools/Function Call函数调用让LLM调用Java本地方法查询外部接口、数据库流式处理FluxChatResponseSSE流式输出打字机效果重试spring.ai.retry.*全局重试配置指数退避可观测性链路追踪、指标、日志内置JSON输出两种模式简单JSON / JSON Schema强约束结构化输出本地部署Ollama 可本地跑模型DeepSeek/OpenAI是云端APIOpenAI兼容APIOllama、DeepSeek、vLLM都兼容OpenAI协议可以直接复用OpenAI客户端通用重试配置所有模型共享spring: ai: retry: max-attempts: 10 backoff: initial-interval: 2s multiplier: 5 max-interval: 3m on-client-errors: false # 4xx默认不重试2. DeepSeek 模型云端API依赖 starter自动配置dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-deepseek/artifactId /dependencyapplication.ymlspring: ai: deepseek: api-key: ${DEEPSEEK_API_KEY} # 环境变量注入不要硬编码 base-url: [https://api.deepseek.com](https://api.deepseek.com) chat: options: model: deepseek-chat # deepseek-reasoner为推理模型 temperature: 0.8 maxTokens: 2000关键特性双模型deepseek-chat通用对话deepseek-reasoner推理模型返回独立思维链CoTreasoningContent多轮对话注意不要把上一轮的reasoningContent塞回消息列表否则报400只保留最终回答文本进入上下文前缀补全DeepSeekAssistantMessage.prefixAssistantMessage(\python\n)强制模型输出指定代码块获取推理内容示例ChatResponse response chatModel.call(new Prompt(9.11 and 9.8 which bigger?, DeepSeekChatOptions.builder().model(DeepSeekApi.ChatModel.DEEPSEEK_REASONER.getValue()).build() )); DeepSeekAssistantMessage msg (DeepSeekAssistantMessage) response.getResult().getOutput(); String reasoning msg.getReasoningContent(); // 思考过程 String answer msg.getText(); // 最终答案手动创建客户端不使用自动配置DeepSeekApi deepSeekApi DeepSeekApi.builder().apiKey(apiKey).build(); DeepSeekChatOptions options DeepSeekChatOptions.builder().model(deepseek-chat).temperature(0.4).build(); DeepSeekChatModel chatModel DeepSeekChatModel.builder().deepSeekApi(deepSeekApi).defaultOptions(options).build();3. Ollama本地部署模型重点依赖starterdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependencyapplication.ymlspring:ai:ollama:base-url:[http://localhost:11434](http://localhost:11434)init:pull-model-strategy:when_missing# 可选 always / never / when_missing生产建议never提前ollama pullchat:options:model:llama3.2temperature:0.7num-ctx:2048# 上下文窗口keep-alive:5m# 模型驻留内存时长启动拉取模型ollama pull llama3.2支持HuggingFace GGUF模型ollama pull hf.co/xxx核心能力思考模式 Thinking Modedeepseek-r1/qwen3OllamaChatOptions.builder().model(deepseek-r1).enableThinking()// 开启思考.build();// 获取思考内容存在metadata thinkingStringthinkingresponse.getResult().getMetadata().get(thinking);若用OpenAI兼容端点对接ollama思考字段名称变成reasoningContent结构化输出两种模式.format(json)任意合法JSON结构不可控.outputSchema(jsonSchemaString)强约束生产推荐强制输出匹配JSON Schema搭配BeanOutputConverter直接把返回JSON转Java Record对象多模态llava系列模型支持传入图片MediavarimageResourcenewClassPathResource(test.png);UserMessageuserMessagenewUserMessage(描述图片,newMedia(MimeTypeUtils.IMAGE_PNG,imageResource));OpenAI兼容模式直接使用OpenAiChatModel对接ollama服务4. OpenAI ChatModelgpt系列兼容通用OpenAI协议依赖starterdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId/dependencyapplication.ymlspring:ai:openai:api-key:${OPENAI_API_KEY}base-url:[https://api.openai.com](https://api.openai.com)chat:options:model:gpt-4o-mini temperature:0.7区分推理模型参数普通模型(gpt4o/gpt3.5)maxTokenso1/o3推理系列maxCompletionTokens两者互斥不能同时设置重点多模态gpt4o支持图片、音频输入responseFormat支持JSON_OBJECT/JSON_SCHEMA强结构化输出extraBody向OpenAI兼容服务vLLM/Ollama/DeepSeek传递模型特有参数top_k、repeat_penalty推理内容官方OpenAI gpt o系列接口不返回reasoningContentDeepSeek R1/vLLM兼容接口才返回reasoningContent5. ChatController 通用示例三个模型写法几乎一样RestControllerpublicclassChatController{privatefinalChatModelchatModel;AutowiredpublicChatController(ChatModelchatModel){this.chatModelchatModel;}// 同步返回GetMapping(/ai/generate)publicMapString,Stringgenerate(RequestParam(defaultValue讲个笑话)Stringmessage){returnMap.of(generation,chatModel.call(message));}// 流式SSEGetMapping(/ai/generateStream)publicFluxChatResponsestream(RequestParam(defaultValue讲个笑话)Stringmessage){PromptpromptnewPrompt(newUserMessage(message));returnchatModel.stream(prompt);}}二、ImageModel 图像生成模型DALL·E顶层接口ImageModel入参ImagePrompt返回ImageResponseFunctionalInterfacepublicinterfaceImageModelextendsModelImagePrompt,ImageResponse{ImageResponsecall(ImagePromptrequest);}ImagePrompt包装多条ImageMessage ImageOptionsImageMessage文本提示词 权重weightImageResponseImageGeneration列表包含图片二进制/urlOpenAI DALL·E 配置spring:ai:openai:api-key:${OPENAI_API_KEY}image:options:model:dall-e-3size:1024x1024 quality:hd response-format:b64_json # url/b64_json代码示例ImageResponseresponseopenaiImageModel.call(newImagePrompt(一只浅金色小狗,OpenAiImageOptions.builder().quality(hd).N(1).height(1024).width(1024).build()));ImageGenerationgenresponse.getResult();byte[]imageBytesgen.getOutput().getImageBytes();三、ModerationModel 内容审核模型OpenAI Moderation检测文本是否包含违规内容暴力、色情、自残、仇恨言论ModerationPromptpromptnewModerationPrompt(待审核文本);ModerationResponseresponseopenAiModerationModel.call(prompt);Moderationresultresponse.getResult().getOutput();booleanflaggedresult.isFlagged();// 是否标记违规Categoriescategoriesresult.getCategories();// categories.isSexual() / isViolence() / isSelfHarm() 等 二、SpringAI+DeepSeek-模型(Model)
一、ChatModel 聊天模型核心1. 公共能力能力说明多模态文本/图片/PDF/音频/视频输入不同模型支持不一样Tools/Function Call函数调用让LLM调用Java本地方法查询外部接口、数据库流式处理FluxChatResponseSSE流式输出打字机效果重试spring.ai.retry.*全局重试配置指数退避可观测性链路追踪、指标、日志内置JSON输出两种模式简单JSON / JSON Schema强约束结构化输出本地部署Ollama 可本地跑模型DeepSeek/OpenAI是云端APIOpenAI兼容APIOllama、DeepSeek、vLLM都兼容OpenAI协议可以直接复用OpenAI客户端通用重试配置所有模型共享spring: ai: retry: max-attempts: 10 backoff: initial-interval: 2s multiplier: 5 max-interval: 3m on-client-errors: false # 4xx默认不重试2. DeepSeek 模型云端API依赖 starter自动配置dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-deepseek/artifactId /dependencyapplication.ymlspring: ai: deepseek: api-key: ${DEEPSEEK_API_KEY} # 环境变量注入不要硬编码 base-url: [https://api.deepseek.com](https://api.deepseek.com) chat: options: model: deepseek-chat # deepseek-reasoner为推理模型 temperature: 0.8 maxTokens: 2000关键特性双模型deepseek-chat通用对话deepseek-reasoner推理模型返回独立思维链CoTreasoningContent多轮对话注意不要把上一轮的reasoningContent塞回消息列表否则报400只保留最终回答文本进入上下文前缀补全DeepSeekAssistantMessage.prefixAssistantMessage(\python\n)强制模型输出指定代码块获取推理内容示例ChatResponse response chatModel.call(new Prompt(9.11 and 9.8 which bigger?, DeepSeekChatOptions.builder().model(DeepSeekApi.ChatModel.DEEPSEEK_REASONER.getValue()).build() )); DeepSeekAssistantMessage msg (DeepSeekAssistantMessage) response.getResult().getOutput(); String reasoning msg.getReasoningContent(); // 思考过程 String answer msg.getText(); // 最终答案手动创建客户端不使用自动配置DeepSeekApi deepSeekApi DeepSeekApi.builder().apiKey(apiKey).build(); DeepSeekChatOptions options DeepSeekChatOptions.builder().model(deepseek-chat).temperature(0.4).build(); DeepSeekChatModel chatModel DeepSeekChatModel.builder().deepSeekApi(deepSeekApi).defaultOptions(options).build();3. Ollama本地部署模型重点依赖starterdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependencyapplication.ymlspring:ai:ollama:base-url:[http://localhost:11434](http://localhost:11434)init:pull-model-strategy:when_missing# 可选 always / never / when_missing生产建议never提前ollama pullchat:options:model:llama3.2temperature:0.7num-ctx:2048# 上下文窗口keep-alive:5m# 模型驻留内存时长启动拉取模型ollama pull llama3.2支持HuggingFace GGUF模型ollama pull hf.co/xxx核心能力思考模式 Thinking Modedeepseek-r1/qwen3OllamaChatOptions.builder().model(deepseek-r1).enableThinking()// 开启思考.build();// 获取思考内容存在metadata thinkingStringthinkingresponse.getResult().getMetadata().get(thinking);若用OpenAI兼容端点对接ollama思考字段名称变成reasoningContent结构化输出两种模式.format(json)任意合法JSON结构不可控.outputSchema(jsonSchemaString)强约束生产推荐强制输出匹配JSON Schema搭配BeanOutputConverter直接把返回JSON转Java Record对象多模态llava系列模型支持传入图片MediavarimageResourcenewClassPathResource(test.png);UserMessageuserMessagenewUserMessage(描述图片,newMedia(MimeTypeUtils.IMAGE_PNG,imageResource));OpenAI兼容模式直接使用OpenAiChatModel对接ollama服务4. OpenAI ChatModelgpt系列兼容通用OpenAI协议依赖starterdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId/dependencyapplication.ymlspring:ai:openai:api-key:${OPENAI_API_KEY}base-url:[https://api.openai.com](https://api.openai.com)chat:options:model:gpt-4o-mini temperature:0.7区分推理模型参数普通模型(gpt4o/gpt3.5)maxTokenso1/o3推理系列maxCompletionTokens两者互斥不能同时设置重点多模态gpt4o支持图片、音频输入responseFormat支持JSON_OBJECT/JSON_SCHEMA强结构化输出extraBody向OpenAI兼容服务vLLM/Ollama/DeepSeek传递模型特有参数top_k、repeat_penalty推理内容官方OpenAI gpt o系列接口不返回reasoningContentDeepSeek R1/vLLM兼容接口才返回reasoningContent5. ChatController 通用示例三个模型写法几乎一样RestControllerpublicclassChatController{privatefinalChatModelchatModel;AutowiredpublicChatController(ChatModelchatModel){this.chatModelchatModel;}// 同步返回GetMapping(/ai/generate)publicMapString,Stringgenerate(RequestParam(defaultValue讲个笑话)Stringmessage){returnMap.of(generation,chatModel.call(message));}// 流式SSEGetMapping(/ai/generateStream)publicFluxChatResponsestream(RequestParam(defaultValue讲个笑话)Stringmessage){PromptpromptnewPrompt(newUserMessage(message));returnchatModel.stream(prompt);}}二、ImageModel 图像生成模型DALL·E顶层接口ImageModel入参ImagePrompt返回ImageResponseFunctionalInterfacepublicinterfaceImageModelextendsModelImagePrompt,ImageResponse{ImageResponsecall(ImagePromptrequest);}ImagePrompt包装多条ImageMessage ImageOptionsImageMessage文本提示词 权重weightImageResponseImageGeneration列表包含图片二进制/urlOpenAI DALL·E 配置spring:ai:openai:api-key:${OPENAI_API_KEY}image:options:model:dall-e-3size:1024x1024 quality:hd response-format:b64_json # url/b64_json代码示例ImageResponseresponseopenaiImageModel.call(newImagePrompt(一只浅金色小狗,OpenAiImageOptions.builder().quality(hd).N(1).height(1024).width(1024).build()));ImageGenerationgenresponse.getResult();byte[]imageBytesgen.getOutput().getImageBytes();三、ModerationModel 内容审核模型OpenAI Moderation检测文本是否包含违规内容暴力、色情、自残、仇恨言论ModerationPromptpromptnewModerationPrompt(待审核文本);ModerationResponseresponseopenAiModerationModel.call(prompt);Moderationresultresponse.getResult().getOutput();booleanflaggedresult.isFlagged();// 是否标记违规Categoriescategoriesresult.getCategories();// categories.isSexual() / isViolence() / isSelfHarm() 等