第4章: RAG 快速上手：文档→向量→可检索问答

from langchain_community.document_loaders import TextLoader

# 加载文本文件
loader = TextLoader("data/article.txt", encoding="utf-8")
documents = loader.load()

# 查看加载结果
print(f"加载了 {len(documents)} 个文档")
print(f"内容: {documents[0].page_content[:100]}...")
print(f"元数据: {documents[0].metadata}")

from langchain_community.document_loaders import Docx2txtLoader

# 加载Word文档（示例：data/6.docx）
loader = Docx2txtLoader("data/6.docx")
documents = loader.load()

print(f"加载了 {len(documents)} 个文档")
print(f"内容: {documents[0].page_content[:200]}...")
print(f"元数据: {documents[0].metadata}")

from langchain_community.document_loaders import WebBaseLoader

# 加载网页内容
loader = WebBaseLoader("https://python.langchain.com/docs/")
documents = loader.load()

print(f"加载了 {len(documents)} 个文档")
print(f"标题: {documents[0].metadata.get('title', 'N/A')}")
print(f"URL: {documents[0].metadata['source']}")
print(f"内容长度: {len(documents[0].page_content)} 字符")

from langchain_community.document_loaders.csv_loader import CSVLoader

# 加载CSV文件
loader = CSVLoader(
    file_path="data/users.csv",
    csv_args={
        'delimiter': ',',
        'quotechar': '"',
    }
)
documents = loader.load()

print(f"加载了 {len(documents)} 行数据")
for i, doc in enumerate(documents[:3]):  # 只看前3行
    print(f"\n行{i+1}: {doc.page_content}")
    print(f"元数据: {doc.metadata}")

from langchain_community.document_loaders import DirectoryLoader, TextLoader

# 加载目录下所有txt文件
loader = DirectoryLoader(
    "data/documents/",
    glob="**/*.txt",  # 匹配所有txt文件
    loader_cls=TextLoader,  # 使用TextLoader加载
    show_progress=True  # 显示进度条
)
documents = loader.load()

print(f"从目录加载了 {len(documents)} 个文档")
for doc in documents[:3]:
    print(f"文件: {doc.metadata['source']}")
    print(f"内容: {doc.page_content[:50]}...\n")

from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader

# 加载文档（示例：data/long_article.txt）
loader = TextLoader("data/long_article.txt")
documents = loader.load()

# 创建分割器
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,      # 每块最大500字符
    chunk_overlap=50,    # 块之间重叠50字符
    length_function=len,  # 使用字符长度计算
    separators=["\n\n", "\n", " ", ""]  # 分割优先级
)

# 分割文档
chunks = text_splitter.split_documents(documents)

print(f"原文档: {len(documents)} 个")
print(f"分割后: {len(chunks)} 个块")
print(f"\n第1块内容:")
print(chunks[0].page_content)
print(f"\n第1块元数据: {chunks[0].metadata}")

from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader

# 加载文档
loader = TextLoader("data/long_article.txt")
documents = loader.load()

# 严格滑窗切分器
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=200,           # 每块最大200字符（固定窗口）
    chunk_overlap=50,         # 块之间重叠50字符（绝对生效）
    length_function=len,     # 使用字符长度计算
    separators=[""],         # 不使用任何分隔符，纯字符滑窗
    add_start_index=True,     # 在元数据中添加起始位置
    strip_whitespace=True,    # 去除每块首尾空白字符
)

# 分割文档
chunks = text_splitter.split_documents(documents)

print(f"原文档: {len(documents)} 个")
print(f"分割后: {len(chunks)} 个块")

# 验证重叠是否生效
def verify_overlap(chunks, overlap=50):
    for i in range(min(3, len(chunks) - 1)):
        tail = chunks[i].page_content[-overlap:]
        head = chunks[i + 1].page_content[:overlap]
        print(f"块{i+1}尾部: {repr(tail)}")
        print(f"块{i+2}头部: {repr(head)}")
        print(f"重叠匹配: {tail == head}")
        print("---")

verify_overlap(chunks, overlap=50)

from langchain_text_splitters import CharacterTextSplitter

# 按段落分割
text_splitter = CharacterTextSplitter(
    separator="\n\n",  # 按双换行符分割
    chunk_size=1000,
    chunk_overlap=100
)

