解析 ‘Local RAG’ 架构：如何在完全断网环境下利用私有向量库与 CPU 推理实现数据安全？

开篇：数据安全与智能应用的交汇点——Local RAG的时代呼唤

各位同仁，各位对数据安全与智能应用充满热情的开发者们，大家好！

今天，我们将共同探讨一个在当前技术浪潮中日益凸显其重要性的主题：如何在完全断网环境下，利用私有向量库与CPU推理能力，构建一个安全、高效的本地化检索增强生成（RAG）系统。这不仅仅是技术上的挑战，更是对数据主权、隐私保护以及独立运作能力的深刻实践。

在云计算和大型语言模型（LLM）API服务盛行的今天，我们享受着前所未有的智能便利。然而，伴随而来的数据安全、隐私合规、网络依赖以及潜在的服务中断风险，也让许多企业和个人对敏感数据的使用望而却步。特别是在金融、医疗、国防等对数据安全有着极高要求的行业，或者在网络连接受限、甚至完全隔离的场景下，如何安全地利用生成式AI的能力，成为了一个迫切需要解决的问题。

Local RAG架构正是为此而生。它将RAG系统的核心组件——检索器（Retriever）和生成器（Generator）——完全部署在本地机器上，所有数据处理、向量化、模型推理都在本地CPU完成，不依赖任何外部网络服务。这意味着您的私有数据永远不会离开您的设备，从而从根本上杜绝了数据泄露的风险，并确保了在任何网络条件下，您都能拥有一个可靠、可控的智能问答或内容生成系统。

本次讲座，我将从编程专家的视角，深入剖析Local RAG的各个技术环节，从数据准备、向量库构建、CPU友好的模型选择与优化，到系统集成与安全保障，力求提供一个全面而严谨的实践指南。我们将通过大量的代码示例，将理论付诸实践，让您能够亲手搭建起一个真正属于自己的、安全的本地智能助手。

第一讲：RAG核心架构剖析与本地化挑战

首先，我们来回顾一下RAG（Retrieval-Augmented Generation）的基本概念。RAG是一种结合了信息检索和生成式AI的技术范式，旨在解决传统LLM在事实性、时效性和领域知识方面的不足。其核心思想是：当用户提出问题时，系统首先从一个外部知识库中检索出相关的、准确的信息片段，然后将这些信息作为上下文（context）与用户问题一并输入给大型语言模型，引导LLM生成更准确、更具参考价值的回答。

一个标准的RAG系统通常包含两个主要阶段：

1. 检索（Retrieval）阶段：
   • 将用户查询转换为向量表示（embedding）。
   • 在预构建的向量数据库中，查找与查询向量最相似的文档块（chunks）。
   • 返回Top-K个最相关的文档块作为上下文。
2. 生成（Generation）阶段：
   • 将用户查询和检索到的上下文一起构建成一个提示（prompt）。
   • 将提示输入给大型语言模型。
   • LLM根据提示生成最终的回答。

本地化RAG的独特挑战

将上述RAG架构完全部署在本地，特别是在CPU推理的严格限制下，会带来一系列独特的挑战：

• 模型体积与性能：大型语言模型通常需要强大的GPU进行推理。要在CPU上实现可接受的推理速度，我们必须选择体积小巧、经过优化的模型，并通过量化等技术进一步压缩。
• 嵌入模型选择：生成高质量的向量嵌入同样需要计算资源。我们需要选择那些在CPU上也能高效运行的嵌入模型。
• 向量数据库：虽然有许多高性能的向量数据库（如Pinecone、Weaviate）是云原生的，但在本地环境下，我们需要选择那些能够离线运行、易于部署且资源消耗低的本地向量库。
• 内存与存储：私有知识库可能非常庞大，向量化后的数据和加载到内存中的模型都会占用大量资源。需要精细管理内存和存储。
• 工具链与生态：确保所有依赖库和工具都能在本地、断网环境下稳定运行，且不引入额外的网络请求。

克服这些挑战，是构建一个实用、安全的Local RAG系统的关键。

第二讲：私有数据准备与向量化

本地RAG系统的基石是您的私有知识库。无论是文档、代码、数据库记录还是其他形式的非结构化数据，都需要经过精心处理，才能转化为RAG系统可用的形式。

2.1 文档加载与处理

数据源的类型多种多样。我们需要一个灵活的加载器来处理不同格式的文档。LangChain是一个优秀的框架，提供了丰富的文档加载器。

import os
from langchain_community.document_loaders import TextLoader, PyPDFLoader, UnstructuredWordDocumentLoader, UnstructuredMarkdownLoader
from langchain_community.document_loaders import DirectoryLoader

def load_documents_from_directory(directory_path: str) -> list:
    """
    从指定目录加载多种格式的文档。
    支持 .txt, .pdf, .docx, .md 文件。
    """
    documents = []

    # 加载TXT文件
    txt_loader = DirectoryLoader(directory_path, glob="**/*.txt", loader_cls=TextLoader, silent_errors=True)
    documents.extend(txt_loader.load())

    # 加载PDF文件
    # 注意：PyPDFLoader需要pypdf库，UnstructuredWordDocumentLoader需要unstructured库
    # 这些库可能需要额外的系统依赖，例如poppler（PDF处理）
    pdf_loader = DirectoryLoader(directory_path, glob="**/*.pdf", loader_cls=PyPDFLoader, silent_errors=True)
    documents.extend(pdf_loader.load())

    # 加载DOCX文件
    docx_loader = DirectoryLoader(directory_path, glob="**/*.docx", loader_cls=UnstructuredWordDocumentLoader, silent_errors=True)
    documents.extend(docx_loader.load())

    # 加载Markdown文件
    md_loader = DirectoryLoader(directory_path, glob="**/*.md", loader_cls=UnstructuredMarkdownLoader, silent_errors=True)
    documents.extend(md_loader.load())

    print(f"成功从目录 '{directory_path}' 加载了 {len(documents)} 份文档。")
    return documents

# 示例用法：
# if __name__ == "__main__":
#     # 创建一个测试目录和一些示例文件
#     if not os.path.exists("data"):
#         os.makedirs("data")
#     with open("data/example.txt", "w", encoding="utf-8") as f:
#         f.write("这是一个示例文本文件，包含一些关于本地RAG架构的描述。nLocal RAG旨在保障数据安全和隐私。")
#     # 假设这里有 example.pdf, example.docx, example.md 文件
#
#     my_documents = load_documents_from_directory("data")
#     for doc in my_documents[:2]: # 打印前两份文档的内容和元数据
#         print(f"--- Document Source: {doc.metadata.get('source')} ---")
#         print(f"Content: {doc.page_content[:200]}...") # 截断显示
#         print("-" * 30)

依赖说明：

• pip install langchain
• pip install pypdf (用于 PyPDFLoader)
• pip install unstructured (用于 UnstructuredWordDocumentLoader, UnstructuredMarkdownLoader 等，可能需要额外的系统依赖，如libmagic-dev或poppler-utils，具体取决于操作系统)

