14 阶段交付
阶段交付
阶段交付的核心不是继续加新功能，而是把前面做过的聊天、流式输出、Tool Calling、FastAPI 和 Java/Python 联调整理成一个能启动、能演示、能复现的小项目。
[TOC]
本节要做什么
本节是基础阶段的收尾。
前面已经学过：
环境和路线
LLM API
Prompt
JSON 结构化输出
流式输出
Spring AI
聊天 DemoTool Calling
Java Tool Calling
FastAPI
LangChain
LangGraph
Java + Python 联调
本节不建议继续堆新知识。
这里要做的是交付一个阶段成果。
最小阶段成果：
聊天接口
流式输出接口
Tool Calling Demo
Python Agent Demo
Java 调 Python DemoREADME
接口文档
运行说明
环境变量示例
阶段交付整理流程：
graph TD;
A["梳理已完成能力"];
B["整理项目结构"];
C["补 README 和环境变量示例"];
D["补接口文档和 curl 示例"];
E["分别启动 Java 和 Python"]; F["按演示脚本验证接口"];
G["接口能复现则提交 Git"]; H["接口不能复现则修正说明和配置"];
A --> B; B --> C; C --> D; D --> E; E --> F; F --> G; F --> H; H --> E;
什么叫能交付
学习项目也要有交付标准。
不是“我写过代码”。
而是别人拿到项目以后能做到：
知道项目做什么
知道怎么配置环境变量
知道怎么启动 Java知道怎么启动 Python知道怎么调用接口
知道每个 Demo 对应哪个主题
知道失败时看哪里
阶段交付的目标是：
把零散练习整理成一个可复现的小作品。
建议项目结构
可以整理成这样：
ai-agent-study
├── ai_agent
│ ├── 01
│ ├── 02
│ └── ...
├── ai_study
│ ├── ai_demo
│ │ ├── src
│ │ ├── pom.xml
│ │ ├── .env.example
│ │ └── README.md
│ └── python_study
│ ├── fastapi_ai_service
│ ├── langchain_basic
│ ├── langgraph_basic
│ ├── requirements.txt
│ ├── .env.example
│ └── README.md
└── README.md
根目录 README.md 讲整体。
Java 子目录 README.md 讲 Spring Boot 怎么跑。
Python 子目录 README.md 讲 FastAPI 和 LangChain 怎么跑。
阶段能力清单
建议在 README 里列清楚：
流式输出
Spring AI ChatClient
AI Chat Demo
Tool Calling 概念
Java Tool Calling
Python FastAPI
LangChain 基础
LangGraph 基础
Java + Python 联调
每个能力后面放：
接口地址
页面地址
启动要求
测试方式
不要让未来的自己重新猜。
README 模板
根目录 README 可以这样写：
# AI Agent Study
这个项目用于按系统化路线学习 AI Agent 开发。
## 当前阶段
基础阶段：基础入门
已经完成：
- LLM API 调用
- Prompt 基础
- JSON 结构化输出
- 流式输出
- Spring AI ChatClient
- Tool Calling
- FastAPI
- LangChain 基础
- LangGraph 基础
- Java + Python 联调
## 子项目
| 目录 | 说明 |
| --- | --- |
| ai_agent | 学习笔记 |
| ai_study/ai_demo | Java Spring Boot Demo |
| ai_study/python_study | Python AI Demo |
## 环境要求
- Java 17+
- Maven 3.9+
- Python 3.11+
- DashScope API Key
## 快速启动
### Java
```bash
cd ai_study/ai_demo
mvn spring-boot:run
```
### Python
```bash
cd ai_study/python_study
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
uvicorn main:app --reload --host 127.0.0.1 --port 8000
```
Windows 可以把激活虚拟环境改成：
.\.venv\Scripts\activate
环境变量
不要提交真实 API Key。
提供 .env.example：
DASHSCOPE_API_KEY=
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen-plus
Java 侧如果使用 Spring AI Alibaba，也可以保持：
spring.ai.openai.api-key=${DASHSCOPE_API_KEY}
spring.ai.openai.base-url=${DASHSCOPE_BASE_URL}
spring.ai.openai.chat.options.model=${QWEN_MODEL}
具体字段按当前项目配置为准。
重点是：
.env.example 可以提交
.env 不要提交
真实 key 不要写进 README
接口文档
阶段交付至少写一个接口表。
示例：
## Java 接口
| 模块 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 05 | GET | /api/05/stream | 流式输出 |
| 06 | POST | /api/06/chat | Spring AI ChatClient |
| 07 | POST | /api/07/chat | 最小聊天 Demo |
| 08 | POST | /api/08/tool-calling/mock-flow | Tool Calling 流程演示 |
| 09 | POST | /api/09/tools/chat | Java Tool Calling |
| 13 | POST | /api/13/chat | Java 调 Python |
## Python 接口
| 模块 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 10 | GET | /health | FastAPI 健康检查 |
| 10 | POST | /chat | Python 聊天接口 |
| 13 | POST | /api/agent/chat | Java 联调用 AI 接口 |
如果某个接口还没实现，就标明：
计划实现
不要假装已经完成。
curl 测试脚本
可以放一个 docs/curl.md。
示例：
curl -X POST http://127.0.0.1:8080/api/07/chat \ -H "Content-Type: application/json" \ -d '{"message":"什么是 AI Agent？"}'
Java 调 Python：
curl -X POST http://127.0.0.1:8080/api/13/chat \ -H "Content-Type: application/json" \ -d '{"message":"什么是 LangGraph？"}'
Python 单独测试：
curl -X POST http://127.0.0.1:8000/api/agent/chat \ -H "Content-Type: application/json" \ -d '{"requestId":"req-001","message":"什么是 RAG？"}'
curl 能跑通，说明交付物至少能被验证。
页面入口
如果已有静态页面，可以在 README 里列出来：
http://127.0.0.1:8080/05-streaming-output-practice.html
http://127.0.0.1:8080/06-spring-ai-intro.html
http://127.0.0.1:8080/07-ai-chat-demo.html
http://127.0.0.1:8080/08-tool-calling-concept.html
页面入口的作用是方便演示。
但后端接口仍然要能用 curl 测试。
阶段验收标准
可以按这个表检查：
Java 项目能启动
Python 项目能启动
Java 能单独调用模型
Python 能单独返回结果
Java 能调用 Python流式输出能看到逐步返回
Tool Calling 能看到工具结果
README 能按步骤复现
.env 没有提交
接口文档和实际路径一致
如果有一项没完成，就写到 TODO。
不要让 README 变成宣传稿。
TODO 写法
阶段交付允许有 TODO。
好的 TODO 是具体的：
## TODO
- 补真实 Spring AI @Tool Demo 页面
- 给 Java 调 Python 增加超时配置
- 补充接口截图
- 进入 RAG 原理和项目边界
不好的 TODO 是模糊的：
优化项目
完善代码
增强功能
写 TODO 的目的不是凑字。
是让下一阶段知道从哪里继续。
演示脚本
如果要给别人演示，可以准备 5 分钟脚本：
1. 打开 README，说明整体路线
2. 启动 Java Spring Boot3. 调用 /api/07/chat 展示普通聊天
4. 打开流式输出页面，展示逐字返回
5. 调用 Tool Calling Demo，展示工具结果不是模型编的
6. 启动 FastAPI，展示 Java 调 Python7. 说明下一阶段进入 RAG 知识库
演示时不要讲太多理论。
重点让对方看到：
能启动
能调用
能解释
能继续扩展
常见问题
阶段交付要不要重构
只做必要整理。
不要在阶段收尾时大改架构。
本节的重点是：
补 README补接口文档
补运行说明
修明显无法运行的问题
没有完成的模块要不要写进 README
要写，但标清楚状态。
比如：
Tool Calling：已完成概念流程，真实工具注册在后续实现中
Java 调 Python：链路已跑通，重试策略待完善
真实状态比漂亮状态更重要。
是否需要截图
可以有，但不是必须。
如果有前端页面，截图能帮助复盘。
建议放：
docs/images
不要把大图散落在根目录。
要不要提交 Git
如果这个目录是 Git 仓库，建议提交。
提交前检查：
git status```
确认没有：
```text
.env
API Key
target
__pycache__
.venv
练习清单
完成几件事情：
整理根目录 README整理 Java README整理 Python README补 .env.example列出 Java 接口表
列出 Python 接口表
补 curl 测试命令
补页面入口
检查 Java 能启动
检查 Python 能启动
检查 Java 调 Python 能通
写清楚 TODO
建议目录：
ai-agent-study
├── README.md
├── docs
│ ├── api.md
│ ├── curl.md
│ └── images
├── ai_study
│ ├── ai_demo
│ │ ├── README.md
│ │ └── .env.example
│ └── python_study
│ ├── README.md
│ └── .env.example
小结
本节的结论：
阶段交付的重点是复现能力，不是功能数量。
一个合格的第 1 阶段交付物应该具备：
能启动
能调用
有文档
有测试命令
无密钥泄露
知道下一步做什么
下一阶段开始，项目进入 RAG 知识库阶段。
前面的 Java、Python、Tool Calling、LangChain、LangGraph 都会变成 RAG 项目的基础设施。