去年年底有个做仓储系统的朋友问我，他们公司想上智能体开发，手里是一个两个 Java 后端加一个写 Python 算法的配置，问我这个组合够不够。我说够，但前提是这几个人得能互相看懂对方的代码——这句话后来成了我做这门 AI 应用与智能体开发线下课的起因。你如果最近在招聘网站上翻过一轮，会发现"AI 应用开发工程师"这个岗位描述已经变了，不再是"熟悉 Transformer 原理"这种学术派要求，而是"能把模型接进现有业务系统、能搭出跑得起来的智能体、能处理数据闭环"。翻译成人话就是：企业要的不是研究员，是把 AI 落地到业务里的那个人。
这也是我为什么坚持把 Java 和 Python 放在同一门线下课里讲。市面上单讲 Python 调模型的课太多了，听完你确实能让一段代码输出文字，但回到公司你会发现，你的业务系统是 Spring Boot 写的，鉴权、事务、限流、日志全在 Java 那边，模型跑在 Python 里怎么跟它对上话？反过来，只讲 Java 的课也不少，可你连 Prompt 怎么改、向量检索的召回率为什么低都插不上手，最后只能当个传话的。两条腿都得有，才能在项目里站住。
这门课定在 2026 年 6 月开班，选的是一整段时间的集中线下形式，不是那种晚上八点开直播、你一边吃饭一边听的回放课。原因很直接：智能体开发的坑，八成以上出在环境和依赖上，这种东西录播讲一百遍都不如你坐在教室里，旁边有人帮你把报错信息看一眼。下面我把这门课的设计思路、技术要点、实操环节和踩过的坑，从头到尾拆一遍，你对着看就知道自己该不该来，以及来之前要准备到什么程度。
1. 为什么 AI 应用开发要把 Java 和 Python 绑在一起学
1.1 两个语言在真实项目里的分工边界
先把这个分工说清楚，因为它决定了你学的时候该往哪个方向使劲。Python 的位置在"模型侧"：调用模型接口、写 Prompt 模板、做文本切分和向量化、跑数据处理脚本、做效果评测。这部分工作变化快、试错多、不需要太强的工程约束，Python 的生态和写法天然适合快速迭代。Java 的位置在"服务侧"：对外暴露接口、做身份校验和权限控制、管理数据库事务、做并发调度、接入公司现有的监控和日志体系。这部分工作要求的是稳、可观测、能扛量。
我见过太多项目把这两块混着做，结果就是 Python 脚本被直接当成线上服务跑，没有连接池、没有超时控制、没有重试策略，模型服务抖一下，整个业务流程就卡死。反过来也有团队为了"统一技术栈"，硬用 Java 去写所有数据清洗逻辑，一个原本三十行 Python 能搞定的文本处理，写了一百多行还不好维护。边界清楚，各干各的活，中间用 HTTP 或者消息队列对接，这是最省心的做法。
你在课上学到的第一个判断能力，就是拿到一个需求先问自己：这一步该放哪边。比如"用户上传合同，系统抽取关键条款并给出风险提示"，抽取和提示词构造放 Python，文件上传、权限校验、结果落库、给前端返回放 Java。分清楚了，后面所有代码都好写。
1.2 只会一门语言的人，会在哪个环节卡住
我把这几年的观察整理成一张表，你可以对号入座，看看自己现在卡在哪一档。
| 你的现状 | 通常能独立完成的部分 | 最容易卡住的地方 |
|---|---|---|
| 只会 Python，做过数据分析 | 调模型、写 Prompt、跑向量检索 demo | 接口并发一上来就崩，不知道怎么和现有业务系统对接，不懂事务和幂等 |
| 只会 Java，后端经验三五年 | 写接口、做鉴权、管数据库、扛并发 | 改不了 Prompt，读不懂检索逻辑，模型输出格式一变就束手无策 |
| 两门都会一点，但都没做过 AI 项目 | 能看懂两边代码 | 不知道一个完整智能体该怎么分层，出了问题定位不到是哪一层 |
| 做过 AI demo，没上过生产 | 能跑通单条链路 | 不知道怎么做评测、怎么控制成本和延迟、怎么处理失败重试 |
这张表里第三档的人其实是最好教的，因为他已经有全局视野，缺的是项目结构和排查经验，线下课集中几天就能补上。第一档和第二档的差距通常在三到五天的密集训练内能大幅缩小，前提是课程里必须有两边对照着写的实操环节，而不是上午讲 Java、下午讲 Python、两边老死不相往来。
1.3 线下集中形式对这门技术组合的特别价值
线上课最大的问题是"环境黑箱"。你本地 Python 是 3.9，课程演示用的是 3.11，某个库的 API 签名变了，你照着敲就是报错，然后在评论区等回复，一来一回半天过去了，学习节奏全断。Java 那边更麻烦，JDK 版本、Maven 依赖冲突、Spring Boot 版本和某个 SDK 不兼容，这些东西没有统一答案，得看你的报错信息现场判断。
线下课把这个问题压缩到几分钟。我在教室里最常做的事就是走到学员旁边看一眼终端，说一句"你这个是依赖版本锁死了，把这段注释掉换另一个坐标试试"。这种交互效率是任何录播都替代不了的。另外还有个隐性收益：智能体开发目前没有标准答案，同一个需求有五六种实现路径，同学之间互相看代码、互相质疑方案，这种碰撞在线上几乎不会发生。你一个人对着屏幕琢磨三天，可能都不如同桌一句"你为什么不把这块抽成一个工具函数"来得有用。
2. 智能体开发到底在开发什么
2.1 从"调一次模型"到"搭一个智能体"的跨越
很多人对智能体的理解停留在"能对话的机器人"，这个理解会让你在项目里走偏。一次普通的模型调用是这样的：你给它一段输入，它给你一段输出，结束。智能体不一样，它是一个带循环的结构：模型先想一步，决定要不要用工具，用了工具拿到结果，再想一步，可能还要再用一次工具，直到它认为任务完成，才给出最终答复。
这个"循环"两个字是整个智能体开发的全部难点。循环意味着你要控制轮数上限，否则模型可能一直绕圈子；意味着你要处理中间状态的传递，每一步的输出要能喂给下一步；意味着你要做异常处理，某一次工具调用失败了，是重试、跳过还是终止；意味着你要记录每一步的轨迹，不然出了问题你根本不知道它在哪一步跑偏了。
我在课上会用一个很土的比喻：普通模型调用是"你问一句它答一句"，智能体是"你给它一个任务，它自己列清单、自己跑腿、自己核对，最后回来汇报"。你要写的代码，就是那个管着它的项目经理——定规则、控预算、看进度、兜底。理解了这个角色定位，后面所有技术点都不会散。
2.2 一个智能体的四个核心部件
不管用什么框架，一个能用的智能体基本都跑不出这四个部件，我在课上会把它们一个一个拆开讲，也会让你自己动手实现最简版本，而不是直接调框架的封装。
第一是规划。模型怎么把一个大任务拆成小步骤。最简单的方式是在系统提示里写清楚"你需要按步骤思考并输出下一步动作"，复杂一点的会做任务分解和依赖排序。这一步的关键不是写得花哨，而是输出格式必须机器可解析，通常是结构化文本或 JSON，你要在代码里做严格的格式校验，解析失败就要触发重试。
第二是记忆。短期记忆就是当前对话的上下文，长期记忆是跨会话的知识，一般存在向量库里。这里最常见的误区是把所有历史记录都塞进上下文，结果 token 消耗爆炸、响应变慢、模型还被无关信息干扰。正确做法是做窗口管理和摘要压缩，把久远的对话压成一段摘要，只保留最近几轮原文。
第三是工具。智能体能干的事，全靠工具撑着。查数据库、调内部接口、算数、发消息，每一个能力都要写成清晰的工具描述，告诉模型这个工具是干什么的、要传什么参数、返回什么格式。工具描述写得含糊，模型就会乱调或者不调，这是新手最容易忽视的地方。
第四是执行循环。也就是前面说的那个项目经理逻辑，控制整个流程的推进、失败处理和终止条件。
2.3 结合自建业务模型的智能体怎么搭
有一类需求特别常见：企业自己有一批业务数据或者自己部署了一个小模型，想在上面搭智能体。这种场景和纯调外部模型不一样，有几个地方要特别注意。
数据权限是第一道坎。自建业务模型通常只能看到内部数据，但智能体在规划的时候可能会想调用外部工具，这时候你要在工具层做白名单控制，哪些工具在这个场景下允许调用，必须写死，不能让模型自由发挥。第二道坎是内网环境，很多企业的模型服务部署在内网，外网访问不了，你的开发环境、调试环境、生产环境网络策略都不一样，这套东西在现场调试的时候最容易出问题，也是线下课能帮你省时间的部分。
第三道坎是效果兜底。自建模型的能力通常弱于通用大模型，规划能力不足，容易在循环里绕圈。我的经验是把复杂任务拆得更细，用多个小智能体串起来，每个只负责一件小事，而不是让一个智能体包打天下。这种"小步快跑"的架构，在自建模型上比单体智能体靠谱得多。
3. Java 侧：把 AI 能力接进企业系统的关键工程点
3.1 用 Spring Boot 搭一个智能体服务网关
Java 这边最核心的角色是网关。所有来自前端的请求先进 Java 服务，由它做鉴权、限流、参数校验、会话管理，再把真正需要模型处理的部分转发给后端。这样做的好处是，模型相关的逻辑可以独立演进，前端和业务系统不用跟着改。
下面是我在课上会带着写的一段最小网关代码，用的是 Spring 的流式返回，因为智能体的输出通常是逐字吐出来的，用普通接口会让用户干等十几秒。
@RestController @RequestMapping("/agent") public class AgentGatewayController { @Resource private AgentOrchestrator orchestrator; @PostMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter chat(@RequestBody ChatRequest request) { // 60 秒超时，超时后前端会收到中断信号 SseEmitter emitter = new SseEmitter(60_000L); // 会话 id 由前端传入，没有则新建，用于串联多轮上下文 String sessionId = StringUtils.hasText(request.getSessionId()) ? request.getSessionId() : UUID.randomUUID().toString(); orchestrator.runAsync(sessionId, request.getQuery(), emitter); return emitter; } }这段代码看着简单，但每一个细节都有讲究。超时时间设 60 秒是因为智能体可能要走好几轮工具调用，设太短会误杀正常请求；会话 id 由前端传入而不是后端生成，是为了支持刷新页面后继续对话；用异步执行而不是同步返回，是因为流式输出必须在独立线程里推送，同步会阻塞容器线程。
注意：SseEmitter 的超时时间和容器本身的连接超时是两回事，两个都要配。我见过太多次学员只改了代码里的超时，结果请求还是被前面的负载均衡掐断，排查了半天。
3.2 并发调度与线程等待的正确姿势
智能体经常需要并行做几件事，比如同时查三个数据源，等结果都回来再一起喂给模型。Java 里做这件事的坑特别多，最常见的错误是用了CompletableFuture但没传自定义线程池，全部挤在默认的 ForkJoinPool 里，量一上来就互相拖死。
// 专门给模型调用准备的线程池，核心数按实际并发量给，别用默认的 private final ExecutorService modelExecutor = new ThreadPoolExecutor( 8, 32, 60L, TimeUnit.SECONDS, new LinkedBlockingQueue<>(200), new ThreadFactoryBuilder().setNameFormat("agent-pool-%d").build(), new ThreadPoolExecutor.CallerRunsPolicy()); public List<String> queryInParallel(List<String> queries) { List<CompletableFuture<String>> futures = queries.stream() .map(q -> CompletableFuture.supplyAsync(() -> callTool(q), modelExecutor) .exceptionally(e -> "")) // 单个失败不影响整体 .collect(Collectors.toList()); // allOf 只保证全部完成，不保证成功，所以前面做了 exceptionally 兜底 CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join(); return futures.stream() .map(CompletableFuture::join) .filter(StringUtils::hasText) .collect(Collectors.toList()); }这段代码里有两个经验点值得单独说。一是线程池的拒绝策略选了CallerRunsPolicy，意思是队列满了就让调用线程自己跑，这样虽然会变慢，但不会丢任务，对智能体这种"宁可慢也不能少"的场景更合适。二是每个 future 都挂了exceptionally，因为allOf在某个任务抛异常时会直接失败，导致你拿不到其他已经成功的结果。工具调用本来就容易失败，一个超时不该让整个回答作废。
3.3 向量库和业务数据的对接方式
Java 这边接向量库，主要工作不是算法，是数据同步。业务数据在 MySQL 里，向量在向量库里，两边怎么保持一致，这是工程问题。我的做法通常是：业务写操作走消息队列，异步触发向量更新；读操作直接查向量库拿 id，再回表查详情。中间要处理的是删除和更新，很多人只做了新增，结果旧数据一直在，检索出来全是过期信息。
还有一种情况是热数据不进向量库，直接在 Java 层做关键词检索，冷数据才走向量召回。这样做的好处是响应快、成本低。判断标准很简单：如果一个查询在业务表里用索引能秒出结果，就别绕向量那一圈。向量检索解决的是语义相似问题，不是替代数据库查询。
4. Python 侧：模型调用、数据处理与工具链
4.1 环境搭建的三种方案和选择依据
Python 环境这块，我在课上会给出三种方案，让学员根据自己的机器和习惯选。
第一种是虚拟环境加 pip，最轻量，适合单人开发和课程练习。python -m venv .venv然后激活，所有依赖装在这个目录里，和系统 Python 隔离。缺点是依赖多了之后解析慢，跨平台复现要靠 requirements.txt。
第二种是 conda，适合需要管理不同 Python 版本、或者要装一些带二进制依赖的科学计算库的场景。体积大，但对新手友好，装不上的包通常换 conda 源就能解决。
第三种是容器，适合团队协作和最终部署。开发阶段用前两种，交付阶段一定要用容器，不然你本地能跑、同事机器上跑不起来这种事会反复发生。
依赖管理有个硬性建议：所有版本号全部锁死，不要用>=这种写法。模型相关的 SDK 更新频繁，小版本之间 API 都可能变，你今天写的代码下周重新装依赖就可能报错。锁定版本，写清楚注释，这是给自己省时间。
4.2 模型调用的封装与流式输出
调模型这件事本身不难，难的是封装。直接在每个业务函数里写 HTTP 请求，代码会迅速失控。我会在课上带大家写一个统一的调用层，把所有模型交互收口到一处，方便加日志、加重试、加超时、换供应商。
import requests import time from typing import Iterator def call_model(prompt: str, system: str = "你是业务助手", retries: int = 2) -> str: payload = { "model": MODEL_NAME, "messages": [ {"role": "system", "content": system}, {"role": "user", "content": prompt}, ], "stream": False, } for attempt in range(retries + 1): try: resp = requests.post( MODEL_ENDPOINT, headers={"Authorization": f"Bearer {API_KEY}"}, json=payload, timeout=(5, 60), # 连接 5 秒，读取 60 秒 ) resp.raise_for_status() return resp.json()["choices"][0]["message"]["content"] except requests.Timeout: if attempt == retries: raise time.sleep(1.5 * (attempt + 1)) # 退避重试，别原地猛冲这里我把连接超时和读取超时分开设了，这是个非常实用的细节。连接超时短，说明网络不通就快速失败；读取超时长，因为模型生成文字本来就慢。很多人只设一个总超时，要么短了误杀，要么长了卡死。
流式输出稍微复杂一点，核心是把响应按行读、按事件边界切、逐块推给前端。课上我会让大家自己实现一遍，因为你只有亲手处理过被截断的半个 JSON，才会明白为什么要在缓冲层做拼接。
4.3 数据采集与清洗这一环为什么绕不开
AI 应用的效果，七成取决于数据质量，这个比例我一点都不夸张。你 Prompt 写得再漂亮，检索出来的资料是乱的、重复的、过期的，输出就是垃圾。数据这块在课上会花不少时间，重点讲三件事：怎么从业务系统里把原始数据取出来、怎么切分成适合检索的片段、怎么去重和打标签。
切分这个环节最容易出问题。按固定字数切会把一句话切断，按段落切遇到超长段落又没法处理。我通常讲的是混合策略：先按语义边界切，超过上限再按标点切，仍然超长才硬切。切完之后每一段都要带上来源、时间、类型这些元数据，因为检索出来之后往往还要按这些字段过滤。
还有一个常被忽略的点是数据更新。知识库不是建一次就完事，业务数据每天都在变，你得设计一套增量更新机制，否则一个月后检索出来的全是老黄历。这套东西线上听一遍记不住，必须现场跟着做一遍。
5. 课程实操环节的三个项目拆解
5.1 项目一：工具调用型智能体
第一个项目我设计得很简单，就是让智能体能查数据、能算数、能按结果给建议。目标是让所有人先把最小闭环跑通：定义工具、让模型选择工具、执行工具、把结果回填、生成最终回答。这个循环写通了，智能体就算入门了。
难点在于工具描述的设计。我会让学员先自己写一版，然后互相对照着改。你会发现同样一个查询工具，"查询订单"和"根据订单号查询订单的当前状态和金额，参数必须是完整订单号"这两种描述，模型的调用准确率差一大截。这种手感只能靠反复试，讲不出来。
Java 这边在这个项目里负责工具的实际执行和结果校验。Python 侧发出的工具调用请求，Java 收到之后要校验参数合法性、查库、格式化返回。两边的接口约定要提前定好，字段名、类型、错误码都不能含糊，不然调起来就是一堆格式错。
5.2 项目二：带知识库检索的智能体
第二个项目是 RAG 的完整链路。从原始文档进去，经过切分、向量化、入库，到查询时召回、重排、拼进 Prompt、生成回答。这条链路每个环节都能调，也每个环节都能出错，我会带大家一个个参数试过去。
召回数量这个参数特别值得现场调。设 3 条可能漏信息，设 20 条模型又被噪声干扰。我的经验是先设 8 到 10 条做粗排，再用一个小的重排模型筛到 3 到 5 条喂给生成。这个过程在现场做，你能直观看到同一句话在不同召回数量下的输出差异，这种体感是看书得不到的。
还有一个必讲的点是"拒答"。检索不到相关内容时，智能体必须能说"我没有找到相关信息"，而不是硬编一个答案。这个能力要在 Prompt 和代码两层都要做，Prompt 里明确要求，代码里检查召回分数阈值，低于阈值直接走兜底回复，不调模型。
5.3 项目三：多智能体协作
第三个项目是综合演练，把前面学的东西串起来。设计是一个主智能体负责理解需求并分派任务，下面挂几个专项智能体，分别负责查询、分析、生成报告。主智能体不直接干活，只做调度和汇总。
多智能体最麻烦的地方是状态传递和终止控制。子任务的结果怎么传回主流程、失败了怎么降级、整体轮数怎么限制，这些都要写清楚。我在课上会故意留一个 bug，让主智能体在某个条件下陷入循环，然后带着大家一起看日志、定位问题、加终止条件。这种"制造故障再修复"的环节，是线下课我能做而录播做不了的部分。
6. 常见问题与排查技巧实录
6.1 环境和依赖类问题
这类问题占了实际调试时间的一半以上，我整理了一张速查表，基本能覆盖你在课程期间会遇到的大部分情况。
| 现象 | 大概率原因 | 处理方式 |
|---|---|---|
| 装了库但导入报找不到模块 | 装到了系统 Python，不是当前虚拟环境 | 确认虚拟环境已激活，用python -m pip install而不是裸 pip |
| 两个库互相冲突，装一个另一个坏 | 依赖版本不兼容 | 锁定版本，建新环境，不要试图在旧环境里硬修 |
| Java 编译报找不到符号 | 依赖没下载完或坐标写错 | 清本地仓库重新拉，检查坐标和版本号 |
| 服务启动报端口占用 | 上一个进程没退干净 | 查端口对应进程，杀掉或换端口 |
| 本地跑得通，换机器就报错 | 环境变量没同步 | 把所有配置外置成环境变量或配置文件，写进文档 |
注意：不要在系统 Python 里装项目依赖，这是新手最容易犯的错。一旦把系统环境弄脏，后面所有环境问题都会变得难以定位。
6.2 模型调用类问题
超时和限流是两类高频问题。超时要分清楚是网络层超时还是模型生成慢，前者缩短连接超时，后者要么延长读取超时，要么改成流式返回让用户先看到内容。限流则需要做退避重试，而且必须是带随机抖动的退避，固定间隔重试在并发场景下会形成新的峰值。
输出格式不可解析也很常见。模型返回的 JSON 偶尔会多一个逗号、少一个引号，或者前面带一段解释文字。我的做法是三层防护：Prompt 里明确要求只输出 JSON；解析前先用正则把代码块标记剥掉；解析失败时把错误信息回传给模型让它重写一次。这三层加上，成功率能到很高。
还有一类问题是答案质量忽好忽坏。排查顺序是先看检索结果，再看 Prompt 版本，最后才怀疑模型。绝大多数情况问题出在前面两步，模型本身反而是最稳的一环。
6.3 工程与并发类问题
接口响应慢但 CPU 不高，一般是卡在等待上，要么是模型调用慢，要么是数据库慢，用链路追踪看一眼就能定位。并发上去之后出现数据错乱，基本是共享状态没做隔离，会话相关的数据一定要按会话 id 分开存，不要用类成员变量。
内存缓慢增长最后崩溃，通常是历史记录没清理。智能体的上下文会随着轮数不断变长，如果不做窗口限制，跑一天下来内存就吃满了。我的建议是在会话层就设一个硬上限，超过轮数的历史直接摘要压缩，别等到出问题再补。
最后一个经验：所有涉及模型调用的地方都要有降级方案。模型服务不可用时，至少要让业务流程能给出一个明确的提示，而不是整个页面转圈到超时。这个兜底逻辑花不了多少代码，但能避免很多线上事故。
7. 学习路线与时间安排建议
7.1 前置基础要补到什么程度
课程虽然是零基础可入，但完全不准备会让你的学习效率打折。我给的建议很具体：Java 方面，你要能独立写出一个带数据库操作的 Spring Boot 接口，知道什么是依赖注入、什么是事务、怎么用 Maven。不需要精通并发包，但要知道线程池是干什么的。Python 方面，你要能读写文件、处理字典和列表、写函数、用 requests 发请求。不需要会机器学习，也不要求你懂深度学习框架。
如果这两条你都不满足，建议提前两到三周每天抽两个小时补一下，把基础语法和常见库过一遍。这个投入很小，但能让课堂上的时间真正花在智能体上，而不是花在语法上。我见过一些学员因为基础不牢，前两天全在补课，后面的实操只能看着别人做，很可惜。
7.2 课程期间的节奏安排
密集课程最怕的是"听懂了但没动手"。我的安排是每天上午讲原理和拆代码，下午全部是动手时间，晚上留一到两小时答疑和补做。下午的实操必须自己敲，不许复制粘贴，这个要求看着严，但效果差别很大。你复制一段代码跑通了，脑子里其实什么都没留下；自己敲一遍报三次错，那个知识点就记住了。
每天结束前我会留一个"今日卡点"的环节，每个人说出自己今天最卡的地方，大家一起看。这一步的价值在于，你遇到的问题往往也是别人的问题，说出来之后解决效率高很多，而且你会发现有些坑是通用的，提前知道能省后面很多时间。
7.3 课后怎么把学到的东西延续下去
课程结束才是真正的开始。我建议回去之后立刻做一件事：把课程里的第三个项目，换成你自己业务里的一个真实场景重做一遍。不用做得完整，能跑通链路就行。这个动作能帮你把课堂知识真正迁移到工作场景，也能暴露你在真实数据上会遇到的新问题。
另外，行业里看 AI 应用公司的时候常用市销率也就是 PS 这个口径来估商业价值，这个数字背后反映的其实是应用能不能规模化落地、能不能持续产生收入。对个人来说，这个道理是一样的：你手里的技术只有接到真实业务上，产生可衡量的价值，才算真正掌握。停留在 demo 阶段的能力，市场不会给它定价。
我个人在实际带课过程中的体会是，学员之间的差距往往不在智商，而在有没有把问题问出口。同样一个环境报错，有人自己憋两个小时，有人直接举手三分钟解决。集中线下这段时间，最大的资源就是你周围坐着的人，别浪费。
最后再分享一个小技巧：把你调试智能体过程中的每一次失败都记下来，包括当时的输入、模型的输出、你的判断。攒够二三十条之后回头看，你会发现自己踩的坑高度集中在几个类型上，把这些类型解决了，你的调试效率会有一个明显的台阶。这个记录习惯我从第一次做智能体项目保持到现在，比任何教程都管用。