2.2 文本切分策略（Chunking）

加载的原始文档可能非常大，直接送入LLM会超出其上下文窗口限制。因此，我们需要将文档切分成更小的、有意义的块（chunks）。切分策略对RAG系统的性能至关重要。

常见的切分策略包括：

• 固定大小切分（Fixed-size Chunking）：最简单直接，按字符数或token数切分。
• 带重叠的固定大小切分（Fixed-size Chunking with Overlap）：在固定大小切分的基础上，引入重叠部分，以保留块之间的上下文连贯性。
• 语义切分（Semantic Chunking）：尝试根据文档的语义结构（如段落、章节、标题）进行切分，确保每个块都包含一个相对完整的语义单元。
• 递归字符文本切分器（RecursiveCharacterTextSplitter）：LangChain中常用的一种，它会尝试按不同的分隔符（如nn, n, `,.`）递归地切分文本，直到块大小满足要求。

from langchain.text_splitter import RecursiveCharacterTextSplitter

def split_documents_into_chunks(documents: list, chunk_size: int = 1000, chunk_overlap: int = 200) -> list:
    """
    将文档切分为指定大小的块，并可设置重叠部分。
    """
    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=chunk_size,
        chunk_overlap=chunk_overlap,
        length_function=len, # 使用字符长度作为度量
        add_start_index=True # 添加块在原始文档中的起始索引
    )
    chunks = text_splitter.split_documents(documents)
    print(f"原始文档被切分为 {len(chunks)} 个块。")
    return chunks

# 示例用法：
# if __name__ == "__main__":
#     # 假设my_documents已加载
#     # my_documents = load_documents_from_directory("data")
#     # 如果没有实际文档，可以创建一个虚拟文档
#     from langchain_core.documents import Document
#     my_documents = [Document(page_content="""
#         Local RAG架构旨在保障数据安全和隐私，尤其是在完全断网的环境下。
#         其核心理念是将检索器和生成器完全部署在本地机器上。
#         所有数据处理、向量化、模型推理都在本地CPU完成，不依赖任何外部网络服务。
#         这意味着您的私有数据永远不会离开您的设备，从根本上杜绝了数据泄露的风险。
#         同时，它确保了在任何网络条件下，您都能拥有一个可靠、可控的智能问答或内容生成系统。
#         选择合适的嵌入模型和本地向量库是成功的关键。
#         我们还需要考虑模型量化和CPU推理的优化。
#     """, metadata={"source": "virtual_doc.txt"})]
#
#     my_chunks = split_documents_into_chunks(my_documents, chunk_size=200, chunk_overlap=50)
#     for i, chunk in enumerate(my_chunks[:3]):
#         print(f"--- Chunk {i+1} ---")
#         print(f"Content (length {len(chunk.page_content)}): {chunk.page_content}")
#         print(f"Metadata: {chunk.metadata}")
#         print("-" * 30)

2.3 CPU友好的本地嵌入模型选择

将文本块转换为数值向量（embeddings）是RAG系统的核心步骤之一。这些向量捕获了文本的语义信息，使得我们能够通过计算向量之间的相似度来找出相关的文本。

在CPU环境下，我们必须选择那些体积小巧、计算效率高的嵌入模型。Sentence Transformers库提供了大量预训练的嵌入模型，其中许多都非常适合在CPU上运行。

推荐的CPU友好型嵌入模型：

模型名称	语言	嵌入维度	模型大小	优点	缺点
all-MiniLM-L6-v2	英文	384	~90MB	速度快，效率高，通用性好。	仅支持英文。
all-MiniLM-L12-v2	英文	384	~120MB	略大，但效果更好，仍适用于CPU。	仅支持英文。
bge-small-en-v1.5	英文	384	~130MB	性能优异，在MTEB基准测试中表现出色。	仅支持英文。
m3e-base	中文	768	~400MB	专为中文优化，效果好，支持中英双语。	模型略大，但仍可CPU推理。
text2vec-base-chinese	中文	768	~400MB	中文语义嵌入，性能良好。	模型略大，但仍可CPU推理。
E5-small-v2	英文	384	~130MB	通用性好，效果不错。	仅支持英文。

对于中文场景，m3e-base或text2vec-base-chinese是很好的选择。它们虽然比MiniLM系列大一些，但在中文语义理解上表现出色，且在CPU上也能有不错的推理速度。

from langchain_community.embeddings import HuggingFaceEmbeddings
import numpy as np

def initialize_embedding_model(model_name: str = "sentence-transformers/all-MiniLM-L6-v2") -> HuggingFaceEmbeddings:
    """
    初始化一个HuggingFaceSentenceTransformerEmbedding模型，用于生成文本嵌入。
    模型会尝试从本地加载，如果本地不存在，则会尝试下载（首次运行需联网）。
    一旦下载完成，后续可在断网环境下使用。
    """
    # 确保模型下载到本地，并指定本地路径
    # cache_folder 参数可以指定模型下载的路径
    # 建议首次运行在联网环境下进行模型下载
    model_kwargs = {'device': 'cpu'} # 明确指定使用CPU
    encode_kwargs = {'normalize_embeddings': True} # 推荐标准化嵌入向量

    # 对于中文模型，可以尝试 "moka-ai/m3e-base" 或 "GanymedeNil/text2vec-base-chinese"
    # model_name = "moka-ai/m3e-base"

    try:
        embeddings_model = HuggingFaceEmbeddings(
            model_name=model_name,
            model_kwargs=model_kwargs,
            encode_kwargs=encode_kwargs
        )
        print(f"成功加载嵌入模型: {model_name} (运行在CPU上)")
        return embeddings_model
    except Exception as e:
        print(f"加载嵌入模型失败: {e}")
        print("请检查模型名称或确保模型已下载到本地。首次运行时可能需要联网下载。")
        raise

def generate_embeddings_for_chunks(chunks: list, embeddings_model: HuggingFaceEmbeddings) -> list[np.ndarray]:
    """
    为文本块生成嵌入向量。
    """
    texts = [chunk.page_content for chunk in chunks]
    try:
        # LangChain的HuggingFaceEmbeddings类会自动处理批处理
        # 内部会调用 model.encode()
        chunk_embeddings = embeddings_model.embed_documents(texts)
        print(f"成功为 {len(chunks)} 个文本块生成了嵌入向量。")
        return chunk_embeddings
    except Exception as e:
        print(f"生成嵌入向量失败: {e}")
        raise

