如果你刚接触大语言模型LLM应用开发听到“LangChain”这个词大概率会有点懵。它看起来不像一个具体的工具更像一个概念集合。简单来说LangChain 是一个用于构建由大语言模型驱动的应用程序的框架。它的核心价值不是提供一个开箱即用的成品应用而是帮你把模型调用、外部数据、记忆、工具使用、逻辑流程这些“积木”标准化、模块化让你能更高效、更稳定地搭建出属于自己的智能应用。很多人一开始会误解以为 LangChain 是一个“更聪明的模型”或者一个“对话界面”。其实不是。你可以把它想象成一个“乐高工具箱”和“搭建说明书”。模型比如 GPT-4、Claude、本地部署的 Llama是乐高积木块而 LangChain 提供了各种标准化的连接器比如怎么读取 PDF、怎么连接网络搜索、组装逻辑比如先做什么后做什么和胶水代码让你能把这些积木块和外部能力数据库、搜索引擎、计算器按照你想要的方式拼装起来最终做成一个机器人、一辆车或一座城堡。所以这篇文章不会只停留在概念介绍。我会以一个多年一线开发者的视角带你拆解 LangChain 到底解决了什么实际问题它的核心“积木”有哪些以及更重要的是在什么情况下你应该用它什么情况下可能直接调用模型 API 更简单。我们直接从搭建一个能“联网搜索并总结”的问答机器人开始把每个环节的配置、代码和踩坑点都过一遍。1. 先搞明白LangChain 到底在解决哪类开发痛点在直接使用大模型 API比如 OpenAI 的接口时你很快会遇到几个典型的工程化难题上下文长度限制模型一次能处理的文本有上限例如 4K、8K、128K tokens。如果你的知识库文档有 100 页根本无法一次性全部塞给模型。“模型失忆”问题标准的 API 调用是无状态的。你问“我上一句话说了什么”模型根本不知道因为它只看到当前这次请求的输入。需要连接外部数据和工具模型的知识有截止日期也不会算数、查数据库。你想让模型回答“今天某支股票价格如何”或者“帮我总结我昨天提交的工单”就需要先获取实时数据或内部数据再交给模型处理。复杂流程编排一个完整的应用可能包含多步判断。例如用户问题 - 判断是否需要搜索 - 如果需要则执行搜索并获取结果 - 将搜索结果和原始问题组合成新的提示词 - 调用模型生成答案 - 可能还需要根据答案再触发另一个动作。用原生 API 写这些 if-else 和状态管理代码会很快变得混乱。LangChain 的切入点就是把这些难题抽象成标准的、可复用的组件。它提供了以下几大类核心“积木”Models模型不止是聊天模型LLMs还包括文本嵌入模型Embedding Models用于将文本转化为向量和提示词模型。它统一了不同厂商OpenAI、Anthropic、Cohere或本地模型通过 Hugging Face的调用接口。Prompts提示词管理提示模板支持变量插入、少量示例few-shot等让你不用在代码里拼接字符串。Indexes索引用于处理外部文档。核心是“检索”功能也就是从大量文档中快速找到与问题相关的片段。这通常结合文本分割、向量化和向量数据库来实现。Memory记忆管理对话或应用的状态。可以是简单的缓存上一次对话也可以是更复杂的总结性记忆或基于向量的记忆存储。Chains链这是 LangChain 的灵魂。一个 Chain 将多个组件模型、提示词、工具等按特定顺序链接起来。LLMChain是最基础的链提示词 模型还有SequentialChain顺序执行多个链、RouterChain根据条件选择不同链等。Agents智能体这是更高级的“链”。智能体配备了一个或多个“工具”如搜索、计算、查数据库并且由模型自己决定在何时、使用哪个工具形成一个“思考-行动-观察”的循环直到完成任务。理解了这些抽象你就知道 LangChain 不是一个“黑盒魔法”而是一套帮助你组织代码、应对复杂性的工程框架。它的学习曲线正在于此你需要理解这些概念并学会如何将它们组合起来。2. 环境准备与核心概念落地从安装到第一个 Chain理论说再多不如跑一行代码。我们从一个最简单的例子开始感受一下 LangChain 的“手感”。2.1 基础环境搭建首先确保你有一个 Python 环境建议 3.8 以上。然后安装 LangChain。注意LangChain 是一个庞大的项目为了保持轻量它按功能拆分了多个包。最核心的是pip install langchain如果你要使用 OpenAI 的模型还需要安装 OpenAI 的 SDK 并设置你的 API Keypip install openai然后在代码中或环境变量中设置OPENAI_API_KEY。强烈建议使用环境变量避免将密钥硬编码在代码中# 在终端中设置临时 export OPENAI_API_KEYyour-api-key-here# 或者在 Python 代码中设置不推荐用于生产 import os os.environ[OPENAI_API_KEY] your-api-key-here2.2 构建第一个链理解LLM和PromptTemplate我们来创建一个最简单的链根据公司名生成一句宣传标语。from langchain_openai import ChatOpenAI # 注意新版本推荐从 langchain_openai 导入 from langchain_core.prompts import ChatPromptTemplate # 1. 初始化模型。temperature 控制创造性0.0 更确定1.0 更随机。 # model_name 可以是 gpt-3.5-turbo, gpt-4 等。 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.7) # 2. 创建提示词模板。{company} 是一个占位符变量。 prompt_template ChatPromptTemplate.from_messages([ (system, 你是一个擅长创作宣传口号的专家。), (user, 为这家公司想一句宣传标语{company}) ]) # 3. 将模板和模型组合成一个最基础的链 from langchain.chains import LLMChain chain LLMChain(llmllm, promptprompt_template) # 4. 运行链传入变量 result chain.invoke({company: 星辰科技}) print(result[text]) # 可能的输出“星辰科技点亮未来智慧生活”这个例子虽然简单但体现了 LangChain 的核心模式定义组件模型、提示词然后用链Chain把它们组装起来并执行。invoke方法是新版本LangChain 0.1.0推荐的运行方式。为什么不用直接调用 API在这个简单例子中优势不明显。但想象一下如果你的提示词非常复杂包含多个系统指令、用户示例和动态变量用PromptTemplate管理会比手动拼接字符串清晰、安全得多。而且LLMChain自动处理了调用格式和结果解析。2.3 连接外部数据体验RetrievalChain检索链这才是 LangChain 的“重头戏”。我们模拟一个常见场景你有一个产品说明书PDF/TXT想让模型根据这份文档来回答问题而不是依靠它自身的知识。这个过程通常分为三步加载文档 - 处理并索引文档 - 检索并生成答案。首先安装处理文档所需的包pip install langchain-community pypdf sentence-transformers chromadb # langchain-community: 社区维护的第三方集成 # pypdf: 用于读取 PDF 文件 # sentence-transformers: 用于生成文本向量Embedding # chromadb: 一个轻量级向量数据库我们使用本地 Embedding 模型all-MiniLM-L6-v2和 Chroma 向量数据库来演示这样不需要额外的 API 密钥。import os from langchain_community.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA from langchain_openai import ChatOpenAI # 假设我们有一个 product_manual.txt 文件 file_path “product_manual.txt” # 1. 加载文档 loader TextLoader(file_path, encoding“utf-8”) documents loader.load() # 2. 分割文本。模型上下文有限必须把长文档切分成小块。 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块大约500字符 chunk_overlap50 # 块之间重叠50字符避免语义被切断 ) texts text_splitter.split_documents(documents) print(f“将文档切分成了 {len(texts)} 个文本块”) # 3. 创建向量存储索引 # 使用本地 Embedding 模型 embeddings HuggingFaceEmbeddings(model_name“all-MiniLM-L6-v2”) # 将文本块转换为向量并存入 ChromaDB vectorstore Chroma.from_documents(documentstexts, embeddingembeddings, persist_directory“./chroma_db”) # persist_directory 指定存储位置下次可以直接加载无需重新生成向量 # 4. 将向量存储转换为检索器 retriever vectorstore.as_retriever(search_kwargs{“k”: 3}) # 检索最相关的3个文本块 # 5. 创建检索问答链 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) qa_chain RetrievalQA.from_chain_type( llmllm, chain_type“stuff”, # 最简单的方式将检索到的所有文档内容“塞”进提示词 retrieverretriever, return_source_documentsTrue # 返回参考来源便于验证 ) # 6. 提问 question “这款产品的主要特性是什么” result qa_chain.invoke({“query”: question}) print(“答案”, result[“result”]) print(“\n参考来源”) for doc in result[“source_documents”]: print(f“- {doc.page_content[:200]}...”) # 打印前200字符关键点解析文本分割Text Splitting这是文档问答质量的关键。分割得太碎语义不完整分割得太大可能超过上下文。RecursiveCharacterTextSplitter是常用选择它尝试按字符递归分割尽量保持段落完整性。Embedding向量化将文本转换为数学向量语义相似的文本向量距离也近。这是实现“模糊查找”的基础。向量数据库存储向量并提供高效的相似性搜索检索功能。Chroma 是轻量级选择生产环境可能会用 Weaviate、Pinecone、Qdrant 等。检索器Retriever封装了从向量库中根据问题查找相关文本块的操作。chain_type“stuff”这是最简单的处理方式把检索到的所有文本块合并后一次性发给模型。如果检索到的内容总长度可能超过模型上下文就需要用“map_reduce”、“refine”等更复杂但能处理长文本的链类型。通过这个流程你就构建了一个最基本的“私有知识库问答系统”。LangChain 的价值在这里凸显它把加载、分割、向量化、检索、提示词组装、模型调用这一整套复杂流程用几个高级组件封装起来你只需要配置参数而不用从头实现向量搜索或上下文管理逻辑。3. 进阶能力智能体Agents与工具Tools实战如果说 Chains 是预先编排好的工作流那么 Agents 就是赋予模型“自主决策”能力让它能根据你的目标自行决定调用哪些工具。一个经典场景是让模型回答“今天北京天气怎么样用摄氏度表示”。模型自己不知道天气但它可以学会调用一个“天气查询工具”。3.1 使用内置工具联网搜索我们使用 LangChain 社区提供的SerpAPI工具一个搜索引擎 API来演示。你需要先注册 SerpAPI 获取 API Key。pip install google-search-resultsimport os from langchain_openai import ChatOpenAI from langchain.agents import initialize_agent, AgentType from langchain.agents import load_tools # 设置 API Keys os.environ[“OPENAI_API_KEY”] “your-openai-key” os.environ[“SERPAPI_API_KEY”] “your-serpapi-key” # 初始化一个能力较强的模型Agent 需要模型有一定的推理和规划能力 llm ChatOpenAI(model“gpt-4”, temperature0) # 加载工具集。“serpapi” 是搜索引擎工具“llm-math” 是计算工具 tools load_tools([“serpapi”, “llm-math”], llmllm) # 初始化智能体 # AgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION 适合聊天模型使用 ReAct 推理框架 agent initialize_agent( tools, llm, agentAgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION, verboseTrue, # 开启详细日志可以看到模型的“思考过程” handle_parsing_errorsTrue # 优雅处理解析错误 ) # 提问一个需要结合搜索和计算的问题 question “苹果公司Apple Inc.最新的市值是多少如果我用它市值的 1% 来购买最新款 iPhone大概能买多少部假设最新款 iPhone 单价 1000 美元” result agent.invoke(question) print(“\n最终答案”, result[“output”])运行上述代码当verboseTrue时你会在控制台看到类似以下的思考过程Thought: 用户需要苹果公司的最新市值我需要搜索来获取这个信息。 Action: Search Action Input: “Apple Inc. latest market capitalization” Observation: [搜索引擎返回的结果例如 “Apple market cap is $2.8 trillion as of April 2024”] Thought: 我得到了苹果的市值大约是 2.8 万亿美元。现在需要计算其 1% 是多少然后除以 1000 美元。 Action: Calculator Action Input: (2.8 * 10^12) * 0.01 / 1000 Observation: 28000000 Thought: 我计算得出结果是 28,000,000。 Final Answer: 苹果公司最新市值约 2.8 万亿美元。其 1% 约为 280 亿美元按每部 iPhone 1000 美元计算大约可以购买 2800 万部。这就是智能体的强大之处模型自己规划了步骤先搜索再计算并正确选择了工具。你不需要写if “市值” in question: then search()这样的硬编码逻辑。模型根据工具的描述description和你的问题动态决定行动方案。3.2 创建自定义工具很多时候你需要连接内部系统比如查询数据库、调用内部 API。LangChain 让你可以轻松创建自定义工具。from langchain.tools import tool from datetime import datetime tool def get_current_time(format: str “%Y-%m-%d %H:%M:%S”) - str: “”“获取当前的系统时间。输入参数 format 是时间格式字符串默认为 ‘年-月-日 时:分:秒’。”“” current_time datetime.now().strftime(format) return current_time # 假设还有一个查询用户订单的工具这里用模拟函数 tool def lookup_user_order(user_id: str) - str: “”“根据用户ID查询其最近一笔订单的状态。输入应为用户ID字符串。”“” # 这里应该是真实的数据库查询逻辑我们模拟返回 order_status_map {“user123”: “已发货”, “user456”: “待付款”} return order_status_map.get(user_id, “未找到该用户订单”) # 将自定义工具和之前的工具一起加载 from langchain.agents import initialize_agent, AgentType from langchain_openai import ChatOpenAI llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) tools [get_current_time, lookup_user_order] # 也可以和 load_tools 的结果合并 agent initialize_agent( tools, llm, agentAgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION, verboseTrue, ) # 现在可以问更复杂的问题了 result agent.invoke(“现在是什么时间另外请查一下用户 user123 的订单状态。”) print(result[“output”])关键点使用tool装饰器并写好工具函数的文档字符串docstring。智能体会根据这个描述来决定是否以及如何使用该工具。输入参数的类型提示如str也很重要。4. 生产环境考量何时用 LangChain有哪些坑LangChain 功能强大但并不意味着所有 LLM 应用项目都要用它。它的抽象带来便利的同时也引入了复杂性和学习成本。4.1 适用场景与不适用场景强烈建议使用 LangChain 的场景快速构建复杂原型当你需要快速验证一个涉及多步推理、工具调用或复杂文档处理的创意时LangChain 的组件能极大节省时间。构建基于私有知识的问答系统它的RetrievalChain及相关生态文档加载器、向量库集成是目前最成熟的方案之一。需要智能体Agent能力当你的应用逻辑难以预先固定需要模型自主决定调用哪些外部工具或 API 时。团队协作与代码维护当项目有多人参与时使用统一的框架和模式有利于代码理解和维护。可能不需要 LangChain直接调用 API 更简单的场景简单的对话或文本生成只需要调用一次模型 API没有复杂逻辑。对延迟和开销极其敏感LangChain 的抽象层会带来轻微的性能开销和额外的依赖。对于超高并发、超低延迟的简单服务直接调用模型 SDK 可能更优。功能极其定制化如果你的应用流程与 LangChain 的标准组件模式差异巨大强行套用可能不如自己从头编写更清晰。学习初期为了理解底层原理先直接用原始 API 实现几次再对比使用 LangChain会理解更深。4.2 常见“坑”与排查指南在实际使用中你可能会遇到以下问题1. 版本兼容性与 API 变动LangChain 版本更新较快尤其是从 0.0.x 到 0.1.x 有较大变动。很多旧教程的导入方式如from langchain.llms import OpenAI在新版本中已废弃。排查始终以 官方文档 为准。安装后首先检查版本pip show langchain。遇到ImportError先去文档查最新的导入路径。建议在新项目中使用langchain0.1.0并主要参考langchain-*的独立包如langchain-openai,langchain-community。2. 提示词Prompt效果不佳LangChain 负责组装流程但提示词的质量最终决定模型输出。链Chain或智能体Agent效果不好首先怀疑提示词。排查打开verboseTrue查看链或智能体实际发送给模型的完整提示词是什么。检查系统指令是否清晰用户问题格式是否正确上下文是否被正确插入。建议在 LangSmithLangChain 官方调试平台中跟踪和测试你的提示词。对于复杂链可以拆解成小步骤单独测试。3. 检索Retrieval质量差文档问答回答不准通常是检索环节的问题而不是模型问题。排查顺序文本分割chunk_size是否合适太大可能包含无关信息太小可能丢失关键上下文。尝试调整大小和重叠度。Embedding 模型不同的 Embedding 模型对中文、专业术语的支持差异很大。all-MiniLM-L6-v2是通用英文模型中文场景可考虑text2vec、m3e等。检索策略search_kwargs{“k”: 3}中的k值是否合理可以尝试增大。检索方法除了相似性搜索similarity_search还可以尝试最大边际相关性MMR来平衡相关性和多样性。原始文档质量垃圾进垃圾出。确保源文档清晰、格式规整。4. 智能体Agent陷入循环或调用错误工具这是 Agent 开发中最常见的问题。排查务必开启verboseTrue观察模型的“思考Thought”过程。它是否误解了工具描述是否在无关步骤上循环建议优化工具描述工具函数的文档字符串要极其精确说明输入输出格式和适用场景。选择更强的基础模型Agent 非常依赖模型的推理和规划能力。gpt-3.5-turbo可能表现不稳定优先使用gpt-4或claude-3系列。设置超时和最大步数使用max_iterations和max_execution_time参数防止无限循环。提供更详细的系统提示在初始化 Agent 时可以通过agent_kwargs传入定制的系统提示约束其行为。5. 成本与性能失控在链或智能体中一次用户查询可能触发多次模型调用如 Agent 的每一步思考都是一次调用和外部 API 调用如搜索。建议记录和监控使用 LangSmith 或自定义日志记录每次请求的 token 消耗、调用次数和耗时。设置预算和限制在工具调用或链层面设置速率限制和费用上限。缓存对频繁重复的查询或 Embedding 结果实施缓存。4.3 部署与规模化建议对于学习原型在 Jupyter Notebook 或脚本中运行即可。但要部署为服务需要考虑异步支持LangChain 支持异步调用ainvoke,astream对于 Web 服务至关重要能提高并发处理能力。状态管理对于多轮对话需要将ConversationBufferMemory等记忆组件与用户会话 ID 绑定并持久化到数据库如 Redis而不是放在内存里。向量数据库选型Chroma 适合原型和中小数据量。生产环境应考虑支持分布式、持久化、高性能的向量数据库如 Weaviate、Qdrant、Pinecone云服务或 PGVector基于 PostgreSQL。模块化设计不要把所有代码写在一个巨型链里。将不同的功能链如检索链、总结链、分类链定义为独立的组件通过更上层的路由逻辑来调用这样更易于测试和维护。5. 总结把 LangChain 当作高效脚手架而非黑盒魔法经过上面的拆解你应该对 LangChain 有了更立体的认识。它不是一个“自动生成应用”的神器而是一个强大的、但需要你清晰架构思维的脚手架。我的核心建议是从问题出发而不是从技术出发先明确你要构建的应用核心流程是什么是简单问答、文档总结、数据查询还是自主规划再判断是否需要以及需要使用 LangChain 的哪些组件。分层学习和实践先掌握Models、Prompts和基础LLMChain。然后攻克Indexes和RetrievalQA这是实用性最强的部分。最后再研究Agents和自定义工具。重视提示词工程和评估LangChain 解决了流程问题但提示词的质量、检索的准确性、工具描述的清晰度这些仍然需要你精心设计和反复调试。结合 LangSmith 进行跟踪和评估。关注抽象背后的原理理解它为什么要把流程拆成链为什么需要向量检索Agent 的 ReAct 框架是如何工作的。这能帮助你在出问题时快速定位是框架问题、配置问题还是你自己的逻辑问题。对于刚入门的开发者可能会觉得 LangChain 概念繁多有点“重”。这很正常。它的设计目标本就是应对复杂场景。如果你的需求很简单直接调用模型 API 是完全合理的选择。但当你开始面对“长文档处理”、“多工具协调”、“动态决策流程”这些挑战时你会发现在 LangChain 的体系下工作远比从零造轮子要高效和稳健得多。最终把它当成一个帮你组织代码、提供最佳实践套件的伙伴而不是一个必须遵循的教条。理解其设计思想熟练运用其核心模块你就能在 LLM 应用开发的路上走得更快、更稳。
LangChain框架解析：从核心概念到实战应用，构建高效LLM应用开发
发布时间：2026/7/22 7:00:55
如果你刚接触大语言模型LLM应用开发听到“LangChain”这个词大概率会有点懵。它看起来不像一个具体的工具更像一个概念集合。简单来说LangChain 是一个用于构建由大语言模型驱动的应用程序的框架。它的核心价值不是提供一个开箱即用的成品应用而是帮你把模型调用、外部数据、记忆、工具使用、逻辑流程这些“积木”标准化、模块化让你能更高效、更稳定地搭建出属于自己的智能应用。很多人一开始会误解以为 LangChain 是一个“更聪明的模型”或者一个“对话界面”。其实不是。你可以把它想象成一个“乐高工具箱”和“搭建说明书”。模型比如 GPT-4、Claude、本地部署的 Llama是乐高积木块而 LangChain 提供了各种标准化的连接器比如怎么读取 PDF、怎么连接网络搜索、组装逻辑比如先做什么后做什么和胶水代码让你能把这些积木块和外部能力数据库、搜索引擎、计算器按照你想要的方式拼装起来最终做成一个机器人、一辆车或一座城堡。所以这篇文章不会只停留在概念介绍。我会以一个多年一线开发者的视角带你拆解 LangChain 到底解决了什么实际问题它的核心“积木”有哪些以及更重要的是在什么情况下你应该用它什么情况下可能直接调用模型 API 更简单。我们直接从搭建一个能“联网搜索并总结”的问答机器人开始把每个环节的配置、代码和踩坑点都过一遍。1. 先搞明白LangChain 到底在解决哪类开发痛点在直接使用大模型 API比如 OpenAI 的接口时你很快会遇到几个典型的工程化难题上下文长度限制模型一次能处理的文本有上限例如 4K、8K、128K tokens。如果你的知识库文档有 100 页根本无法一次性全部塞给模型。“模型失忆”问题标准的 API 调用是无状态的。你问“我上一句话说了什么”模型根本不知道因为它只看到当前这次请求的输入。需要连接外部数据和工具模型的知识有截止日期也不会算数、查数据库。你想让模型回答“今天某支股票价格如何”或者“帮我总结我昨天提交的工单”就需要先获取实时数据或内部数据再交给模型处理。复杂流程编排一个完整的应用可能包含多步判断。例如用户问题 - 判断是否需要搜索 - 如果需要则执行搜索并获取结果 - 将搜索结果和原始问题组合成新的提示词 - 调用模型生成答案 - 可能还需要根据答案再触发另一个动作。用原生 API 写这些 if-else 和状态管理代码会很快变得混乱。LangChain 的切入点就是把这些难题抽象成标准的、可复用的组件。它提供了以下几大类核心“积木”Models模型不止是聊天模型LLMs还包括文本嵌入模型Embedding Models用于将文本转化为向量和提示词模型。它统一了不同厂商OpenAI、Anthropic、Cohere或本地模型通过 Hugging Face的调用接口。Prompts提示词管理提示模板支持变量插入、少量示例few-shot等让你不用在代码里拼接字符串。Indexes索引用于处理外部文档。核心是“检索”功能也就是从大量文档中快速找到与问题相关的片段。这通常结合文本分割、向量化和向量数据库来实现。Memory记忆管理对话或应用的状态。可以是简单的缓存上一次对话也可以是更复杂的总结性记忆或基于向量的记忆存储。Chains链这是 LangChain 的灵魂。一个 Chain 将多个组件模型、提示词、工具等按特定顺序链接起来。LLMChain是最基础的链提示词 模型还有SequentialChain顺序执行多个链、RouterChain根据条件选择不同链等。Agents智能体这是更高级的“链”。智能体配备了一个或多个“工具”如搜索、计算、查数据库并且由模型自己决定在何时、使用哪个工具形成一个“思考-行动-观察”的循环直到完成任务。理解了这些抽象你就知道 LangChain 不是一个“黑盒魔法”而是一套帮助你组织代码、应对复杂性的工程框架。它的学习曲线正在于此你需要理解这些概念并学会如何将它们组合起来。2. 环境准备与核心概念落地从安装到第一个 Chain理论说再多不如跑一行代码。我们从一个最简单的例子开始感受一下 LangChain 的“手感”。2.1 基础环境搭建首先确保你有一个 Python 环境建议 3.8 以上。然后安装 LangChain。注意LangChain 是一个庞大的项目为了保持轻量它按功能拆分了多个包。最核心的是pip install langchain如果你要使用 OpenAI 的模型还需要安装 OpenAI 的 SDK 并设置你的 API Keypip install openai然后在代码中或环境变量中设置OPENAI_API_KEY。强烈建议使用环境变量避免将密钥硬编码在代码中# 在终端中设置临时 export OPENAI_API_KEYyour-api-key-here# 或者在 Python 代码中设置不推荐用于生产 import os os.environ[OPENAI_API_KEY] your-api-key-here2.2 构建第一个链理解LLM和PromptTemplate我们来创建一个最简单的链根据公司名生成一句宣传标语。from langchain_openai import ChatOpenAI # 注意新版本推荐从 langchain_openai 导入 from langchain_core.prompts import ChatPromptTemplate # 1. 初始化模型。temperature 控制创造性0.0 更确定1.0 更随机。 # model_name 可以是 gpt-3.5-turbo, gpt-4 等。 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.7) # 2. 创建提示词模板。{company} 是一个占位符变量。 prompt_template ChatPromptTemplate.from_messages([ (system, 你是一个擅长创作宣传口号的专家。), (user, 为这家公司想一句宣传标语{company}) ]) # 3. 将模板和模型组合成一个最基础的链 from langchain.chains import LLMChain chain LLMChain(llmllm, promptprompt_template) # 4. 运行链传入变量 result chain.invoke({company: 星辰科技}) print(result[text]) # 可能的输出“星辰科技点亮未来智慧生活”这个例子虽然简单但体现了 LangChain 的核心模式定义组件模型、提示词然后用链Chain把它们组装起来并执行。invoke方法是新版本LangChain 0.1.0推荐的运行方式。为什么不用直接调用 API在这个简单例子中优势不明显。但想象一下如果你的提示词非常复杂包含多个系统指令、用户示例和动态变量用PromptTemplate管理会比手动拼接字符串清晰、安全得多。而且LLMChain自动处理了调用格式和结果解析。2.3 连接外部数据体验RetrievalChain检索链这才是 LangChain 的“重头戏”。我们模拟一个常见场景你有一个产品说明书PDF/TXT想让模型根据这份文档来回答问题而不是依靠它自身的知识。这个过程通常分为三步加载文档 - 处理并索引文档 - 检索并生成答案。首先安装处理文档所需的包pip install langchain-community pypdf sentence-transformers chromadb # langchain-community: 社区维护的第三方集成 # pypdf: 用于读取 PDF 文件 # sentence-transformers: 用于生成文本向量Embedding # chromadb: 一个轻量级向量数据库我们使用本地 Embedding 模型all-MiniLM-L6-v2和 Chroma 向量数据库来演示这样不需要额外的 API 密钥。import os from langchain_community.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA from langchain_openai import ChatOpenAI # 假设我们有一个 product_manual.txt 文件 file_path “product_manual.txt” # 1. 加载文档 loader TextLoader(file_path, encoding“utf-8”) documents loader.load() # 2. 分割文本。模型上下文有限必须把长文档切分成小块。 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块大约500字符 chunk_overlap50 # 块之间重叠50字符避免语义被切断 ) texts text_splitter.split_documents(documents) print(f“将文档切分成了 {len(texts)} 个文本块”) # 3. 创建向量存储索引 # 使用本地 Embedding 模型 embeddings HuggingFaceEmbeddings(model_name“all-MiniLM-L6-v2”) # 将文本块转换为向量并存入 ChromaDB vectorstore Chroma.from_documents(documentstexts, embeddingembeddings, persist_directory“./chroma_db”) # persist_directory 指定存储位置下次可以直接加载无需重新生成向量 # 4. 将向量存储转换为检索器 retriever vectorstore.as_retriever(search_kwargs{“k”: 3}) # 检索最相关的3个文本块 # 5. 创建检索问答链 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) qa_chain RetrievalQA.from_chain_type( llmllm, chain_type“stuff”, # 最简单的方式将检索到的所有文档内容“塞”进提示词 retrieverretriever, return_source_documentsTrue # 返回参考来源便于验证 ) # 6. 提问 question “这款产品的主要特性是什么” result qa_chain.invoke({“query”: question}) print(“答案”, result[“result”]) print(“\n参考来源”) for doc in result[“source_documents”]: print(f“- {doc.page_content[:200]}...”) # 打印前200字符关键点解析文本分割Text Splitting这是文档问答质量的关键。分割得太碎语义不完整分割得太大可能超过上下文。RecursiveCharacterTextSplitter是常用选择它尝试按字符递归分割尽量保持段落完整性。Embedding向量化将文本转换为数学向量语义相似的文本向量距离也近。这是实现“模糊查找”的基础。向量数据库存储向量并提供高效的相似性搜索检索功能。Chroma 是轻量级选择生产环境可能会用 Weaviate、Pinecone、Qdrant 等。检索器Retriever封装了从向量库中根据问题查找相关文本块的操作。chain_type“stuff”这是最简单的处理方式把检索到的所有文本块合并后一次性发给模型。如果检索到的内容总长度可能超过模型上下文就需要用“map_reduce”、“refine”等更复杂但能处理长文本的链类型。通过这个流程你就构建了一个最基本的“私有知识库问答系统”。LangChain 的价值在这里凸显它把加载、分割、向量化、检索、提示词组装、模型调用这一整套复杂流程用几个高级组件封装起来你只需要配置参数而不用从头实现向量搜索或上下文管理逻辑。3. 进阶能力智能体Agents与工具Tools实战如果说 Chains 是预先编排好的工作流那么 Agents 就是赋予模型“自主决策”能力让它能根据你的目标自行决定调用哪些工具。一个经典场景是让模型回答“今天北京天气怎么样用摄氏度表示”。模型自己不知道天气但它可以学会调用一个“天气查询工具”。3.1 使用内置工具联网搜索我们使用 LangChain 社区提供的SerpAPI工具一个搜索引擎 API来演示。你需要先注册 SerpAPI 获取 API Key。pip install google-search-resultsimport os from langchain_openai import ChatOpenAI from langchain.agents import initialize_agent, AgentType from langchain.agents import load_tools # 设置 API Keys os.environ[“OPENAI_API_KEY”] “your-openai-key” os.environ[“SERPAPI_API_KEY”] “your-serpapi-key” # 初始化一个能力较强的模型Agent 需要模型有一定的推理和规划能力 llm ChatOpenAI(model“gpt-4”, temperature0) # 加载工具集。“serpapi” 是搜索引擎工具“llm-math” 是计算工具 tools load_tools([“serpapi”, “llm-math”], llmllm) # 初始化智能体 # AgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION 适合聊天模型使用 ReAct 推理框架 agent initialize_agent( tools, llm, agentAgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION, verboseTrue, # 开启详细日志可以看到模型的“思考过程” handle_parsing_errorsTrue # 优雅处理解析错误 ) # 提问一个需要结合搜索和计算的问题 question “苹果公司Apple Inc.最新的市值是多少如果我用它市值的 1% 来购买最新款 iPhone大概能买多少部假设最新款 iPhone 单价 1000 美元” result agent.invoke(question) print(“\n最终答案”, result[“output”])运行上述代码当verboseTrue时你会在控制台看到类似以下的思考过程Thought: 用户需要苹果公司的最新市值我需要搜索来获取这个信息。 Action: Search Action Input: “Apple Inc. latest market capitalization” Observation: [搜索引擎返回的结果例如 “Apple market cap is $2.8 trillion as of April 2024”] Thought: 我得到了苹果的市值大约是 2.8 万亿美元。现在需要计算其 1% 是多少然后除以 1000 美元。 Action: Calculator Action Input: (2.8 * 10^12) * 0.01 / 1000 Observation: 28000000 Thought: 我计算得出结果是 28,000,000。 Final Answer: 苹果公司最新市值约 2.8 万亿美元。其 1% 约为 280 亿美元按每部 iPhone 1000 美元计算大约可以购买 2800 万部。这就是智能体的强大之处模型自己规划了步骤先搜索再计算并正确选择了工具。你不需要写if “市值” in question: then search()这样的硬编码逻辑。模型根据工具的描述description和你的问题动态决定行动方案。3.2 创建自定义工具很多时候你需要连接内部系统比如查询数据库、调用内部 API。LangChain 让你可以轻松创建自定义工具。from langchain.tools import tool from datetime import datetime tool def get_current_time(format: str “%Y-%m-%d %H:%M:%S”) - str: “”“获取当前的系统时间。输入参数 format 是时间格式字符串默认为 ‘年-月-日 时:分:秒’。”“” current_time datetime.now().strftime(format) return current_time # 假设还有一个查询用户订单的工具这里用模拟函数 tool def lookup_user_order(user_id: str) - str: “”“根据用户ID查询其最近一笔订单的状态。输入应为用户ID字符串。”“” # 这里应该是真实的数据库查询逻辑我们模拟返回 order_status_map {“user123”: “已发货”, “user456”: “待付款”} return order_status_map.get(user_id, “未找到该用户订单”) # 将自定义工具和之前的工具一起加载 from langchain.agents import initialize_agent, AgentType from langchain_openai import ChatOpenAI llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) tools [get_current_time, lookup_user_order] # 也可以和 load_tools 的结果合并 agent initialize_agent( tools, llm, agentAgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION, verboseTrue, ) # 现在可以问更复杂的问题了 result agent.invoke(“现在是什么时间另外请查一下用户 user123 的订单状态。”) print(result[“output”])关键点使用tool装饰器并写好工具函数的文档字符串docstring。智能体会根据这个描述来决定是否以及如何使用该工具。输入参数的类型提示如str也很重要。4. 生产环境考量何时用 LangChain有哪些坑LangChain 功能强大但并不意味着所有 LLM 应用项目都要用它。它的抽象带来便利的同时也引入了复杂性和学习成本。4.1 适用场景与不适用场景强烈建议使用 LangChain 的场景快速构建复杂原型当你需要快速验证一个涉及多步推理、工具调用或复杂文档处理的创意时LangChain 的组件能极大节省时间。构建基于私有知识的问答系统它的RetrievalChain及相关生态文档加载器、向量库集成是目前最成熟的方案之一。需要智能体Agent能力当你的应用逻辑难以预先固定需要模型自主决定调用哪些外部工具或 API 时。团队协作与代码维护当项目有多人参与时使用统一的框架和模式有利于代码理解和维护。可能不需要 LangChain直接调用 API 更简单的场景简单的对话或文本生成只需要调用一次模型 API没有复杂逻辑。对延迟和开销极其敏感LangChain 的抽象层会带来轻微的性能开销和额外的依赖。对于超高并发、超低延迟的简单服务直接调用模型 SDK 可能更优。功能极其定制化如果你的应用流程与 LangChain 的标准组件模式差异巨大强行套用可能不如自己从头编写更清晰。学习初期为了理解底层原理先直接用原始 API 实现几次再对比使用 LangChain会理解更深。4.2 常见“坑”与排查指南在实际使用中你可能会遇到以下问题1. 版本兼容性与 API 变动LangChain 版本更新较快尤其是从 0.0.x 到 0.1.x 有较大变动。很多旧教程的导入方式如from langchain.llms import OpenAI在新版本中已废弃。排查始终以 官方文档 为准。安装后首先检查版本pip show langchain。遇到ImportError先去文档查最新的导入路径。建议在新项目中使用langchain0.1.0并主要参考langchain-*的独立包如langchain-openai,langchain-community。2. 提示词Prompt效果不佳LangChain 负责组装流程但提示词的质量最终决定模型输出。链Chain或智能体Agent效果不好首先怀疑提示词。排查打开verboseTrue查看链或智能体实际发送给模型的完整提示词是什么。检查系统指令是否清晰用户问题格式是否正确上下文是否被正确插入。建议在 LangSmithLangChain 官方调试平台中跟踪和测试你的提示词。对于复杂链可以拆解成小步骤单独测试。3. 检索Retrieval质量差文档问答回答不准通常是检索环节的问题而不是模型问题。排查顺序文本分割chunk_size是否合适太大可能包含无关信息太小可能丢失关键上下文。尝试调整大小和重叠度。Embedding 模型不同的 Embedding 模型对中文、专业术语的支持差异很大。all-MiniLM-L6-v2是通用英文模型中文场景可考虑text2vec、m3e等。检索策略search_kwargs{“k”: 3}中的k值是否合理可以尝试增大。检索方法除了相似性搜索similarity_search还可以尝试最大边际相关性MMR来平衡相关性和多样性。原始文档质量垃圾进垃圾出。确保源文档清晰、格式规整。4. 智能体Agent陷入循环或调用错误工具这是 Agent 开发中最常见的问题。排查务必开启verboseTrue观察模型的“思考Thought”过程。它是否误解了工具描述是否在无关步骤上循环建议优化工具描述工具函数的文档字符串要极其精确说明输入输出格式和适用场景。选择更强的基础模型Agent 非常依赖模型的推理和规划能力。gpt-3.5-turbo可能表现不稳定优先使用gpt-4或claude-3系列。设置超时和最大步数使用max_iterations和max_execution_time参数防止无限循环。提供更详细的系统提示在初始化 Agent 时可以通过agent_kwargs传入定制的系统提示约束其行为。5. 成本与性能失控在链或智能体中一次用户查询可能触发多次模型调用如 Agent 的每一步思考都是一次调用和外部 API 调用如搜索。建议记录和监控使用 LangSmith 或自定义日志记录每次请求的 token 消耗、调用次数和耗时。设置预算和限制在工具调用或链层面设置速率限制和费用上限。缓存对频繁重复的查询或 Embedding 结果实施缓存。4.3 部署与规模化建议对于学习原型在 Jupyter Notebook 或脚本中运行即可。但要部署为服务需要考虑异步支持LangChain 支持异步调用ainvoke,astream对于 Web 服务至关重要能提高并发处理能力。状态管理对于多轮对话需要将ConversationBufferMemory等记忆组件与用户会话 ID 绑定并持久化到数据库如 Redis而不是放在内存里。向量数据库选型Chroma 适合原型和中小数据量。生产环境应考虑支持分布式、持久化、高性能的向量数据库如 Weaviate、Qdrant、Pinecone云服务或 PGVector基于 PostgreSQL。模块化设计不要把所有代码写在一个巨型链里。将不同的功能链如检索链、总结链、分类链定义为独立的组件通过更上层的路由逻辑来调用这样更易于测试和维护。5. 总结把 LangChain 当作高效脚手架而非黑盒魔法经过上面的拆解你应该对 LangChain 有了更立体的认识。它不是一个“自动生成应用”的神器而是一个强大的、但需要你清晰架构思维的脚手架。我的核心建议是从问题出发而不是从技术出发先明确你要构建的应用核心流程是什么是简单问答、文档总结、数据查询还是自主规划再判断是否需要以及需要使用 LangChain 的哪些组件。分层学习和实践先掌握Models、Prompts和基础LLMChain。然后攻克Indexes和RetrievalQA这是实用性最强的部分。最后再研究Agents和自定义工具。重视提示词工程和评估LangChain 解决了流程问题但提示词的质量、检索的准确性、工具描述的清晰度这些仍然需要你精心设计和反复调试。结合 LangSmith 进行跟踪和评估。关注抽象背后的原理理解它为什么要把流程拆成链为什么需要向量检索Agent 的 ReAct 框架是如何工作的。这能帮助你在出问题时快速定位是框架问题、配置问题还是你自己的逻辑问题。对于刚入门的开发者可能会觉得 LangChain 概念繁多有点“重”。这很正常。它的设计目标本就是应对复杂场景。如果你的需求很简单直接调用模型 API 是完全合理的选择。但当你开始面对“长文档处理”、“多工具协调”、“动态决策流程”这些挑战时你会发现在 LangChain 的体系下工作远比从零造轮子要高效和稳健得多。最终把它当成一个帮你组织代码、提供最佳实践套件的伙伴而不是一个必须遵循的教条。理解其设计思想熟练运用其核心模块你就能在 LLM 应用开发的路上走得更快、更稳。
基础与实用命令详解)