chunks = text_splitter.split_documents(documents)
print(f"分割成 {len(chunks)} 个段落")

from langchain_text_splitters import TokenTextSplitter

# 按Token分割
text_splitter = TokenTextSplitter(
    chunk_size=100,  # 每块100个Token
    chunk_overlap=10
)

chunks = text_splitter.split_documents(documents)
print(f"分割成 {len(chunks)} 个Token块")

from langchain_experimental.text_splitter import SemanticChunker
from langchain_community.embeddings import DashScopeEmbeddings
import os

# 设置API密钥
os.environ["DASHSCOPE_API_KEY"] = "your-api-key"

# 初始化Embedding模型
embeddings = DashScopeEmbeddings(model="text-embedding-v1")

# 尝试使用 SemanticChunker（可能只返回1个块）
semantic_splitter = SemanticChunker(
    embeddings=embeddings,
    breakpoint_threshold_type="standard_deviation",
    breakpoint_threshold_amount=1.0,
)

# 示例文本
sample_text = """
人工智能的发展历程

人工智能（Artificial Intelligence，简称AI）是计算机科学的一个分支，
它企图了解智能的实质，并生产出一种新的能以人类智能相似的方式做出反应的智能机器。

机器学习是AI的核心技术之一。通过算法让机器从数据中学习规律，
无需显式编程即可完成特定任务。

自然语言处理（NLP）是AI的重要应用领域。
它让计算机能够理解、解释和生成人类语言。

计算机视觉让机器能够"看懂"图像和视频。
"""

# 语义分割
chunks = semantic_splitter.create_documents([sample_text])

print(f"语义分割后: {len(chunks)} 个块")
# 注意：在中文文本上，很可能只返回 1 个块

from langchain_text_splitters import MarkdownHeaderTextSplitter

# 示例Markdown文档
markdown_text = """
# 人工智能概述

人工智能（AI）是计算机科学的重要分支。

## 机器学习

机器学习是AI的核心技术。

### 监督学习
监督学习使用标注数据训练模型。

### 无监督学习
无监督学习发现数据中的隐藏模式。

## 深度学习

深度学习使用神经网络。

### 卷积神经网络
CNN主要用于图像处理。

### 循环神经网络
RNN适合处理序列数据。

# 应用领域

AI在各个领域都有广泛应用。
"""

# 创建Markdown分割器
markdown_splitter = MarkdownHeaderTextSplitter(
    headers_to_split_on=[
        ("#", "Header 1"),
        ("##", "Header 2"),
        ("###", "Header 3"),
    ]
)

# 分割Markdown文档
chunks = markdown_splitter.split_text(markdown_text)

print(f"Markdown分割后: {len(chunks)} 个块")
for i, chunk in enumerate(chunks, 1):
    print(f"\n--- 第{i}块 ---")
    print(f"元数据: {chunk.metadata}")
    print(f"内容: {chunk.page_content[:100]}...")

from langchain_community.embeddings import DashScopeEmbeddings
import os

os.environ["DASHSCOPE_API_KEY"] = "your-api-key"

# 初始化Embedding模型
embeddings = DashScopeEmbeddings(
    model="text-embedding-v1"  # 通义千问的Embedding模型
)

# 将文本转换为向量
text = "人工智能正在改变世界"
vector = embeddings.embed_query(text)

print(f"文本: {text}")
print(f"向量维度: {len(vector)}")
print(f"向量前5个值: {vector[:5]}")

from langchain_community.embeddings import DashScopeEmbeddings
import os

os.environ["DASHSCOPE_API_KEY"] = "your-api-key"

# 初始化Embedding模型
embeddings = DashScopeEmbeddings(
    model="text-embedding-v1"  # 通义千问的Embedding模型
)

# 批量将多个文本转换为向量
texts = [
    "人工智能的发展历程",
    "机器学习算法介绍",
    "深度学习神经网络"
]

vectors = embeddings.embed_documents(texts)

print(f"转换了 {len(vectors)} 个文本")
for i, text in enumerate(texts):
    print(f"{i+1}. {text} → 向量维度: {len(vectors[i])}")

import os

from langchain_community.document_loaders import PyMuPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.embeddings import DashScopeEmbeddings
from langchain_community.vectorstores import Chroma
from langchain_community.chat_models import ChatTongyi
from langchain_core.messages import AIMessage, HumanMessage
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser


