在 AI 人才市场的讨论里年薪千万不如估值百亿AI 大神看不上大厂这类说法经常出现。它背后的真实信号不是薪酬本身而是 AI 行业的竞争焦点变了大家关注的已经不单是哪个模型参数更大而是谁能把模型能力变成稳定、可评估、可交付的软件产品。对开发者来说这意味着 AI 大模型应用开发的核心能力正从会调 API转向工程化落地。这篇文章不讨论薪酬和公司选择而是拆解 AI 应用开发中最容易被低估、却最能拉开差距的工程环节AI Agent 的任务编排、Spring AI 在 Java 生态里的集成方式、模型部署的选型、AI 幻觉的排查以及提示词、上下文和成本三个隐藏抓手。适合已经写过接口、对 Spring Boot 有一定了解的开发者。读完以后你会得到一张从概念到代码、从验证到排查的 AI 应用工程实践地图而不是一堆散落的 API 示例。1. 先想清楚AI 应用竞争的是工程能力不是模型参数1.1 为什么同样的模型有人做出 demo有人做出产品很多团队拿到的大模型是一样的甚至用的是同一个 API。差距往往出现在模型之外。观察实际落地项目时最常看到的五个问题提示词是写死在业务代码里还是按模板和场景统一管理用户输入千奇百怪时程序能不能保证输出结构稳定模型答错时有没有校验、兜底和人工确认一次请求消耗多少 token、响应有多慢、并发上来会不会打爆成本线上出问题时日志和链路能不能支撑快速定位这五个问题没有一个是模型本身能回答的全部是工程问题。大模型 API 提供的是强大的生成能力但它只是一个能力引擎。要让引擎在真实业务里稳定工作还需要一层完整的工程骨架接口层把用户输入变成规范请求提示词层控制模型行为边界检索层补充最新知识校验层拦截错误输出缓存和限流保护成本与稳定性监控层记录每一次调用的质量。缺少任何一层应用停留在 demo 阶段非常正常。所以判断一个 AI 应用是否能上线不能只看模型答得准不准还要看模型答错时系统会怎样。工程化的核心就是在模型能力之外补上可控性和确定性。1.2 AI 大神看不上大厂背后的技术信号用AI 大神来概括技术能力优秀的人不一定准确但这类讨论里有一个值得注意的信号能持续做出好 AI 产品的人往往更愿意待在自己能定义技术方向、能快速尝试新方案的环境里而不是固化在成熟流程中维护一套稳定旧系统。这不是价值观对错问题而是技术成长路径的选择问题。对普通开发者来说与其羡慕别人的薪酬或估值不如把注意力放在可迁移的能力上。目前市面上大量岗位需要的不是发明新模型的人而是能把现有模型接进业务系统的人。具体来说就是做好这些事情把开源模型或商业 API 接入业务系统设计 Agent 的任务流程治理 AI 幻觉优化请求成本建立评估和回归机制。这些能力不依赖某一家公司也不绑定某一个模型换一个场景仍然成立。后面几节就围绕这条主线展开不追逐模型前沿而是把模型当成一个组件把工程做扎实。2. AI Agent、Spring AI、模型部署三个概念要放在一起理解2.1 AI Agent让模型从回答问题变成完成任务AI Agent智能体是目前 AI 应用开发里最热的方向之一。通俗地说它不是让模型说一段话而是让模型根据一个目标自己拆解步骤、调用工具、检查结果最后完成任务。一个典型 Agent 至少包含四部分规划拆解任务决定下一步做什么。记忆短期记忆保存当前任务上下文长期记忆来自外部存储或知识库。工具调用模型通过函数调用访问外部系统比如查数据库、调接口、发消息。执行与反馈执行动作后把结果再交给模型判断循环直到结束。工程难度在于Agent 的自由度越大越不可控。所以真实项目里不会让 Agent 无限循环而是会设置最大轮数、工具白名单、输出格式约束和人工确认节点。Spring AI 在 Java 生态里提供的工具主要就是解决这类工程化诉求而不是让模型随便跑。2.2 Spring AIJava 生态接入大模型的一层抽象Spring AI 是一个面向 AI 应用的 Spring 生态项目。它的目标是提供统一抽象层让开发者用类似 Spring Boot 的方式接入大模型而不是为每家模型厂商写一套不同的调用代码。它解决的问题有几类ChatClient统一聊天接口支持 system、user 提示词管理和结构化输出。EmbeddingModel统一向量化接口方便接入不同向量模型。VectorStore统一向量存储抽象对接内存、Redis、PGVector、Milvus。Tool 调用通过注解把 Spring Bean 暴露成可被模型调用的工具。Advisors类似过滤器用来做上下文整理、日志记录、内容改写。实际项目里Spring AI 的价值不是让模型能力变强而是降低集成成本让团队用熟悉的 Spring 风格开发 AI 功能。需要注意Spring AI 版本迭代较快不同版本 API 会有差异落地前要以官方文档和依赖版本为准不要照抄旧版本博客。2.3 模型部署自建、API 与私有化的取舍模型部署是 AI 应用落地里很容易被低估的一环。很多团队在测试环境用 API 调得很顺到了生产环境才发现延迟、成本、合规和可用性全都不一样。三种常见方式的对比部署方式优点主要代价适合场景商业 API接入快、免运维单次调用成本、数据出域、限流快速验证、数据敏感度不高的场景自建推理服务可控成本、数据内部闭环GPU 资源、运维复杂、版本更新高频调用、数据隐私要求高私有化一体机或混合部署满足合规、离线可用前期投入大、模型更新慢政企、内网、强合规场景自建推理路线里常见做法是先用量化模型在开发机验证效果再通过推理框架暴露成兼容接口业务侧无需改代码。以本地方便验证为例可以用 Ollama 这类工具快速启动一个模型# 本地开发验证先确认 Ollama 已安装 ollama pull qwen2.5:7b ollama run qwen2.5:7b业务侧配置改成指向本地地址即可spring: ai: openai: base-url: http://localhost:11434/v1 api-key: ${LOCAL_AI_KEY}这里要特别强调不要把本地能跑通等同于生产可以用。推理服务的吞吐、并发上限、GPU 显存占用和冷启动时间都需要单独做压测和容量规划。3. 搭建一个最小可运行的 AI 应用工程骨架3.1 技术选型用最小闭环验证全链路为了演示从模型调用到工程化的完整链路这里使用一个最小闭环Spring Boot 提供接口层Spring AI 封装模型调用内存向量存储模拟知识库最后用结构化输出保证返回结果可控。这个骨架把提示词、检索、输出校验、工具调用串在一起适合作为学习模板。示例工程假设技术栈Java 17、Spring Boot 3.x、Spring AI。模型来源兼容接口开发环境可以是商业 API也可以是本地推理服务。知识库内存向量存储重启后数据清空生产环境要换成 Redis、PGVector 或 Milvus。3.2 项目结构与依赖配置先看最小目录结构ai-demo ├── pom.xml └── src/main/java/com/example/ai ├── AiDemoApplication.java ├── controller/AiController.java ├── service/AiChatService.java ├── service/RagService.java ├── config/VectorStoreConfig.java └── tool/DeviceTools.javapom.xml 中引入 Spring AI 相关依赖。版本不写死以 Maven 中央仓库当前稳定版为准避免教程里的版本和实际环境不一致。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-vector-store/artifactId /dependencyapplication.yml 里配置模型地址、密钥和基础参数spring: application: name: ai-demo ai: openai: base-url: ${AI_BASE_URL:http://localhost:11434/v1} api-key: ${AI_API_KEY:demo-key} chat: options: model: ${AI_MODEL:qwen2.5:7b} temperature: 0.2 client: max-output-tokens: 800密钥不要写死在配置里使用环境变量注入。temperature 调低可以降低输出随机性适合知识问答和结构化输出场景。如果 base-url 指向本地推理服务api-key 填一个占位值也可以但生产环境必须走密钥管理。3.3 核心代码ChatClient、结构化输出与工具调用先定义一个最基础的对话服务Service public class AiChatService { private final ChatClient chatClient; public AiChatService(ChatClient.Builder builder) { this.chatClient builder.build(); } public String ask(String question) { return chatClient.prompt() .system(你是一名资深软件工程师回答要简洁、准确、结构清晰。) .user(question) .call() .content(); } }很多场景不希望模型返回松散文本而是希望返回一个可解析的 JSON 对象。可以用 record 定义返回结构public record Solution(String title, ListString steps, double confidence) { }public Solution plan(String problem) { return chatClient.prompt() .system(给出一个可执行的解决方案并评估置信度。) .user(problem) .entities(Solution.class) .call() .entity(); }这样解析结果就有了类型安全业务层可以进一步校验和兜底。如果模型连续输出不符合结构要检查提示词是否足够明确以及当前模型对结构化输出的支持情况。工具调用是 Agent 的基础能力。通过注解把业务方法暴露给模型Component public class DeviceTools { Tool(description 查询指定设备最近一次在线状态) public String lastOnline(String deviceId) { // 真实项目里这里会查询设备表 return deviceId 最近在线时间2025-01-01 12:00:00; } }创建 ChatClient 时把工具注册进去this.chatClient ChatClient.builder(chatModel) .defaultTools(new DeviceTools()) .build();模型在回答设备问题时可以自行决定是否调用这个工具。工程上建议在 user 提示词里明确先调用工具查询再基于结果回答降低模型瞎猜的概率。3.4 启动验证输入、输出与异常分支在 Controller 暴露 HTTP 接口RestController public class AiController { private final AiChatService chatService; private final RagService ragService; public AiController(AiChatService chatService, RagService ragService) { this.chatService chatService; this.ragService ragService; } GetMapping(/chat) public String chat(RequestParam String question) { return chatService.ask(question); } GetMapping(/rag) public String rag(RequestParam String question) { return ragService.answer(question); } }启动后用 curl 验证curl http://localhost:8080/chat?question什么是缓存穿透curl http://localhost:8080/rag?question数据库连接池的默认连接数是多少正常结果应该是一段结构清晰的回答。异常时常见现象包括服务启动失败密钥或 base-url 配置错误、请求超时模型服务不可用、返回内容为空模型输出被拦截或内容策略限制、返回结构不对结构化输出解析失败。这些现象在排错章节再展开。注意不要只验证程序能启动还要验证输入、输出、异常分支和日志是否符合预期。AI 应用最容易出问题的地方往往发生在模型返回之后。4. AI 幻觉不是模型的锅是工程链路要补的课4.1 幻觉的类型事实性幻觉、逻辑幻觉、指令幻觉AI 幻觉是指模型生成的内容与现实不符、逻辑矛盾或不符合指令要求。常见类型如下类型表现示例事实性幻觉编造不存在的事实虚构某公司发布的版本号或日期逻辑幻觉推理链条站不住前一步说禁用了缓存后一步又说缓存生效指令幻觉不遵守用户明确约束明确要求只输出 JSON结果带了 Markdown 代码块幻觉无法彻底消除但工程上能显著降低。核心思路是不让模型自由发挥它不知道的部分同时给足可溯源的上下文。4.2 缓解幻觉的工程手段第一条是减少回答依赖模型内部记忆。把知识库和当前业务数据通过检索增强RAG放到提示词里让模型优先基于给定上下文作答。RAGService 的最小实现Service public class RagService { private final ChatClient chatClient; private final VectorStore vectorStore; public RagService(ChatClient.Builder builder, VectorStore vectorStore) { this.chatClient builder.build(); this.vectorStore vectorStore; } public String answer(String question) { ListDocument docs vectorStore.similaritySearch( SearchRequest.builder().query(question).topK(3).build()); String context docs.stream() .map(Document::getContent) .collect(Collectors.joining(\n)); return chatClient.prompt() .system(只基于参考资料回答。资料中没有的信息直接说明不知道不要编造。) .user(参考资料\n context \n\n问题 question) .call() .content(); } }这段代码的关键有两点一是给模型的上下文必须来自可溯源资料二是 system 提示词明确限制不知道就直说降低编造概率。第二条是调低温度参数。知识问答、结构化抽取场景建议用 0 到 0.3别用高温度。高温度适合创意写作不适合事实回答。第三条是输出校验与兜底。对结构化输出校验关键字段是否缺失、数值是否合理不合法就重试或走默认值。对涉及操作类的 Agent 任务最后一步增加人工确认或风险校验。幻觉无法彻底消除工程目标是把发生概率降到可控范围并让模型在信息不足时明确告知用户我不确定。4.3 幻觉排查路径排查幻觉问题按这个顺序看输入是否完整。用户问题本身是否模糊缺少关键约束。上下文是否准确。RAG 检索到的文档是否相关、是否太旧、是否混入噪声。提示词是否明确。是否给了模型编造的空间是否缺少不知道就直说的约束。温度是否合适。事实问答是不是用了过高温度。输出校验是否存在。结构化和数值结果有没有校验层。实际项目里幻觉治理不是一次性工作而是要持续积累错误案例集。把用户反馈和评估中发现的问题保存下来作为提示词优化和检索优化的回归数据。5. 提示词、上下文与成本三个隐藏工程抓手5.1 提示词模板化而不是散落在代码里提示词是 AI 应用最重要的业务配置但很多时候会被写散在代码里。推荐做法是放到 resources 下按场景管理src/main/resources/prompts/ ├── chat-system.txt ├── rag-system.txt └── extract-system.txtSpring 里用 Resource 加载提示词模板Value(classpath:/prompts/rag-system.txt) private Resource ragSystemPrompt;模板文件里写清楚角色、任务、约束和输出格式。测试时只改文件不用重新编译业务代码。提示词改动要进入版本管理和代码一起评审、回归。5.2 上下文窗口是资源要按预算分配大模型的上下文窗口不是无限内存。超出窗口长度会发生截断、遗忘或成本暴增所以要把上下文当成资源来管理。三种常见做法截断保留最近 N 轮对话丢弃更早的内容。压缩对历史消息做摘要把长对话压缩成要点。检索只在需要时拉取相关知识片段而不是每次塞入全量知识库。Spring AI 的 Advisor 机制可以做这类处理也可以自己写在调用前的准备函数里。建议所有涉及上下文的逻辑都集中在统一位置方便后续调优和排查。5.3 成本治理从请求结构开始token 成本取决于输入和输出长度。要控制成本先控制请求结构系统提示词保持精简删除不生效的冗余说明。知识检索只传 topK 之后的片段不要传整篇文档。输出限制 tokens避免模型生成超长无用内容。对相同或相似请求加缓存减少重复调用。设置单用户、单接口的限流和配额防止异常调用打爆账单。一个简单缓存思路对问题和检索命中文档的组合做哈希如果近段时间有相同结果直接返回。要注意缓存后的数据时效问题业务数据更新频繁的场景要设置合理的过期时间。6. 从演示到生产还要补齐部署、监控与回滚6.1 配置外置与密钥管理演示项目里配置写在 application.yml生产环境不能这么干。至少要做到模型密钥、数据库密码、存储地址全部使用环境变量或配置中心。不同环境用独立配置禁止把测试环境密钥带到生产。涉及敏感信息的配置进入代码仓库前要做脱敏检查。如果用的是商业 API建议在网关或代理层统一管理密钥不让业务服务直接持有厂商密钥。6.2 日志、追踪与可观测性AI 应用的可观测性比普通应用更强调模型输入输出记录。排错时不能只看 HTTP 状态码还要知道模型收到了什么提示词、返回了什么内容、用了多少 token、耗时多久。生产建议记录以下信息记录项用途用户输入原文判断问题是否模糊最终提示词脱敏后复现模型行为模型输出评估输出质量token 数成本核算延迟和重试次数性能优化工具调用结果排查 Agent 决策链路注意脱敏防止用户隐私和业务敏感数据进入日志。6.3 缓存、限流与回滚策略生产环境需要三件事缓存、限流、回滚。缓存降低重复请求的成本和延迟限流保护模型服务和后端资源回滚在模型升级、提示词调整效果不符合预期时能迅速恢复。模型版本本身也要纳入发布流程。模型厂商更新模型、本地推理服务升级权重都可能改变输出行为。上线前先小流量验证再逐步放量。一旦发现问题要能快速切回上一个可用版本。上线前请自己问一遍模型调用失败时用户看到的是什么有没有兜底提示如果答案是空白页说明工程链路还没走完。7. AI 应用开发的常见坑与排查清单7.1 高频踩坑点速查坑点现象原因解决密钥配置错了启动报 401 或认证失败环境变量没生效、写错密钥检查配置来源使用配置中心或环境变量注入base-url 指向错误连接超时、404地址多空格、路径不支持确认服务地址和版本路径温度过高同一问题多次回答不一致温度参数不适合事实问答降到 0 到 0.3配合结构约束上下文过长请求报错或输出截断超过上下文窗口加截断、压缩或检索结构化输出不稳定JSON 解析失败模型指令不明确或模型能力不足明确输出格式用结构化解析并校验工具调用失败Agent 一直重试或乱答工具方法异常、参数描述不准确检查工具描述和异常处理效果上线后变差同一提示词效果突然下降模型版本或行为发生变化建立评估集小流量验证准备回滚本地能跑生产不能并发高时延迟飙升推理资源不足、没有压测做容量规划和压测必要时换商业 API7.2 上线前检查清单已确认模型来源、版本和调用方式密钥通过安全方式注入。提示词已模板化并经过评审。知识库数据已清洗检索返回内容的时效性和相关性有保障。输出校验已加结构化结果有兜底逻辑。日志已记录模型输入输出脱敏后、token 和耗时。缓存、限流、配额已配置。模型升级或提示词变更具备回滚方案。已压测预期并发延迟和成本在可接受范围。7.3 下一步扩展方向沿着这套工程骨架可以继续深入的方向RAG 精细化混合检索、重排序、段落切分策略。Agent 进阶多轮规划、任务队列、人工介入审批。评估体系建立离线评测集和在线质量监控。统一模型网关多模型路由、降级、成本分摊。Java 生态扩展关注 Spring AI 版本更新以及社区的工具调用和 Agent 编排方案。AI 应用开发的竞争最后会落到工程能力上。对普通开发者来说最有价值的做法不是盯着哪些大厂给多少钱而是把一个 AI 应用从 demo 一步步推到可观测、可回滚、可评估的生产状态。这个过程积累的提示词管理、上下文治理、幻觉排查和成本控制能力无论未来模型怎么换代都依然有效。 AI应用工程化实践：Agent编排、模型部署与幻觉排查
在 AI 人才市场的讨论里年薪千万不如估值百亿AI 大神看不上大厂这类说法经常出现。它背后的真实信号不是薪酬本身而是 AI 行业的竞争焦点变了大家关注的已经不单是哪个模型参数更大而是谁能把模型能力变成稳定、可评估、可交付的软件产品。对开发者来说这意味着 AI 大模型应用开发的核心能力正从会调 API转向工程化落地。这篇文章不讨论薪酬和公司选择而是拆解 AI 应用开发中最容易被低估、却最能拉开差距的工程环节AI Agent 的任务编排、Spring AI 在 Java 生态里的集成方式、模型部署的选型、AI 幻觉的排查以及提示词、上下文和成本三个隐藏抓手。适合已经写过接口、对 Spring Boot 有一定了解的开发者。读完以后你会得到一张从概念到代码、从验证到排查的 AI 应用工程实践地图而不是一堆散落的 API 示例。1. 先想清楚AI 应用竞争的是工程能力不是模型参数1.1 为什么同样的模型有人做出 demo有人做出产品很多团队拿到的大模型是一样的甚至用的是同一个 API。差距往往出现在模型之外。观察实际落地项目时最常看到的五个问题提示词是写死在业务代码里还是按模板和场景统一管理用户输入千奇百怪时程序能不能保证输出结构稳定模型答错时有没有校验、兜底和人工确认一次请求消耗多少 token、响应有多慢、并发上来会不会打爆成本线上出问题时日志和链路能不能支撑快速定位这五个问题没有一个是模型本身能回答的全部是工程问题。大模型 API 提供的是强大的生成能力但它只是一个能力引擎。要让引擎在真实业务里稳定工作还需要一层完整的工程骨架接口层把用户输入变成规范请求提示词层控制模型行为边界检索层补充最新知识校验层拦截错误输出缓存和限流保护成本与稳定性监控层记录每一次调用的质量。缺少任何一层应用停留在 demo 阶段非常正常。所以判断一个 AI 应用是否能上线不能只看模型答得准不准还要看模型答错时系统会怎样。工程化的核心就是在模型能力之外补上可控性和确定性。1.2 AI 大神看不上大厂背后的技术信号用AI 大神来概括技术能力优秀的人不一定准确但这类讨论里有一个值得注意的信号能持续做出好 AI 产品的人往往更愿意待在自己能定义技术方向、能快速尝试新方案的环境里而不是固化在成熟流程中维护一套稳定旧系统。这不是价值观对错问题而是技术成长路径的选择问题。对普通开发者来说与其羡慕别人的薪酬或估值不如把注意力放在可迁移的能力上。目前市面上大量岗位需要的不是发明新模型的人而是能把现有模型接进业务系统的人。具体来说就是做好这些事情把开源模型或商业 API 接入业务系统设计 Agent 的任务流程治理 AI 幻觉优化请求成本建立评估和回归机制。这些能力不依赖某一家公司也不绑定某一个模型换一个场景仍然成立。后面几节就围绕这条主线展开不追逐模型前沿而是把模型当成一个组件把工程做扎实。2. AI Agent、Spring AI、模型部署三个概念要放在一起理解2.1 AI Agent让模型从回答问题变成完成任务AI Agent智能体是目前 AI 应用开发里最热的方向之一。通俗地说它不是让模型说一段话而是让模型根据一个目标自己拆解步骤、调用工具、检查结果最后完成任务。一个典型 Agent 至少包含四部分规划拆解任务决定下一步做什么。记忆短期记忆保存当前任务上下文长期记忆来自外部存储或知识库。工具调用模型通过函数调用访问外部系统比如查数据库、调接口、发消息。执行与反馈执行动作后把结果再交给模型判断循环直到结束。工程难度在于Agent 的自由度越大越不可控。所以真实项目里不会让 Agent 无限循环而是会设置最大轮数、工具白名单、输出格式约束和人工确认节点。Spring AI 在 Java 生态里提供的工具主要就是解决这类工程化诉求而不是让模型随便跑。2.2 Spring AIJava 生态接入大模型的一层抽象Spring AI 是一个面向 AI 应用的 Spring 生态项目。它的目标是提供统一抽象层让开发者用类似 Spring Boot 的方式接入大模型而不是为每家模型厂商写一套不同的调用代码。它解决的问题有几类ChatClient统一聊天接口支持 system、user 提示词管理和结构化输出。EmbeddingModel统一向量化接口方便接入不同向量模型。VectorStore统一向量存储抽象对接内存、Redis、PGVector、Milvus。Tool 调用通过注解把 Spring Bean 暴露成可被模型调用的工具。Advisors类似过滤器用来做上下文整理、日志记录、内容改写。实际项目里Spring AI 的价值不是让模型能力变强而是降低集成成本让团队用熟悉的 Spring 风格开发 AI 功能。需要注意Spring AI 版本迭代较快不同版本 API 会有差异落地前要以官方文档和依赖版本为准不要照抄旧版本博客。2.3 模型部署自建、API 与私有化的取舍模型部署是 AI 应用落地里很容易被低估的一环。很多团队在测试环境用 API 调得很顺到了生产环境才发现延迟、成本、合规和可用性全都不一样。三种常见方式的对比部署方式优点主要代价适合场景商业 API接入快、免运维单次调用成本、数据出域、限流快速验证、数据敏感度不高的场景自建推理服务可控成本、数据内部闭环GPU 资源、运维复杂、版本更新高频调用、数据隐私要求高私有化一体机或混合部署满足合规、离线可用前期投入大、模型更新慢政企、内网、强合规场景自建推理路线里常见做法是先用量化模型在开发机验证效果再通过推理框架暴露成兼容接口业务侧无需改代码。以本地方便验证为例可以用 Ollama 这类工具快速启动一个模型# 本地开发验证先确认 Ollama 已安装 ollama pull qwen2.5:7b ollama run qwen2.5:7b业务侧配置改成指向本地地址即可spring: ai: openai: base-url: http://localhost:11434/v1 api-key: ${LOCAL_AI_KEY}这里要特别强调不要把本地能跑通等同于生产可以用。推理服务的吞吐、并发上限、GPU 显存占用和冷启动时间都需要单独做压测和容量规划。3. 搭建一个最小可运行的 AI 应用工程骨架3.1 技术选型用最小闭环验证全链路为了演示从模型调用到工程化的完整链路这里使用一个最小闭环Spring Boot 提供接口层Spring AI 封装模型调用内存向量存储模拟知识库最后用结构化输出保证返回结果可控。这个骨架把提示词、检索、输出校验、工具调用串在一起适合作为学习模板。示例工程假设技术栈Java 17、Spring Boot 3.x、Spring AI。模型来源兼容接口开发环境可以是商业 API也可以是本地推理服务。知识库内存向量存储重启后数据清空生产环境要换成 Redis、PGVector 或 Milvus。3.2 项目结构与依赖配置先看最小目录结构ai-demo ├── pom.xml └── src/main/java/com/example/ai ├── AiDemoApplication.java ├── controller/AiController.java ├── service/AiChatService.java ├── service/RagService.java ├── config/VectorStoreConfig.java └── tool/DeviceTools.javapom.xml 中引入 Spring AI 相关依赖。版本不写死以 Maven 中央仓库当前稳定版为准避免教程里的版本和实际环境不一致。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-vector-store/artifactId /dependencyapplication.yml 里配置模型地址、密钥和基础参数spring: application: name: ai-demo ai: openai: base-url: ${AI_BASE_URL:http://localhost:11434/v1} api-key: ${AI_API_KEY:demo-key} chat: options: model: ${AI_MODEL:qwen2.5:7b} temperature: 0.2 client: max-output-tokens: 800密钥不要写死在配置里使用环境变量注入。temperature 调低可以降低输出随机性适合知识问答和结构化输出场景。如果 base-url 指向本地推理服务api-key 填一个占位值也可以但生产环境必须走密钥管理。3.3 核心代码ChatClient、结构化输出与工具调用先定义一个最基础的对话服务Service public class AiChatService { private final ChatClient chatClient; public AiChatService(ChatClient.Builder builder) { this.chatClient builder.build(); } public String ask(String question) { return chatClient.prompt() .system(你是一名资深软件工程师回答要简洁、准确、结构清晰。) .user(question) .call() .content(); } }很多场景不希望模型返回松散文本而是希望返回一个可解析的 JSON 对象。可以用 record 定义返回结构public record Solution(String title, ListString steps, double confidence) { }public Solution plan(String problem) { return chatClient.prompt() .system(给出一个可执行的解决方案并评估置信度。) .user(problem) .entities(Solution.class) .call() .entity(); }这样解析结果就有了类型安全业务层可以进一步校验和兜底。如果模型连续输出不符合结构要检查提示词是否足够明确以及当前模型对结构化输出的支持情况。工具调用是 Agent 的基础能力。通过注解把业务方法暴露给模型Component public class DeviceTools { Tool(description 查询指定设备最近一次在线状态) public String lastOnline(String deviceId) { // 真实项目里这里会查询设备表 return deviceId 最近在线时间2025-01-01 12:00:00; } }创建 ChatClient 时把工具注册进去this.chatClient ChatClient.builder(chatModel) .defaultTools(new DeviceTools()) .build();模型在回答设备问题时可以自行决定是否调用这个工具。工程上建议在 user 提示词里明确先调用工具查询再基于结果回答降低模型瞎猜的概率。3.4 启动验证输入、输出与异常分支在 Controller 暴露 HTTP 接口RestController public class AiController { private final AiChatService chatService; private final RagService ragService; public AiController(AiChatService chatService, RagService ragService) { this.chatService chatService; this.ragService ragService; } GetMapping(/chat) public String chat(RequestParam String question) { return chatService.ask(question); } GetMapping(/rag) public String rag(RequestParam String question) { return ragService.answer(question); } }启动后用 curl 验证curl http://localhost:8080/chat?question什么是缓存穿透curl http://localhost:8080/rag?question数据库连接池的默认连接数是多少正常结果应该是一段结构清晰的回答。异常时常见现象包括服务启动失败密钥或 base-url 配置错误、请求超时模型服务不可用、返回内容为空模型输出被拦截或内容策略限制、返回结构不对结构化输出解析失败。这些现象在排错章节再展开。注意不要只验证程序能启动还要验证输入、输出、异常分支和日志是否符合预期。AI 应用最容易出问题的地方往往发生在模型返回之后。4. AI 幻觉不是模型的锅是工程链路要补的课4.1 幻觉的类型事实性幻觉、逻辑幻觉、指令幻觉AI 幻觉是指模型生成的内容与现实不符、逻辑矛盾或不符合指令要求。常见类型如下类型表现示例事实性幻觉编造不存在的事实虚构某公司发布的版本号或日期逻辑幻觉推理链条站不住前一步说禁用了缓存后一步又说缓存生效指令幻觉不遵守用户明确约束明确要求只输出 JSON结果带了 Markdown 代码块幻觉无法彻底消除但工程上能显著降低。核心思路是不让模型自由发挥它不知道的部分同时给足可溯源的上下文。4.2 缓解幻觉的工程手段第一条是减少回答依赖模型内部记忆。把知识库和当前业务数据通过检索增强RAG放到提示词里让模型优先基于给定上下文作答。RAGService 的最小实现Service public class RagService { private final ChatClient chatClient; private final VectorStore vectorStore; public RagService(ChatClient.Builder builder, VectorStore vectorStore) { this.chatClient builder.build(); this.vectorStore vectorStore; } public String answer(String question) { ListDocument docs vectorStore.similaritySearch( SearchRequest.builder().query(question).topK(3).build()); String context docs.stream() .map(Document::getContent) .collect(Collectors.joining(\n)); return chatClient.prompt() .system(只基于参考资料回答。资料中没有的信息直接说明不知道不要编造。) .user(参考资料\n context \n\n问题 question) .call() .content(); } }这段代码的关键有两点一是给模型的上下文必须来自可溯源资料二是 system 提示词明确限制不知道就直说降低编造概率。第二条是调低温度参数。知识问答、结构化抽取场景建议用 0 到 0.3别用高温度。高温度适合创意写作不适合事实回答。第三条是输出校验与兜底。对结构化输出校验关键字段是否缺失、数值是否合理不合法就重试或走默认值。对涉及操作类的 Agent 任务最后一步增加人工确认或风险校验。幻觉无法彻底消除工程目标是把发生概率降到可控范围并让模型在信息不足时明确告知用户我不确定。4.3 幻觉排查路径排查幻觉问题按这个顺序看输入是否完整。用户问题本身是否模糊缺少关键约束。上下文是否准确。RAG 检索到的文档是否相关、是否太旧、是否混入噪声。提示词是否明确。是否给了模型编造的空间是否缺少不知道就直说的约束。温度是否合适。事实问答是不是用了过高温度。输出校验是否存在。结构化和数值结果有没有校验层。实际项目里幻觉治理不是一次性工作而是要持续积累错误案例集。把用户反馈和评估中发现的问题保存下来作为提示词优化和检索优化的回归数据。5. 提示词、上下文与成本三个隐藏工程抓手5.1 提示词模板化而不是散落在代码里提示词是 AI 应用最重要的业务配置但很多时候会被写散在代码里。推荐做法是放到 resources 下按场景管理src/main/resources/prompts/ ├── chat-system.txt ├── rag-system.txt └── extract-system.txtSpring 里用 Resource 加载提示词模板Value(classpath:/prompts/rag-system.txt) private Resource ragSystemPrompt;模板文件里写清楚角色、任务、约束和输出格式。测试时只改文件不用重新编译业务代码。提示词改动要进入版本管理和代码一起评审、回归。5.2 上下文窗口是资源要按预算分配大模型的上下文窗口不是无限内存。超出窗口长度会发生截断、遗忘或成本暴增所以要把上下文当成资源来管理。三种常见做法截断保留最近 N 轮对话丢弃更早的内容。压缩对历史消息做摘要把长对话压缩成要点。检索只在需要时拉取相关知识片段而不是每次塞入全量知识库。Spring AI 的 Advisor 机制可以做这类处理也可以自己写在调用前的准备函数里。建议所有涉及上下文的逻辑都集中在统一位置方便后续调优和排查。5.3 成本治理从请求结构开始token 成本取决于输入和输出长度。要控制成本先控制请求结构系统提示词保持精简删除不生效的冗余说明。知识检索只传 topK 之后的片段不要传整篇文档。输出限制 tokens避免模型生成超长无用内容。对相同或相似请求加缓存减少重复调用。设置单用户、单接口的限流和配额防止异常调用打爆账单。一个简单缓存思路对问题和检索命中文档的组合做哈希如果近段时间有相同结果直接返回。要注意缓存后的数据时效问题业务数据更新频繁的场景要设置合理的过期时间。6. 从演示到生产还要补齐部署、监控与回滚6.1 配置外置与密钥管理演示项目里配置写在 application.yml生产环境不能这么干。至少要做到模型密钥、数据库密码、存储地址全部使用环境变量或配置中心。不同环境用独立配置禁止把测试环境密钥带到生产。涉及敏感信息的配置进入代码仓库前要做脱敏检查。如果用的是商业 API建议在网关或代理层统一管理密钥不让业务服务直接持有厂商密钥。6.2 日志、追踪与可观测性AI 应用的可观测性比普通应用更强调模型输入输出记录。排错时不能只看 HTTP 状态码还要知道模型收到了什么提示词、返回了什么内容、用了多少 token、耗时多久。生产建议记录以下信息记录项用途用户输入原文判断问题是否模糊最终提示词脱敏后复现模型行为模型输出评估输出质量token 数成本核算延迟和重试次数性能优化工具调用结果排查 Agent 决策链路注意脱敏防止用户隐私和业务敏感数据进入日志。6.3 缓存、限流与回滚策略生产环境需要三件事缓存、限流、回滚。缓存降低重复请求的成本和延迟限流保护模型服务和后端资源回滚在模型升级、提示词调整效果不符合预期时能迅速恢复。模型版本本身也要纳入发布流程。模型厂商更新模型、本地推理服务升级权重都可能改变输出行为。上线前先小流量验证再逐步放量。一旦发现问题要能快速切回上一个可用版本。上线前请自己问一遍模型调用失败时用户看到的是什么有没有兜底提示如果答案是空白页说明工程链路还没走完。7. AI 应用开发的常见坑与排查清单7.1 高频踩坑点速查坑点现象原因解决密钥配置错了启动报 401 或认证失败环境变量没生效、写错密钥检查配置来源使用配置中心或环境变量注入base-url 指向错误连接超时、404地址多空格、路径不支持确认服务地址和版本路径温度过高同一问题多次回答不一致温度参数不适合事实问答降到 0 到 0.3配合结构约束上下文过长请求报错或输出截断超过上下文窗口加截断、压缩或检索结构化输出不稳定JSON 解析失败模型指令不明确或模型能力不足明确输出格式用结构化解析并校验工具调用失败Agent 一直重试或乱答工具方法异常、参数描述不准确检查工具描述和异常处理效果上线后变差同一提示词效果突然下降模型版本或行为发生变化建立评估集小流量验证准备回滚本地能跑生产不能并发高时延迟飙升推理资源不足、没有压测做容量规划和压测必要时换商业 API7.2 上线前检查清单已确认模型来源、版本和调用方式密钥通过安全方式注入。提示词已模板化并经过评审。知识库数据已清洗检索返回内容的时效性和相关性有保障。输出校验已加结构化结果有兜底逻辑。日志已记录模型输入输出脱敏后、token 和耗时。缓存、限流、配额已配置。模型升级或提示词变更具备回滚方案。已压测预期并发延迟和成本在可接受范围。7.3 下一步扩展方向沿着这套工程骨架可以继续深入的方向RAG 精细化混合检索、重排序、段落切分策略。Agent 进阶多轮规划、任务队列、人工介入审批。评估体系建立离线评测集和在线质量监控。统一模型网关多模型路由、降级、成本分摊。Java 生态扩展关注 Spring AI 版本更新以及社区的工具调用和 Agent 编排方案。AI 应用开发的竞争最后会落到工程能力上。对普通开发者来说最有价值的做法不是盯着哪些大厂给多少钱而是把一个 AI 应用从 demo 一步步推到可观测、可回滚、可评估的生产状态。这个过程积累的提示词管理、上下文治理、幻觉排查和成本控制能力无论未来模型怎么换代都依然有效。