一、背景本文记录在 Trae 中使用ragconda 虚拟环境调试src/pipeline.py时遇到的两个经典报错及解决方案。适用项目为 RAG-Challengesrc/包结构 pipeline.py主入口。项目结构如下pipeline.py是主流程入口内含if __name__ __main__依赖同目录下的src包src.pdf_parsing、src.retrieval、src.reranking等。rag_challenge/ ├── src/ │ ├── pipeline.py # 主入口可独立运行 / 可调试 │ ├── pdf_parsing.py │ ├── retrieval.py │ └── ... ├── data/ └── .vscode/ └── launch.json # 调试配置 AI填充日常命令行运行方式conda activate rag cd C:\Users\Administrator\rag_challenge python -m src.pipeline目标是在 IDE 里按 F5 直接调试pipeline.py并且使用rag虚拟环境。创建配置文件使用AI填充json配置解释器选择虚拟环境// 使用 IntelliSense 了解相关属性。 // 悬停以查看现有属性的描述。 // 欲了解更多信息请访问: https://go.microsoft.com/fwlink/?linkid830387 version: 0.2.0, configurations: [ { name: Python Debugger: Current File with Arguments, type: debugpy, request: launch, program: ${file}, console: integratedTerminal, args: ${command:pickArgs} } ]然后点击调试按钮有什么错误修改配置文件二、错误 1Could not find debugpy path.现象F5 启动调试时直接报错Could not find debugpy path.排查debugpy 是 Python 调试器依赖包。先用目标解释器验证它是否安装 D:/ProgramData/anaconda3/envs/rag/python.exe -c import debugpy; print(debugpy.__version__) # 输出debugpy ok 1.8.21结论debugpy 其实已经装好了。问题不在环境而在 IDE 没有用rag解释器去解析 debugpy。解决在 IDE 中选中rag解释器Ctrl Shift P→Python: Select Interpreter→ 选择D:\ProgramData\anaconda3\envs\rag\python.exe确认左下角状态栏显示rag。重载窗口Ctrl Shift P→Developer: Reload Window。建议把launch.json的type: python改为type: debugpy新版推荐写法。三、错误 2ModuleNotFoundError: No module named src现象debugpy 的问题解决后F5 启动又报错且断点停在runpy._run_module_as_main发生异常: ModuleNotFoundError No module named src File C:\Users\Administrator\rag_challenge\src\pipeline.py, line 10, in module from src.pdf_parsing import PDFParser ModuleNotFoundError: No module named src原因分析关键pipeline.py第 10 行是from src.pdf_parsing import PDFParser这里的src是一个包目录Python 必须把项目根目录C:\Users\Administrator\rag_challenge加入sys.path才能找到它。而用program: .../src/pipeline.py方式启动时Python 只会把脚本所在目录即src/加入sys.path不会把项目根目录加进去。因此import src必然失败。对比验证在终端里python -c from src.pipeline import Pipeline之所以成功是因为-c方式会把当前工作目录加入sys.path。而program方式只认脚本目录。解决改用 module 模式启动module: src.pipeline等价于命令行python -m src.pipeline它会把当前工作目录cwd加入sys.path从而让import src成功。最终launch.json{ version: 0.2.0, configurations: [ { name: Python: Debug pipeline.py (rag env), type: debugpy, request: launch, module: src.pipeline, cwd: ${workspaceFolder}, console: integratedTerminal, justMyCode: false } ] }要点module: src.pipeline与program二选一不能同时存在。cwd: ${workspaceFolder}必须保留module 模式靠它解析src包。justMyCode: false允许进入第三方库源码调试可选。保存后按 F5选择Python: Debug pipeline.py (rag env)即可正常调试。四、备选方案继续用 program 注入 PYTHONPATH如果坚持用program方式需要手动把项目根目录注入搜索路径{ version: 0.2.0, configurations: [ { name: Python: Debug pipeline.py (rag env), type: debugpy, request: launch, program: C:/Users/Administrator/rag_challenge/src/pipeline.py, cwd: ${workspaceFolder}, env: { PYTHONPATH: ${workspaceFolder} }, console: integratedTerminal, justMyCode: false } ] }推荐第一种module 模式与日常命令行运行方式完全一致最稳。五、调试时的注意事项入口会自动跑完整流程pipeline.py的__main__会依次执行merge_reports→export_reports_to_markdown→chunk_reports→create_vector_dbs→process_questions。只想调某一步就把其他步骤临时注释掉。process_questions会真实调用 LLM APIqwen-turbo / dashscope断点单步很慢且消耗 token。建议只保留process_questions()一行并临时只跑 1~2 题验证。并行解析 PDF 使用多进程parse_pdf_reports并行模式的子进程断点不会触发调试 PDF 解析请改用顺序模式。六、核心结论速查问题根因解法Could not find debugpy pathIDE 未使用 rag 解释器Select Interpreter 选 rag Reload WindowNo module named srcprogram 启动只把脚本目录加入 sys.path改用 module: src.pipeline cwd多进程步骤断点不触发子进程无法被 IDE 断点捕获用顺序模式替代并行模式一句话总结用python -m的方式跑代码sys.path里才有项目根目录IDE 调试也一样——module 模式 cwd 就是调试包结构项目的最稳姿势。