【免费下载链接】chatbot-templateA minimal chatbot template built with Next.js, AI SDK, shadcn/ui, shadcn/react, shadcn/typeset. It runs on the Vercel AI Gateway.项目地址https://gitcode.com/gh_mirrors/chatbo/chatbot-template点击查看免费下载文章开始chatbot-template是一个基于Next.js AI SDK构建的最小化流式聊天机器人模板开箱即用地支持流式输出Streaming、工具调用Tool Calling、网页搜索和人在回路问卷交互模型接入由Vercel AI Gateway统一代理。这篇文章带你深入它的核心实现一条消息从点击发送到逐字渲染中间到底经历了什么。如果你正在学习 AI SDK 的流式聊天架构这个项目的代码量足够小、结构足够清晰是理解前后端流式数据流的绝佳范例。一、项目概览一次聊天用到哪些技术chatbot-template 的技术栈可以概括为四层层次技术作用框架层Next.jsApp Router提供/api/chat流式接口路由与页面AI 层aiAI SDK Vercel AI Gateway统一接入多家模型流式输出交互层ai-sdk/react的useChat前端聊天状态管理与流式订阅UI 层shadcn/ui shadcn/typeset消息气泡、问卷、Markdown 排版项目结构非常扁平核心文件只有这几个app/api/chat/route.ts —— 流式聊天接口整个后端的心脏components/chat.tsx —— 前端聊天主组件useChat的调用处tools/index.ts —— 工具注册中心定义聊天机器人能做什么components/chat-message.tsx —— 消息渲染分发器把不同类型的零件交给对应组件依赖清单见 package.jsonAI 相关的关键依赖有ai核心 SDK、ai-sdk/reactReact 集成、ai-sdk/gatewayAI Gateway 接入。二、核心数据流一条消息的完整旅程理解这个项目最重要的是先建立一张数据流地图。一次聊天的完整链路如下前端发送 → Next.js 路由校验 →streamText调用模型 → 工具执行多轮循环 → UI 消息流 → 前端逐段渲染拆开来看前端用户在输入框提交消息components/prompt-form.tsx 调用sendMessageHTTP 请求发往/api/chat同时把当前选中的模型 ID 放在请求体里。路由层app/api/chat/route.ts 校验模型白名单、校验消息结构然后调用streamText发起流式生成。模型层streamText通过 AI Gateway 调用真实模型返回的不是完整文本而是一个流Stream——token 产生多少就推送多少。工具循环如果模型决定调用工具查仓库、搜索网页、问用户流中会插入工具调用片段工具执行完结果再喂回模型继续生成最多循环 5 步。前端渲染流被转换成 UI Message StreamuseChat按零件part粒度消费——文本块、工具调用块、引用来源块各自渲染成不同的 UI 组件。用户输入 │ ▼ prompt-form.tsx ──sendMessage──▶ /api/chat (route.ts) │ validateUIMessages ▼ streamText ──▶ AI Gateway ──▶ 模型 │ (tool call? 是 → 执行工具 → 回喂≤5步) ▼ toUIMessageStream (UI 消息流) ▼ useChat 订阅 ──▶ chat-message.tsx 按 part 分发渲染三、后端核心streamText流式输出是怎么写安全的app/api/chat/route.ts 只有 70 行却覆盖了生产级流式接口该做的所有防御值得逐点看1. 请求体容错先try/catch解析 JSON失败直接返回400不会让整个服务崩掉。2. 模型白名单模型列表集中在 lib/models.ts路由里用isModelAllowed(modelId)拦截用户传任意模型 ID 都没用。想换模型或加模型改这一个文件即可。3. 消息结构校验validateUIMessages在信任任何消息之前逐条校验消息和工具片段的结构是否合法——这是防注入、防脏数据的关键一步。4. 流式参数控制见 app/api/chat/route.ts参数作用stopWhen: isStepCount(5)限制模型↔工具最多循环 5 步防止无限递归烧钱maxOutputTokens: 8192限制单次输出长度控制成本上限abortSignal: req.signal用户关页面/停止生成时立即中断上游请求5. 流式响应封装最终通过createUIMessageStreamResponsetoUIMessageStream把原始 token 流封装为UI 消息流并开启sendSources: true——这样网页搜索的引用来源也能随流推给前端。 架构要点streamText的返回值是一个惰性流不是等模型说完再返回。这正是聊天机器人逐字蹦出来体验的技术基础。四、工具调用Tool Calling机器人的三种超能力工具定义在 tools/ 目录一个文件一个工具文件名就是模型看到的工具名。tools/index.ts 负责组合注册const baseTools { github_repo: githubRepo, ask_user: askUser } // 若当前模型支持再追加 web_search1️⃣ github_repo —— 服务端执行的典型工具tools/github_repo.ts 用zod定义了输入owner/name格式的仓库名和输出stars、forks、语言等的 Schemaexecute里调用 GitHub API 查公开数据并内置了5 秒超时 流中断信号合并保证工具不会卡死整个聊天流。2️⃣ web_search —— 各厂商原生搜索工具tools/web_search.ts 展示了工具随模型而变的写法OpenAI 模型用openai.tools.webSearch()Anthropic 模型用其对应的搜索工具。这种按模型 ID 前缀分发的策略让一套前端适配了不同厂商的原生能力。3️⃣ ask_user —— 唯一不在服务端执行的工具tools/ask_user.ts 定义了输入若干问题 每题恰好 3 个选项和输出问答对但没有execute函数——因为它的执行者是屏幕前的用户。这个设计是全文最巧妙的部分下一节细说。五、前端渲染消息 parts 与状态机思维AI SDK 里一条助手消息不是纯文本而是一组有序的类型化零件parts。components/chat-message.tsx 的核心就是一个switch (part.type)分发器part 类型渲染组件界面效果texttext-part.tsxMarkdown 富文本react-markdown typesettool-github_repogithub-repo-part.tsx先转圈 Looking up…再显示 stars/forks 统计条tool-web_searchweb-search-part.tsxSearching the web… → Searched the webtool-ask_userask-user-part.tsx已回答的问答内联展示source-urlsources-part.tsx流结束后聚合为 Searched N websites 抽屉更有意思的是每个工具零件都实现了状态机input-streaming → input-available → output-available └→ output-error以 web-search-part.tsx 为例流刚开始推送工具输入时显示正在搜索…执行完切换为已搜索出错则显示错误文案。一个组件四种状态随流自动演进——这就是流式 UI 与普通轮询 UI 的本质区别。六、Human-in-the-loopask_user 问卷如何打断又续传对话这是 chatbot-template 最有教学价值的功能当用户的问题含糊不清时模型会主动发起问卷等用户答完再继续。实现分三步第一步模型发起提问模型调用ask_user工具流中插入tool-ask_user零件。components/chat.tsx 检测到存在状态为input-streaming或input-available的待答问题就在滚动区底部吸顶弹出问卷卡片 components/question-card.tsx——用户可点选选项也可自由输入。第二步用户作答提交后调用addToolOutput见 components/chat.tsx把答案作为工具输出回传。因为ask_user没有服务端execute用户的操作就是那次执行。第三步自动续传components/chat.tsx 中有一个关键配置sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls它让前端在最后一条助手消息已完成且带工具调用时自动重发请求把工具结果回喂给模型。用户答完问卷对话无需任何手动操作就继续流式生成。 总结这个模式省略 execute 前端自动重发 人在回路Human-in-the-loop。这是 AI SDK 里把用户变成工具执行器的标准范式。七、快速上手本地运行 chatbot-template三步跑起来# 1. 安装依赖 pnpm install # 2. 配置 AI Gateway 凭证二选一 vercel link vercel env pull # 从已链接的 Vercel 项目拉取 OIDC token # 或在 Vercel 控制台 AI Gateway → API Keys 创建密钥写入 .env.local 的 AI_GATEWAY_API_KEY # 3. 启动 pnpm dev⚠️安全提醒详见 README.md 的 Security 章节/api/chat是公开无鉴权接口每个请求都消耗你的 AI Gateway 额度。上真实流量前务必加限流、设置 Gateway 消费上限、或加登录鉴权。八、如何扩展给自己加一个新工具想加工具比如查天气只需两步类型系统全程护航新建 tools/ 下weather.ts用tool()导出描述、inputSchema和execute再到 tools/index.ts 注册在 components/parts/ 加一个零件组件并在 chat-message.tsx 加一个case tool-weather。由于消息类型通过InferUITools从工具定义自动推导你在零件组件里能拿到完整类型提示——改错字段名直接编译报错而不是运行时悄悄变成undefined。总结chatbot-template 用极小的代码量完整演示了一个现代流式聊天机器人的架构骨架后端streamText 流式响应封装 白名单/限步/限 token/可中断构成安全的流式接口范式app/api/chat/route.ts工具层一文件一工具、Schema 描述输入输出、execute与人在回路分离tools/前端useChat消费 UI 消息流parts 状态机驱动渐进式 UIcomponents/chat-message.tsx范式省略executesendAutomaticallyWhen实现 Human-in-the-loop 问卷交互tools/ask_user.ts如果你想给自己的产品加一个 AI 聊天能力直接以它为起点改造是最短的路径。赞分享【免费下载链接】chatbot-templateA minimal chatbot template built with Next.js, AI SDK, shadcn/ui, shadcn/react, shadcn/typeset. It runs on the Vercel AI Gateway.项目地址https://gitcode.com/gh_mirrors/chatbo/chatbot-template点击查看免费下载相关推荐揭秘Awesome ChatGPT深入理解AI聊天机器人核心架构与实现原理揭秘Awesome ChatGPT深入理解AI聊天机器人核心架构与实现原理 在人工智能快速发展的今天ChatGPT作为最受欢迎的AI聊天机器人之一其背后的SonataAdminBundle 与工作流集成实现复杂业务状态管理SonataAdminBundle 与工作流集成实现复杂业务状态管理 SonataAdminBundle 作为 Symfony 的强大管理后台生成器提供了丰10分钟上手现代AI聊天机器人GitHub_Trending/ai/ai-chatbot架构全解析10分钟上手现代AI聊天机器人GitHub_Trending/ai/ai chatbot架构全解析 你是否还在为构建AI聊天机器人时的技术选型而烦恼是否想快AI 应用前端后端交互助手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/15 18:41:01 · 阅读 1.2k 深入理解 chatbot-template 架构：AI SDK 流式聊天机器人的核心实现原理
【免费下载链接】chatbot-templateA minimal chatbot template built with Next.js, AI SDK, shadcn/ui, shadcn/react, shadcn/typeset. It runs on the Vercel AI Gateway.项目地址https://gitcode.com/gh_mirrors/chatbo/chatbot-template点击查看免费下载文章开始chatbot-template是一个基于Next.js AI SDK构建的最小化流式聊天机器人模板开箱即用地支持流式输出Streaming、工具调用Tool Calling、网页搜索和人在回路问卷交互模型接入由Vercel AI Gateway统一代理。这篇文章带你深入它的核心实现一条消息从点击发送到逐字渲染中间到底经历了什么。如果你正在学习 AI SDK 的流式聊天架构这个项目的代码量足够小、结构足够清晰是理解前后端流式数据流的绝佳范例。一、项目概览一次聊天用到哪些技术chatbot-template 的技术栈可以概括为四层层次技术作用框架层Next.jsApp Router提供/api/chat流式接口路由与页面AI 层aiAI SDK Vercel AI Gateway统一接入多家模型流式输出交互层ai-sdk/react的useChat前端聊天状态管理与流式订阅UI 层shadcn/ui shadcn/typeset消息气泡、问卷、Markdown 排版项目结构非常扁平核心文件只有这几个app/api/chat/route.ts —— 流式聊天接口整个后端的心脏components/chat.tsx —— 前端聊天主组件useChat的调用处tools/index.ts —— 工具注册中心定义聊天机器人能做什么components/chat-message.tsx —— 消息渲染分发器把不同类型的零件交给对应组件依赖清单见 package.jsonAI 相关的关键依赖有ai核心 SDK、ai-sdk/reactReact 集成、ai-sdk/gatewayAI Gateway 接入。二、核心数据流一条消息的完整旅程理解这个项目最重要的是先建立一张数据流地图。一次聊天的完整链路如下前端发送 → Next.js 路由校验 →streamText调用模型 → 工具执行多轮循环 → UI 消息流 → 前端逐段渲染拆开来看前端用户在输入框提交消息components/prompt-form.tsx 调用sendMessageHTTP 请求发往/api/chat同时把当前选中的模型 ID 放在请求体里。路由层app/api/chat/route.ts 校验模型白名单、校验消息结构然后调用streamText发起流式生成。模型层streamText通过 AI Gateway 调用真实模型返回的不是完整文本而是一个流Stream——token 产生多少就推送多少。工具循环如果模型决定调用工具查仓库、搜索网页、问用户流中会插入工具调用片段工具执行完结果再喂回模型继续生成最多循环 5 步。前端渲染流被转换成 UI Message StreamuseChat按零件part粒度消费——文本块、工具调用块、引用来源块各自渲染成不同的 UI 组件。用户输入 │ ▼ prompt-form.tsx ──sendMessage──▶ /api/chat (route.ts) │ validateUIMessages ▼ streamText ──▶ AI Gateway ──▶ 模型 │ (tool call? 是 → 执行工具 → 回喂≤5步) ▼ toUIMessageStream (UI 消息流) ▼ useChat 订阅 ──▶ chat-message.tsx 按 part 分发渲染三、后端核心streamText流式输出是怎么写安全的app/api/chat/route.ts 只有 70 行却覆盖了生产级流式接口该做的所有防御值得逐点看1. 请求体容错先try/catch解析 JSON失败直接返回400不会让整个服务崩掉。2. 模型白名单模型列表集中在 lib/models.ts路由里用isModelAllowed(modelId)拦截用户传任意模型 ID 都没用。想换模型或加模型改这一个文件即可。3. 消息结构校验validateUIMessages在信任任何消息之前逐条校验消息和工具片段的结构是否合法——这是防注入、防脏数据的关键一步。4. 流式参数控制见 app/api/chat/route.ts参数作用stopWhen: isStepCount(5)限制模型↔工具最多循环 5 步防止无限递归烧钱maxOutputTokens: 8192限制单次输出长度控制成本上限abortSignal: req.signal用户关页面/停止生成时立即中断上游请求5. 流式响应封装最终通过createUIMessageStreamResponsetoUIMessageStream把原始 token 流封装为UI 消息流并开启sendSources: true——这样网页搜索的引用来源也能随流推给前端。 架构要点streamText的返回值是一个惰性流不是等模型说完再返回。这正是聊天机器人逐字蹦出来体验的技术基础。四、工具调用Tool Calling机器人的三种超能力工具定义在 tools/ 目录一个文件一个工具文件名就是模型看到的工具名。tools/index.ts 负责组合注册const baseTools { github_repo: githubRepo, ask_user: askUser } // 若当前模型支持再追加 web_search1️⃣ github_repo —— 服务端执行的典型工具tools/github_repo.ts 用zod定义了输入owner/name格式的仓库名和输出stars、forks、语言等的 Schemaexecute里调用 GitHub API 查公开数据并内置了5 秒超时 流中断信号合并保证工具不会卡死整个聊天流。2️⃣ web_search —— 各厂商原生搜索工具tools/web_search.ts 展示了工具随模型而变的写法OpenAI 模型用openai.tools.webSearch()Anthropic 模型用其对应的搜索工具。这种按模型 ID 前缀分发的策略让一套前端适配了不同厂商的原生能力。3️⃣ ask_user —— 唯一不在服务端执行的工具tools/ask_user.ts 定义了输入若干问题 每题恰好 3 个选项和输出问答对但没有execute函数——因为它的执行者是屏幕前的用户。这个设计是全文最巧妙的部分下一节细说。五、前端渲染消息 parts 与状态机思维AI SDK 里一条助手消息不是纯文本而是一组有序的类型化零件parts。components/chat-message.tsx 的核心就是一个switch (part.type)分发器part 类型渲染组件界面效果texttext-part.tsxMarkdown 富文本react-markdown typesettool-github_repogithub-repo-part.tsx先转圈 Looking up…再显示 stars/forks 统计条tool-web_searchweb-search-part.tsxSearching the web… → Searched the webtool-ask_userask-user-part.tsx已回答的问答内联展示source-urlsources-part.tsx流结束后聚合为 Searched N websites 抽屉更有意思的是每个工具零件都实现了状态机input-streaming → input-available → output-available └→ output-error以 web-search-part.tsx 为例流刚开始推送工具输入时显示正在搜索…执行完切换为已搜索出错则显示错误文案。一个组件四种状态随流自动演进——这就是流式 UI 与普通轮询 UI 的本质区别。六、Human-in-the-loopask_user 问卷如何打断又续传对话这是 chatbot-template 最有教学价值的功能当用户的问题含糊不清时模型会主动发起问卷等用户答完再继续。实现分三步第一步模型发起提问模型调用ask_user工具流中插入tool-ask_user零件。components/chat.tsx 检测到存在状态为input-streaming或input-available的待答问题就在滚动区底部吸顶弹出问卷卡片 components/question-card.tsx——用户可点选选项也可自由输入。第二步用户作答提交后调用addToolOutput见 components/chat.tsx把答案作为工具输出回传。因为ask_user没有服务端execute用户的操作就是那次执行。第三步自动续传components/chat.tsx 中有一个关键配置sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls它让前端在最后一条助手消息已完成且带工具调用时自动重发请求把工具结果回喂给模型。用户答完问卷对话无需任何手动操作就继续流式生成。 总结这个模式省略 execute 前端自动重发 人在回路Human-in-the-loop。这是 AI SDK 里把用户变成工具执行器的标准范式。七、快速上手本地运行 chatbot-template三步跑起来# 1. 安装依赖 pnpm install # 2. 配置 AI Gateway 凭证二选一 vercel link vercel env pull # 从已链接的 Vercel 项目拉取 OIDC token # 或在 Vercel 控制台 AI Gateway → API Keys 创建密钥写入 .env.local 的 AI_GATEWAY_API_KEY # 3. 启动 pnpm dev⚠️安全提醒详见 README.md 的 Security 章节/api/chat是公开无鉴权接口每个请求都消耗你的 AI Gateway 额度。上真实流量前务必加限流、设置 Gateway 消费上限、或加登录鉴权。八、如何扩展给自己加一个新工具想加工具比如查天气只需两步类型系统全程护航新建 tools/ 下weather.ts用tool()导出描述、inputSchema和execute再到 tools/index.ts 注册在 components/parts/ 加一个零件组件并在 chat-message.tsx 加一个case tool-weather。由于消息类型通过InferUITools从工具定义自动推导你在零件组件里能拿到完整类型提示——改错字段名直接编译报错而不是运行时悄悄变成undefined。总结chatbot-template 用极小的代码量完整演示了一个现代流式聊天机器人的架构骨架后端streamText 流式响应封装 白名单/限步/限 token/可中断构成安全的流式接口范式app/api/chat/route.ts工具层一文件一工具、Schema 描述输入输出、execute与人在回路分离tools/前端useChat消费 UI 消息流parts 状态机驱动渐进式 UIcomponents/chat-message.tsx范式省略executesendAutomaticallyWhen实现 Human-in-the-loop 问卷交互tools/ask_user.ts如果你想给自己的产品加一个 AI 聊天能力直接以它为起点改造是最短的路径。赞分享【免费下载链接】chatbot-templateA minimal chatbot template built with Next.js, AI SDK, shadcn/ui, shadcn/react, shadcn/typeset. It runs on the Vercel AI Gateway.项目地址https://gitcode.com/gh_mirrors/chatbo/chatbot-template点击查看免费下载相关推荐揭秘Awesome ChatGPT深入理解AI聊天机器人核心架构与实现原理揭秘Awesome ChatGPT深入理解AI聊天机器人核心架构与实现原理 在人工智能快速发展的今天ChatGPT作为最受欢迎的AI聊天机器人之一其背后的SonataAdminBundle 与工作流集成实现复杂业务状态管理SonataAdminBundle 与工作流集成实现复杂业务状态管理 SonataAdminBundle 作为 Symfony 的强大管理后台生成器提供了丰10分钟上手现代AI聊天机器人GitHub_Trending/ai/ai-chatbot架构全解析10分钟上手现代AI聊天机器人GitHub_Trending/ai/ai chatbot架构全解析 你是否还在为构建AI聊天机器人时的技术选型而烦恼是否想快AI 应用前端后端交互助手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考