# 示例用法：
# if __name__ == "__main__":
#     # 假设my_chunks已生成
#     from langchain_core.documents import Document
#     my_documents = [Document(page_content="""
#         Local RAG架构旨在保障数据安全和隐私，尤其是在完全断网的环境下。
#         其核心理念是将检索器和生成器完全部署在本地机器上。
#         所有数据处理、向量化、模型推理都在本地CPU完成，不依赖任何外部网络服务。
#         这意味着您的私有数据永远不会离开您的设备，从根本上杜绝了数据泄露的风险。
#         同时，它确保了在任何网络条件下，您都能拥有一个可靠、可控的智能问答或内容生成系统。
#         选择合适的嵌入模型和本地向量库是成功的关键。
#         我们还需要考虑模型量化和CPU推理的优化。
#     """, metadata={"source": "virtual_doc.txt"})]
#     my_chunks = split_documents_into_chunks(my_documents, chunk_size=200, chunk_overlap=50)
#
#     # 初始化嵌入模型 (首次运行可能需要下载)
#     # 如果是中文，请将 model_name 改为 "moka-ai/m3e-base"
#     # 确保在断网前已下载好模型
#     embedding_model = initialize_embedding_model("sentence-transformers/all-MiniLM-L6-v2")
#
#     # 生成嵌入向量
#     chunk_embeddings = generate_embeddings_for_chunks(my_chunks, embedding_model)
#     if chunk_embeddings:
#         print(f"第一个文本块的嵌入向量维度: {len(chunk_embeddings[0])}")
#         print(f"第一个文本块的嵌入向量（前5个值）: {chunk_embeddings[0][:5]}")

注意：HuggingFaceEmbeddings 首次加载模型时会尝试从 Hugging Face Hub 下载。在完全断网环境下，您需要确保模型已经提前下载到本地。下载后，sentence-transformers 库会自动将模型缓存到默认位置（通常是~/.cache/huggingface/hub），或者您可以通过设置环境变量 HF_HOME 或在 HuggingFaceEmbeddings 初始化时通过 cache_folder 参数指定缓存路径。

第三讲：本地向量库的构建与管理

将文本块及其对应的嵌入向量存储起来，以便后续高效检索，是向量库的核心功能。在断网、CPU推理的环境下，我们需要选择轻量级、无需服务器、易于部署且性能尚可的本地向量库。

3.1 向量库选型

以下是几种适合本地部署的向量库：

向量库名称	类型	特点	优点	缺点
FAISS	内存/文件	Facebook AI Similarity Search，高度优化的C++库，提供Python接口。	极速的相似度搜索，支持多种索引类型，可磁盘持久化。	内存管理需谨慎，无内置文档存储，需要手动管理。
ChromaDB	本地/客户端	嵌入式（SQLite）或客户端-服务器模式，提供文档和向量一体化存储。	易于使用，开箱即用，支持元数据过滤，提供持久化。	大规模数据可能不如FAISS纯粹的搜索速度。
Hnswlib	内存/文件	Hierarchical Navigable Small World (HNSW) 算法的轻量级实现。	快速的近似最近邻搜索，纯Python绑定，可磁盘持久化。	类似FAISS，主要关注向量搜索，无内置文档存储。
LanceDB	文件	基于Apache Lance格式，面向AI的嵌入式数据库，支持高维向量和结构化数据。	支持高效向量搜索和SQL查询，持久化，可扩展。	相对较新，生态尚在发展中。

对于大多数本地RAG应用，FAISS和ChromaDB是两个非常好的选择。FAISS以其极致的搜索性能闻名，适合对检索速度要求极高的场景；ChromaDB则以其易用性和文档向量一体化存储的便利性，简化了开发流程。

3.2 FAISS实战：内存与磁盘持久化

FAISS是一个强大的库，但它只存储向量。我们通常需要将原始文本块及其元数据与向量关联起来。一种常见的做法是将文本块的索引与FAISS索引中的向量索引对应。

import faiss
import numpy as np
import pickle # 用于持久化原始文本块

class LocalFAISSVectorStore:
    def __init__(self, index_path: str = "faiss_index.bin", doc_path: str = "faiss_docs.pkl"):
        self.index_path = index_path
        self.doc_path = doc_path
        self.index = None
        self.documents = [] # 存储原始的LangChain Document对象
        self.is_loaded = False

    def _create_index(self, embedding_dim: int):
        """创建FAISS索引，这里使用IndexFlatL2作为简单示例"""
        # IndexFlatL2 是一个简单的L2距离索引，适合小规模数据
        # 对于大规模数据，可以考虑使用 IndexIVFFlat 或 IndexHNSWFlat
        self.index = faiss.IndexFlatL2(embedding_dim)
        print(f"创建FAISS IndexFlatL2，维度: {embedding_dim}")

    def add_documents(self, chunks: list, embeddings: list[np.ndarray]):
        """
        向向量库中添加文档块及其嵌入向量。
        embeddings 应该是 numpy 数组列表或二维 numpy 数组。
        """
        if not chunks or not embeddings:
            print("没有文档块或嵌入向量可添加。")
            return

        if not self.index:
            self._create_index(len(embeddings[0]))

        # 将嵌入向量转换为float32 numpy数组
        embeddings_np = np.array(embeddings).astype('float32')

        # 确保嵌入向量的维度与索引维度一致
        if embeddings_np.shape[1] != self.index.d:
            raise ValueError(f"嵌入向量维度 ({embeddings_np.shape[1]}) 与FAISS索引维度 ({self.index.d}) 不匹配。")

        self.index.add(embeddings_np)
        self.documents.extend(chunks)
        print(f"FAISS索引中已添加 {embeddings_np.shape[0]} 个向量。当前总向量数: {self.index.ntotal}")

    def search(self, query_embedding: np.ndarray, k: int = 5) -> list:
        """
        在向量库中搜索最相似的K个文档块。
        query_embedding 应该是单个查询的嵌入向量。
        返回 (distance, document) 对的列表。
        """
        if self.index is None or self.index.ntotal == 0:
            print("FAISS索引为空或未初始化。")
            return []

        query_embedding_np = np.array([query_embedding]).astype('float32')
        # D是距离，I是索引
        distances, indices = self.index.search(query_embedding_np, k)

        results = []
        for i in range(len(indices[0])):
            doc_idx = indices[0][i]
            if 0 <= doc_idx < len(self.documents):
                results.append((distances[0][i], self.documents[doc_idx]))
            else:
                print(f"警告: 搜索结果中包含无效索引 {doc_idx}。")
        return results

    def save_index(self):
        """将FAISS索引和原始文档持久化到磁盘。"""
        if self.index:
            faiss.write_index(self.index, self.index_path)
            with open(self.doc_path, 'wb') as f:
                pickle.dump(self.documents, f)
            print(f"FAISS索引和文档已保存到 '{self.index_path}' 和 '{self.doc_path}'。")
        else:
            print("FAISS索引未初始化，无法保存。")

    def load_index(self):
        """从磁盘加载FAISS索引和原始文档。"""
        if os.path.exists(self.index_path) and os.path.exists(self.doc_path):
            self.index = faiss.read_index(self.index_path)
            with open(self.doc_path, 'rb') as f:
                self.documents = pickle.load(f)
            self.is_loaded = True
            print(f"FAISS索引和文档已从 '{self.index_path}' 和 '{self.doc_path}' 加载。总向量数: {self.index.ntotal}")
        else:
            print("未找到FAISS索引或文档文件，将创建新的。")
            self.is_loaded = False

