纯本地 RAG 系统部署详细教程:DeepSeek+BGE+FAISS

部署流程整体步骤介绍

本次纯本地离线 RAG 系统完整部署,严格遵循环境搭建→依赖安装→本地模型离线下载→项目文件配置→PDF 知识库准备→向量库构建→本地大模型加载→RAG 问答逻辑调试→项目运行测试→问题优化排错十大标准化流程,全程断网可用、无云端 API 调用、无需密钥授权、全程屏蔽运行警告。整体部署逻辑由浅入深、层层递进:先搭建隔离独立的 Python 虚拟运行环境,规避多项目依赖冲突;再批量安装 PDF 解析、文本分割、向量数据库、大模型推理全套依赖库;接着手动下载 DeepSeek 大语言模型、BGE 中文嵌入模型两大核心模型至本地缓存目录,实现全离线加载;随后配置项目路径、离线环境变量、文档读取规则;通过代码完成 PDF 文本提取、长文本智能分割、语义向量化处理、FAISS 本地向量库写入存储;加载本地离线大模型与分词器,封装 RAG 检索 + 大模型生成一体化问答逻辑;最后放入测试 PDF 文档,执行代码完成问答实测,并配套常见报错排查、参数调优、功能扩展方案,零基础可一步步跟着操作落地,全程实操化、代码化、细节化,确保每一步部署均可复现。

前言

在人工智能快速普及的今天,RAG(检索增强生成)技术成为企业和个人搭建私有知识库、实现精准问答的核心方案。但市面上绝大多数 RAG 教程依赖云端 API、需要密钥、存在数据隐私泄露风险,且无法完全离线运行。

本教程基于纯本地部署理念 ,手把手教你搭建一套DeepSeek 本地大模型 + BGE 中文嵌入模型 + FAISS 向量数据库的完整 RAG 系统,全程无 API、无密钥、无网络依赖、无警告报错,支持本地 PDF 文件导入向量库,实现私有数据的精准问答。教程包含环境配置、模型下载、代码解析、实战调试、问题排查全流程,总字数超 5000 字,新手也能零基础完成部署。

一、本地 RAG 系统核心原理与技术栈介绍

1.1 什么是纯本地 RAG?

RAG = 检索(Retrieve)+ 生成(Generate),核心逻辑是:先从本地私有文档中检索与用户问题相关的内容→将检索内容作为上下文输入本地大模型→大模型基于真实文档内容生成精准答案。纯本地 RAG 的核心优势:

  1. 数据绝对安全:所有文档、模型、计算都在本地电脑运行,无数据上传云端;
  2. 无成本依赖:无需购买 API 服务、无需充值,永久免费使用;
  3. 离线可用:断网状态下也能正常运行,不受网络限制;
  4. 无警告无报错:优化环境配置,屏蔽冗余警告,运行稳定。

1.2 本教程技术栈详解

表格

组件 名称 作用
大语言模型 DeepSeek-Coder-1.3B-Instruct 本地轻量级开源大模型,负责理解问题、生成答案,支持中文问答
嵌入模型 BGE-Small-ZH-v1.5 中文最优轻量级嵌入模型,将文本转换为向量,用于语义检索
向量数据库 FAISS Facebook 开源本地向量库,存储文档向量、快速检索相似内容
文档处理 PyPDF 解析本地 PDF 文件,提取文本内容
文本分割 LangChain 拆分长文本为小片段,适配向量库存储和模型输入
运行环境 Python+Torch 核心运行环境,支持模型加载与推理

1.3 硬件要求(零基础友好)

本教程选用轻量级模型,低配电脑也能流畅运行:

  • 最低配置:CPU(i5-8 代以上)+ 8G 内存;
  • 推荐配置:CPU(i7-10 代以上)+ 16G 内存;
  • 无显卡要求:全程 CPU 运行,无需 NVIDIA 显卡,不依赖 CUDA。

二、环境准备:Python 与依赖库安装

2.1 Python 环境安装

本教程基于 Python 3.10(稳定兼容版,推荐新手使用),步骤如下:

  1. 打开 Python 官网:https://www.python.org/downloads/release/python-3100/
  2. 下载对应系统的安装包(Windows 选 Windows installer,Mac 选 macOS installer);
  3. 安装时务必勾选 Add Python to PATH(自动配置环境变量);
  4. 安装完成后,打开 CMD / 终端,输入命令验证:

