LangChain文档模块学习入门指南

在LangChain框架中，Document对象是数据检索与RAG（检索增强生成）流水线的核心基石。无论是从外部加载知识库、切分文本，还是存入向量数据库，所有数据传输都必须被标准化封装为Document对象。简单来说，它就是整个链条中流通的“标准货币”，确保数据格式统一、流转高效。

1. Document 的核心结构与属性

Document类的底层基于Pydantic的BaseModel实现。官方设计极为精简，在最新版本中主要包含以下三个核心属性：

 复制代码from langchain_core.documents import Documentdoc = Document(
    page_content="这是文档的核心文本内容...",
    metadata={
        "source": "https://example.com",
        "author": "张三",
        "page": 12,
        "category": "AI开发"
    },
    id="doc_001"  # 需 langchain-core >= 0.1.0，支持id
)

查看Document源码的继承关系，可以发现它确实继承自Pydantic的BaseModel：

 复制代码class Document(BaseMedia):
class BaseMedia(Serializable):
class Serializable(BaseModel, ABC):

下面逐一拆解这些属性：

1. page_content（str）：必填项。存放纯文本内容，是未来被转换为向量（Embedding）并最终输入大模型（LLM）的检索核心。
2. metadata（dict）：可选项，默认为空字典。用于存储任意维度的元数据。在向量检索时，可以基于这些字段进行硬过滤（Metadata Filtering），例如只检索category == "AI开发"的文档。
3. id（str或int）：可选项。文档的唯一标识。在大规模检索和向量数据库的增删改查操作中，显式指定id至关重要，能有效防止重复插入。

需要特别注意的是，Document本身是Pydantic对象，不应直接作为聊天消息发送。与LLM交互时，必须提取其page_content字段，组合成纯文本Prompt或Message。

2. Document 在 RAG 完整生命周期中的关键角色

在典型的RAG架构中，Document扮演着“标准通用货币”的角色，串联起以下四个核心环节：

 复制代码[外部数据源 (PDF/Web/Notion)] 
         │  
         ▼ 1. Document Loaders (加载为 Document 对象列表)
[List[Document]] 
         │  
         ▼ 2. Text Splitters (将大 Document 切分为多个小 Chunk Document)
[List[Chunk Documents]] 
         │  
         ▼ 3. Embeddings & Vector Stores (提取 page_content 转换为向量，连同 metadata 一起持久化)
[向量数据库] 
         │  
         ▼ 4. Retrievers (检索出最相似的 Document 对象，拼入 Prompt)
[大模型 (LLM)]

• 加载阶段：通过Document Loaders（如PyPDFLoader、WebBaseLoader）将网页、PDF等文档统一解析为Document对象。
• 切分阶段：由于大模型存在Token限制，Text Splitters（如RecursiveCharacterTextSplitter）接收一个Document，将其切碎后返回一组全新的、page_content更短的Document列表，同时原有的metadata会被自动复制或继承。

3. 常用方法与实用技巧

在实际工程中，可能需要手动创建、转换或过滤Document对象。下面几个技巧值得掌握。

技巧 A：手动创建与合并文档

 复制代码from langchain_core.documents import Document# 1. 快速手动创建
doc1 = Document(page_content="人工智能改变世界。", metadata={"source": "news"})
doc2 = Document(page_content="Python 是 AI 开发的首选语言。", metadata={"source": "blog"})# 2. 批量处理：比如通过循环清洗、拼接文本
all_docs = [doc1, doc2] # all_docs: list[Document]
for doc in all_docs:
    doc.metadata = {**doc.metadata, "processed_at": "2026-06-10"} # 字典解包，避免了绕过验证器的风险。# 字典解包
old = {"source": "news", "author": "张三" }
{**old, "processed_at": "..."} # 等价于 {"source": "news", "author": "张三", "processed_at": "..."}
# 字典的键值对：追加/覆盖，特点：返回一个新字典，未修改原字典

技巧 B：将结构化数据（如 JSON/CSV）转化为 Document

当拥有数据库导出的结构化数据时，可以自由决定哪些字段作为检索文本，哪些作为过滤标签：

 复制代码user_data = [
    {"name": "李四", "review": "这款产品太棒了，体验丝滑。", "rating": 5},
    {"name": "王五", "review": "物流太慢，客服态度一般。", "rating": 2}
]documents = []
for item in user_data:
    # 将核心评论作为检索文本
    content = f"用户评论: {item['review']}"
    # 将姓名和评分作为元数据过滤标签
    meta = {"user": item["name"], "rating": item["rating"]}
    
    documents.append(Document(page_content=content, metadata=meta))

技巧 C：直接利用 Document 与大模型交互

当检索出Document后，可以非常方便地将它们串联成大模型所需的上下文：

 复制代码# 假设从向量库检索出了 2 个相关的 Document
retrieved_docs = [doc1, doc2]# 提取并拼接内容
context = "nn".join([d.page_content for d in retrieved_docs])# 构建最后的 Prompt
prompt = f"请根据以下参考资料回答问题：nn资料：{context}nn问题：AI 的首选语言是什么？"

练习例子：

 复制代码from langchain_core.documents import Document# 访问
document1 = Document(
    page_content="LangChain 是一个用于开发大语言模型应用的框架。",
    metadata={"author": "张三", "page": 10}
)
print(document1)documents = [
    Document(page_content="第一章：Python 基础语法", metadata={"chapter": 1, "title": "Python 入门"}),
    Document(page_content="第二章：Python 数据结构", metadata={"chapter": 2, "title": "Python 入门"}),
    Document(page_content="第三章：Python 函数编程", metadata={"chapter": 3, "title": "Python 入门"}),
]
for doc in documents:
    print(f"{doc.page_content}")# 修改
document3 = Document(
    page_content="原始内容",
    metadata={"source": "test"}
)
document4 = {**document3.metadata, "source": "test11111"}
print(f"document3={document3}")
print(f"document4={document4}")# 序列化，转换成JSON格式
import json
document1_json = document1.to_json()
print(f"转换格式后：n{json.dumps(document1_json, ensure_ascii=False, indent=2)}")
# 转换格式后，{
#   "lc": 1,
#   "type": "constructor",
#   "id": [
#     "langchain",
#     "schema",
#     "document",
#     "Document"
#   ],
#   "kwargs": {
#     "metadata": {
#       "author": "张三",
#       "page": 10
#     },
#     "page_content": "LangChain 是一个用于开发大语言模型应用的框架。",
#     "type": "Document"
#   }
# }