最近大模型的应用已经从“能聊天”进化到“能干活”的阶段而Langchain在这股浪潮里几乎是绕不开的基础设施。我自己从最早用API裸调到后来上手Langchain再到用它搭出一套能跑通RAG和Agent的智能体系统中间踩了不少坑也攒了不少心得。这篇博文就把我从入门到实战的路径拆开来讲重点是LLM接入、RAG检索增强、Agent工具调用这三块核心希望能给正在学Langchain或者准备做智能体项目的朋友一份能直接上手的参考。1. Langchain到底解决了什么问题1.1 从“调API”到“搭系统”的跨越先说说我为什么从裸调API转向Langchain。最早做AI应用本质就是封装大模型接口你发一段prompt模型回一段文字然后你自己处理字符串、管上下文、做日志。这套流程在demo阶段完全够用但一旦涉及多个步骤、外部数据源、工具调用代码就变得极其臃肿。举个例子你做一个“查询公司内部知识库并生成摘要”的功能。裸调API的话你需要自己写向量化逻辑、自己管理向量数据库连接、自己拼接检索结果和用户问题、自己处理模型返回格式异常。这些代码彼此耦合换个模型或者换个向量库就要大改。而Langchain做的事就是把这套流水线的公共部分抽象成标准组件你用搭积木的方式把功能串起来业务逻辑清晰很多后期维护和替换组件也方便。很多刚接触的朋友会问Langchain是不是必须学如果你只是写个一次性用的脚本确实不需要。但如果你要长期维护一个智能体应用或者要快速迭代多个功能Langchain的组件化设计能帮你省掉大量重复劳动。1.2 核心组件一览链、模型、记忆、检索、智能体Langchain的功能模块可以按照大模型应用的通用架构来理解不需要一上来就背概念我先按常用程度排个序模型封装Model I/O统一了不同厂商模型OpenAI、开源模型等的调用方式。你在代码里换模型只需要改配置不用改业务逻辑。我自己习惯把模型名称、温度、max_tokens都放在配置文件里切换模型时只动配置不动代码。检索增强Retrieval对应RAG的核心环节包括文档加载、切分、向量化、存储、查询。Langchain把这一整条链路都标准化了Loader处理不同格式的文档TextSplitter控制切分方式VectorStore接口对接各种向量数据库。记忆管理Memory解决多轮对话中的上下文保持问题。智能体不能每次都是“失忆状态”需要把历史对话归纳、压缩、存储。链Chain把多个步骤编排成流水线。比如“检索-生成-校验”三步就是一条链。Langchain里面链的概念有点多但本质上就是函数的组合、流程的串联。智能体Agent比链更灵活。链是固定流程Agent是模型自己决定下一步干什么、调用哪个工具、什么时候结束。这个区别非常关键后面我会详细展开。回调机制Callbacks用于监控、日志、跟踪。这在生产环境几乎是必需的你可以监听模型调用的开始、结束、报错把信息输出到日志系统。理解这些组件的定位之后你再看Langchain的复杂文档就不会慌——它本质上就是一个“大模型应用的操作系统”各个组件就是标准接口的零件。2. 智能体系统的整体设计思路2.1 从需求倒推架构知识库问答是绝佳的起点我建议入门智能体的第一站做一个基于RAG的知识库问答系统然后再往外挂工具、做成真正的Agent。因为知识库问答的骨架是完整的加载文档、向量化、检索、生成回答每一环都有明确输入输出适合理解数据流向。我之前带过几位实习生直接让他们上手Agent工具调用结果往往一头雾水。后来调整策略先花两天做一个“简历问答系统”把几份简历文档喂进去让模型回答相关问题基本就理解了RAG的完整流程。让数据先流动起来再考虑智能体决策的问题学习曲线平滑得多。2.2 平衡复杂度什么时候用Chain什么时候用Agent这里有一个非常务实的取舍问题。Agent虽然智能但它引入了不确定性——模型可能会调用错误的工具、生成无效的参数甚至陷入循环。如果你的业务步骤是固定的比如先检索、再总结、再翻译用Chain就行了没必要让模型做决策。Chain执行链路稳定、耗时可控、调试方便。那么什么时候该上Agent当任务路径高度不确定的时候。比如一个助手需要根据用户的不同问题决定“查天气还是查日历还是发邮件”这个决策逻辑用代码写很繁琐让模型基于工具描述自己决策反而更自然。我个人的经验是能用Chain解决的绝不硬上AgentAgent是补足灵活性的手段而不是越复杂越好。实际项目中往往是混合架构——固定流程用Chain编排需要动态决策的节点挂Agent作为子模块。2.3 技术选型模型、向量库、Embedding的最佳开局组合开局阶段不用追求最新最强的技术要追求“能跑通、易调试、社区资料多”。以下是我验证过比较省心的组合模块推荐选择理由LLMOpenAI GPT系列接口工具调用成熟、生态完善初学阶段省去很多兼容性问题EmbeddingOpenAI Embedding或开源BGE系列BGE在中文场景表现稳定OpenAI的接入最简单向量数据库Chroma本地起步/ Milvus生产Chroma零配置直接跑Milvus适合数据量大时切换框架版本Langchain 0.x注意新老版本差异社区讨论多踩坑时容易搜到解决方案提示模型和向量库领域发展非常快不要迷信“最强”组合先选一套资料最多的方案跑通全流程再逐步替换你觉得不合适的组件。2.4 项目结构规划别把所有代码写在Jupyter里很多初学者喜欢在Jupyter Notebook里验证思路这没问题但正式做项目一定要按模块组织代码。我常用的目录结构是这样的agent_project/ ├── config/ # 配置文件模型参数、API Key、路径 ├── data/ # 文档原始数据 ├── documents/ # 切分后的文档缓存 ├── src/ │ ├── llm.py # 模型实例化与统一入口 │ ├── retriever.py # 索引构建与检索模块 │ ├── memory.py # 对话记忆管理 │ ├── tools/ # 自定义工具集 │ ├── agent.py # Agent编排核心 │ └── chains.py # 固定流程链的封装 ├── tests/ # 针对检索、工具调用的单元测试 └── app.py # 入口CLI或Web API这种结构的好处是当你想把一个模块替换掉比如换向量库影响面被限制在对应文件里。我见过太多人把所有逻辑堆在一个脚本里最后改一行代码牵连一片所有时间都花在“搞清楚这段代码干嘛的”上面了。3. 核心环节实操RAG与Agent的实现细节3.1 文档加载与切分切分策略直接影响检索质量RAG的第一步是让模型“读”你的文档。这里的核心不是加载而是切分——不同切分方式会直接决定后续检索的命中率。我常用的切分策略是递归字符切分法Langchain里叫RecursiveCharacterTextSplitter。它有几个关键参数chunk_size每个块的长度。我之前用500字符后来在中文场景下调整为300-400效果更稳因为中文信息密度高。chunk_overlap相邻块的重复区域。不设置重叠的话一个问题正好卡在两个块的边界上检索时两边都差一点信息回答就会残缺。我一般设置50字符左右。separators分隔符优先级。按段落、句子、字符的顺序逐级切割。实操时需要注意如果原始文档是Markdown或者HTML先用对应的Loader解析出结构再切分。直接按纯文本切分会把代码块、表格、列表打得稀碎检索结果基本没法看。我遇到过一次把Excel表格导入后切分模型生成的回答完全错乱就是因为表格被切成了无意义的碎片。3.2 向量化与检索找到“语义相似”而不是“字面匹配”向量化的意义是把文本映射为高维向量检索时通过向量距离找到语义相近的内容。这句话说起来简单但有个常见的误区很多人以为向量检索是万能的于是放弃关键词检索。实际上多个检索策略融合才是RAG工程的常态。我现在的做法是混合检索Hybrid Search先用关键词如BM25粗筛一轮再做向量相似度精排最后用重排序模型Reranker综合打分。纯向量检索的问题是专有名词、缩写、编号这些场景语义向量往往会忽略字面信息。比如用户搜“YOLO v5”语义向量可能匹配到“目标检测模型”这种宽泛描述而不是精确到版本的文档。关于向量库的选择我一开始用Chroma图省事数据到了百万级就撑不住了。后来迁移到Milvus性能提升明显。但Milvus的部署和运维成本高不少团队规模小的时候性价比不一定划算。建议数据量在十万条以下Chroma或单机FAISS完全够用数据量大且并发高再考虑分布式向量库。3.3 Agent核心机制从ReAct到Function CallingAgent与传统Chain的根本区别在于“循环决策”能力。这里简单拆解一下主流的Agent工作机制。ReAct模式Reason and Act是最早的agent范式思路是让模型循环执行两步推理reasoning和行动action。模型先分析当前状态决定需要调用什么工具把工具和参数输出为指定格式执行工具后把结果返回给模型继续推理直到模型判定任务完成。Langchain的ZeroShotAgent就是按这个思路实现的。后来OpenAI接口直接支持了Function Calling机制平台在API层面帮你做了输出约束模型输出的就是结构化调用参数不需要在prompt里来回强迫模型输出JSON了。Langchain对此做了很好的适配你定义好工具函数框架负责解析模型返回的调用请求并在内存中执行。实操中最关键的是工具定义的质量。Langchain里定义一个工具通常需要绑定函数的名称、描述和参数结构。模型自己不能“看”函数内部的实现它只根据函数名和描述决定何时调用。所以工具描述写得是否清晰直接决定Agent能不能正确使用它。不要写“一个有用的小工具”要写清“何时使用、输入参数含义、返回值结构、注意事项”。3.4 记忆机制的四种形态智能体的记忆不是把聊天记录原样塞进上下文那是新手最容易犯的错误。上下文窗口是有限的塞多了不仅浪费token还会让模型“迷失”在无关历史里。Langchain的Memory模块通常有几种形态ConversationBufferMemory缓存全部历史对话。适用于上下文窗口足够大、对话轮次少的场景。ConversationBufferWindowMemory只保留最近K轮。适合多轮对话中的“短期记忆”用滑动窗口避免token膨胀。ConversationSummaryMemory定期总结历史对话把摘要当记忆保存。适合长对话场景代价是会增加一次模型调用有额外延迟。VectorStoreRetrieverMemory把历史对话向量化检索时按相关性回忆。适合需要从大量历史中找到特定信息的场景。实际中我经常组合使用短期会话用窗口记忆长期知识用向量检索复杂任务先用摘要压缩历史再继续推理。没有一种记忆方案能适配所有场景按需组合才是正解。3.5 自定义工具从“查天气”到“查数据库”工具调用是Agent最有价值的能力之一。我做过一个内部工具让Agent能够执行SQL查询数据库。实现起来并不复杂先定义一个函数接收用户问题的相关参数执行查询并返回结果。比如query_user_by_name(name: str) - str函数内部连接数据库执行SQL把结果格式化成字符串返回。然后用Langchain的tool装饰器把这个函数注册为工具让模型知道这个函数的存在和用途。有一个细节值得注意工具返回的数据必须是“模型看得懂的”。如果函数返回的是一个Python对象或DataFrame模型无法直接处理必须先把数据转成简洁的字符串。比如从数据库查出100行数据你不要全部塞给模型可以先聚合、筛选、格式化再返回关键信息。这样既能节省token又能减少模型被无关数据干扰的概率。我还踩过一个坑工具执行耗时太长超过了模型请求的超时限制。解决办法是在工具定义里明确标注“此操作可能需要较长时间”或者把长耗时任务拆成两步——先创建任务再查询结果用异步机制规避超时问题。4. 试跑完整智能体从0到1的实战过程4.1 环境准备与依赖安装实战是最好的学习方式。下面我给出一个最简可运行的环境搭建流程和示例代码尽量少说概念直接复现。我建议用Python3.10以上的版本创建一个虚拟环境然后安装依赖pip install langchain langchain-openai langchain-community chromadb tiktoken如果你的接口兼容OpenAI规范配置非常简单from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o-mini, temperature0.3, api_key你的API密钥, base_urlhttps://你的接口地址/v1 # 可选使用兼容服务时配置 )这里把温度设为0.3是比较合适的——智能体任务需要一定的确定性完全随机高温会让工具调用不稳定。如果你用的是第三方开源模型的兼容接口同样通过base_url接入Langchain对此支持得很好。4.2 构建RAG检索管线的完整代码下面是我最常用的一个RAG管线示例把文档加载、切分、向量化、检索几个环节都串进去了from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA # 1. 加载文档 loader TextLoader(data/产品手册.txt, encodingutf-8) documents loader.load() # 2. 切分文档 splitter RecursiveCharacterTextSplitter( chunk_size400, chunk_overlap50, separators[\n\n, \n, 。, , , , ] ) chunks splitter.split_documents(documents) # 3. 创建向量存储 embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectorstore Chroma.from_documents( documentschunks, embeddingembeddings, persist_directory./chroma_db ) # 4. 构建检索问答链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(search_kwargs{k: 4}) ) # 5. 查询测试 result qa_chain.invoke(这款产品的安装步骤是什么) print(result[result])这里有很多参数值得逐一说清楚。chunk_size400意味着每块约400字符适合做比较精准的召回如果你的文档段落很长、需要整体理解可以调大一些。k4表示一次检索返回4条相关片段太少可能漏信息太多会稀释上下文4到6是经验值。chain_type有“stuff”、“map_reduce”、“refine”等选项。stuff最简单把所有检索结果一次性拼进prompt适合结果集小、质量要求高的场景map_reduce把每条结果分别处理再合并总结适合结果集大但容易超限的场景。我的经验是默认用stuff等出现超限再考虑换类型。4.3 打造一个能调用搜索与计算工具的AgentRAG日常再好用也只是“从库里查答案”。要做一个真正能“干活”的Agent核心是工具调用。下面这段代码演示了如何给Agent加上搜索和计算两类工具from langchain_core.tools import tool from langchain.agents import create_react_agent, AgentExecutor from langchain_core.prompts import PromptTemplate # 定义工具1通用搜索引擎 tool def web_search(query: str) - str: 当用户询问实时信息、新闻、最新动态等或本地知识库无法回答时使用。 return 模拟搜索结果 query 相关的最新信息 # 定义工具2数学计算 tool def calculator(expression: str) - str: 当用户需要进行数学运算时使用传入标准的数学表达式例如12*3 return str(eval(expression)) tools [web_search, calculator] prompt PromptTemplate.from_template( 你是一个智能助手可以根据问题选择合适的工具。 工具列表 {tools} 工具名称[{tool_names}] 回答要求逐步思考如果需要使用工具请明确输出工具名和参数。 用户问题{input} 思考过程{agent_scratchpad} ) agent create_react_agent(llmllm, toolstools, promptprompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, max_iterations5) resp agent_executor.invoke({input: 帮我计算25*37同时查一下今天的天气}) print(resp[output])运行这个代码你会发现模型会“决定”先调用计算器再调用搜索引擎两次调用之间有思考过程的回溯。这个回溯就是ReAct循环模型自己判断当前状态、选择下一动作、观察动作结果、再判断是否结束。这里有一个重要参数max_iterations。如果没有这个限制Agent在处理模糊任务时可能陷入无限循环反复调用工具而不输出结果。我在生产环境设置为6-8次再高就该检查工具定义是否有问题了。4.4 流式输出与回调监控的接入初学者往往忽略流式输出和日志但这两项在实际部署中必不可少。流式输出能让用户看到模型实时的token生成过程而不是苦等五六秒才看到一坨文字回调机制能让你监控每一步的耗时、token消耗、工具调用内容。from langchain_core.callbacks import StreamingStdOutCallbackHandler callbacks [StreamingStdOutCallbackHandler()] llm_stream ChatOpenAI( modelgpt-4o-mini, temperature0.3, streamingTrue, callbackscallbacks ) agent_executor_with_stream AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, callbackscallbacks )在Langchain里回调链是可以向子组件传播的你设置了一次回调链中的模型调用、检索器调用、工具调用都会触发对应的事件。我一般在生产环境里重写一个回调处理器把事件输出到结构化日志JSON格式这样排查问题时就一目了然——用户问了什么、模型调了哪个工具、工具返回了什么、最终答了什么全链路可追踪。5. 常见疑难杂症与排查思路5.1 模型答非所问检索结果不相关的系统性排查如果你发现回答质量差先别急着调prompt按以下顺序排查第一步验证检索质量。直接打印retriever返回的chunk内容看这些片段跟用户问题有没有关系。如果检索出来的东西本身相关性就差后端模型再强也白搭。这一步最常出现的问题是切分不合理——一条知识被拦腰截断在多个块里。第二步验证prompt是否把检索结果讲清楚。把最终发送给模型的prompt完整打印出来用标准格式标注“这是检索到的参考内容”、“这是用户的问题”让模型清楚自己的角色。第三步验证模型对检索结果的利用程度。有些模型版本比较“倔”过度依赖自己的内在知识不乐意看外部参考。这种情况可以在prompt里强调“依据参考内容回答不要使用自己的先验知识”或者在检索结果中明确标出来源序号提高引用权重。第四步检查Embedding模型是否合适。对于专业领域文档医学、法律、软件工程通用Embedding往往表现不佳建议在领域数据上微调一个Embedding模型或者使用领域适配的文本向量模型。5.2 Agent循环出不来工具调用不生效Agent最常见的故障就是“无限循环”或“错误调参”。我有一次遇到Agent反复调用同一个工具每次都报参数格式错误——原因是模型的工具描述里要求JSON格式参数但模型输出的格式总差一个引号。解决办法很实用在工具函数内部做健壮性处理。不要假设模型会乖乖传入标准参数函数开头先清洗参数、加try/except拦截异常返回报错信息也比直接崩溃强。比如tool def calculator(expression: str) - str: try: return str(eval(expression)) except Exception as e: return f表达式错误{e}。请重新输入合法的表达式。把错误信息返回给模型模型会读报错并尝试修正。这种“容错式设计”大幅提升Agent的稳定性。另一个常见问题是缓存冲突。当你改了工具代码Langchain可能会缓存旧的工具模式导致Agent还在按老规则调用。重启进程或者清理缓存目录就能解决。5.3 Token超限与上下文管理的实用技巧你使用的模型上下文窗口再大也不能无限制往里面塞数据。RAG检索召回10条片段、每条500字符再加上系统提示词、历史对话、工具定义很容易就逼近上限。控制Token开销的几个实用招数压缩检索片段召回之后加一步“压缩/提取关键句”的模型调用用一次便宜的小模型调用把长文本浓缩成核心要点。减少召回的片段数k值从6降到3配合重排序消除“凑数片段”。精简系统提示词把系统提示词控制在1000字符以内重点写清“角色边界输出要求”不要啰嗦。历史对话轮次控制即便用窗口记忆窗口大小也别太大。我一般保留最近4轮完整对话更早的历史交给摘要记忆处理。还有一个容易忽略的坑Langchain框架层面有Token计算功能但你自定义工具返回的内容不会自动算进去。如果你工具返回了一大坨数据模型上下文可能瞬间爆炸。解决方案是在工具内部做数据截断与聚合把返回体量控制在预期范围内。5.4 常见报错速查表下面整理我个人常遇到的报错及处理办法供大家按图索骥报错信息原因解决方案ModuleNotFoundError: langchain依赖未安装检查虚拟环境是否激活重新安装依赖Unauthorized/AuthenticationErrorAPI Key错误检查环境变量或配置文件中的密钥是否有效RateLimitError请求频率超限增加重试机制、降低并发或使用异步调用控制速率ContextLengthExceededPrompt过长减少召回片段数、压缩历史对话、精简系统提示词Tool not foundAgent的工具定义丢失检查tools列表是否完整传入AgentExecutorIndexError或KeyError检索结果为空或格式异常检查文档是否成功切分打印chunks列表确认重要提示在生产环境请务必给大模型调用加上重试和降级逻辑。网络抖动、上游限流都是常态没有重试机制的应用用户体验会非常差而且排查问题时异常日志也很难定位到真正原因。6. 进阶扩展从Demo到可部署应用的几条路径6.1 多Agent协作复杂任务的分解策略单个Agent的能力边界受限于其单轮决策能力。当任务很复杂例如“帮我把这个月的销售数据做个分析报告并发给团队”一个Agent要处理数据提取、分析、写报告、发邮件多个环节决策链条太长容易中途出错。多Agent方案就是把大任务拆成多个专职Agent数据分析Agent、报告生成Agent、邮件发送Agent。它们之间有一个“主管Agent”负责调度和汇总。Langchain生态里有支持这种编排的工具不同Agent独立维护工具集和提示词主管Agent决定把任务分给哪个子Agent以及如何组合各自的输出。我在实践中的体会是多Agent并非越多越好每多一个Agent就多一层不稳定性和维护成本。业务复杂度不足以支撑分工时单Agent反而更可靠。6.2 从Langchain到LangGraph状态机的升级思维如果你接触Langchain比较早现在再打开官方文档会发现推荐优先用LangGraph。简单说LangGraph把Agent流程建模成一张有向图节点是各种操作模型调用、工具调用、条件判断边是流转路径。相比老版的AgentExecutorLangGraph最大的优势是可以精细控制循环结构实现条件分支、人工介入、多Agent协作这些复杂流程。我个人建议如果你还在入门阶段用基础的AgentExecutor能更快跑通一旦你的流程里出现“如果模型置信度不够就转人工”这类条件逻辑请果断切换到LangGraph。它本质上还是Langchain生态学习成本是递进的不是推倒重来。6.3 部署与监控智能体也要上Observing工具最后聊一个很多教程不会细讲的部分部署后的可观测性。大模型应用的出错率比传统软件高出几个量级而且错误往往是“非确定性”的——同一个问题模型前一次答对了后一次可能答错。我的建议是尽早接入观测体系核心看三类数据调用上报每次大模型调用的延迟、Token消耗、模型版本必须记录在案。追踪链路一次用户请求内部的多次模型调用、工具调用之间的关联关系用链路追踪还原全过程。质量评测对RAG场景可以批量跑一组评估集统计检索命中率和最终回答的准确性以此判断系统迭代是否真的变好了。这些数据积累起来才能支撑你后续优化系统——没有度量就没有优化。就我个人而言Langchain学起来不难难的是理解“为什么需要这些抽象”。当你亲手把一个朴素的API调用改造成一个具备检索增强、工具调用、记忆管理的智能体时你会对“大模型应用工程”有完全不一样的感觉。这个领域还在快速演进框架本身的版本更迭也很快但底层的数据流、工具调用、上下文管理这些核心思路是很稳定的。我踩过的坑希望你能少踩一些。 
长河君 · 2026/10/17 8:27:49 · 阅读 1.2k Langchain实战：从入门到搭建RAG与Agent智能体系统
最近大模型的应用已经从“能聊天”进化到“能干活”的阶段而Langchain在这股浪潮里几乎是绕不开的基础设施。我自己从最早用API裸调到后来上手Langchain再到用它搭出一套能跑通RAG和Agent的智能体系统中间踩了不少坑也攒了不少心得。这篇博文就把我从入门到实战的路径拆开来讲重点是LLM接入、RAG检索增强、Agent工具调用这三块核心希望能给正在学Langchain或者准备做智能体项目的朋友一份能直接上手的参考。1. Langchain到底解决了什么问题1.1 从“调API”到“搭系统”的跨越先说说我为什么从裸调API转向Langchain。最早做AI应用本质就是封装大模型接口你发一段prompt模型回一段文字然后你自己处理字符串、管上下文、做日志。这套流程在demo阶段完全够用但一旦涉及多个步骤、外部数据源、工具调用代码就变得极其臃肿。举个例子你做一个“查询公司内部知识库并生成摘要”的功能。裸调API的话你需要自己写向量化逻辑、自己管理向量数据库连接、自己拼接检索结果和用户问题、自己处理模型返回格式异常。这些代码彼此耦合换个模型或者换个向量库就要大改。而Langchain做的事就是把这套流水线的公共部分抽象成标准组件你用搭积木的方式把功能串起来业务逻辑清晰很多后期维护和替换组件也方便。很多刚接触的朋友会问Langchain是不是必须学如果你只是写个一次性用的脚本确实不需要。但如果你要长期维护一个智能体应用或者要快速迭代多个功能Langchain的组件化设计能帮你省掉大量重复劳动。1.2 核心组件一览链、模型、记忆、检索、智能体Langchain的功能模块可以按照大模型应用的通用架构来理解不需要一上来就背概念我先按常用程度排个序模型封装Model I/O统一了不同厂商模型OpenAI、开源模型等的调用方式。你在代码里换模型只需要改配置不用改业务逻辑。我自己习惯把模型名称、温度、max_tokens都放在配置文件里切换模型时只动配置不动代码。检索增强Retrieval对应RAG的核心环节包括文档加载、切分、向量化、存储、查询。Langchain把这一整条链路都标准化了Loader处理不同格式的文档TextSplitter控制切分方式VectorStore接口对接各种向量数据库。记忆管理Memory解决多轮对话中的上下文保持问题。智能体不能每次都是“失忆状态”需要把历史对话归纳、压缩、存储。链Chain把多个步骤编排成流水线。比如“检索-生成-校验”三步就是一条链。Langchain里面链的概念有点多但本质上就是函数的组合、流程的串联。智能体Agent比链更灵活。链是固定流程Agent是模型自己决定下一步干什么、调用哪个工具、什么时候结束。这个区别非常关键后面我会详细展开。回调机制Callbacks用于监控、日志、跟踪。这在生产环境几乎是必需的你可以监听模型调用的开始、结束、报错把信息输出到日志系统。理解这些组件的定位之后你再看Langchain的复杂文档就不会慌——它本质上就是一个“大模型应用的操作系统”各个组件就是标准接口的零件。2. 智能体系统的整体设计思路2.1 从需求倒推架构知识库问答是绝佳的起点我建议入门智能体的第一站做一个基于RAG的知识库问答系统然后再往外挂工具、做成真正的Agent。因为知识库问答的骨架是完整的加载文档、向量化、检索、生成回答每一环都有明确输入输出适合理解数据流向。我之前带过几位实习生直接让他们上手Agent工具调用结果往往一头雾水。后来调整策略先花两天做一个“简历问答系统”把几份简历文档喂进去让模型回答相关问题基本就理解了RAG的完整流程。让数据先流动起来再考虑智能体决策的问题学习曲线平滑得多。2.2 平衡复杂度什么时候用Chain什么时候用Agent这里有一个非常务实的取舍问题。Agent虽然智能但它引入了不确定性——模型可能会调用错误的工具、生成无效的参数甚至陷入循环。如果你的业务步骤是固定的比如先检索、再总结、再翻译用Chain就行了没必要让模型做决策。Chain执行链路稳定、耗时可控、调试方便。那么什么时候该上Agent当任务路径高度不确定的时候。比如一个助手需要根据用户的不同问题决定“查天气还是查日历还是发邮件”这个决策逻辑用代码写很繁琐让模型基于工具描述自己决策反而更自然。我个人的经验是能用Chain解决的绝不硬上AgentAgent是补足灵活性的手段而不是越复杂越好。实际项目中往往是混合架构——固定流程用Chain编排需要动态决策的节点挂Agent作为子模块。2.3 技术选型模型、向量库、Embedding的最佳开局组合开局阶段不用追求最新最强的技术要追求“能跑通、易调试、社区资料多”。以下是我验证过比较省心的组合模块推荐选择理由LLMOpenAI GPT系列接口工具调用成熟、生态完善初学阶段省去很多兼容性问题EmbeddingOpenAI Embedding或开源BGE系列BGE在中文场景表现稳定OpenAI的接入最简单向量数据库Chroma本地起步/ Milvus生产Chroma零配置直接跑Milvus适合数据量大时切换框架版本Langchain 0.x注意新老版本差异社区讨论多踩坑时容易搜到解决方案提示模型和向量库领域发展非常快不要迷信“最强”组合先选一套资料最多的方案跑通全流程再逐步替换你觉得不合适的组件。2.4 项目结构规划别把所有代码写在Jupyter里很多初学者喜欢在Jupyter Notebook里验证思路这没问题但正式做项目一定要按模块组织代码。我常用的目录结构是这样的agent_project/ ├── config/ # 配置文件模型参数、API Key、路径 ├── data/ # 文档原始数据 ├── documents/ # 切分后的文档缓存 ├── src/ │ ├── llm.py # 模型实例化与统一入口 │ ├── retriever.py # 索引构建与检索模块 │ ├── memory.py # 对话记忆管理 │ ├── tools/ # 自定义工具集 │ ├── agent.py # Agent编排核心 │ └── chains.py # 固定流程链的封装 ├── tests/ # 针对检索、工具调用的单元测试 └── app.py # 入口CLI或Web API这种结构的好处是当你想把一个模块替换掉比如换向量库影响面被限制在对应文件里。我见过太多人把所有逻辑堆在一个脚本里最后改一行代码牵连一片所有时间都花在“搞清楚这段代码干嘛的”上面了。3. 核心环节实操RAG与Agent的实现细节3.1 文档加载与切分切分策略直接影响检索质量RAG的第一步是让模型“读”你的文档。这里的核心不是加载而是切分——不同切分方式会直接决定后续检索的命中率。我常用的切分策略是递归字符切分法Langchain里叫RecursiveCharacterTextSplitter。它有几个关键参数chunk_size每个块的长度。我之前用500字符后来在中文场景下调整为300-400效果更稳因为中文信息密度高。chunk_overlap相邻块的重复区域。不设置重叠的话一个问题正好卡在两个块的边界上检索时两边都差一点信息回答就会残缺。我一般设置50字符左右。separators分隔符优先级。按段落、句子、字符的顺序逐级切割。实操时需要注意如果原始文档是Markdown或者HTML先用对应的Loader解析出结构再切分。直接按纯文本切分会把代码块、表格、列表打得稀碎检索结果基本没法看。我遇到过一次把Excel表格导入后切分模型生成的回答完全错乱就是因为表格被切成了无意义的碎片。3.2 向量化与检索找到“语义相似”而不是“字面匹配”向量化的意义是把文本映射为高维向量检索时通过向量距离找到语义相近的内容。这句话说起来简单但有个常见的误区很多人以为向量检索是万能的于是放弃关键词检索。实际上多个检索策略融合才是RAG工程的常态。我现在的做法是混合检索Hybrid Search先用关键词如BM25粗筛一轮再做向量相似度精排最后用重排序模型Reranker综合打分。纯向量检索的问题是专有名词、缩写、编号这些场景语义向量往往会忽略字面信息。比如用户搜“YOLO v5”语义向量可能匹配到“目标检测模型”这种宽泛描述而不是精确到版本的文档。关于向量库的选择我一开始用Chroma图省事数据到了百万级就撑不住了。后来迁移到Milvus性能提升明显。但Milvus的部署和运维成本高不少团队规模小的时候性价比不一定划算。建议数据量在十万条以下Chroma或单机FAISS完全够用数据量大且并发高再考虑分布式向量库。3.3 Agent核心机制从ReAct到Function CallingAgent与传统Chain的根本区别在于“循环决策”能力。这里简单拆解一下主流的Agent工作机制。ReAct模式Reason and Act是最早的agent范式思路是让模型循环执行两步推理reasoning和行动action。模型先分析当前状态决定需要调用什么工具把工具和参数输出为指定格式执行工具后把结果返回给模型继续推理直到模型判定任务完成。Langchain的ZeroShotAgent就是按这个思路实现的。后来OpenAI接口直接支持了Function Calling机制平台在API层面帮你做了输出约束模型输出的就是结构化调用参数不需要在prompt里来回强迫模型输出JSON了。Langchain对此做了很好的适配你定义好工具函数框架负责解析模型返回的调用请求并在内存中执行。实操中最关键的是工具定义的质量。Langchain里定义一个工具通常需要绑定函数的名称、描述和参数结构。模型自己不能“看”函数内部的实现它只根据函数名和描述决定何时调用。所以工具描述写得是否清晰直接决定Agent能不能正确使用它。不要写“一个有用的小工具”要写清“何时使用、输入参数含义、返回值结构、注意事项”。3.4 记忆机制的四种形态智能体的记忆不是把聊天记录原样塞进上下文那是新手最容易犯的错误。上下文窗口是有限的塞多了不仅浪费token还会让模型“迷失”在无关历史里。Langchain的Memory模块通常有几种形态ConversationBufferMemory缓存全部历史对话。适用于上下文窗口足够大、对话轮次少的场景。ConversationBufferWindowMemory只保留最近K轮。适合多轮对话中的“短期记忆”用滑动窗口避免token膨胀。ConversationSummaryMemory定期总结历史对话把摘要当记忆保存。适合长对话场景代价是会增加一次模型调用有额外延迟。VectorStoreRetrieverMemory把历史对话向量化检索时按相关性回忆。适合需要从大量历史中找到特定信息的场景。实际中我经常组合使用短期会话用窗口记忆长期知识用向量检索复杂任务先用摘要压缩历史再继续推理。没有一种记忆方案能适配所有场景按需组合才是正解。3.5 自定义工具从“查天气”到“查数据库”工具调用是Agent最有价值的能力之一。我做过一个内部工具让Agent能够执行SQL查询数据库。实现起来并不复杂先定义一个函数接收用户问题的相关参数执行查询并返回结果。比如query_user_by_name(name: str) - str函数内部连接数据库执行SQL把结果格式化成字符串返回。然后用Langchain的tool装饰器把这个函数注册为工具让模型知道这个函数的存在和用途。有一个细节值得注意工具返回的数据必须是“模型看得懂的”。如果函数返回的是一个Python对象或DataFrame模型无法直接处理必须先把数据转成简洁的字符串。比如从数据库查出100行数据你不要全部塞给模型可以先聚合、筛选、格式化再返回关键信息。这样既能节省token又能减少模型被无关数据干扰的概率。我还踩过一个坑工具执行耗时太长超过了模型请求的超时限制。解决办法是在工具定义里明确标注“此操作可能需要较长时间”或者把长耗时任务拆成两步——先创建任务再查询结果用异步机制规避超时问题。4. 试跑完整智能体从0到1的实战过程4.1 环境准备与依赖安装实战是最好的学习方式。下面我给出一个最简可运行的环境搭建流程和示例代码尽量少说概念直接复现。我建议用Python3.10以上的版本创建一个虚拟环境然后安装依赖pip install langchain langchain-openai langchain-community chromadb tiktoken如果你的接口兼容OpenAI规范配置非常简单from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o-mini, temperature0.3, api_key你的API密钥, base_urlhttps://你的接口地址/v1 # 可选使用兼容服务时配置 )这里把温度设为0.3是比较合适的——智能体任务需要一定的确定性完全随机高温会让工具调用不稳定。如果你用的是第三方开源模型的兼容接口同样通过base_url接入Langchain对此支持得很好。4.2 构建RAG检索管线的完整代码下面是我最常用的一个RAG管线示例把文档加载、切分、向量化、检索几个环节都串进去了from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA # 1. 加载文档 loader TextLoader(data/产品手册.txt, encodingutf-8) documents loader.load() # 2. 切分文档 splitter RecursiveCharacterTextSplitter( chunk_size400, chunk_overlap50, separators[\n\n, \n, 。, , , , ] ) chunks splitter.split_documents(documents) # 3. 创建向量存储 embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectorstore Chroma.from_documents( documentschunks, embeddingembeddings, persist_directory./chroma_db ) # 4. 构建检索问答链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(search_kwargs{k: 4}) ) # 5. 查询测试 result qa_chain.invoke(这款产品的安装步骤是什么) print(result[result])这里有很多参数值得逐一说清楚。chunk_size400意味着每块约400字符适合做比较精准的召回如果你的文档段落很长、需要整体理解可以调大一些。k4表示一次检索返回4条相关片段太少可能漏信息太多会稀释上下文4到6是经验值。chain_type有“stuff”、“map_reduce”、“refine”等选项。stuff最简单把所有检索结果一次性拼进prompt适合结果集小、质量要求高的场景map_reduce把每条结果分别处理再合并总结适合结果集大但容易超限的场景。我的经验是默认用stuff等出现超限再考虑换类型。4.3 打造一个能调用搜索与计算工具的AgentRAG日常再好用也只是“从库里查答案”。要做一个真正能“干活”的Agent核心是工具调用。下面这段代码演示了如何给Agent加上搜索和计算两类工具from langchain_core.tools import tool from langchain.agents import create_react_agent, AgentExecutor from langchain_core.prompts import PromptTemplate # 定义工具1通用搜索引擎 tool def web_search(query: str) - str: 当用户询问实时信息、新闻、最新动态等或本地知识库无法回答时使用。 return 模拟搜索结果 query 相关的最新信息 # 定义工具2数学计算 tool def calculator(expression: str) - str: 当用户需要进行数学运算时使用传入标准的数学表达式例如12*3 return str(eval(expression)) tools [web_search, calculator] prompt PromptTemplate.from_template( 你是一个智能助手可以根据问题选择合适的工具。 工具列表 {tools} 工具名称[{tool_names}] 回答要求逐步思考如果需要使用工具请明确输出工具名和参数。 用户问题{input} 思考过程{agent_scratchpad} ) agent create_react_agent(llmllm, toolstools, promptprompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, max_iterations5) resp agent_executor.invoke({input: 帮我计算25*37同时查一下今天的天气}) print(resp[output])运行这个代码你会发现模型会“决定”先调用计算器再调用搜索引擎两次调用之间有思考过程的回溯。这个回溯就是ReAct循环模型自己判断当前状态、选择下一动作、观察动作结果、再判断是否结束。这里有一个重要参数max_iterations。如果没有这个限制Agent在处理模糊任务时可能陷入无限循环反复调用工具而不输出结果。我在生产环境设置为6-8次再高就该检查工具定义是否有问题了。4.4 流式输出与回调监控的接入初学者往往忽略流式输出和日志但这两项在实际部署中必不可少。流式输出能让用户看到模型实时的token生成过程而不是苦等五六秒才看到一坨文字回调机制能让你监控每一步的耗时、token消耗、工具调用内容。from langchain_core.callbacks import StreamingStdOutCallbackHandler callbacks [StreamingStdOutCallbackHandler()] llm_stream ChatOpenAI( modelgpt-4o-mini, temperature0.3, streamingTrue, callbackscallbacks ) agent_executor_with_stream AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, callbackscallbacks )在Langchain里回调链是可以向子组件传播的你设置了一次回调链中的模型调用、检索器调用、工具调用都会触发对应的事件。我一般在生产环境里重写一个回调处理器把事件输出到结构化日志JSON格式这样排查问题时就一目了然——用户问了什么、模型调了哪个工具、工具返回了什么、最终答了什么全链路可追踪。5. 常见疑难杂症与排查思路5.1 模型答非所问检索结果不相关的系统性排查如果你发现回答质量差先别急着调prompt按以下顺序排查第一步验证检索质量。直接打印retriever返回的chunk内容看这些片段跟用户问题有没有关系。如果检索出来的东西本身相关性就差后端模型再强也白搭。这一步最常出现的问题是切分不合理——一条知识被拦腰截断在多个块里。第二步验证prompt是否把检索结果讲清楚。把最终发送给模型的prompt完整打印出来用标准格式标注“这是检索到的参考内容”、“这是用户的问题”让模型清楚自己的角色。第三步验证模型对检索结果的利用程度。有些模型版本比较“倔”过度依赖自己的内在知识不乐意看外部参考。这种情况可以在prompt里强调“依据参考内容回答不要使用自己的先验知识”或者在检索结果中明确标出来源序号提高引用权重。第四步检查Embedding模型是否合适。对于专业领域文档医学、法律、软件工程通用Embedding往往表现不佳建议在领域数据上微调一个Embedding模型或者使用领域适配的文本向量模型。5.2 Agent循环出不来工具调用不生效Agent最常见的故障就是“无限循环”或“错误调参”。我有一次遇到Agent反复调用同一个工具每次都报参数格式错误——原因是模型的工具描述里要求JSON格式参数但模型输出的格式总差一个引号。解决办法很实用在工具函数内部做健壮性处理。不要假设模型会乖乖传入标准参数函数开头先清洗参数、加try/except拦截异常返回报错信息也比直接崩溃强。比如tool def calculator(expression: str) - str: try: return str(eval(expression)) except Exception as e: return f表达式错误{e}。请重新输入合法的表达式。把错误信息返回给模型模型会读报错并尝试修正。这种“容错式设计”大幅提升Agent的稳定性。另一个常见问题是缓存冲突。当你改了工具代码Langchain可能会缓存旧的工具模式导致Agent还在按老规则调用。重启进程或者清理缓存目录就能解决。5.3 Token超限与上下文管理的实用技巧你使用的模型上下文窗口再大也不能无限制往里面塞数据。RAG检索召回10条片段、每条500字符再加上系统提示词、历史对话、工具定义很容易就逼近上限。控制Token开销的几个实用招数压缩检索片段召回之后加一步“压缩/提取关键句”的模型调用用一次便宜的小模型调用把长文本浓缩成核心要点。减少召回的片段数k值从6降到3配合重排序消除“凑数片段”。精简系统提示词把系统提示词控制在1000字符以内重点写清“角色边界输出要求”不要啰嗦。历史对话轮次控制即便用窗口记忆窗口大小也别太大。我一般保留最近4轮完整对话更早的历史交给摘要记忆处理。还有一个容易忽略的坑Langchain框架层面有Token计算功能但你自定义工具返回的内容不会自动算进去。如果你工具返回了一大坨数据模型上下文可能瞬间爆炸。解决方案是在工具内部做数据截断与聚合把返回体量控制在预期范围内。5.4 常见报错速查表下面整理我个人常遇到的报错及处理办法供大家按图索骥报错信息原因解决方案ModuleNotFoundError: langchain依赖未安装检查虚拟环境是否激活重新安装依赖Unauthorized/AuthenticationErrorAPI Key错误检查环境变量或配置文件中的密钥是否有效RateLimitError请求频率超限增加重试机制、降低并发或使用异步调用控制速率ContextLengthExceededPrompt过长减少召回片段数、压缩历史对话、精简系统提示词Tool not foundAgent的工具定义丢失检查tools列表是否完整传入AgentExecutorIndexError或KeyError检索结果为空或格式异常检查文档是否成功切分打印chunks列表确认重要提示在生产环境请务必给大模型调用加上重试和降级逻辑。网络抖动、上游限流都是常态没有重试机制的应用用户体验会非常差而且排查问题时异常日志也很难定位到真正原因。6. 进阶扩展从Demo到可部署应用的几条路径6.1 多Agent协作复杂任务的分解策略单个Agent的能力边界受限于其单轮决策能力。当任务很复杂例如“帮我把这个月的销售数据做个分析报告并发给团队”一个Agent要处理数据提取、分析、写报告、发邮件多个环节决策链条太长容易中途出错。多Agent方案就是把大任务拆成多个专职Agent数据分析Agent、报告生成Agent、邮件发送Agent。它们之间有一个“主管Agent”负责调度和汇总。Langchain生态里有支持这种编排的工具不同Agent独立维护工具集和提示词主管Agent决定把任务分给哪个子Agent以及如何组合各自的输出。我在实践中的体会是多Agent并非越多越好每多一个Agent就多一层不稳定性和维护成本。业务复杂度不足以支撑分工时单Agent反而更可靠。6.2 从Langchain到LangGraph状态机的升级思维如果你接触Langchain比较早现在再打开官方文档会发现推荐优先用LangGraph。简单说LangGraph把Agent流程建模成一张有向图节点是各种操作模型调用、工具调用、条件判断边是流转路径。相比老版的AgentExecutorLangGraph最大的优势是可以精细控制循环结构实现条件分支、人工介入、多Agent协作这些复杂流程。我个人建议如果你还在入门阶段用基础的AgentExecutor能更快跑通一旦你的流程里出现“如果模型置信度不够就转人工”这类条件逻辑请果断切换到LangGraph。它本质上还是Langchain生态学习成本是递进的不是推倒重来。6.3 部署与监控智能体也要上Observing工具最后聊一个很多教程不会细讲的部分部署后的可观测性。大模型应用的出错率比传统软件高出几个量级而且错误往往是“非确定性”的——同一个问题模型前一次答对了后一次可能答错。我的建议是尽早接入观测体系核心看三类数据调用上报每次大模型调用的延迟、Token消耗、模型版本必须记录在案。追踪链路一次用户请求内部的多次模型调用、工具调用之间的关联关系用链路追踪还原全过程。质量评测对RAG场景可以批量跑一组评估集统计检索命中率和最终回答的准确性以此判断系统迭代是否真的变好了。这些数据积累起来才能支撑你后续优化系统——没有度量就没有优化。就我个人而言Langchain学起来不难难的是理解“为什么需要这些抽象”。当你亲手把一个朴素的API调用改造成一个具备检索增强、工具调用、记忆管理的智能体时你会对“大模型应用工程”有完全不一样的感觉。这个领域还在快速演进框架本身的版本更迭也很快但底层的数据流、工具调用、上下文管理这些核心思路是很稳定的。我踩过的坑希望你能少踩一些。