从零开始学习RAG——01 环境搭建

完整开发环境配置手册 — RAG from scratch(Ollama 版)

项目根:…\\rag-from-scratch 解释器:…\\python3.12\\python.exe(Python 3.12)+ venv 向量模型:Ollama 本地服务 bge-m3(GPU,1024 维) 检索:faiss-cpu | 生成:远程 Qwen API(dashscope) 硬件:GTX 1050Ti 4GB (Pascal sm_61) / i7-6700 / 32GB RAM | IDE:PyCharm 2025.3.3

1. 总览 — 用前必读

新架构

用户问题
↓
[Python pipeline]
├─ ① 问题向量化 → HTTP → Ollama 服务(bge-m3, GPU)
├─ ② faiss-cpu 检索 top-k(本地内存)
├─ ③ (进阶)重排 —— 注意:Ollama 不支持 cross-encoder,见文末说明
└─ ④ 组装 prompt → Qwen API(qwen-plus)生成答案

为什么 bge-m3? Ollama 官方库中对中文效果最好的 embedding 模型:多语言、8192 长上下文、1024 维,~1.2GB,1050Ti 轻松跑。备选:shaw/dmeta-embedding-zh(社区中文专用,768 维)。

阶段 1 — 前置环境确认

这一步的目的:在动手改任何配置之前,先确认四个基石都在位——Python 解释器、Ollama 客户端、Ollama 后台服务、磁盘空间。全部是只读检查,不改任何东西。

打开 cmd,逐条执行:

:: 【执行位置】任意目录(无需 venv;命令均为绝对路径)

echo — Python —
:: 用完整路径调解释器,打印版本号
:: 为什么用完整路径:PATH 里排在前面的可能是 Anaconda,直接敲 python 可能命中错误版本
E:…python3.12\\python.exe -V
:: 期望: Python 3.12.x(项目约定 3.12,不兼容 3.13,原因见常见坑 wikiextractor 一行)

echo — Ollama —
:: 查看 Ollama 客户端版本;注意这只是 CLI 版本,不代表后台服务已启动
ollama –version
:: 期望: client version is 0.30.5 或更高(更新到 0.34+ 更好)

echo — Ollama 服务 —
:: -s 表示静默模式,只输出响应体
curl -s http://localhost:port/api/version
:: 期望: {\”version\”:\”…\”} 一段 JSON
:: 若报 could not connect:从开始菜单启动 Ollama,或命令行直接敲 ollama(会自动拉起服务)

echo — 磁盘 —
:: 列出 E 盘信息并用 findstr 过滤出含\”可用\”字样的那一行(即剩余空间)
:: 维基 dump 解压后约 8GB + 向量索引若干 GB,所以至少要 10GB 余量
dir E:\\ | findstr \”可用\”
:: 确认 E 盘 ≥ 10GB 可用

• Python 3.12 就位
• Ollama 服务响应正常
• E 盘 10GB+ 空闲

💡 GPU 无需额外配置:Ollama 基于 llama.cpp,原生支持 Pascal(sm_61)及以上的 NVIDIA 卡,1050Ti 自动用 GPU。运行模型时用 ollama ps 可确认(显示 100% GPU 即在用显卡)。

阶段 2 — 缓存全部指向 E 盘(C 盘零占用)

这一步的目的:pip 下载的包缓存、HuggingFace 模型缓存、临时文件,默认全都写进 C 盘用户目录,日积月累能吃掉十几 GB。这一步把三个\”吃盘大户\”全部重定向到 E 盘,保证 C 盘零新增。

:: 【执行位置】任意目录(无需 venv;均为绝对路径/全局配置)

:: 一次性创建三个缓存目录(pip 包缓存 / HF 模型缓存 / 临时文件区)
:: mkdir 支持一次建多个,空格分隔;目录已存在时该命令不报错、不覆盖
mkdir E:…\\pip-cache E:…\\hf-cache E:…\\tmp

:: 把 pip 的全局下载缓存目录指向 E 盘(写入 pip.ini,永久生效)
:: 效果:以后 pip install 下载的 wheel 包(单个可达 2~3GB)都落在 E 盘
pip config set global.cache-dir E:…\\pip-cache

:: 设置 HF_HOME 用户级环境变量(setx 写入注册表,对所有新进程生效)
:: 作用:HuggingFace 系工具(datasets 等)下载的模型/数据集缓存全部改存此处
setx HF_HOME …\\hf-cache

:: 把系统临时目录也指向 E 盘(可选,进一步保险)
:: 某些安装过程会把临时文件写进 TMP/TEMP,一并重定向最干净
setx TMP …\\tmp
setx TEMP …\\tmp

