最近在接触大模型应用开发时发现很多同学对 LangChain 这个框架既好奇又畏惧——功能强大但概念繁多网上资料要么过于简单要么过于零散。本文基于真实项目经验用 20 分钟带你系统掌握 LangChain 的核心链路从最基础的 Prompt 工程到构建 RAG 知识库再到开发智能 Agent全程代码实战 高频避坑指南无论你是刚入门大模型开发还是已有基础想系统梳理都能直接复用。1. LangChain 核心概念与价值定位1.1 什么是 LangChainLangChain 是一个用于构建大语言模型LLM应用程序的框架它提供了一套标准化的接口和组件让开发者能够更高效地连接 LLM 与外部数据源、工具和业务逻辑。简单来说LangChain 就像是大模型应用的脚手架帮你处理 prompt 组装、上下文管理、工具调用等重复性工作。核心价值体现在三个方面模块化设计将 LLM 应用开发拆解为可复用的组件Models、Prompts、Chains、Agents 等生态集成预集成数百种数据源、工具和第三方服务减少重复造轮子生产就绪提供内存管理、回调系统、异步支持等工程化特性1.2 核心架构组件解析LangChain 的核心架构围绕几个关键抽象层展开Models模型层LLMs文本生成模型如 GPT、Claude 等ChatModels对话优化的模型支持 system/user/assistant 消息格式Embeddings文本向量化模型用于语义搜索和 RAGPrompts提示层PromptTemplate可复用的提示词模板FewShotPromptTemplate少样本学习模板ChatPromptTemplate对话式提示模板Chains链式层LLMChain最基本的模型调用链SequentialChain多个链的顺序执行TransformChain数据转换链Agents代理层Tool可调用的外部工具AgentExecutor代理执行器负责决策和工具调用Memory记忆层ConversationBufferMemory对话历史记忆VectorStoreRetrieverMemory向量存储记忆1.3 为什么选择 LangChain与直接调用 API 相比LangChain 提供了更完整的开发体验避免 prompt 工程中的模板代码标准化数据处理流程内置最佳实践和设计模式活跃的社区和持续更新2. 环境准备与版本兼容性2.1 基础环境要求本文示例基于以下环境但 LangChain 具有较好的跨平台兼容性操作系统Windows 10/11, macOS 10.15, Ubuntu 18.04Python 版本3.8-3.11推荐 3.9包管理pip 或 conda2.2 核心依赖安装创建新的 Python 虚拟环境后安装 LangChain 核心包# 创建并激活虚拟环境 python -m venv langchain-env source langchain-env/bin/activate # Linux/macOS # langchain-env\Scripts\activate # Windows # 安装 LangChain 核心包 pip install langchain # 安装社区扩展包含大量第三方集成 pip install langchain-community # 安装文本嵌入相关 pip install sentence-transformers # 安装向量数据库以 Chroma 为例 pip install chromadb # 安装可选工具包 pip install wikipedia2.3 版本兼容性注意事项LangChain 生态更新较快版本兼容性是常见坑点# 检查当前安装版本 pip show langchain langchain-community # 推荐版本组合2024年稳定组合 langchain0.1.0 langchain-community0.0.10 chromadb0.4.15 sentence-transformers2.2.2如果遇到版本冲突优先使用较新的稳定版本。常见错误如 prompt outputs failed validation 通常源于版本不匹配。2.4 API 密钥配置大部分 LLM 集成需要 API 密钥建议使用环境变量管理# 设置环境变量临时 export OPENAI_API_KEYyour-openai-key export ANTHROPIC_API_KEYyour-claude-key # 或在代码中配置 import os os.environ[OPENAI_API_KEY] your-openai-key3. Prompt 工程实战从基础到高级3.1 基础 PromptTemplate 使用PromptTemplate 是 LangChain 中最基础的组件用于创建可复用的提示词from langchain.prompts import PromptTemplate # 创建简单模板 template 请用{style}风格写一篇关于{topic}的短文字数限制在{word_count}字以内。 prompt_template PromptTemplate( input_variables[style, topic, word_count], templatetemplate ) # 填充模板 filled_prompt prompt_template.format( style幽默风趣, topic人工智能的未来, word_count300 ) print(filled_prompt)3.2 对话式 ChatPromptTemplate对于对话场景使用 ChatPromptTemplate 更符合 LLM 的消息格式from langchain.prompts import ChatPromptTemplate from langchain.schema import HumanMessage, SystemMessage, AIMessage # 创建对话模板 chat_template ChatPromptTemplate.from_messages([ (system, 你是一个专业的{role}请用{language}回答用户问题。), (human, 请问{question}) ]) # 生成对话提示 messages chat_template.format_messages( role技术顾问, language中文, question如何学习 LangChain ) for msg in messages: print(f{msg.type}: {msg.content})3.3 少样本学习模板FewShotPromptTemplate 让模型通过示例学习from langchain.prompts import FewShotPromptTemplate, PromptTemplate # 定义示例 examples [ { input: 苹果, output: 水果富含维生素C有助于增强免疫力 }, { input: 汽车, output: 交通工具使用内燃机或电动机驱动用于人员运输 } ] # 定义示例模板 example_template 输入: {input} 输出: {output} example_prompt PromptTemplate( input_variables[input, output], templateexample_template ) # 创建少样本模板 few_shot_prompt FewShotPromptTemplate( examplesexamples, example_promptexample_prompt, prefix请根据以下示例对给定的输入进行分类描述, suffix输入: {user_input}\n输出:, input_variables[user_input], example_separator\n\n ) result few_shot_prompt.format(user_input笔记本电脑) print(result)3.4 常见 Prompt 工程错误与修复错误1变量未定义# 错误示例 template 请分析{undefined_var}的影响 prompt_template PromptTemplate(templatetemplate) # 缺少 input_variables # 正确做法 prompt_template PromptTemplate( input_variables[undefined_var], templatetemplate )错误2消息格式错误# 错误system message 位置不正确 messages [ HumanMessage(content你好), SystemMessage(content你是助手) # system 应该在开头 ] # 正确顺序 messages [ SystemMessage(content你是助手), HumanMessage(content你好) ]4. RAG 系统构建从零搭建知识库4.1 RAG 核心原理RAGRetrieval-Augmented Generation通过以下流程增强 LLM 回答的准确性检索从知识库中查找与问题相关的文档片段增强将检索结果作为上下文提供给 LLM生成LLM 基于上下文生成更准确的回答4.2 文档加载与处理首先准备知识库文档from langchain.document_loaders import TextLoader, WebBaseLoader from langchain.text_splitter import RecursiveCharacterTextSplitter # 从文本文件加载 loader TextLoader(knowledge_base.txt) documents loader.load() # 从网页加载可选 # loader WebBaseLoader([https://example.com/docs]) # documents loader.load() # 文档分割 text_splitter RecursiveCharacterTextSplitter( chunk_size1000, # 每个块的大小 chunk_overlap200, # 块之间的重叠 length_functionlen ) docs text_splitter.split_documents(documents) print(f原始文档数: {len(documents)}) print(f分割后块数: {len(docs)})4.3 向量化与存储使用嵌入模型将文本转换为向量并存储from langchain.embeddings import HuggingFaceEmbeddings from langchain.vectorstores import Chroma # 初始化嵌入模型 embeddings HuggingFaceEmbeddings( model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ) # 创建向量数据库 vectorstore Chroma.from_documents( documentsdocs, embeddingembeddings, persist_directory./chroma_db # 持久化存储 ) # 持久化保存 vectorstore.persist()4.4 检索与问答链构建完整的 RAG 流水线from langchain.chains import RetrievalQA from langchain.llms import OpenAI # 初始化 LLM llm OpenAI(temperature0) # temperature0 减少随机性 # 创建检索器 retriever vectorstore.as_retriever( search_typesimilarity, search_kwargs{k: 3} # 返回最相关的3个文档 ) # 创建 RAG 链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 简单地将所有上下文塞入 prompt retrieverretriever, return_source_documentsTrue ) # 测试问答 question LangChain 的主要组件有哪些 result qa_chain({query: question}) print(f问题: {question}) print(f回答: {result[result]}) print(参考文档:) for i, doc in enumerate(result[source_documents]): print(f{i1}. {doc.page_content[:200]}...)4.5 RAG 性能优化技巧优化检索质量# 使用 MMR最大边际相关性提高多样性 retriever vectorstore.as_retriever( search_typemmr, search_kwargs{k: 5, fetch_k: 10} ) # 使用过滤器 retriever vectorstore.as_retriever( search_kwargs{k: 3, filter: {category: technical}} )优化 chunk 策略# 根据内容类型调整 chunk 大小 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 技术文档可以小一些 chunk_overlap100, separators[\n\n, \n, 。, , , ] # 中文友好分隔符 )5. Agent 开发让 LLM 学会使用工具5.1 Agent 核心概念Agent 是能够理解用户指令、决定执行步骤、使用工具完成任务的智能体。核心组件包括ToolsAgent 可以调用的外部函数Agent决策逻辑ReAct、Self-Ask 等策略AgentExecutor执行引擎处理工具调用和错误恢复5.2 基础工具定义首先定义 Agent 可用的工具from langchain.agents import tool from datetime import datetime import math tool def get_current_time(): 获取当前日期和时间 return datetime.now().strftime(%Y-%m-%d %H:%M:%S) tool def calculate_square_root(number: float): 计算数字的平方根 return math.sqrt(number) tool def search_wikipedia(query: str): 在维基百科中搜索内容 from langchain.utilities import WikipediaAPIWrapper wikipedia WikipediaAPIWrapper() return wikipedia.run(query)5.3 创建 ReAct Agent使用 ReActReasoning Acting策略构建智能体from langchain.agents import initialize_agent, AgentType from langchain.llms import OpenAI # 初始化 LLM llm OpenAI(temperature0) # 工具列表 tools [get_current_time, calculate_square_root, search_wikipedia] # 创建 Agent agent initialize_agent( toolstools, llmllm, agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, # 零样本 ReAct 策略 verboseTrue, # 显示详细执行过程 handle_parsing_errorsTrue # 处理解析错误 ) # 测试复杂任务 result agent.run(请先查询人工智能的最新发展然后计算16的平方根最后告诉我当前时间) print(result)5.4 自定义 Agent 工作流对于复杂任务可以自定义执行逻辑from langchain.agents import Tool, AgentExecutor from langchain.schema import SystemMessage from langchain.prompts import MessagesPlaceholder from langchain.agents.openai_functions_agent.base import OpenAIFunctionsAgent # 定义系统消息 system_message SystemMessage( content你是一个专业的助手擅长使用工具解决问题。请逐步思考并清晰解释你的推理过程。 ) # 创建自定义提示 prompt OpenAIFunctionsAgent.create_prompt( system_messagesystem_message, extra_prompt_messages[MessagesPlaceholder(variable_namechat_history)] ) # 创建 Agent agent OpenAIFunctionsAgent(llmllm, toolstools, promptprompt) # 创建执行器 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations3, # 限制最大迭代次数 early_stopping_methodgenerate # 提前停止策略 ) # 执行任务 result agent_executor.run(请分析机器学习的主要算法类型) print(result)5.5 Agent 高级特性记忆功能集成from langchain.memory import ConversationBufferMemory # 添加对话记忆 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue ) # 多轮对话测试 result1 agent_executor.run(什么是深度学习) result2 agent_executor.run(它和机器学习有什么关系) # 能记住上下文工具调用约束# 限制工具使用范围 from langchain.agents import Tool constrained_tools [ Tool( nameTimeCheck, funcget_current_time, description仅当用户询问时间相关问题时使用 ) ]6. 完整项目实战构建智能技术问答系统6.1 项目架构设计结合前面所学构建一个完整的技术问答系统RAG 知识库存储技术文档Agent 系统理解问题并选择最佳回答策略工具集成计算、搜索、时间查询等6.2 代码实现import os from langchain import LLMChain, PromptTemplate from langchain.agents import AgentExecutor, Tool, initialize_agent from langchain.embeddings import HuggingFaceEmbeddings from langchain.vectorstores import Chroma from langchain.chains import RetrievalQA from langchain.llms import OpenAI from langchain.memory import ConversationBufferMemory class TechnicalQASystem: def __init__(self, knowledge_base_path, openai_api_key): os.environ[OPENAI_API_KEY] openai_api_key # 初始化组件 self.llm OpenAI(temperature0) self.memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 构建 RAG 知识库 self.setup_knowledge_base(knowledge_base_path) # 构建工具集 self.setup_tools() # 创建 Agent self.setup_agent() def setup_knowledge_base(self, knowledge_path): 设置 RAG 知识库 # 文档加载和分割简化版 from langchain.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter loader TextLoader(knowledge_path) documents loader.load() text_splitter RecursiveCharacterTextSplitter( chunk_size1000, chunk_overlap200 ) docs text_splitter.split_documents(documents) # 向量化存储 embeddings HuggingFaceEmbeddings() self.vectorstore Chroma.from_documents(docs, embeddings) # 创建 QA 链 self.qa_chain RetrievalQA.from_chain_type( llmself.llm, chain_typestuff, retrieverself.vectorstore.as_retriever() ) def setup_tools(self): 设置工具集 tool def technical_qa(question: str): 回答技术相关问题基于知识库 return self.qa_chain.run(question) tool def general_search(query: str): 通用信息搜索 from langchain.utilities import GoogleSerperAPIWrapper search GoogleSerperAPIWrapper() return search.run(query) self.tools [technical_qa, general_search] def setup_agent(self): 设置 Agent self.agent initialize_agent( toolsself.tools, llmself.llm, agentAgentType.CHAT_CONVERSATIONAL_REACT_DESCRIPTION, memoryself.memory, verboseTrue, handle_parsing_errorsTrue ) def ask_question(self, question): 提问接口 try: response self.agent.run(question) return response except Exception as e: return f处理问题时出现错误: {str(e)} # 使用示例 if __name__ __main__: # 初始化系统需要准备 knowledge_base.txt qa_system TechnicalQASystem( knowledge_base_pathtechnical_docs.txt, openai_api_keyyour-api-key ) # 测试问答 questions [ LangChain 的 Chain 组件有什么作用, 最近人工智能领域有什么新进展, 请详细解释一下 RAG 的工作原理 ] for question in questions: print(fQ: {question}) answer qa_system.ask_question(question) print(fA: {answer}\n{-*50})6.3 系统优化建议性能优化使用异步处理提高并发性能实现缓存机制减少重复计算对向量数据库进行索引优化功能扩展添加多模态支持图像、音频集成更多专业工具代码执行、数据分析实现用户个性化记忆7. 常见问题与解决方案7.1 安装与配置问题问题1版本兼容性错误错误信息ModuleNotFoundError: No module named langchain.schema 解决方案统一版本使用 pip install langchain0.1.0 langchain-community0.0.10问题2API 密钥配置错误错误信息AuthenticationError: Incorrect API key provided 解决方案检查环境变量设置确保在代码执行前正确配置 API 密钥7.2 Prompt 工程问题问题3模板变量错误错误信息KeyError: variable_name 解决方案确保 PromptTemplate 的 input_variables 包含所有模板中使用的变量问题4消息格式错误错误信息api error: 400 failed to build prompt: system message must be at the beginning 解决方案确保消息顺序为 [SystemMessage, HumanMessage, AIMessage, ...]7.3 RAG 系统问题问题5检索效果差现象返回的文档与问题不相关 解决方案调整 chunk_size、尝试不同的嵌入模型、使用 MMR 检索策略问题6上下文长度超限现象prompt has no outputs 或上下文截断 解决方案减小 chunk_size、使用 map_reduce 或 refine 链类型7.4 Agent 开发问题问题7工具调用失败现象Agent 无法正确选择或使用工具 解决方案完善工具描述、添加示例、使用更详细的 Agent 类型问题8无限循环现象Agent 陷入重复的工具调用 解决方案设置 max_iterations 限制、实现超时机制8. 生产环境最佳实践8.1 代码组织规范模块化设计# 推荐结构 project/ ├── agents/ # Agent 定义 ├── chains/ # 自定义 Chain ├── tools/ # 工具函数 ├── vectorstores/ # 向量数据库管理 ├── config.py # 配置管理 └── main.py # 主程序配置管理# config.py import os from dataclasses import dataclass dataclass class Config: openai_api_key: str os.getenv(OPENAI_API_KEY) model_name: str gpt-3.5-turbo temperature: float 0.1 max_tokens: int 1000 # 使用配置 config Config()8.2 性能与稳定性错误处理与重试from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def safe_llm_call(prompt): try: return llm(prompt) except Exception as e: print(fLLM调用失败: {e}) raise异步处理import asyncio from langchain.llms import OpenAI async def process_questions_async(questions): llm OpenAI() tasks [llm.agenerate([q]) for q in questions] results await asyncio.gather(*tasks, return_exceptionsTrue) return results8.3 安全与合规输入验证def validate_input(user_input): # 检查长度 if len(user_input) 1000: raise ValueError(输入过长) # 检查敏感内容 sensitive_keywords [密码, 密钥, token] if any(keyword in user_input for keyword in sensitive_keywords): raise ValueError(输入包含敏感信息) return True数据隐私本地处理敏感数据避免不必要的 API 调用使用本地嵌入模型减少数据外传实现数据脱敏和匿名化通过这套完整的 LangChain 实战指南你应该已经掌握了从基础 Prompt 工程到复杂 Agent 开发的全流程技能。在实际项目中建议从小功能开始验证逐步构建复杂系统重点关注版本兼容性、错误处理和性能优化。