VSCode需显式配置Python解释器、禁用justMyCode并验证路径/API密钥，否则load_data易静默失败导致documents为空。
VSCode 本身不直接运行 LlamaIndex，但它是目前最实用的 RAG 开发编辑器——关键在于配置好 Python 环境、调试链路和依赖隔离，否则 load_data 卡住、DashScopeParse 报 401、from_documents 返回空列表这类问题会反复出现。
Python 解释器与虚拟环境必须显式指定
VSCode 默认可能复用系统 Python 或旧环境，而 LlamaIndex 要求 Python 3.8–3.12，且不同项目常需隔离 llama-index-core 和 llama-index-indices-managed-dashscope 版本。不指定解释器会导致 pip 安装成功但 import 失败。
- 在 VSCode 中按
Ctrl+Shift+P（macOS 为Cmd+Shift+P），输入 “Python: Select Interpreter” - 选择项目根目录下
.venv/bin/python（Linux/macOS）或.venv\Scripts\python.exe（Windows） - 确认
.vscode/settings.json中有"python.defaultInterpreterPath": "./.venv/bin/python" - 终端中执行
pip list | grep llama，应看到llama-index-core、llama-index-llms-dashscope等包
调试时 load_data 卡死或返回空列表的常见原因
load_data 是 RAG 流程中最容易“看起来没报错但实际失败”的环节。它不抛异常，只默默跳过解析失败的文件，最终 documents 为空，后续 from_documents 就会创建空索引。
- 检查
file_path是否为绝对路径 ——DashScopeParse.load_data(file_path="xxx.pdf")中相对路径常因工作目录不一致失效 - 确认环境变量已设置：
os.environ["DASHSCOPE_API_KEY"]和可选的os.environ["DASHSCOPE_WORKSPACE_ID"]必须在load_data前生效 - PDF/DOCX 文件若含加密、扫描图或超 1000 页，
DashScopeParse会静默跳过，建议先用小测试文件（如一页纯文本 PDF）验证流程 - 使用
SimpleDirectoryReader时，file_extractor的 key 必须严格匹配后缀，例如".pdf"不能写成"pdf"或".PDF"
调试配置必须启用 justMyCode: false
LlamaIndex 内部大量使用异步、装饰器和动态模块加载，VSCode 默认的 justMyCode: true 会跳过所有第三方库断点，导致你在 from_documents 内部无法停住、看不到 index 实际构造过程。
- 在
.vscode/launch.json的配置中，确保包含"justMyCode": false - 调试启动命令应指向你自己的入口脚本，例如
"program": "${workspaceFolder}/rag_app.py"，而非 LlamaIndex 源码 - 如果使用阿里云百炼服务，建议在
rag_app.py开头加一行import logging; logging.basicConfig(level=logging.DEBUG)，观察DashScopeCloudIndex是否发出 HTTP 请求
真正卡住的地方往往不是模型调用，而是文档解析前的路径、权限、API Key 加载顺序——这些在 VSCode 终端里跑一次 python rag_app.py 可能立刻暴露错误，但调试器里却因 justMyCode 设置不当而“一切正常”。
