1、AI程序员系列文章2、AI面试系列文章3、AI编程系列文章一、开篇别让环境搭建劝退你你肯定遇到过这种场景GitHub上找了个看起来很香的RAG项目README写得天花乱坠结果pip install -r requirements.txt一跑红色报错像瀑布一样刷屏——CUDA版本不对、torch和langchain打架、Chroma突然罢工。你开始怀疑人生这到底是AI开发还是系统运维传统教程只会甩给你一句建议用conda创建虚拟环境然后就当甩手掌柜了。这篇就是来填坑的——我把从零搭RAG客服过程中遇到的所有环境问题、版本兼容雷区、GPU驱动选择策略按照踩坑顺序整理成一战指南。看完还搞不定你来找我。二、目录1. 硬件选型先看清你的家底再动手2. 系统环境全对比Ubuntu / Windows / macOS 的修罗场3. GPU vs CPU用CPU跑RAG的残酷现实4. Python 版本选择3.10 为什么是版本答案5. 虚拟环境搭建venv 正确打开方式5.1 为什么不用 conda5.2 从创建到激活手把手教程5.3 关于虚拟环境存放位置5.4 激活失败的抢救方案6. 核心依赖精确版本对照表核心依赖安装命令精确版本对照表已测试兼容的黄金组合安装特别注意torch的版本7. 依赖安装验证代码脚本 输出对照预期输出对照8. CUDA 版本选择11.8 vs 12.1 的灵魂拷问为什么推荐CUDA 12.1CUDA 安装速查9. 常见错误急救手册1. 硬件选型先看清你的家底再动手写代码之前先看看你电脑是骡子是马。RAG虽然不是大模型训练那种烧卡狂魔但对硬件也有硬性门槛。最低配置能跑但别指望多快配置项最低要求推荐配置CPU4核 2.0GHz8核 3.0GHz内存8GB32GBGPU无纯CPU模式16GB显存RTX 3060 12GB起步磁盘20GB空闲50GB模型动辄5-15GB网络能下HuggingFace稳定的科学上网⚠️避坑警告千万不要信了某些教程说的4GB显存够用。Qwen2-7B量化后吃7-8GB显存加上Chroma和embedding模型12GB是及格线。RTX 3060 12GB是性价比之王预算够直接上RTX 4090 24GB。事实就是8GB显存 ≈ 你拿着自行车链条去拧航母螺丝。2. 系统环境全对比Ubuntu / Windows / macOS 的修罗场做AI开发系统选择直接决定你接下来一周是写代码还是修环境。graph TD A[选择操作系统] -- B{生产环境?} B --|是| C[Ubuntu 22.04 LTS] B --|否| D{显卡情况?} D --|NVIDIA GPU| E[Ubuntu 22.04] D --|AMD/Intel| F[Windows 11] D --|Apple Silicon| G[macOS 14 Sonoma] C -- H[最优选择] E -- H F -- I[WSL2 Ubuntu] G -- J[可以但麻烦] I -- K[次优选择]为什么Ubuntu是首选这不是信仰问题——PyTorch CUDA生态在Linux上维护得最好驱动问题少遇到bug社区解决方案最多。Windows用户老老实实上WSL2就行。效率技巧如果你非得用Windows一定要用WSL2不要在原生Windows上直接pip安装torch。WSL2 Ubuntu 22.04 VS Code Remote ≈ 80%的生产力剩下的20%用来骂Windows。macOS用户M1/M2/M3的Metal Performance ShadersMPS后端在PyTorch 2.0进步很大但你的Chroma用的是FAISSFAISS在MPS上…嗯…你可以用CPU模式。3. GPU vs CPU用CPU跑RAG的残酷现实来让我给你算一笔账。# 别急着跑这是数学题 model_size Qwen2-7B # 70亿参数 inference_speed_gpu 30-50 tokens/s # RTX 4090 inference_speed_cpu 2-5 tokens/s # i9-13900K answer_length 500 # token time_gpu 500 / 40 # ≈ 12.5 秒 time_cpu 500 / 3 # ≈ 167 秒 ≈ 2.8 分钟你没看错同样的回答CPU要多等14倍的时间。 如果非要用CPU跑选量化模型GGUF格式 llama.cpp比直接用Transformers库快3-5倍。代价是回答质量下降约5-10%。一个严肃的建议你的设备建议方案无独立显卡用GPT-4o/Claude API别自虐6-8GB显存Qwen2-1.5B int4量化12GB显存RTX 3060Qwen2-7B int4量化RAG全链路无压力24GB显存RTX 4090Qwen2-72B量化不上完整Qwen2-7B 大知识库⚠️避坑警告别以为公司给配了A100就能随便跑。embedding模型也吃显存BGE-large-zh一个embedding就占2GB。跑RAG不等于只跑LLM** embedding reranker LLM 三件套同时跑显存是叠加的。**4. Python 版本选择3.10 为什么是版本答案在Python版本这件事上我踩过最深的一个坑是Python 3.12 LangChain 0.0.2xx TypeError: canonicalize_version() got an unexpected keyword argument strip_trailing_zero。调了一下午最后发现LangChain 0.0.268不支持Python 3.12。各Python版本兼容性速查Python版本LangChain 0.0.268Chroma 0.4.18Transformers 4.40.0推荐度3.8✅✅✅❌ 快EOL了3.10✅✅✅⭐⭐⭐⭐⭐3.11✅✅✅⭐⭐⭐⭐3.12❌✅❌ 别用效率技巧多个Python版本管理强烈推荐pyenvLinux/macOS或pyenv-winWindows。别用系统自带的Python做开发哪天你手抖pip install --upgrade pip把系统Python搞炸了那就等着重装系统吧。⚠️避坑警告Python 3.8的asyncio在新版LangChain里有已知bug。Python 3.9虽然也能跑但2025年10月就EOL了。Python 3.10就是RAG项目的版本答案没有之一。5. 虚拟环境搭建venv 正确打开方式5.1 为什么不用 condaconda很好但它太重了——一个base环境500MB起步。venv是Python官方钦定的虚拟环境工具轻量、无依赖、跨平台。当然如果你已经在用conda管理项目继续用也完全OK。但新建一个RAG项目我选venv。5.2 从创建到激活手把手教程# 确认Python版本 python3 --version # 输出应有Python 3.10.x # 创建虚拟环境 python3 -m venv rag_env # 激活虚拟环境 # macOS / Linux: source rag_env/bin/activate # Windows (CMD): rag_env\Scripts\activate.bat # Windows (PowerShell): rag_env\Scripts\Activate.ps1看到终端前面多了(rag_env)前缀恭喜你环境激活成功。graph LR A[python3 -m venv rag_env] -- B{环境创建完成} B -- C[rag_env/bin/python] B -- D[rag_env/bin/pip] B -- E[rag_env/lib/python3.10/site-packages] C -- F[source rag_env/bin/activate] D -- F E -- F F -- G[(rag_env) $]5.3 关于虚拟环境存放位置# ❌ 不要这样 # 把虚拟环境放在项目里 my-rag-project/ rag_env/ # 200MB谁把venv提交到git我跟谁急 app.py requirements.txt # ✅ 建议这样 # 把虚拟环境统一放在 ~/venvs/ 下 mkdir -p ~/venvs python3 -m venv ~/venvs/rag_env source ~/venvs/rag_env/bin/activate # 然后 cd 到项目目录工作效率技巧把 virtualenv 放在项目外部好处太多了gitignore不用写一堆规则多个项目共享同一份环境误删项目文件夹不会连带丢了环境VSCode配置.vscode/settings.json指定Python路径更干净{ python.defaultInterpreterPath: ~/venvs/rag_env/bin/python }5.4 激活失败的抢救方案Windows PowerShell执行策略限制# 报错无法加载文件 xx.ps1因为在此系统上禁止运行脚本 # 解决方案用CMD激活 rag_env\Scripts\activate.bat # 或者修改PowerShell执行策略需要管理员权限 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser rag_env\Scripts\Activate.ps1macOS/Linux zsh找不到activate# 常见原因你不在项目目录 # 解决方案用绝对路径 source ~/venvs/rag_env/bin/activate # 或者每次先 cd 到项目目录再 source cd ~/projects/rag-customer-service source ~/venvs/rag_env/bin/activate⚠️避坑警告永远不要sudo pip install这会把依赖装的系统级Python目录里污染全局环境。如果你遇到了Permission denied错误说明你在虚拟环境外执行了pip——check一下前面的(rag_env)还在不在。6. 核心依赖精确版本对照表这套版本组合是我在Ubuntu 22.04 Python 3.10 CUDA 12.1 RTX 4090上跑通RAG全链路文档加载→文本分割→向量存储→检索→LLM生成的稳定组合。⚠️避坑警告不要直接复制别人的requirements.txt就用。不同CUDA版本、不同GPU、不同Python依赖版本可能都需要微调。下面这个版本表是我们测过的稳定组合但也请在虚拟环境里先测试再部署。核心依赖安装命令# 确保在虚拟环境内 # 用pip安装前先升级pip本身 pip install --upgrade pip setuptools wheel # 核心三件套精确版本 pip install langchain0.0.268 pip install chromadb0.4.18 pip install transformers4.40.0 # 向量计算和文本处理 pip install sentence-transformers2.2.2 pip install faiss-cpu1.7.4 # 无GPU用这个 # pip install faiss-gpu1.7.4 # 有GPU用这个 # LLM推理框架 pip install accelerate0.27.2 pip install bitsandbytes0.43.0 # 文档解析 pip install pypdf3.17.4 pip install python-docx1.1.0 pip install markdown3.5.1 # Web框架后续API用 pip install fastapi0.109.0 pip install uvicorn0.27.0 # 其他工具 pip install tiktoken0.5.2 pip install sentencepiece0.1.99 pip install nltk3.8.1精确版本对照表已测试兼容的黄金组合依赖包推荐版本最低版本作用版本说明langchain0.0.2680.0.240RAG框架核心0.0.240以下缺DocumentLoader0.0.270API有breaking changechromadb0.4.180.4.10向量数据库与langchain 0.0.268兼容0.4.22与langchain通信方式变了transformers4.40.04.32.0HuggingFace模型加载4.40.0支持Qwen2-7B降级4.32.0可跑Qwen-1.8Bsentence-transformers2.2.22.2.0文本embedding加载BGE系列模型专用2.3.x改了模型命名规则faiss-cpu1.7.41.7.3向量检索CPU与chromadb互不冲突faiss-gpu1.7.41.7.3向量检索GPU需要CUDA 11.8accelerate0.27.20.25.0分布式推理加速配合transformers做model parallelismbitsandbytes0.43.00.41.0模型量化4/8bitWindows用户注意0.43.0才稳定支持Windowspypdf3.17.43.10.0PDF文档解析3.15.0修复了大量中文PDF乱码bugtiktoken0.5.20.4.0token计数OpenAI的tokenizerlangchain内部依赖fastapi0.109.00.104.0API框架后续构建RAG服务接口用uvicorn0.27.00.24.0ASGI服务器给fastapi跑服务的安装特别注意torch的版本PyTorch不列入上面的版本表是因为它的安装方式和其他依赖不一样——你需要根据自己的CUDA版本选择安装命令。graph TD A[开始安装PyTorch] -- B{有NVIDIA GPU?} B --|有| C{知道CUDA版本?} B --|没有| D[pip install torch --index-url https://download.pytorch.org/whl/cpu] C --|CUDA 11.8| E[pip install torch2.1.0 --index-url https://download.pytorch.org/whl/cu118] C --|CUDA 12.1| F[pip install torch2.1.0 --index-url https://download.pytorch.org/whl/cu121] C --|不知道| G[运行 nvidia-smi 查看CUDA版本] G -- C# CUDA 11.8 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118 # CUDA 12.1 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu121 # CPU only pip install torch2.1.0 --index-url https://download.pytorch.org/whl/cpu⚠️避坑警告千万不要pip install torch从默认源安装它会给你装CPU版torch然后你后面加载模型时怎么都找不到CUDA——你以为装了GPU版实际是CPU版在负重前行。7. 依赖安装验证代码脚本 输出对照环境搭建完不验证等于买了保险不看条款——出事了才知道白搭。创建一个验证脚本check_env.py RAG环境验证脚本 运行方式python check_env.py 输出对照见下方 import sys import platform import subprocess from importlib import import_module def check_version(package_name, min_versionNone): 检查包是否安装及版本 try: mod import_module(package_name) version getattr(mod, __version__, unknown) status ✅ if min_version: from packaging.version import Version if Version(version) Version(min_version): status ⚠️ return f{status} {package_name}{version} except ImportError: return f❌ {package_name} 未安装 def check_torch(): 详细检查PyTorch及CUDA try: import torch print(f PyTorch版本: {torch.__version__}) print(f CUDA是否可用: {torch.cuda.is_available()}) if torch.cuda.is_available(): print(f CUDA版本: {torch.version.cuda}) print(f GPU型号: {torch.cuda.get_device_name(0)}) print(f 显存总量: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB) # MPS (Apple Silicon) if hasattr(torch, backends) and hasattr(torch.backends, mps): print(f MPS是否可用: {torch.backends.mps.is_available()}) return True except ImportError: print( ❌ PyTorch未安装) return False def main(): print( * 50) print( RAG环境验证报告) print( * 50) # 系统信息 print(f\n 系统信息:) print(f 操作系统: {platform.system()} {platform.release()}) print(f Python版本: {sys.version.split()[0]}) print(f 架构: {platform.machine()}) # Python版本验证 py_version sys.version_info if py_version (3, 10) and py_version (3, 12): print( 版本状态: ✅ Python版本符合要求) else: print( 版本状态: ⚠️ 推荐Python 3.10或3.11) # 核心依赖检查 print(f\n 核心依赖:) deps [ (langchain, 0.0.240), (chromadb, 0.4.10), (transformers, 4.32.0), ] for name, min_ver in deps: print(f {check_version(name, min_ver)}) # 辅助依赖 print(f\n 辅助依赖:) extra_deps [ sentence_transformers, faiss, accelerate, bitsandbytes, pypdf, tiktoken, sentencepiece, fastapi, uvicorn ] for dep in extra_deps: print(f {check_version(dep)}) # PyTorch CUDA print(f\n PyTorch / CUDA:) check_torch() # Chroma连接测试 print(f\n️ Chroma连接测试:) try: import chromadb client chromadb.Client() collection client.create_collection(test_collection) collection.add( documents[这是一条测试文档], ids[test1] ) results collection.query(query_texts[测试], n_results1) print(f ✅ Chroma读写正常: {results}) client.delete_collection(test_collection) except Exception as e: print(f ❌ Chroma测试失败: {e}) # 检查虚拟环境 print(f\n 虚拟环境检查:) if hasattr(sys, real_prefix) or ( hasattr(sys, base_prefix) and sys.base_prefix ! sys.prefix ): print(f ✅ 在虚拟环境中运行: {sys.prefix}) else: print(f ⚠️ 未检测到虚拟环境可能用的是系统Python) print(\n * 50) print( 验证完成) print( * 50) if __name__ __main__: main()预期输出对照成功输出含GPU RAG环境验证报告 系统信息: 操作系统: Linux 6.5.0-26-generic Python版本: 3.10.12 架构: x86_64 版本状态: ✅ Python版本符合要求 核心依赖: ✅ langchain0.0.268 ✅ chromadb0.4.18 ✅ transformers4.40.0 辅助依赖: ✅ sentence_transformers2.2.2 ✅ faiss1.7.4 ✅ accelerate0.27.2 ✅ bitsandbytes0.43.0 ✅ pypdf3.17.4 ✅ tiktoken0.5.2 ✅ sentencepiece0.1.99 ✅ fastapi0.109.0 ✅ uvicorn0.27.0 PyTorch / CUDA: PyTorch版本: 2.1.0cu121 CUDA是否可用: True CUDA版本: 12.1 GPU型号: NVIDIA GeForce RTX 4090 显存总量: 24.0 GB ️ Chroma连接测试: ✅ Chroma读写正常 虚拟环境检查: ✅ 在虚拟环境中运行: /home/user/venvs/rag_env 验证完成 效率技巧把check_env.py放进你的项目根目录。每次换机器、重装环境、CI/CD部署时先跑一遍这个脚本。如果输出全是 ✅那就可以放心继续了。如果有 ❌逐个排查。这个脚本我用了三年救了我至少十次命。8. CUDA 版本选择11.8 vs 12.1 的灵魂拷问CUDA版本选不对后面全是泪。先给你结论新机器直接上CUDA 12.1别纠结。# 查看当前CUDA版本 nvidia-smi # 右上角会显示 CUDA Version: 12.1 # 或者 nvcc --versiongraph TD A[怎么选CUDA版本?] -- B{显卡是什么?} B --|RTX 30系列| C[CUDA 11.8 - 安全兼容] B --|RTX 40系列| D[CUDA 12.1 - 推荐] B --|A100/H100| E[CUDA 12.1] B --|RTX 20系列及更早| C C -- F{用bitsandbytes?} D -- F F --|是| G[推荐CUDA 12.1] F --|否| H[CUDA 11.8也可以] G -- I[bitsandbytes 0.43.0 CUDA 12.1 是黄金组合] H -- J[但注意: bitsandbytes在CUDA 11.8上可能报错]为什么推荐CUDA 12.1bitsandbytes的兼容性0.43.0版本以后bitsandbytes对CUDA 12.x做了针对性优化CUDA 11.8上跑int4量化偶尔会报CUDA error: no kernel image is available for execution on the devicePyTorch 2.1 默认支持CUDA 12.1从官方源安装torch时cu121版本是默认选择RTX 40系列新架构Ada Lovelace架构在CUDA 12.x上才能发挥全部性能CUDA 安装速查# Ubuntu 22.04 安装 CUDA 12.1 wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt-get update sudo apt-get -y install cuda-12-1 # 配置环境变量加到 ~/.bashrc echo export PATH/usr/local/cuda-12.1/bin:$PATH ~/.bashrc echo export LD_LIBRARY_PATH/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH ~/.bashrc source ~/.bashrc⚠️避坑警告千万不要sudo apt install nvidia-cuda-toolkit这装的是Ubuntu仓库里远古版本的CUDA9.x系列装完你会怀疑为什么PyTorch说找不到CUDA 12.x。⚠️避坑警告如果你系统中已有CUDA 11.8装了CUDA 12.1后两个版本会共存。用update-alternatives来切换默认版本sudo update-alternatives --config cuda日常开发时通过环境变量指定用哪个版本不要动系统的/usr/local/cuda软链接。9. 常见错误急救手册自己在踩坑时遇到的群里也经常有人问的问题整理成小程序方便下次遇到直接搜方案。错误信息原因解决方案ModuleNotFoundError: No module named langchain.document_loadersLangChain版本过低 (0.0.240)pip install langchain0.0.268pysqlite3.OperationalError: no such table: collectionsChroma依赖的sqlite3版本不兼容安装pysqlite3-binary或升级python到3.10CUDA error: no kernel image is available for execution on the devicebitsandbytes与CUDA版本不匹配升级到bitsandbytes 0.43.0 且CUDA 12.1RuntimeError: LayerNormKernelImpl not implemented for Half半精度浮点数与模型不兼容添加model.half()或用torch.float16ImportError: cannot import name validate_environment from langchain.schemaLangChain版本混乱重装pip uninstall langchain pip install langchain0.0.268requests.exceptions.ConnectionError: Failed to resolve huggingface.co网络问题无法访问HuggingFace配置镜像站export HF_ENDPOINThttps://hf-mirror.comValueError: SQLite version too low, need 3.35Python内置sqlite3版本过旧Windows下删除python3.dll目录下的sqlite3.dllOSError: [WinError 126] The specified module could not be foundWindows下torch依赖的CUDA DLL找不到确认CUDA Toolkit完整安装检查PATH环境变量效率技巧把上面这张表保存成troubleshooting.md放在项目根目录每次遇到问题先在本地查比上网搜快10倍。而且这些问题不是可能遇到——是一定会遇到提前存好等于预判了错误的预判。文末三件套 源码获取这篇的环境验证脚本check_env.py以及完整的requirements.txt都已整理好。 关注获取后续更新后台回复“RAG客服”获取完整环境和配置文件包含check_env.py— 环境验证脚本上面贴的完整版requirements.txt— 精确版本锁定版后续每篇的配套代码 思考题学完不思考等于白学试试回答这几个问题Chroma 0.4.18 升级到 0.4.22 后和 LangChain 0.0.268 的兼容性问题具体是什么如果一定要升级ChrombaLangChain需要怎么配合调整提示看看Chroma的Python SDK API变化在同一个虚拟环境里同时装faiss-cpu和faiss-gpu会怎样如果不想同时装两个有什么更优雅的方式在CPU/GPU间切换提示看看FAISS的GpuIndexFlatIP是怎么初始化的Transformers 4.40.0 支持了Qwen2系列但你有一个老项目用了Qwen-1.8B需要 transformers 4.32.0 以下。如果不降级transformers有什么办法能让两个模型共存提示思考transformers的模型加载机制和trust_remote_code参数 系列文章预告篇号标题状态01RAG客服系统设计从架构到落地的完整方案✅ 已发布02RAG环境从零搭建——Python虚拟环境与核心依赖安装的避坑实战✅ 本篇03Qwen2-7B本地部署全流程从HuggingFace下载到Tokenizer对齐 下一篇发布04LangChain Chroma 知识库构建文档加载、文本分割与向量存储敬请期待05RAG客服API封装FastAPI LangChain服务化部署敬请期待下一篇预告环境就绪后我们将实测Qwen2-7B本地部署全流程——从HuggingFace下载模型、Tokenzier对齐踩坑、int4量化加速到跑通第一条你好我是客服小R的完整回答。️ 标签#环境搭建 #Python虚拟环境 #LangChain #Chroma #依赖安装 #GPU配置 #RAG本文基于真实项目踩坑记录。如果本文对你有帮助欢迎点赞、收藏、转发让更多小伙伴少走弯路。
