一、两个代码共同实现的核心流程

无论是 LangChain 还是 LlamaIndex，本质上实现的都是标准 RAG（Retrieval-Augmented Generation，检索增强生成）流程。核心思想不是让大模型直接凭记忆回答，而是先从知识库中检索相关资料，再把检索结果作为上下文交给大模型生成答案。

文档读取 → 文档切分 → Embedding 向量化 → 向量数据库/向量索引 → 问题检索 Top-K 文档块 → 拼接 context → 大模型生成答案

步骤	作用	关键对象
文档读取	把 txt、PDF、网页等资料读入程序	TextLoader / SimpleDirectoryReader
文档切分	把长文档切成可检索的小块	RecursiveCharacterTextSplitter / SentenceSplitter
向量化	把文本转换为语义向量	HuggingFaceEmbeddings / OpenAIEmbedding
向量存储	保存文本块向量并支持相似度检索	Chroma / FAISS / VectorStoreIndex
检索增强	根据问题召回相关片段作为 context	similarity_search / Retriever
答案生成	让 LLM 基于 context 生成答案	ChatOpenAI / QueryEngine

二、LangChain 代码知识点

1. 文档读取：TextLoader

loader = TextLoader("./藜麦.txt", encoding="utf-8")
documents = loader.load()

TextLoader 用于读取本地 txt 文件。Windows 中文系统默认编码可能是 GBK，而很多文本文件实际是 UTF-8，因此必须显式设置 encoding="utf-8"，否则容易出现 UnicodeDecodeError。

对象/参数	含义
loader	文档加载器，负责读取本地文本文件
documents	Document 对象列表，虽然只有一个文件，也会返回列表
page_content	Document 中的正文内容
metadata	Document 中的元数据，例如 source 文件路径
encoding="utf-8"	指定文本编码，避免 Windows 默认 GBK 解码失败

2. 文档切分：RecursiveCharacterTextSplitter

text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=256,
    chunk_overlap=50,
    separators=["\n\n", "\n", "。", "！", "？", "；", "，", " "]
)

RAG 不能简单地把整篇文档作为一个整体检索。切分的目的是把长文档变成多个语义较完整的小块，使检索更精准。

参数	作用
chunk_size=256	每个文本块大约 256 个字符，适合短中文文档
chunk_overlap=50	相邻文本块保留 50 个字符重叠，避免重要句子被截断
separators	指定中文分隔符，优先按段落、句号、问号、分号、逗号等切分

3. 生成切分后的文本块

texts = text_splitter.create_documents(
    [documents[0].page_content],
    metadatas=[documents[0].metadata]
)

texts 是切分后的 Document 块列表。后续构建向量库时应使用 texts，而不是原始 documents。因为 RAG 检索的基本单位是 chunk，而不是整篇文章。

4. Embedding 模型：HuggingFaceEmbeddings

embedding = HuggingFaceEmbeddings(
    model_name="moka-ai/m3e-small",
    model_kwargs={"device": "cpu"},
    encode_kwargs={"normalize_embeddings": True}
)

Embedding 的作用是把文本转成高维向量，使计算机能够基于语义相似度进行检索。例如“藜一般几月播种”和“藜麦什么时候种植”文字不同，但语义相近，向量距离也应较近。

参数	含义
model_name="moka-ai/m3e-small"	中文语义向量模型，适合中文检索
device="cpu"	使用 CPU 推理，小模型可以正常运行
normalize_embeddings=True	对向量归一化，便于相似度检索

5. 向量数据库：Chroma

db = Chroma.from_documents(
    documents=texts,
    embedding=embedding
)

Chroma 用于保存“文本块 + 向量 + 元数据”。当用户输入问题时，系统会先把问题转为向量，再在 Chroma 中寻找语义最相似的文本块。

注意：这里 documents=texts 是正确写法。如果用 documents=documents，则相当于把整篇文章作为一个大块存入向量库，检索粒度会变粗。

6. 相似度检索：similarity_search

search_result = db.similarity_search(question, k=4)

参数	作用
question	用户输入的问题
k=4	返回最相似的 4 个文本块

RAG 答错时，首先应检查 similarity_search 返回的片段是否相关。如果检索结果不相关，大模型后续再强也难以给出正确答案。

7. 大模型配置：ChatOpenAI

llm = ChatOpenAI(
    model="deepseek-v3",
    temperature=0,
    max_retries=2,
    api_key="...",
    base_url="https://api.apiyi.com/v1"
)

