企业官网建设流程全解析

1. LangChain到底解决什么问题

先说个痛点。过去两年里，我见过大量团队开发AI应用时,代码写到最后全都长一个样：调用大模型接口、拼接提示词、处理返回结果、再根据结果决定下一步调用什么工具。这些逻辑本身不复杂，但架不住项目一大了之后，提示词散落在各个文件里，模型切换要改十几个地方的参数，连个上下文记忆都要自己用列表维护，整个项目很快就变成一座没人愿意碰的屎山。

LangChain就是为了收拾这片狼藉而生的。它把AI应用开发里那些高频重复的动作——调用模型、组织提示词、维护记忆、编排工具调用——全部抽象成标准组件，让你像拼乐高一样把应用搭起来。这套框架从2022年底发布到现在，已经成了大模型应用开发领域事实上的基础设施，GitHub上星标数量常年霸榜，背后有大几万开发者在贡献生态。

所以这篇快速入门，我不会去抄官方文档的目录，而是按照我实际项目里用的顺序来讲——先搞清楚LangChain的核心抽象是什么，再动手跑通一个能用的Demo，然后解决接入真实项目时最容易踩的坑。适合刚接触LangChain的开发者，也适合那些已经"会用但总感觉哪里不对"的朋友重新梳理一遍认知。

2. 核心概念拆解：从Model到Chain再到Agent

2.1 模型层：Model I/O的三件套

LangChain对模型操作的封装是我用得最顺手、也是建议所有人第一个掌握的模块。它把"跟大模型打交道"这件事拆成了三个部分：提示词模板（PromptTemplate）、语言模型封装（LLM/ChatModel）、输出解析器（OutputParser）。

语言模型的封装解决的是"换模型不换代码"的问题。你只需要通过统一的接口初始化一个模型对象，后面就可以用invoke、predict这些标准方法去调用它，模型的供应商、版本、温度参数都收敛在初始化那一段配置里。这个抽象的价值在切换模型时特别明显——我之前有个项目先用某家的模型做原型，后来换成了开源模型部署的本地服务，整个工程的改动量只有模型初始化那一行。

提示词模板解决的是"提示词动态化"的问题。真实项目里，提示词几乎不可能是一段静态文字，它总要掺和进用户的输入、检索到的上下文、对话历史这些变量。如果用f-string去拼，代码很快就会变得混乱，PromptTemplate把变量用占位符标注出来，最后通过格式化方法填充实际内容，思路清晰得多。

输出解析器则帮你把模型的文本输出变成结构化数据。这个模块经常被新手忽略，但实际上它最能体现工程价值。大模型只会输出字符串，而你的业务逻辑往往需要字段、列表、JSON对象。OutputParser做到的事情就是"文本——结构化"之间的转换，比如用PydanticOutputParser能按照你定义的Pydantic模型自动校验和修正模型输出。

2.2 链的本质：把多个步骤串起来

LangChain里最核心也最容易被误解的概念就是"链"。很多人刚接触时以为链就是"调用一次模型"，其实链的本质是"编排"——把多个步骤组织成一个可复用、可组合的执行流。

最简单的链是PromptTemplate、Model、OutputParser三者串起来的一个链路：格式化提示词、送入模型、解析输出，三步合成一步完成。这就是LLMChain的雏形。但真正好用的链要复杂得多，比如典型的"检索增强生成"链，要经过"查询改写——向量检索——文档重排——提示词组装——模型生成——输出校验"这些步骤，每一步都可以是一个独立的组件，通过链把它们串起来之后，整个流程对外暴露一个统一接口。

我自己的经验是，使用链的时候不要总想着去继承框架的Chain类写自己的链子。多数场景下用LCEL（LangChain Expression Language）直接声明式地组合表达式就够了，它用管道符|把各个组件连起来，比如prompt | model | parser，既直观又省事。LCEL还天然支持流式输出、异步执行、并行处理这些高级特性，是新一代LangChain官方主打的使用方式。

2.3 记忆、工具与Agent：让模型拥有上下文和执行能力

聊完链，再补两个项目实战里绕不开的抽象，记忆和智能体。

