从零构建一个全栈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_dotenv

load_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>
        <textarea
          value={message}
          onChange={(e) => setMessage(e.target.value)}
          placeholder="输入你的问题..."
          className="w-full p-4 rounded border"
          rows={5}
        />
        <button
          onClick={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>
  );
}

四、前后端联调

确保：

后端 FastAPI 在 localhost:8000
前端 Next.js 项目运行在 localhost:3000
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