整理时间2026-10-09适用版本Spring AI 1.1.0 / Spring AI Alibaba 1.1.2.xspring-ai-alibaba-starter-dashscope一、整体定位ChatModel API 的作用把发一段自然语言给模型、拿回一段补全文本这件事标准化。它建立在Generic Model API之上提供 Chat 特有的抽象通过Prompt输入封装与ChatResponse输出封装统一与各类 AI 模型的通信屏蔽请求拼装与响应解析的复杂度换模型只需换 Starter 改配置业务代码基本不动。一句话记忆「ChatModel 吃 Prompt吐 ChatResponse」。二、Generic Model API地基publicinterfaceModelTReqextendsModelRequest?,TResextendsModelResponse?{TRescall(TReqrequest);}publicinterfaceStreamingModelTReqextendsModelRequest?,TResChunkextendsModelResponse?{FluxTResChunkstream(TReqrequest);}四个配套抽象接口职责关键方法ModelRequestT封装请求T getInstructions()输入、ModelOptions getOptions()参数ModelOptions可定制选项标记接口无方法ModelResponseT extends ModelResult?封装响应getResult()、getResults()、getMetadata()ModelResultT单个结果T getOutput()、getMetadata()泛型是这套 API 的灵魂ModelPrompt, ChatResponse就是 ChatModel 的精确描述。三、Chat Model API3.1 两个核心接口publicinterfaceChatModelextendsModelPrompt,ChatResponse,StreamingChatModel{defaultStringcall(Stringmessage){...}// 便捷版OverrideChatResponsecall(Promptprompt);// 正式版}publicinterfaceStreamingChatModelextendsStreamingModelPrompt,ChatResponse{defaultFluxStringstream(Stringmessage){...}OverrideFluxChatResponsestream(Promptprompt);}call(String)/stream(String)快速尝鲜用返回纯文本拿不到元数据和 token 用量。call(Prompt)/stream(Prompt)**生产使用」可携带 System/多轮消息 运行时选项。3.2 PromptpublicclassPromptimplementsModelRequestListMessage{privatefinalListMessagemessages;privateChatOptionsmodelOptions;// getInstructions() → messagesgetOptions() → modelOptions}Prompt 消息列表 可选 ChatOptions。多轮对话就是把历史一条条塞进messages。3.3 Message 体系publicinterfaceContent{StringgetText();MapString,ObjectgetMetadata();}publicinterfaceMessageextendsContent{MessageTypegetMessageType();}publicinterfaceMediaContentextendsContent{CollectionMediagetMedia();}// 多模态实现类角色场景SystemMessagesystem人设、规则、输出格式约束UserMessageuser用户输入对无角色概念的模型作为标准类别兜底AssistantMessageassistant模型回复也是流式输出的载体FunctionMessagefunction函数调用结果旧式ToolResponseMessagetool工具执行结果Agent 场景MessageType不是数据格式而是这条消息在对话中扮演的角色。3.4 ChatOptions可移植选项publicinterfaceChatOptionsextendsModelOptions{StringgetModel();FloatgetFrequencyPenalty();// -2.0~2.0降低重复 tokenIntegergetMaxTokens();// 最大生成 tokenFloatgetPresencePenalty();// -2.0~2.0鼓励谈新主题ListStringgetStopSequences();// 停止序列FloatgetTemperature();// 0.0~2.0采样温度IntegergetTopK();// Top-K 采样FloatgetTopP();// Top-P 核采样ChatOptionscopy();}各厂商实现可追加私有选项如 OpenAI 的logitBias、seed、user这就是统一接口 厂商扩展的设计。3.5 选项合并流程重要① 启动配置 ChatModel 初始化时设置 defaultOptions全局默认 ↓ ② 运行时配置 Prompt 里携带的 ChatOptions本次请求 ↓ ③ 合并 merge运行时选项 优先 于 启动选项 ↓ ④ 转换输入 转成厂商原生的请求格式如 DashScope 的 payload ↓ ⑤ 转换输出 厂商响应 → 标准化 ChatResponse意义全局一套默认参数个别请求可临时微调defaultOptionsPrompt(messages, runtimeOptions)。本项目正是这样全局application.yml配enable-thinking每次调用在Prompt里单独传temperature(0.7)。3.6 ChatResponse / GenerationpublicclassChatResponseimplementsModelResponseGeneration{privatefinalChatResponseMetadatachatResponseMetadata;// token 用量、速率限制等privatefinalListGenerationgenerations;// n 个候选结果}publicclassGenerationimplementsModelResultAssistantMessage{privatefinalAssistantMessageassistantMessage;privateChatGenerationMetadatachatGenerationMetadata;// 结束原因等}取值链路必须记牢StringtextchatResponse.getResult()// Generation第一个候选.getOutput()// AssistantMessage.getText();// 文本getResults()拿全部候选对应 n1getResult()是getResults().get(0)的快捷方式。四、支持的模型提供商全部走统一的ChatModel/StreamingChatModel接口提供商流式多模态函数调用OpenAI Chat Completion✓✓✓Azure OpenAI✓—✓Alibaba DashScope✓—✓Ollama✓✓✓Hugging Face✗——Google Vertex AI Gemini✓✓✓Amazon Bedrock———Mistral AI✓—✓Anthropic✓—✓五、DashScopeChatModel通义千问5.1 前置条件exportAI_DASHSCOPE_API_KEYyour_api_key# 阿里云百炼申请dependencygroupIdcom.alibaba.cloud.ai/groupIdartifactIdspring-ai-alibaba-starter-dashscope/artifactIdversion1.1.2.1/version/dependency5.2 创建与调用DashScopeApidashScopeApiDashScopeApi.builder().apiKey(System.getenv(AI_DASHSCOPE_API_KEY)).build();ChatModelchatModelDashScopeChatModel.builder().dashScopeApi(dashScopeApi).build();// 简化调用Stringr1chatModel.call(介绍一下Spring框架);// 正式调用PromptpromptnewPrompt(newUserMessage(解释什么是微服务架构));ChatResponseresponsechatModel.call(prompt);Stringanswerresponse.getResult().getOutput().getText();在 Spring Boot 中不需要手写 builder引入 starter 后自动装配DashScopeChatModel直接Autowired/构造器注入即可本项目就是构造器注入方式。5.3 启动选项 vs 运行时选项// 启动选项全局默认DashScopeChatOptionsoptionsDashScopeChatOptions.builder().withModel(qwen-plus).withTemperature(0.7).withMaxToken(2000).withTopP(0.9).build();ChatModelchatModelDashScopeChatModel.builder().dashScopeApi(dashScopeApi).defaultOptions(options).build();// 运行时选项覆盖默认值DashScopeChatOptionsruntimeOptionsDashScopeChatOptions.builder().withTemperature(0.3)// 更确定、更适合评分/抽取.withMaxToken(500).build();PromptpromptnewPrompt(newUserMessage(用一句话总结Java的特点),runtimeOptions);ChatResponseresponsechatModel.call(prompt);5.4 流式响应FluxChatResponseresponseStreamchatModel.stream(newPrompt(详细解释Spring Boot的自动配置原理));responseStream.subscribe(chatResponse-System.out.print(chatResponse.getResult().getOutput().getText()),error-System.err.println(错误: error.getMessage()),()-System.out.println(\n流式响应完成));5.5 多轮对话ListMessagemessagesList.of(newSystemMessage(你是一个Java专家),newUserMessage(什么是Spring Boot?),newAssistantMessage(Spring Boot是...),// 历史回复要显式回填newUserMessage(它有什么优势?));ChatResponseresponsechatModel.call(newPrompt(messages));ChatModel 是无状态的上下文靠你自己维护消息列表需要自动记忆请用ChatMemory或 ReactAgent 的Saver。5.6 函数调用Function CallingToolCallbackweatherFunctionFunctionToolCallback.builder(getWeather,(Stringcity)-晴朗25°C).description(获取指定城市的天气)// 描述决定模型何时调用必须写准.inputType(String.class).build();DashScopeChatOptionsoptionsDashScopeChatOptions.builder().withToolCallbacks(List.of(weatherFunction)).build();ChatResponseresponsechatModel.call(newPrompt(北京的天气怎么样?,options));5.7 支持的模型模型特点qwen-turbo速度快、成本低适合高频短任务qwen-plus增强版综合性价比高qwen-max旗舰版复杂推理最强qwen-max-longcontext长文本场景选型建议出题/创作类用 plus简历评分、答案评估这类需要稳定判定 长 JSON 输出的场景建议qwen-max 低温度0.2~0.3。5.8 与 ReactAgent 集成ReactAgentagentReactAgent.builder().name(my_agent).model(chatModel)// 复用同一个 ChatModel 实例.systemPrompt(你是一个有帮助的AI助手).build();AssistantMessageresponseagent.call(帮我分析这个问题);六、对照本项目xs-interview-agentMockInterviewService是这套 API 的标准用法范本ListMessagemessagesnewArrayList();messages.add(newSystemMessage(resumeAnalysisSystemPromptResource));// system 角色messages.add(newUserMessage(promptTemplate.render(...)));// user 角色PromptpromptnewPrompt(messages,// 运行时选项DashScopeChatOptions.builder().temperature(0.7).build());StringresponsechatModel.call(prompt).getResult().getOutput().getText();// 标准取值链路对照笔记可做的三处优化温度分场景出题保持 0.7评分与评估改 0.2new Prompt(messages, lowTempOptions)稳定性明显提升。别丢ChatResponse当前链式取值直接丢弃了中间对象等于丢弃ChatResponseMetadatatoken 消耗、finishReason。建议先接住再做日志/成本统计ChatResponsecrchatModel.call(prompt);log.info(tokens{},cr.getMetadata().getUsage());Stringtextcr.getResult().getOutput().getText();长任务改流式chatModel.stream(prompt) SSE 推送到interview.html解决评估阶段长时间白屏或用outputType/BeanOutputConverter让框架帮你做结构化输出替掉手写的JsonNode解析与 JSON 去围栏逻辑。七、速查卡// 1. 注入Spring Boot 自动装配推荐privatefinalChatModelchatModel;// 构造器注入// 2. 极简StringtextchatModel.call(你好);// 3. 系统提示 用户消息 运行时参数ListMessagemsgsList.of(newSystemMessage(...),newUserMessage(...));PromptpromptnewPrompt(msgs,DashScopeChatOptions.builder().withModel(qwen-plus).withTemperature(0.2).withMaxToken(4096).build());// 4. 取值StringoutchatModel.call(prompt).getResult().getOutput().getText();FluxChatResponsefluxchatModel.stream(prompt);取值链路ChatResponse → getResult() → Generation → getOutput() → AssistantMessage → getText()合并优先级运行时Prompt的 ChatOptions覆盖启动时defaultOptions。