bash

运行

复制代码
python --version

出现Python 3.10.x即安装成功。

2.2 创建虚拟环境(推荐,避免依赖冲突)

虚拟环境可以隔离不同项目的依赖库,是 Python 开发的最佳实践:

bash

运行

python 复制代码
# 1. 创建项目文件夹(自定义名称,如LocalRAG)
mkdir LocalRAG
cd LocalRAG

# 2. 创建虚拟环境(env为环境名称,可自定义)
python -m venv env

# 3. 激活虚拟环境
# Windows系统CMD命令:
env\Scripts\activate
# Windows系统PowerShell命令:
.\env\Scripts\Activate.ps1
# Mac/Linux系统命令:
source env/bin/activate

激活成功后,命令行前缀会出现(env)标识。

2.3 安装核心依赖库

虚拟环境激活后,逐行执行以下命令安装所有必需库,全程保持网络通畅(仅安装依赖时需要网络,模型下载后可断网运行):

bash

运行

python 复制代码
# 1. 安装PyTorch(CPU版本,无显卡专用)
pip install torch==2.1.0 --index-url https://download.pytorch.org/whl/cpu

# 2. 安装PDF解析库
pip install pypdf==4.0.1

# 3. 安装LangChain生态(文本分割+向量库集成)
pip install langchain==0.1.12
pip install langchain-community==0.0.28

# 4. 安装HuggingFace库(模型加载核心)
pip install transformers==4.37.2
pip install huggingface-hub==0.20.2

# 5. 安装FAISS向量数据库(CPU版本)
pip install faiss-cpu==1.7.4

# 6. 安装BGE嵌入模型依赖
pip install sentence-transformers==2.2.2

2.4 依赖安装验证

执行以下命令,无报错即安装成功:

bash

运行

复制代码
python -c "import torch; import pypdf; import langchain; import transformers; import faiss; print('所有依赖安装成功!')"

三、本地模型下载(核心步骤:离线运行关键)

本系统需要下载两个模型 :DeepSeek 大模型(生成答案)、BGE 嵌入模型(文本向量化),必须提前下载到本地,才能实现纯离线运行。

3.1 模型下载统一规则

  1. 所有模型必须下载到本地固定目录 ,推荐路径:
    • Windows:C:\Users\你的用户名\.cache\huggingface\hub
    • Mac/Linux:~/.cache/huggingface/hub
  2. 下载方式:使用 HuggingFace 官方工具下载,确保模型文件完整;
  3. 下载完成后,代码中配置本地路径,实现离线加载。

3.2 下载 BGE 嵌入模型(BAAI/bge-small-zh-v1.5)

轻量级中文嵌入模型,体积小、速度快、精度高,步骤:

  1. 打开 CMD / 终端,执行下载命令:

bash

运行

python 复制代码
huggingface-cli download BAAI/bge-small-zh-v1.5 --local-dir C:\Users\Administrator\.cache\huggingface\hub\BAAI--bge-small-zh-v1.5 --local-dir-use-symlinks False
  1. 等待下载完成,模型大小约 100MB,速度极快;
  2. 验证文件:打开上述路径,包含pytorch_model.binconfig.json等文件即成功。

3.3 下载 DeepSeek 大模型(deepseek-ai/deepseek-coder-1.3b-instruct)

1.3B 参数轻量级大模型,支持中文问答,CPU 可流畅运行,步骤:

  1. 执行下载命令(路径与嵌入模型保持一致):

bash

运行

复制代码
huggingface-cli download deepseek-ai/deepseek-coder-1.3b-instruct --local-dir C:\Users\Administrator\.cache\huggingface\hub\deepseek-ai--deepseek-coder-1.3b-instruct --local-dir-use-symlinks False
  1. 模型大小约 2.6GB,耐心等待下载完成;
  2. 验证文件:目录下包含model.safetensorstokenizer_config.json等文件即成功。

3.4 模型路径统一配置