记忆模块解决的是多轮对话中上下文丢失的问题。大模型本身是无状态的，每一次调用它都当作第一次见你。LangChain提供了好几种记忆实现，简单的如ConversationBufferMemory，把对话原封不动地存进列表；进阶的如ConversationSummaryMemory，用模型自己把历史对话总结成摘要再塞进上下文，适合超长对话场景。记忆这个东西，选型时最忌讳"想当然"，得掂量你的应用是短对话多、还是长上下文多，比如实现智能客服机器人，通常用窗口化记忆就行，保存最近几轮；而做长文提炼类的工具，就该用摘要型记忆。

Agent是LangChain里最亮眼也最令新手困惑的概念。它本质上是一个"决策者"：当用户提了一个问题，Agent自己决定先调用什么工具、按什么顺序执行。比如你问"今天杭州天气适合穿什么衣服"，Agent可能会先调用天气查询工具拿到温度湿度，再调用一个穿衣建议的提示词链。实现这个效果靠的是ReAct等推理框架——模型推理出"我需要获取数据"，再推理出"获取数据应该调用工具A"，然后执行并观察结果，循环直到任务完成。

3. 动手实操：半小时跑通你的第一个LangChain应用

3.1 环境准备与依赖安装

开始写代码前，先把环境收拾利索。我建议用Python 3.10及以上的版本，因为LangChain新版本对Python版本有要求，太老的版本会遇到依赖冲突。

python -m venv langchain-demo source langchain-demo/bin/activate # Windows下是 activate.bat pip install langchain langchain-openai langchain-community

这里有个经验值得说说：很多教程会让你直接pip install langchain一把梭，但实际项目中最好按需安装。LangChain这些年做的最重要的架构调整之一就是把各种集成拆成了独立的命名空间包，比如要用OpenAI的模型就装langchain-openai，要用向量数据库就装对应的langchain-xxx。这样做的好处是依赖树干净，不会装一堆用不到的包导致版本冲突。

然后做模型层面的配置。现在的LangChain有三种接入模型的方式：官方托管API、兼容接口的第三方服务、本地部署的模型服务（比如各类开源模型）。如果你的场景是本地私有化部署，通常会把模型服务包装成一个兼容标准接口的服务，然后通过ChatOpenAI的配置项来接入，把base_url指向本地服务地址就行。

