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