# 方式1：直接在这里填写 key（仅 demo）
# os.environ["DASHSCOPE_API_KEY"] = "your-api-key"

# 方式2：推荐从环境变量读取
os.environ["DASHSCOPE_API_KEY"] = os.environ.get("DASHSCOPE_API_KEY", "your-api-key")


def build_vectorstore():
    """加载 PDF，构建向量库，返回 vectorstore 对象。"""
    print("步骤1：加载 PDF 文档...")
    loader = PyMuPDFLoader("data/sample_document.pdf")
    documents = loader.load()
    print(f"加载了 {len(documents)} 页文档")

    print("\n步骤2：分割文档...")
    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=500,
        chunk_overlap=50,
    )
    chunks = text_splitter.split_documents(documents)
    print(f"分割成 {len(chunks)} 个文本块")

    print("\n步骤3：创建向量数据库...")
    embeddings = DashScopeEmbeddings(model="text-embedding-v1")
    vectorstore = Chroma.from_documents(chunks, embeddings)
    print("向量数据库创建完成！")

    return vectorstore


def rewrite_query(llm, history_msgs, question):
    """把用户问题改写成可独立检索的查询（减少指代、补全关键实体）。"""
    history_text = "\n".join([f"{m.type}: {m.content}" for m in history_msgs])
    prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                "你是一个严谨的检索查询改写助手。"
                "请把用户当前问题改写为可独立检索的中文查询，输出一行即可。",
            ),
            (
                "human",
                "对话历史：\n{history}\n\n当前问题：{question}\n\n改写后的查询：",
            ),
        ]
    )
    chain = prompt | llm | StrOutputParser()
    return chain.invoke({"history": history_text, "question": question}).strip()


def rerank_with_llm(llm, query, docs, top_n=4):
    """对候选片段做精排（演示版：用 LLM 给候选打分）。"""
    scored = []
    score_prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                "你是一个文档重排序器。给定查询和候选片段，请输出一个 0-10 的相关性分数（只输出数字）。",
            ),
            (
                "human",
                "查询：{query}\n\n候选片段：\n{chunk}\n\n分数：",
            ),
        ]
    )
    score_chain = score_prompt | llm | StrOutputParser()

    for d in docs:
        raw = score_chain.invoke({"query": query, "chunk": d.page_content})
        try:
            score = float("".join([c for c in raw if (c.isdigit() or c == ".")]))
        except Exception:
            score = 0.0
        scored.append((score, d))

    scored.sort(key=lambda x: x[0], reverse=True)
    return [d for _, d in scored[:top_n]]


# 模拟"论文学习助手"的对话历史
history = [
    HumanMessage(content="我在学习一份大语言模型必读论文合集。"),
    AIMessage(content="好的，我会基于论文内容回答，并在结尾标注引用来源。"),
]

questions = [
    "请用通俗语言解释 Transformer 的核心思想，并指出相关段落。",
    "Self-Attention 相比 RNN 的优势是什么？给出依据。",
    "训练 Transformer 时常见的优化技巧有哪些？请给引用。",
]

if __name__ == "__main__":
    # 步骤1-3：构建向量库
    vectorstore = build_vectorstore()

    # 步骤4：创建问答链
    print("\n步骤4：创建问答链...")
    llm = ChatTongyi(model="qwen-turbo", temperature=0.1)

    prompt = ChatPromptTemplate.from_template(
        """你是一个严谨的论文学习知识库问答助手。请只根据给定的上下文回答问题。
如果上下文不足以支撑结论，请明确回答"不知道"。
请在回答末尾用【引用】列出使用到的 source。

上下文：
{context}

问题：{input}
"""
    )

    def format_docs(docs):
        return "\n\n".join(
            [
                f"[source={d.metadata.get('source', 'unknown')}]\n{d.page_content}"
                for d in docs
            ]
        )

    qa_chain = prompt | llm | StrOutputParser()

    # 步骤5：提问
    print("\n步骤5：开始提问（含 Rewrite + Rerank）...")

    # 模拟"论文学习助手"的对话历史
    history = [
        HumanMessage(content="我在学习一份大语言模型必读论文合集。"),
        AIMessage(content="好的，我会基于论文内容回答，并在结尾标注引用来源。"),
    ]

    for q in questions:
        print(f"\n用户问题: {q}")

        rewritten = rewrite_query(llm, history, q)
        print(f"改写后查询: {rewritten}")

        # Retrieve：先拿候选
        candidates = vectorstore.as_retriever(search_kwargs={"k": 8}).invoke(rewritten)
        # Rerank：精排出最相关的证据
        top_docs = rerank_with_llm(llm, rewritten, candidates, top_n=4)

        # 打印命中文档片段预览，便于验收
        print("命中文档片段（Top4）:")
        for i, d in enumerate(top_docs, 1):
            src = d.metadata.get("source", "unknown")
            preview = d.page_content.replace("\n", " ")[:120]
            print(f"- #{i} source={src} preview={preview}...")

        # 用精排后的 docs 组装上下文，再交给 LLM 生成
        ctx = format_docs(top_docs)
        answer = qa_chain.invoke({"context": ctx, "input": q})
        print(f"回答: {answer}")