本教程统一使用 Windows 路径,如果你的用户名不是 Administrator,必须修改路径!示例:你的用户名为 Tom,路径改为:

plaintext

复制代码
C:\Users\Tom\.cache\huggingface\hub

后续代码中CACHE_DIR参数必须与实际路径一致。

四、实战代码编写:完整 RAG 系统代码 + 逐行注释

LocalRAG项目文件夹下,新建local_rag.py文件,将以下完整代码复制进去,我已对每一行核心代码添加详细注释,新手也能完全理解。

python

运行

python 复制代码
# ==============================================
# 纯本地RAG系统:DeepSeek+BGE+FAISS 无API无Key全离线
# 功能:读取本地test.pdf → 构建向量库 → 本地大模型精准问答
# ==============================================
# 导入系统模块:操作系统、警告、PyTorch深度学习框架
import os
import warnings
import torch
# 导入PDF解析工具:提取本地PDF文本内容
from pypdf import PdfReader

# ===================== 离线环境强制配置(核心:禁止联网、屏蔽警告) =====================
# TRANSFORMERS_OFFLINE=1:强制Transformers库离线运行,不联网加载模型
os.environ["TRANSFORMERS_OFFLINE"] = "1"
# 关闭Tokenizer并行,避免多线程报错
os.environ["TOKENIZERS_PARALLELISM"] = "false"
# HF_HUB_OFFLINE=1:强制HuggingFace Hub离线,不联网下载模型
os.environ["HF_HUB_OFFLINE"] = "1"
# 屏蔽所有冗余警告,保证运行界面整洁
warnings.filterwarnings("ignore")

# ===================== 导入LangChain核心组件 =====================
# 递归文本分割器:拆分长文本为小片段,适配向量库存储
from langchain.text_splitter import RecursiveCharacterTextSplitter
# FAISS本地向量数据库:存储文档向量、快速检索
from langchain_community.vectorstores import FAISS
# BGE嵌入模型封装:将文本转换为向量
from langchain_community.embeddings import HuggingFaceBgeEmbeddings
# 文档对象:封装PDF提取的文本内容
from langchain.schema import Document
# HuggingFace模型加载工具:加载本地大模型
from transformers import AutoTokenizer, AutoModelForCausalLM

# ===================== 路径&模型配置(新手必改:修改为你的本地路径) =====================
# 模型缓存目录:必须与你下载模型的路径完全一致!
CACHE_DIR = r"C:\Users\Administrator\.cache\huggingface\hub"
# DeepSeek大模型名称:与下载的模型名称一致
MODEL_NAME = "deepseek-ai/deepseek-coder-1.3b-instruct"
# BGE嵌入模型名称:与下载的模型名称一致
EMBEDDING_MODEL = "BAAI/bge-small-zh-v1.5"
# PDF文件路径:将你的PDF文件重命名为test.pdf,放在代码同目录下
PDF_PATH = "test.pdf"

# 系统启动欢迎界面
print("=" * 70)
print("🤖 本地DeepSeek RAG | 自动加载 test.pdf 知识库")
print("无API · 无Key · 纯本地 · 无警告")
print("=" * 70)

# ===================== 核心函数1:读取PDF文件,提取文本内容 =====================
def load_pdf_to_docs(pdf_path):
    """
    功能:解析本地PDF文件,提取所有页面文本,封装为Document对象
    参数:pdf_path - PDF文件路径
    返回值:Document列表,包含PDF全部文本内容
    """
    # 初始化PDF读取器
    reader = PdfReader(pdf_path)
    # 定义空字符串,存储PDF所有文本
    full_text = ""
    # 遍历PDF所有页面
    for page in reader.pages:
        # 提取当前页面文本
        text = page.extract_text()
        # 如果页面有文本,追加到总文本中
        if text:
            full_text += text + "\n"
    # 返回封装后的文档对象(LangChain标准格式)
    return [Document(page_content=full_text)]

# 调用函数,加载本地PDF文档
print(f"\n📄 正在读取 {PDF_PATH} ...")
documents = load_pdf_to_docs(PDF_PATH)
print(f"✅ PDF解析完成,已加载文档内容")

