PageIndex：基于RAG的网页智能知识库构建实战指南

1. 项目概述：从“网页索引”到“智能知识库”的进化

最近在折腾一个很有意思的项目，叫 PageIndex。乍一看名字，你可能会觉得这又是一个简单的网页爬虫或者内容抓取工具。但如果你深入了解一下，就会发现它的野心远不止于此。本质上，PageIndex 是一个旨在将任意网页内容，通过向量化处理，构建成可被高效检索的智能知识库的开源项目。它解决的核心痛点，是信息过载时代下，如何从海量的、非结构化的网页信息中，快速、精准地找到你需要的“知识片段”，而不是让你重新去大海捞针。

想象一下这个场景：你正在研究一个复杂的技术问题，比如“如何在 Kubernetes 中实现有状态应用的高可用部署”。你可能会打开十几个浏览器标签页，里面是官方文档、技术博客、Stack Overflow 问答、GitHub Issue 讨论等等。每个页面都包含部分答案，但信息分散、冗余，甚至可能存在矛盾。你需要反复切换、阅读、对比，才能拼凑出完整的图景。PageIndex 要做的，就是帮你把这些散落在各处的“知识碎片”收集起来，用一种更聪明的方式组织好，让你可以用自然语言提问，直接得到整合后的、最相关的答案。

这个项目背后，是当前 AI 应用开发，特别是基于大语言模型（LLM）构建智能助手或知识库应用时，一个非常核心且通用的需求：检索增强生成（RAG）。RAG 的核心在于，将外部知识源（如文档、网页）向量化后存入向量数据库，当用户提问时，先从向量库中检索出最相关的上下文片段，再连同问题一起喂给 LLM 生成答案。PageIndex 正是瞄准了 RAG 流程中的“知识源处理”这一关键环节，提供了一个专门针对网页内容的、开箱即用的解决方案。

它适合谁呢？首先，是独立开发者或小团队，想要快速为自己的产品（比如客服机器人、内部知识库、研究助手）接入网页内容作为知识源，但又不想从零开始写爬虫、处理 HTML、做文本分块和向量化。其次，是研究人员或数据分析师，需要定期跟踪特定网站的内容更新，并希望以结构化的方式进行分析和查询。最后，对于任何对 AI 应用开发感兴趣的爱好者来说，PageIndex 也是一个绝佳的学习案例，可以让你直观地理解 RAG 技术栈中数据预处理管道的完整实现。

2. 核心设计思路：构建一个健壮的网页处理管道

PageIndex 的设计哲学非常清晰：将复杂的网页内容处理流程，拆解成一系列职责单一、可插拔的模块，形成一个稳定可靠的数据处理管道（Pipeline）。这种模块化设计不仅让代码结构清晰，更赋予了项目极强的灵活性和可扩展性。我们来拆解一下这个管道的核心环节。

2.1 从 URL 到纯净文本：内容提取的挑战与应对

一切始于一个 URL。但网页不是为机器阅读而生的，它充满了导航栏、广告、侧边栏、页脚等“噪音”。第一步，就是如何高效、准确地将主内容提取出来。

PageIndex 通常会集成像readability、newspaper3k或trafilatura这样的库。这些库背后是经过大量网页样本训练的算法，能够识别出文章标题、作者、发布时间和正文内容。但这里有个关键细节：没有一种提取算法是万能的。技术博客的代码块、电商网站的产品规格表、论坛的嵌套回复，这些特殊结构都可能让通用提取器“失明”。

因此，一个健壮的设计是采用“后备策略”或“组合策略”。例如，优先使用readability提取，如果提取出的正文过短或质量不高（比如全是导航链接），则回退到更基础的 HTML 标签解析（如寻找<article>,<main>标签或计算文本密度）。在 PageIndex 的实现中，你可能会看到一个ContentExtractor的抽象类，不同的提取策略作为其子类，通过一个简单的决策逻辑来选用。

