langchain-rag

检索增强生成（RAG）通过从外部知识源获取相关上下文来提升大模型的响应质量。

流程：

1. 索引：加载 → 切分 → 嵌入 → 存储
2. 检索：查询 → 嵌入 → 搜索 → 返回文档
3. 生成：文档 + 查询 → 大模型 → 响应

核心组件：

• 文档加载器：从文件、网页和数据库导入数据
• 文本切分器：将文档拆分为文本块
• 嵌入：将文本转换为向量
• 向量存储：存储并搜索嵌入向量

向量存储	用例	持久化
InMemory	测试	仅内存
FAISS	本地、高性能	磁盘
Chroma	开发	磁盘
Pinecone	生产、托管	云端

---

完整的 RAG 流程

端到端 RAG 流程：加载文档、切分为文本块、嵌入、存储、检索并生成响应。 ```python from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain_community.vectorstores import InMemoryVectorStore from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_core.documents import Document

1. Load documents

docs = [ Document(page_content="LangChain is a framework for LLM apps.", metadata={}), Document(page_content="RAG = Retrieval Augmented Generation.", metadata={}), ]

2. Split documents

splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50) splits = splitter.split_documents(docs)

3. Create embeddings and store

embeddings = OpenAIEmbeddings(model="text-embedding-3-small") vectorstore = InMemoryVectorStore.from_documents(splits, embeddings)

4. Create retriever

retriever = vectorstore.as_retriever(search_kwargs={"k": 4})

5. Use in RAG

model = ChatOpenAI(model="gpt-4.1") query = "What is RAG?" relevant_docs = retriever.invoke(query)

context = "\n\n".join([doc.page_content for doc in relevant_docs]) response = model.invoke([ {"role": "system", "content": f"Use this context:\n\n{context}"}, {"role": "user", "content": query}, ])

</python>
<typescript>
端到端 RAG 流程：加载文档、切分为文本块、嵌入、存储、检索并生成响应。
```typescript
import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai";
import { MemoryVectorStore } from "@langchain/classic/vectorstores/memory";
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";
import { Document } from "@langchain/core/documents";

// 1. Load documents
const docs = [
  new Document({ pageContent: "LangChain is a framework for LLM apps.", metadata: {} }),
  new Document({ pageContent: "RAG = Retrieval Augmented Generation.", metadata: {} }),
];

// 2. Split documents
const splitter = new RecursiveCharacterTextSplitter({ chunkSize: 500, chunkOverlap: 50 });
const splits = await splitter.splitDocuments(docs);

// 3. Create embeddings and store
const embeddings = new OpenAIEmbeddings({ model: "text-embedding-3-small" });
const vectorstore = await MemoryVectorStore.fromDocuments(splits, embeddings);

// 4. Create retriever
const retriever = vectorstore.asRetriever({ k: 4 });

// 5. Use in RAG
const model = new ChatOpenAI({ model: "gpt-4.1" });
const query = "What is RAG?";
const relevantDocs = await retriever.invoke(query);

const context = relevantDocs.map(doc => doc.pageContent).join("\n\n");
const response = await model.invoke([
  { role: "system", content: `Use this context:\n\n${context}` },
  { role: "user", content: query },
]);

---

文档加载器

加载 PDF 文件，并将每一页提取为单独的文档。 ```python from langchain_community.document_loaders import PyPDFLoader

loader = PyPDFLoader("./document.pdf") docs = loader.load() print(f"Loaded {len(docs)} pages")

</python>
<typescript>
加载 PDF 文件，并将每一页提取为单独的文档。
```typescript
import { PDFLoader } from "@langchain/community/document_loaders/fs/pdf";

const loader = new PDFLoader("./document.pdf");
const docs = await loader.load();
console.log(`Loaded ${docs.length} pages`);

从网页 URL 获取并解析内容，将其转换为文档。 ```python from langchain_community.document_loaders import WebBaseLoader

loader = WebBaseLoader("https://docs.langchain.com") docs = loader.load()

</python>
<typescript>
使用 Cheerio 从网页 URL 获取并解析内容，将其转换为文档。
```typescript
import { CheerioWebBaseLoader } from "@langchain/community/document_loaders/web/cheerio";

const loader = new CheerioWebBaseLoader("https://docs.langchain.com");
const docs = await loader.load();