from langchain_community.document_loaders import PyMuPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.embeddings import DashScopeEmbeddings
from langchain_community.vectorstores import Chroma
import os

# 请先在环境变量中配置 DASHSCOPE_API_KEY，或在这里直接赋值
os.environ["DASHSCOPE_API_KEY"] = os.environ.get("DASHSCOPE_API_KEY", "your-api-key")


def build_vectorstore():
    """加载 PDF，构建向量库，返回 vectorstore 对象。"""
    print("步骤1：加载 PDF 文档...")
    loader = PyMuPDFLoader("data/sample_document.pdf")
    documents = loader.load()
    print(f"加载了 {len(documents)} 页文档")

    print("\n步骤2：分割文档...")
    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=500,
        chunk_overlap=50,
    )
    chunks = text_splitter.split_documents(documents)
    print(f"分割成 {len(chunks)} 个文本块")

    print("\n步骤3：创建向量数据库...")
    embeddings = DashScopeEmbeddings(model="text-embedding-v1")
    vectorstore = Chroma.from_documents(chunks, embeddings)
    print("向量数据库创建完成！")

    return vectorstore


def advanced_search(vectorstore):
    """演示带分数检索和 MMR 检索。"""
    query = "公司的加班和调休政策是什么？"
    print(f"\n查询：{query}")

    # 1. 带分数的相似度搜索
    print("\n=== 带分数的相似度搜索 ===")
    results_with_scores = vectorstore.similarity_search_with_score(query, k=3)

    for doc, score in results_with_scores:
        print(f"相似度分数: {score:.4f}")
        print(f"内容: {doc.page_content[:80]}...\n")

    # 2. MMR 检索（最大边际相关性）
    print("\n=== MMR 检索（既相关又多样） ===")
    results = vectorstore.max_marginal_relevance_search(
        query,
        k=5,            # 最终返回5个结果
        fetch_k=20,     # 先取20个候选
        lambda_mult=0.5 # 0=更看重多样性，1=更看重相关性
    )

    for i, doc in enumerate(results, 1):
        print(f"{i}. {doc.page_content[:60]}...")
    
    # 注意：Chroma 不支持 max_marginal_relevance_search_with_score
    # 如果需要获取 MMR 结果的相似度分数，可以用原始查询计算每个结果的相似度
    print("\n=== MMR 结果的相似度分数（与原始查询的相似度） ===")
    # 先获取所有候选文档的分数
    all_results_with_scores = vectorstore.similarity_search_with_score(query, k=20)
    
    # 创建文档内容到分数的映射
    content_to_score = {doc.page_content: score for doc, score in all_results_with_scores}
    
    # 为 MMR 结果匹配分数
    for i, doc in enumerate(results, 1):
        score = content_to_score.get(doc.page_content, None)
        if score is not None:
            print(f"{i}. 相似度分数: {score:.4f}")
            print(f"   内容: {doc.page_content[:60]}...\n")
        else:
            print(f"{i}. 相似度分数: N/A")
            print(f"   内容: {doc.page_content[:60]}...\n")


if __name__ == "__main__":
    vectorstore = build_vectorstore()
    advanced_search(vectorstore)

# 先安装依赖（如果还没有安装）
# pip install rank_bm25

from langchain_community.document_loaders import PyMuPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import DashScopeEmbeddings
from langchain_community.retrievers import BM25Retriever