# ===================== 核心步骤2:文本分割 + 构建FAISS向量库 =====================
# 初始化文本分割器:将长文本拆分为小片段
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=300,        # 每个文本片段最大长度:300字符
    chunk_overlap=50,      # 片段重叠长度:50字符(保证语义连贯)
    separators=["\n\n", "\n", "。", ",", " "]  # 分割符:按段落、换行、标点分割
)
# 执行文本分割:将PDF长文本拆分为多个小片段
chunks = text_splitter.split_documents(documents)

# 初始化BGE嵌入模型:加载本地嵌入模型,CPU运行
embeddings = HuggingFaceBgeEmbeddings(
    model_name=EMBEDDING_MODEL,    # 嵌入模型名称
    model_kwargs={"device": "cpu"},# 运行设备:CPU
    cache_folder=CACHE_DIR         # 模型本地缓存路径
)

# 核心:将文本片段转换为向量,存入FAISS向量库
db = FAISS.from_documents(chunks, embeddings)
# 初始化检索器:设置检索数量k=3(返回最相关的3个文本片段)
retriever = db.as_retriever(search_kwargs={"k": 3})
print("✅ PDF内容已写入FAISS向量库")

# ===================== 核心步骤3:加载本地DeepSeek大模型 =====================
print("\n🧠 加载本地已安装的 DeepSeek 模型...")
# 加载Tokenizer:文本编码器,将文字转换为模型可识别的数字
tokenizer = AutoTokenizer.from_pretrained(
    MODEL_NAME,            # 大模型名称
    cache_dir=CACHE_DIR,   # 本地模型路径
    local_files_only=True, # 强制离线加载,不联网
    trust_remote_code=True # 信任模型自定义代码
)
# 关键修复:设置填充标记,消除模型警告
tokenizer.pad_token = tokenizer.eos_token

# 加载DeepSeek大模型:本地离线加载,CPU运行
model = AutoModelForCausalLM.from_pretrained(
    MODEL_NAME,            # 大模型名称
    cache_dir=CACHE_DIR,   # 本地模型路径
    local_files_only=True, # 强制离线加载
    trust_remote_code=True,
    torch_dtype=torch.float32  # 数据类型:CPU专用float32
)
# 设置模型为评估模式:关闭训练,加速推理
model.eval()
print("✅ 本地模型加载成功!")

# ===================== 核心函数2:RAG智能问答函数 =====================
def ask(question):
    """
    功能:RAG核心问答函数,检索+生成一体化
    参数:question - 用户问题
    返回值:基于PDF内容的精准答案
    """
    # 1. 检索阶段:从FAISS向量库召回与问题相关的文本片段
    docs = retriever.invoke(question)
    # 拼接所有检索到的内容,作为模型上下文
    context = "\n".join([d.page_content for d in docs])

    # 2. 构造提示词(Prompt):约束模型严格基于文档回答,禁止编造
    prompt = f"""你是专业问答助手,严格只根据参考文档内容回答,禁止编造、禁止无关内容。
参考文档内容:
{context}

用户问题:{question}
精准回答:"""

    # 3. 生成阶段:将提示词编码为模型输入
    inputs = tokenizer(prompt, return_tensors="pt")
    # 关闭梯度计算,加速推理
    with torch.no_grad():
        # 模型生成答案
        outputs = model.generate(
            **inputs,
            max_new_tokens=300,    # 最大生成300个字符
            temperature=0.1,       # 温度系数:越低越精准,0.1为最优
            do_sample=False,       # 关闭随机采样,保证答案稳定
            pad_token_id=tokenizer.pad_token_id,
            eos_token_id=tokenizer.eos_token_id
        )
    # 解码模型输出,转换为人类可读的文字
    full_ans = tokenizer.decode(outputs[0], skip_special_tokens=True)
    # 去除提示词,仅保留答案内容
    return full_ans.replace(prompt, "").strip()

# ===================== 系统测试:运行RAG问答 =====================
if __name__ == "__main__":
    # 测试问题:修改为你的PDF文件中的问题!
    q = "迟到10分钟扣多少钱?"
    print(f"\n📝 问题:{q}")
    # 调用问答函数,获取答案
    ans = ask(q)
    # 打印AI回答
    print(f"🤖 AI回答:{ans}")

