在构建基于大语言模型LLM的应用时你是否遇到过这样的困境模型本身知识有限无法回答专业问题或者想让模型执行复杂任务却不知如何让它调用外部工具面对网上零散的教程和快速迭代的框架版本从零搭建一个智能应用更是无从下手。本文将围绕 LangChain 1.3 这一主流框架为你系统梳理从基础概念到高级应用Agent、RAG、MCP、LangGraph的完整知识体系并提供可直接运行的代码示例。无论你是希望快速入门的新手还是寻求项目落地的开发者都能从中获得一套清晰、可复现的实战方案。1. LangChain 核心概念与生态全景在深入代码之前我们首先要理解 LangChain 究竟解决了什么问题以及其核心组件如何协同工作。1.1 LangChain 是什么LangChain 是一个用于开发由语言模型驱动的应用程序的框架。它的核心价值在于“连接”将大语言模型与外部数据源、计算工具以及记忆系统连接起来从而构建出功能远超单纯对话的、具备行动能力的智能应用。简单来说你可以把 LangChain 想象成一个“乐高积木”平台。LLM如 GPT、Claude、本地模型是核心的“动力引擎”而 LangChain 提供了标准化的“接口”和“连接件”让你可以轻松地为这个引擎装上“数据库”RAG、“机械臂”Agent 工具调用和“控制中枢”LangGraph 工作流。1.2 核心组件与本次学习路线LangChain 的生态庞大但我们可以聚焦于构建智能应用最关键的四个模块这也是本文的讲解主线LangChain Core框架的基础包含模型 I/O、提示模板、输出解析器等是与 LLM 直接交互的基石。RAG检索增强生成解决 LLM 知识陈旧、幻觉问题。通过从外部知识库如向量数据库检索相关信息并将其作为上下文提供给 LLM从而生成更准确、可靠的答案。Agent智能体赋予 LLM 使用工具如计算器、搜索引擎、API的能力。LLM 作为“大脑”根据用户问题自主规划、选择并调用工具最终整合结果。LangGraph用于构建复杂、有状态的多步骤工作流。它超越了简单的链式调用可以处理循环、分支和持久化状态是构建高级 Agent 和应用程序的利器。MCP模型上下文协议一个新兴的开放协议旨在标准化应用程序与各种“上下文源”如数据库、文件系统、API之间的交互方式。LangChain 正在集成 MCP未来能更方便地连接和管理工具。本文将按照“基础 - 检索 - 智能 - 编排”的递进顺序带你逐一攻克。2. 环境准备与项目初始化工欲善其事必先利其器。我们将创建一个干净的 Python 虚拟环境并安装必要的依赖。2.1 环境与版本说明本文示例基于以下环境不同版本可能存在细微差异核心逻辑保持一致。操作系统: macOS/Linux/Windows (WSL2 推荐)Python 版本: 3.10 或 3.11LangChain 版本: 0.1.3 (即常说的 LangChain 1.3)LLM: 使用 OpenAI GPT 系列模型作为示例同时会介绍接入本地模型如 Qwen的方法。向量数据库: 使用轻量级的Chroma。工具调用: 使用Tavily搜索引擎作为示例工具。重要提示LangChain 版本迭代很快本文内容基于langchain0.1.3和langchain-community0.0.10等配套包。建议使用虚拟环境管理依赖。2.2 创建项目并安装依赖首先创建项目目录并进入。mkdir langchain-tutorial cd langchain-tutorial python -m venv venv # 创建虚拟环境 # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate创建requirements.txt文件内容如下langchain0.1.3 langchain-community0.0.10 langchain-openai0.0.5 langchain-chroma0.0.1 chromadb0.4.22 tavily-python0.3.0 python-dotenv1.0.0 langgraph0.0.33执行安装命令pip install -r requirements.txt2.3 配置 API 密钥为了调用 OpenAI 和 Tavily 等服务需要配置 API 密钥。推荐使用.env文件管理避免密钥硬编码在代码中。在项目根目录创建.env文件。填入你的密钥请前往对应官网申请。# .env OPENAI_API_KEYsk-your-openai-api-key-here TAVILY_API_KEYyour-tavily-api-key-here在 Python 代码中使用dotenv加载。# config.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 OPENAI_API_KEY os.getenv(OPENAI_API_KEY) TAVILY_API_KEY os.getenv(TAVILY_API_KEY)3. LangChain 核心基础模型 I/O、提示与链让我们从最基础的与 LLM 交互开始。3.1 模型 I/O与 LLM 对话模型 I/O 是 LangChain 最基础的抽象主要包括ChatModel聊天模型和LLM补全模型。我们以ChatOpenAI为例。# basic_io.py from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage, SystemMessage # 初始化聊天模型指定模型名称和温度 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.7, api_keyOPENAI_API_KEY) # 最简单的调用单条消息 response llm.invoke(请用一句话介绍 LangChain。) print(简单调用:, response.content) # 结构化消息调用支持系统消息、用户消息等 messages [ SystemMessage(content你是一个专业的 Python 编程助手。), HumanMessage(content如何用 Python 反转一个字符串) ] response llm.invoke(messages) print(\n带系统消息的调用:, response.content)关键参数解释model: 指定使用的模型如gpt-4,gpt-3.5-turbo。temperature: 控制输出的随机性0.0 ~ 2.0。值越低输出越确定越高越有创造性。api_key: 传入密钥也可以通过环境变量设置。3.2 提示模板管理你的提示词硬编码提示词难以维护和复用。提示模板PromptTemplate可以帮助我们创建动态提示。# prompt_template.py from langchain_core.prompts import ChatPromptTemplate # 创建一个聊天提示模板 prompt_template ChatPromptTemplate.from_messages([ (system, 你是一位{role}。), (human, 请针对以下问题提供详细的解答{question}) ]) # 格式化模板传入变量 formatted_prompt prompt_template.format_messages(role机器学习专家, question什么是过拟合) print(格式化后的提示消息:, formatted_prompt) # 将模板与模型组合成链并调用 chain prompt_template | llm # 使用管道运算符 | 组合 response chain.invoke({role: 历史学家, question: 简述第二次世界大战的起因。}) print(\n链式调用结果:, response.content)为什么用模板它实现了提示逻辑与业务逻辑的分离便于进行 A/B 测试、批量处理和国际化。3.3 输出解析器获取结构化结果很多时候我们需要 LLM 输出结构化的数据如 JSON、列表而非纯文本。OutputParser就负责这件事。# output_parser.py from langchain_core.output_parsers import CommaSeparatedListOutputParser, JsonOutputParser from langchain_core.pydantic_v1 import BaseModel, Field # 示例1解析为逗号分隔的列表 list_parser CommaSeparatedListOutputParser() list_prompt ChatPromptTemplate.from_messages([ (human, 列出三种主要的{category}。\n{format_instructions}) ]) chain list_prompt | llm | list_parser result chain.invoke({ category: 编程语言, format_instructions: list_parser.get_format_instructions() }) print(列表解析结果:, result) # 示例2解析为 Pydantic 模型更强大 class Book(BaseModel): title: str Field(description书名) author: str Field(description作者) year: int Field(description出版年份) json_parser JsonOutputParser(pydantic_objectBook) json_prompt ChatPromptTemplate.from_messages([ (human, 根据描述生成一本书的信息{description}\n{format_instructions}) ]) chain json_prompt | llm | json_parser result chain.invoke({ description: 这是一本关于人工智能的经典教材作者是 Stuart Russell。, format_instructions: json_parser.get_format_instructions() }) print(JSON解析结果:, result)get_format_instructions()方法会自动生成指导 LLM 输出格式的文本这是保证解析成功的关键。4. RAG 实战构建你的专属知识库问答系统RAG 是当前克服 LLM 知识局限性的主流方案。其核心流程是索引 - 检索 - 增强 - 生成。4.1 文档加载与文本分割首先我们需要准备知识库文档并将其处理成适合检索的片段。# rag_indexing.py from langchain_community.document_loaders import TextLoader, WebBaseLoader from langchain_text_splitters import RecursiveCharacterTextSplitter # 方法1从本地文件加载 loader TextLoader(./sample_data/ai_news.txt, encodingutf-8) # 方法2从网页加载示例 # loader WebBaseLoader(https://example.com/article) documents loader.load() print(f加载了 {len(documents)} 个文档) print(第一个文档片段:, documents[0].page_content[:200]) # 文本分割将长文档切分为重叠的小块chunks text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块的最大字符数 chunk_overlap50, # 块之间的重叠字符数保持上下文连贯 separators[\n\n, \n, 。, , , , , ] # 分割符优先级 ) chunks text_splitter.split_documents(documents) print(f\n分割为 {len(chunks)} 个文本块)分割策略选择chunk_size和chunk_overlap需要根据文档类型和模型上下文长度调整。通用文本常用RecursiveCharacterTextSplitter。4.2 向量化与存储嵌入模型 向量数据库将文本块转换为向量嵌入并存入向量数据库以便相似性搜索。# rag_embedding.py from langchain_openai import OpenAIEmbeddings from langchain_chroma import Chroma # 初始化嵌入模型 embeddings OpenAIEmbeddings(modeltext-embedding-3-small, api_keyOPENAI_API_KEY) # 创建向量存储并持久化到本地目录 ./chroma_db vectorstore Chroma.from_documents( documentschunks, embeddingembeddings, persist_directory./chroma_db ) vectorstore.persist() # 显式保存到磁盘 print(向量数据库已创建并持久化。) # 测试检索查找与查询最相关的文本块 query 大语言模型的最新进展是什么 retrieved_docs vectorstore.similarity_search(query, k2) # 返回最相似的2个块 print(f\n针对查询 {query} 检索到的结果) for i, doc in enumerate(retrieved_docs): print(f\n--- 结果 {i1} ---) print(doc.page_content[:300])嵌入模型选择除了 OpenAI你也可以使用HuggingFaceEmbeddings等开源模型只需注意性能与精度的权衡。4.3 构建检索链并问答将检索器与 LLM 组合成一个完整的问答链。# rag_chain.py from langchain.chains import create_retrieval_chain from langchain.chains.combine_documents import create_stuff_documents_chain from langchain_core.prompts import ChatPromptTemplate # 1. 从磁盘加载已有的向量数据库 vectorstore Chroma(persist_directory./chroma_db, embedding_functionembeddings) retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 定义检索器每次取3个块 # 2. 定义处理检索结果的链 system_prompt 请仅根据以下提供的上下文信息来回答问题。如果上下文信息不足以回答问题请直接说“根据提供的信息我无法回答这个问题”。 不要使用你已有的知识。 上下文 {context} qa_prompt ChatPromptTemplate.from_messages([ (system, system_prompt), (human, {input}) ]) # 此链负责将检索到的文档context和问题input组合成最终提示 combine_docs_chain create_stuff_documents_chain(llm, qa_prompt) # 3. 创建完整的检索问答链 rag_chain create_retrieval_chain(retriever, combine_docs_chain) # 4. 进行问答 result rag_chain.invoke({input: 文档中提到了哪些AI公司}) print(问题:, result[input]) print(\n答案:, result[answer]) print(\n--- 使用的上下文 ---) for doc in result[context]: print(doc.page_content[:200])至此一个最基本的 RAG 问答系统就完成了。它能够从你的专属文档中寻找答案极大减少了 LLM 的“幻觉”。5. Agent 实战打造能使用工具的智能体Agent 的核心思想是让 LLM 学会调用工具。其运行遵循“感知 - 规划 - 行动 - 观察”的循环。5.1 定义工具工具是 Agent 可以调用的函数。LangChain 提供了装饰器来轻松创建工具。# agent_tools.py from langchain.agents import tool from datetime import datetime import math tool def get_current_time(tz: str Asia/Shanghai) - str: 获取指定时区的当前时间。 # 简化示例实际应使用pytz等库 now datetime.now() return f当前时间{tz}是{now.strftime(%Y-%m-%d %H:%M:%S)} tool def calculate_circle_area(radius: float) - str: 计算圆的面积。参数 radius 是圆的半径。 area math.pi * radius * radius return f半径为 {radius} 的圆的面积是{area:.2f} # 使用 Tavily 搜索工具需要 API Key from langchain_community.tools.tavily_search import TavilySearchResults search_tool TavilySearchResults(api_keyTAVILY_API_KEY, max_results2) # 工具列表 tools [get_current_time, calculate_circle_area, search_tool]5.2 创建 Agent 执行器我们将使用 LangChain 提供的create_react_agent来创建一个基于 ReAct 框架的 Agent。# agent_executor.py from langchain.agents import create_react_agent, AgentExecutor from langchain_core.prompts import PromptTemplate # ReAct 代理的提示模板LangChain 有内置这里为演示自定义 react_prompt PromptTemplate.from_template( 你是一个有帮助的助手可以访问以下工具{tools}。 请严格按照以下格式回答 思考你需要先思考当前情况决定是否需要使用工具 行动你要使用的工具名称必须是[{tool_names}]中的一个 行动输入工具的输入参数 观察工具返回的结果 ...这个“思考/行动/行动输入/观察”循环可以重复多次 最终答案当你有了最终答案时用它来回答用户最初的问题 开始 问题{input} 思考{agent_scratchpad} ) # 创建 Agent agent create_react_agent(llm, tools, react_prompt) # 创建执行器它负责运行循环 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 执行一个需要多步推理和工具调用的任务 result agent_executor.invoke({ input: 先搜索一下 LangChain 的最新版本是什么然后告诉我如果我想计算半径为5的圆的面积结果是多少最后告诉我现在上海的时间。 }) print(\n最终输出:, result[output])运行上述代码你会看到verboseTrue模式下 Agent 详细的思考过程Thought、行动Action和观察Observation这正是 ReAct 框架的体现。5.3 Agent 与 LLM Function Calling 的区别这是一个常见问题。本质上它们目的相同但实现层级不同LLM Function Calling是底层模型如 GPT-4原生支持的一种能力模型输出结构化的函数调用请求名称和参数。它更底层速度通常受模型本身推理速度和网络延迟影响。LangChain Agent/Tool Calling是一个更高层次的框架抽象。它可以利用 LLM Function Calling也可以使用其他方式如 ReAct 提示工程来让模型决定使用工具。LangChain 工具调用的速度主要受LLM 调用延迟、工具本身执行时间以及Agent 规划步骤数的影响。优化方法包括选择更快的模型、简化工具、优化提示以减少不必要的思考步骤。6. LangGraph 实战编排复杂多步骤工作流当任务需要循环、分支或持久化状态时简单的链或 Agent 就显得力不从心。LangGraph 通过“图”的概念来定义和运行这种工作流。6.1 理解 State 和 NodeLangGraph 的核心是两个概念State一个共享的、可修改的状态字典在所有节点间传递。Node一个函数接收 State执行操作如调用 LLM、工具并返回更新后的 State。Edge定义节点之间的流转条件。6.2 构建一个审批工作流我们模拟一个简单的文章审核流程生成 - 审核 - 根据审核结果决定是“发布”还是“修改”。# langgraph_workflow.py from typing import Literal from langgraph.graph import StateGraph, END from langchain_core.messages import HumanMessage, SystemMessage import json # 1. 定义状态结构 class WorkflowState(dict): 工作流状态 topic: str draft: str None feedback: str None decision: Literal[approve, revise, reject] None final_content: str None # 2. 定义各个节点函数 def generate_draft(state: WorkflowState): 节点1生成草稿 print(f\n 节点 [生成草稿] 执行主题{state[topic]}) prompt f请围绕{state[topic]}写一篇简短的技术博客草稿200字以内。 messages [HumanMessage(contentprompt)] response llm.invoke(messages) state[draft] response.content print(f草稿生成完毕。) return state def review_draft(state: WorkflowState): 节点2审核草稿 print(f\n 节点 [审核草稿] 执行) prompt f你是一个严格的审核编辑。请审核以下草稿并给出 1. 简要评价好/一般/差。 2. 具体的修改建议。 3. 你的决定approve通过、revise需要修改、reject拒绝。 草稿内容 {state[draft]} messages [HumanMessage(contentprompt)] response llm.invoke(messages) # 简单解析响应实际应用中应使用输出解析器 content response.content state[feedback] content if approve in content.lower(): state[decision] approve elif reject in content.lower(): state[decision] reject else: state[decision] revise print(f审核决定{state[decision]}) return state def publish_article(state: WorkflowState): 节点3发布文章 print(f\n 节点 [发布文章] 执行) state[final_content] state[draft] \n\n---\n*已发布* return state def revise_draft(state: WorkflowState): 节点4修改文章 print(f\n 节点 [修改文章] 执行) prompt f根据审核反馈修改以下草稿。 反馈{state[feedback]} 原始草稿{state[draft]} 请输出修改后的完整草稿。 messages [HumanMessage(contentprompt)] response llm.invoke(messages) state[draft] response.content print(草稿已修改将返回重新审核。) return state # 3. 定义条件路由函数 def decide_route(state: WorkflowState) - str: 根据审核决定路由到下一个节点 decision state[decision] if decision approve: return publish elif decision revise: return revise else: # reject return END # 结束流程 # 4. 构建图 workflow StateGraph(WorkflowState) # 添加节点 workflow.add_node(generate, generate_draft) workflow.add_node(review, review_draft) workflow.add_node(publish, publish_article) workflow.add_node(revise, revise_draft) # 设置入口点 workflow.set_entry_point(generate) # 添加边连接节点 workflow.add_edge(generate, review) # 从 review 节点出来根据条件路由 workflow.add_conditional_edges( review, decide_route, # 条件函数 { publish: publish, # 如果返回 “publish” 跳转到 publish 节点 revise: revise, # 如果返回 “revise” 跳转到 revise 节点 END: END # 如果返回 END 直接结束 } ) workflow.add_edge(publish, END) # 发布后结束 workflow.add_edge(revise, review) # 修改后返回审核节点形成循环 # 编译图 app workflow.compile() # 5. 执行工作流 initial_state WorkflowState(topicLangGraph 的使用场景) final_state app.invoke(initial_state) print(\n *50) print(工作流执行完毕) print(f最终状态: {json.dumps(final_state, indent2, ensure_asciiFalse)})这个例子展示了 LangGraph 如何优雅地处理循环修改后重新审核和分支通过/修改/拒绝。对于构建复杂的 AI Agent 或业务流程自动化这是极其强大的工具。7. 进阶话题与最佳实践掌握了核心组件后以下实践能帮助你构建更健壮、高效的应用。7.1 接入本地/开源模型除了 OpenAILangChain 可以轻松接入百川、通义千问等模型。# custom_llm.py from langchain_community.llms import Tongyi from langchain_openai import ChatOpenAI import os # 示例使用通义千问 # 需要设置环境变量 DASHSCOPE_API_KEY llm_qwen Tongyi(modelqwen-max, dashscope_api_keyos.getenv(DASHSCOPE_API_KEY)) # 示例使用 OpenAI 兼容的本地模型如使用 Ollama from langchain_community.llms import Ollama llm_local Ollama(modelllama3, base_urlhttp://localhost:11434) # 之后像使用 ChatOpenAI 一样使用它们 # chain prompt | llm_qwen7.2 RAG 优化技巧检索优化多向量检索器同时存储文档的摘要和块提高检索精度。重排序使用更精细的模型如BAAI/bge-reranker-large对初步检索结果进行重排提升 Top-K 结果的相关性。混合搜索结合关键词搜索如 BM25和向量搜索兼顾语义和精确匹配。提示优化在 RAG 提示中加入指令要求模型引用来源、或对不确定信息说“不知道”。后处理对模型生成的答案进行事实性检查或格式规整。7.3 Agent 设计原则工具设计要精准每个工具功能应单一明确描述清晰参数结构化。控制思考深度通过max_iterations和max_execution_time参数限制 Agent 运行步数防止死循环。提供充足示例在系统提示中提供少量工具调用的示例Few-shot能显著提升 Agent 使用工具的准确性。处理解析错误务必设置handle_parsing_errorsTrue并设计降级逻辑如让用户重试。7.4 LangGraph 生产级考量状态持久化使用Checkpointer将图的状态保存到数据库实现工作流的暂停、恢复和追溯。并发与流式LangGraph 支持并发执行节点和流式输出中间结果适合构建实时响应的复杂应用。子图将复杂的图分解为多个子图提高可维护性和复用性。8. 常见问题与排查清单在实际开发中你可能会遇到以下问题问题现象可能原因排查思路与解决方案ModuleNotFoundError: No module named ‘langchain_xxx‘依赖未安装或版本不匹配。1. 检查requirements.txt和实际安装的包 (pip list)。2. LangChain 0.1.x 将很多组件移到了langchain-community确保已安装。3. 使用pip install langchain[all]安装所有可选依赖不推荐生产环境。LLM 调用超时或无响应网络问题、API 密钥错误、模型服务不可用。1. 检查网络连接和代理设置。2. 验证 API 密钥是否正确且有效。3. 查看对应云服务商的状态页面。4. 增加timeout参数。RAG 检索结果不相关文本分割策略不当、嵌入模型不匹配、检索参数k不合适。1. 调整chunk_size和chunk_overlap。2. 尝试不同的嵌入模型。3. 调整检索器的search_type如mmr最大边际相关性和k值。4. 清洗和预处理源文档。Agent 陷入循环或调用错误工具提示指令不清晰、工具描述模糊、缺少示例。1. 优化 Agent 的提示词明确步骤和格式。2. 为每个工具编写清晰、包含参数示例的描述。3. 在系统提示中加入工具调用的成功案例。4. 设置max_iterations。LangGraph 状态更新不符合预期节点函数没有正确返回更新后的状态或状态键名错误。1. 确保每个节点函数都return state。2. 使用类型提示如WorkflowState来避免键名拼写错误。3. 打开详细日志检查每个节点输入/输出的状态。处理中文时效果不佳默认分词或嵌入模型对中文支持不好。1. 使用针对中文优化的嵌入模型如BAAI/bge-small-zh。2. 在文本分割时确保中文标点如。在分隔符列表中。3. 尝试使用中文优化的 LLM。本文从 LangChain 的基础概念出发逐步深入到 RAG、Agent 和 LangGraph 三大核心应用提供了从环境搭建到代码实战的完整路径。关键在于理解每个组件的职责LangChain Core 是粘合剂RAG 赋予知识Agent 赋予行动力LangGraph 则负责编排复杂行动。真正的掌握离不开动手实践建议你从改造文中的示例开始将其应用到自己的数据或业务场景中例如用你的技术文档构建一个 RAG 问答机器人或者用 Agent 自动化一个日常的工作流程。在遇到问题时多查阅官方文档和社区讨论LangChain 生态正在快速发展保持学习才能跟上最佳实践。