Tare使用：如何在虚拟环境中调试，（小白教程）

一、背景

本文记录在 Trae 中使用 rag conda 虚拟环境调试 src/pipeline.py 时遇到的两个经典报错及解决方案。适用项目为 RAG-Challenge（src/ 包结构 + 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/?linkid=830387
    "version": "0.2.0",
    "configurations": [
    
        {
            "name": "Python Debugger: Current File with Arguments",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "args": "${command:pickArgs}"
        }
    ]

然后点击调试按钮

有什么错误修改配置文件

二、错误 1：Could 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"（新版推荐写法）。

三、错误 2：ModuleNotFoundError: 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 API（qwen-turbo / dashscope），断点单步很慢且消耗 token。建议只保留 process_questions() 一行，并临时只跑 1~2 题验证。
• 并行解析 PDF 使用多进程：parse_pdf_reports（并行模式）的子进程断点不会触发，调试 PDF 解析请改用顺序模式。

六、核心结论速查

问题	根因	解法
Could not find debugpy path	IDE 未使用 rag 解释器	Select Interpreter 选 rag + Reload Window
No module named 'src'	program 启动只把脚本目录加入 sys.path	改用 "module": "src.pipeline" + "cwd"
多进程步骤断点不触发	子进程无法被 IDE 断点捕获	用顺序模式替代并行模式

一句话总结：用 python -m 的方式跑代码，sys.path 里才有项目根目录；IDE 调试也一样------module 模式 + cwd 就是调试包结构项目的最稳姿势。