# 示例用法：
# if __name__ == "__main__":
#     # 准备数据
#     from langchain_core.documents import Document
#     documents_raw = [
#         Document(page_content="Local RAG架构关注数据安全，所有操作都在本地完成。", metadata={"source": "doc1.txt"}),
#         Document(page_content="CPU推理是本地RAG的关键技术，需要优化模型。", metadata={"source": "doc2.txt"}),
#         Document(page_content="私有向量库如FAISS和ChromaDB适用于断网环境。", metadata={"source": "doc3.txt"}),
#         Document(page_content="量化技术可以有效减小LLM模型体积，提升CPU推理速度。", metadata={"source": "doc4.txt"}),
#         Document(page_content="文本切分策略影响检索质量，需要合理设置chunk_size和overlap。", metadata={"source": "doc5.txt"}),
#         Document(page_content="本地RAG系统可以保障企业敏感数据的隐私性，符合合规要求。", metadata={"source": "doc6.txt"}),
#         Document(page_content="嵌入模型如all-MiniLM-L6-v2在CPU上表现良好。", metadata={"source": "doc7.txt"}),
#         Document(page_content="FAISS提供了高效的相似度搜索功能。", metadata={"source": "doc8.txt"}),
#         Document(page_content="ChromaDB是一个易用的本地向量数据库。", metadata={"source": "doc9.txt"}),
#     ]
#     chunks = split_documents_into_chunks(documents_raw, chunk_size=100, chunk_overlap=20)
#     embedding_model = initialize_embedding_model("sentence-transformers/all-MiniLM-L6-v2")
#     embeddings = generate_embeddings_for_chunks(chunks, embedding_model)
#
#     # 初始化FAISS向量库
#     faiss_store = LocalFAISSVectorStore("my_faiss_index.bin", "my_faiss_docs.pkl")
#
#     # 尝试加载现有索引，如果不存在则添加
#     faiss_store.load_index()
#     if not faiss_store.is_loaded:
#         faiss_store.add_documents(chunks, embeddings)
#         faiss_store.save_index()
#
#     # 执行搜索
#     query = "本地数据安全和隐私"
#     query_embedding = embedding_model.embed_query(query)
#     search_results = faiss_store.search(query_embedding, k=3)
#
#     print(f"n查询: '{query}' 的搜索结果:")
#     for dist, doc in search_results:
#         print(f"  - 距离: {dist:.4f}, 内容: {doc.page_content[:100]}..., 源: {doc.metadata.get('source')}")

依赖说明：pip install faiss-cpu (注意是faiss-cpu，而不是faiss-gpu)

3.3 ChromaDB的本地化应用

ChromaDB提供了一个非常方便的嵌入式模式，它使用SQLite作为后端，可以将数据完全存储在本地文件系统中，非常适合断网环境。

from langchain_community.vectorstores import Chroma
from langchain_core.documents import Document
from langchain_community.embeddings import HuggingFaceEmbeddings
import os

class LocalChromaVectorStore:
    def __init__(self, persist_directory: str = "chroma_db", embedding_model: HuggingFaceEmbeddings = None):
        self.persist_directory = persist_directory
        self.embedding_model = embedding_model
        if not self.embedding_model:
            raise ValueError("ChromaDB需要一个嵌入模型进行初始化。")
        self.vectorstore = None
        self._initialize_chroma()

    def _initialize_chroma(self):
        """初始化或加载ChromaDB。"""
        if not os.path.exists(self.persist_directory):
            os.makedirs(self.persist_directory)
            print(f"创建ChromaDB持久化目录: {self.persist_directory}")
        else:
            print(f"加载ChromaDB持久化目录: {self.persist_directory}")

        self.vectorstore = Chroma(
            persist_directory=self.persist_directory,
            embedding_function=self.embedding_model
        )
        # 检查是否已存在集合，ChromaDB在首次add_documents时才会真正创建集合
        if self.vectorstore._collection is None:
             print("ChromaDB集合尚未初始化，将在添加文档时创建。")
        else:
            print(f"ChromaDB中已存在 {self.vectorstore._collection.count()} 个文档。")

    def add_documents(self, chunks: list[Document]):
        """向ChromaDB中添加文档块。"""
        if not chunks:
            print("没有文档块可添加。")
            return

        # ChromaDB的from_documents方法会自动处理嵌入和添加
        # 首次添加文档时，如果集合不存在，会被创建
        if self.vectorstore._collection is None or self.vectorstore._collection.count() == 0:
            self.vectorstore = Chroma.from_documents(
                documents=chunks,
                embedding=self.embedding_model,
                persist_directory=self.persist_directory
            )
            print(f"ChromaDB已从 {len(chunks)} 个文档中初始化并添加。")
        else:
            # 如果集合已存在，使用add_documents方法
            self.vectorstore.add_documents(chunks)
            print(f"ChromaDB中已添加 {len(chunks)} 个文档。当前总文档数: {self.vectorstore._collection.count()}")

        # 确保数据写入磁盘
        self.vectorstore.persist()
        print("ChromaDB数据已持久化。")

    def search(self, query: str, k: int = 5) -> list[Document]:
        """
        在ChromaDB中搜索最相似的K个文档块。
        直接传入查询字符串，ChromaDB会使用内部的embedding_function进行嵌入。
        返回LangChain Document对象的列表。
        """
        if self.vectorstore._collection is None or self.vectorstore._collection.count() == 0:
            print("ChromaDB为空或未初始化。")
            return []

        # ChromaDB的similarity_search返回的是Document对象列表
        results = self.vectorstore.similarity_search(query, k=k)
        return results

    def get_document_count(self) -> int:
        """获取当前向量库中的文档数量。"""
        if self.vectorstore._collection is None:
            return 0
        return self.vectorstore._collection.count()

# 示例用法：
# if __name__ == "__main__":
#     # 准备数据 (同FAISS示例)
#     documents_raw = [
#         Document(page_content="Local RAG架构关注数据安全，所有操作都在本地完成。", metadata={"source": "doc1.txt"}),
#         Document(page_content="CPU推理是本地RAG的关键技术，需要优化模型。", metadata={"source": "doc2.txt"}),
#         Document(page_content="私有向量库如FAISS和ChromaDB适用于断网环境。", metadata={"source": "doc3.txt"}),
#         Document(page_content="量化技术可以有效减小LLM模型体积，提升CPU推理速度。", metadata={"source": "doc4.txt"}),
#         Document(page_content="文本切分策略影响检索质量，需要合理设置chunk_size和overlap。", metadata={"source": "doc5.txt"}),
#         Document(page_content="本地RAG系统可以保障企业敏感数据的隐私性，符合合规要求。", metadata={"source": "doc6.txt"}),
#         Document(page_content="嵌入模型如all-MiniLM-L6-v2在CPU上表现良好。", metadata={"source": "doc7.txt"}),
#         Document(page_content="FAISS提供了高效的相似度搜索功能。", metadata={"source": "doc8.txt"}),
#         Document(page_content="ChromaDB是一个易用的本地向量数据库。", metadata={"source": "doc9.txt"}),
#     ]
#     chunks = split_documents_into_chunks(documents_raw, chunk_size=100, chunk_overlap=20)
#     embedding_model = initialize_embedding_model("sentence-transformers/all-MiniLM-L6-v2")
#
#     # 初始化ChromaDB向量库
#     chroma_store = LocalChromaVectorStore("my_chroma_db", embedding_model)
#
#     # 如果是第一次运行或者数据库为空，则添加文档
#     if chroma_store.get_document_count() == 0:
#         chroma_store.add_documents(chunks)
#
#     # 执行搜索
#     query = "本地数据安全和隐私"
#     search_results_chroma = chroma_store.search(query, k=3)
#
#     print(f"n查询: '{query}' 的ChromaDB搜索结果:")
#     for doc in search_results_chroma:
#         print(f"  - 内容: {doc.page_content[:100]}..., 源: {doc.metadata.get('source')}")