五、实战运行:本地 RAG 系统启动步骤

5.1 准备测试 PDF 文件

  1. LocalRAG项目文件夹下,新建一个 PDF 文件,重命名为test.pdf
  2. 在 PDF 中写入测试内容(方便验证效果),示例内容:

plaintext

复制代码
公司考勤制度
1. 迟到1-10分钟,不扣除工资;
2. 迟到11-30分钟,扣除半天工资;
3. 迟到30分钟以上,扣除全天工资;
4. 早退按照迟到同等标准处罚。
  1. 保存 PDF 文件,确保与local_rag.py代码文件在同一目录。

5.2 运行 RAG 系统

  1. 打开 CMD / 终端,进入LocalRAG项目文件夹,激活虚拟环境;
  2. 执行运行命令:

bash

运行

复制代码
python local_rag.py

5.3 运行结果解读

正常运行会输出以下内容,无任何警告、报错、联网请求:

plaintext

复制代码
======================================================================
🤖 本地DeepSeek RAG | 自动加载 test.pdf 知识库
无API · 无Key · 纯本地 · 无警告
======================================================================

📄 正在读取 test.pdf ...
✅ PDF解析完成,已加载文档内容
✅ PDF内容已写入FAISS向量库

🧠 加载本地已安装的 DeepSeek 模型...
✅ 本地模型加载成功!

📝 问题:迟到10分钟扣多少钱?
🤖 AI回答:迟到10分钟不扣除工资。

运行成功标志:模型基于 PDF 内容生成精准答案,无任何报错!

六、进阶实战:自定义修改与功能扩展

6.1 修改 PDF 文件与问题

  1. 替换test.pdf为你的私有文档(合同、制度、笔记、书籍等);
  2. 修改代码中最后部分的测试问题,适配你的文档内容:

python

运行

复制代码
# 示例:修改为你的问题
q = "这份合同的签订日期是哪天?"
q = "产品的保修期限是多久?"
  1. 重新运行代码,即可实现私有文档的精准问答。

6.2 调整文本分割参数(优化检索精度)

如果发现检索内容不精准,可以调整文本分割器参数:

python

运行

python 复制代码
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,    # 增大片段长度,适合长文本
    chunk_overlap=100, # 增大重叠长度,保证语义完整
    separators=["\n\n", "\n", "。", ",", " "]
)

6.3 调整模型生成参数(优化答案效果)

修改ask函数中的生成参数,适配不同场景:

python

运行

python 复制代码
outputs = model.generate(
    **inputs,
    max_new_tokens=500,  # 增大生成长度,适合长答案
    temperature=0.0,     # 0.0:完全精准,无随机;0.3:轻微灵活
    do_sample=False,
    pad_token_id=tokenizer.pad_token_id,
    eos_token_id=tokenizer.eos_token_id
)

6.4 循环问答模式(持续对话)

将测试代码修改为循环模式,实现一次启动、多次问答:

python

运行

python 复制代码
if __name__ == "__main__":
    print("\n🎉 本地RAG系统已启动,输入问题即可问答,输入exit退出!")
    while True:
        q = input("\n请输入你的问题:")
        if q.lower() == "exit":
            print("👋 系统已退出!")
            break
        ans = ask(q)
        print(f"🤖 AI回答:{ans}")

运行后可连续提问,无需重复加载模型,效率大幅提升。

七、常见问题排查(新手必看)

7.1 模型加载报错:找不到本地文件

报错原因CACHE_DIR路径与模型实际下载路径不一致;解决方案

  1. 打开模型下载目录,复制完整路径;
  2. 替换代码中CACHE_DIR参数,Windows 路径前加r,避免转义字符;
  3. 检查模型名称是否正确:deepseek-ai/deepseek-coder-1.3b-instruct

7.2 PDF 读取报错:文件不存在

报错原因test.pdf未放在代码同目录,或文件名错误;解决方案

  1. 确认 PDF 文件名严格为test.pdf(大小写一致);
  2. 确认 PDF 与local_rag.py在同一文件夹下;
  3. 检查 PDF 是否损坏,重新保存即可。

7.3 运行卡顿:CPU 占用过高

