6.7 KiB
6.7 KiB
前端项目待办事项 (TODO)
项目名称
frontend-vue3
当前状态
✅ 项目已交付，功能完整可用
必需配置事项
1. 后端服务启动 ⚠️
优先级: 🔴 高 (阻塞项)
问题: 前端依赖后端 API，后端服务必须运行
操作步骤:
# 1. 确保后端服务运行在 localhost:8000
cd langchain-learning-kit
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
# 2. 验证后端可访问
curl http://localhost:8000/health
# 预期输出: {"status":"healthy","environment":"development"}
验证方式:
- 浏览器访问: http://localhost:8000/docs
- 应该看到 Swagger UI 文档
2. 前端环境变量配置 ⚠️
优先级: 🔴 高 (阻塞项)
问题: 需要确认 API 地址配置正确
操作步骤:
cd frontend
# 1. 检查 .env.development 是否存在
cat .env.development
# 内容应为: VITE_API_BASE_URL=http://localhost:8000/api/v1
# 2. 如果文件不存在，复制示例
cp .env.example .env.development
验证方式:
- 文件存在:
frontend/.env.development - 内容正确:
VITE_API_BASE_URL=http://localhost:8000/api/v1
3. 安装前端依赖 ⚠️
优先级: 🔴 高 (阻塞项)
问题: 需要安装 npm 依赖包
操作步骤:
cd frontend
# 安装依赖
npm install
# 验证安装成功
npm list --depth=0
# 应该看到 vue, vue-router, axios, element-plus 等包
验证方式:
node_modules/目录存在package-lock.json文件存在
可选配置事项
4. 创建初始模型配置 🟡
优先级: 🟡 中 (功能依赖)
问题: 前端下拉框需要至少一个 LLM 和 Embedding 模型
操作步骤:
- 启动前端:
cd frontend && npm run dev - 访问: http://localhost:5173/models
- 点击"创建模型"，创建以下配置:
LLM 模型示例:
{
"name": "gpt-4",
"type": "llm",
"config": {
"model": "gpt-4",
"temperature": 0.7,
"api_key": "${OPENAI_API_KEY}"
},
"is_default": true
}
Embedding 模型示例:
{
"name": "text-embedding-ada-002",
"type": "embedding",
"config": {
"model": "text-embedding-ada-002",
"api_key": "${OPENAI_API_KEY}"
},
"is_default": true
}
验证方式:
- 模型管理页面显示 2 个模型
- 其他页面的模型下拉框有可选项
5. 后端对话列表 API 补充 🟡
优先级: 🟡 中 (功能缺失)
问题: 对话列表页面当前无法加载数据（后端未提供 GET /conversations 接口）
解决方式1: 等待后端补充 联系后端开发者补充接口:
# 在 app/api/conv.py 添加
@router.get("/conversations")
def list_conversations():
# 返回对话列表
pass
解决方式2: 临时使用创建对话
- 对话列表页面点击"创建对话"
- 创建后会自动跳转到聊天页
当前状态: 前端已预留接口，使用空数组兜底
6. 生产环境部署配置 🟢
优先级: 🟢 低 (生产部署)
问题: 生产环境需要修改 API 地址
操作步骤:
cd frontend
# 1. 修改生产环境配置
echo "VITE_API_BASE_URL=https://your-production-api.com/api/v1" > .env.production
# 2. 构建生产包
npm run build
# 3. 预览构建结果
npm run preview
验证方式:
dist/目录生成- 访问 http://localhost:4173 预览
常见问题排查
Q1: 前端启动失败
现象: npm run dev 报错
排查步骤:
# 1. 检查 Node.js 版本
node --version
# 需要 >= 18
# 2. 清除缓存重新安装
rm -rf node_modules package-lock.json
npm install
# 3. 检查端口占用
lsof -i :5173 # Mac/Linux
netstat -ano | findstr :5173 # Windows
Q2: 无法连接后端
现象: 页面显示"网络连接失败"
排查步骤:
# 1. 检查后端服务状态
curl http://localhost:8000/health
# 2. 检查环境变量
cat frontend/.env.development
# 3. 浏览器控制台查看网络请求
# 打开开发者工具 -> Network 标签
Q3: 模型下拉框为空
现象: 知识库、对话页面模型选择框无内容
排查步骤:
# 1. 检查是否已创建模型
curl http://localhost:8000/api/v1/models
# 2. 如果为空，访问前端创建模型
# http://localhost:5173/models
Q4: 知识库查询无结果
现象: 查询返回 0 条结果
排查步骤:
- 确认已摄取文档 (查看状态: 文档数 > 0)
- 确认 Embedding 模型与摄取时一致
- 检查后端日志确认 FAISS 索引存在
- 尝试重新摄取文档
快速启动指南
一键启动脚本（推荐）
Windows (PowerShell):
# 1. 启动后端 (新窗口)
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd ..; python -m uvicorn app.main:app --reload --port 8000"
# 2. 启动前端
cd frontend
npm install
npm run dev
Mac/Linux (Bash):
# 1. 启动后端 (后台运行)
cd ..
python -m uvicorn app.main:app --reload --port 8000 &
# 2. 启动前端
cd frontend
npm install
npm run dev
访问地址:
- 前端: http://localhost:5173
- 后端 API 文档: http://localhost:8000/docs
操作指引
完整使用流程
步骤1: 创建模型配置
- 访问 http://localhost:5173/models
- 创建 LLM 模型 (例如: gpt-4)
- 创建 Embedding 模型 (例如: text-embedding-ada-002)
步骤2: 创建知识库
- 访问 http://localhost:5173/knowledge-base
- 点击"创建知识库"
- 输入名称和描述
步骤3: 摄取文档
- 在知识库列表点击"摄取文档"
- 选择 Embedding 模型
- 添加文档内容（支持多个）
- 提交摄取
步骤4: 查询知识库
- 点击"查询"按钮
- 输入查询文本
- 选择返回数量 (k 值)
- 查看结果和相关度评分
步骤5: 创建对话
- 访问 http://localhost:5173/conversations
- 点击"创建对话"
- 输入用户ID和标题
- 自动跳转到聊天页
步骤6: 聊天交互
- 启用/禁用 RAG 开关
- 选择知识库和 LLM 模型
- 输入消息并发送
- 查看助手回复和来源信息
步骤7: Agent 执行
- 访问 http://localhost:5173/agent
- 输入任务描述
- 选择知识库（可选）和 LLM
- 点击"执行任务"
- 查看结果和工具调用日志
联系支持
技术支持渠道
- 项目文档:
frontend/README.md - 架构设计:
docs/frontend-vue3/DESIGN_frontend-vue3.md - 后端 API 文档: http://localhost:8000/docs
问题反馈
如遇到其他问题，请检查:
- Node.js 版本 >= 18
- 后端服务正常运行
- 浏览器控制台错误信息
- Network 面板 API 请求响应
最后更新: 2025-10-02 状态: ✅ 项目完成，待启动使用 下一步: 按照上述配置事项启动项目