LangChain 基础对话链构建新手指南从零开始跑通你的第一个智能对话机器人附完整可运行代码 避坑大全① 开发环境搭建与依赖安装先说个很多人踩过的坑。你去搜“LangChain 安装教程”看到的第一个命令大概率是pip install langchain。你照着做了然后兴冲冲地写了一个from langchain_openai import ChatOpenAI一运行报错ModuleNotFoundError: No module named langchain_openai你会觉得是代码写错了但其实不是。问题在于langchain 这个包早就被拆分了。你只装了主包但那些具体和大模型对接的功能都在别的包里。正确的安装方式一步到位# 第一步建虚拟环境跳过这步以后有的苦吃python-mvenv langchain_env# Windows:langchain_env\Scripts\activate# Mac/Linux:sourcelangchain_env/bin/activate# 第二步装需要的包别只装langchainpipinstalllangchain langchain-community langchain-core pipinstalllangchain-openai pipinstallpython-dotenv推荐用Python 3.10 或更高版本低版本在某些组件上会有奇怪的兼容性问题。装完验证一下python-cfrom langchain_openai import ChatOpenAI; print(OK)如果没报错说明环境好了。补充说明LangChain 生态主要有这几个包langchain主包包含链、记忆等核心抽象langchain-core最底层的基础接口Runnable 等langchain-community社区维护的第三方集成langchain-openaiOpenAI 模型的专用包如果你要用其他国产大模型智谱、通义千问等也有对应的包。不过初学者建议先用 OpenAI 兼容的接口后面再换。② 核心概念解析与大模型连接LangChain 有很多新名词但你先别被吓住。最核心的东西就三块第一块大模型LLM/ChatModel就是那个负责“说话”的东西。在 LangChain 里ChatOpenAI就是你的大模型实例。你给它输入它返回输出。第二块提示词模板Prompt Template你每次问模型的问题大部分时候只是其中几个关键词在变。模板就是帮你把这种重复劳动的活儿抽象出来。比如你写“把下面的文字翻译成英文{text}”这里的{text}就是等你填进去的变量。第三块链Chain把上面两样东西串起来。你输入一个变量比如待翻译的文字模板先生成完整的提示词再交给模型模型返回结果。整个流程就是一条链。后来 LangChain 又推出了 LCELLangChain Expression Language你可以用管道符号|把这几个组件拼在一起写起来非常直观chainprompt_template|model|output_parser现在先不急记这些后面实战里你亲手写了就理解了。连接一个大模型以 OpenAI 为例fromlangchain_openaiimportChatOpenAI modelChatOpenAI(modelgpt-3.5-turbo,# 换成你有的模型temperature0.7,# 控制随机性0~1之间api_key你的密钥# 当然实际上别这么写)temperature是个挺重要的参数。数值越低回答越保守、越确定数值越高回答越有创造性但也可能跑偏。聊天机器人一般设在 0.7 左右就行。③ 构建最小可运行对话链这里我们只做一件事让模型回答一个问题。不求花哨先跑通。第一步配置 API Key安全第一别硬编码建一个.env文件OPENAI_API_KEYsk-你的真实密钥 OPENAI_BASE_URLhttps://api.openai.com/v1加上.gitignore把.env排除掉防止上传。然后在代码里加载fromdotenvimportload_dotenvimportos load_dotenv()api_keyos.getenv(OPENAI_API_KEY)base_urlos.getenv(OPENAI_BASE_URL)第二步最小可运行代码fromlangchain_openaiimportChatOpenAIfromdotenvimportload_dotenvimportos load_dotenv()# 初始化模型modelChatOpenAI(modelgpt-3.5-turbo,api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL),# 如果用国产厂商就填他们的地址temperature0.7)# 发出请求responsemodel.invoke(你好请简单介绍一下LangChain是什么)print(response.content)运行看到输出恭喜你——第一个 LangChain 程序跑通了。如果你用的是国产大模型比如 DeepSeek、智谱、通义千问只要它们提供 OpenAI 兼容的接口ChatOpenAI一样能用把base_url换成厂商给的地址就行。零成本方案后面会专门讲。④ 自定义提示词模板设计每次都把完整提示词写在代码里不优雅。而且如果你想用同样的模板去处理不同内容就得反复写重复的代码。最简单的字符串模板fromlangchain_core.promptsimportPromptTemplate templatePromptTemplate.from_template(请用{字数}字以内的中文总结以下内容\n\n{内容})# 填入变量prompttemplate.format(字数50,内容LangChain是一个用于开发由语言模型驱动的应用程序的框架...)print(prompt)更常用的是 ChatPromptTemplate适用多轮对话场景fromlangchain_core.promptsimportChatPromptTemplate chat_templateChatPromptTemplate.from_messages([(system,你是一个{角色}回答需要简洁专业。),(human,{用户输入}),])# 使用messageschat_template.format_messages(角色编程助手,用户输入什么是Python装饰器)ChatPromptTemplate专门为聊天场景设计可以包含 system、human、ai 等多种角色比单条字符串更灵活。把提示词模板和模型串起来不用解析器版本fromlangchain_openaiimportChatOpenAIfromlangchain_core.promptsimportChatPromptTemplate promptChatPromptTemplate.from_messages([(system,你是一个翻译助手把用户输入翻译成{目标语言}。),(human,{user_input})])modelChatOpenAI(modelgpt-3.5-turbo,temperature0.3)# 用管道符号串起来LCEL写法chainprompt|model responsechain.invoke({目标语言:英语,user_input:今天天气真好})print(response.content)这里你还没有输出解析器模型返回的还是AIMessage对象取.content就能拿到文本。后面会讲怎么直接把结果解析成 Python 对象。注意ChatPromptTemplate和普通PromptTemplate的区别在于前者输出的是一组消息适用于聊天 API后者输出的是纯字符串。用 OpenAI 风格的大模型建议用ChatPromptTemplate。⑤ 多轮对话记忆机制实现大模型本身是不记事的。你问它第一轮“我叫张三”第二轮问“我叫什么”它大概率不知道因为每次调用都是独立的。你需要一个“记忆组件”来保存对话历史每次把历史塞回输入里。LangChain 里最简单的记忆组件是ConversationBufferMemory它把整个对话历史放在一个缓冲区里每次都全部打包带走。基本用法fromlangchain.memoryimportConversationBufferMemoryfromlangchain.chainsimportConversationChainfromlangchain_openaiimportChatOpenAI memoryConversationBufferMemory()modelChatOpenAI(modelgpt-3.5-turbo)# ConversationChain 是一个封装好的对话链自动处理记忆的存取conversationConversationChain(llmmodel,memorymemory,verboseTrue# 设为True可看到内部处理过程方便调试)# 第一轮print(conversation.predict(input你好我叫小明。))# 第二轮print(conversation.predict(input你还记得我叫什么吗))运行一下你会发现第二轮模型真的回答对了。verboseTrue是个好东西。运行的时候会打印出 LangChain 内部生成的完整提示词你可以看到记忆是怎么被塞进去的对理解背后原理很有帮助。如果不喜欢全记下来对话长了 Token 会爆炸怎么办全量记忆会导致对话越长花销越大。你可以用ConversationBufferWindowMemory只保留最近 K 轮对话fromlangchain.memoryimportConversationBufferWindowMemory memoryConversationBufferWindowMemory(k3)# 只保留最近3轮LCEL 新写法高级用法从 LangChain 0.2 开始官方推荐用 LCEL 自己构建带记忆的链而不是依赖ConversationChain这种封装类。但初学者先用ConversationChain足够了等你熟练了再切到 LCEL 版。一个容易混淆的点memory_key参数。ConversationBufferMemory默认的memory_key是 “history”。如果你的提示词模板里的变量不叫这个名字会匹配不上导致记忆没被用上。用ConversationChain就不用操心这个它会自动处理好。⑥ 完整代码实战与效果验证把前面学的所有东西串起来写一个完整的对话机器人。支持自定义 system prompt定角色记住多轮对话流式输出可随时退出importosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain.memoryimportConversationBufferMemoryfromlangchain.chainsimportConversationChain# 加载密钥load_dotenv()# 初始化模型modelChatOpenAI(modelgpt-3.5-turbo,api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL),temperature0.7,streamingTrue# 开启流式输出)# 记忆memoryConversationBufferMemory()# 对话链conversationConversationChain(llmmodel,memorymemory,verboseFalse)print( 对话机器人已启动输入 quit 或 exit 退出。\n)whileTrue:user_inputinput(你)ifuser_input.lower()in[quit,exit]:print(再见)break# 流式输出逐个字符打印responseconversation.predict(inputuser_input)print(,response)print()效果验证流式输出每个字出来你就看到了不用等全部生成完。多轮记忆问完“我叫小明”再问“我叫什么”模型应该能答对。角色扮演默认用的是ConversationChain的默认 System Prompt你也可以自己定制下一节会讲。注意流式输出在 Jupyter Notebook 里效果不如命令行终端明显建议直接在终端里跑这个脚本。⑦ 常见报错排查与解决思路LangChain 迭代速度快版本之间经常有不兼容的改动。下面是几个最常碰到的报错和解决方案。No.1ModuleNotFoundError: No module named ‘langchain_openai’原因你只装了langchain没装专门的大模型集成包。LangChain 把具体模型的支持拆成了独立包需要单独装。解决pip install langchain-openai。同理用智谱就装langchain-zhipu。No.2ImportError: cannot import name ‘ConversationBufferMemory’ from ‘langchain.memory’这个一般发生在高版本上。不同版本的 LangChain 模块结构变化很大有教程用的是 0.1.x你装的是 0.2.x 甚至 1.x路径可能已经不一样了。解决方案先去官方文档确认当前版本的正确导入路径或者在代码里打印一下dir(langchain.memory)看看有什么。No.3版本冲突导致旧代码跑不通现象照着 2023 年的教程写from langchain.schema import Document结果报错ModuleNotFoundError: No module named langchain.schema。原因新版 LangChain 已经把Document挪到了langchain_core.documents。解决升级代码或者固定版本pip install langchain0.1.12。初学者建议先固定版本避免踩坑。No.4API Key 读不到现象各种AuthenticationError。原因load_dotenv()没执行或者.env文件不在当前目录或者 Key 前面有空格被当成字符串一部分了。排查打印前几位看看print(os.getenv(OPENAI_API_KEY)[:10])如果是 None 说明没读到。No.5Rate Limit 429调用太快超过免费额度。加重试逻辑或者time.sleep(1)控制频率。通用排查流程看报错的最后一行基本能定位问题类型确认 langchain 版本pip show langchain用最简单的调用测试就一个model.invoke(hi)搜一下官方文档或者 GitHub Issues另外LangChain 社区有一个避坑指南专门讲了从旧版本迁移到新版本的模块路径变化碰到了可以找来看看。⑧ 输出格式化与解析技巧大模型返回的是自然语言文本。但很多场景下你想要的是一段 JSON、一个列表、或者一个自定义的对象比如“提取这段文本里的姓名、年龄、职业”。PydanticOutputParser把模型输出变成 Python 对象fromlangchain_core.output_parsersimportPydanticOutputParserfromlangchain_core.promptsimportPromptTemplatefrompydanticimportBaseModel,Fieldfromlangchain_openaiimportChatOpenAI# 定义你想要的数据结构classPersonInfo(BaseModel):name:strField(description人物的姓名)age:intField(description人物的年龄)occupation:strField(description人物的职业)parserPydanticOutputParser(pydantic_objectPersonInfo)# 提示词模板引导模型按格式输出promptPromptTemplate(template从以下文本中提取人物信息\n{text}\n\n{format_instructions},input_variables[text],partial_variables{format_instructions:parser.get_format_instructions()})modelChatOpenAI(modelgpt-3.5-turbo,temperature0)# 构建并执行链chainprompt|model|parser resultchain.invoke({text:张伟今年28岁是一名软件工程师。})print(result)print(result.name)# 张伟print(result.age)# 28print(result.occupation)# 软件工程师跑一下你会发现result直接是一个 Python 对象字段都可以用点号访问。parser.get_format_instructions()会自动生成一段指导模型按 JSON 格式输出的说明默认会写在提示词里。这是 LangChain 的一大便利功能。如果不想要额外依赖最简单的 JSON 解析importjsonfromlangchain_core.output_parsersimportStrOutputParser chainprompt|model|StrOutputParser()# 先拿到字符串response_strchain.invoke({text:...})# 假设模型返回的是标准JSONdatajson.loads(response_str)但这种方式依赖模型“自觉”输出正确 JSON没有 PydanticOutputParser 稳定。实际场景建议开发调试阶段用StrOutputParser看原始输出最快上生产环境要求稳定的结构化输出用PydanticOutputParser如果模型经常输出格式错误适当调低temperature比如 0 或 0.1⑨ 本地模型替换与配置调整免费方案来了。如果你不想花 API 费用或者有数据隐私方面的顾虑可以用Ollama在本地跑开源模型。第一步安装 Ollama到 https://ollama.com 下载安装包一路下一步就行。装完后命令行应该能用ollama命令了。第二步下载一个模型以 llama3.2 为例只有几十MB很快ollama run llama3.2第一次运行会自动下载等它跑完。你也可以用国内的 Qwen 系列ollama run qwen:7b# 7B 版本需要比较多内存第三步在 LangChain 里调用本地模型Ollama 启动后会默认跑在http://localhost:11434/上而且提供了 OpenAI 兼容的 API 接口。你什么都不用改把base_url指过去就行fromlangchain_openaiimportChatOpenAI local_modelChatOpenAI(modelllama3.2,# 用你下载的模型名base_urlhttp://localhost:11434/v1,api_keyollama,# 本地服务不需要真实Key随便填temperature0.7)responselocal_model.invoke(介绍一下什么是LangChain)print(response.content)注意ollama run命令会直接进入交互模式建议另开一个终端窗口运行它或者在后台挂着。这样你的 Python 脚本就可以调用它了。内存需求提醒llama3.23B约 2GB 内存普通电脑都能跑qwen:7b 约 4-6GB 内存更大的模型需要 16GB 以上内存不够的话建议还是用国产大模型的云端 API价格也不贵。DeepSeek 最近有优惠活动用不了几个钱。如果 Ollama 报错连不上检查一下服务有没有在跑。访问http://localhost:11434/v1/models如果能返回 JSON 说明正常。⑩ 进阶功能扩展与安全注意事项到了这一步你已经能把 LangChain 的基础功能跑通了。下面是几个进阶方向的提示以及绕不开的安全红线。进阶一添加工具调用让模型能做事大模型只会说话但如果你给它一个“计算器”工具它就能帮你算数学。LangChain 的 Agent 功能就是干这个的模型判断什么时候需要调用工具然后执行并返回结果。这个方向值得单独写一篇教程初学者先了解有这么个东西就行。进阶二RAG检索增强生成当你需要模型回答它“不知道”的问题比如你们公司的内部知识库可以让模型先去搜一堆相关文档再基于这些文档来回答。LangChain 在这一块有非常完善的工具链从文档加载、切分、向量化存储到检索检索全都支持。进阶三LCEL 高级玩法前面我们用管道符号|串了 prompt、model、parser这只是 LCEL 的冰山一角。你还可以做并行处理、条件分支、流式输出等更复杂的编排。安全注意事项这条要读三遍API Key 绝不提交到 Git 仓库。用.env.gitignore是最低要求。生产环境不要暴露调试信息。verboseTrue开发用用就好上线前一定关掉。用户输入做清洗和限制长度。恶意用户可能故意输入超长文本让你的 API 费用爆炸。设置用量预算和限流。多轮对话很容易 Token 暴增设计好记忆窗口大小k值别设太大。本地跑私有模型有门槛但值得。如果处理的是敏感业务数据建议上 Ollama 本地模型数据不出本机。虽然质量可能不如 GPT-4但在数据安全和成本之间能找到一个不错的平衡点。WEB项目地址演示地址安卓APP下载地址演示地址写在最后从环境搭建到本地模型替换你已经把 LangChain 对话机器人开发的整个链路摸了一遍。别想着一次全记住把这篇文章存下来动手敲一遍代码。有个常用的调试技巧——设置verboseTrue。运行时会打印出 LangChain 内部生成的完整提示词能看到记忆是怎么被塞进去的、模型实际收到了什么内容对理解原理帮助很大。下一步想往哪个方向走可以试试 RAG让模型读你的 PDF、Agent让模型帮你干活或者换成国产大模型跑通中文场景。这些每个都能单独写一篇有需要的话我接着写。遇到问题先去搜一下具体报错或者到 LangChain 的 GitHub Issues 看看大部分坑别人已经踩过了。祝顺利
LangChain 基础对话链构建新手指南
LangChain 基础对话链构建新手指南从零开始跑通你的第一个智能对话机器人附完整可运行代码 避坑大全① 开发环境搭建与依赖安装先说个很多人踩过的坑。你去搜“LangChain 安装教程”看到的第一个命令大概率是pip install langchain。你照着做了然后兴冲冲地写了一个from langchain_openai import ChatOpenAI一运行报错ModuleNotFoundError: No module named langchain_openai你会觉得是代码写错了但其实不是。问题在于langchain 这个包早就被拆分了。你只装了主包但那些具体和大模型对接的功能都在别的包里。正确的安装方式一步到位# 第一步建虚拟环境跳过这步以后有的苦吃python-mvenv langchain_env# Windows:langchain_env\Scripts\activate# Mac/Linux:sourcelangchain_env/bin/activate# 第二步装需要的包别只装langchainpipinstalllangchain langchain-community langchain-core pipinstalllangchain-openai pipinstallpython-dotenv推荐用Python 3.10 或更高版本低版本在某些组件上会有奇怪的兼容性问题。装完验证一下python-cfrom langchain_openai import ChatOpenAI; print(OK)如果没报错说明环境好了。补充说明LangChain 生态主要有这几个包langchain主包包含链、记忆等核心抽象langchain-core最底层的基础接口Runnable 等langchain-community社区维护的第三方集成langchain-openaiOpenAI 模型的专用包如果你要用其他国产大模型智谱、通义千问等也有对应的包。不过初学者建议先用 OpenAI 兼容的接口后面再换。② 核心概念解析与大模型连接LangChain 有很多新名词但你先别被吓住。最核心的东西就三块第一块大模型LLM/ChatModel就是那个负责“说话”的东西。在 LangChain 里ChatOpenAI就是你的大模型实例。你给它输入它返回输出。第二块提示词模板Prompt Template你每次问模型的问题大部分时候只是其中几个关键词在变。模板就是帮你把这种重复劳动的活儿抽象出来。比如你写“把下面的文字翻译成英文{text}”这里的{text}就是等你填进去的变量。第三块链Chain把上面两样东西串起来。你输入一个变量比如待翻译的文字模板先生成完整的提示词再交给模型模型返回结果。整个流程就是一条链。后来 LangChain 又推出了 LCELLangChain Expression Language你可以用管道符号|把这几个组件拼在一起写起来非常直观chainprompt_template|model|output_parser现在先不急记这些后面实战里你亲手写了就理解了。连接一个大模型以 OpenAI 为例fromlangchain_openaiimportChatOpenAI modelChatOpenAI(modelgpt-3.5-turbo,# 换成你有的模型temperature0.7,# 控制随机性0~1之间api_key你的密钥# 当然实际上别这么写)temperature是个挺重要的参数。数值越低回答越保守、越确定数值越高回答越有创造性但也可能跑偏。聊天机器人一般设在 0.7 左右就行。③ 构建最小可运行对话链这里我们只做一件事让模型回答一个问题。不求花哨先跑通。第一步配置 API Key安全第一别硬编码建一个.env文件OPENAI_API_KEYsk-你的真实密钥 OPENAI_BASE_URLhttps://api.openai.com/v1加上.gitignore把.env排除掉防止上传。然后在代码里加载fromdotenvimportload_dotenvimportos load_dotenv()api_keyos.getenv(OPENAI_API_KEY)base_urlos.getenv(OPENAI_BASE_URL)第二步最小可运行代码fromlangchain_openaiimportChatOpenAIfromdotenvimportload_dotenvimportos load_dotenv()# 初始化模型modelChatOpenAI(modelgpt-3.5-turbo,api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL),# 如果用国产厂商就填他们的地址temperature0.7)# 发出请求responsemodel.invoke(你好请简单介绍一下LangChain是什么)print(response.content)运行看到输出恭喜你——第一个 LangChain 程序跑通了。如果你用的是国产大模型比如 DeepSeek、智谱、通义千问只要它们提供 OpenAI 兼容的接口ChatOpenAI一样能用把base_url换成厂商给的地址就行。零成本方案后面会专门讲。④ 自定义提示词模板设计每次都把完整提示词写在代码里不优雅。而且如果你想用同样的模板去处理不同内容就得反复写重复的代码。最简单的字符串模板fromlangchain_core.promptsimportPromptTemplate templatePromptTemplate.from_template(请用{字数}字以内的中文总结以下内容\n\n{内容})# 填入变量prompttemplate.format(字数50,内容LangChain是一个用于开发由语言模型驱动的应用程序的框架...)print(prompt)更常用的是 ChatPromptTemplate适用多轮对话场景fromlangchain_core.promptsimportChatPromptTemplate chat_templateChatPromptTemplate.from_messages([(system,你是一个{角色}回答需要简洁专业。),(human,{用户输入}),])# 使用messageschat_template.format_messages(角色编程助手,用户输入什么是Python装饰器)ChatPromptTemplate专门为聊天场景设计可以包含 system、human、ai 等多种角色比单条字符串更灵活。把提示词模板和模型串起来不用解析器版本fromlangchain_openaiimportChatOpenAIfromlangchain_core.promptsimportChatPromptTemplate promptChatPromptTemplate.from_messages([(system,你是一个翻译助手把用户输入翻译成{目标语言}。),(human,{user_input})])modelChatOpenAI(modelgpt-3.5-turbo,temperature0.3)# 用管道符号串起来LCEL写法chainprompt|model responsechain.invoke({目标语言:英语,user_input:今天天气真好})print(response.content)这里你还没有输出解析器模型返回的还是AIMessage对象取.content就能拿到文本。后面会讲怎么直接把结果解析成 Python 对象。注意ChatPromptTemplate和普通PromptTemplate的区别在于前者输出的是一组消息适用于聊天 API后者输出的是纯字符串。用 OpenAI 风格的大模型建议用ChatPromptTemplate。⑤ 多轮对话记忆机制实现大模型本身是不记事的。你问它第一轮“我叫张三”第二轮问“我叫什么”它大概率不知道因为每次调用都是独立的。你需要一个“记忆组件”来保存对话历史每次把历史塞回输入里。LangChain 里最简单的记忆组件是ConversationBufferMemory它把整个对话历史放在一个缓冲区里每次都全部打包带走。基本用法fromlangchain.memoryimportConversationBufferMemoryfromlangchain.chainsimportConversationChainfromlangchain_openaiimportChatOpenAI memoryConversationBufferMemory()modelChatOpenAI(modelgpt-3.5-turbo)# ConversationChain 是一个封装好的对话链自动处理记忆的存取conversationConversationChain(llmmodel,memorymemory,verboseTrue# 设为True可看到内部处理过程方便调试)# 第一轮print(conversation.predict(input你好我叫小明。))# 第二轮print(conversation.predict(input你还记得我叫什么吗))运行一下你会发现第二轮模型真的回答对了。verboseTrue是个好东西。运行的时候会打印出 LangChain 内部生成的完整提示词你可以看到记忆是怎么被塞进去的对理解背后原理很有帮助。如果不喜欢全记下来对话长了 Token 会爆炸怎么办全量记忆会导致对话越长花销越大。你可以用ConversationBufferWindowMemory只保留最近 K 轮对话fromlangchain.memoryimportConversationBufferWindowMemory memoryConversationBufferWindowMemory(k3)# 只保留最近3轮LCEL 新写法高级用法从 LangChain 0.2 开始官方推荐用 LCEL 自己构建带记忆的链而不是依赖ConversationChain这种封装类。但初学者先用ConversationChain足够了等你熟练了再切到 LCEL 版。一个容易混淆的点memory_key参数。ConversationBufferMemory默认的memory_key是 “history”。如果你的提示词模板里的变量不叫这个名字会匹配不上导致记忆没被用上。用ConversationChain就不用操心这个它会自动处理好。⑥ 完整代码实战与效果验证把前面学的所有东西串起来写一个完整的对话机器人。支持自定义 system prompt定角色记住多轮对话流式输出可随时退出importosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain.memoryimportConversationBufferMemoryfromlangchain.chainsimportConversationChain# 加载密钥load_dotenv()# 初始化模型modelChatOpenAI(modelgpt-3.5-turbo,api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL),temperature0.7,streamingTrue# 开启流式输出)# 记忆memoryConversationBufferMemory()# 对话链conversationConversationChain(llmmodel,memorymemory,verboseFalse)print( 对话机器人已启动输入 quit 或 exit 退出。\n)whileTrue:user_inputinput(你)ifuser_input.lower()in[quit,exit]:print(再见)break# 流式输出逐个字符打印responseconversation.predict(inputuser_input)print(,response)print()效果验证流式输出每个字出来你就看到了不用等全部生成完。多轮记忆问完“我叫小明”再问“我叫什么”模型应该能答对。角色扮演默认用的是ConversationChain的默认 System Prompt你也可以自己定制下一节会讲。注意流式输出在 Jupyter Notebook 里效果不如命令行终端明显建议直接在终端里跑这个脚本。⑦ 常见报错排查与解决思路LangChain 迭代速度快版本之间经常有不兼容的改动。下面是几个最常碰到的报错和解决方案。No.1ModuleNotFoundError: No module named ‘langchain_openai’原因你只装了langchain没装专门的大模型集成包。LangChain 把具体模型的支持拆成了独立包需要单独装。解决pip install langchain-openai。同理用智谱就装langchain-zhipu。No.2ImportError: cannot import name ‘ConversationBufferMemory’ from ‘langchain.memory’这个一般发生在高版本上。不同版本的 LangChain 模块结构变化很大有教程用的是 0.1.x你装的是 0.2.x 甚至 1.x路径可能已经不一样了。解决方案先去官方文档确认当前版本的正确导入路径或者在代码里打印一下dir(langchain.memory)看看有什么。No.3版本冲突导致旧代码跑不通现象照着 2023 年的教程写from langchain.schema import Document结果报错ModuleNotFoundError: No module named langchain.schema。原因新版 LangChain 已经把Document挪到了langchain_core.documents。解决升级代码或者固定版本pip install langchain0.1.12。初学者建议先固定版本避免踩坑。No.4API Key 读不到现象各种AuthenticationError。原因load_dotenv()没执行或者.env文件不在当前目录或者 Key 前面有空格被当成字符串一部分了。排查打印前几位看看print(os.getenv(OPENAI_API_KEY)[:10])如果是 None 说明没读到。No.5Rate Limit 429调用太快超过免费额度。加重试逻辑或者time.sleep(1)控制频率。通用排查流程看报错的最后一行基本能定位问题类型确认 langchain 版本pip show langchain用最简单的调用测试就一个model.invoke(hi)搜一下官方文档或者 GitHub Issues另外LangChain 社区有一个避坑指南专门讲了从旧版本迁移到新版本的模块路径变化碰到了可以找来看看。⑧ 输出格式化与解析技巧大模型返回的是自然语言文本。但很多场景下你想要的是一段 JSON、一个列表、或者一个自定义的对象比如“提取这段文本里的姓名、年龄、职业”。PydanticOutputParser把模型输出变成 Python 对象fromlangchain_core.output_parsersimportPydanticOutputParserfromlangchain_core.promptsimportPromptTemplatefrompydanticimportBaseModel,Fieldfromlangchain_openaiimportChatOpenAI# 定义你想要的数据结构classPersonInfo(BaseModel):name:strField(description人物的姓名)age:intField(description人物的年龄)occupation:strField(description人物的职业)parserPydanticOutputParser(pydantic_objectPersonInfo)# 提示词模板引导模型按格式输出promptPromptTemplate(template从以下文本中提取人物信息\n{text}\n\n{format_instructions},input_variables[text],partial_variables{format_instructions:parser.get_format_instructions()})modelChatOpenAI(modelgpt-3.5-turbo,temperature0)# 构建并执行链chainprompt|model|parser resultchain.invoke({text:张伟今年28岁是一名软件工程师。})print(result)print(result.name)# 张伟print(result.age)# 28print(result.occupation)# 软件工程师跑一下你会发现result直接是一个 Python 对象字段都可以用点号访问。parser.get_format_instructions()会自动生成一段指导模型按 JSON 格式输出的说明默认会写在提示词里。这是 LangChain 的一大便利功能。如果不想要额外依赖最简单的 JSON 解析importjsonfromlangchain_core.output_parsersimportStrOutputParser chainprompt|model|StrOutputParser()# 先拿到字符串response_strchain.invoke({text:...})# 假设模型返回的是标准JSONdatajson.loads(response_str)但这种方式依赖模型“自觉”输出正确 JSON没有 PydanticOutputParser 稳定。实际场景建议开发调试阶段用StrOutputParser看原始输出最快上生产环境要求稳定的结构化输出用PydanticOutputParser如果模型经常输出格式错误适当调低temperature比如 0 或 0.1⑨ 本地模型替换与配置调整免费方案来了。如果你不想花 API 费用或者有数据隐私方面的顾虑可以用Ollama在本地跑开源模型。第一步安装 Ollama到 https://ollama.com 下载安装包一路下一步就行。装完后命令行应该能用ollama命令了。第二步下载一个模型以 llama3.2 为例只有几十MB很快ollama run llama3.2第一次运行会自动下载等它跑完。你也可以用国内的 Qwen 系列ollama run qwen:7b# 7B 版本需要比较多内存第三步在 LangChain 里调用本地模型Ollama 启动后会默认跑在http://localhost:11434/上而且提供了 OpenAI 兼容的 API 接口。你什么都不用改把base_url指过去就行fromlangchain_openaiimportChatOpenAI local_modelChatOpenAI(modelllama3.2,# 用你下载的模型名base_urlhttp://localhost:11434/v1,api_keyollama,# 本地服务不需要真实Key随便填temperature0.7)responselocal_model.invoke(介绍一下什么是LangChain)print(response.content)注意ollama run命令会直接进入交互模式建议另开一个终端窗口运行它或者在后台挂着。这样你的 Python 脚本就可以调用它了。内存需求提醒llama3.23B约 2GB 内存普通电脑都能跑qwen:7b 约 4-6GB 内存更大的模型需要 16GB 以上内存不够的话建议还是用国产大模型的云端 API价格也不贵。DeepSeek 最近有优惠活动用不了几个钱。如果 Ollama 报错连不上检查一下服务有没有在跑。访问http://localhost:11434/v1/models如果能返回 JSON 说明正常。⑩ 进阶功能扩展与安全注意事项到了这一步你已经能把 LangChain 的基础功能跑通了。下面是几个进阶方向的提示以及绕不开的安全红线。进阶一添加工具调用让模型能做事大模型只会说话但如果你给它一个“计算器”工具它就能帮你算数学。LangChain 的 Agent 功能就是干这个的模型判断什么时候需要调用工具然后执行并返回结果。这个方向值得单独写一篇教程初学者先了解有这么个东西就行。进阶二RAG检索增强生成当你需要模型回答它“不知道”的问题比如你们公司的内部知识库可以让模型先去搜一堆相关文档再基于这些文档来回答。LangChain 在这一块有非常完善的工具链从文档加载、切分、向量化存储到检索检索全都支持。进阶三LCEL 高级玩法前面我们用管道符号|串了 prompt、model、parser这只是 LCEL 的冰山一角。你还可以做并行处理、条件分支、流式输出等更复杂的编排。安全注意事项这条要读三遍API Key 绝不提交到 Git 仓库。用.env.gitignore是最低要求。生产环境不要暴露调试信息。verboseTrue开发用用就好上线前一定关掉。用户输入做清洗和限制长度。恶意用户可能故意输入超长文本让你的 API 费用爆炸。设置用量预算和限流。多轮对话很容易 Token 暴增设计好记忆窗口大小k值别设太大。本地跑私有模型有门槛但值得。如果处理的是敏感业务数据建议上 Ollama 本地模型数据不出本机。虽然质量可能不如 GPT-4但在数据安全和成本之间能找到一个不错的平衡点。WEB项目地址演示地址安卓APP下载地址演示地址写在最后从环境搭建到本地模型替换你已经把 LangChain 对话机器人开发的整个链路摸了一遍。别想着一次全记住把这篇文章存下来动手敲一遍代码。有个常用的调试技巧——设置verboseTrue。运行时会打印出 LangChain 内部生成的完整提示词能看到记忆是怎么被塞进去的、模型实际收到了什么内容对理解原理帮助很大。下一步想往哪个方向走可以试试 RAG让模型读你的 PDF、Agent让模型帮你干活或者换成国产大模型跑通中文场景。这些每个都能单独写一篇有需要的话我接着写。遇到问题先去搜一下具体报错或者到 LangChain 的 GitHub Issues 看看大部分坑别人已经踩过了。祝顺利