def load_sample_documents():
    """加载示例PDF文档，包含LangChain相关内容"""
    # 加载实际PDF文件
    loader = PyMuPDFLoader("../data/sample_document.pdf")
    documents = loader.load()
    print(f"✅ 成功加载PDF文件，共 {len(documents)} 页")
    return documents


def build_hybrid_retriever(documents):
    """构建混合检索器：BM25 + 向量检索"""
    
    # 1) 文本分割
    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=200,
        chunk_overlap=20,
    )
    chunks = text_splitter.split_documents(documents)
    
    # 2) 构建向量库
    embeddings = DashScopeEmbeddings(model="text-embedding-v1")
    vectorstore = Chroma.from_documents(chunks, embeddings)
    
    # 3) 稀疏检索：BM25（强关键词兜底）
    bm25_retriever = BM25Retriever.from_documents(chunks)
    bm25_retriever.k = 5
    
    # 4) 稠密检索：向量检索（语义召回）
    dense_retriever = vectorstore.as_retriever(search_kwargs={"k": 5})
    
    return bm25_retriever, dense_retriever


def hybrid_search(query, bm25_retriever, dense_retriever, bm25_weight=0.6, dense_weight=0.4):
    """手动实现Hybrid Search：BM25 + 向量检索融合"""
    
    # 1) 获取BM25检索结果
    bm25_docs = bm25_retriever.invoke(query)
    
    # 2) 获取向量检索结果
    dense_docs = dense_retriever.invoke(query)
    
    # 3) 手动融合结果
    # 创建文档到分数的映射
    doc_scores = {}
    
    # BM25结果：根据排名给分（排名越前分数越高）
    for rank, doc in enumerate(bm25_docs):
        doc_content = doc.page_content
        if doc_content not in doc_scores:
            doc_scores[doc_content] = {"doc": doc, "bm25_score": 0, "dense_score": 0}
        # BM25分数：排名越前分数越高
        doc_scores[doc_content]["bm25_score"] = 1.0 / (rank + 1)
    
    # 向量检索结果：根据排名给分
    for rank, doc in enumerate(dense_docs):
        doc_content = doc.page_content
        if doc_content not in doc_scores:
            doc_scores[doc_content] = {"doc": doc, "bm25_score": 0, "dense_score": 0}
        # 向量检索分数：排名越前分数越高
        doc_scores[doc_content]["dense_score"] = 1.0 / (rank + 1)
    
    # 4) 计算融合分数
    hybrid_docs = []
    for content, scores in doc_scores.items():
        # 加权融合分数
        hybrid_score = (scores["bm25_score"] * bm25_weight + 
                       scores["dense_score"] * dense_weight)
        hybrid_docs.append((scores["doc"], hybrid_score))
    
    # 5) 按融合分数排序
    hybrid_docs.sort(key=lambda x: x[1], reverse=True)
    
    # 返回排序后的文档
    return [doc for doc, score in hybrid_docs]


def rrf_fusion(bm25_docs, dense_docs, k=60):
    """
    真正的 RRF (Reciprocal Rank Fusion) 融合实现
    这是业界标准做法，比简单加权更科学
    """
    doc_rrf_scores = {}
    
    # BM25 排名贡献：k / (rank + k)
    for rank, doc in enumerate(bm25_docs):
        doc_content = doc.page_content
        if doc_content not in doc_rrf_scores:
            doc_rrf_scores[doc_content] = {"doc": doc, "rrf_score": 0}
        doc_rrf_scores[doc_content]["rrf_score"] += k / (rank + k)
    
    # 向量检索排名贡献：k / (rank + k)
    for rank, doc in enumerate(dense_docs):
        doc_content = doc.page_content
        if doc_content not in doc_rrf_scores:
            doc_rrf_scores[doc_content] = {"doc": doc, "rrf_score": 0}
        doc_rrf_scores[doc_content]["rrf_score"] += k / (rank + k)
    
    # 按 RRF 分数排序
    rrf_results = sorted(
        doc_rrf_scores.values(), 
        key=lambda x: x["rrf_score"], 
        reverse=True
    )
    
    return [item["doc"] for item in rrf_results]


