165 lines
3.9 KiB
Markdown
165 lines
3.9 KiB
Markdown
|
# VS Code 调试配置指南
|
|||
|
|
|
|||
|
|
本文档说明如何在 VS Code 中运行和调试 Agentic RAG 服务。
|
|||
|
|
|
|||
|
|
## 🚀 快速开始
|
|||
|
|
|
|||
|
|
### 1. 打开VS Code
|
|||
|
|
```bash
|
|||
|
|
cd /home/fl/code/ai-solution/agentic-rag-4
|
|||
|
|
code .
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 选择Python解释器
|
|||
|
|
- 按 `Ctrl+Shift+P` 打开命令面板
|
|||
|
|
- 输入 "Python: Select Interpreter"
|
|||
|
|
- 选择 `.venv/bin/python` (项目虚拟环境)
|
|||
|
|
|
|||
|
|
## 🐛 调试配置
|
|||
|
|
|
|||
|
|
已配置了以下调试选项，可在"运行和调试"面板中使用：
|
|||
|
|
|
|||
|
|
### 1. Debug Agentic RAG Service
|
|||
|
|
- **用途**: 直接调试服务主程序
|
|||
|
|
- **端口**: 8000
|
|||
|
|
- **特点**: 支持断点调试，实时代码重载
|
|||
|
|
|
|||
|
|
### 2. Debug Service with uvicorn
|
|||
|
|
- **用途**: 使用uvicorn调试服务（推荐）
|
|||
|
|
- **端口**: 8000
|
|||
|
|
- **特点**: 更接近生产环境，支持热重载
|
|||
|
|
|
|||
|
|
### 3. Run Tests
|
|||
|
|
- **用途**: 运行所有测试用例
|
|||
|
|
- **特点**: 支持测试断点调试
|
|||
|
|
|
|||
|
|
### 4. Run Streaming Test
|
|||
|
|
- **用途**: 运行流式API测试
|
|||
|
|
- **特点**: 测试实际的流式响应
|
|||
|
|
|
|||
|
|
## 📋 如何使用
|
|||
|
|
|
|||
|
|
### 方法1: 使用VS Code调试面板
|
|||
|
|
1. 点击左侧活动栏的"运行和调试"图标 (Ctrl+Shift+D)
|
|||
|
|
2. 选择调试配置（推荐 "Debug Service with uvicorn"）
|
|||
|
|
3. 点击绿色的"开始调试"按钮或按 F5
|
|||
|
|
|
|||
|
|
### 方法2: 使用调试启动器
|
|||
|
|
```bash
|
|||
|
|
python debug_service.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 方法3: 使用任务
|
|||
|
|
1. 按 `Ctrl+Shift+P` 打开命令面板
|
|||
|
|
2. 输入 "Tasks: Run Task"
|
|||
|
|
3. 选择相应的任务（如 "Start Service"）
|
|||
|
|
|
|||
|
|
## 🔧 断点调试
|
|||
|
|
|
|||
|
|
### 设置断点
|
|||
|
|
- 在代码行号左侧点击设置断点
|
|||
|
|
- 红色圆点表示断点已设置
|
|||
|
|
|
|||
|
|
### 常用调试点
|
|||
|
|
- `service/main.py:app` - 应用入口
|
|||
|
|
- `service/graph/graph.py` - 核心逻辑
|
|||
|
|
- `service/llm_client.py:astream` - LLM流式调用（你选中的代码）
|
|||
|
|
- `service/config.py` - 配置加载
|
|||
|
|
|
|||
|
|
### 调试控制
|
|||
|
|
- **F5**: 继续执行
|
|||
|
|
- **F10**: 单步跳过
|
|||
|
|
- **F11**: 单步进入
|
|||
|
|
- **Shift+F11**: 单步跳出
|
|||
|
|
- **Ctrl+Shift+F5**: 重启调试
|
|||
|
|
|
|||
|
|
## 🌐 服务端点
|
|||
|
|
|
|||
|
|
调试时服务运行在:
|
|||
|
|
- **主页**: http://localhost:8000
|
|||
|
|
- **健康检查**: http://localhost:8000/health
|
|||
|
|
- **API文档**: http://localhost:8000/docs
|
|||
|
|
- **聊天API**: http://localhost:8000/api/chat
|
|||
|
|
|
|||
|
|
## 📊 调试技巧
|
|||
|
|
|
|||
|
|
### 1. 查看变量
|
|||
|
|
- 鼠标悬停在变量上查看值
|
|||
|
|
- 使用"变量"面板查看作用域内的所有变量
|
|||
|
|
- 使用"监视"面板添加表达式监视
|
|||
|
|
|
|||
|
|
### 2. 控制台调试
|
|||
|
|
- 在"调试控制台"中执行Python表达式
|
|||
|
|
- 例如: `config.get_llm_config()`
|
|||
|
|
|
|||
|
|
### 3. 异步调试
|
|||
|
|
- 对于 `async` 函数，断点会在 `await` 处暂停
|
|||
|
|
- 可以查看异步调用栈
|
|||
|
|
|
|||
|
|
### 4. 流式调试
|
|||
|
|
- 在 `llm_client.py` 的 `astream` 方法设置断点
|
|||
|
|
- 观察流式数据的生成过程
|
|||
|
|
|
|||
|
|
## 🛠️ 故障排除
|
|||
|
|
|
|||
|
|
### 问题1: 端口已占用
|
|||
|
|
```bash
|
|||
|
|
./stop_service.sh # 停止现有服务
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 问题2: 模块导入错误
|
|||
|
|
确保环境变量正确设置:
|
|||
|
|
- `PYTHONPATH`: 项目根目录
|
|||
|
|
- `CONFIG_FILE`: config.yaml路径
|
|||
|
|
|
|||
|
|
### 问题3: 配置文件找不到
|
|||
|
|
确保 `config.yaml` 在项目根目录
|
|||
|
|
|
|||
|
|
### 问题4: 虚拟环境问题
|
|||
|
|
```bash
|
|||
|
|
uv sync # 重新同步依赖
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🔄 开发工作流
|
|||
|
|
|
|||
|
|
### 标准调试流程
|
|||
|
|
1. 设置断点
|
|||
|
|
2. 启动调试 (F5)
|
|||
|
|
3. 发送测试请求
|
|||
|
|
4. 在断点处检查状态
|
|||
|
|
5. 修改代码
|
|||
|
|
6. 热重载自动生效
|
|||
|
|
|
|||
|
|
### 测试流程
|
|||
|
|
1. 运行 "Run Tests" 配置
|
|||
|
|
2. 或使用任务 "Run Tests"
|
|||
|
|
3. 查看测试结果
|
|||
|
|
|
|||
|
|
### 流式测试
|
|||
|
|
1. 运行 "Run Streaming Test" 配置
|
|||
|
|
2. 观察流式输出
|
|||
|
|
3. 检查事件序列
|
|||
|
|
|
|||
|
|
## 📝 日志查看
|
|||
|
|
|
|||
|
|
### 调试模式日志
|
|||
|
|
- 在VS Code终端中查看详细日志
|
|||
|
|
- 日志级别: DEBUG
|
|||
|
|
|
|||
|
|
### 服务日志
|
|||
|
|
```bash
|
|||
|
|
tail -f server.log # 查看服务日志
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🎯 最佳实践
|
|||
|
|
|
|||
|
|
1. **使用条件断点**: 右键断点设置条件
|
|||
|
|
2. **异常断点**: 设置在异常处暂停
|
|||
|
|
3. **日志断点**: 不停止执行，只记录日志
|
|||
|
|
4. **热重载**: 保存文件自动重启服务
|
|||
|
|
5. **环境隔离**: 使用项目专用虚拟环境
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
现在你可以愉快地在VS Code中调试你的Agentic RAG服务了！🎉
|