Appearance
环境准备：从零到第一次真实调用
1. 本节产出
本地机器上完成：JDK + Maven + IDE + Docker 就绪，申请到至少一个国内模型的 API Key，并用一条 curl 和一个最小 Java 工程，各跑通一次真实调用。
2. 前置依赖
无额外技术前置。需要准备：
- 一台内存 ≥ 16GB 的开发机（跑向量库和 Redis 会占内存；8GB 也能跑，但 Docker 会很吃紧）
- 能正常访问公网的模型服务商（国内服务商即可）
3. 为什么这节不能跳过
统计上新手卡住的位置，八成在这步，而不是代码：
| 卡点 | 典型报错 | 真实原因 |
|---|---|---|
| 依赖拉不下来 | Could not find artifact | 里程碑版本需要额外仓库，中央仓库没有 |
| 调用 401 | invalid api key | Key 复制时带了空格，或用了错环境的 Key |
| 调用 404 | path not found | Base URL 重复拼接了 /v1 |
| 本地端口不通 | Connection refused / 超时 | Docker 没起、或被本机代理/安全软件拦截回环地址 |
先把环境做扎实，后面每一章才能只看增量。
4. 核心原理：一次调用到底经过什么
你的 Java 代码
→ Spring AI 的 ChatModel（封装请求/解析响应）
→ HTTP POST {baseUrl}/chat/completions
→ 模型厂商的服务端
→ 返回 JSON（choices[0].message.content + usage）你需要向模型厂商拿到三样东西，缺一不可：
| 项 | 说明 | 易错点 |
|---|---|---|
| Base URL | 服务商的 API 地址 | 有的厂商要求以 /v1 结尾，有的不需要。Spring AI 的 OpenAI 客户端通常会自己拼 /chat/completions，所以要确认完整拼起来对不对 |
| API Key | 鉴权凭据 | 环境变量注入，绝不进 Git |
| Model Name | 模型标识字符串 | deepseek-chat、glm-4 这类，写错会报模型不存在 |
为什么推荐 OpenAI 兼容协议的模型：国内多数厂商都提供 OpenAI 兼容端点，Spring AI 的 OpenAI starter 可以直接改 base-url 对接。这意味着一套代码切换厂商只需要改配置，不需要换依赖——这是后面「多模型切换」能力的基础。
提示：务必确认你选的模型是否支持工具调用（function calling）。不支持工具调用的模型，01-07 之后的章节都做不了。选型时把这当成硬门槛。
5. 操作步骤
步骤 1：安装 JDK
推荐 JDK 21（LTS）。用 SDKMAN 或直接从发行版官网装均可：
bash
java -version
# 期望输出包含 21.x如果公司老项目还在 17，也没问题，本新课程内容在 17 上可跑；差别只在极少数语法特性，遇到时在章节里会标注。
步骤 2：安装 Maven
bash
mvn -v
# 期望 Maven 3.9+给 Maven 配好国内镜像源（很多公司网络拉境外仓库会超时），修改 ~/.m2/settings.xml 的 mirrors。
步骤 3：安装 IDE
IntelliJ IDEA 或 VS Code 均可。录屏演示用深色主题 + 等宽字体（JetBrains Mono / Fira Code），字号不小于 18pt——这是为了让录屏出来的视频在手机上也看得清。
步骤 4：安装 Docker Desktop
后面 PGVector、Redis、Milvus 全靠它起。
bash
docker version
docker compose version
docker run --rm hello-worldWindows 用户注意：Docker Desktop 依赖 WSL2，装完要确认 BIOS 虚拟化已开启。
步骤 5：申请模型 API Key
选一家国内服务商注册，在控制台创建 API Key。建议：
- 演示用单独的 Key，并设置低额度上限，避免调试失控烧钱
- 立刻充值一个小额（比如 20-50 元），避免演示到一半余额不足
步骤 6：用 curl 验证联通（先于 Java）
这一步是关键：先用最原始的方式确认 Key、URL、模型名三者都对，排除掉网络与鉴权问题，再写 Java。
bash
curl https://<厂商域名>/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "<模型名>",
"messages": [{"role":"user","content":"用一句话介绍 Spring Boot"}],
"max_tokens": 100
}'期望返回（节选）：
json
{
"choices": [{"message": {"role": "assistant", "content": "..."}}],
"usage": {"prompt_tokens": 15, "completion_tokens": 42, "total_tokens": 57}
}拿到这段输出，记下 usage 字段——后面的成本章节要用到它。
步骤 7：最小 Java 工程
不要手写 pom，用 Spring Initializr 生成骨架，选择 Spring Web + 对应的 Spring AI starter。或者在配套 demo 仓库检出：
bash
cd demos/spring-ai-basics
git checkout ch00-02-env-setup配置 .env（仓库里只有 .env.example，复制后填自己的 Key）：
properties
spring.ai.openai.api-key=${API_KEY}
spring.ai.openai.base-url=https://<厂商域名>
spring.ai.openai.chat.options.model=<模型名>跑起来后调一次接口，确认 Java 侧也通了。
6. 验证清单
逐条打勾，全绿再进下一章：
- [ ]
java -version输出 17 或 21 - [ ]
mvn -v输出 3.9+ - [ ]
docker ps能正常返回 - [ ] curl 调用返回了带
usage的 JSON - [ ] Key 没有硬编码在代码里，且
.env已被.gitignore忽略 - [ ] Java 工程能启动并成功返回一次模型回答
7. 生产避坑
- 别把 Base URL 的
/v1拼两遍。最常见的情况：厂商文档给的域名已经带/v1，配置文件里又写了一遍，结果请求打到/v1/v1/chat/completions报 404。做法：先在 curl 里试通，把 curl 里那串 URL 原样搬到配置里。 - Key 一旦进过 Git 历史就当它已泄露。立刻去控制台吊销重新生成，
git rm之后还要清理历史记录。演示时养成习惯：.gitignore里预置.env，仓库只放.env.example。 - 本机代理/安全软件会拦截回环地址。表现是 Docker 容器映射的端口连不上、或 IDE 里调 localhost 超时，而关掉代理软件就正常。排查方法：
telnet 127.0.0.1 <端口>，如果代理开着时不通、关掉就通，那就是它——去软件里把127.0.0.1加入排除列表，而不是关掉整个代理（公司准入软件通常关不掉）。 - 验证时不要偷懒跳过 curl 那一步。直接上 Java 的话，一次报错里同时混杂了依赖问题、配置问题、网络问题，排查时间通常是先 curl 的三倍。
8. 延伸与锚点
- 思考题：你的公司网络能直连模型厂商吗？如果不能，需要找谁申请放行？这个答案决定了后续能不能做内部推广。
- 代码锚点：
ch00-02-env-setup - 下一章：00-03 版本矩阵——把依赖版本一次定死，后面就不会再被环境问题打断。