注意：对于 JavaScript 重度渲染的现代单页应用（SPA），上述基于静态 HTML 的提取器会完全失效。这时就需要引入无头浏览器，如Playwright或Selenium，在真实浏览器环境中加载页面、等待渲染完成后再获取 HTML。这虽然带来了额外的复杂性和性能开销，但对于某些知识源来说是必须的。PageIndex 可能会将这一部分作为可选的高级模块。

2.2 文本分块的艺术：平衡上下文与精度

提取出纯净的连续文本后，下一个关键步骤是分块（Chunking）。这是影响后续检索效果最关键的环节之一。为什么不能把整篇文章作为一个向量存入数据库？因为 LLM 有上下文长度限制，且过长的文本会包含大量无关信息，稀释核心内容的语义，导致检索精度下降。

分块的目标是：将长文本切割成一个个语义相对完整、长度适中的片段。最 naive 的方法是固定字符数切割（比如每 500 字符一块）。但这样很容易把一个完整的句子或段落从中间切断，破坏语义。

更优的方案是使用递归字符文本分割器。它的工作原理是：先尝试用较大的分隔符（如“\n\n”）分割，如果分割后的块仍然太大，则用次一级的分隔符（如“\n”）继续分割，依此类推，直到每个块的大小落在预设的区间内（如 200-1000 字符）。同时，可以设置一个较小的重叠区间（如 50-200 字符），让相邻的块有一小部分内容重叠，这能有效避免检索时因切割而丢失跨越两个块的关键信息。

# 示例：使用 LangChain 的 RecursiveCharacterTextSplitter from langchain.text_splitter import RecursiveCharacterTextSplitter splitter = RecursiveCharacterTextSplitter( chunk_size=500, # 目标块大小 chunk_overlap=50, # 块间重叠字符数 length_function=len, separators=["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""] # 中文场景下的分隔符优先级 ) chunks = splitter.split_text(extracted_text)

对于代码、Markdown 或特定格式的文档，还可以采用更智能的分割器，如按标题层级（##）、代码块（```）或列表进行分割。PageIndex 的设计可能会预留接口，允许用户根据源网页的类型注入自定义的分块策略。

2.3 向量化与元数据：为文本赋予可检索的“灵魂”

分块后的文本是机器可读的，但还不是机器可“理解”和“比较”的。向量化（Embedding）就是将这些文本块转换为高维空间中的向量（一组数字）。语义相似的文本，其向量在空间中的距离（如余弦相似度）也更近。

PageIndex 的核心必然会集成一个或多个文本嵌入模型。开源领域，Sentence Transformers系列模型（如all-MiniLM-L6-v2）因其在速度和效果上的平衡而被广泛使用。云服务方面，OpenAI 的text-embedding-ada-002或 Cohere 的嵌入 API 也是常见选择。项目的配置中，应该允许用户灵活指定嵌入模型。

但仅仅存储向量是不够的。高效的检索系统还需要丰富的元数据（Metadata）。每个文本块在存入向量数据库时，至少应该附带以下信息：

• source: 源 URL。
• title: 网页标题。
• chunk_index: 该块在原文中的顺序。
• text_length: 文本块长度。
• 可能还有author,publish_date,language等。

这些元数据有两个重要作用：1.过滤：检索时，可以限定只从某个网站或某个日期之后的内容中查找。2.引用溯源：当 LLM 基于检索到的块生成答案时，可以明确指出信息来源是哪个 URL 的哪部分内容，极大增强了答案的可信度。

2.4 向量数据库的选择与集成：持久化与快速检索

处理好的向量和元数据需要被持久化存储，并支持快速的近似最近邻搜索。这就是向量数据库的职责。PageIndex 作为一个开源项目，很可能会优先支持轻量级、易部署的本地向量数据库，例如：

• ChromaDB: 简单易用，API 友好，非常适合原型开发和中小型项目。
• FAISS(Facebook AI Similarity Search): 一个库而非数据库，专注于高效的相似性搜索，性能极佳，但需要自己处理元数据存储和持久化。
• Qdrant/Weaviate: 功能更全面的向量数据库，支持过滤、分片等高级特性，可以 Docker 部署。

