第 0 章
全书导读——先看地图，再跑环境
本章基线：LangChain4j
1.22.0+ 实验模块1.22.0-beta32｜ JDK21｜ Maven3.9+｜ 最后验证2026-10-28
本章目标：
- 15 分钟内把两个项目跑起来，或者明确知道哪一章可以先跳过
- 看懂基础篇、进阶篇、实战篇的依赖关系，自己安排阅读顺序
- 认识全系列的写作约定（基线块 / 实测标记 / 坑点表），知道哪些数字可以直接信
- 预先踩掉环境层面的高频坑——JDK 版本、API key 欠费、Redis 缺失，本章一次说清
0.1 这套教程给你什么
教程围绕两个可运行的 Spring Boot 项目展开，所有章节的代码都来自它们：
| 项目 | 端口 | 是什么 | 服务哪些章 |
|---|---|---|---|
smart-doc-assistant |
8090 | 智能文档问答（RAG + Agent，多租户） | Ch1~Ch19、Ch21、Ch22（基础篇把它从零搭起来） |
hiring-ai-assistant |
8091 | 招聘流程自动化（FSM + 6 Agent + 三护栏 + 自迭代） | Ch24/25 |
全书分三段：
- 基础篇（Ch1→9）：每章一个必备能力，从跑通第一个 AI 接口一路讲到多模态
- 进阶篇（Ch10→19）：两条主线。RAG 主线（Ch10→13）解决“怎么让 AI 答得准、并且知道它到底准不准”；Agent 主线（Ch14→19）解决“怎么让 AI 自己干活、并且干得可控”
- 横切实战（Ch21/22、Ch24/25）：Ch21/22 是防护与可观测两块横切能力，Ch24/25 把前面所有能力组装成一个完整业务系统
版本口径全系列统一：LangChain4j 用 1.22.0 正式线 + 1.22.0-beta32 实验线（Guardrails、Skills、MCP Server SDK 在实验线里），JDK 推荐 21。
0.2 环境前置
0.2.1 必装
| 组件 | 版本要求 | 说明 |
|---|---|---|
| JDK | 21（推荐） | 全书在 21.0.10 上验证；低于 21 编译不过（enforcer 拦下限），更高版本一般也能构建 |
| Maven | 3.9+ | 两个项目都是标准单模块结构 |
| LLM API Key | 任选一家 | 放 application-local.yml（已被 .gitignore 忽略） |
enforcer 只拦下限：低于 21 会报 RequireJavaVersion failed，21 及以上都放行。推荐直接用 21，全书在这版上验证过。机器上装了多个 JDK 时，让 JAVA_HOME 指向 21 再跑 Maven（macOS：export JAVA_HOME=$(/usr/libexec/java_home -v 21)）。
0.2.2 按章可选
| 组件 | 哪章需要 | 不装会怎样 |
|---|---|---|
| Node.js ≥ 18 | Ch17、Ch19 | MCP demo 服务器起不来；demo-server.mjs 零 npm 依赖，装 Node 即可 |
| MySQL 8 | Ch24/25（hiring 项目） | hiring 起不来；smart-doc 默认进程内存储，不需要 |
| Redis | Ch24 必需（compose 用 redis:7，普通 Redis 够用）；Ch11 的 Redis 向量库、Ch5/Ch14 的 Redis 记忆要 Redis Stack（RediSearch / RedisJSON 模块） | 普通 Redis 跑向量库和 Redis 记忆会报 unknown command（FT.CREATE / JSON.GET）；换 redis/redis-stack-server 镜像，或 smart-doc 加 --chat.memory.backend=memory 绕开 |
| Claude Desktop | Ch19.9.2（可选验证） | 不装也能用 curl 完成 stdio 模式自测 |
0.2.3 API Key 放哪
两个项目都从 application-local.yml 读真实 key（模板见 application.yml 的 ${XXX:默认值} 占位）。这个文件已被 .gitignore 忽略，clone 下来需要自己创建一个。全系列实测用过两家：
- DeepSeek（
deepseek-v4-flash）：¥1.0/M 输入 + ¥2.0/M 输出，Ch22 有完整成本实测； - DashScope qwen（
qwen3.7-flash）：走 OpenAI 兼容端点。
key 欠费时的报错长这样，见到就该去充值而不是改代码：
Access denied, please make sure your account is in good standing。
0.3 五分钟跑通 smart-doc-assistant
git clone <仓库地址> && cd langchain4j-in-production
# 先创建 smart-doc-assistant/src/main/resources/application-local.yml，填入你的 key
cd smart-doc-assistant
mvn spring-boot:run
# 首次启动会下载本地 ONNX 嵌入模型（All-MiniLM-L6-v2，384 维），并自动入库 classpath:docs/ 下的文档记忆后端默认是 Redis（chat.memory.backend 缺省即 redis）。本机没有 Redis 时加一个参数切到进程内实现：
mvn spring-boot:run \
-Dspring-boot.run.arguments="--chat.memory.backend=memory"验证（端口 8090）：
curl -s -X POST http://localhost:8090/api/chat \
-H "Content-Type: application/json" \
-d '{"sessionId":"first","message":"七天无理由退货的条件是什么？"}'
# → {"answer":"...","inputTokens":...,"outputTokens":...,"totalTokens":...}hiring 项目（Ch24/25）需要 MySQL + Redis 先就位，启动与 E2E 验证见 Ch24 的 24.8 节，那里有完整实测记录。
0.4 章节地图与学习路径
基础篇（Ch1→9）把 smart-doc-assistant 从空目录一路搭到 v0.7，按序读最省力；有经验的读者可以直接进进阶篇，缺什么回来查。
| 章 | 主题 | 前置 | 外部服务 |
|---|---|---|---|
| Ch1 | 环境搭建与 Hello World | — | LLM key |
| Ch2 | AI Services 声明式编程 | Ch1 | LLM key |
| Ch3 | 模型参数与 Prompt Engineering | 上一章 | LLM key |
| Ch4 | 流式输出与 SSE | 上一章 | LLM key |
| Ch5 | 对话记忆 ChatMemory | 上一章 | LLM key、可选 Redis |
| Ch6 | 工具调用 Tools | 上一章 | LLM key |
| Ch7 | 结构化输出 | 上一章 | LLM key |
| Ch8 | Embedding 与语义检索 | 上一章 | 无（本地 ONNX 即可） |
| Ch9 | 多模态与图像模型 | 上一章 | 多模态模型 API（DashScope） |
进阶篇与实战篇（Ch10 起）的依赖关系：
| 章 | 主题 | 前置 | 外部服务 |
|---|---|---|---|
| Ch10 | 文档管线（解析/分块/入库） | Ch8 | 无（本地嵌入模型） |
| Ch11 | 向量库（选型与切换） | Ch10 | 可选 Redis |
| Ch12 | 高级 RAG（父子分块 + 混合检索 + 重排） | Ch10、Ch11 | LLM key |
| Ch13 | RAG 评估（金标集 + MRR 门禁） | Ch12 | LLM key |
| Ch14 | Agent 基础（@Tool 与工具循环） | Ch6 | LLM key |
| Ch15 | Agentic 编排模式（官方六种多 Agent 协作） | Ch14 | LLM key |
| Ch16 | Agent 工程（动态供给/审计/并发/护栏） | Ch14 | LLM key |
| Ch17 | MCP 客户端（接外部工具生态） | Ch14 | Node ≥ 18 |
| Ch18 | Skills（按需加载行为手册） | Ch14、Ch17 更佳 | 无 |
| Ch19 | MCP 服务端（stdio + Streamable HTTP） | Ch17 | Node、可选 Claude Desktop |
| Ch21 | Guardrails（输入/输出/工具三层防护） | Ch14 | 无（护栏单测不需要 Spring） |
| Ch22 | 可观测性（token 计量 + 成本对账 + 告警阈值） | Ch2 | LLM key |
| Ch24/25 | 企业级实战：招聘自动化全链路 | 全部 | MySQL + Redis |
两个“顺序不敏感”的地方：Ch15~18 可以互换顺序（都只依赖 Ch14）；Ch21/22 是横切能力，插在主线任意位置读都成立。Ch17/19 是 MCP 的客户端/服务端一对，对照读收获最大。只有 Ch13 建议放在 Ch12 之后立刻读——评估是前面所有优化的裁判，没有它的 MRR 数字，Ch12 里“父子分块更好”就只是一句主张。
0.5 全系列约定
进阶篇与实战篇（Ch10 起）每章开头有一块基线（项目 / 端口 / LangChain4j 版本 / JDK / 最后验证日期），先看它再读正文——版本对不上，某些 API 可能已经变了；基础篇（Ch1~9）不设这块，版本与端口口径统一以本章为准。
正文里的数字分两档，处理方式不同：
- 实测数字（MRR 0.652、单次成本 ¥0.000285、误杀率 10%）：都是标注了日期的真实运行结果，环境是“本项目 + 指定模型”。你换模型、换语料后数字会变，结论的方向通常不变，数值请自己重测；
- 演示数字（单价表、吞吐估算）：来自厂商官网或公开资料，只用于演示公式，用前自己核对。
进阶篇与实战篇每章末尾有坑点表（来自真实踩坑——源码核实、javap 反编译、当天报错，不是“可能遇到的问题”清单）和练习题（分动手和思考两档，动手题都验证过可行）；基础篇的坑写在正文对应位置（如 Ch1 的「坑 1~4」小节）。代码块遵守一个硬约束：单行不超过 94 个显示宽度（汉字算 2），保证不横向滚动——这也是你读代码时不用左右拖动的原因。
教学版与生产版的边界在每章单独声明（内存存储、mock 工具、演示单价等）。教学版只证明机制成立，上生产前要按各章“生产建议”逐条补齐。
0.6 常见环境问题速查
| 症状 | 原因 | 处理 |
|---|---|---|
构建报 RequireJavaVersion failed |
JDK 低于 21 | JAVA_HOME 指向 21（推荐）或更高版本 |
启动报 JedisConnectionException |
没装 Redis 但配置要连 | 加 --chat.memory.backend=memory，或装 Redis |
调模型报 Access denied ... good standing |
API key 欠费 | 去厂商控制台充值；或换另一家 key |
启动报 Conflict: multiple HTTP clients |
MCP 依赖引入了第二个 HTTP SPI 实现 | pom 已排除 langchain4j-http-client-jdk，不要删那个 exclusion |
POST /api/chat 返回 500 |
请求体缺 sessionId（@MemoryId 不接受 null） |
请求体带上 sessionId 字段 |
| 8090/8091 端口被占 | 上一个实例没退 | lsof -ti:8090 | xargs kill 后重启 |
本章参考
- LangChain4j 版本发布页：https://github.com/langchain4j/langchain4j/releases
- 两个项目的
application.yml（全部配置项带注释，是配置的单一真相源） - 各章“本章基线”块——环境口径以它为准
下一站：从 Ch10 文档管线开始，或者直接跳到你需要的章节——每章都是自包含的，缺的前置在“章节地图”里。