依赖说明：pip install chromadb

第四讲：高效检索机制的设计与实现

检索机制的核心目标是从庞大的知识库中，快速、准确地找出与用户查询最相关的少数信息片段。这涉及到相似度计算和Top-K选择。

4.1 相似度算法与Top-K选择

• 相似度算法：
  • 余弦相似度（Cosine Similarity）：最常用的一种，衡量两个向量方向的相似性，与向量的长度无关。取值范围通常在-1到1之间，1表示完全相同，-1表示完全相反，0表示正交。
  • 欧氏距离（Euclidean Distance）/L2距离：衡量两个向量在欧氏空间中的直线距离。距离越小表示越相似。FAISS的IndexFlatL2就是基于欧氏距离。
  • 内积（Dot Product）：两个向量点乘，与余弦相似度在向量归一化后等价。

在实际应用中，如果您的嵌入模型输出的向量是经过归一化的（如encode_kwargs={'normalize_embeddings': True}），那么余弦相似度和点积相似度在排序上是等价的，且点积计算更快。FAISS的IndexFlatL2索引计算的是欧氏距离的平方，但通过一些转换，也可以与余弦相似度进行比较。

• Top-K选择：
  • K值的选择至关重要。如果K太小，可能遗漏关键信息；如果K太大，会引入过多噪音，并增加LLM的上下文长度，从而降低LLM推理速度和准确性。
  • K通常根据LLM的上下文窗口大小、文档块的平均长度以及实际应用的需求来经验性设置。常见的K值在3到10之间。

4.2 检索器实现

无论是基于FAISS还是ChromaDB，检索器的实现本质上都是调用向量库的搜索接口。这里我们封装一个通用的检索器类。

from langchain_core.documents import Document
from typing import List, Tuple

class Retriever:
    def __init__(self, vector_store, embedding_model):
        """
        初始化检索器。
        :param vector_store: 封装了search方法的向量存储实例（如LocalFAISSVectorStore或LocalChromaVectorStore）。
        :param embedding_model: 用于将查询转换为嵌入向量的HuggingFaceEmbeddings实例。
        """
        self.vector_store = vector_store
        self.embedding_model = embedding_model
        print("检索器初始化完成。")

    def retrieve(self, query: str, k: int = 5) -> List[Document]:
        """
        根据用户查询，从向量库中检索最相关的文档块。
        """
        if isinstance(self.vector_store, LocalFAISSVectorStore):
            query_embedding = self.embedding_model.embed_query(query)
            # FAISS的search方法返回 (distance, document)
            results = self.vector_store.search(query_embedding, k=k)
            # 提取Document对象并根据距离排序（FAISS返回的已经是排序好的）
            # 注意：FAISS的距离是L2距离，越小越相似。
            # 这里直接返回Document对象，实际RAG中通常只关心内容
            retrieved_docs = [doc for dist, doc in results]
        elif isinstance(self.vector_store, LocalChromaVectorStore):
            # ChromaDB的search方法直接返回Document对象
            retrieved_docs = self.vector_store.search(query, k=k)
        else:
            raise TypeError("不支持的向量存储类型。")

        print(f"为查询 '{query}' 检索到 {len(retrieved_docs)} 个文档块。")
        return retrieved_docs

# 示例用法：
# if __name__ == "__main__":
#     # 假设已初始化 embedding_model 和 chroma_store (或 faiss_store)
#     embedding_model = initialize_embedding_model("sentence-transformers/all-MiniLM-L6-v2")
#     chroma_store = LocalChromaVectorStore("my_chroma_db", embedding_model)
#     # 如果数据库为空，添加一些示例文档
#     if chroma_store.get_document_count() == 0:
#         documents_raw = [
#             Document(page_content="Local RAG架构关注数据安全，所有操作都在本地完成。", metadata={"source": "doc1.txt"}),
#             Document(page_content="CPU推理是本地RAG的关键技术，需要优化模型。", metadata={"source": "doc2.txt"}),
#             Document(page_content="私有向量库如FAISS和ChromaDB适用于断网环境。", metadata={"source": "doc3.txt"}),
#             Document(page_content="量化技术可以有效减小LLM模型体积，提升CPU推理速度。", metadata={"source": "doc4.txt"}),
#             Document(page_content="文本切分策略影响检索质量，需要合理设置chunk_size和overlap。", metadata={"source": "doc5.txt"}),
#             Document(page_content="本地RAG系统可以保障企业敏感数据的隐私性，符合合规要求。", metadata={"source": "doc6.txt"}),
#             Document(page_content="嵌入模型如all-MiniLM-L6-v2在CPU上表现良好。", metadata={"source": "doc7.txt"}),
#             Document(page_content="FAISS提供了高效的相似度搜索功能。", metadata={"source": "doc8.txt"}),
#             Document(page_content="ChromaDB是一个易用的本地向量数据库。", metadata={"source": "doc9.txt"}),
#         ]
#         chunks = split_documents_into_chunks(documents_raw, chunk_size=100, chunk_overlap=20)
#         chroma_store.add_documents(chunks)
#
#     my_retriever = Retriever(chroma_store, embedding_model)
#
#     # 执行检索
#     user_query = "本地RAG的数据安全是如何实现的？"
#     retrieved_documents = my_retriever.retrieve(user_query, k=2)
#
#     print(f"n查询 '{user_query}' 的检索结果:")
#     for i, doc in enumerate(retrieved_documents):
#         print(f"  - Doc {i+1} (Source: {doc.metadata.get('source')}): {doc.page_content[:150]}...")

第五讲：CPU推理时代的本地大语言模型

在断网和CPU推理的严格限制下，我们无法直接运行数千亿参数的商用LLM。解决方案是选择小型化、经过优化和量化的模型。

5.1 小型化与量化技术

