从零构建一个全栈AI应用：Next.js + FastAPI + OpenAI API

💡 为什么写这篇文章？

很多开发者希望构建一个能“聊天、问答、调用AI能力”的完整应用，但在前端、后端、模型接口之间打通时，常常踩坑。

今天这篇文章将手把手教你如何从零构建一个 AI 全栈应用：

• 前端用 Next.js 构建交互界面
• 后端用 FastAPI 管理 API 和权限
• 模型调用使用 OpenAI API（或其他 LLM API）

目标是让你掌握前后端分离 + LLM 调用 + API 代理 + UI 交互的整个流程。

---

🏗 项目结构概览

ai-app/
├── backend/              # FastAPI 服务
│   └── main.py
├── frontend/             # Next.js 页面
│   └── pages/
│       └── index.tsx
├── .env
└── README.md

---

一、准备工作

✅ 技术选型

层级	技术栈	用途
前端	Next.js + Tailwind	搭建聊天界面
后端	FastAPI	提供统一 API 接口
LLM 接口	OpenAI API	提供模型回答能力

✅ 安装依赖

后端环境

cd backend
pip install fastapi uvicorn requests python-dotenv

前端环境

cd frontend
npx create-next-app@latest
npm install axios
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

---

二、构建后端 API（FastAPI）

🔐 文件：backend/main.py

from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
import requests, os
from dotenv import load_dotenvload_dotenv()
app = FastAPI()# 允许前端跨域访问
app.add_middleware(CORSMiddleware,allow_origins=["*"], allow_credentials=True,allow_methods=["*"],allow_headers=["*"],
)OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")@app.post("/chat")
async def chat(req: Request):body = await req.json()user_input = body.get("message", "")headers = {"Authorization": f"Bearer {OPENAI_API_KEY}","Content-Type": "application/json"}data = {"model": "gpt-3.5-turbo","messages": [{"role": "user", "content": user_input}]}response = requests.post("https://api.openai.com/v1/chat/completions", headers=headers, json=data)result = response.json()reply = result["choices"][0]["message"]["content"]return {"reply": reply}

🌿 .env 文件

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

🚀 启动服务

uvicorn main:app --reload --port 8000

---

三、构建前端页面（Next.js）

🎨 配置 TailwindCSS（略）

参考官网：https://tailwindcss.com/docs/guides/nextjs

📄 文件：frontend/pages/index.tsx

import { useState } from "react";
import axios from "axios";export default function Home() {const [message, setMessage] = useState("");const [reply, setReply] = useState("");const handleSend = async () => {const res = await axios.post("http://localhost:8000/chat", { message });setReply(res.data.reply);};return (<main className="min-h-screen p-10 bg-gray-50"><div className="max-w-2xl mx-auto"><h1 className="text-2xl font-bold mb-4">💬 AI Chat Assistant</h1><textareavalue={message}onChange={(e) => setMessage(e.target.value)}placeholder="输入你的问题..."className="w-full p-4 rounded border"rows={5}/><buttononClick={handleSend}className="mt-4 px-4 py-2 bg-blue-600 text-white rounded">发送</button>{reply && (<div className="mt-6 bg-white p-4 rounded shadow"><strong>AI 回复：</strong><p className="mt-2 whitespace-pre-wrap">{reply}</p></div>)}</div></main>);
}

---

四、前后端联调

确保：

1. 后端 FastAPI 在 localhost:8000
2. 前端 Next.js 项目运行在 localhost:3000
3. CORS 跨域设置正确，前端使用 axios.post('http://localhost:8000/chat')

启动服务

# 后端
cd backend && uvicorn main:app --reload# 前端
cd frontend && npm run dev

访问 http://localhost:3000，即可看到聊天页面！

---

五、扩展方向（建议）

你已经构建了一个完整的 AI 全栈应用，下一步可以考虑：

📌 加入上下文记忆

将每轮聊天记录维护在前端 messages 数组中，一起发给后端。

📌 多轮聊天记录存储（MongoDB）

将历史对话存入数据库，实现“对话历史”、“回顾功能”。

📌 接入企业知识库（RAG）

结合向量数据库（如 FAISS、Qdrant）+ 文本 embedding，实现个性化问答。

📌 支持语音输入、TTS 语音回复

用 Web Speech API + Edge TTS 创建语音 AI 助手。

---

六、踩坑记录

问题	解决方案
跨域失败（CORS）	FastAPI 添加 allow_origins=["*"]
OpenAI 返回错误	检查 API key 是否正确，模型是否支持聊天格式
Axios 报错 Network Error	后端服务未启动 / 地址不正确 / 端口冲突
Next.js SSR 与 API 混淆	前端直接请求后端接口，避免 API route 混用

