3.9 KiB
3.9 KiB
VS Code 调试配置指南
本文档说明如何在 VS Code 中运行和调试 Agentic RAG 服务。
🚀 快速开始
1. 打开VS Code
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调试面板
- 点击左侧活动栏的"运行和调试"图标 (Ctrl+Shift+D)
- 选择调试配置（推荐 "Debug Service with uvicorn"）
- 点击绿色的"开始调试"按钮或按 F5
方法2: 使用调试启动器
python debug_service.py
方法3: 使用任务
- 按
Ctrl+Shift+P打开命令面板 - 输入 "Tasks: Run Task"
- 选择相应的任务（如 "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: 端口已占用
./stop_service.sh # 停止现有服务
问题2: 模块导入错误
确保环境变量正确设置:
PYTHONPATH: 项目根目录CONFIG_FILE: config.yaml路径
问题3: 配置文件找不到
确保 config.yaml 在项目根目录
问题4: 虚拟环境问题
uv sync # 重新同步依赖
🔄 开发工作流
标准调试流程
- 设置断点
- 启动调试 (F5)
- 发送测试请求
- 在断点处检查状态
- 修改代码
- 热重载自动生效
测试流程
- 运行 "Run Tests" 配置
- 或使用任务 "Run Tests"
- 查看测试结果
流式测试
- 运行 "Run Streaming Test" 配置
- 观察流式输出
- 检查事件序列
📝 日志查看
调试模式日志
- 在VS Code终端中查看详细日志
- 日志级别: DEBUG
服务日志
tail -f server.log # 查看服务日志
🎯 最佳实践
- 使用条件断点: 右键断点设置条件
- 异常断点: 设置在异常处暂停
- 日志断点: 不停止执行，只记录日志
- 热重载: 保存文件自动重启服务
- 环境隔离: 使用项目专用虚拟环境
现在你可以愉快地在VS Code中调试你的Agentic RAG服务了！🎉