• 模型小型化：从一开始就选择参数量较小的模型，如1B-7B参数范围的模型。这些模型通常经过精心设计，在较小规模下也能展现出令人印象深刻的性能。例如，Microsoft Phi系列、Mistral-7B、Qwen-1.8B等。
• 量化（Quantization）：这是在CPU上运行大型模型最关键的技术。量化将模型参数从浮点数（如FP32）转换为低精度整数（如INT8、INT4甚至更低）。
  • GGUF (GPT-Generated Unified Format)：由llama.cpp项目推广的一种文件格式，专门用于在CPU上高效运行LLM。它支持多种量化级别，如Q4_K_M、Q5_K_M等，在保证一定精度的前提下，极大地减小了模型体积并加速了CPU推理。
  • ONNX (Open Neural Network Exchange)：一种开放的神经网络表示格式，支持多种深度学习框架的模型导出和导入。ONNX Runtime可以在CPU上提供优化的推理性能，也支持量化。

5.2 CPU推理框架与模型选择

• llama.cpp及其Python绑定 llama-cpp-python：这是当前在CPU上运行LLM最流行且高效的方案。llama.cpp由C++编写，高度优化，支持多种CPU指令集（如AVX2、AVX512），并提供了对GGUF格式模型的原生支持。llama-cpp-python提供了方便的Python接口。
• ONNX Runtime：如果模型以ONNX格式提供，ONNX Runtime是另一个强大的选择，它也支持CPU推理优化。

推荐的CPU友好型LLM（GGUF格式）：

模型名称	参数量	语言	推荐量化级别	估算文件大小 (Q4)	优点	缺点
Mistral-7B-Instruct-v0.2	7B	英文	Q4_K_M	~4.5GB	性能强大，理解能力好，指令遵循能力强。	体积相对较大，对内存要求略高。
Phi-2	2.7B	英文	Q4_K_M	~1.8GB	体积小巧，性能惊人，适合资源受限环境。	仅支持英文，可能不如7B模型泛化能力强。
Qwen1.5-1.8B-Chat	1.8B	中文/英文	Q4_K_M	~1.2GB	中文能力优秀，支持多语言，体积非常小。	相对较新，可能需要更多社区验证。
Llama-2-7B-Chat	7B	英文	Q4_K_M	~4.5GB	广泛使用，社区支持好。	性能可能略逊于Mistral。
CodeLlama-7B-Instruct	7B	英文	Q4_K_M	~4.5GB	专门针对代码生成和理解优化。	侧重代码，通用文本能力可能不如其他Chat模型。

模型下载：这些GGUF模型通常可以在Hugging Face Hub上找到，例如搜索 "Mistral-7B-Instruct-v0.2 GGUF"。在断网前，您需要手动下载这些模型文件（.gguf后缀）。

5.3 llama-cpp-python实战：加载与推理

from llama_cpp import Llama
import os

class LocalLLMGenerator:
    def __init__(self, model_path: str, n_ctx: int = 2048, n_batch: int = 512, verbose: bool = False):
        """
        初始化本地LLM生成器。
        :param model_path: GGUF模型文件的本地路径。
        :param n_ctx: 上下文窗口大小（token数量）。影响模型能处理的最大输入长度。
        :param n_batch: 批处理大小。影响推理速度。
        :param verbose: 是否打印详细日志。
        """
        if not os.path.exists(model_path):
            raise FileNotFoundError(f"GGUF模型文件未找到: {model_path}")

        self.model_path = model_path
        self.n_ctx = n_ctx
        self.n_batch = n_batch
        self.llm = None
        self._load_model(verbose)

    def _load_model(self, verbose: bool):
        """加载GGUF模型。"""
        try:
            print(f"正在加载GGUF模型: {self.model_path}...")
            self.llm = Llama(
                model_path=self.model_path,
                n_ctx=self.n_ctx,
                n_batch=self.n_batch,
                n_gpu_layers=0, # 强制使用CPU
                verbose=verbose,
                # kv_cache_dtype='f16', # 可以尝试优化KV缓存类型
            )
            print("GGUF模型加载成功 (CPU模式)。")
        except Exception as e:
            print(f"加载GGUF模型失败: {e}")
            print("请检查模型路径、文件完整性以及llama-cpp-python依赖。")
            raise

    def generate(self, prompt: str, max_tokens: int = 500, temperature: float = 0.7) -> str:
        """
        使用加载的LLM生成文本。
        :param prompt: 输入给LLM的提示文本。
        :param max_tokens: 生成的最大token数量。
        :param temperature: 采样温度，控制生成文本的随机性。
        :return: 生成的文本。
        """
        if self.llm is None:
            raise RuntimeError("LLM模型未加载。")

        try:
            output = self.llm(
                prompt,
                max_tokens=max_tokens,
                temperature=temperature,
                stop=["nUser:", "###", "User:"], # 根据模型和提示格式调整停止词
                echo=False # 不回显prompt
            )
            return output["choices"][0]["text"].strip()
        except Exception as e:
            print(f"LLM生成失败: {e}")
            return "对不起，生成回答时发生错误。"

# 示例用法：
# if __name__ == "__main__":
#     # 假设您已下载 Qwen1.5-1.8B-Chat-Q4_K_M.gguf 到 ./models/ 目录
#     # 请根据您实际下载的模型文件路径进行修改
#     model_dir = "./models"
#     model_name = "qwen1_5-1_8b-chat-q4_k_m.gguf" # 或 "mistral-7b-instruct-v0.2.Q4_K_M.gguf"
#     model_path = os.path.join(model_dir, model_name)
#
#     # 创建模型目录并放置模型文件 (手动操作)
#     if not os.path.exists(model_dir):
#         os.makedirs(model_dir)
#     # 此时，请确保 'qwen1_5-1_8b-chat-q4_k_m.gguf' 文件已存在于 'models/' 目录下
#     # 例如，可以从 https://huggingface.co/Qwen/Qwen1.5-1.8B-Chat-GGUF/blob/main/qwen1_5-1_8b-chat-q4_k_m.gguf 下载

#     try:
#         generator = LocalLLMGenerator(model_path=model_path, n_ctx=2048, n_batch=512)
#
#         # 构造一个简单的提示
#         simple_prompt = "请用中文描述一下Local RAG的核心优势。"
#         response = generator.generate(simple_prompt, max_tokens=150)
#         print(f"nLLM生成结果:n{response}")
#
#     except FileNotFoundError as e:
#         print(f"错误: {e}")
#         print("请确保已将GGUF模型文件下载到指定路径。")
#     except Exception as e:
#         print(f"发生其他错误: {e}")

依赖说明：pip install llama-cpp-python (注意，安装时可能需要编译C++代码，确保您的系统有C++编译器，如GCC或MSVC)。

第六讲：Local RAG系统集成与工作流

现在我们已经具备了构建Local RAG系统的所有核心组件：文档加载与切分、CPU友好的嵌入模型、本地向量库以及CPU推理的LLM。接下来，我们将它们整合起来，形成一个完整的RAG工作流。

6.1 RAG工作流编排与Prompt工程

RAG工作流的核心是将检索到的上下文有效地融入到LLM的提示中。一个典型的RAG提示模板如下：

你是一个专业的问答助手，请根据提供的上下文信息，简洁、准确地回答用户的问题。
如果上下文中没有足够的信息来回答问题，请说明你无法回答。