在架构上，PageIndex 会定义一个VectorStore接口或抽象类，然后为不同的数据库实现具体的适配器（如ChromaAdapter,FaissAdapter）。这样，用户就可以通过配置文件轻松切换后端，而无需改动核心的业务逻辑。

3. 实操流程：手把手构建你的第一个网页知识库

理论讲完了，我们来点实际的。假设我们要用 PageIndex（或者其思想）构建一个关于“机器学习实践”的微型知识库，源数据来自几篇知名的技术博客。

3.1 环境准备与项目初始化

首先，我们需要一个干净的 Python 环境（建议 3.8+）。使用虚拟环境是个好习惯。

# 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # 安装核心依赖 # 假设 PageIndex 已发布到 PyPI，这里列出其可能的核心依赖 pip install requests beautifulsoup4 readability-lxml langchain sentence-transformers chromadb # 如果需要处理 JS 渲染页面，额外安装 # pip install playwright # playwright install chromium

接下来，我们规划项目结构。一个清晰的结构有助于长期维护：

my_pageindex_project/ ├── config.yaml # 配置文件 ├── src/ │ ├── __init__.py │ ├── crawler.py # 爬虫/URL 收集模块 │ ├── processor.py # 内容提取、分块、向量化管道 │ ├── vectordb.py # 向量数据库交互封装 │ └── query.py # 查询检索模块 ├── data/ │ ├── raw_html/ # 原始 HTML 缓存（可选） │ ├── processed/ # 处理后的文本块（可选） │ └── chroma_db/ # Chroma 数据库存储路径 └── main.py # 主执行入口

3.2 配置解析与核心参数设定

我们将关键配置放在config.yaml中，实现代码与配置的分离。

# config.yaml sources: - url: "https://example.com/blog/ml-ops-best-practices" depth: 0 # 爬取深度，0表示只爬本页 - url: "https://anotherblog.ai/understanding-transformers" depth: 0 processing: extractor: "readability" # 或 "bs4", "trafilatura" chunk_size: 512 chunk_overlap: 50 separators: ["\n\n", "\n", ". ", "? ", "! ", " ", ""] embedding: model_name: "sentence-transformers/all-MiniLM-L6-v2" device: "cpu" # 或 "cuda" # 若使用 OpenAI，则配置 api_key 和 model # provider: "openai" # model: "text-embedding-ada-002" vectordb: provider: "chroma" persist_directory: "./data/chroma_db" collection_name: "ml_knowledge_base" query: top_k: 5 # 每次检索返回的最相关块数量

在代码中，我们使用一个Config类来加载和管理这些配置。

3.3 实现网页抓取与内容处理管道

现在，我们实现processor.py中的核心管道。

# src/processor.py import yaml import requests from readability import Document from langchain.text_splitter import RecursiveCharacterTextSplitter from sentence_transformers import SentenceTransformer import logging logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) class PageProcessor: def __init__(self, config): self.config = config self.extractor_type = config['processing']['extractor'] # 初始化文本分割器 self.text_splitter = RecursiveCharacterTextSplitter( chunk_size=config['processing']['chunk_size'], chunk_overlap=config['processing']['chunk_overlap'], separators=config['processing']['separators'] ) # 初始化嵌入模型 emb_config = config['embedding'] if emb_config.get('provider', 'sentence-transformers') == 'sentence-transformers': self.embed_model = SentenceTransformer(emb_config['model_name'], device=emb_config['device']) # 注意：这里省略了 OpenAI 等云端模型初始化的代码 logger.info("Processor initialized.") def fetch_and_extract(self, url): """抓取URL并提取主要内容""" try: headers = {'User-Agent': 'Mozilla/5.0 (PageIndex Bot)'} response = requests.get(url, headers=headers, timeout=10) response.raise_for_status() html_content = response.text if self.extractor_type == 'readability': doc = Document(html_content) title = doc.title() content = doc.summary() # 返回的是清理后的HTML # 需要将HTML转换为纯文本 from bs4 import BeautifulSoup soup = BeautifulSoup(content, 'html.parser') clean_text = soup.get_text(separator='\n', strip=True) else: # 其他提取器的实现... raise ValueError(f"Unsupported extractor: {self.extractor_type}") return { 'url': url, 'title': title, 'raw_text': clean_text, 'success': True } except Exception as e: logger.error(f"Failed to process {url}: {e}") return {'url': url, 'success': False, 'error': str(e)} def chunk_text(self, text, metadata): """将文本分割成块，并附加元数据""" chunks = self.text_splitter.split_text(text) chunk_metadatas = [] for i, chunk in enumerate(chunks): chunk_meta = metadata.copy() chunk_meta.update({ 'chunk_index': i, 'chunk_size': len(chunk), }) chunk_metadatas.append(chunk_meta) return chunks, chunk_metadatas def embed_chunks(self, chunks): """将文本块列表转换为向量列表""" # Sentence Transformers 模型可以直接处理字符串列表 embeddings = self.embed_model.encode(chunks, show_progress_bar=False) return embeddings.tolist() # 转换为Python list

