1. 从零开始理解LangChain它到底是什么以及为什么你需要它如果你最近在接触大语言模型应用开发那么“LangChain”这个词大概率已经在你眼前晃过无数次了。无论是技术社区、招聘要求还是各种AI应用的分析文章它都频繁出现。但当你兴冲冲地打开官方文档面对“Chains”、“Agents”、“Memory”这些概念时是不是又感觉一头雾水不知道从何下手别担心这种感觉我最初也有。LangChain并不是一个高深莫测的黑魔法它更像是一个为LLM应用开发者准备的、功能齐全的“瑞士军刀”工具箱。它的核心目标非常明确简化构建基于大语言模型的应用程序的复杂性。简单来说LangChain提供了一套标准化的接口、组件和设计模式让你能把大语言模型比如GPT-4、Claude、本地部署的Llama等轻松地连接到你的数据源如PDF、数据库、网页并组合成可以执行复杂任务的工作流。没有它你需要自己处理API调用、上下文管理、工具集成、记忆存储等一系列繁琐且容易出错的底层细节。有了它你可以更专注于应用逻辑本身用更少的代码实现更强大的功能。无论你是想做一个能和你聊私人文档的智能助手还是一个能自动分析数据并生成报告的自动化流程LangChain都能为你提供坚实的脚手架。2. LangChain核心架构与设计哲学拆解要玩转LangChain死记硬背API是没用的必须理解其背后的设计思想。它的架构可以看作是一种“乐高积木”式的模块化设计整个框架围绕几个核心抽象概念构建理解这些概念就等于拿到了入门钥匙。2.1 核心六大组件构建应用的基石LangChain将LLM应用开发中常见的需求抽象成了六大核心组件它们之间松耦合可以灵活组合。模型 I/O (Model I/O)这是与LLM交互的入口层。它进一步细分为三个部分语言模型 (LLMs/Chat Models)这是核心例如OpenAI的GPT-3.5-turbo、Anthropic的Claude或通过Hugging Face集成的开源模型。LangChain统一了它们的调用接口让你用几乎相同的方式与不同模型对话。提示词模板 (Prompt Templates)直接向模型发送“请总结这段文本”这样的指令是低效且不稳定的。提示词模板允许你创建可复用的提示结构并动态注入变量。例如一个总结文档的模板可能是“请用中文总结以下内容{document_text}”。你只需要替换{document_text}部分即可。输出解析器 (Output Parsers)LLM的输出是自由文本但我们的程序需要结构化的数据如JSON对象、列表。输出解析器负责将模型的文本输出转换成你程序能方便使用的格式。例如你可以让模型输出一个包含“观点”和“理由”的JSON然后由解析器确保你拿到的是一个干净的字典。数据连接 (Retrieval)这是让LLM“拥有”你私有知识的关键通常与RAG架构紧密相关。它处理从加载文档如PDF、Word、网页到最终被模型使用的全过程文档加载器 (Document Loaders)从各种来源文件系统、网络、数据库加载原始数据并将其转换成统一的Document对象包含文本内容和元数据。文本分割器 (Text Splitters)LLM有上下文长度限制。一篇长文档必须被切分成语义连贯的“块”。文本分割器负责这项工作常见策略有按字符、按标记、按递归分割等目标是让每个块既能被模型处理又尽可能保持其独立语义。向量存储与检索器 (Vectorstores Retrievers)这是RAG的核心。文本块通过嵌入模型转换成向量一组数字存入向量数据库如Chroma、Pinecone、Weaviate。当用户提问时将问题也转换成向量并在数据库中快速找到最相似的几个文本块作为“参考材料”提供给LLM。链 (Chains)链是LangChain的灵魂。它允许你将多个组件或多个LLM调用按顺序组合成一个完整的应用逻辑。最简单的链是LLMChain它组合了一个提示词模板和一个LLM。更复杂的链可以包含检索、多个模型调用、条件判断等。你可以把链想象成一个工作流或管道。代理 (Agents)如果说链是预设好的工作流那么代理就是赋予LLM“使用工具”能力的智能体。你给代理一些可用的工具如搜索网络、查询数据库、执行代码并给它一个目标如“找出今年AI领域最大的融资事件”代理会自己决定先做什么、后做什么、如何使用工具并循环直到完成任务。这是构建高度自主应用的关键。记忆 (Memory)为了让LLM在对话中记住之前说过的话实现多轮对话或者让代理记住之前的操作步骤你需要记忆组件。它可以是简单的缓冲区只记住最近几轮对话也可以是更复杂的、将历史总结后存储的长期记忆。回调 (Callbacks)用于在应用执行过程中进行日志记录、流式输出、监控等。它让你能深入了解链或代理的内部执行过程对于调试和构建用户界面如显示生成过程中的中间结果非常有用。2.2 LangChain的设计优势与典型应用场景理解了组件我们再来看看这套设计解决了什么问题。在没有框架的情况下构建一个简单的文档问答应用你可能需要写代码调用嵌入API、设计分块逻辑、搭建向量数据库、处理提示词、调用LLM API、解析输出……这些代码往往粘合在一起难以维护和复用。LangChain通过模块化带来了几个核心优势组件可替换性今天用OpenAI的模型明天想换Claude你只需要换一个ChatModel的实例其他部分代码基本不用动。向量存储从Chroma换成Pinecone也同样简单。工作流标准化常见的应用模式如“检索-问答”、“摘要生成”、“基于SQL的问答”都有预构建的链或代理你可以直接使用或在其基础上微调极大提升开发效率。生态丰富围绕这些核心抽象社区贡献了海量的集成各种文档加载器、工具、向量库你几乎可以找到任何你需要的第三方服务连接器。典型的应用场景包括个人知识库问答将你的笔记、论文、手册灌入向量库创建一个能回答你私人问题的助手。聊天机器人构建具有长期记忆、能调用外部API查天气、订机票的智能客服或伴侣。内容分析与生成自动分析一批用户反馈生成总结报告或者根据结构化数据生成营销文案。智能工作流自动化让代理自动浏览网页收集信息整理到表格中并撰写邮件摘要。3. 核心概念深度解析与实操要点了解了宏观架构我们深入到几个最关键也最容易混淆的概念里看看它们具体怎么用以及有哪些坑需要避开。3.1 提示词模板不只是字符串替换很多人觉得提示词模板就是f-string这低估了它的价值。LangChain的模板支持更复杂的结构。基础用法from langchain.prompts import PromptTemplate template “””你是一个专业的翻译官。请将以下英文翻译成中文并保持专业术语准确 英文{input_text} 中文翻译””” prompt PromptTemplate.from_template(template) # 填充变量 filled_prompt prompt.format(input_text“Large Language Models are revolutionizing software development.”) print(filled_prompt)这看起来很简单但模板的核心优势在于与链的集成。你可以直接把prompt对象传给LLMChain链会自动处理格式化并调用模型。高级技巧Few-Shot 示例模板对于复杂任务你需要在提示词中提供例子。FewShotPromptTemplate可以优雅地处理from langchain.prompts import FewShotPromptTemplate, PromptTemplate examples [ { “input”: “The product is great but delivery was slow.”, “output”: “情感混合正面评价产品负面评价物流” }, { “input”: “This is the worst experience ever.”, “output”: “情感负面” }, ] example_prompt PromptTemplate( input_variables[“input”, “output”], template“输入{input}\n输出{output}” ) few_shot_prompt FewShotPromptTemplate( examplesexamples, example_promptexample_prompt, prefix“请根据示例分析用户评论的情感倾向。”, suffix“输入{user_input}\n输出”, input_variables[“user_input”], )这样你就构建了一个包含示例的、可复用的复杂提示词。注意提示词模板中的变量名必须与format时传入的字典键名完全匹配否则会报错。建议在复杂应用中将模板字符串单独存放在配置文件或数据库中便于管理和迭代优化。3.2 链不仅仅是顺序执行LLMChain是最简单的链但链的真正威力在于组合。顺序链 (SequentialChain)当你有多个步骤且后一步需要前一步的输出时就需要顺序链。例如先总结一篇文章再根据总结写一首诗。from langchain.chains import LLMChain, SimpleSequentialChain from langchain.prompts import PromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI(model“gpt-3.5-turbo”) # 链1总结 summary_prompt PromptTemplate( input_variables[“text”], template“请用一句话总结以下文本{text}” ) summary_chain LLMChain(llmllm, promptsummary_prompt) # 链2写诗 poem_prompt PromptTemplate( input_variables[“summary”], template“根据这句话的意境创作一首四句中文古诗{summary}” ) poem_chain LLMChain(llmllm, promptpoem_prompt) # 组合成顺序链 overall_chain SimpleSequentialChain(chains[summary_chain, poem_chain], verboseTrue) result overall_chain.run(“这里输入一篇很长的文章...”)verboseTrue参数会让你在控制台看到链的每一步执行过程和中间结果调试神器。路由链 (RouterChain)这是更高级的模式用于根据输入内容决定将其发送给哪个子链处理。比如用户输入可能是“查询天气”或“翻译句子”你需要一个路由链来先做意图识别然后分流到“天气查询链”或“翻译链”。这通常需要借助LLMRouterChain和MultiPromptChain来实现构建一个初步的智能体雏形。实操心得不要试图用一个超级复杂的链解决所有问题。应该遵循“单一职责”原则先构建多个功能单一、测试完备的小链再将它们组合起来。这样不仅易于调试也方便后续替换或升级其中某个环节。3.3 检索器RAG应用的心脏构建一个高效的检索器是RAG应用成败的关键。它不仅仅是“存进去查出来”那么简单。文本分割的艺术分块大小和重叠度是两个关键参数。块大小 (chunk_size)通常设置在500-1500字符或256-1024个token之间。太小会失去上下文太大会超出模型窗口且检索精度下降。对于技术文档可以稍小对于叙事性文本可以稍大。重叠度 (chunk_overlap)设置在块大小的10%-20%。这是为了避免一个完整的句子或关键概念被硬生生切到两个块中间导致检索时信息不完整。重叠部分保证了上下文的连续性。from langchain.text_splitter import RecursiveCharacterTextSplitter text_splitter RecursiveCharacterTextSplitter( chunk_size1000, # 每个块的最大字符数 chunk_overlap200, # 块之间的重叠字符数 length_functionlen, # 计算长度的方法 separators[“\n\n”, “\n”, “。”, “”, “”, “ “, “”] # 分割符优先级 ) docs text_splitter.split_documents(your_documents)RecursiveCharacterTextSplitter是常用选择它尝试按分隔符优先级递归分割以得到大小接近的块。检索策略的选择从向量库检索时默认是相似性搜索。但LangChain提供了更丰富的检索器VectorStoreRetriever最基础的基于向量相似度的检索。ContextualCompressionRetriever在返回结果前使用一个额外的LLM来压缩或过滤掉不相关的信息只返回最精华的部分可以节省上下文窗口。EnsembleRetriever集成多个检索器如一个向量检索器一个关键词检索器BM25合并结果提高召回率。ParentDocumentRetriever一种高级模式。存储时将文档分成小块用于检索但同时保留指向原始大块的引用。检索到小塊后返回其所属的完整大块作为上下文兼顾了检索精度和上下文完整性。常见问题为什么我的RAG系统总是“胡言乱语”很可能不是模型问题而是检索环节出了问题。检索到的文档块与问题不相关或者信息不完整导致模型“巧妇难为无米之炊”。务必检查你的分割策略和检索相似度阈值。4. 手把手构建你的第一个LangChain智能应用一个本地知识库问答机器人理论说得再多不如动手做一遍。我们来构建一个经典的RAG应用一个能回答关于特定文档比如你自己写的技术笔记问题的本地问答机器人。我们将使用本地运行的嵌入模型和向量数据库完全离线保护隐私。4.1 环境准备与依赖安装首先创建一个新的Python虚拟环境并安装核心库。这里我们选择Chroma作为向量数据库轻量、易用sentence-transformers来获取本地嵌入模型。# 创建并激活虚拟环境以conda为例 conda create -n langchain-demo python3.10 conda activate langchain-demo # 安装核心库 pip install langchain langchain-community langchain-chroma # 安装本地嵌入模型库和向量数据库 pip install sentence-transformers chromadb # 安装文档加载器以处理txt和pdf为例 pip install pypdflangchain-community包含了大量第三方集成langchain-chroma是ChromaDB的专门集成包。4.2 文档加载、分割与向量化假设你的知识文档放在./my_docs文件夹下里面有若干PDF和TXT文件。import os from langchain_community.document_loaders import DirectoryLoader, PyPDFLoader, TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_huggingface import HuggingFaceEmbeddings from langchain_chroma import Chroma # 1. 加载文档 documents [] data_path “./my_docs” # 加载所有PDF文件 pdf_loader DirectoryLoader(data_path, glob“**/*.pdf”, loader_clsPyPDFLoader) documents.extend(pdf_loader.load()) # 加载所有TXT文件 txt_loader DirectoryLoader(data_path, glob“**/*.txt”, loader_clsTextLoader) documents.extend(txt_loader.load()) print(f“共加载了 {len(documents)} 个文档”) # 2. 分割文档 text_splitter RecursiveCharacterTextSplitter( chunk_size800, chunk_overlap150, length_functionlen, separators[“\n\n”, “\n”, “。”, “”, “”, “ “, “”] ) split_docs text_splitter.split_documents(documents) print(f“分割后得到 {len(split_docs)} 个文本块”) # 3. 初始化本地嵌入模型 # 选用一个轻量且效果不错的中文模型 embed_model HuggingFaceEmbeddings(model_name“BAAI/bge-small-zh-v1.5”) # 4. 创建向量数据库并持久化 vectorstore Chroma.from_documents( documentssplit_docs, embeddingembed_model, persist_directory“./chroma_db” # 指定持久化目录 ) vectorstore.persist() # 将数据写入磁盘 print(“向量数据库已创建并持久化到 ./chroma_db”)这段代码完成了从原始文档到向量数据库的整个流水线。关键点在于选择了BAAI/bge-small-zh-v1.5这个针对中文优化的嵌入模型它对中文语义的理解和向量化效果比通用模型好很多。4.3 构建检索问答链数据库建好后我们需要一个链它能接收用户问题自动检索相关文档并组合成提示词发送给LLM。from langchain.chains import RetrievalQA from langchain_openai import ChatOpenAI from langchain.prompts import PromptTemplate # 注意这里为了演示使用了OpenAI的模型。如果你需要完全离线可以替换为本地LLM如通过Ollama集成。 # 请确保已设置OPENAI_API_KEY环境变量。 # 1. 从磁盘加载已存在的向量数据库 embed_model HuggingFaceEmbeddings(model_name“BAAI/bge-small-zh-v1.5”) vectorstore Chroma(persist_directory“./chroma_db”, embedding_functionembed_model) # 2. 将向量数据库转为检索器 # 设置 search_kwargs{“k”: 4} 表示每次检索返回最相似的4个文档块 retriever vectorstore.as_retriever(search_kwargs{“k”: 4}) # 3. 定义自定义提示词模板让模型基于检索到的上下文回答 custom_prompt_template “””使用以下上下文片段来回答最后的问题。如果你不知道答案就说你不知道不要编造答案。请使用中文回答。 上下文 {context} 问题{question} 有帮助的答案””” PROMPT PromptTemplate( templatecustom_prompt_template, input_variables[“context”, “question”] ) # 4. 创建检索问答链 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) # temperature0使输出更确定 qa_chain RetrievalQA.from_chain_type( llmllm, chain_type“stuff”, # 最简单的方式将所有检索到的上下文“塞”进提示词 retrieverretriever, chain_type_kwargs{“prompt”: PROMPT}, return_source_documentsTrue # 非常重要返回检索到的源文档便于验证 ) # 5. 进行问答 query “我的文档中提到了哪些关于机器学习模型部署的要点” result qa_chain.invoke({“query”: query}) print(“问题”, query) print(“\n答案”, result[“result”]) print(“\n 参考来源 ) for i, doc in enumerate(result[“source_documents”]): print(f“\n片段 {i1} (来自 ‘{doc.metadata.get(‘source’, ‘N/A’)}’):”) print(doc.page_content[:300] “…”) # 打印前300个字符这个RetrievalQA链是一个高级抽象它内部帮你完成了“检索 - 组合上下文 - 提问 - 解析输出”的全过程。chain_type“stuff”是最直接的方式但如果检索到的文档总长度超过模型上下文就会出错。对于超长文档可以考虑“map_reduce”或“refine”等更复杂的链类型。4.4 为机器人添加对话记忆上面的机器人是“健忘”的每次问答都是独立的。要让它记住对话历史需要引入Memory组件。from langchain.memory import ConversationBufferMemory from langchain.chains import ConversationalRetrievalChain # 初始化记忆保存对话历史 memory ConversationBufferMemory(memory_key“chat_history”, return_messagesTrue, output_key‘answer’) # 创建带记忆的对话检索链 conversational_qa_chain ConversationalRetrievalChain.from_llm( llmllm, retrieverretriever, memorymemory, combine_docs_chain_kwargs{“prompt”: PROMPT}, # 使用之前的自定义提示词 verboseTrue # 显示详细执行过程 ) # 进行多轮对话 print(“第一轮问答”) result1 conversational_qa_chain.invoke({“question”: “LangChain是什么”}) print(“AI:”, result1[“answer”]) print(“\n第二轮问答基于历史”) # 直接问“它有什么优势”AI应该能理解“它”指代LangChain result2 conversational_qa_chain.invoke({“question”: “它有什么优势”}) print(“AI:”, result2[“answer”]) # 查看当前记忆 print(“\n当前对话历史”) print(memory.load_memory_variables({}))现在你的机器人就具备了多轮对话的能力。ConversationBufferMemory会保存完整的对话历史。在真实应用中你可能需要考虑更节省token的记忆方式如ConversationSummaryMemory。5. 进阶探索与避坑指南当你完成了第一个基础应用后肯定会想尝试更酷的功能也会遇到各种问题。这里分享一些进阶方向和常见坑点。5.1 从链到代理让AI学会使用工具链是固定的流程而代理能动态决策。创建一个能使用搜索引擎和计算器的简单代理from langchain.agents import initialize_agent, AgentType from langchain.agents import Tool from langchain_community.utilities import SerpAPIWrapper from langchain.chains import LLMMathChain # 注意SerpAPI需要注册并获取API_KEY llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) search SerpAPIWrapper(serpapi_api_key“your_api_key”) llm_math LLMMathChain.from_llm(llmllm) tools [ Tool( name“Search”, funcsearch.run, description“在互联网上搜索当前事件或事实信息。当你需要获取最新、未知的信息时使用此工具。” ), Tool( name“Calculator”, funcllm_math.run, description“用于回答数学计算问题。输入应该是一个明确的数学表达式。” ), ] agent initialize_agent( tools, llm, agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, # 一种通用的代理类型 verboseTrue, handle_parsing_errorsTrue # 优雅处理代理输出解析错误 ) # 运行代理 agent.run(“上海今天的天气怎么样如果气温是25摄氏度那么相当于多少华氏度”)代理会先思考Reason然后行动Act。在verboseTrue模式下你能看到它完整的思考过程“我需要先查天气然后用计算器转换温度”。这就是自主智能的雏形。避坑指南代理虽然强大但也容易出错。常见问题有1)循环调用代理陷入死循环不断调用同一个工具。需要设置max_iterations参数限制步数。2)工具选择错误代理误解问题选错了工具。这需要你精心设计工具的描述description描述越清晰准确代理判断力越强。3)解析失败代理输出的指令格式不符合工具要求。确保使用handle_parsing_errorsTrue并考虑使用更稳定的代理类型如AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION。5.2 流式输出与回调打造流畅的用户体验直接等待LLM生成完整答案再返回用户体验很差。流式输出可以逐词返回结果。from langchain.callbacks.streaming_stdout import StreamingStdOutCallbackHandler # 创建支持流式输出的LLM streaming_llm ChatOpenAI( model“gpt-3.5-turbo”, streamingTrue, # 开启流式 callbacks[StreamingStdOutCallbackHandler()], # 使用标准输出回调 temperature0 ) # 在链或代理中使用这个llm qa_chain_streaming RetrievalQA.from_chain_type( llmstreaming_llm, chain_type“stuff”, retrieverretriever ) # 调用时答案会逐词打印出来 qa_chain_streaming.invoke({“query”: “请解释什么是RAG”})在Web应用中你可以使用StreamingStdOutCallbackHandler的自定义版本将token推送到前端。5.3 常见错误与排查清单API Rate Limit或Authentication Error检查API密钥是否正确设置os.environ[“OPENAI_API_KEY”]。免费额度是否用完。请求频率是否超限。解决使用temperature0测试减少不必要请求。对于OpenAI考虑升级套餐或使用多个密钥轮询。Context Length Exceeded(上下文长度超限)检查使用stuff链时检索到的文档总长度是否超过模型限制。解决减少检索数量search_kwargs{“k”: 2}或换用map_reduce、refine链类型。优化文本分割减少块大小。检索结果不相关导致答案质量差检查嵌入模型是否适合你的文本领域中文用中文模型。分块大小和重叠度是否合理。检索相似度阈值是否可调有些向量库支持score_threshold。解决尝试不同的嵌入模型。调整分块策略。使用MultiQueryRetriever或EnsembleRetriever提高召回率。在提示词中严格要求模型“基于上下文回答”。代理运行缓慢或卡住检查是否进入了循环verboseTrue查看思考过程。网络工具如搜索响应是否超时。解决设置max_iterations5等限制。为工具调用添加超时处理。使用更精确的工具描述来引导代理。安装或导入错误 (ModuleNotFoundError)检查LangChain模块化后许多集成需要单独安装。错误提示缺少langchain-community或langchain-openai等。解决根据官方文档使用pip install langchain-community langchain-openai等命令安装所需的具体集成包。LangChain的世界很大本文涵盖的只是其基础和核心部分。当你熟悉了这些概念和模式后可以进一步探索LangGraph用于构建有状态、循环的复杂代理工作流、更高级的记忆系统、以及如何将你的链部署为API服务。记住最好的学习方式就是动手做一个你自己的项目在解决具体问题的过程中你会对这套框架有更深刻的理解。 LangChain框架解析：从核心概念到RAG应用实战
1. 从零开始理解LangChain它到底是什么以及为什么你需要它如果你最近在接触大语言模型应用开发那么“LangChain”这个词大概率已经在你眼前晃过无数次了。无论是技术社区、招聘要求还是各种AI应用的分析文章它都频繁出现。但当你兴冲冲地打开官方文档面对“Chains”、“Agents”、“Memory”这些概念时是不是又感觉一头雾水不知道从何下手别担心这种感觉我最初也有。LangChain并不是一个高深莫测的黑魔法它更像是一个为LLM应用开发者准备的、功能齐全的“瑞士军刀”工具箱。它的核心目标非常明确简化构建基于大语言模型的应用程序的复杂性。简单来说LangChain提供了一套标准化的接口、组件和设计模式让你能把大语言模型比如GPT-4、Claude、本地部署的Llama等轻松地连接到你的数据源如PDF、数据库、网页并组合成可以执行复杂任务的工作流。没有它你需要自己处理API调用、上下文管理、工具集成、记忆存储等一系列繁琐且容易出错的底层细节。有了它你可以更专注于应用逻辑本身用更少的代码实现更强大的功能。无论你是想做一个能和你聊私人文档的智能助手还是一个能自动分析数据并生成报告的自动化流程LangChain都能为你提供坚实的脚手架。2. LangChain核心架构与设计哲学拆解要玩转LangChain死记硬背API是没用的必须理解其背后的设计思想。它的架构可以看作是一种“乐高积木”式的模块化设计整个框架围绕几个核心抽象概念构建理解这些概念就等于拿到了入门钥匙。2.1 核心六大组件构建应用的基石LangChain将LLM应用开发中常见的需求抽象成了六大核心组件它们之间松耦合可以灵活组合。模型 I/O (Model I/O)这是与LLM交互的入口层。它进一步细分为三个部分语言模型 (LLMs/Chat Models)这是核心例如OpenAI的GPT-3.5-turbo、Anthropic的Claude或通过Hugging Face集成的开源模型。LangChain统一了它们的调用接口让你用几乎相同的方式与不同模型对话。提示词模板 (Prompt Templates)直接向模型发送“请总结这段文本”这样的指令是低效且不稳定的。提示词模板允许你创建可复用的提示结构并动态注入变量。例如一个总结文档的模板可能是“请用中文总结以下内容{document_text}”。你只需要替换{document_text}部分即可。输出解析器 (Output Parsers)LLM的输出是自由文本但我们的程序需要结构化的数据如JSON对象、列表。输出解析器负责将模型的文本输出转换成你程序能方便使用的格式。例如你可以让模型输出一个包含“观点”和“理由”的JSON然后由解析器确保你拿到的是一个干净的字典。数据连接 (Retrieval)这是让LLM“拥有”你私有知识的关键通常与RAG架构紧密相关。它处理从加载文档如PDF、Word、网页到最终被模型使用的全过程文档加载器 (Document Loaders)从各种来源文件系统、网络、数据库加载原始数据并将其转换成统一的Document对象包含文本内容和元数据。文本分割器 (Text Splitters)LLM有上下文长度限制。一篇长文档必须被切分成语义连贯的“块”。文本分割器负责这项工作常见策略有按字符、按标记、按递归分割等目标是让每个块既能被模型处理又尽可能保持其独立语义。向量存储与检索器 (Vectorstores Retrievers)这是RAG的核心。文本块通过嵌入模型转换成向量一组数字存入向量数据库如Chroma、Pinecone、Weaviate。当用户提问时将问题也转换成向量并在数据库中快速找到最相似的几个文本块作为“参考材料”提供给LLM。链 (Chains)链是LangChain的灵魂。它允许你将多个组件或多个LLM调用按顺序组合成一个完整的应用逻辑。最简单的链是LLMChain它组合了一个提示词模板和一个LLM。更复杂的链可以包含检索、多个模型调用、条件判断等。你可以把链想象成一个工作流或管道。代理 (Agents)如果说链是预设好的工作流那么代理就是赋予LLM“使用工具”能力的智能体。你给代理一些可用的工具如搜索网络、查询数据库、执行代码并给它一个目标如“找出今年AI领域最大的融资事件”代理会自己决定先做什么、后做什么、如何使用工具并循环直到完成任务。这是构建高度自主应用的关键。记忆 (Memory)为了让LLM在对话中记住之前说过的话实现多轮对话或者让代理记住之前的操作步骤你需要记忆组件。它可以是简单的缓冲区只记住最近几轮对话也可以是更复杂的、将历史总结后存储的长期记忆。回调 (Callbacks)用于在应用执行过程中进行日志记录、流式输出、监控等。它让你能深入了解链或代理的内部执行过程对于调试和构建用户界面如显示生成过程中的中间结果非常有用。2.2 LangChain的设计优势与典型应用场景理解了组件我们再来看看这套设计解决了什么问题。在没有框架的情况下构建一个简单的文档问答应用你可能需要写代码调用嵌入API、设计分块逻辑、搭建向量数据库、处理提示词、调用LLM API、解析输出……这些代码往往粘合在一起难以维护和复用。LangChain通过模块化带来了几个核心优势组件可替换性今天用OpenAI的模型明天想换Claude你只需要换一个ChatModel的实例其他部分代码基本不用动。向量存储从Chroma换成Pinecone也同样简单。工作流标准化常见的应用模式如“检索-问答”、“摘要生成”、“基于SQL的问答”都有预构建的链或代理你可以直接使用或在其基础上微调极大提升开发效率。生态丰富围绕这些核心抽象社区贡献了海量的集成各种文档加载器、工具、向量库你几乎可以找到任何你需要的第三方服务连接器。典型的应用场景包括个人知识库问答将你的笔记、论文、手册灌入向量库创建一个能回答你私人问题的助手。聊天机器人构建具有长期记忆、能调用外部API查天气、订机票的智能客服或伴侣。内容分析与生成自动分析一批用户反馈生成总结报告或者根据结构化数据生成营销文案。智能工作流自动化让代理自动浏览网页收集信息整理到表格中并撰写邮件摘要。3. 核心概念深度解析与实操要点了解了宏观架构我们深入到几个最关键也最容易混淆的概念里看看它们具体怎么用以及有哪些坑需要避开。3.1 提示词模板不只是字符串替换很多人觉得提示词模板就是f-string这低估了它的价值。LangChain的模板支持更复杂的结构。基础用法from langchain.prompts import PromptTemplate template “””你是一个专业的翻译官。请将以下英文翻译成中文并保持专业术语准确 英文{input_text} 中文翻译””” prompt PromptTemplate.from_template(template) # 填充变量 filled_prompt prompt.format(input_text“Large Language Models are revolutionizing software development.”) print(filled_prompt)这看起来很简单但模板的核心优势在于与链的集成。你可以直接把prompt对象传给LLMChain链会自动处理格式化并调用模型。高级技巧Few-Shot 示例模板对于复杂任务你需要在提示词中提供例子。FewShotPromptTemplate可以优雅地处理from langchain.prompts import FewShotPromptTemplate, PromptTemplate examples [ { “input”: “The product is great but delivery was slow.”, “output”: “情感混合正面评价产品负面评价物流” }, { “input”: “This is the worst experience ever.”, “output”: “情感负面” }, ] example_prompt PromptTemplate( input_variables[“input”, “output”], template“输入{input}\n输出{output}” ) few_shot_prompt FewShotPromptTemplate( examplesexamples, example_promptexample_prompt, prefix“请根据示例分析用户评论的情感倾向。”, suffix“输入{user_input}\n输出”, input_variables[“user_input”], )这样你就构建了一个包含示例的、可复用的复杂提示词。注意提示词模板中的变量名必须与format时传入的字典键名完全匹配否则会报错。建议在复杂应用中将模板字符串单独存放在配置文件或数据库中便于管理和迭代优化。3.2 链不仅仅是顺序执行LLMChain是最简单的链但链的真正威力在于组合。顺序链 (SequentialChain)当你有多个步骤且后一步需要前一步的输出时就需要顺序链。例如先总结一篇文章再根据总结写一首诗。from langchain.chains import LLMChain, SimpleSequentialChain from langchain.prompts import PromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI(model“gpt-3.5-turbo”) # 链1总结 summary_prompt PromptTemplate( input_variables[“text”], template“请用一句话总结以下文本{text}” ) summary_chain LLMChain(llmllm, promptsummary_prompt) # 链2写诗 poem_prompt PromptTemplate( input_variables[“summary”], template“根据这句话的意境创作一首四句中文古诗{summary}” ) poem_chain LLMChain(llmllm, promptpoem_prompt) # 组合成顺序链 overall_chain SimpleSequentialChain(chains[summary_chain, poem_chain], verboseTrue) result overall_chain.run(“这里输入一篇很长的文章...”)verboseTrue参数会让你在控制台看到链的每一步执行过程和中间结果调试神器。路由链 (RouterChain)这是更高级的模式用于根据输入内容决定将其发送给哪个子链处理。比如用户输入可能是“查询天气”或“翻译句子”你需要一个路由链来先做意图识别然后分流到“天气查询链”或“翻译链”。这通常需要借助LLMRouterChain和MultiPromptChain来实现构建一个初步的智能体雏形。实操心得不要试图用一个超级复杂的链解决所有问题。应该遵循“单一职责”原则先构建多个功能单一、测试完备的小链再将它们组合起来。这样不仅易于调试也方便后续替换或升级其中某个环节。3.3 检索器RAG应用的心脏构建一个高效的检索器是RAG应用成败的关键。它不仅仅是“存进去查出来”那么简单。文本分割的艺术分块大小和重叠度是两个关键参数。块大小 (chunk_size)通常设置在500-1500字符或256-1024个token之间。太小会失去上下文太大会超出模型窗口且检索精度下降。对于技术文档可以稍小对于叙事性文本可以稍大。重叠度 (chunk_overlap)设置在块大小的10%-20%。这是为了避免一个完整的句子或关键概念被硬生生切到两个块中间导致检索时信息不完整。重叠部分保证了上下文的连续性。from langchain.text_splitter import RecursiveCharacterTextSplitter text_splitter RecursiveCharacterTextSplitter( chunk_size1000, # 每个块的最大字符数 chunk_overlap200, # 块之间的重叠字符数 length_functionlen, # 计算长度的方法 separators[“\n\n”, “\n”, “。”, “”, “”, “ “, “”] # 分割符优先级 ) docs text_splitter.split_documents(your_documents)RecursiveCharacterTextSplitter是常用选择它尝试按分隔符优先级递归分割以得到大小接近的块。检索策略的选择从向量库检索时默认是相似性搜索。但LangChain提供了更丰富的检索器VectorStoreRetriever最基础的基于向量相似度的检索。ContextualCompressionRetriever在返回结果前使用一个额外的LLM来压缩或过滤掉不相关的信息只返回最精华的部分可以节省上下文窗口。EnsembleRetriever集成多个检索器如一个向量检索器一个关键词检索器BM25合并结果提高召回率。ParentDocumentRetriever一种高级模式。存储时将文档分成小块用于检索但同时保留指向原始大块的引用。检索到小塊后返回其所属的完整大块作为上下文兼顾了检索精度和上下文完整性。常见问题为什么我的RAG系统总是“胡言乱语”很可能不是模型问题而是检索环节出了问题。检索到的文档块与问题不相关或者信息不完整导致模型“巧妇难为无米之炊”。务必检查你的分割策略和检索相似度阈值。4. 手把手构建你的第一个LangChain智能应用一个本地知识库问答机器人理论说得再多不如动手做一遍。我们来构建一个经典的RAG应用一个能回答关于特定文档比如你自己写的技术笔记问题的本地问答机器人。我们将使用本地运行的嵌入模型和向量数据库完全离线保护隐私。4.1 环境准备与依赖安装首先创建一个新的Python虚拟环境并安装核心库。这里我们选择Chroma作为向量数据库轻量、易用sentence-transformers来获取本地嵌入模型。# 创建并激活虚拟环境以conda为例 conda create -n langchain-demo python3.10 conda activate langchain-demo # 安装核心库 pip install langchain langchain-community langchain-chroma # 安装本地嵌入模型库和向量数据库 pip install sentence-transformers chromadb # 安装文档加载器以处理txt和pdf为例 pip install pypdflangchain-community包含了大量第三方集成langchain-chroma是ChromaDB的专门集成包。4.2 文档加载、分割与向量化假设你的知识文档放在./my_docs文件夹下里面有若干PDF和TXT文件。import os from langchain_community.document_loaders import DirectoryLoader, PyPDFLoader, TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_huggingface import HuggingFaceEmbeddings from langchain_chroma import Chroma # 1. 加载文档 documents [] data_path “./my_docs” # 加载所有PDF文件 pdf_loader DirectoryLoader(data_path, glob“**/*.pdf”, loader_clsPyPDFLoader) documents.extend(pdf_loader.load()) # 加载所有TXT文件 txt_loader DirectoryLoader(data_path, glob“**/*.txt”, loader_clsTextLoader) documents.extend(txt_loader.load()) print(f“共加载了 {len(documents)} 个文档”) # 2. 分割文档 text_splitter RecursiveCharacterTextSplitter( chunk_size800, chunk_overlap150, length_functionlen, separators[“\n\n”, “\n”, “。”, “”, “”, “ “, “”] ) split_docs text_splitter.split_documents(documents) print(f“分割后得到 {len(split_docs)} 个文本块”) # 3. 初始化本地嵌入模型 # 选用一个轻量且效果不错的中文模型 embed_model HuggingFaceEmbeddings(model_name“BAAI/bge-small-zh-v1.5”) # 4. 创建向量数据库并持久化 vectorstore Chroma.from_documents( documentssplit_docs, embeddingembed_model, persist_directory“./chroma_db” # 指定持久化目录 ) vectorstore.persist() # 将数据写入磁盘 print(“向量数据库已创建并持久化到 ./chroma_db”)这段代码完成了从原始文档到向量数据库的整个流水线。关键点在于选择了BAAI/bge-small-zh-v1.5这个针对中文优化的嵌入模型它对中文语义的理解和向量化效果比通用模型好很多。4.3 构建检索问答链数据库建好后我们需要一个链它能接收用户问题自动检索相关文档并组合成提示词发送给LLM。from langchain.chains import RetrievalQA from langchain_openai import ChatOpenAI from langchain.prompts import PromptTemplate # 注意这里为了演示使用了OpenAI的模型。如果你需要完全离线可以替换为本地LLM如通过Ollama集成。 # 请确保已设置OPENAI_API_KEY环境变量。 # 1. 从磁盘加载已存在的向量数据库 embed_model HuggingFaceEmbeddings(model_name“BAAI/bge-small-zh-v1.5”) vectorstore Chroma(persist_directory“./chroma_db”, embedding_functionembed_model) # 2. 将向量数据库转为检索器 # 设置 search_kwargs{“k”: 4} 表示每次检索返回最相似的4个文档块 retriever vectorstore.as_retriever(search_kwargs{“k”: 4}) # 3. 定义自定义提示词模板让模型基于检索到的上下文回答 custom_prompt_template “””使用以下上下文片段来回答最后的问题。如果你不知道答案就说你不知道不要编造答案。请使用中文回答。 上下文 {context} 问题{question} 有帮助的答案””” PROMPT PromptTemplate( templatecustom_prompt_template, input_variables[“context”, “question”] ) # 4. 创建检索问答链 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) # temperature0使输出更确定 qa_chain RetrievalQA.from_chain_type( llmllm, chain_type“stuff”, # 最简单的方式将所有检索到的上下文“塞”进提示词 retrieverretriever, chain_type_kwargs{“prompt”: PROMPT}, return_source_documentsTrue # 非常重要返回检索到的源文档便于验证 ) # 5. 进行问答 query “我的文档中提到了哪些关于机器学习模型部署的要点” result qa_chain.invoke({“query”: query}) print(“问题”, query) print(“\n答案”, result[“result”]) print(“\n 参考来源 ) for i, doc in enumerate(result[“source_documents”]): print(f“\n片段 {i1} (来自 ‘{doc.metadata.get(‘source’, ‘N/A’)}’):”) print(doc.page_content[:300] “…”) # 打印前300个字符这个RetrievalQA链是一个高级抽象它内部帮你完成了“检索 - 组合上下文 - 提问 - 解析输出”的全过程。chain_type“stuff”是最直接的方式但如果检索到的文档总长度超过模型上下文就会出错。对于超长文档可以考虑“map_reduce”或“refine”等更复杂的链类型。4.4 为机器人添加对话记忆上面的机器人是“健忘”的每次问答都是独立的。要让它记住对话历史需要引入Memory组件。from langchain.memory import ConversationBufferMemory from langchain.chains import ConversationalRetrievalChain # 初始化记忆保存对话历史 memory ConversationBufferMemory(memory_key“chat_history”, return_messagesTrue, output_key‘answer’) # 创建带记忆的对话检索链 conversational_qa_chain ConversationalRetrievalChain.from_llm( llmllm, retrieverretriever, memorymemory, combine_docs_chain_kwargs{“prompt”: PROMPT}, # 使用之前的自定义提示词 verboseTrue # 显示详细执行过程 ) # 进行多轮对话 print(“第一轮问答”) result1 conversational_qa_chain.invoke({“question”: “LangChain是什么”}) print(“AI:”, result1[“answer”]) print(“\n第二轮问答基于历史”) # 直接问“它有什么优势”AI应该能理解“它”指代LangChain result2 conversational_qa_chain.invoke({“question”: “它有什么优势”}) print(“AI:”, result2[“answer”]) # 查看当前记忆 print(“\n当前对话历史”) print(memory.load_memory_variables({}))现在你的机器人就具备了多轮对话的能力。ConversationBufferMemory会保存完整的对话历史。在真实应用中你可能需要考虑更节省token的记忆方式如ConversationSummaryMemory。5. 进阶探索与避坑指南当你完成了第一个基础应用后肯定会想尝试更酷的功能也会遇到各种问题。这里分享一些进阶方向和常见坑点。5.1 从链到代理让AI学会使用工具链是固定的流程而代理能动态决策。创建一个能使用搜索引擎和计算器的简单代理from langchain.agents import initialize_agent, AgentType from langchain.agents import Tool from langchain_community.utilities import SerpAPIWrapper from langchain.chains import LLMMathChain # 注意SerpAPI需要注册并获取API_KEY llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) search SerpAPIWrapper(serpapi_api_key“your_api_key”) llm_math LLMMathChain.from_llm(llmllm) tools [ Tool( name“Search”, funcsearch.run, description“在互联网上搜索当前事件或事实信息。当你需要获取最新、未知的信息时使用此工具。” ), Tool( name“Calculator”, funcllm_math.run, description“用于回答数学计算问题。输入应该是一个明确的数学表达式。” ), ] agent initialize_agent( tools, llm, agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, # 一种通用的代理类型 verboseTrue, handle_parsing_errorsTrue # 优雅处理代理输出解析错误 ) # 运行代理 agent.run(“上海今天的天气怎么样如果气温是25摄氏度那么相当于多少华氏度”)代理会先思考Reason然后行动Act。在verboseTrue模式下你能看到它完整的思考过程“我需要先查天气然后用计算器转换温度”。这就是自主智能的雏形。避坑指南代理虽然强大但也容易出错。常见问题有1)循环调用代理陷入死循环不断调用同一个工具。需要设置max_iterations参数限制步数。2)工具选择错误代理误解问题选错了工具。这需要你精心设计工具的描述description描述越清晰准确代理判断力越强。3)解析失败代理输出的指令格式不符合工具要求。确保使用handle_parsing_errorsTrue并考虑使用更稳定的代理类型如AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION。5.2 流式输出与回调打造流畅的用户体验直接等待LLM生成完整答案再返回用户体验很差。流式输出可以逐词返回结果。from langchain.callbacks.streaming_stdout import StreamingStdOutCallbackHandler # 创建支持流式输出的LLM streaming_llm ChatOpenAI( model“gpt-3.5-turbo”, streamingTrue, # 开启流式 callbacks[StreamingStdOutCallbackHandler()], # 使用标准输出回调 temperature0 ) # 在链或代理中使用这个llm qa_chain_streaming RetrievalQA.from_chain_type( llmstreaming_llm, chain_type“stuff”, retrieverretriever ) # 调用时答案会逐词打印出来 qa_chain_streaming.invoke({“query”: “请解释什么是RAG”})在Web应用中你可以使用StreamingStdOutCallbackHandler的自定义版本将token推送到前端。5.3 常见错误与排查清单API Rate Limit或Authentication Error检查API密钥是否正确设置os.environ[“OPENAI_API_KEY”]。免费额度是否用完。请求频率是否超限。解决使用temperature0测试减少不必要请求。对于OpenAI考虑升级套餐或使用多个密钥轮询。Context Length Exceeded(上下文长度超限)检查使用stuff链时检索到的文档总长度是否超过模型限制。解决减少检索数量search_kwargs{“k”: 2}或换用map_reduce、refine链类型。优化文本分割减少块大小。检索结果不相关导致答案质量差检查嵌入模型是否适合你的文本领域中文用中文模型。分块大小和重叠度是否合理。检索相似度阈值是否可调有些向量库支持score_threshold。解决尝试不同的嵌入模型。调整分块策略。使用MultiQueryRetriever或EnsembleRetriever提高召回率。在提示词中严格要求模型“基于上下文回答”。代理运行缓慢或卡住检查是否进入了循环verboseTrue查看思考过程。网络工具如搜索响应是否超时。解决设置max_iterations5等限制。为工具调用添加超时处理。使用更精确的工具描述来引导代理。安装或导入错误 (ModuleNotFoundError)检查LangChain模块化后许多集成需要单独安装。错误提示缺少langchain-community或langchain-openai等。解决根据官方文档使用pip install langchain-community langchain-openai等命令安装所需的具体集成包。LangChain的世界很大本文涵盖的只是其基础和核心部分。当你熟悉了这些概念和模式后可以进一步探索LangGraph用于构建有状态、循环的复杂代理工作流、更高级的记忆系统、以及如何将你的链部署为API服务。记住最好的学习方式就是动手做一个你自己的项目在解决具体问题的过程中你会对这套框架有更深刻的理解。