上下文信息:
{context}

用户问题:
{query}

回答:

这里的 {context} 将由检索器提供的文档块填充，{query} 则是用户的原始问题。

6.2 端到端Local RAG系统构建

我们将创建一个 LocalRAGSystem 类，封装整个RAG流程。

from langchain_core.documents import Document
import os
from typing import List

# 假设前面定义的类都已导入
# from your_module import load_documents_from_directory, split_documents_into_chunks, 
#                        initialize_embedding_model, LocalChromaVectorStore, Retriever, LocalLLMGenerator

class LocalRAGSystem:
    def __init__(self,
                 data_dir: str,
                 embedding_model_name: str,
                 vector_db_persist_dir: str,
                 llm_model_path: str,
                 chunk_size: int = 1000,
                 chunk_overlap: int = 200,
                 llm_n_ctx: int = 2048,
                 llm_n_batch: int = 512):
        """
        初始化端到端Local RAG系统。
        :param data_dir: 原始文档所在目录。
        :param embedding_model_name: 嵌入模型名称。
        :param vector_db_persist_dir: 向量数据库持久化目录。
        :param llm_model_path: GGUF LLM模型文件路径。
        :param chunk_size: 文本块大小。
        :param chunk_overlap: 文本块重叠大小。
        :param llm_n_ctx: LLM上下文窗口大小。
        :param llm_n_batch: LLM批处理大小。
        """
        self.data_dir = data_dir
        self.chunk_size = chunk_size
        self.chunk_overlap = chunk_overlap
        self.llm_n_ctx = llm_n_ctx
        self.llm_n_batch = llm_n_batch

        # 1. 初始化嵌入模型
        self.embedding_model = initialize_embedding_model(embedding_model_name)

        # 2. 初始化向量数据库 (这里使用ChromaDB作为示例)
        self.vector_store = LocalChromaVectorStore(vector_db_persist_dir, self.embedding_model)

        # 3. 初始化检索器
        self.retriever = Retriever(self.vector_store, self.embedding_model)

        # 4. 初始化LLM生成器
        self.llm_generator = LocalLLMGenerator(llm_model_path, n_ctx=llm_n_ctx, n_batch=llm_n_batch)

        print("nLocal RAG系统初始化完成。")

    def ingest_documents(self):
        """
        加载、切分文档并添加到向量数据库。
        首次运行或更新知识库时调用。
        """
        print(f"n--- 开始文档摄取 (Ingestion) 流程 ---")
        # 1. 加载文档
        documents = load_documents_from_directory(self.data_dir)
        if not documents:
            print("没有找到要摄取的文档。")
            return

        # 2. 切分文档
        chunks = split_documents_into_chunks(documents, self.chunk_size, self.chunk_overlap)

        # 3. 添加到向量数据库
        self.vector_store.add_documents(chunks)
        print(f"--- 文档摄取完成，向量库中共有 {self.vector_store.get_document_count()} 个文档块 ---")

    def query(self, user_query: str, top_k: int = 5, max_tokens: int = 500, temperature: float = 0.7) -> str:
        """
        执行RAG查询。
        :param user_query: 用户提出的问题。
        :param top_k: 检索Top-K个文档块。
        :param max_tokens: LLM生成最大token数。
        :param temperature: LLM生成温度。
        :return: LLM生成的回答。
        """
        print(f"n--- 处理查询: '{user_query}' ---")

        # 1. 检索阶段
        retrieved_docs = self.retriever.retrieve(user_query, k=top_k)

        if not retrieved_docs:
            print("未检索到相关文档，直接使用LLM回答。")
            context_str = "没有找到相关上下文信息。"
        else:
            # 拼接上下文
            context_str = "n".join([doc.page_content for doc in retrieved_docs])
            print(f"检索到 {len(retrieved_docs)} 个文档块作为上下文。")
            # print("--- 上下文内容 ---n" + context_str[:500] + "...n---") # 打印部分上下文

        # 2. 生成阶段
        # 构建RAG提示
        rag_prompt = f"""你是一个专业的问答助手，请根据提供的上下文信息，简洁、准确地回答用户的问题。
如果上下文中没有足够的信息来回答问题，请说明你无法回答。

上下文信息:
{context_str}

用户问题:
{user_query}

回答:
"""
        # print("--- 发送给LLM的完整提示 (部分) ---n" + rag_prompt[:800] + "...n---")

        response = self.llm_generator.generate(rag_prompt, max_tokens=max_tokens, temperature=temperature)
        print("--- LLM生成回答完成 ---")
        return response

# 示例用法：
if __name__ == "__main__":
    # 配置参数
    DATA_DIR = "data" # 存放您的私有文档
    EMBEDDING_MODEL_NAME = "sentence-transformers/all-MiniLM-L6-v2" # 英文模型
    # EMBEDDING_MODEL_NAME = "moka-ai/m3e-base" # 中文模型，请确保已下载
    VECTOR_DB_PERSIST_DIR = "chroma_db_local_rag"
    # 假设Qwen1.5-1.8B-Chat-Q4_K_M.gguf文件已位于 ./models/
    LLM_MODEL_PATH = os.path.join("models", "qwen1_5-1_8b-chat-q4_k_m.gguf") # 中文LLM
    # LLM_MODEL_PATH = os.path.join("models", "mistral-7b-instruct-v0.2.Q4_K_M.gguf") # 英文LLM

    # 1. 确保数据目录和模型目录存在，并放置好文件
    if not os.path.exists(DATA_DIR):
        os.makedirs(DATA_DIR)
        # 创建一些示例文档
        with open(os.path.join(DATA_DIR, "doc_security.txt"), "w", encoding="utf-8") as f:
            f.write("Local RAG系统在完全断网环境下运行，所有数据处理和模型推理都在本地CPU完成，确保数据安全和隐私。n"
                    "敏感数据永不离开本地机器，从而避免了云端数据泄露的风险。n"
                    "这对于金融、医疗等行业的数据合规性至关重要。n"
                    "通过本地加密和严格的访问控制，可以进一步提升安全性。")
        with open(os.path.join(DATA_DIR, "doc_performance.txt"), "w", encoding="utf-8") as f:
            f.write("CPU推理性能是Local RAG的挑战之一。n"
                    "我们通过选择小型化、量化（如GGUF格式）的LLM模型来优化性能。n"
                    "嵌入模型也选择CPU高效的Sentence Transformers系列。n"
                    "FAISS和ChromaDB等本地向量库提供了快速的相似度搜索。n"
                    "批量处理和KV缓存优化可以进一步提升推理速度。")
        print(f"创建了示例文档于 {DATA_DIR} 目录。")

    if not os.path.exists(os.path.dirname(LLM_MODEL_PATH)):
        os.makedirs(os.path.dirname(LLM_MODEL_PATH))
        print(f"请手动将LLM模型文件 '{os.path.basename(LLM_MODEL_PATH)}' 放置到 '{os.path.dirname(LLM_MODEL_PATH)}' 目录。")
        exit() # 退出程序，提示用户手动操作

    # 2. 初始化Local RAG系统
    try:
        rag_system = LocalRAGSystem(
            data_dir=DATA_DIR,
            embedding_model_name=EMBEDDING_MODEL_NAME,
            vector_db_persist_dir=VECTOR_DB_PERSIST_DIR,
            llm_model_path=LLM_MODEL_PATH,
            chunk_size=500,
            chunk_overlap=100,
            llm_n_ctx=2048, # 根据LLM模型和RAM调整
            llm_n_batch=512 # 根据CPU核心数和RAM调整
        )
    except Exception as e:
        print(f"RAG系统初始化失败: {e}")
        print("请检查模型文件路径、依赖库安装和缓存。")
        exit()

    # 3. 摄取文档 (如果向量数据库为空或需要更新)
    if rag_system.vector_store.get_document_count() == 0:
        rag_system.ingest_documents()

    # 4. 执行查询
    user_question = "Local RAG如何保障数据安全？"
    response = rag_system.query(user_question, top_k=3, max_tokens=200)
    print(f"n用户问题: {user_question}")
    print(f"RAG系统回答:n{response}")

    user_question_2 = "Local RAG在CPU推理方面有哪些优化？"
    response_2 = rag_system.query(user_question_2, top_k=2, max_tokens=150)
    print(f"n用户问题: {user_question_2}")
    print(f"RAG系统回答:n{response_2}")