这个PageProcessor类封装了从抓取到向量化的主要逻辑。注意异常处理和对网络请求的超时控制，这在处理大量外部 URL 时至关重要。

3.4 与向量数据库交互

接下来，我们实现vectordb.py，用于处理向量的存储和检索。

# src/vectordb.py import chromadb from chromadb.config import Settings import hashlib from typing import List, Dict, Any import logging logger = logging.getLogger(__name__) class VectorDBManager: def __init__(self, config): self.config = config vdb_config = config['vectordb'] self.persist_dir = vdb_config['persist_directory'] self.collection_name = vdb_config['collection_name'] # 初始化 Chroma 客户端，持久化数据到磁盘 self.client = chromadb.PersistentClient(path=self.persist_dir) # 获取或创建集合 self.collection = self.client.get_or_create_collection( name=self.collection_name, metadata={"hnsw:space": "cosine"} # 使用余弦相似度 ) logger.info(f"Connected to vector database collection: {self.collection_name}") def _generate_id(self, url: str, chunk_index: int) -> str: """生成唯一的文档ID，避免重复插入""" input_str = f"{url}_{chunk_index}" return hashlib.md5(input_str.encode()).hexdigest() def add_documents(self, chunks: List[str], metadatas: List[Dict[str, Any]], embeddings: List[List[float]]): """将文本块、元数据和向量添加到数据库""" if not (len(chunks) == len(metadatas) == len(embeddings)): raise ValueError("chunks, metadatas and embeddings must have the same length") ids = [self._generate_id(meta['url'], meta['chunk_index']) for meta in metadatas] # 检查哪些ID已存在，避免重复插入 existing = self.collection.get(ids=ids) existing_ids = set(existing['ids']) if existing['ids'] else set() new_ids, new_chunks, new_metadatas, new_embeddings = [], [], [], [] for idx, chunk_id in enumerate(ids): if chunk_id not in existing_ids: new_ids.append(chunk_id) new_chunks.append(chunks[idx]) new_metadatas.append(metadatas[idx]) new_embeddings.append(embeddings[idx]) if new_ids: self.collection.add( ids=new_ids, documents=new_chunks, metadatas=new_metadatas, embeddings=new_embeddings ) logger.info(f"Added {len(new_ids)} new documents to the database.") else: logger.info("No new documents to add.") def search(self, query_embedding: List[float], top_k: int = 5, filter_dict: Dict = None) -> List[Dict]: """根据查询向量进行相似性搜索""" results = self.collection.query( query_embeddings=[query_embedding], n_results=top_k, where=filter_dict # 可用于元数据过滤，如 where={"source": "特定网站"} ) # 整理返回格式 returned_docs = [] for i in range(len(results['ids'][0])): returned_docs.append({ 'id': results['ids'][0][i], 'document': results['documents'][0][i], 'metadata': results['metadatas'][0][i], 'distance': results['distances'][0][i] # 距离越小越相似 }) return returned_docs

