《Local_Pdf_Chat_RAG 深度学习笔记：PDF 本地化对话的 RAG 原理与实践》

在处理本地 PDF 文档的智能对话需求时，很多人会面临 “云端依赖泄露隐私”“开源项目部署门槛高” 的问题 —— 而 GitHub 上的 Local_Pdf_Chat_RAG 项目，恰好以 “本地化部署 + RAG 技术” 为核心，解决了 PDF 文档的高效检索与自然语言对话难题。近期我系统学习了这个项目，从环境搭建、代码核心模块拆解，到实际场景测试与调优，踩过不少新手常见的坑，也总结了一套可复用的实践经验。因此整理这份学习笔记，一方面记录自己的技术成长，另一方面希望能帮到同样想入门 “本地 PDF+RAG” 的朋友。整篇笔记会围绕「环境准备→核心组件解析（PDF 加载 / 向量存储 / 对话逻辑）→部署测试→问题排查」四个维度展开，尽量兼顾原理讲解与实战操作，适合有 Python 基础、对 RAG 技术感兴趣的学习者参考。

一、环境准备：从依赖到服务的完整搭建

Local_Pdf_Chat_RAG 项目的核心优势是 “本地化部署”，但新手常因环境配置不完整导致项目启动失败。本节将按 “系统要求→Python 环境→核心依赖→服务启动” 的顺序，提供可复现的操作步骤，规避常见的 “依赖冲突”“服务失联” 问题。

1.1 基础系统与硬件要求

项目对硬件的要求主要取决于本地模型的规模（如 7B 模型需至少 16GB 内存，120B 模型需 64GB+ 内存），系统需满足以下条件：

• 操作系统：Windows 10/11（PowerShell 5.1+）、Linux（Ubuntu 20.04+）、macOS 12+（M1/M2 芯片需开启 Rosetta 兼容）；
• 权限：本地磁盘读写权限（用于存储 PDF 文档、向量数据库缓存）；
• 网络：首次部署需联网下载依赖和模型（无需科学上网，可通过国内镜像加速）。

1.2 Python 环境配置

项目依赖 Python 3.8~3.11（3.12+ 可能存在部分库兼容性问题），建议使用虚拟环境隔离依赖：

步骤 1：创建并激活虚拟环境

• Windows（PowerShell）：

  powershell

  # 安装虚拟环境工具（若未安装）
  pip install virtualenv
  # 在项目根目录创建虚拟环境
  virtualenv .venv
  # 激活虚拟环境
  .\.venv\Scripts\Activate.ps1
  

• Linux/macOS（终端）：

  bash

  # 创建虚拟环境
  python3 -m venv .venv
  # 激活虚拟环境
  source .venv/bin/activate
  

步骤 2：配置国内镜像（解决依赖下载慢）

在虚拟环境中执行以下命令，优先使用阿里云镜像：

bash

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

1.3 核心依赖安装

项目依赖分为 “基础工具库”“RAG 核心库”“本地化服务库” 三类，可通过 requirements.txt 批量安装（建议手动创建该文件，避免版本冲突）：

1.3.1 编写 requirements.txt

txt

# 基础工具库（PDF 提取、文本处理）
pdfminer.six==20221105  # PDF 文本提取（比 PyPDF2 准确率更高）
jieba==0.42.1  # 中文分词（用于 BM25 检索）
langchain-text-splitters==0.2.2  # 文本分块（RecursiveCharacterTextSplitter）
python-dotenv==1.0.1  # 环境变量管理（读取 .env 文件）

# RAG 核心库（向量生成、检索、重排序）
sentence-transformers==2.7.0  # 嵌入模型（生成文本向量）
faiss-cpu==1.7.4  # 向量数据库（轻量版，GPU 版需装 faiss-gpu）
rank-bm25==0.2.2  # BM25 关键词检索（与向量检索混合提升精度）

# 本地化服务库（Web 界面、模型调用）
gradio==4.44.1  # Web 交互界面（避免用 5.x 版本，部分 API 不兼容）
requests==2.32.3  # HTTP 请求（调用 Ollama/SiliconFlow 服务）
urllib3==2.2.2  # 解决 requests 依赖冲突

1.3.2 执行安装命令

bash

pip install -r requirements.txt

1.3.3 特殊依赖：HF 镜像配置（无需科学上网）

项目需下载 sentence-transformers 嵌入模型（如 all-MiniLM-L6-v2），默认从 Hugging Face 官网下载较慢，需配置国内镜像 hf-mirror.com：

• 临时生效（仅当前终端）：
  • Windows（PowerShell）：$env:HF_ENDPOINT = "https://hf-mirror.com"
  • Linux/macOS（终端）：export HF_ENDPOINT=https://hf-mirror.com
• 永久生效：
  • Windows：将 $env:HF_ENDPOINT = "https://hf-mirror.com" 写入 ~\.bashrc（需安装 Git Bash）；
  • Linux：将 export HF_ENDPOINT=https://hf-mirror.com 写入 ~/.bashrc，执行 source ~/.bashrc 生效。

1.4 Ollama 服务与模型部署

项目默认使用 Ollama 运行本地大模型（如 gpt-oss:120b-cloud），需先安装 Ollama 并拉取模型：

步骤 1：安装 Ollama

• 下载地址：Ollama 官网（Windows 需勾选 “添加到 PATH”，Linux/macOS 按官网脚本安装）；
• 验证安装：终端执行 ollama --version，输出 ollama version 0.1.xx 即成功。

步骤 2：拉取本地模型

根据硬件配置选择模型（新手推荐先试小模型如 deepseek-r1:1.5b，再用大模型 gpt-oss:120b-cloud）：

bash

# 拉取 gpt-oss:120b-cloud（用户实际使用的模型）
ollama pull gpt-oss:120b-cloud
# 拉取轻量模型（测试用）
ollama pull deepseek-r1:1.5b

步骤 3：启动 Ollama 服务

项目需通过 Ollama 的 API 调用模型，需先启动服务：

• Windows：无需手动启动，拉取模型后自动后台运行；
• Linux/macOS：终端执行 ollama serve（需保持终端开启，关闭则服务停止）；
• 验证服务：浏览器访问 http://localhost:11434，显示 “Ollama is running” 即成功。

1.5 .env 文件配置（敏感信息管理）

项目需配置 SERPAPI_KEY（联网搜索功能）、SILICONFLOW_API_KEY（云端模型备用），避免硬编码泄露信息。在项目根目录创建 .env<