第七讲：断网环境下的数据安全与隐私保障

Local RAG架构天生就具备高级别的数据安全和隐私保护能力，因为所有敏感数据和处理过程都保留在本地。但这并不意味着我们可以掉以轻心，仍有几个关键点需要加强。

7.1 本地数据加密

即使数据不离开本地机器，本地存储也可能面临物理访问或恶意软件的威胁。

• 文件系统加密：操作系统级别的文件系统加密（如Windows的BitLocker、macOS的FileVault、Linux的LUKS）是最基础也是最有效的保护措施。它能确保即使硬盘被盗，数据也无法被未经授权者访问。
• 应用程序级加密：对于特别敏感的数据，可以在应用程序层面进行加密。例如，在将原始文档存储到本地文件系统之前进行加密，或者对向量库中的元数据进行加密。虽然FAISS和ChromaDB本身不提供内置的加密功能，但您可以：
  • 在将文档内容传递给向量库之前，对其进行加密。检索时，先解密上下文再交给LLM。
  • 加密存储向量库文件的目录。

# 示例：一个非常简化的文件内容加密/解密函数 (实际应用应使用更强大的加密库，如PyCryptodome)
from cryptography.fernet import Fernet # pip install cryptography

def generate_key():
    """生成一个用于对称加密的密钥。"""
    return Fernet.generate_key()

def encrypt_data(data: str, key: bytes) -> bytes:
    """加密字符串数据。"""
    f = Fernet(key)
    return f.encrypt(data.encode('utf-8'))

def decrypt_data(encrypted_data: bytes, key: bytes) -> str:
    """解密字节数据。"""
    f = Fernet(key)
    return f.decrypt(encrypted_data).decode('utf-8')

# 实际应用中，密钥需要安全存储，不能硬编码
# encryption_key = generate_key() # 首次生成并安全存储
# encrypted_content = encrypt_data("这是我的秘密文档内容。", encryption_key)
# decrypted_content = decrypt_data(encrypted_content, encryption_key)

7.2 供应链安全

即使在断网环境下，您使用的模型和库也来自外部。确保这些组件的安全性至关重要。

• 模型来源验证：只从可信的、官方的源下载GGUF模型。核对模型的哈希值，确保下载的文件未被篡改。
• 库依赖审计：定期检查项目依赖的第三方库是否存在已知的安全漏洞。使用pip-audit或Snyk等工具进行扫描。
• 离线安装：一旦确认依赖安全，可以在联网环境中一次性下载所有依赖包，然后进行离线安装，避免后续因网络访问而引入新的风险。

7.3 隔离与沙箱

对于极度敏感的环境，可以将整个Local RAG系统部署在：

• 虚拟化环境：如VMware、VirtualBox中的虚拟机，提供更强的隔离性。
• 容器化环境：如Docker容器。虽然Docker通常用于部署到服务器，但在本地，它也能提供一个隔离的运行环境，方便管理依赖，并限制应用对宿主系统的访问权限。

第八讲：性能优化与实用考量

即使是CPU推理，我们也能通过多种手段优化性能，提升用户体验。

8.1 硬件与系统优化

• CPU核心数与频率：更多的CPU核心和更高的主频能显著提升LLM推理速度，因为llama.cpp等框架能有效利用多核并行计算。
• 内存（RAM）：LLM模型和向量库都需要加载到内存中。确保有足够的RAM（通常8GB-32GB甚至更多，取决于模型大小和知识库规模）是流畅运行的基础。如果内存不足，系统会频繁使用交换空间，导致性能急剧下降。
• 固态硬盘（SSD）：模型加载、向量库的读写速度会受到硬盘性能影响。SSD比传统HDD快得多，能显著缩短启动和数据加载时间。
• 操作系统优化：确保操作系统和驱动是最新版本，关闭不必要的后台服务，为RAG应用分配足够的系统资源。

8.2 批量处理与缓存

• 批量嵌入：在构建向量库时，批量处理文本块来生成嵌入向量，可以显著提高效率。HuggingFaceEmbeddings内部通常会进行批处理。
• LLM KV缓存：llama.cpp在生成文本时会利用KV缓存（Key-Value Cache），避免重复计算注意力机制中的Key和Value。合理设置n_ctx和n_batch有助于充分利用缓存。
• 结果缓存：对于重复查询，可以缓存RAG系统的最终回答，避免重复检索和生成。

8.3 评估指标

即使是本地系统，也需要评估其性能和效果。

• 检索准确率：衡量检索器是否能找出真正相关的文档。可以使用召回率（Recall）和精确率（Precision）等指标。
• 生成质量：评估LLM回答的准确性、流畅性、相关性和完整性。这通常需要人工评估，或使用RAG specific metrics (如 faithfulness, answer relevancy, context relevancy) 结合一些自动化工具。
• 响应时间：从用户提问到获得回答的总时间。这是用户体验最直观的指标。

结语：本地智能，掌控未来

Local RAG架构不仅仅是一种技术实现，它更代表了一种对数据主权和自主智能的追求。在完全断网的环境下，利用私有向量库与CPU推理，我们证明了即使没有云端巨头的支持，也能构建出强大、安全、可靠的智能问答系统。

这种能力对于保护敏感信息、遵守严格法规、确保业务连续性以及在资源受限环境中拓展AI应用边界，都具有不可估量的价值。通过本讲座，希望各位能够掌握Local RAG的核心技术，并在此基础上，根据自己的实际需求，构建出满足特定安全和性能要求的本地化智能解决方案。本地智能，掌控未来，让我们共同开启AI应用的新篇章。