许多新手在搭建第一个 RAG 系统时，常因环境配置和版本兼容等细节问题卡住，耗费大量时间。这篇指南提供了一套经过验证的稳定方案和完整代码，通过避坑指南，帮助开发者在 1 小时内成功跑通首个 RAG 项目，专注于核心逻辑而非环境调试。
智能速览
推荐一套适配新手场景的稳定环境组合。
提供从文档加载到问答的完整可运行代码。
总结了 5 个新手最容易踩的“致命坑”及解决方法。
指出 Ollama 调用超时应将 base_url 改为 127.0.0.1。
强调检索为空多为 embedding 模型不一致导致。
精华内容
RAG 落地的成功关键在于细节。以下将从核心环境配置、完整代码实现、以及避坑指南三个维度，深度拆解整个流程，确保每一步都清晰可执行。
稳定环境配置
新手落地 RAG 的首要难题是环境不稳定。推荐使用 Python 3.8~3.10 版本，并固定安装 LangChain 0.1.20 与 langchain-community 0.0.38。这套组合经过了广泛测试，能有效避免因版本过高或依赖冲突引发的频繁报错，为后续开发打下坚实基础。核心依赖安装命令可参考原文，使用国内源加速，确保安装过程顺畅。
核心代码实现
完整的 RAG 流程包含五个核心步骤。首先，使用 PyPDFLoader 加载本地 PDF 文档。其次，通过 RecursiveCharacterTextSplitter 将文档切分为合适的文本块。然后，利用 HuggingFaceEmbeddings 模型将文本块转化为向量并存入 Chroma 向量数据库。接着，本地部署 Ollama 的 deepseek-r1 模型作为大语言模型。最后，通过 RetrievalQA 链将检索与问答结合，实现基于文档的智能问答。
五大致命避坑
90% 的新手都会遇到以下问题。
第一，检索为空，通常是入库和检索时使用的 embedding 模型不一致，或向量库路径错误，需确保模型统一并重建索引。
第二，Ollama 调用超时，关键在于 langchain-community 版本不兼容 localhost，必须将 base_url 修改为 http://127.0.0.1:11434。
第三，模型回答胡说八道，根源是 Prompt 模板未做限制，必须明确指令模型“仅根据上下文回答”，禁止编造。
第四，Token 超限导致无法生成，可调整 chunk_size 至 500-800，并设置检索器 k 值为 2-3。
第五，环境安装报错，多为 Python 版本过高或依赖未固定，务必降级 Python 并按指定版本安装。
新手实操建议
RAG 落地的核心在于“稳定环境+规范流程+避开细节坑”。新手无需求多求全，严格按照一套经过验证的流程操作，就能在短时间内跑通第一个项目。遇到问题时，优先检查环境配置和代码细节，往往能快速定位并解决。
掌握了这套从环境配置到避坑指南的完整流程，意味着新手已经攻克了 RAG 落地的最大难点。未来可以在此基础上探索更高级的 RAG 技术，如多模态检索或 Agent 集成，开启更广阔的 AI 应用开发之路。