ChatOpenAI 可以调用 OpenAI 兼容接口，不一定只调用 OpenAI 官方模型。这里通过 APIyi 的 base_url 调用 deepseek-v3。RAG 场景中 temperature 通常设为 0，使回答更稳定、更少发散。

安全建议：不要把真实 API Key 写死在代码中，更推荐使用环境变量，例如 api_key=os.getenv("APIYI_API_KEY")。

8. RAG Prompt 模板

prompt = PromptTemplate.from_template("""
你是一个严谨的知识库问答助手。
请只根据给定资料回答问题。
如果资料中没有相关信息，请回答“根据现有资料无法确定”。

资料：
{context}

问题：
{question}

答案：
""")

Prompt 的作用是约束大模型：只能根据检索到的 context 回答，如果资料中没有答案，就明确回答无法确定。这是减少幻觉的关键。

9. LCEL 链式调用

chain = prompt | llm | StrOutputParser()

这是 LangChain 新版 LCEL 写法，表示 PromptTemplate → LLM → 字符串输出解析器。相比旧版 LLMChain，这种写法更推荐，也更符合新版 LangChain 的设计。

10. RAG 问答函数

def rag_answer(question: str, top_k: int = 4):
    docs = db.similarity_search(question, k=top_k)
    context = "\n\n".join([f"资料{i + 1}：{doc.page_content}" for i, doc in enumerate(docs)])
    answer = chain.invoke({"context": context, "question": question})
    return answer, docs

该函数完成完整 RAG：输入问题 → 检索相关文本块 → 拼接 context → 调用大模型 → 返回答案和参考片段。返回 source_docs 可以帮助检查答案依据。

三、LlamaIndex 代码知识点

1. LlamaIndex 的定位

LlamaIndex 更偏向“数据接入 + 索引构建 + 查询引擎”的 RAG 框架。相比 LangChain 手写流程，LlamaIndex 封装程度更高，尤其适合文档问答、PDF 解析、索引管理、查询引擎和 Agent 工具调用。

模块	作用
Data Connectors	读取本地文件、PDF、网页、数据库等数据源
Data Indexes	对文档进行切分、向量化和索引构建
Query Engines	基于索引回答用户问题
Chat Engines	支持带上下文和记忆的聊天
Data Agents	让大模型根据任务选择工具并调用

2. Settings 全局配置

Settings.llm = OpenAI(...)
Settings.embed_model = OpenAIEmbedding(...)

Settings 是 LlamaIndex 的全局配置，用来指定默认 LLM 和 Embedding 模型。后续创建索引和查询时，如果没有单独指定，就会默认使用 Settings 中的模型配置。

3. 文档读取：SimpleDirectoryReader / PyMuPDFReader / LlamaParse

LlamaIndex 支持多种数据读取方式。SimpleDirectoryReader 适合读取目录下的 txt、pdf 等文件；PyMuPDFReader 适合读取普通 PDF；LlamaParse 适合复杂 PDF、表格、论文和版式复杂文档。

Reader	适用场景
SimpleDirectoryReader	读取本地目录中的多种文件
PyMuPDFReader	读取普通 PDF 文本
BeautifulSoupWebReader	读取网页内容
LlamaParse	解析复杂 PDF、表格、论文、报告，输出 Markdown

4. 文档切分：SentenceSplitter

splitter = SentenceSplitter(
    chunk_size=1024,
    chunk_overlap=100,
    paragraph_separator="\n\n"
)
nodes = splitter.get_nodes_from_documents(documents)

LlamaIndex 中切分后的文本块叫 nodes，对应 LangChain 中的 texts。nodes 是后续构建 VectorStoreIndex、SummaryIndex 和 QueryEngine 的基础。

5. 向量索引：VectorStoreIndex

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("问题")

VectorStoreIndex 会自动完成文档切分、向量化、索引构建等流程。相比 LangChain 中手动构建 Chroma，LlamaIndex 的写法更简洁。

6. FAISS 与 StorageContext

faiss_index = faiss.IndexFlatL2(embed_dim)
vector_store = FaissVectorStore(faiss_index=faiss_index)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

FAISS 是高性能向量检索库，适合大规模向量检索。StorageContext 是 LlamaIndex 中统一管理存储后端的对象，用于指定向量存储、文档存储、索引存储等。

7. Retriever 与 QueryEngine