使用 glob 模式从目录加载所有文本文件。 ```python from langchain_community.document_loaders import DirectoryLoader, TextLoader

Load all text files from directory

loader = DirectoryLoader( "path/to/documents", glob="**/*.txt", # Pattern for files to load loader_cls=TextLoader ) docs = loader.load()

</python>
</ex-loading-directory>

---

## 文本切分

<ex-text-splitting>
<python>
使用 RecursiveCharacterTextSplitter 将文档切分为文本块，并配置块大小和重叠长度。
```python
from langchain_text_splitters import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,        # Characters per chunk
    chunk_overlap=200,      # Overlap for context continuity
    separators=["\n\n", "\n", " ", ""],  # Split hierarchy
)

splits = splitter.split_documents(docs)

---

向量存储

创建持久化 Chroma 向量存储，并从磁盘重新加载。 ```python from langchain_chroma import Chroma from langchain_openai import OpenAIEmbeddings

vectorstore = Chroma.from_documents( documents=splits, embedding=OpenAIEmbeddings(), persist_directory="./chroma_db", collection_name="my-collection", )

Load existing

vectorstore = Chroma( persist_directory="./chroma_db", embedding_function=OpenAIEmbeddings(), collection_name="my-collection", )

</python>
<typescript>
创建连接到正在运行的 Chroma 服务的 Chroma 向量存储。
```typescript
import { Chroma } from "@langchain/community/vectorstores/chroma";
import { OpenAIEmbeddings } from "@langchain/openai";

const vectorstore = await Chroma.fromDocuments(
  splits,
  new OpenAIEmbeddings(),
  { collectionName: "my-collection", url: "http://localhost:8000" }
);

创建 FAISS 向量存储，将其保存到磁盘并重新加载。 ```python from langchain_community.vectorstores import FAISS

vectorstore = FAISS.from_documents(splits, embeddings) vectorstore.save_local("./faiss_index")

Load (requires allow_dangerous_deserialization)

loaded = FAISS.load_local( "./faiss_index", embeddings, allow_dangerous_deserialization=True )

</python>
<typescript>
创建 FAISS 向量存储，将其保存到磁盘并重新加载。
```typescript
import { FaissStore } from "@langchain/community/vectorstores/faiss";

const vectorstore = await FaissStore.fromDocuments(splits, embeddings);
await vectorstore.save("./faiss_index");

const loaded = await FaissStore.load("./faiss_index", embeddings);

---

检索

执行相似度搜索，并检索带有相关性分数的结果。 ```python # Basic search results = vectorstore.similarity_search(query, k=5)

With scores

results_with_score = vectorstore.similarity_search_with_score(query, k=5) for doc, score in results_with_score: print(f"Score: {score}, Content: {doc.page_content}")

</python>
<typescript>
执行相似度搜索，并检索带有相关性分数的结果。
```typescript
// Basic search
const results = await vectorstore.similaritySearch(query, 5);

// With scores
const resultsWithScore = await vectorstore.similaritySearchWithScore(query, 5);
for (const [doc, score] of resultsWithScore) {
  console.log(`Score: ${score}, Content: ${doc.pageContent}`);
}

使用 MMR（最大边际相关性）平衡搜索结果的相关性和多样性。 ```python # MMR balances relevance and diversity retriever = vectorstore.as_retriever( search_type="mmr", search_kwargs={"fetch_k": 20, "lambda_mult": 0.5, "k": 5}, ) ``` 为文档添加元数据，并根据元数据属性筛选搜索结果。 ```python # Add metadata when creating documents docs = [ Document( page_content="Python programming guide", metadata={"language": "python", "topic": "programming"} ), ]

Search with filter

results = vectorstore.similarity_search( "programming", k=5, filter={"language": "python"} # Only Python docs )

</python>
</ex-metadata-filtering>

<ex-rag-with-agent>
<python>
创建一个使用 RAG 作为工具回答问题的 Agent。
```python
from langchain.agents import create_agent
from langchain.tools import tool

@tool
def search_docs(query: str) -> str:
    """Search documentation for relevant information."""
    docs = retriever.invoke(query)
    return "\n\n".join([d.page_content for d in docs])

agent = create_agent(
    model="gpt-4.1",
    tools=[search_docs],
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "How do I create an agent?"}]
})

