项目实战路线图

要点

  • 本知识体系用三个递进式实战项目串联核心知识点
  • 项目一：AI 聊天 API——覆盖基础层 + AI 层核心能力
  • 项目二：RAG 系统——覆盖检索增强全链路
  • 项目三：Agent 平台——覆盖工具调用与多步编排
  • 每个项目都有明确的技术栈、功能边界和验收标准
  • 项目代码从零开始写，不是"改模板"

内容

1. 为什么需要实战项目

技术知识有一个特点：读的时候觉得懂了，做的时候发现不会。

比如你读完了"流式响应"的讲解，理解了 SSE 的原理，知道 streamText 的用法。但真正做项目时，你会遇到：

  • 客户端断连后服务端还在跑，怎么取消模型调用？
  • 流式输出到一半出错了，怎么给客户端发错误信号？
  • 多个用户同时请求，怎么保证流不会串？

这些问题只有在做项目的过程中才会暴露。

所以本知识体系设计了三个递进式的实战项目（分组 25-27），每个项目覆盖一组核心能力。

2. 项目总览

项目核心能力涉及分组预计工时
AI 聊天 API模型调用 + 流式输出 + 用户认证02-12, 221-2 周
RAG 知识库系统文档处理 + 向量检索 + 上下文组装09, 14, 161-2 周
Agent 工具平台Function Calling + 多步编排 + 状态管理15, 17, 182-3 周

三个项目的关系是递进的：

项目一：AI 聊天 API
  ↓ 你已经能让模型"说话"
项目二：RAG 系统
  ↓ 你已经能让模型"查资料后回答"
项目三：Agent 平台
  ↓ 你已经能让模型"使用工具完成任务"

3. 项目一：AI 聊天 API

这是第一个实战项目，目标是构建一个完整的 AI 聊天后端服务。

3.1 功能需求

  • 用户注册 / 登录（邮箱 + 密码）
  • JWT 认证，请求需携带 token
  • 创建对话、发送消息、获取历史
  • 调用模型 API 生成回复（支持流式输出）
  • 用量统计（token 消耗记录）
  • 速率限制（防滥用）

3.2 技术栈

运行时：Cloudflare Workers
框架：Hono
数据库：Cloudflare D1（用户、对话、消息）
缓存：Cloudflare KV（会话、限流计数）
AI：Cloudflare Workers AI 或 OpenAI API
ORM：Drizzle ORM
认证：JWT（hono/jwt）
校验：Zod + @hono/zod-validator

3.3 核心学习点

学习点对应分组
Hono 路由 + 中间件02, 03, 05
Zod 校验 + 类型推导06
数据库 CRUD09
JWT 认证10
模型 API 调用 + 流式输出11, 12
速率限制18
Workers 部署22

3.4 验收标准

  • 能注册、登录、获取 token
  • 能创建对话、发送消息、收到流式回复
  • 未认证请求返回 401
  • 超出速率限制返回 429
  • 用量正确记录到数据库
  • 成功部署到 Cloudflare Workers

4. 项目二：RAG 知识库系统

在"能聊天"的基础上，让模型能基于你的文档回答问题。

4.1 功能需求

  • 上传文档（支持 TXT、Markdown、PDF）
  • 文档切片（按段落或固定长度分块）
  • 生成 Embedding 并存入向量数据库
  • 用户提问时，先检索相关文档片段
  • 将检索结果注入 prompt，调用模型生成回答
  • 引用来源展示（告诉用户答案来自哪个文档的哪一段）

4.2 技术栈

运行时：Cloudflare Workers
框架：Hono
向量数据库：Cloudflare Vectorize
Embedding：Workers AI / OpenAI Embedding
对象存储：Cloudflare R2（原始文档存储）
数据库：Cloudflare D1（文档元数据、用户数据）
PDF 解析：pdf-parse 或 pdfjs-dist（在 Worker 中需要兼容处理）

4.3 核心学习点

学习点对应分组
文件上传与处理16
文档切片策略14
Embedding 生成14
向量存储与检索14
Prompt 组装（检索结果 + 用户问题）13
引用来源追踪14

4.4 RAG 完整流程

文档上传 → 文本提取 → 文档切片 → 生成 Embedding → 存入向量数据库
                                                           │
用户提问 → 问题 Embedding → 向量检索 → Top-K 片段 → 组装 Prompt → 模型生成 → 返回答案 + 引用

4.5 验收标准

  • 能上传 TXT / Markdown 文档
  • 文档自动切片并生成 Embedding
  • 用户提问时能检索到相关文档片段
  • 模型回答引用了正确的文档来源
  • 上传不存在的文档内容时，模型回答"不确定"

5. 项目三：Agent 工具平台

最复杂的项目。让 AI 不只是"回答问题"，而是能"使用工具完成任务"。

5.1 功能需求

  • 定义工具（如：天气查询、网页搜索、计算器）
  • 用户发消息，模型决定调用哪个工具
  • 后端执行工具调用，将结果返回给模型
  • 模型根据工具结果生成最终回答
  • 支持多轮工具调用（一次不够就调多次）
  • 工具调用的日志和状态追踪

5.2 技术栈

运行时：Cloudflare Workers
框架：Hono
工具执行：Worker 内函数调用
状态管理：Durable Objects 或 KV（多轮对话状态）
模型：OpenAI GPT-4 / Claude（支持 Function Calling）
日志：结构化日志记录每次工具调用

5.3 核心学习点

学习点对应分组
Function Calling 协议15
工具定义与注册15
多轮工具调用循环15
状态管理（Durable Objects / KV）17
错误处理与超时控制19
结构化日志21

5.4 Agent 执行循环

用户消息 → 模型推理
              │
              ├─→ 模型返回最终回答 → 结束
              │
              └─→ 模型返回 tool_call
                     │
                     ├─→ 执行工具函数
                     ├─→ 将结果注入对话
                     └─→ 再次调用模型 ← 回到循环

5.5 验收标准

  • 能定义并注册至少 3 个工具
  • 模型能正确选择工具并生成调用参数
  • 工具执行结果能正确返回给模型
  • 多轮工具调用能正常工作
  • 工具调用超时时有合理的降级处理
  • 每次工具调用有完整的日志记录

6. 三个项目的能力覆盖图

             基础层     能力层      AI 层      工程化     部署
项目一（聊天） ████████  ████████  ████████  ██░░░░░░  ████████
项目二（RAG）  ████░░░░  ████████  ████████  ████████  ████████
项目三（Agent）██░░░░░░  ████████  ████████  ████████  ████████

三个项目组合起来，覆盖了 30 个分组中约 80% 的核心内容。

7. 项目之间可以跳过吗

可以，但不建议。

三个项目的递进关系不只是功能复杂度，还有知识依赖：

  • 项目一建立了 Hono 基础 + 模型调用的心智模型
  • 项目二在此基础上增加了检索增强链路
  • 项目三进一步引入了状态管理和多步编排

如果你已经有 RAG 经验，可以跳过项目二直接做项目三。但如果你三个都是新领域，建议按顺序来。

8. 总结

本知识体系通过三个递进式实战项目，帮你把 30 个分组的知识点串联起来：

  1. AI 聊天 API——跑通最基本的模型调用 + 流式输出
  2. RAG 知识库系统——加上文档检索，让模型能基于你的数据回答
  3. Agent 工具平台——让模型能使用工具，处理更复杂的任务

每个项目都有明确的功能需求、技术栈和验收标准。做完这三个项目，你就有了三个可以放到简历或作品集里的完整作品。

下一篇讲技术选型总览——把整个知识体系用到的技术栈统一梳理一遍，帮你建立全局技术地图。