
文章目录
- 前言
- [一、Python 3环境搭建](#一、Python 3环境搭建)
-
- [1.1 Python 3版本选择与下载](#1.1 Python 3版本选择与下载)
-
- [1.1.1 官方下载渠道](#1.1.1 官方下载渠道)
- [1.1.2 下载注意事项](#1.1.2 下载注意事项)
- [1.2 Python 3安装与环境配置](#1.2 Python 3安装与环境配置)
-
- [1.2.1 Windows系统安装步骤](#1.2.1 Windows系统安装步骤)
- [1.2.2 Mac系统安装步骤](#1.2.2 Mac系统安装步骤)
- [1.2.3 Linux系统配置(Ubuntu/CentOS)](#1.2.3 Linux系统配置(Ubuntu/CentOS))
- [1.3 环境验证与pip源优化](#1.3 环境验证与pip源优化)
-
- [1.3.1 环境验证](#1.3.1 环境验证)
- [1.3.2 pip国内源配置(解决安装依赖慢、失败问题)](#1.3.2 pip国内源配置(解决安装依赖慢、失败问题))
- [1.4 Python虚拟环境创建(可选,推荐)](#1.4 Python虚拟环境创建(可选,推荐))
- 二、Vue3环境搭建
-
- [2.1 Node.js环境安装(Vue3运行基础)](#2.1 Node.js环境安装(Vue3运行基础))
-
- [2.1.1 Node.js版本选择](#2.1.1 Node.js版本选择)
- [2.1.2 下载与安装](#2.1.2 下载与安装)
- [2.1.3 Node.js环境验证](#2.1.3 Node.js环境验证)
- [2.2 npm镜像源配置](#2.2 npm镜像源配置)
- [2.3 Vue3环境初始化](#2.3 Vue3环境初始化)
-
- [2.3.1 安装Vue CLI与Vite(二选一,推荐Vite)](#2.3.1 安装Vue CLI与Vite(二选一,推荐Vite))
- [2.3.2 验证Vue环境](#2.3.2 验证Vue环境)
- 三、Python开发工具下载
-
- [3.1 PyCharm下载与安装](#3.1 PyCharm下载与安装)
-
- [3.1.1 官方下载](#3.1.1 官方下载)
- [3.1.2 安装步骤](#3.1.2 安装步骤)
- [3.2 PyCharm基础配置](#3.2 PyCharm基础配置)
-
- [3.2.1 配置Python解释器](#3.2.1 配置Python解释器)
- [3.2.2 必备插件安装](#3.2.2 必备插件安装)
- [3.3 备选开发工具(VSCode)](#3.3 备选开发工具(VSCode))
- 四、Python项目创建与FastAPI依赖安装
-
- [4.1 Python后端项目创建](#4.1 Python后端项目创建)
- [4.2 项目核心依赖安装](#4.2 项目核心依赖安装)
- [4.3 项目基础结构与启动代码](#4.3 项目基础结构与启动代码)
-
- [4.3.1 基础项目结构](#4.3.1 基础项目结构)
- [4.3.2 主启动文件代码](#4.3.2 主启动文件代码)
- [4.3.3 启动后端服务验证](#4.3.3 启动后端服务验证)
- 五、Vue3项目创建与基础配置
-
- [5.1 Vue3项目创建(Vite方式)](#5.1 Vue3项目创建(Vite方式))
- [5.2 前端依赖安装](#5.2 前端依赖安装)
- [5.3 Vue3项目基础配置](#5.3 Vue3项目基础配置)
-
- [5.3.1 配置跨域代理](#5.3.1 配置跨域代理)
- [5.3.2 项目入口配置](#5.3.2 项目入口配置)
- [5.4 前端项目启动验证](#5.4 前端项目启动验证)
- 六、Vue3智能交互聊天页面开发
-
- [6.1 前端路由配置](#6.1 前端路由配置)
- [6.2 Axios请求封装](#6.2 Axios请求封装)
- [6.3 用户登录页面开发](#6.3 用户登录页面开发)
- [6.4 智能聊天页面开发](#6.4 智能聊天页面开发)
- 七、FastAPI构建大模型交互+登录鉴权
-
- [7.1 登录鉴权模块开发](#7.1 登录鉴权模块开发)
-
- [7.1.1 工具类封装(密码加密、JWT生成)](#7.1.1 工具类封装(密码加密、JWT生成))
- [7.1.2 登录接口开发](#7.1.2 登录接口开发)
- [7.2 大模型对接扩展(替换真实模型)](#7.2 大模型对接扩展(替换真实模型))
- 八、前后端项目分层规范
-
- [8.1 后端Python项目分层](#8.1 后端Python项目分层)
-
- [8.1.1 最终分层结构](#8.1.1 最终分层结构)
- [8.1.2 分层说明](#8.1.2 分层说明)
- [8.2 前端Vue3项目分层](#8.2 前端Vue3项目分层)
-
- [8.2.1 最终分层结构](#8.2.1 最终分层结构)
- [8.2.2 分层说明](#8.2.2 分层说明)
- [8.3 分层开发优势](#8.3 分层开发优势)
- 九、总结
- 十、项目完整运行与前后端联调手册
-
- [10.1 后端服务启动流程](#10.1 后端服务启动流程)
-
- [10.1.1 启动前检查](#10.1.1 启动前检查)
- [10.1.2 启动后端服务](#10.1.2 启动后端服务)
- [10.2 前端服务启动流程](#10.2 前端服务启动流程)
-
- [10.2.1 启动前检查](#10.2.1 启动前检查)
- [10.2.2 启动前端项目](#10.2.2 启动前端项目)
- [10.3 全流程联调测试](#10.3 全流程联调测试)
- 十一、项目常见问题与解决方案
-
- [11.1 后端常见问题](#11.1 后端常见问题)
-
- [11.1.1 FastAPI启动报错,端口被占用](#11.1.1 FastAPI启动报错,端口被占用)
- [11.1.2 导入依赖报错,模块不存在](#11.1.2 导入依赖报错,模块不存在)
- [11.1.3 跨域报错,前端无法请求后端接口](#11.1.3 跨域报错,前端无法请求后端接口)
- [11.1.4 JWT鉴权失效,提示无效token](#11.1.4 JWT鉴权失效,提示无效token)
- [11.2 前端常见问题](#11.2 前端常见问题)
-
- [11.2.1 npm install安装依赖失败、速度慢](#11.2.1 npm install安装依赖失败、速度慢)
- [11.2.2 前端页面无法加载,控制台报错](#11.2.2 前端页面无法加载,控制台报错)
- [11.2.3 聊天消息无法滚动到底部](#11.2.3 聊天消息无法滚动到底部)
- 十二、项目功能扩展与进阶优化方向
-
- [12.1 后端功能扩展](#12.1 后端功能扩展)
- [12.2 前端功能扩展](#12.2 前端功能扩展)
- [12.3 工程化优化](#12.3 工程化优化)
- 十三、全文总结与学习建议
-
- [AI 大模型基础教程目录大纲](#AI 大模型基础教程目录大纲)
前言
在AI大模型全面普及的当下,智能聊天系统早已从单一的文本对话,演变为全栈技术落地的核心实战项目,也是初级开发者入门全栈开发、后端工程师对接前端界面、前端开发者对接AI接口、运维人员部署全栈项目、AI爱好者落地模型应用的绝佳练手案例。想要搭建一套可运行、可扩展、具备登录鉴权、前后端分离的智能聊天系统,选择轻量化、高性能的技术栈至关重要,而FastAPI+Vue3的组合,凭借上手快、性能强、易部署、生态完善的优势,成为全栈智能聊天系统开发的首选方案。
FastAPI作为Python生态高性能Web框架,自带接口文档、数据校验、异步支持、登录鉴权能力,能够快速搭建稳定可靠的后端服务,完美对接各类大模型接口,实现智能对话逻辑;Vue3作为前端主流框架,搭配现代化工程化工具,能够快速搭建响应式、交互流畅的聊天页面,实现消息实时渲染、用户交互、状态管理,前后端分离架构也便于后期维护、扩展与部署。
市面上多数智能聊天系统教程,要么只侧重前端页面实现、缺失后端核心逻辑,要么只讲解后端接口、无完整前端交互,要么代码无注释、步骤碎片化,无法满足全岗位学习者从零上手的需求。针对这一痛点,本文专为初级/中级开发者、后端、前端、运维、AI爱好者打造,全程采用手把手实操教学,从环境搭建、项目创建,到前后端核心代码编写、功能实现、项目分层规范,全覆盖无死角,所有代码均可直接复制运行,且附带逐行详细注释,无晦涩理论、无跳跃步骤,即便是零基础开发者,也能顺利完成整套系统搭建。
在开始实战前,建议读者准备好Windows/Mac/Linux任一操作系统,全程无需付费工具、无需复杂配置,依托开源免费工具与框架,即可完成整套系统开发,接下来我们正式开启全栈实战之旅。
一、Python 3环境搭建
作为系统后端开发的基础,Python 3环境的稳定搭建是后续FastAPI后端服务开发、大模型对接的前提,本文选用Python
3.9及以上稳定版本,适配全平台、兼容所有依赖库,全程步骤清晰、无坑点,新手可一步步跟着完成。
1.1 Python 3版本选择与下载
智能聊天系统后端基于FastAPI开发,推荐选用Python 3.9 / 3.10 /
3.11三个稳定版本,兼容性最佳、生态最完善,避免使用过高或过低版本导致依赖安装失败。
1.1.1 官方下载渠道
直接访问Python官方下载地址:https://www.python.org/downloads/,根据自身操作系统选择对应安装包:
Windows系统:选择Windows Installer (64-bit)安装包,优先3.10版本
Mac系统:选择macOS 64-bit installer,Intel芯片与Apple Silicon芯片均兼容
Linux系统:自带Python 3,可直接跳过下载,仅需配置环境变量
1.1.2 下载注意事项
务必下载64位版本,32位版本存在内存限制、依赖兼容问题,无法支撑大模型对接与高并发对话请求;同时不要下载带debug、rc标识的测试版本,优先选择正式稳定版。
1.2 Python 3安装与环境配置
1.2.1 Windows系统安装步骤
双击下载好的exe安装包,务必勾选底部"Add Python.exe to PATH"(自动配置环境变量,省去手动配置麻烦)
选择"Customize installation"自定义安装,点击Next
勾选所有可选功能:Documentation、pip、tcl/tk、Python test suite、py launcher,点击Next
勾选"Install for all users",自定义安装路径(建议非C盘,如D:Python310)
点击Install,等待安装完成,弹出Setup was successful即安装成功
1.2.2 Mac系统安装步骤
双击下载的pkg安装包,全程点击继续、同意协议
选择安装磁盘(默认系统盘即可),输入电脑密码授权安装
等待安装完成,Mac系统会自动配置环境变量,无需手动操作
1.2.3 Linux系统配置(Ubuntu/CentOS)
Linux系统默认自带Python 3,执行以下命令检查版本、安装pip:
shell
# 检查Python3版本
python3 --version
# 安装pip3
sudo apt install python3-pip # Ubuntu/Debian系统
sudo yum install python3-pip # CentOS系统
1.3 环境验证与pip源优化
1.3.1 环境验证
打开终端(Windows为CMD/PowerShell,Mac/Linux为Terminal),执行以下命令,出现对应版本号即环境搭建成功:
shell
# 检查Python版本
python --version # Windows
python3 --version # Mac/Linux
# 检查pip版本
pip --version # Windows
pip3 --version # Mac/Linux
1.3.2 pip国内源配置(解决安装依赖慢、失败问题)
Python默认pip源为国外服务器,安装依赖速度极慢、极易报错,需配置国内阿里云镜像源,提升依赖安装速度:
shell
# 临时配置(单次生效)
pip install 库名 -i https://mirrors.aliyun.com/pypi/simple/
# 永久配置(推荐)
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
1.4 Python虚拟环境创建(可选,推荐)
为避免不同项目依赖冲突,推荐创建独立虚拟环境,专门用于本次智能聊天系统开发:
shell
# 安装虚拟环境工具
pip install virtualenv
# 创建项目文件夹,进入文件夹
mkdir fastapi-vue3-chat
cd fastapi-vue3-chat
# 创建虚拟环境
virtualenv venv
# 激活虚拟环境
# Windows系统
venvScriptsactivate
# Mac/Linux系统
source venv/bin/activate
激活成功后,终端前方会出现(venv)标识,后续所有后端依赖均安装在此虚拟环境中,不影响全局Python环境。
二、Vue3环境搭建
Vue3作为前端核心框架,需依托Node.js环境运行,搭建流程简单、无复杂配置,全程基于官方推荐工具,实现现代化前端工程化开发,适配智能聊天页面的响应式交互、实时消息渲染需求。
2.1 Node.js环境安装(Vue3运行基础)
2.1.1 Node.js版本选择
Vue3需依托Node.js 16.0及以上版本,推荐选用Node.js 18.18 LTS长期稳定版,兼容Vue3、Vite等所有前端工具,稳定性最佳。
2.1.2 下载与安装
访问Node.js官方下载地址:https://nodejs.org/dist/latest-v18.x/,根据系统选择对应安装包:
Windows:选择node-v18.18.0-x64.msi
Mac:选择node-v18.18.0.pkg
Linux:选择node-v18.18.0-linux-x64.tar.xz
安装全程默认下一步即可,安装包会自动配置Node.js与npm环境变量,无需手动操作。
2.1.3 Node.js环境验证
打开新终端,执行以下命令,出现版本号即安装成功:
shell
# 检查Node.js版本
node --version
# 检查npm版本
npm --version
2.2 npm镜像源配置
npm默认国外源,下载前端依赖速度极慢,配置淘宝npm镜像源,提升依赖安装速度:
shell
# 配置淘宝镜像源
npm config set registry https://registry.npmmirror.com/
# 验证镜像源
npm config get registry
2.3 Vue3环境初始化
2.3.1 安装Vue CLI与Vite(二选一,推荐Vite)
Vue3支持Vue CLI与Vite两种工程化工具,Vite启动速度更快、打包效率更高,更适合智能聊天系统这类轻量化前端项目,优先安装Vite:
shell
# 全局安装Vite
npm install -g vite
# 全局安装Vue CLI(备选)
npm install -g @vue/cli
2.3.2 验证Vue环境
shell
# 验证Vite
vite --version
# 验证Vue CLI
vue --version
至此,Vue3全套环境搭建完成,可直接创建Vue3前端项目,后续无需额外配置环境。
三、Python开发工具下载
Python开发推荐使用PyCharm Community
Edition(社区免费版),功能齐全、适配FastAPI开发、代码提示完善、调试便捷,完全满足本次智能聊天系统后端开发需求,且免费开源、无需付费激活。
3.1 PyCharm下载与安装
3.1.1 官方下载
访问JetBrains官方下载地址:https://www.jetbrains.com/pycharm/download/,选择Community(社区版),根据系统下载对应安装包。
3.1.2 安装步骤
双击安装包,点击Next,自定义安装路径(建议非C盘)
勾选"Create Desktop Shortcut"、"Add launchers dir to the PATH"、"Associate .py files"
点击Install,等待安装完成,重启电脑生效
3.2 PyCharm基础配置
3.2.1 配置Python解释器
打开PyCharm,点击File → New Project,创建新项目
选择"Previously configured interpreter",点击Add
选择Virtualenv Environment,找到之前创建的虚拟环境中的python.exe(Windows)或python(Mac/Linux)
点击OK,完成解释器配置,后续开发自动使用虚拟环境
3.2.2 必备插件安装
点击File → Settings → Plugins,搜索并安装以下插件,提升开发效率:
FastAPI Helper:FastAPI专属插件,支持路由跳转、接口调试
Rainbow Brackets:彩色括号,方便代码阅读
Translation:翻译插件,方便理解代码注释
3.3 备选开发工具(VSCode)
若习惯轻量级工具,可下载VSCode:https://code.visualstudio.com/,安装Python、Pylance、FastAPI Snippets插件,同样可完成后端开发,本文以PyCharm为例讲解。
四、Python项目创建与FastAPI依赖安装
本节正式创建Python后端项目,搭建FastAPI基础服务,安装登录鉴权、大模型对接、跨域处理所需依赖,编写基础启动代码,为后续智能聊天接口、登录接口开发打好基础。
4.1 Python后端项目创建
打开PyCharm,点击File → New Project
设置项目名称:fastapi_chat_backend,选择项目存储路径
选择配置好的虚拟Python解释器,取消勾选Create a main.py welcome script
点击Create,完成后端项目创建
4.2 项目核心依赖安装
在PyCharm底部终端中,执行以下命令,安装FastAPI及全套所需依赖,所有依赖均带详细作用说明:
shell
# 1. 安装FastAPI核心框架
pip install fastapi
# 2. 安装Uvicorn ASGI服务器,用于启动后端服务
pip install "uvicorn[standard]"
# 3. 安装跨域依赖,解决前后端联调跨域问题
pip install python-multipart
# 4. 安装JWT登录鉴权依赖,实现用户登录、token校验
pip install pyjwt
# 5. 安装加密依赖,实现用户密码加密存储
pip install passlib[bcrypt]
# 6. 安装请求依赖,对接大模型接口
pip install requests
4.3 项目基础结构与启动代码
4.3.1 基础项目结构
在项目根目录下,创建主启动文件
main.py,编写FastAPI服务启动代码,自带跨域配置、基础路由,保证服务可正常运行。
4.3.2 主启动文件代码
python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
FastAPI智能聊天系统后端启动文件
功能:创建应用实例、配置跨域、注册路由、启动服务
"""
# 导入FastAPI核心类
from fastapi import FastAPI
# 导入跨域中间件
from fastapi.middleware.cors import CORSMiddleware
# 1. 创建FastAPI应用实例
app = FastAPI(
title="智能聊天系统后端API",
description="基于FastAPI+大模型的智能聊天后端服务",
version="1.0.0"
)
# 2. 配置跨域,解决前后端联调跨域问题
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # 允许所有域名访问,生产环境可改为指定前端域名
allow_credentials=True,
allow_methods=["*"], # 允许所有请求方法
allow_headers=["*"], # 允许所有请求头
)
# 3. 基础测试接口,验证服务是否正常
@app.get("/", summary="系统健康检查接口")
def health_check():
"""
健康检查接口
用于验证后端服务是否正常启动
"""
return {
"code": 200,
"message": "智能聊天系统后端服务启动成功",
"data": None
}
# 4. 启动服务入口
if __name__ == "__main__":
import uvicorn
# 启动服务,本地访问地址:http://127.0.0.1:8000
# API文档地址:http://127.0.0.1:8000/docs
uvicorn.run(
app="main:app",
host="127.0.0.1",
port=8000,
reload=True # 开发模式,代码修改自动重启服务
)
4.3.3 启动后端服务验证
直接运行main.py文件,终端出现以下信息即服务启动成功:
服务访问地址:http://127.0.0.1:8000
交互式API文档地址:http://127.0.0.1:8000/docs(可在线调试接口)
五、Vue3项目创建与基础配置
本节基于Vite创建Vue3前端项目,配置基础依赖、跨域代理、项目结构,打造适配智能聊天的前端工程,实现与后端的无缝联调。
5.1 Vue3项目创建(Vite方式)
-
打开终端,进入之前创建的全栈项目文件夹,执行创建命令
-
输入项目名称:vue3_chat_frontend,框架选择Vue,语言选择JavaScript
shell
# 创建Vite+Vue3项目
npm create vite@latest
# 按提示操作
# ? Project name: vue3_chat_frontend
# ? Select a framework: Vue
# ? Select a variant: JavaScript
# 进入项目目录
cd vue3_chat_frontend
5.2 前端依赖安装
安装前端开发所需核心依赖,包括路由、请求库、UI组件、状态管理,适配聊天页面交互、登录状态管理、接口请求需求:
shell
# 安装项目基础依赖
npm install
# 1. 安装axios,用于前后端接口请求
npm install axios
# 2. 安装Vue Router,实现页面路由跳转(登录页/聊天页)
npm install vue-router@4
# 3. 安装Element Plus,Vue3 UI组件库,快速搭建聊天页面
npm install element-plus
# 4. 安装pinia,状态管理,存储用户登录状态、聊天消息
npm install pinia
5.3 Vue3项目基础配置
5.3.1 配置跨域代理
在项目根目录创建vite.config.js,配置后端接口代理,解决前端请求后端跨域问题:
javascript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
// https://vitejs.dev/config/
export default defineConfig({
plugins: [vue()],
// 配置前端服务
server: {
host: '127.0.0.1',
port: 3000, // 前端服务端口
open: true, // 启动后自动打开浏览器
// 跨域代理配置
proxy: {
'/api': {
target: 'http://127.0.0.1:8000', // 后端服务地址
changeOrigin: true,
rewrite: (path) => path.replace(/^/api/, '')
}
}
}
})
5.3.2 项目入口配置
修改src/main.js,全局引入Element Plus、路由、状态管理,实现全局组件注册:
javascript
import { createApp } from 'vue'
// 引入根组件
import App from './App.vue'
// 引入路由
import router from './router'
// 引入状态管理
import { createPinia } from 'pinia'
// 引入Element Plus
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
// 创建应用实例
const app = createApp(App)
// 注册全局插件
app.use(createPinia())
app.use(router)
app.use(ElementPlus)
// 挂载应用
app.mount('#app')
5.4 前端项目启动验证
shell
# 启动前端项目
npm run dev
启动成功后,浏览器自动打开前端页面,访问地址:http://127.0.0.1:3000,出现Vue3默认页面即项目创建成功。
六、Vue3智能交互聊天页面开发
本节开发智能聊天系统前端核心页面:用户登录页面 与智能聊天页面,实现响应式布局、消息实时渲染、输入发送、登录校验、路由拦截等完整交互,代码简洁、注释详尽,适配各类屏幕尺寸。
6.1 前端路由配置
在src文件夹下创建router文件夹,新建index.js,配置登录页、聊天页路由,实现登录状态拦截:
javascript
// 引入路由核心
import { createRouter, createWebHistory } from 'vue-router'
// 引入页面组件
const Login = () => import('../views/Login.vue')
const Chat = () => import('../views/Chat.vue')
// 路由规则
const routes = [
{
path: '/',
redirect: '/chat' // 默认重定向到聊天页
},
{
path: '/login',
name: 'Login',
component: Login,
meta: { title: '用户登录' }
},
{
path: '/chat',
name: 'Chat',
component: Chat,
meta: { title: '智能聊天', requireAuth: true } // 需要登录才能访问
}
]
// 创建路由实例
const router = createRouter({
history: createWebHistory(),
routes
})
// 路由守卫:登录拦截
router.beforeEach((to, from, next) => {
const token = localStorage.getItem('token')
// 需要登录的页面,无token跳转到登录页
if (to.meta.requireAuth && !token) {
next('/login')
} else {
next()
}
})
export default router
6.2 Axios请求封装
在src文件夹下创建utils文件夹,新建request.js,封装全局请求工具,统一处理请求头、响应、异常:
javascript
import axios from 'axios'
// 创建axios实例
const service = axios.create({
baseURL: '/api', // 基础请求地址,对应vite.config代理配置
timeout: 30000 // 请求超时时间
})
// 请求拦截器:统一添加token
service.interceptors.request.use(
config => {
const token = localStorage.getItem('token')
if (token) {
config.headers.Authorization = `Bearer ${token}`
}
return config
},
error => {
return Promise.reject(error)
}
)
// 响应拦截器:统一处理响应结果
service.interceptors.response.use(
response => {
return response.data
},
error => {
ElMessage.error('请求失败,请检查后端服务')
return Promise.reject(error)
}
)
export default service
6.3 用户登录页面开发
在src文件夹下创建views文件夹,新建Login.vue,实现登录表单、校验、登录请求:
vue
<template>
<div class="login-container">
<div class="login-box">
<h2>智能聊天系统</h2>
<!-- 登录表单 -->
<el-form :model="loginForm" :rules="loginRules" ref="loginRef" label-width="80px">
<el-form-item label="用户名" prop="username">
<el-input v-model="loginForm.username" placeholder="请输入用户名" />
</el-form-item>
<el-form-item label="密码" prop="password">
<el-input v-model="loginForm.password" type="password" placeholder="请输入密码" />
</el-form-item>
<el-form-item>
<el-button type="primary" @click="login" class="login-btn">登录</el-button>
</el-form-item>
</el-form>
</div>
</div>
</template>
<script setup>
import { ref } from 'vue'
import { useRouter } from 'vue-router'
import request from '../utils/request'
import { ElMessage } from 'element-plus'
const router = useRouter()
// 登录表单ref
const loginRef = ref(null)
// 登录表单数据
const loginForm = ref({
username: '',
password: ''
})
// 表单校验规则
const loginRules = ref({
username: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
password: [{ required: true, message: '请输入密码', trigger: 'blur' }]
})
// 登录请求
const login = async () => {
await loginRef.value.validate()
try {
const res = await request.post('/login', loginForm.value)
if (res.code === 200) {
// 存储token
localStorage.setItem('token', res.data.token)
ElMessage.success('登录成功')
// 跳转到聊天页
router.push('/chat')
} else {
ElMessage.error(res.message)
}
} catch (error) {
ElMessage.error('登录失败,请检查账号密码')
}
}
</script>
<style scoped>
.login-container {
width: 100vw;
height: 100vh;
background-color: #f5f5f5;
display: flex;
align-items: center;
justify-content: center;
}
.login-box {
width: 400px;
padding: 30px;
background-color: #fff;
border-radius: 8px;
box-shadow: 0 0 10px rgba(0,0,0,0.1);
}
.login-box h2 {
text-align: center;
margin-bottom: 30px;
}
.login-btn {
width: 100%;
}
</style>
6.4 智能聊天页面开发
在views文件夹下新建Chat.vue,实现消息列表渲染、消息发送、滚动到底部、对接后端聊天接口:
vue
<template>
<div class="chat-container">
<!-- 聊天头部 -->
<div class="chat-header">
<span>智能聊天助手</span>
<el-button type="danger" size="small" @click="logout">退出登录</el-button>
</div>
<!-- 消息列表 -->
<div class="chat-body" ref="chatBodyRef">
<div class="message-item" v-for="(item, index) in messageList" :key="index">
<!-- 用户消息 -->
<div class="user-message" v-if="item.role === 'user'">
<span class="message-content">{{ item.content }}</span>
<el-avatar size="40">我</el-avatar>
</div>
<!-- AI消息 -->
<div class="ai-message" v-if="item.role === 'ai'">
<el-avatar size="40" type="primary">AI</el-avatar>
<span class="message-content">{{ item.content }}</span>
</div>
</div>
</div>
<!-- 消息输入框 -->
<div class="chat-footer">
<el-input
v-model="sendContent"
type="textarea"
:rows="3"
placeholder="请输入消息,按Enter发送"
@keyup.enter="sendMessage"
/>
<el-button type="primary" @click="sendMessage" :loading="loading">发送</el-button>
</div>
</div>
</template>
<script setup>
import { ref, onMounted, nextTick } from 'vue'
import { useRouter } from 'vue-router'
import request from '../utils/request'
import { ElMessage } from 'element-plus'
const router = useRouter()
// 聊天容器ref,用于自动滚动到底部
const chatBodyRef = ref(null)
// 消息列表
const messageList = ref([])
// 发送内容
const sendContent = ref('')
// 加载状态
const loading = ref(false)
// 页面挂载后,初始化欢迎消息
onMounted(() => {
messageList.value.push({
role: 'ai',
content: '你好,我是智能聊天助手,有什么可以帮你的吗?'
})
scrollToBottom()
})
// 自动滚动到底部
const scrollToBottom = () => {
nextTick(() => {
chatBodyRef.value.scrollTop = chatBodyRef.value.scrollHeight
})
}
// 发送消息
const sendMessage = async () => {
if (!sendContent.value.trim()) {
ElMessage.warning('请输入消息内容')
return
}
// 添加用户消息到列表
messageList.value.push({
role: 'user',
content: sendContent.value
})
scrollToBottom()
loading.value = true
try {
// 请求后端AI聊天接口
const res = await request.post('/chat', {
prompt: sendContent.value
})
if (res.code === 200) {
// 添加AI回复消息
messageList.value.push({
role: 'ai',
content: res.data.answer
})
} else {
ElMessage.error(res.message)
}
} catch (error) {
ElMessage.error('AI回复失败,请检查后端服务')
} finally {
loading.value = false
sendContent.value = ''
scrollToBottom()
}
}
// 退出登录
const logout = () => {
localStorage.removeItem('token')
ElMessage.success('退出成功')
router.push('/login')
}
</script>
<style scoped>
.chat-container {
width: 100vw;
height: 100vh;
display: flex;
flex-direction: column;
overflow: hidden;
}
.chat-header {
height: 60px;
background-color: #409eff;
color: #fff;
display: flex;
align-items: center;
justify-content: space-between;
padding: 0 20px;
font-size: 18px;
}
.chat-body {
flex: 1;
padding: 20px;
background-color: #f5f5f5;
overflow-y: auto;
}
.message-item {
margin-bottom: 20px;
display: flex;
align-items: flex-end;
}
.user-message {
justify-content: flex-end;
}
.ai-message {
justify-content: flex-start;
}
.message-content {
max-width: 60%;
padding: 10px 15px;
border-radius: 20px;
margin: 0 10px;
background-color: #fff;
}
.user-message .message-content {
background-color: #409eff;
color: #fff;
}
.chat-footer {
height: 120px;
padding: 10px 20px;
background-color: #fff;
display: flex;
align-items: flex-end;
gap: 10px;
}
.chat-footer el-input {
flex: 1;
}
</style>
七、FastAPI构建大模型交互+登录鉴权
本节开发后端核心功能:用户登录鉴权(JWT) 、智能聊天接口(对接大模型) 、接口权限拦截,实现完整的后端逻辑,保证接口安全、聊天功能正常运行。
7.1 登录鉴权模块开发
7.1.1 工具类封装(密码加密、JWT生成)
在项目根目录创建utils.py,封装密码加密、token生成与校验工具:
python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
工具类:密码加密、JWT登录鉴权
"""
from datetime import datetime, timedelta
from passlib.context import CryptContext
from jose import JWTError, jwt
# 配置密钥(生产环境请修改为复杂随机字符串)
SECRET_KEY = "fastapi-vue3-chat-2024"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30 # token过期时间30分钟
# 密码加密上下文
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
# 密码加密
def get_password_hash(password: str):
return pwd_context.hash(password)
# 密码校验
def verify_password(plain_password: str, hashed_password: str):
return pwd_context.verify(plain_password, hashed_password)
# 生成JWT token
def create_access_token(data: dict):
to_encode = data.copy()
# 设置token过期时间
expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
to_encode.update({"exp": expire})
encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
return encoded_jwt
# 校验JWT token
def verify_token(token: str):
try:
payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
username: str = payload.get("sub")
if username is None:
return None
return username
except JWTError:
return None
7.1.2 登录接口开发
修改main.py,添加登录接口、权限依赖,实现登录校验与接口拦截:
python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from utils import verify_password, get_password_hash, create_access_token, verify_token
# 创建应用实例
app = FastAPI(
title="智能聊天系统后端API",
description="基于FastAPI+大模型的智能聊天后端服务",
version="1.0.0"
)
# 配置跨域
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# 模拟用户数据(生产环境可替换为数据库)
fake_users = {
"admin": {
"username": "admin",
"hashed_password": get_password_hash("123456") # 密码:123456
}
}
# 登录请求体模型
class LoginRequest(BaseModel):
username: str
password: str
# 聊天请求体模型
class ChatRequest(BaseModel):
prompt: str
# 权限依赖:校验token
def get_current_user(token: str = Depends(verify_token)):
if token is None:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="无效token,请重新登录"
)
return token
# 健康检查接口
@app.get("/", summary="系统健康检查接口")
def health_check():
return {
"code": 200,
"message": "智能聊天系统后端服务启动成功",
"data": None
}
# 登录接口
@app.post("/login", summary="用户登录接口")
def login(login_req: LoginRequest):
# 校验用户是否存在
user = fake_users.get(login_req.username)
if not user or not verify_password(login_req.password, user["hashed_password"]):
return {
"code": 400,
"message": "用户名或密码错误",
"data": None
}
# 生成token
token = create_access_token(data={"sub": login_req.username})
return {
"code": 200,
"message": "登录成功",
"data": {"token": token}
}
# ------------------- 大模型聊天接口 -------------------
@app.post("/chat", summary="智能聊天接口", dependencies=[Depends(get_current_user)])
def chat(chat_req: ChatRequest):
"""
智能聊天接口,对接大模型
需登录才能访问
"""
try:
# 此处为模拟大模型回复,可替换为真实大模型API调用
# 真实对接:调用第三方大模型接口,传入chat_req.prompt,获取回复
prompt = chat_req.prompt
# 模拟AI回复(可自行扩展逻辑)
answer = f"收到你的消息:{prompt},我是基于FastAPI+Vue3的智能聊天助手,很高兴为你服务!"
return {
"code": 200,
"message": "AI回复成功",
"data": {"answer": answer}
}
except Exception as e:
return {
"code": 500,
"message": f"AI回复失败:{str(e)}",
"data": None
}
# 启动服务
if __name__ == "__main__":
import uvicorn
uvicorn.run(
app="main:app",
host="127.0.0.1",
port=8000,
reload=True
)
7.2 大模型对接扩展(替换真实模型)
若需对接真实大模型(如OpenAI、讯飞星火、文心一言等),只需修改/chat接口内的逻辑,调用对应大模型API,示例如下:
python
# 示例:对接OpenAI格式大模型
import requests
def get_ai_response(prompt: str):
url = "大模型接口地址"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer 模型API密钥"
}
data = {
"model": "模型名称",
"messages": [{"role": "user", "content": prompt}]
}
response = requests.post(url, headers=headers, json=data)
return response.json()["choices"][0]["message"]["content"]
八、前后端项目分层规范
为便于后期功能扩展、代码维护,需对前后端项目进行规范化分层,拆解单一文件代码,实现业务分离、职责清晰,打造可扩展的全栈项目结构。
8.1 后端Python项目分层
8.1.1 最终分层结构
shell
fastapi_chat_backend/
├── main.py # 项目启动文件,注册路由、中间件
├── api/ # 接口层
│ ├── __init__.py
│ ├── login.py # 登录相关接口
│ └── chat.py # 聊天相关接口
├── core/ # 核心配置层
│ ├── __init__.py
│ ├── config.py # 项目配置
│ └── security.py # 鉴权核心逻辑
├── models/ # 数据模型层
│ ├── __init__.py
│ └── schema.py # 请求/响应模型
├── utils/ # 工具层
│ ├── __init__.py
│ └── common.py # 通用工具
└── requirements.txt # 依赖清单
8.1.2 分层说明
api层:专门存放各类接口,拆分不同业务模块,避免主文件代码臃肿
core层:存放项目核心配置、安全相关逻辑,统一管理项目参数
models层:专门定义Pydantic数据模型,统一管理请求/响应参数
utils层:存放通用工具类,加密、token、请求等工具复用
8.2 前端Vue3项目分层
8.2.1 最终分层结构
shell
vue3_chat_frontend/
├── src/
│ ├── api/ # 接口请求层,统一管理后端接口
│ │ ├── login.js
│ │ └── chat.js
│ ├── components/ # 公共组件层
│ ├── views/ # 页面组件层
│ │ ├── Login.vue
│ │ └── Chat.vue
│ ├── router/ # 路由层
│ ├── store/ # 状态管理层
│ ├── utils/ # 工具层
│ │ └── request.js
│ └── App.vue # 根组件
├── vite.config.js # 前端配置
└── package.json # 依赖清单
8.2.2 分层说明
api层:统一封装所有后端请求,便于维护、修改接口地址
components层:抽取公共组件,如消息气泡、头部导航等
store层:统一管理用户状态、消息状态,实现数据共享
utils层:存放前端通用工具,如请求、格式化、缓存工具
8.3 分层开发优势
-
代码结构清晰,便于多人协作开发、后期维护
-
业务逻辑分离,单一模块修改不影响其他模块
-
便于功能扩展,新增业务只需对应分层添加代码
-
符合前后端分离开发规范,适配生产环境部署
九、总结
本文从零起步,完整讲解了基于FastAPI+Vue3的智能聊天系统全栈开发流程,覆盖Python3环境、Vue3环境搭建、开发工具配置、前后端项目创建、核心功能开发、项目分层规范全环节,从零基础环境配置,到完整功能落地,再到工程化规范梳理,全程无跳跃、无晦涩理论,所有代码均可直接复制运行,且附带逐行详细注释,完美适配初级、中级开发者,以及前端、后端、运维、AI爱好者各类人群的学习需求。
整套系统采用前后端分离架构,后端依托FastAPI实现高性能接口服务、JWT登录鉴权与大模型对接,前端借助Vue3+Vite打造响应式聊天交互页面,兼顾开发效率与用户体验,既能作为全栈开发入门实战项目,也能在此基础上快速迭代,打造商用级智能对话应用。
十、项目完整运行与前后端联调手册
10.1 后端服务启动流程
10.1.1 启动前检查
启动后端服务前,务必完成以下检查,避免启动失败、接口报错问题:
确认Python虚拟环境已激活,终端前方显示(venv)标识;
确认所有依赖已完整安装,无缺失库、版本冲突问题;
确认
main.py与utils.py文件处于同一级目录,路径无错误;确认端口8000未被占用,若被占用可修改启动端口号。
10.1.2 启动后端服务
进入后端项目根目录,有两种启动方式,任选其一即可:
方式一:PyCharm直接运行(推荐新手)
右键点击
main.py文件,选择Run 'main',等待控制台输出启动信息,看到Uvicorn running
on http://127.0.0.1:8000 即代表后端启动成功,此时可访问http://127.0.0.1:8000/docs打开自动生成的交互式API文档,在线测试登录、聊天接口。
方式二:终端命令启动
shell
# 激活虚拟环境
# Windows
venvScriptsactivate
# Mac/Linux
source venv/bin/activate
# 启动后端服务
uvicorn main:app --host 127.0.0.1 --port 8000 --reload
10.2 前端服务启动流程
10.2.1 启动前检查
确认Node.js环境正常,npm镜像源已切换为国内源;
确认前端所有依赖已安装完毕,无缺失依赖;
确认
vite.config.js内代理地址与后端地址一致;确认端口3000未被占用,若冲突可修改配置内port参数。
10.2.2 启动前端项目
打开新终端,进入Vue3前端项目根目录,执行启动命令:
shell
# 安装依赖(首次启动必须执行)
npm install
# 启动前端开发服务
npm run dev
启动成功后,浏览器会自动弹出前端页面,访问地址为http://127.0.0.1:3000,默认跳转至登录页面,代表前端项目启动正常。
10.3 全流程联调测试
-
登录测试:输入默认账号admin、密码123456,点击登录,跳转至智能聊天页面,代表登录接口、前端路由、JWT鉴权均正常;
-
权限拦截测试:清除浏览器本地缓存token,直接访问http://127.0.0.1:3000/chat,会自动跳转回登录页面,代表路由守卫生效;
-
聊天功能测试:在输入框输入任意文本,点击发送或按回车键,页面正常渲染用户消息与AI回复消息,代表前后端接口联调成功、大模型交互逻辑正常;
-
退出登录测试:点击右上角退出登录按钮,清除token并跳转回登录页,代表状态管理、路由跳转正常。
十一、项目常见问题与解决方案
11.1 后端常见问题
11.1.1 FastAPI启动报错,端口被占用
问题描述:控制台提示端口8000已被占用,无法启动服务。
解决方案:
-
修改启动命令,更换端口,例如改为8080:
uvicorn main:app --host 127.0.0.1 --port 8080 --reload; -
同时修改前端
vite.config.js内代理target地址端口号,保持前后端端口一致; -
关闭占用端口的程序,或重启电脑释放端口。
11.1.2 导入依赖报错,模块不存在
问题描述:运行代码提示No module named 'fastapi'等模块缺失错误。
解决方案:
确认虚拟环境已激活,未激活则执行激活命令;
重新执行依赖安装命令,确保所有依赖安装至当前虚拟环境;
PyCharm内重新配置Python解释器,指向虚拟环境解释器。
11.1.3 跨域报错,前端无法请求后端接口
问题描述:浏览器控制台提示CORS跨域异常,接口请求失败。
解决方案:
检查
main.py内跨域中间件是否配置,allow_origins是否设为["*"];确认后端服务正常启动,可直接在浏览器访问后端接口测试;
重启前后端服务,清除浏览器缓存后重新测试。
11.1.4 JWT鉴权失效,提示无效token
问题描述:登录成功后,请求聊天接口提示无效token、权限不足。
解决方案:
检查前端请求拦截器,确认token已正常添加至请求头;
确认后端
utils.py内SECRET_KEY、ALGORITHM配置一致;清除浏览器token,重新登录获取新token。
11.2 前端常见问题
11.2.1 npm install安装依赖失败、速度慢
解决方案:
确认npm镜像源已切换为淘宝镜像,执行校验命令查看;
删除node_modules文件夹与package-lock.json,重新执行npm install;
使用cnpm代替npm安装依赖。
11.2.2 前端页面无法加载,控制台报错
解决方案:
检查路由、组件引入路径是否正确,避免路径大小写、拼写错误;
确认Element Plus、Vue Router等插件已全局注册;
重启前端开发服务,重新执行npm run dev。
11.2.3 聊天消息无法滚动到底部
解决方案:
确认
chatBodyRef绑定至聊天列表容器;在消息添加完毕后,使用nextTick确保DOM渲染完成再执行滚动;
检查聊天容器CSS是否设置overflow-y: auto。
十二、项目功能扩展与进阶优化方向
12.1 后端功能扩展
接入数据库:替换模拟用户数据,接入MySQL、SQLite、Redis等数据库,实现用户注册、密码持久化存储、聊天记录保存;
对接真实大模型:接入OpenAI、讯飞星火、文心一言、通义千问等官方API,实现真正的AI智能对话,支持流式响应、上下文对话;
新增接口权限:细化用户权限,区分普通用户与管理员权限,实现接口级权限控制;
日志记录:添加全局日志模块,记录接口请求、异常报错、用户操作日志,便于运维排查问题;
接口限流:添加接口限流机制,防止恶意请求、频繁调用,提升服务稳定性;
部署优化:使用Gunicorn+Uvicorn部署,搭配Nginx反向代理,适配生产环境高并发场景。
12.2 前端功能扩展
流式消息渲染:实现大模型流式输出,打字机效果回复,提升用户交互体验;
聊天记录缓存:本地缓存聊天记录,刷新页面不丢失,支持历史消息查看;
消息发送状态:添加发送中、发送失败、已读等消息状态,优化交互反馈;
响应式适配:适配移动端、平板、PC多端屏幕,实现全端兼容;
主题切换:新增深色、浅色模式切换,自定义页面主题样式;
文件上传:支持图片、文件发送,扩展多模态对话能力。
12.3 工程化优化
依赖管理:后端生成requirements.txt依赖清单,前端锁定package版本,便于团队协作与部署;
代码规范:添加ESLint、Black等代码格式化工具,统一代码规范;
自动化部署:编写Dockerfile,使用Docker容器化部署,实现一键部署、环境隔离;
配置分离:拆分开发、测试、生产环境配置,避免敏感信息泄露。
十三、全文总结与学习建议
对于初级开发者而言,这套FastAPI+Vue3智能聊天系统,是打通前后端开发逻辑、入门全栈开发的绝佳实战项目,不用再零散学习单一框架,而是通过完整业务场景,把环境搭建、代码编写、接口联调、问题排查全流程走通,彻底理解前后端分离开发的核心逻辑。对于后端开发者,能快速掌握Vue3前端基础,实现前端页面自主开发;对于前端开发者,能清晰理解后端接口逻辑、鉴权流程、大模型对接方式,提升全栈开发能力;对于运维人员,能掌握前后端项目启动、部署、问题排查的全套流程;对于AI爱好者,能快速落地大模型应用,打造属于自己的智能对话工具。
学习本套教程,切忌只看不练、只复制代码不理解逻辑,建议每完成一个章节,亲手复现对应功能,理解每一行代码的作用、每一项配置的含义,遇到问题自主排查解决,夯实基础。在掌握基础功能后,可按照前文扩展方向,自主优化功能、迭代版本,把实战项目打磨得更加完善,逐步具备商用级项目开发能力。
FastAPI与Vue3作为当下主流的前后端技术栈,生态完善、上手简单、性能优异,在AI应用、后台管理系统、API服务开发等场景应用广泛,掌握这套技术栈,无论是求职面试还是个人项目开发,都能具备极强的竞争力。后续可深入学习异步编程、数据库优化、前端工程化、容器化部署等进阶知识,持续提升全栈开发水平,打造更多高质量的AI应用与全栈项目。
至此,基于FastAPI+Vue3的智能聊天系统全栈开发教程全部完结,从环境搭建到项目落地,从基础功能到进阶优化,全程全覆盖,希望能帮助各位开发者顺利入门全栈开发、落地AI应用,在技术学习的道路上稳步前行。
🌟 感谢您耐心阅读到这里!
🚀 技术成长没有捷径,但每一次的阅读、思考和实践,都在默默缩短您与成功的距离。
💡 如果本文对您有所启发,欢迎点赞👍、收藏📌、分享📤给更多需要的伙伴!
🗣️ 期待在评论区看到您的想法、疑问或建议,我会认真回复,让我们共同探讨、一起进步~
🔔 关注我,持续获取更多干货内容!
🤗 我们下篇文章见!
AI 大模型基础教程目录大纲
第一章:Python3 基础入门:从零基础到实战精通
第二章:Python3 之 列表与元组
第三章:Python3 之 字符串
第四章:Python3 之 字典
第五章:Python3 之 条件、循环和其他语句
第六章:Python3 之 函数【从基础入门到底层原理】
第七章:Python3 之 面向对象编程
第八章:Python3 之 异常与文件处理【从基础入门到底层原理+项目实战】
第九章:AI大模型基础认知【从入门原理到行业赋能】
第十章:AI大模型核心原理【从基础架构到落地训练】
第十一章:深入剖析 Prompt 提示工程
第十二章:Prompt 提示工程 之 实战项目
第十三章:AI大模型基础之 FastAPI
第十四章:基于 FastAPI+Vue3 的智能聊天系统全栈开发实战