使用 Next.js 构建 Web 聊天应用

​

示例项目

• GitHub: examples/web-chat-nextjs
• 仓库本地路径： examples/web-chat-nextjs

​

此应用的功能

• • 获取可用模型 GET /v1/models
• • 提交聊天轮次 POST /v1/responses
• 将 API 密钥保留在服务器上
• 为真实产品提供简单的起点，避免 OAuth 带来的复杂性

​

关键文件

• app/api/models/route.ts
• app/api/responses/route.ts
• app/components/ChatClient.tsx
• lib/gateway.ts

​

采用此结构的原因

​

1. 浏览器不会直接调用 Phaseo

• 在服务器端管理机密信息
• 集中管理请求标头和请求正文
• 方便日后添加身份验证、请求速率限制或日志记录

​

2. 将模型发现与生成分开

• 一个用于列出模型的路由
• 一个用于执行聊天请求的路由

​

3. UI 只管理交互状态

• 输入状态
• 加载状态
• 错误展示
• 渲染的消息

​

前置条件

• • Node.js 和受支持的包管理器
• Phaseo API 密钥

​

运行示例

cd examples/web-chat-nextjs
npm install
cp .env.example .env.local

cd examples/web-chat-nextjs
pnpm install
cp .env.example .env.local

cd examples/web-chat-nextjs
yarn install
cp .env.example .env.local

cd examples/web-chat-nextjs
bun install
cp .env.example .env.local

• PHASEO_API_KEY
• NEXT_PUBLIC_GATEWAY_URL

npm run dev

pnpm dev

yarn dev

bun run dev

​

检查结果

• 模型选择器从服务器路由加载模型。
• 发送消息后会收到一条助手回复。
• 浏览器网络面板不会暴露 PHASEO_API_KEY.
• Gateway 请求失败时，界面会显示有用的错误状态。

​

根据需要修改应用

• 将默认模型改为计划用于生产环境的模型
• 如果用户体验需要逐个显示 token，则添加流式传输
• 如果应用之后支持多个用户，再添加身份验证
• 如果希望使用更高层级的客户端，之后可将服务器路由的内部实现替换为 TypeScript SDK

​

何时选择其他起点

• 如果需要脚本或后端连通性测试，而不是 UI，请使用 Node 快速入门。
• 如果首次集成要运行在 worker、CLI 或后端服务中，请使用 Python 快速入门。

​

相关指南

• 迷你应用起步提示词
• 示例
• 快速入门