这里的关键点在于_generate_id方法，它确保了同一 URL 的同一文本块不会被重复插入。add_documents方法中的去重逻辑，对于支持增量更新的知识库非常重要。

3.5 组装完整流程并执行索引

最后，我们在main.py中把一切串联起来。

# main.py from src.processor import PageProcessor from src.vectordb import VectorDBManager import yaml import time def load_config(config_path='config.yaml'): with open(config_path, 'r', encoding='utf-8') as f: return yaml.safe_load(f) def main(): config = load_config() processor = PageProcessor(config) db_manager = VectorDBManager(config) sources = config['sources'] for source in sources: url = source['url'] print(f"\nProcessing: {url}") # 1. 抓取并提取 result = processor.fetch_and_extract(url) if not result['success']: print(f" Failed: {result.get('error')}") continue # 2. 分块 chunks, chunk_metadatas = processor.chunk_text( result['raw_text'], {'url': url, 'title': result['title'], 'source': 'manual_import'} ) print(f" Split into {len(chunks)} chunks.") # 3. 向量化 print(" Generating embeddings...") embeddings = processor.embed_chunks(chunks) # 4. 存入向量数据库 db_manager.add_documents(chunks, chunk_metadatas, embeddings) print(f" Saved to database.") # 礼貌性延迟，避免对目标服务器造成压力 time.sleep(2) print("\nIndexing completed!") if __name__ == "__main__": main()

运行python main.py，你的第一个网页知识库的索引过程就开始了。你会看到控制台输出每个 URL 的处理状态、分块数量以及存储结果。

4. 查询与检索：让知识库“开口说话”

索引建好了，怎么用呢？我们需要一个查询接口。这通常是一个独立的脚本或服务。

# src/query.py from sentence_transformers import SentenceTransformer from .vectordb import VectorDBManager import yaml class QueryEngine: def __init__(self, config_path='config.yaml'): with open(config_path, 'r') as f: self.config = yaml.safe_load(f) # 加载与索引时相同的嵌入模型 emb_config = self.config['embedding'] self.embed_model = SentenceTransformer(emb_config['model_name'], device=emb_config['device']) self.db_manager = VectorDBManager(self.config) self.top_k = self.config['query']['top_k'] def ask(self, question: str, filter_by_source: str = None): """核心查询方法""" # 1. 将问题转换为向量 query_embedding = self.embed_model.encode(question).tolist() # 2. 构建过滤条件（可选） filter_dict = None if filter_by_source: filter_dict = {"source": filter_by_source} # 3. 在向量数据库中搜索 search_results = self.db_manager.search(query_embedding, top_k=self.top_k, filter_dict=filter_dict) # 4. 格式化返回结果 context = "" sources = set() for res in search_results: context += f"[来自: {res['metadata']['title']}]\n{res['document']}\n\n" sources.add(res['metadata']['url']) return { 'question': question, 'context': context.strip(), 'sources': list(sources), 'raw_results': search_results # 包含详细元数据和相似度分数 } # 简单的命令行交互 if __name__ == "__main__": engine = QueryEngine() print("知识库查询引擎已启动。输入 'quit' 退出。") while True: try: query = input("\n请输入你的问题: ") if query.lower() in ['quit', 'exit', 'q']: break if not query.strip(): continue answer = engine.ask(query) print("\n" + "="*50) print(f"问题: {answer['question']}") print("-"*50) print("检索到的相关上下文:") print(answer['context']) print("-"*50) print("信息来源:") for src in answer['sources']: print(f" - {src}") print("="*50) except KeyboardInterrupt: break except Exception as e: print(f"查询出错: {e}")

这个QueryEngine提供了最核心的检索功能。它展示了 RAG 中 “Retrieval” 部分的完整流程。获取到context后，你可以将其与原始问题一起，发送给 OpenAI GPT、Claude 或本地部署的 Llama 等 LLM，来生成最终的、基于上下文的答案，这就是完整的 RAG 流程。