def explain_rrf_with_example():
    """
    详细解释 RRF 融合原理（面试必备）
    """
    print("🔄 RRF (Reciprocal Rank Fusion) 融合原理详解")
    print("=" * 60)
    
    # 完整示例：多个文档的 RRF 计算
    print("\n📊 完整示例：用户查询 'Spring Boot 配置文件加载顺序'")
    print("=" * 60)
    
    # 模拟检索结果
    bm25_results = [
        "Spring Boot 配置文件加载机制",      # 第1名
        "Spring Boot 配置文件优先级详解",      # 第2名  
        "Spring Boot 多环境配置切换",         # 第3名
        "Spring Boot 启动流程分析",           # 第4名
        "Spring Boot 自动配置原理",           # 第5名
    ]
    
    vector_results = [
        "Spring Boot 配置文件加载机制",      # 第1名
        "Spring Boot 自动配置原理",           # 第2名
        "Spring Boot 配置文件优先级详解",      # 第3名
        "Spring Boot 启动流程分析",           # 第4名
        "Spring Boot 多环境配置切换",         # 第5名
    ]
    
    k = 60
    print(f"平滑参数 k = {k}")
    print("\n🔍 BM25 检索结果（关键词匹配）:")
    for i, doc in enumerate(bm25_results, 1):
        print(f"  第{i}名: {doc}")
    
    print("\n🧠 向量检索结果（语义相似）:")
    for i, doc in enumerate(vector_results, 1):
        print(f"  第{i}名: {doc}")
    
    # RRF 计算
    print(f"\n🧮 RRF 融合计算过程:")
    print("-" * 60)
    
    # 计算所有文档的 RRF 分数
    all_docs = set(bm25_results + vector_results)
    rrf_scores = {}
    
    for doc in all_docs:
        # BM25 排名
        bm25_rank = bm25_results.index(doc) + 1 if doc in bm25_results else None
        # 向量排名  
        vector_rank = vector_results.index(doc) + 1 if doc in vector_results else None
        
        # 计算贡献
        bm25_score = k / (bm25_rank + k) if bm25_rank else 0
        vector_score = k / (vector_rank + k) if vector_rank else 0
        rrf_score = bm25_score + vector_score
        
        rrf_scores[doc] = {
            'bm25_rank': bm25_rank,
            'vector_rank': vector_rank, 
            'bm25_score': bm25_score,
            'vector_score': vector_score,
            'rrf_score': rrf_score
        }
        
        # 打印计算过程
        print(f"\n📄 {doc}")
        if bm25_rank:
            print(f"  BM25第{bm25_rank}名: {k}/({bm25_rank}+{k}) = {bm25_score:.4f}")
        else:
            print(f"  BM25未召回: 0")
        if vector_rank:
            print(f"  向量第{vector_rank}名: {k}/({vector_rank}+{k}) = {vector_score:.4f}")
        else:
            print(f"  向量未召回: 0")
        print(f"  🎯 RRF总分: {rrf_score:.4f}")
    
    # 排序并显示结果
    print(f"\n🏆 RRF 融合最终排序:")
    print("-" * 60)
    
    sorted_docs = sorted(rrf_scores.items(), key=lambda x: x[1]['rrf_score'], reverse=True)
    
    for i, (doc, scores) in enumerate(sorted_docs, 1):
        bm25_rank = scores['bm25_rank'] or '-'
        vector_rank = scores['vector_rank'] or '-'
        rrf_score = scores['rrf_score']
        
        rank_diff = ""
        if bm25_rank != '-' and vector_rank != '-':
            if abs(bm25_rank - vector_rank) <= 1:
                rank_diff = "🎯 (共识强)"
            elif abs(bm25_rank - vector_rank) <= 3:
                rank_diff = "✅ (互补)"
            else:
                rank_diff = "⚠️ (差异大)"
        
        print(f"第{i}名: {doc} (RRF:{rrf_score:.4f}) BM25:{bm25_rank} 向量:{vector_rank} {rank_diff}")
    
    print(f"\n💡 关键洞察:")
    print("• 🎯 共识效应: 在两个系统都排名靠前的文档，RRF分数最高")
    print("• ✅ 互补效应: 在一个系统表现好、另一个表现差的文档，仍能获得较高分数") 
    print("• ⚠️ 不丢失: 只在某个系统出现的文档，仍有贡献，不会完全丢失")
    print("• 🔄 公式优势: 不需要分数归一化，直接用排名即可，工程简单稳定")


