00 · 导读：给资深 Java 工程师的 Agent 开发教程
版本 v1.0（2026-09-19） · 面向读者的技术栈：Java / Spring 后端 · 目标技能栈：LLM / RAG / Agent
0.1 这套教程解决什么问题
你是工作多年的 Java 工程师，对并发、分布式、微服务、数据库了如指掌。但"Agent""RAG""LangChain"这些词可能还很模糊：
- 大模型输出为什么不稳定？凭什么值得信任？
- 所谓 Agent 到底是"多了一个 API"还是"一种新架构"？
- RAG 和搜索引擎有什么区别？为什么大家都在做？
- LangChain / LangGraph 这些框架解决了什么问题，值不值得引入工程？
- 如果我用 Java 写生产代码，这些东西怎么落地？
本系列文档的目标是：把你已有的工程能力，迁移到 LLM/Agent 领域。我们不堆概念，每章都讲清楚"原理 → 代码 → 坑与权衡"，并且全部配实际可运行的例子。
0.2 技术选型：为什么主线用 Python，还要讲 Java
| 层 | 本系列主线 | 说明 |
|---|---|---|
| 概念与算法（RAG、Embedding、Agent 循环） | 语言无关，用 Python 演示 | 原理是通用的 |
| Agent 编排框架 | LangChain / LangGraph（Python） | 生态最成熟、资料最多、更新最快 |
| Java 生产落地 | LangChain4j / Spring AI（第 13 章专讲） | 你团队里的真实落地路径 |
理由很简单：你点名要学的 langchain 和 langgraph 本质是 Python 生态，用它们教学最直接；但真实的生产系统大概率跑在 Java 里。所以本系列用 Python 讲透原理（前 12 章），再用一整章（第 13 章）教你如何用 LangChain4j 和 Spring AI 在 Java 里复刻同样的能力。概念在 Python 学会，工程在 Java 落地。
0.3 内容地图
| 章节 | 主题 | 核心收获 |
|---|---|---|
| 01 认识LLM与Agent | 大模型心智模型 | LLM 为什么"会一本正经胡说八道"、Function Calling、Agent 定义 |
| 02 Python环境与第一个Agent | 动手热身 | 搭建环境、跑通第一个 LLM 调用、手写第一个 Agent 循环 |
| 03 Prompt工程与结构化输出 | 与大模型对话的艺术 | 提示词结构、思维链、JSON 结构化输出与校验 |
| 04 RAG核心原理 | RAG 理论 | Embedding、向量检索、分块策略、检索质量指标 |
| 05 RAG从零实战 | 手写 RAG | 不依赖框架，从加载文档到问答的完整实现 |
| 06 RAG进阶与生产实践 | 把 RAG 做扎实 | 混合检索、重排序、查询改写、RAG 评估 |
| 07 LangChain核心概念 | 框架世界观 | LangChain 抽象、LCEL 管道、何时值得用框架 |
| 08 LangChain实战·工具调用 | 框架实战 | 用 LangChain 重写 RAG、定义工具、构建 Agent |
| 09 LangGraph核心概念 | 图式编排 | State、节点、边、条件分支、checkpointer |
| 10 LangGraph实战·智能体编排 | 高级编排 | ReAct、人工介入、多 Agent 协作 |
| 11 Agent工程原理与设计模式 | 套路与反套路 | 记忆、规划、反思、Agent 设计模式选型 |
| 12 生产级工程化 | 上线必读 | 评估、可观测性、安全、成本、稳定性的清单 |
| 13 Java生态落地 | Java 工程师的主场 | LangChain4j + Spring AI 复刻经典案例 |
| 14 综合实战·企业级客服系统 | 端到端 | 一个含 RAG + 工具 + 人工接管的完整系统 |
0.4 三条学习路径
- 速通路径（半天）：00 → 02 → 03 → 05 → 10，再回到 13。先动手跑起来。
- 系统路径（推荐，一周）：按 00-14 顺序通读，每章动手跑代码。
- 工程化路径（给要上生产的人）：系统路径 + 06 + 12 重点精读，再完成 14 的综合实战。
0.5 环境与版本约定
本系列示例统一使用以下版本，避免"代码照着抄跑不通"的版本漂移问题：
- Python 3.10+
langchain==0.3.x、langchain-community==0.3.x、langchain-openai==0.3.xlanggraph==0.4.xchromadb、faiss-cpu（向量库，按章节需要）- 向量模型默认
text-embedding-3-small，可替换为国产bge-m3等
注意：LangChain 已有 1.x、LangGraph 也在持续演进。本系列按 0.3/0.4 稳定版写作，你遇到新版本时以官方文档为准，概念与思路不变。
API Key 统一通过环境变量读取（不硬编码）：
export OPENAI_API_KEY="sk-xxx" # 或你的国产模型 Key
export OPENAI_BASE_URL="https://api.deepseek.com/v1" # 国内可直接替换为兼容端点国内可用的 OpenAI 兼容端点示例：DeepSeek（https://api.deepseek.com/v1）、阿里云百炼 Qwen（https://dashscope.aliyuncs.com/compatible-mode/v1）、智谱 GLM、Kimi/Moonshot 等。本系列所有 ChatOpenAI 示例都支持通过 base_url 指向它们。
0.6 阅读约定
- 代码块带语言标注，可直接复制运行（先
pip install -r requirements.txt）。 - 图示使用 Mermaid 或 ASCII。
- 章节之间用"参见第 X 章"交叉引用。
- 每章结尾有小结、练习、延伸阅读，练习建议动手做。
0.7 常见疑问速答
Q：我不做算法，学这些有用吗？
A：Agent 开发 90% 是工程（数据、编排、评测、稳定），不是算法。这正是资深工程师的主场。
Q：LangChain 大家都在吐槽，还值得学吗？
A：值得——但把它当作"可组合的工具箱"而非"万能框架"来学。第 7 章会讲清楚它的边界。
Q：我直接上 Java 生态不就行了？
A：可以，但建议至少过一遍 Python 的 RAG 原理（04-06），否则你只会调用 API 而不知道检索在干什么。第 13 章起全程 Java。
现在，从第 01 章开始。
0 条评论