七、项目优化建议：让你的 AI 应用更好用、更像产品

现在你的全栈 AI 应用已经可以对话了，但距离一个“真正能用”的产品，还有以下几个重要提升点：

---

🧠 1. 多轮上下文记忆（Chat History）

当前每次只发送用户一句话，没有上下文，模型不知道你在问什么。

✅ 解决方案：

维护一个 messages 数组，结构如下：

const messages = [{ role: "user", content: "你是谁？" },{ role: "assistant", content: "我是一个AI助手。" },{ role: "user", content: "你能做什么？" },
];

并将 messages 整体发给后端，模型就能理解上下文。

---

🔐 2. 接口鉴权（Token 验证）

当前 FastAPI 是开放的，任何人都能访问。

✅ 解决方案：

• 在请求中添加自定义 Authorization header
• 后端校验合法性（可以设定 JWT token 或简单密码）
• 避免 OpenAI API 被滥用

---

💾 3. 聊天记录存储（MongoDB / SQLite）

为了实现“对话记录查看”、“历史导出”、“用户画像”功能，可以接入数据库。

✅ 示例结构：

{"user_id": "abc123","timestamp": "2025-04-09T10:00:00Z","messages": [{ "role": "user", "content": "你好" },{ "role": "assistant", "content": "你好！请问有什么可以帮你？" }]
}

---

🎙 4. 加入语音输入输出（Web Speech API + Edge TTS）

✅ 实现方向：

• 浏览器原生 SpeechRecognition（Chrome）识别语音
• 语音识别后转文本发给后端
• AI 回复后，用 Edge TTS 合成语音播放

这就是一个真正意义上的语音助手。

---

🎨 5. UI 美化 + Loading 状态优化

• 使用 Tailwind + Shadcn/ui 构建现代组件（如对话框、按钮、输入框）
• 加入 loading 动画（如 Typing 动效）
• 支持 markdown 渲染（渲染代码、公式、链接）

---

八、实战部署：让你的 AI 应用上线可用

接下来把这个项目部署上线，分享给朋友或部署到企业内部。

---

🚀 1. 部署 FastAPI 到服务器（Gunicorn + Nginx）

pip install gunicorn uvicorn
gunicorn main:app -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

使用 Nginx 反向代理到端口 8000，设置 HTTPS 证书。

---

🌐 2. 部署 Next.js 应用到 Vercel / Docker

✅ 方法一：Vercel 免费部署

vercel login
vercel deploy

✅ 方法二：Docker 本地部署

创建 Dockerfile：

FROM node:18
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

---

🌍 3. 前后端通信环境变量

Vercel 环境变量设为：

NEXT_PUBLIC_API_URL=https://your-backend-domain.com

---

九、完整源码目录结构参考

ai-assistant-app/
├── backend/                         # FastAPI 后端
│   ├── main.py                      # 主 API 服务
│   └── .env                         # API 密钥配置
├── frontend/                        # Next.js 前端
│   ├── pages/
│   │   └── index.tsx                # 主页面
│   ├── components/                  # 可拆分组件（ChatBox, MessageBubble）
│   ├── public/                      # 静态资源
│   ├── styles/                      # 全局样式
│   └── tailwind.config.js
├── docker-compose.yml              # 可选：一键部署配置
├── README.md

---

十、进阶建议与未来趋势

🔄 接入本地模型（替代 OpenAI）

想要离线、私有化部署？你可以替换为：

• 🌐 vLLM + LLaMA3 / Qwen
• 🤗 transformers + AutoModelForCausalLM
• ✨ OpenRouter 统一调用多模型 API

只需修改 FastAPI 中调用模型的部分逻辑即可。

---

🤖 让 AI 应用变成插件系统（多工具调用）

支持 AI 自动调用搜索、数据库、发送邮件等“工具”：

• 构建多工具 agent：LangChain / OpenAgents
• 添加功能：获取天气 / 查航班 / 调用企业 API
• 变成你的“AI 秘书”甚至“AI 员工”

---

🧬 构建 AI Copilot：面向业务的智能助手

例如：

• 🧾 财务 Copilot：读取发票、报销记录、汇总财报
• 📖 教育 Copilot：答疑解惑 + 多模态 PPT 生成
• 🧠 法律 Copilot：合同审核 + 法条查找 + GPT 生成解读

---

🔚 结语：AI 全栈应用，不只是聊天机器人

你现在拥有的，不只是一个聊天前后端，而是一个灵活的 AI 架构基础：

• 可以换模型、接数据库、加插件
• 可以本地部署、远程扩展、加智能记忆
• 可以向企业级 AI Copilot 逐步演化

这是 2025 年最值得学习的技能之一 —— “用代码连接人和大模型”。