5. 进阶优化与生产级考量

一个玩具系统到生产可用的服务，还有很长的路要走。PageIndex 要真正强大，必须在以下几个方向进行深度优化。

5.1 内容质量过滤与去重

不是所有抓取到的内容都有价值。我们需要引入质量过滤机制：

• 文本质量评估：过滤掉正文过短（如 < 100 字符）、广告文本密度过高、或主要包含导航链接的页面。
• 语言检测：如果只关注中文内容，可以使用langdetect库过滤非中文网页。
• 语义去重：即使 URL 不同，内容也可能高度相似（如转载）。可以在向量化后，计算新块与库中现有块的余弦相似度，如果超过阈值（如 0.95），则视为重复，仅更新元数据而不新增。

# 简化的语义去重逻辑示例 def deduplicate_by_semantic(self, new_embedding, new_chunk_meta, threshold=0.95): # 临时搜索最相似的Top1现有块 existing = self.collection.query(query_embeddings=[new_embedding], n_results=1) if existing['distances'][0] and existing['distances'][0][0] > threshold: logger.info(f"Chunk from {new_chunk_meta['url']} is duplicate of {existing['ids'][0][0]}, skipped.") return True return False

5.2 增量更新与实时性维护

知识库不是一成不变的。网页会更新，我们需要支持增量更新。

1. 定期抓取：为每个 URL 记录其last_modified（从 HTTP 头获取）或内容的哈希值。定期重新抓取，如果发现变化，则重新处理该页面。
2. 智能更新策略：重新处理一个页面后，需要先删除该页面对应的所有旧块，再插入新块。这可以通过元数据过滤实现（where={"url": target_url}进行删除，然后插入新块）。
3. 处理删除：如果某个源 URL 失效（返回 404），可能需要将相关块标记为过期或归档，而不是立即删除，以防误删。

5.3 性能优化与大规模处理

当需要索引成千上万个页面时，性能成为瓶颈。

• 异步并发抓取：使用aiohttp和asyncio实现异步 HTTP 客户端，可以成倍提升抓取速度。
• 批量向量化与入库：嵌入模型对批量输入的处理效率远高于单条。应积累一定数量的文本块（如 100 条）后，一次性生成向量并批量入库。
• 分布式处理：对于超大规模数据，可以将 URL 列表分片，由多个工作节点并行处理，最后将向量统一存入一个中心化的向量数据库。

5.4 元数据增强与混合搜索

更丰富的元数据意味着更强大的检索能力。

• 自动标签生成：利用轻量级 NLP 模型或关键词提取算法（如RAKE,YAKE）为每个文本块自动生成关键词标签，存入元数据。
• 时间加权搜索：在检索时，除了语义相似度，还可以引入时间因子，让较新的内容获得更高的排名。
• 混合搜索：结合稠密向量检索（语义相似）和稀疏向量检索（关键词匹配，如 BM25）。例如，可以用向量检索得到 Top 20 个候选，再用关键词匹配进行重排序，兼顾语义和字面匹配。Chroma和Weaviate等数据库已开始支持混合搜索。

6. 常见问题与实战排坑指南

在实际操作中，你一定会遇到各种问题。以下是我在类似项目中踩过的坑和总结的经验。

6.1 内容提取失败或质量差

• 问题：提取出的正文包含大量无关文本，或漏掉了主要内容。
• 排查：
  1. 检查网页结构：用浏览器开发者工具查看，主内容是否在特定的<div>或<article>标签内，且是否有明显的id或class。
  2. 测试不同提取器：换用trafilatura或newspaper3k试试，不同库对不同网站模板的适应性不同。
  3. 查看原始 HTML：有时候网站会通过奇怪的标签或样式包裹内容，可能需要写一个简单的自定义 XPath 或 CSS 选择器来定位。
• 解决：实现一个“提取器降级链”。优先用智能提取器（如readability），失败或结果质量差（如文本长度小于阈值）时，降级到基于规则的方法（如用BeautifulSoup找<main>或计算文本密度最大的区域）。