setx 后关掉当前 cmd,重开一个新窗口再验证(已开着的窗口读不到新变量——2026-09-19 实测踩坑):

:: 【执行位置】任意目录(必须在 setx 后【重开的新窗口】里执行)

:: 打印 HF_HOME 环境变量的当前值,验证重定向是否生效
echo %HF_HOME%
:: 期望: …\\hf-cache
:: 若输出 %HF_HOME% 原样,说明窗口是旧的,关掉重开

• TMP/TEMP 那两条可选,跳过也行——大头是 pip cache 和 HF_HOME。
• HF_ENDPOINT=https://hf-mirror.com 你早已设好(用户级),无需重复。

阶段 3 — 创建虚拟环境

日常使用只需激活:

:: 【执行位置】E:…\\rag-from-scratch(本块目的就是激活项目 venv)

:: 进入项目根目录(venv 绑定在项目里,必须先到位)
cd /d …\\rag-from-scratch

:: 激活虚拟环境:把 .venv\\Scripts 插到 PATH 最前面
:: 之后 python/pip 全部指向 .venv 内部,与全局(含 Anaconda)完全隔离
.venv\\Scripts\\activate

• 前缀出现 (.venv),python -V 为 3.12.x

⚠️ 当年建 venv 必须用完整路径的原因:避免命中 PATH 里的 Anaconda。你的 venv 已正确绑定 …\\python3.12,无需处理。

阶段 4 — pip 换清华源

这一步的目的:PyPI 官方源服务器在国外,直连下载经常只有几十 KB/s 甚至超时。清华 TUNA 镜像在国内同步了全部 PyPI 包,下载速度能到几十 MB/s。此配置写进全局 pip.ini,一次配置永久生效。

配置全局 pip.ini

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

如需复核:

:: 【执行位置】任意目录(无需 venv)

:: 列出 pip 当前生效的全部配置项,确认镜像源已写入
pip config list
:: 期望看到 global.index-url=https://pypi.tuna.tsinghua.edu.cn/simple

阶段 5 — 装依赖

这一步的目的:把项目所需的全部 Python 库一次性装进 venv。清单在 requirements.txt 里,带版本约束(如 numpy<2 防冲突),保证装出来的环境可复现。

先确认已激活 venv(前缀 (.venv)),否则会装进全局 Python,白装一遍。

:: 【执行位置】…\\rag-from-scratch · venv 已激活(装进项目,不要装进全局)

:: 先切到项目根(venv 和 requirements.txt 都在这里)
cd /d …\\rag-from-scratch

:: 激活 venv(新开的窗口必须重新激活,激活状态不跨窗口)
.venv\\Scripts\\activate

:: 按 requirements.txt 清单批量安装;-r 表示从文件读取依赖列表
:: 走清华源,2~3 分钟装完;全部装进 .venv\\Lib\\site-packages
pip install -r requirements.txt

# RAG from scratch — Python 3.12
# 架构:Ollama(bge-m3 向量) + faiss-cpu(检索) + Qwen API(生成)
# 好消息:向量模型由 Ollama 服务化提供,Python 侧不再需要 torch / sentence-transformers
# (注意:若日后要加 cross-encoder 重排器,Ollama 不支持,届时再单独引入 torch)

faiss-cpu>=1.8
numpy>=1.26,<2.0 # 锁 <2.0,防 faiss-cpu DLL 冲突
requests>=2.31 # 调 Ollama REST API(/api/embed)
dashscope>=1.20
tiktoken>=0.7
jieba>=0.42
wikiextractor>=3.0.6 # 仅支持到 Python 3.12(cgi 模块 3.13 被移除)
datasets>=2.20
tqdm>=4.66
python-dotenv>=1.0

清单:faiss-cpu、numpy(<2.0)、requests、dashscope、tiktoken、jieba、wikiextractor、datasets、tqdm、python-dotenv。

没有 torch / sentence-transformers——向量模型走 Ollama 服务,Python 只负责调 HTTP API。若日后加 cross-encoder 重排器再单独引入 torch(见文末)。

验证:

:: 【执行位置】项目根 · venv 已激活

:: 一行代码同时 import 五个核心库,任何一个装失败都会在这里抛 ImportError
:: 全部成功则打印\”全部安装成功\”
python -c \”import faiss, requests, dashscope, jieba, tiktoken; print(\’全部安装成功\’)\”

阶段 6 — Ollama 向量模型

这一步的目的:embedding 模型是这个 RAG 系统的\”翻译官\”——把文字变成 1024 维向量,语义相近的文本向量距离就近。它由 Ollama 本地服务化运行,GPU 加速,Python 侧只发 HTTP 请求。

6.1 拉取模型