如果你最近在尝试用 AI 大模型做点实际应用大概率会遇到这几个问题明明模型能力很强但一接入真实业务就发现单次对话解决不了复杂任务想让它按固定格式输出它总给你意外惊喜希望它能调用工具、查资料、执行多步操作但自己写调度逻辑又异常繁琐。这背后其实是一个更本质的问题——我们到底需要什么样的“胶水层”才能把大模型的能力真正固化到工作流里LangChain 的出现正是为了解决这类问题。它不是另一个模型而是一套开发框架帮你把大模型、工具链、数据源和任务逻辑“链”起来。尤其是从早期版本迭代到 V1.3 后LangChain 在模块化、稳定性和工程化程度上都有了明显提升。但很多人学 LangChain 容易陷入两个误区要么被它繁杂的模块吓退只敢跑官方示例要么盲目套用高级功能却连最基本的 Prompt 控制都做不稳。这篇文章不会只讲“LangChain 有什么”而是聚焦“怎么用它把想法落地”尤其是如何结合 Prompt 工程、Agent 机制和 RAG 架构把一个概念变成可复用的项目。1. 先理解 LangChain 到底解决了什么而不仅仅是它包含了什么LangChain 的官方文档会列出几十个模块Models、Prompts、Chains、Agents、Memory、Indexes……但如果你按模块顺序学很容易迷失在细节里。其实从工程角度LangChain 核心只做三件事标准化输入输出、编排任务流程、连接外部资源。V1.3 版本在这三件事上做了大量优化比如更好的错误提示、更清晰的接口约定、更稳定的 Agent 执行逻辑。举个例子你想让大模型帮你分析一篇技术文章并提取关键术语。如果直接调用 API你需要自己处理文章分段、术语定义提示词、结果解析、错误重试。而用 LangChain你可以用TextSplitter处理长文本用PromptTemplate固化提取逻辑用LLMChain把流程串起来再用OutputParser确保返回结构一致。这背后的价值不是省几行代码而是把一次性的临时脚本变成了可复用、可调试、可扩展的数据处理管道。LangChain 的另一个关键设计是“松耦合”。它不绑定特定模型你可以轻松切换 OpenAI、通义千问、本地部署的模型只要适配了统一接口。这在模型迭代飞快的今天尤其重要——今天用的模型可能下个月就有更强替代品但你的业务逻辑不需要重写。注意LangChain 本身不解决模型能力上限的问题。如果模型基础能力不足再好的框架也无力回天。所以选型时要先确认模型能否完成核心任务再用 LangChain 做工程化包装。2. Prompt 提示词工程别再把提示词当成“对话开场白”很多人误以为 Prompt 就是“用更聪明的话问模型”结果每次测试都要重新调整措辞。在 LangChain 中Prompt 是被当作可配置、可复用、可验证的工程组件来设计的。V1.3 对 Prompt 的校验更严格比如会检查 System Message 位置、变量填充完整性等避免运行时才报错。2.1 从静态文本到参数化模板直接拼接字符串的方式非常脆弱# 不推荐 prompt 请分析以下文章 article 并提取三个关键词。LangChain 的PromptTemplate允许你定义带变量的模板from langchain.prompts import PromptTemplate template 你是一名技术文档分析师。请分析以下文章并提取关键术语。 文章{article} 请按以下格式返回 - 术语1解释1 - 术语2解释2 - 术语3解释3 prompt PromptTemplate( input_variables[article], templatetemplate )这样做的好处是提示词结构清晰变量集中管理更容易迭代优化。你可以把常用模板保存为文件团队共享。2.2 System Message 和 Human Message 的分工在 Chat 模型中System Message 用于设定角色和规则Human Message 是具体查询。V1.3 明确要求 System Message 必须在对话开始位置否则会报错system message must be at the beginning。正确的做法是使用ChatPromptTemplatefrom langchain.prompts import ChatPromptTemplate from langchain.schema import SystemMessage, HumanMessage system_template SystemMessage(content你是一名资深技术博主擅长用通俗语言解释复杂概念。) human_template HumanMessage(content请用生活类比解释什么是{RAG}。) chat_prompt ChatPromptTemplate.from_messages([ (system, system_template.content), (human, human_template.content) ])这种分离让角色设定和具体任务解耦同一个角色可以复用于不同任务。2.3 提示词验证与调试LangChain 提供了OutputParser来校验模型输出。比如你想让模型返回 JSON可以定义ResponseSchema并搭配StructuredOutputParserfrom langchain.output_parsers import StructuredOutputParser from langchain.schema import ResponseSchema response_schemas [ ResponseSchema(nameterm, description提取的术语), ResponseSchema(nameexplanation, description术语解释) ] parser StructuredOutputParser.from_response_schemas(response_schemas) format_instructions parser.get_format_instructions() # 把 format_instructions 加入提示词 template \n\n{format_instructions} prompt PromptTemplate( input_variables[article], partial_variables{format_instructions: format_instructions}, templatetemplate ) # 解析输出 try: output_dict parser.parse(model_response) except Exception as e: print(f解析失败{e})这种方式大幅减少了输出格式不匹配的问题特别适合自动化流程。3. Agent 机制不是所有任务都需要一步到位当任务需要多步决策或调用工具时就需要 Agent。LangChain 的 Agent 核心思想是让模型根据当前状态决定下一步做什么。V1.3 增强了 Agent 的稳定性减少了无意义循环和工具调用错误。3.1 Agent 的基本工作流程一个典型的 Agent 包含三个部分工具集Tools模型可以调用的函数如搜索、计算、API 调用。代理逻辑Agent决定使用哪个工具或直接回答。执行器AgentExecutor管理交互流程处理超时、错误等。示例创建一个能查询天气和计算的 Agentfrom langchain.agents import Tool, AgentType, initialize_agent from langchain.utilities import SerpAPIWrapper from langchain.llms import OpenAI # 定义工具 search SerpAPIWrapper() tools [ Tool( name搜索, funcsearch.run, description用于查询当前事件、天气、新闻等 ), Tool( name计算器, funclambda x: eval(x), # 生产环境需更安全实现 description用于数学计算 ) ] # 初始化 Agent agent initialize_agent( tools, OpenAI(temperature0), agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, verboseTrue ) # 执行复杂查询 result agent.run(北京今天的温度是多少如果是华氏度请转换成摄氏度。)这个例子中模型会先决定调用搜索工具获取温度再判断是否需要单位转换必要时调用计算器。3.2 如何避免常见 Agent 陷阱新手用 Agent 常遇到几个问题无限循环模型反复调用工具却不结束。可以通过max_iterations参数限制步数。工具选择错误模型误解工具描述。需要把工具描述写得更精确避免歧义。状态混乱多轮对话后模型忘记初始目标。合理使用Memory模块记录关键信息。V1.3 的AgentExecutor内置了更多防护比如超时控制、错误捕获但核心还是在于工具设计和提示词引导。3.3 实战构建一个技术文档查询 Agent假设你想做一个查询 LangChain 最新特性的 Agent可以这样设计# 假设已有文档检索工具 def search_docs(query: str) - str: # 实现基于向量库的检索 return relevant_text tools [ Tool( name文档检索, funcsearch_docs, description用于从LangChain文档中查询特定功能说明 ) ] agent initialize_agent( tools, llm, agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION, memoryConversationBufferMemory(), # 保留对话历史 verboseTrue ) query LangChain V1.3 在 Prompt 方面有什么改进 result agent.run(query)这种 Agent 适合内部知识库问答比直接问模型更准确因为答案来源受限且可追溯。4. RAG让模型“学会”你的私有知识RAGRetrieval-Augmented Generation可能是当前最实用的 AI 应用模式。它解决了一个核心矛盾大模型的知识是静态的而业务数据是动态的。RAG 通过“检索生成”的方式让模型能基于最新、私有的数据回答问题。4.1 RAG 的工作流程分解一个完整的 RAG 系统包含以下步骤文档加载从文件、数据库、API 获取原始数据。文本分割将长文档切分成适合检索的片段。向量化用 Embedding 模型将文本转为向量。存储索引将向量存入向量数据库如 Weaviate、Chroma。检索根据问题查找最相关的文档片段。生成将检索结果作为上下文生成最终答案。LangChain 为每一步提供了对应组件让 RAG 实现变得标准化。4.2 搭建一个企业知识库 RAG 系统以下是用 LangChain 实现 RAG 的关键代码框架from langchain.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.embeddings import OpenAIEmbeddings from langchain.vectorstores import Chroma from langchain.chains import RetrievalQA # 1. 加载文档 loader TextLoader(企业知识库.txt) documents loader.load() # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50 ) texts text_splitter.split_documents(documents) # 3. 创建向量库 embeddings OpenAIEmbeddings() vectorstore Chroma.from_documents(texts, embeddings) # 4. 构建 RAG 链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 还有其他方式如 map_reduce retrievervectorstore.as_retriever(), return_source_documentsTrue # 返回参考来源 ) # 5. 提问 question 我们公司的请假流程是什么 result qa_chain({query: question}) print(f答案{result[result]}) print(f参考文档{result[source_documents]})4.3 RAG 的优化方向基础 RAG 容易遇到检索不准、生成幻觉等问题。可以考虑以下优化分层检索先检索章节标题再定位具体内容。重排序ReRank用更精细的模型对检索结果重新排序。HyDE 技术让模型先生成假设答案再用假设答案去检索。多查询扩展从原问题生成多个相关问题合并检索结果。LangChain 的MultiQueryRetriever、ContextualCompressionRetriever等组件支持这些高级用法。5. 项目落地从实验脚本到可维护系统很多人在本地跑通 Demo 后不知道如何推进到生产环境。其实关键在于补上工程化要素配置管理、错误处理、日志记录、性能监控。5.1 配置化与环境隔离不要硬编码 API Key、模型参数、文件路径。使用环境变量或配置文件import os from langchain.llms import OpenAI # 从环境变量读取配置 llm OpenAI( api_keyos.getenv(OPENAI_API_KEY), model_nameos.getenv(MODEL_NAME, gpt-3.5-turbo), temperaturefloat(os.getenv(TEMPERATURE, 0.1)) )不同环境开发、测试、生产使用不同配置避免相互影响。5.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.invoke(prompt) except Exception as e: print(f调用失败{e}) raise # 触发重试对于关键业务还要实现降级方案比如主模型失败时切换到备用模型。5.3 日志与监控记录每次调用的输入、输出、耗时、Token 用量便于排查问题和优化成本import logging import time logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) def logged_llm_call(prompt): start_time time.time() try: result llm.invoke(prompt) end_time time.time() logger.info(f调用成功耗时{end_time-start_time:.2f}秒) return result except Exception as e: logger.error(f调用失败{e}) raise长期项目还可以集成 Prometheus、Grafana 等监控工具。5.4 版本兼容性管理LangChain 更新较快需要注意版本兼容。比如 1.3.11 版本的 LangChain 需要匹配特定版本的langchain-community。使用requirements.txt或 Poetry 锁定依赖版本langchain1.3.11 langchain-community0.3.5 openai1.63.0升级前在测试环境充分验证避免破坏现有功能。6. 常见问题排查指南遇到问题不要盲目调整代码按以下顺序排查6.1 Prompt 相关错误prompt has no outputs检查 PromptTemplate 的 input_variables 是否与传入参数匹配。system message must be at the beginning确保 ChatPromptTemplate 中 System Message 是第一个元素。输出格式不符合预期使用 OutputParser 校验或简化 Prompt 逐步测试。6.2 Agent 执行异常工具调用失败检查工具函数是否正常返回描述是否清晰。无限循环设置max_iterations10添加超时控制。内存不足对话历史过长时使用ConversationSummaryMemory替代完整历史记录。6.3 RAG 效果不佳检索不到相关内容调整文本分割大小chunk_size优化 Embedding 模型。生成答案不准确在 Prompt 中明确要求“基于检索内容回答”减少模型幻觉。速度慢考虑缓存检索结果或使用更轻量级的 Embedding 模型。6.4 依赖和版本问题导入错误检查 LangChain 模块路径是否与版本匹配。V1.x 相比早期版本有大量重构。API 变更关注 LangChain 更新日志提前适配废弃接口。LangChain 的真正价值不在于功能多全而在于它提供了一套可组合、可测试、可扩展的范式。开始新项目时不要试图一次性用上所有高级功能。先从最简单的 LLMChain 做起确保单任务流程稳定再加入 Prompt 模板化让输入输出可控接着尝试 Agent 处理复杂决策最后用 RAG 接入私有数据。每一步都做好错误处理和日志记录这样构建的系统才能经得起实际使用。
LangChain实战：从Prompt工程到RAG架构的AI应用开发指南
如果你最近在尝试用 AI 大模型做点实际应用大概率会遇到这几个问题明明模型能力很强但一接入真实业务就发现单次对话解决不了复杂任务想让它按固定格式输出它总给你意外惊喜希望它能调用工具、查资料、执行多步操作但自己写调度逻辑又异常繁琐。这背后其实是一个更本质的问题——我们到底需要什么样的“胶水层”才能把大模型的能力真正固化到工作流里LangChain 的出现正是为了解决这类问题。它不是另一个模型而是一套开发框架帮你把大模型、工具链、数据源和任务逻辑“链”起来。尤其是从早期版本迭代到 V1.3 后LangChain 在模块化、稳定性和工程化程度上都有了明显提升。但很多人学 LangChain 容易陷入两个误区要么被它繁杂的模块吓退只敢跑官方示例要么盲目套用高级功能却连最基本的 Prompt 控制都做不稳。这篇文章不会只讲“LangChain 有什么”而是聚焦“怎么用它把想法落地”尤其是如何结合 Prompt 工程、Agent 机制和 RAG 架构把一个概念变成可复用的项目。1. 先理解 LangChain 到底解决了什么而不仅仅是它包含了什么LangChain 的官方文档会列出几十个模块Models、Prompts、Chains、Agents、Memory、Indexes……但如果你按模块顺序学很容易迷失在细节里。其实从工程角度LangChain 核心只做三件事标准化输入输出、编排任务流程、连接外部资源。V1.3 版本在这三件事上做了大量优化比如更好的错误提示、更清晰的接口约定、更稳定的 Agent 执行逻辑。举个例子你想让大模型帮你分析一篇技术文章并提取关键术语。如果直接调用 API你需要自己处理文章分段、术语定义提示词、结果解析、错误重试。而用 LangChain你可以用TextSplitter处理长文本用PromptTemplate固化提取逻辑用LLMChain把流程串起来再用OutputParser确保返回结构一致。这背后的价值不是省几行代码而是把一次性的临时脚本变成了可复用、可调试、可扩展的数据处理管道。LangChain 的另一个关键设计是“松耦合”。它不绑定特定模型你可以轻松切换 OpenAI、通义千问、本地部署的模型只要适配了统一接口。这在模型迭代飞快的今天尤其重要——今天用的模型可能下个月就有更强替代品但你的业务逻辑不需要重写。注意LangChain 本身不解决模型能力上限的问题。如果模型基础能力不足再好的框架也无力回天。所以选型时要先确认模型能否完成核心任务再用 LangChain 做工程化包装。2. Prompt 提示词工程别再把提示词当成“对话开场白”很多人误以为 Prompt 就是“用更聪明的话问模型”结果每次测试都要重新调整措辞。在 LangChain 中Prompt 是被当作可配置、可复用、可验证的工程组件来设计的。V1.3 对 Prompt 的校验更严格比如会检查 System Message 位置、变量填充完整性等避免运行时才报错。2.1 从静态文本到参数化模板直接拼接字符串的方式非常脆弱# 不推荐 prompt 请分析以下文章 article 并提取三个关键词。LangChain 的PromptTemplate允许你定义带变量的模板from langchain.prompts import PromptTemplate template 你是一名技术文档分析师。请分析以下文章并提取关键术语。 文章{article} 请按以下格式返回 - 术语1解释1 - 术语2解释2 - 术语3解释3 prompt PromptTemplate( input_variables[article], templatetemplate )这样做的好处是提示词结构清晰变量集中管理更容易迭代优化。你可以把常用模板保存为文件团队共享。2.2 System Message 和 Human Message 的分工在 Chat 模型中System Message 用于设定角色和规则Human Message 是具体查询。V1.3 明确要求 System Message 必须在对话开始位置否则会报错system message must be at the beginning。正确的做法是使用ChatPromptTemplatefrom langchain.prompts import ChatPromptTemplate from langchain.schema import SystemMessage, HumanMessage system_template SystemMessage(content你是一名资深技术博主擅长用通俗语言解释复杂概念。) human_template HumanMessage(content请用生活类比解释什么是{RAG}。) chat_prompt ChatPromptTemplate.from_messages([ (system, system_template.content), (human, human_template.content) ])这种分离让角色设定和具体任务解耦同一个角色可以复用于不同任务。2.3 提示词验证与调试LangChain 提供了OutputParser来校验模型输出。比如你想让模型返回 JSON可以定义ResponseSchema并搭配StructuredOutputParserfrom langchain.output_parsers import StructuredOutputParser from langchain.schema import ResponseSchema response_schemas [ ResponseSchema(nameterm, description提取的术语), ResponseSchema(nameexplanation, description术语解释) ] parser StructuredOutputParser.from_response_schemas(response_schemas) format_instructions parser.get_format_instructions() # 把 format_instructions 加入提示词 template \n\n{format_instructions} prompt PromptTemplate( input_variables[article], partial_variables{format_instructions: format_instructions}, templatetemplate ) # 解析输出 try: output_dict parser.parse(model_response) except Exception as e: print(f解析失败{e})这种方式大幅减少了输出格式不匹配的问题特别适合自动化流程。3. Agent 机制不是所有任务都需要一步到位当任务需要多步决策或调用工具时就需要 Agent。LangChain 的 Agent 核心思想是让模型根据当前状态决定下一步做什么。V1.3 增强了 Agent 的稳定性减少了无意义循环和工具调用错误。3.1 Agent 的基本工作流程一个典型的 Agent 包含三个部分工具集Tools模型可以调用的函数如搜索、计算、API 调用。代理逻辑Agent决定使用哪个工具或直接回答。执行器AgentExecutor管理交互流程处理超时、错误等。示例创建一个能查询天气和计算的 Agentfrom langchain.agents import Tool, AgentType, initialize_agent from langchain.utilities import SerpAPIWrapper from langchain.llms import OpenAI # 定义工具 search SerpAPIWrapper() tools [ Tool( name搜索, funcsearch.run, description用于查询当前事件、天气、新闻等 ), Tool( name计算器, funclambda x: eval(x), # 生产环境需更安全实现 description用于数学计算 ) ] # 初始化 Agent agent initialize_agent( tools, OpenAI(temperature0), agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, verboseTrue ) # 执行复杂查询 result agent.run(北京今天的温度是多少如果是华氏度请转换成摄氏度。)这个例子中模型会先决定调用搜索工具获取温度再判断是否需要单位转换必要时调用计算器。3.2 如何避免常见 Agent 陷阱新手用 Agent 常遇到几个问题无限循环模型反复调用工具却不结束。可以通过max_iterations参数限制步数。工具选择错误模型误解工具描述。需要把工具描述写得更精确避免歧义。状态混乱多轮对话后模型忘记初始目标。合理使用Memory模块记录关键信息。V1.3 的AgentExecutor内置了更多防护比如超时控制、错误捕获但核心还是在于工具设计和提示词引导。3.3 实战构建一个技术文档查询 Agent假设你想做一个查询 LangChain 最新特性的 Agent可以这样设计# 假设已有文档检索工具 def search_docs(query: str) - str: # 实现基于向量库的检索 return relevant_text tools [ Tool( name文档检索, funcsearch_docs, description用于从LangChain文档中查询特定功能说明 ) ] agent initialize_agent( tools, llm, agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION, memoryConversationBufferMemory(), # 保留对话历史 verboseTrue ) query LangChain V1.3 在 Prompt 方面有什么改进 result agent.run(query)这种 Agent 适合内部知识库问答比直接问模型更准确因为答案来源受限且可追溯。4. RAG让模型“学会”你的私有知识RAGRetrieval-Augmented Generation可能是当前最实用的 AI 应用模式。它解决了一个核心矛盾大模型的知识是静态的而业务数据是动态的。RAG 通过“检索生成”的方式让模型能基于最新、私有的数据回答问题。4.1 RAG 的工作流程分解一个完整的 RAG 系统包含以下步骤文档加载从文件、数据库、API 获取原始数据。文本分割将长文档切分成适合检索的片段。向量化用 Embedding 模型将文本转为向量。存储索引将向量存入向量数据库如 Weaviate、Chroma。检索根据问题查找最相关的文档片段。生成将检索结果作为上下文生成最终答案。LangChain 为每一步提供了对应组件让 RAG 实现变得标准化。4.2 搭建一个企业知识库 RAG 系统以下是用 LangChain 实现 RAG 的关键代码框架from langchain.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.embeddings import OpenAIEmbeddings from langchain.vectorstores import Chroma from langchain.chains import RetrievalQA # 1. 加载文档 loader TextLoader(企业知识库.txt) documents loader.load() # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50 ) texts text_splitter.split_documents(documents) # 3. 创建向量库 embeddings OpenAIEmbeddings() vectorstore Chroma.from_documents(texts, embeddings) # 4. 构建 RAG 链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 还有其他方式如 map_reduce retrievervectorstore.as_retriever(), return_source_documentsTrue # 返回参考来源 ) # 5. 提问 question 我们公司的请假流程是什么 result qa_chain({query: question}) print(f答案{result[result]}) print(f参考文档{result[source_documents]})4.3 RAG 的优化方向基础 RAG 容易遇到检索不准、生成幻觉等问题。可以考虑以下优化分层检索先检索章节标题再定位具体内容。重排序ReRank用更精细的模型对检索结果重新排序。HyDE 技术让模型先生成假设答案再用假设答案去检索。多查询扩展从原问题生成多个相关问题合并检索结果。LangChain 的MultiQueryRetriever、ContextualCompressionRetriever等组件支持这些高级用法。5. 项目落地从实验脚本到可维护系统很多人在本地跑通 Demo 后不知道如何推进到生产环境。其实关键在于补上工程化要素配置管理、错误处理、日志记录、性能监控。5.1 配置化与环境隔离不要硬编码 API Key、模型参数、文件路径。使用环境变量或配置文件import os from langchain.llms import OpenAI # 从环境变量读取配置 llm OpenAI( api_keyos.getenv(OPENAI_API_KEY), model_nameos.getenv(MODEL_NAME, gpt-3.5-turbo), temperaturefloat(os.getenv(TEMPERATURE, 0.1)) )不同环境开发、测试、生产使用不同配置避免相互影响。5.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.invoke(prompt) except Exception as e: print(f调用失败{e}) raise # 触发重试对于关键业务还要实现降级方案比如主模型失败时切换到备用模型。5.3 日志与监控记录每次调用的输入、输出、耗时、Token 用量便于排查问题和优化成本import logging import time logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) def logged_llm_call(prompt): start_time time.time() try: result llm.invoke(prompt) end_time time.time() logger.info(f调用成功耗时{end_time-start_time:.2f}秒) return result except Exception as e: logger.error(f调用失败{e}) raise长期项目还可以集成 Prometheus、Grafana 等监控工具。5.4 版本兼容性管理LangChain 更新较快需要注意版本兼容。比如 1.3.11 版本的 LangChain 需要匹配特定版本的langchain-community。使用requirements.txt或 Poetry 锁定依赖版本langchain1.3.11 langchain-community0.3.5 openai1.63.0升级前在测试环境充分验证避免破坏现有功能。6. 常见问题排查指南遇到问题不要盲目调整代码按以下顺序排查6.1 Prompt 相关错误prompt has no outputs检查 PromptTemplate 的 input_variables 是否与传入参数匹配。system message must be at the beginning确保 ChatPromptTemplate 中 System Message 是第一个元素。输出格式不符合预期使用 OutputParser 校验或简化 Prompt 逐步测试。6.2 Agent 执行异常工具调用失败检查工具函数是否正常返回描述是否清晰。无限循环设置max_iterations10添加超时控制。内存不足对话历史过长时使用ConversationSummaryMemory替代完整历史记录。6.3 RAG 效果不佳检索不到相关内容调整文本分割大小chunk_size优化 Embedding 模型。生成答案不准确在 Prompt 中明确要求“基于检索内容回答”减少模型幻觉。速度慢考虑缓存检索结果或使用更轻量级的 Embedding 模型。6.4 依赖和版本问题导入错误检查 LangChain 模块路径是否与版本匹配。V1.x 相比早期版本有大量重构。API 变更关注 LangChain 更新日志提前适配废弃接口。LangChain 的真正价值不在于功能多全而在于它提供了一套可组合、可测试、可扩展的范式。开始新项目时不要试图一次性用上所有高级功能。先从最简单的 LLMChain 做起确保单任务流程稳定再加入 Prompt 模板化让输入输出可控接着尝试 Agent 处理复杂决策最后用 RAG 接入私有数据。每一步都做好错误处理和日志记录这样构建的系统才能经得起实际使用。