6.2 文本分块导致语义断裂

• 问题：一个完整的概念或代码示例被切割到两个块中，检索时只能返回一半信息。
• 排查：检查分块后的文本，特别是块的开头和结尾，是否在句子或段落中间断开。
• 解决：
  1. 调整分隔符优先级：对于中文，将句号、问号、感叹号放在换行符之前。separators=["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""]。
  2. 增加重叠大小：适当增加chunk_overlap参数（如从 50 调到 100 或 200），确保关键信息有冗余。
  3. 使用语义分块：更高级的方法是使用 NLP 模型判断句子边界和语义连贯性进行分块，但这会显著增加计算开销。

6.3 检索结果不相关

• 问题：提出的问题明明在知识库中，但返回的文本块完全不相关。
• 排查：
  1. 检查查询向量化：确保查询语句和索引时使用的是同一个嵌入模型。不同模型生成的向量空间不同，无法直接比较。
  2. 检查向量数据库的相似度度量：确保创建集合时指定的距离度量（如余弦相似度、内积、欧氏距离）与嵌入模型训练时使用的度量一致。Sentence Transformers模型通常使用余弦相似度。
  3. 观察原始文本块：直接查看被索引的文本块内容，是否清晰、完整地表达了某个知识点？噪声是否过多？
• 解决：
  1. 统一模型和度量标准。
  2. 优化分块策略，确保每个块是自包含的语义单元。
  3. 在查询时，尝试对原始问题进行查询扩展。例如，使用 LLM 为问题生成几个同义或相关的问法，将这些问法一起向量化并检索，然后合并结果。

6.4 向量数据库性能或内存问题

• 问题：数据量变大后，检索变慢，或内存消耗过高。
• 排查：
  1. 数据量：向量数据库存储了多少条记录？每条记录的向量维度是多少？
  2. 索引类型：Chroma默认使用hnswlib作为索引，它是在精度、速度和内存之间取得平衡的选择。FAISS则有更多索引类型（如IndexFlatL2,IndexIVFFlat）可供选择。
• 解决：
  1. 选择合适的索引：对于千万级以下的数据，HNSW通常是好选择。对于十亿级数据，可能需要IVF类索引进行聚类。
  2. 向量维度：考虑使用维度更小的嵌入模型（如all-MiniLM-L6-v2是 384 维，all-mpnet-base-v2是 768 维），在精度损失可接受的前提下提升速度和节省空间。
  3. 持久化与加载：确保正确配置持久化路径。对于FAISS，需要显式调用write_index和read_index。

6.5 处理动态网页与反爬机制

• 问题：无法抓取到内容，或收到 403 等错误。
• 排查：
  1. 检查 User-Agent：使用常见的浏览器 User-Agent。
  2. 检查 JavaScript 渲染：页面内容是否由 JS 动态加载？查看网页源代码（Ctrl+U），如果看不到正文，就需要无头浏览器。
  3. 频率限制：是否抓取太快触发了反爬？
• 解决：
  1. 使用无头浏览器：集成Playwright，但这是最后的手段，因为它慢且重。
  2. 设置请求头：模拟真实浏览器，包括User-Agent,Accept,Accept-Language等。
  3. 添加延迟与代理：在请求间添加随机延迟（如time.sleep(random.uniform(1, 3))）。对于大规模抓取，考虑使用代理 IP 池。
  4. 尊重 robots.txt：在抓取前检查网站的robots.txt文件，避免抓取被禁止的页面。

构建一个像 PageIndex 这样的系统，最难的不是实现单个功能，而是在实际运行中应对各种边角案例和异常情况。我的经验是，尽早建立完善的日志和监控系统。记录每个 URL 的处理状态（成功、失败、跳过）、处理耗时、提取出的文本长度等。这些日志是后期优化和排查问题最宝贵的依据。例如，你可以定期分析失败率最高的网站类型，然后针对性地优化你的提取器链。记住，一个健壮的数据管道，其价值远高于一个在理想数据上表现完美的算法。