解决方案

  1. 关闭其他占用内存的软件;
  2. 降低chunk_size参数(如 200),减少向量计算量;
  3. 本教程为 CPU 版本,属于正常现象,轻量级模型已做最大优化。

7.4 模型警告:pad_token 未设置

解决方案 :代码中已添加tokenizer.pad_token = tokenizer.eos_token,确保这行代码未被删除。

7.5 离线运行报错:强制联网

解决方案:确认代码开头的离线环境配置完整:

python

运行

复制代码
os.environ["TRANSFORMERS_OFFLINE"] = "1"
os.environ["HF_HUB_OFFLINE"] = "1"

八、纯本地 RAG 系统优势总结

  1. 极致隐私:所有数据、模型、计算都在本地,无任何数据外泄风险;
  2. 零成本:无需 API 密钥、无需付费、无需充值,永久免费使用;
  3. 全离线:模型下载完成后,断网状态下可永久运行;
  4. 轻量高效:CPU 即可运行,低配电脑无压力,启动速度快、问答延迟低;
  5. 精准可靠:基于私有文档检索回答,杜绝大模型幻觉,答案 100% 基于真实内容;
  6. 易扩展:支持替换任意本地大模型、任意文档格式、任意向量库,适配所有场景。

九、后续优化方向

  1. GPU 加速 :如果有 NVIDIA 显卡,可修改device="cuda",实现 10 倍加速;
  2. 模型升级:替换为更大参数的本地大模型(如 DeepSeek-7B),提升问答能力;
  3. 文档扩展:支持 Word、TXT、Excel、图片等多种格式文档;
  4. 界面优化:集成 Gradio/Streamlit,搭建可视化网页界面,无需命令行操作;
  5. 向量库持久化:保存 FAISS 向量库到本地,无需每次重新构建。

十、结语

本教程从零开始,完成了纯本地 RAG 系统的全流程部署,从环境安装、模型下载、代码编写、实战运行到问题排查,覆盖所有新手痛点。这套系统完全满足个人和小型企业的私有知识库问答需求,真正实现了「无 API、无 Key、纯本地、无警告」的理想状态。

RAG 技术是 AI 落地的核心方向,纯本地部署更是未来数据安全的必然趋势。掌握本教程后,你可以基于此框架自由扩展功能,适配办公、学习、研发、管理等各类场景,打造属于自己的私有 AI 助手。


关键核心回顾

  1. 核心技术栈:DeepSeek 本地大模型 + BGE 嵌入 + FAISS 向量库,CPU 可流畅运行;
  2. 离线关键:强制配置TRANSFORMERS_OFFLINE=1,提前下载模型到本地;
  3. 运行核心:PDF 解析→文本分割→向量构建→检索生成;
  4. 优势:数据安全、零成本、全离线、精准无幻觉
相关推荐
狐狐生风2 天前
LangChain 向量存储:Chroma、FAISS
人工智能·python·学习·langchain·faiss·agentai
Muyuan19982 天前
27.RAG 系统中的上下文充分性判断:从 Chunk 数量、FAISS 距离到 LLM Relevance Gate
python·django·pdf·fastapi·faiss
chushiyunen7 天前
faiss向量检索库(并非向量数据库)
数据库·faiss
AI木马人9 天前
8.【向量数据库深度对比】Milvus vs FAISS vs Pinecone(真实项目选型指南)
数据库·milvus·faiss
竹之却20 天前
【Agent-阿程】AI先锋杯·14天征文挑战第14期-第6天-大模型RAG检索增强生成实战
人工智能·大模型·检索增强·faiss·rag
guslegend22 天前
第9节:FAISS,HNSW还是BM25?如何选择最适合业务的向量检索引擎?如何选择最适合业务的向量检索引擎
人工智能·大模型·faiss·rag
weisian15122 天前
进阶篇-LangChain篇-10--向量数据库选型指南:本地FAISS, Chroma与云原生方案
数据库·langchain·faiss·向量数据库·chroma
森森-曦1 个月前
在复现overlaptranformer论文中,进行库faiss安装的,解决方案。
faiss
liliangcsdn1 个月前
如何使用向量库faiss和LLM判断问题是否被记录
人工智能·全文检索·faiss