def compare_retrieval_methods(query, bm25_retriever, dense_retriever):
    """对比不同检索方法的效果"""
    print(f"查询：{query}")
    print("=" * 60)
    
    # 1) 纯 BM25 检索
    print("\n🔹 BM25 检索结果（关键词匹配）：")
    bm25_docs = bm25_retriever.invoke(query)
    for i, doc in enumerate(bm25_docs[:3], 1):
        print(f"{i}. {doc.page_content}")
    
    # 2) 纯向量检索
    print("\n🔹 向量检索结果（语义相似）：")
    dense_docs = dense_retriever.invoke(query)
    for i, doc in enumerate(dense_docs[:3], 1):
        print(f"{i}. {doc.page_content}")
    
    # 3) Hybrid 检索（手动融合）
    print("\n🔹 Hybrid 检索结果（BM25 + 向量融合）：")
    hybrid_docs = hybrid_search(query, bm25_retriever, dense_retriever)
    for i, doc in enumerate(hybrid_docs[:3], 1):
        print(f"{i}. {doc.page_content}")
    
    # 4) 分析结果差异
    print("\n📊 结果分析：")
    bm25_content = set(doc.page_content for doc in bm25_docs[:3])
    dense_content = set(doc.page_content for doc in dense_docs[:3])
    hybrid_content = set(doc.page_content for doc in hybrid_docs[:3])
    
    print(f"• BM25 独有结果：{len(bm25_content - dense_content)} 条")
    print(f"• 向量检索独有结果：{len(dense_content - bm25_content)} 条")
    print(f"• Hybrid 融合后结果：{len(hybrid_content)} 条")
    print(f"• Hybrid 覆盖了 BM25 的 {len(hybrid_content & bm25_content)}/{len(bm25_content)} 条")
    print(f"• Hybrid 覆盖了向量检索的 {len(hybrid_content & dense_content)}/{len(dense_content)} 条")


if __name__ == "__main__":
    # 加载示例PDF文档
    documents = load_sample_documents()
    
    # 构建混合检索器
    bm25_retriever, dense_retriever = build_hybrid_retriever(documents)
    
    # 测试查询（包含强关键词）
    query = "LCEL 的 | 管道语法怎么用？"
    
    # 对比不同检索方法
    compare_retrieval_methods(query, bm25_retriever, dense_retriever)
    
    print("\n✅ 运行完成！可以看到 Hybrid Search 如何结合 BM25 的关键词匹配能力和向量检索的语义理解能力。")

            
                ⚖️ RRF vs 简单加权融合：为什么业界更推荐 RRF？
                
                    简单加权融合（代码中的 hybrid_search）：
                    • 公式：score = bm25_weight × (1/rank) + dense_weight × (1/rank)
                    • 问题：权重需要人工调参，不同数据集需要不同权重
                    • 局限：假设 BM25 和向量分数分布相同，实际往往不成立
                    
                    RRF 融合（业界标准）：
                    • 公式：score = Σ(k / (rank_i + k))，k=60
                    • 优势：无需调参，k=60 在各种场景下表现稳定
                    • 理论：基于排名融合，避免分数归一化问题
                    • 效果：天然偏向在多个检索系统中都排名靠前的文档
                    
                    面试金句："RRF 的核心思想是'信任共识'——如果一个文档在多个检索系统中都排前面，那它很可能真的相关。而且 RRF 不需要调权重参数，工程上更稳定。"
                
            

            
                一句工程建议：Hybrid 的输出最好再接一步"去重/精排"（MMR 或 Rerank），典型链路是：Dense Top-20 + BM25 Top-20 → RRF 融合取 Top-12 → MMR 去重取 Top-8 → Rerank 精排取 Top-4。
            

            
                📌 小结
                
                    similarity_search：只要简单、快速检索时使用。
                    similarity_search_with_score：需要可解释的分数时使用。
                    max_marginal_relevance_search：追求既相关又多样的结果时使用。
                    Hybrid Search（BM25 + Dense）：专有名词/强关键词密集场景下，用来兜底召回，减少漏召回。
                
                
                    掌握这些检索方式后，你就可以根据业务需求，灵活地为 RAG 系统选择"最聪明"的检索策略。