from langchain_openai import ChatOpenAI model = ChatOpenAI( model="qwen2.5:7b", temperature=0.7, base_url="http://localhost:8000/v1", api_key="not-needed", # 本地服务一般不校验key )

我实际项目中最多的是这种"API地址换来换去"的场景，把模型接入层做好抽象之后，切换模型时不动其他代码，非常省心。

3.2 从零搭一个带记忆的问答机器人

下面我们做一个真正的、能跑起来的应用：一个带记忆的客服问答机器人，它可以根据知识库资料回答问题，同时记住用户刚才聊过什么。这个Demo覆盖了LangChain最核心的组件用法，做完它你就基本摸清框架的套路了。

第一步，先定义知识库资料和对应的检索器。真实场景里知识库一般在向量数据库里，Demo阶段用内存里的列表就够了：

from langchain_core.documents import Document docs = [ Document(page_content="某品牌的智能音箱支持语音控制家电，包括灯光、空调、电视等。"), Document(page_content="该音箱的蓝牙连接有效距离为10米，超出范围可能导致断连。"), Document(page_content="如果设备无法开机，请先检查电源适配器是否插紧，再尝试长按电源键10秒。"), ]

第二步，构建一个简单的向量检索器。这里用的是内存版的向量存储，不使用外部向量数据库，它内部会把文档做向量化并支持相似度搜索：

from langchain_community.vectorstores import FAISS from langchain_openai import OpenAIEmbeddings vector_store = FAISS.from_documents( docs, embedding=OpenAIEmbeddings(model="text-embedding-3-small") ) retriever = vector_store.as_retriever(search_kwargs={"k": 2})

第三步，定义提示词模板，把"资料片段"和"用户问题"都变成可填充的变量：

from langchain_core.prompts import ChatPromptTemplate prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个智能客服助手。请基于下面的资料回答用户的问题，不要编造资料中没有的信息。\n\n资料：{context}"), ("human", "{question}"), ])

第四步，加上记忆模块，让机器人能记住上下文。现代版本的LangChain用RunnableWithMessageHistory来处理记忆，它能把对话历史自动注入到提示词的messages里：

from langchain_core.runnables.history import RunnableWithMessageHistory chain = prompt | model chain_with_history = RunnableWithMessageHistory( chain, get_session_history=..., # 这里要传入一个函数，按session_id取历史 )

实际编码时你会发现，get_session_history函数需要你实现一个"按会话ID存取消息列表"的方法。最简单的方式是维护一个全局字典，生产环境换成Redis就没问题了。

3.3 完整Demo代码与关键参数说明

把上面几步串起来，一个可运行的完整Demo大概是这样的。这段代码我建议你直接跑一遍再逐行读，因为有几个参数的实际效果只看文档是体会不到的：

from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain_community.vectorstores import FAISS from langchain_core.documents import Document from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables.history import RunnableWithMessageHistory from langchain_core.chat_history import InMemoryChatMessageHistory sessions = {} def get_session_history(session_id: str): if session_id not in sessions: sessions[session_id] = InMemoryChatMessageHistory() return sessions[session_id] docs = [ Document(page_content="某品牌的智能音箱支持语音控制家电，包括灯光、空调、电视等。"), Document(page_content="该音箱的蓝牙连接有效距离为10米，超出范围可能导致断连。"), Document(page_content="如果设备无法开机，请先检查电源适配器是否插紧，再尝试长按电源键10秒。"), ] model = ChatOpenAI( model="qwen2.5:7b", temperature=0.5, base_url="http://localhost:8000/v1", api_key="not-needed", ) vector_store = FAISS.from_documents(docs, embedding=OpenAIEmbeddings(model="text-embedding-3-small")) retriever = vector_store.as_retriever(search_kwargs={"k": 2}) prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个智能客服助手。请基于下面的资料回答用户的问题，不要编造资料中没有的信息。\n\n资料：{context}"), ("human", "{question}"), ]) def format_docs(docs): return "\n\n".join(doc.page_content for doc in docs) chain = ( { "context": lambda x: format_docs(retriever.invoke(x["question"])), "question": lambda x: x["question"], } | prompt | model ) chain_with_history = RunnableWithMessageHistory( chain, get_session_history, input_messages_key="question", history_messages_key="history", )

调用方式是这样的，注意config参数里要传session_id：

result1 = chain_with_history.invoke( {"question": "我的音箱连不上蓝牙了，可能是什么原因？"}, config={"configurable": {"session_id": "user-001"}}, ) print(result1.content) result2 = chain_with_history.invoke( {"question": "那我应该怎么排查？"}, config={"configurable": {"session_id": "user-001"}}, ) print(result2.content)

这里有几个参数值得单独拎出来解释：

第一个是temperature=0.5。这个参数控制模型输出的随机性，值越低越稳定、越倾向于按部就班，客服场景我一般设在0.3到0.6之间。你要是做文案创作类应用，可以调到0.8以上，但知识问答类应用千万别调太高，不然模型会一本正经地编造答案。

第二个是search_kwargs={"k": 2}里的k。这个参数决定每次检索返回多少条相关文档。调大k会提升召回率但会稀释上下文质量，模型可能被不相关的片段干扰。我做项目时的经验是：知识库文档越碎片化，k反而要调小，先保证精准，再谈覆盖。

第三个是history_messages_key="history"，需要保证提示词模板里有一个名字叫history的消息占位符，LangChain会自动把对话历史插入到这个位置。如果提示词模板里漏了这个占位符，调用时会报错，这是新手最常遇到的一个报错点。

4. 深入Agent：让模型学会调用工具

4.1 为什么需要Agent而不只是链

聊到这一步，很多人会问：我上面这个Demo已经能回答问题了，为什么还需要Agent？答案是——链适合处理"流程固定"的任务，Agent适合处理"流程不固定"的任务。

举个例子，用户问"帮我查一下订单状态，然后根据物流信息判断能不能今天送到"。如果你用链，你得把"查订单""查物流""判断送达时间"全部预先编排好，但实际项目中用户的需求千奇百怪，你不可能把所有可能场景都固化到链里。Agent的思路完全不同：你只需要给模型备好几把工具——查订单工具、查物流工具、计算时间工具——然后让模型自己决定怎么组合使用。

这就是把"决策逻辑"从你的代码里转移到了模型推理中。代价是你对过程的控制变弱了，所以Agent适合用在对准确性要求不那么苛刻、但任务种类繁多的场景，比如个人助理、信息聚合类的应用。

4.2 用Tool和Agent搭建一个自动查天气的应用

实操一个最简单的Agent：用户问天气，Agent决定是否需要调用天气查询工具。这里我用一个模拟的天气工具函数来演示，它假装通过城市名返回天气数据：

from langchain_core.tools import tool @tool def get_weather(city: str): """查询指定城市的当前天气，返回温度、天气状况和风力。""" data = { "杭州": "晴，22°C，东南风3级", "上海": "多云，24°C，东风2级", "北京": "小雨，18°C，北风4级", } return data.get(city, "暂不支持该城市的天气查询") tools = [get_weather]

然后创建Agent执行器。新版本的LangChain推荐用create_openai_functions_agent或者直接用LangGraph来实现Agent逻辑，这里我展示一种简洁可靠的写法：

from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate agent_prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个实用的助手，可以根据用户问题调用合适的工具。"), ("placeholder", "{chat_history}"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) agent = create_tool_calling_agent(model, tools, agent_prompt) executor = AgentExecutor(agent=agent, tools=tools, verbose=True) result = executor.invoke({"input": "帮我查一下杭州的天气，适合穿什么衣服？"}) print(result["output"])

运行这段代码你会发现，模型会先调用get_weather工具，拿到返回结果之后，再根据结果生成穿衣建议。agent_scratchpad这个占位符是Agent运行过程中的"思考记录区"，模型会把中间推理步骤写进去，框架负责维护。

我要提醒的是：Agent是把双刃剑。它虽然灵活，但会增加推理延迟，并且偶尔会做出意料之外的工具调用顺序。生产环境里我一般会给Agent加上max_iterations限制，防止它陷入死循环，同时给每个工具函数写尽可能清晰的docstring，因为工具描述就是模型决定"该不该调用这个工具"的依据。你写city: str参数时一定把支持的城市列表写清楚，模型乱传参数的情况会少很多。

5. 生产环境落地：从Demo到可用系统要跨过的坎

5.1 外部记忆存储与状态管理

Demo里头我们用内存字典存session历史，这在开发调试时没有问题，但一旦服务重启，所有对话历史就全丢了。生产环境里，我强烈建议把消息历史存到Redis或数据库里。LangChain提供了RedisChatMessageHistory和SQLChatMessageHistory，换起来很简单：

from langchain_redis import RedisChatMessageHistory def get_session_history(session_id: str): return RedisChatMessageHistory( session_id=session_id, url="redis://localhost:6379", ttl=3600, # 一小时后过期 )

这里有个细节值得说：对ttl的设定要结合你的业务来判断——客服类应用可能希望保留3天到1周的聊天记录供运营分析，而工具类应用可能只保留30分钟就够。这个参数不是随便填的，它直接决定了用户的记忆是"短期有用"还是"隐私风险"。另外一个细节是，生产环境的用户身份认证一定要做，session_id千万不要用用户可控制的明文，否则会出现会话串号这种安全事故，我见到过不止一次。

5.2 流式输出与并发控制

真正上线之后，用户对"打字机效果"的期待几乎成了标配。LangChain的LCEL天然支持流式输出：

for chunk in chain_with_history.stream({"question": "你好"}, config={"configurable": {"session_id": "user-001"}}): print(chunk.content, end="", flush=True)

注意，加了RunnableWithMessageHistory之后，流式的行为有时会让人困惑——它可能只在最后阶段输出，因为整个历史要重新填入上下文。遇到这种情况不用慌，检查一下你的链结构是不是把历史注入的步骤放在最前面。写自己的链要对"什么步骤该走流式、什么步骤必须等完整结果"有清晰认知，比如Agent的中间工具调用过程就不适合流式，因为模型需要先拿到工具返回结果才能继续生成。

并发控制是我要特别强调但很少被教程提到的部分。LangChain本身不管理并发，多实例部署时你要自己做限流。模型提供方基本都有每分钟调用次数限制，你的应用层必须做好排队或熔断，不然流量高峰时会把模型服务打爆。我现在会用一个简单的信号量来控制并发：

import asyncio semaphore = asyncio.Semaphore(10) async def guarded_invoke(payload, session_id): async with semaphore: return await chain_with_history.ainvoke(payload, config={"configurable": {"session_id": session_id}})

5.3 成本控制与可观测性

模型调用是按token收费的，这个成本在真实流量下会高得让人肉疼。我常用的成本控制手段有三板斧：缓存、限流、降级。

缓存最值得做。对FAQ类的常见问题，完全可以把模型输出缓存下来，命中缓存就直接返回，能省一大半成本。LangChain提供了InMemoryCache和SQLiteCache：

from langchain_core.caches import InMemoryCache from langchain.globals import set_llm_cache set_llm_cache(InMemoryCache())

设置之后，相同的提示词会直接命中缓存返回结果，不再调用模型。这个方案对"请求重复度高"的应用效果立竿见影。要注意的是，缓存键不是用户输入，而是完整的提示词内容，因此你的提示词模板里如果有温度这种会导致输出变化的参数，缓存策略需要调整。

可观测性方面，我强烈建议尽早接入LangSmith或者至少在代码里加上结构化日志。LangSmith能完整记录每次模型调用的输入输出、token消耗、延迟、哪个链环节出了问题，排障的效率提升是数量级的。没有这类工具的话，你会有一天面对生产环境报错却完全不知道模型实际收到了什么，无从排查。

6. 常见问题与排查技巧实录

6.1 高频报错及解决方案速查

我把自己和身边同事在LangChain项目里遇到的高频问题整理成一张速查表，按遇到概率排序：

6.2 几个容易踩坑的隐蔽细节

有些坑只有真正跑过业务才能发现，它们不会让程序崩溃，但会让结果质量差一个档次。

第一个坑是文档切分。很多人做RAG时直接把PDF按500个字硬切，导致一句话被拦腰截断成两半、语义丢失。正确的做法是使用RecursiveCharacterTextSplitter，并传入合适的separators列表，让切分器优先在段落、句子边界处切割。对中文文档，我习惯把分隔符设置为["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""]，这样切出来的chunk基本保留完整的语义单元。

第二个坑是embedding模型的选型。初学者最容易犯的错是直接用默认embedding模型处理中文，效果惨不忍睹。中文场景下需要选择对中文语料优化的embedding模型，否则检索召回率会明显偏低。我的经验是，接入新embedding模型后一定要用一个包含同义改写、近义表达的测试集去验证检索效果，别拿一两个例子凭感觉判断。

第三个坑是链和Agent的调试。生产环境里最让人头疼的场景之一是："模型回答质量不达标，你根本不知道是检索没召回相关内容，还是提示词引导不善，还是模型本身能力不够。"遇到这种情况，我建议按层排查：先单独调用retriever看返回的context是否正确，再单独调用model看给定正确context时能否生成正确答案，最后才去看整体链路。LangSmith的trace功能恰好能把这几步的输入输出都可视化出来，是定位这类问题的利器。

第四个坑是版本兼容。LangChain的版本迭代速度极快，社区里看到的示例代码很可能已经过时。比如旧版的LLMChain在新版本中被LCEL取代，很多抽象被移到了langchain-core包。我踩过最大的坑是生产环境锁了一个版本，结果想用新功能就必须升级，升级后又出现一堆deprecation warning。建议项目从第一天就锁死版本，而且只按需引入langchain-xxx的子包，不要全家桶式安装。

6.3 一组实战对比数据

最后分享一组很有意思的实测数据。我做一个简单的知识库问答系统，分别用"裸模型直接回答"、"基础RAG链"、"带重排的RAG链"三种方案测试同一批50个问题，指标是这样的：

可以看到，RAG的价值是决定性的，但重排序带来的收益也很明显——多花0.7秒和一点成本，正确率提升8个百分点。对于知识密度高、答案容易混淆的场景，强烈建议引入重排序环节，这也是LangChain生态里ContextualCompressionRetriever这类组件存在的意义。

我个人在实际项目里的体会是，LangChain的价值不在于它让代码变短多少，而在于它把AI应用开发的思考方式从"面向过程"扭转为"面向组件"。现在我做新项目，脑子里第一反应是：我的输入输出是什么、需要哪些中间步骤、哪些步骤需要换、哪些步骤要复用。想清楚了这几个问题，用LangChain拼装出来的应用结构是高度清晰、可审计的。希望这篇快速入门能帮你建立同样的工程直觉，剩下的路，就得靠你多踩几个坑、多调几次参，才能真正长在自己身上。