创建一个使用 RAG 作为工具回答问题的 Agent。 ```typescript import { createAgent } from "langchain"; import { tool } from "@langchain/core/tools"; import { z } from "zod";

const searchDocs = tool( async (input) => { const docs = await retriever.invoke(input.query); return docs.map(d => d.pageContent).join("\n\n"); }, { name: "search_docs", description: "Search documentation for relevant information.", schema: z.object({ query: z.string() }), } );

const agent = createAgent({ model: "gpt-4.1", tools: [searchDocs], });

const result = await agent.invoke({ messages: [{ role: "user", content: "How do I create an agent?" }], });

</typescript>
</ex-rag-with-agent>

<boundaries>
### 可配置项

- 文本块大小/重叠长度
- 嵌入模型
- 结果数量（k）
- 元数据筛选器
- 搜索算法：相似度、MMR
### 无法配置的内容

- 嵌入维度（每个模型）
- 在同一存储中混用不同模型的嵌入
</boundaries>

<fix-chunk-size>
<python>
块大小通常以 500-1500 为宜。
```python
# WRONG: Too small (loses context) or too large (hits limits)
splitter = RecursiveCharacterTextSplitter(chunk_size=50)
splitter = RecursiveCharacterTextSplitter(chunk_size=10000)

# CORRECT
splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)

块大小通常以 500-1500 为宜。 ```typescript // WRONG: Too small or too large const splitter = new RecursiveCharacterTextSplitter({ chunkSize: 50 });

// CORRECT const splitter = new RecursiveCharacterTextSplitter({ chunkSize: 1000, chunkOverlap: 200 });

</typescript>
</fix-chunk-size>

<fix-chunk-overlap>
<python>
使用重叠部分（块大小的 10-20%）来保持边界处的上下文。
```python
# WRONG: No overlap - context breaks at boundaries
splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=0)

# CORRECT: 10-20% overlap
splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)

使用持久化向量存储，而不是内存存储，以避免数据丢失。 ```python # WRONG: InMemory - lost on restart vectorstore = InMemoryVectorStore.from_documents(docs, embeddings)

CORRECT

vectorstore = Chroma.from_documents(docs, embeddings, persist_directory="./chroma_db")

</python>
<typescript>
使用持久化向量存储，而不是内存存储，以避免数据丢失。
```typescript
// WRONG: Memory - lost on restart
const vectorstore = await MemoryVectorStore.fromDocuments(docs, embeddings);

// CORRECT
const vectorstore = await Chroma.fromDocuments(docs, embeddings, { collectionName: "my-collection" });

为索引和查询使用相同的嵌入模型。 ```python # WRONG: Different embeddings for index and query - incompatible! vectorstore = Chroma.from_documents(docs, OpenAIEmbeddings(model="text-embedding-3-small")) retriever = vectorstore.as_retriever(embeddings=OpenAIEmbeddings(model="text-embedding-3-large"))

CORRECT: Same model

embeddings = OpenAIEmbeddings(model="text-embedding-3-small") vectorstore = Chroma.from_documents(docs, embeddings) retriever = vectorstore.as_retriever() # Uses same embeddings

</python>
<typescript>
为索引和查询使用相同的嵌入模型。
```typescript
const embeddings = new OpenAIEmbeddings({ model: "text-embedding-3-small" });
const vectorstore = await Chroma.fromDocuments(docs, embeddings);
const retriever = vectorstore.asRetriever();  // Uses same embeddings

加载 FAISS 索引时，显式允许反序列化。 ```python # WRONG: Will raise error loaded_store = FAISS.load_local("./faiss_index", embeddings)

CORRECT

loaded_store = FAISS.load_local("./faiss_index", embeddings, allow_dangerous_deserialization=True)

</python>
</fix-faiss-deserialization>

<fix-dimension-mismatch>
<python>
确保嵌入维度与向量存储索引的维度相匹配。
```python
# WRONG: Index has 1536 dimensions but using 512-dim embeddings
pc.create_index(name="idx", dimension=1536, metric="cosine")
vectorstore = PineconeVectorStore.from_documents(
    docs, OpenAIEmbeddings(model="text-embedding-3-small", dimensions=512), index=pc.Index("idx")
)  # Error: dimension mismatch!

# CORRECT: Match dimensions
embeddings = OpenAIEmbeddings()  # Default 1536