vector_retriever = VectorIndexRetriever(index=vector_index, similarity_top_k=5)
query_engine = RetrieverQueryEngine.from_args(retriever=vector_retriever)

Retriever 负责检索相关 nodes，QueryEngine 负责把检索结果组织成上下文并调用 LLM 生成答案。这相当于 LangChain 中自己写的 rag_answer 函数。

8. SummaryIndex 与全文总结

summary_index = SummaryIndex(nodes)
summary_query_engine = summary_index.as_query_engine(
    response_mode="tree_summarize",
    use_async=True
)

SummaryIndex 用于全文总结。tree_summarize 会先对多个文本块分别总结，再递归合并成最终总结，适合长文档概括。use_async=True 可以提高长文档总结效率。

9. Agent 工具调用：vector_tool 与 summary_tool

LlamaIndex 可以把查询函数或查询引擎包装成工具。例如 vector_tool 负责具体问题检索，summary_tool 负责全文总结。Agent 可以根据用户问题自动判断调用哪个工具。

工具	适合问题
vector_tool	查询具体事实，例如“第几页讲了什么”“某个指标是多少”
summary_tool	总结全文，例如“概括这篇文章”“总结主要内容”

四、LangChain 与 LlamaIndex 对比

对比项	LangChain	LlamaIndex
文档读取	TextLoader 等 Loader	SimpleDirectoryReader、PyMuPDFReader、LlamaParse
切分对象	texts	nodes
切分器	RecursiveCharacterTextSplitter	SentenceSplitter
Embedding	HuggingFaceEmbeddings	OpenAIEmbedding / 自定义 Embedding
向量库	Chroma	FAISS / VectorStoreIndex / 其他 VectorStore
检索方式	db.similarity_search()	VectorIndexRetriever.retrieve()
问答方式	手写 rag_answer + chain.invoke	query_engine.query()
Prompt 控制	PromptTemplate	system_prompt / query engine 参数
工具调用	可用 Tool/Runnable 自定义	FunctionTool / QueryEngineTool 更方便
特点	灵活、流程清楚、适合学习底层	封装高、适合复杂文档问答系统

五、学习 RAG 时必须掌握的关键点

1. RAG 的关键不是“让模型更聪明”，而是“让模型基于外部知识回答”。

私有文档、课程资料、企业知识库、论文报告等通常不在大模型训练数据中，因此需要通过检索把相关资料喂给模型。

2. Chunk 质量直接影响检索质量

chunk 太小会导致语义不完整，chunk 太大会导致检索不精准。中文短文档可以使用 256-500 字符，长 PDF 或报告可以使用 800-1200 字符，并配合适当 overlap。

3. Embedding 决定语义匹配能力

如果中文资料使用不适合中文的 Embedding，检索结果可能偏差较大。常见中文模型包括 m3e-small、bge-small-zh、bge-base-zh 等。

4. 检索结果要可检查

调试 RAG 时应打印检索到的参考片段。只有确认检索片段相关，才能继续判断模型回答是否正确。

5. Prompt 必须限制模型不要胡编

例如“请只根据给定资料回答；如果资料中没有相关信息，请回答无法确定”。这是知识库问答中非常重要的安全约束。

6. API Key 不应写死在代码里

真实项目中应使用环境变量或配置文件管理 API Key，避免泄露。

六、推荐排错顺序

顺序	检查内容	常见问题
1	文件是否读取成功	路径错误、编码错误、文件为空
2	文本是否切分成功	chunk 太大或太小、中文分隔符不合适
3	Embedding 是否加载成功	模型下载失败、网络问题、设备配置错误
4	向量库是否构建成功	Chroma/FAISS 安装或版本问题
5	检索片段是否相关	Embedding 不合适、top_k 设置不合理、chunk 策略不佳
6	Prompt 是否合理	没有限制模型只基于资料回答
7	LLM 接口是否成功	API Key、base_url、model 名称或权限问题

七、最终结论

LangChain 代码适合学习 RAG 的底层流程，能清楚看到读取、切分、向量化、检索、拼接 context 和调用大模型的每一步。LlamaIndex 代码更适合快速搭建文档问答系统，尤其在复杂 PDF 解析、索引构建、查询引擎、总结工具和 Agent 调用方面更方便。

两者的核心思想完全一致：先检索，再生成。真正决定 RAG 效果的关键不是单一大模型，而是文档切分质量、Embedding 检索质量、向量库召回效果、Prompt 约束和结果可追溯性。