写在前面你是不是也踩过这些坑大模型火了你肯定也被安利过无数次 GPT 能写代码了 —— 然后呢怎么把它用到自己的业务里 教程一堆0.x 版本、1.0 版本混着来学了半天 API 又变了 代码跑不通bug 满天飞踩坑踩到怀疑人生 想做一个能记住上下文的对话机器人不知道从哪下手别慌这些我都经历过。所以写了这篇教程特点很明确✅基于 LangChain 1.0 最新版不学过时 API上来就是正经生产级写法 ✅6 个完整案例代码可直接复制运行跑不通你回来找我 ✅从零搭建到完整项目循序渐进每一章都在上一章基础上加东西废话不多说咱们直接开干 第1章LangChain 基础认知与环境搭建 为什么需要 LangChain你直接调 DeepSeek API一次能干嘛—— 问一句答一句仅此而已。但真实场景里你需要的是让 AI 记住你们之前聊了啥让 AI 能查天气、搜数据库、调接口让 AI 按照你定的规矩说话把多个步骤串起来自动化完成复杂任务LangChain 就是干这个的—— 它是大模型应用的乐高搭建框架。大模型是大脑LangChain 给大脑装上手、脚、记忆让它真正能干活。 LangChain 生态四层栈别被架构吓到其实就四层从底到上┌──────────────────────────────────────────────────────┐ │ 部署层 (Deployment) │ │ LangGraph Cloud云端部署| LangSmith监控平台 │ ├──────────────────────────────────────────────────────┤ │ 组件层 (Components) │ │ langchain-community / langchain-deepseek / ... │ │ 各种第三方集成模型、向量库、工具、文档加载器 │ ├──────────────────────────────────────────────────────┤ │ ️ 架构层 (Architecture) │ │ langchain-core基础抽象 LCEL │ │ LangGraph图状态机支持复杂工作流 │ ├──────────────────────────────────────────────────────┤ │ 核心层 (Core) │ │ langchain统一入口 │ │ 模型调用、提示词、工具、记忆等核心抽象 │ └──────────────────────────────────────────────────────┘包名干嘛用的langchain-core基础抽象Runnable、Message、Prompt 等 LCEL 表达式语言langchain-community第三方集成模型、工具、向量库等社区维护包langchain-deepseekDeepSeek 专用适配器langgraph图状态机协调多 Chain/Agent/Tool支持循环调用langsmith可观测性调试、评测、Prompt 管理、性能监控小技巧刚开始学只需要装langchainlangchain-deepseekpython-dotenv三个包就够跑通本教程所有案例了。️ 环境准备第一步安装依赖# 核心三件套必装 pip install langchain langchain-deepseek python-dotenv⚠️踩坑预警Python 版本要求3.11低于这个版本会各种报错检查版本python --version不够就升级如果之前装过旧版 LangChain建议先卸载pip uninstall langchain langchain-core langchain-community再重新装第二步申请 DeepSeek API Key访问 DeepSeek 开放平台注册/登录账号支持微信登录进入API Keys页面点击创建 API Key复制生成的密钥只显示一次赶紧保存第三步配置 .env 文件在项目根目录创建.env文件DEEPSEEK_API_KEYsk-你复制的密钥粘贴到这里⚠️踩坑预警文件名必须是.env不能是env.txt或.env.txtWindows 用户创建时注意先新建文本文档重命名时把前面的名字删掉只留.env确保文件扩展名已显示文件夹 → 查看 → 勾选文件扩展名千万不要把 API Key 直接写在代码里泄露了别人能用你的额度 案例1Hello LangChain —— 验证环境是否正常场景写代码第一步永远是跑通 Hello World。这个案例帮你确认环境装好了没Key 配对了没模型能连上没# -*- coding: utf-8 -*- 案例1Hello LangChain 功能验证环境配置是否正确测试 DeepSeek 模型能否正常对话 # 加载 .env 环境变量读取 API Key from dotenv import load_dotenv load_dotenv() # 使用 LangChain 1.0 推荐的统一接口初始化模型 from langchain.chat_models import init_chat_model llm init_chat_model(deepseek:deepseek-chat) # 发起一次对话测试 response llm.invoke(你好请用一句话介绍你自己) print( 模型回复) print(response.content)运行后如果看到模型的回复恭喜你环境搞定了 ✅老手习惯init_chat_model是 LangChain 1.0 的统一入口后续想换 GPT、通义千问只需要改模型名代码结构完全不用动。这就是统一接口的魅力。 案例2带人设的对话 —— 感受 System 消息的威力场景直接问模型问题它会用自己的风格回答。但你的业务场景里你需要 AI 扮演特定角色按你的规矩说话。比如一个友好的 Python 编程助手。# -*- coding: utf-8 -*- 案例2带人设的对话 功能通过 System 消息设定 AI 角色观察回答风格的变化 from dotenv import load_dotenv load_dotenv() from langchain.chat_models import init_chat_model llm init_chat_model(deepseek:deepseek-chat) # 定义对话消息列表 messages [ # System 消息给 AI 定规矩设定身份和行为准则 (system, 你是一个友好的AI编程助手擅长Python教学回答简洁明了只给代码和关键说明不啰嗦), # Human 消息用户的提问 (human, 帮我写一个 Python 冒泡排序注释写详细一点) ] # 调用模型 response llm.invoke(messages) print( 编程助手回复) print(response.content)看到了吗同样的问题加了 System 消息后回答风格完全不一样了 —— 更简洁、更有针对性。小技巧System 消息就像给 AI 的上岗培训手册写得越清晰AI 表现越稳定。后面所有案例都会用到它。第2章模型消息结构 —— 搞清楚消息才能玩明白对话 为什么需要理解消息结构新手 90% 的 LangChain 报错都是因为消息格式搞混了。大模型收到的不是一句话而是一组结构化的消息。每条消息都有自己的角色模型根据角色来理解谁说了什么。 三大核心消息类LangChain 定义了四种消息类型但日常开发最常用的就三个消息类型角色标识用途谁写的SystemMessagesystem设定 AI 的身份、行为准则开发者写死的HumanMessagehuman/user用户每一轮的提问用户输入AIMessageai/assistant模型返回的回答模型生成小技巧还有一种ToolMessage是工具调用场景才会用到的本章先不管它。️ temperature控制 AI 的创造力值效果适用场景0 ~ 0.3严谨、确定性高、不废话客服、数据查询、代码生成0.4 ~ 0.7平衡模式通用对话、内容创作0.8 ~ 1.0随机、有创意、偶尔离谱写诗、头脑风暴# 客服场景低温度回答稳定 llm init_chat_model( deepseek:deepseek-chat, temperature0.3 ) # 创意写作高温度天马行空 llm_creative init_chat_model( deepseek:deepseek-chat, temperature0.9 )老手习惯生产环境建议 temperature 不超过 0.7。太高的话AI 容易自由发挥给出你意想不到的答案。 案例3多轮对话 —— 让 AI 记住你说过啥场景你问 AI 我叫小明接着问我叫什么名字 —— 如果没有记忆AI 会一脸懵。这个案例教你实现真正的多轮对话。# -*- coding: utf-8 -*- 案例3多轮对话 功能通过消息列表管理对话历史让 AI 记住上下文 from dotenv import load_dotenv load_dotenv() from langchain.chat_models import init_chat_model from langchain_core.messages import SystemMessage, HumanMessage, AIMessage llm init_chat_model(deepseek:deepseek-chat, temperature0.5) # 初始化对话消息列表 messages [ SystemMessage(content你是一个友好的聊天助手请记住用户告诉你的信息。) ] # 第一轮对话 user_input 你好我叫小明我是一名前端开发工程师 messages.append(HumanMessage(contentuser_input)) # 记录用户说的话 response llm.invoke(messages) messages.append(AIMessage(contentresponse.content)) # 记录 AI 的回复 print(f 用户{user_input}) print(f 助手{response.content}\n) # 第二轮对话 user_input 你还记得我叫什么名字吗我的职业是什么 messages.append(HumanMessage(contentuser_input)) response llm.invoke(messages) messages.append(AIMessage(contentresponse.content)) print(f 用户{user_input}) print(f 助手{response.content}\n)核心原理每次调用模型时把之前所有的对话历史messages 列表一起传进去。模型看到完整对话记录自然就记住了。⚠️踩坑预警消息顺序必须是System → Human → AI → Human → AI ...交替排列禁止连续放两条同类消息比如两条 HumanMessage 紧挨着否则模型行为会出问题每条 HumanMessage 后必须跟一条 AIMessage这是对话协议✂️ 历史截断对话太长怎么办对话越来越长消息列表越来越长会遇到两个问题超出模型上下文限制DeepSeek 默认 4K/8K tokensToken 费用飙升每轮都带全量历史太贵了解决方案截断历史消息只保留最近 N 轮对话。LangChain 提供了trim_messages工具from langchain_core.messages import trim_messages # 配置截断规则 trimmed_messages trim_messages( messagesmessages, max_tokens2000, # 最多保留 2000 个 token token_counterllm, # 用模型自带的 token 计数器最准 strategylast, # 从后往前保留保留最新的对话 include_systemTrue, # 永远保留 System 消息人设不能丢 start_onhuman, # 保证消息从 Human 开始格式合法 allow_partialFalse # 不拆分单条消息语义完整 )参数作用推荐值max_tokens保留的最大 token 数轻量模型 2000-4000长上下文模型 4000-8000strategy截断策略last保留最新对话场景首选include_system是否保留系统消息True必须人设不能丢start_on从哪种消息开始human保证对话格式合法allow_partial是否允许截断单条消息False保证语义完整小技巧还有一种更简单的按轮次截断方案适合极简场景def trim_by_round(msg_list, keep_rounds3): 只保留最近 keep_rounds 轮对话 系统消息 system_msg msg_list[0] # 第一条是 System history msg_list[1:] # 每轮 1条 Human 1条 AI 2条消息 recent history[-(keep_rounds * 2):] return [system_msg] recent第3章完整命令行客服实战 场景说明前面学的所有知识点这一章全部串起来 —— 做一个命令行客服机器人✅ 有固定人设System 消息✅ 能记住上下文多轮对话✅ 自动截断历史不怕对话太长✅ 流式输出打字机效果体验更好✅ 无限循环直到用户说退出老手习惯这个案例的代码结构就是所有客服机器人的最小可用原型。后面不管加 RAG、加工具、接前端骨架都是一样的。 案例4基础版客服机器人无限循环# -*- coding: utf-8 -*- 案例4命令行客服机器人 功能支持多轮对话、自动截断历史、流式输出的客服助手 from dotenv import load_dotenv load_dotenv() from langchain.chat_models import init_chat_model from langchain_core.messages import SystemMessage, HumanMessage, AIMessage, trim_messages # 模型初始化 llm init_chat_model(deepseek:deepseek-chat, temperature0.3) # 配置参数 MAX_CONTEXT_TOKENS 2000 # 最大上下文 token 数 # 初始化对话上下文 # 全局消息列表System 消息永远在最前面不会被截断 messages [ SystemMessage(content( 你是一名专业的电商客服助手。\n 回答要求\n 1. 礼貌、简洁、通俗易懂\n 2. 涉及订单问题时提醒用户提供订单号\n 3. 不确定的问题引导用户联系人工客服\n 4. 不要编造不存在的政策或信息 )) ] # 上下文自动截断函数 def auto_trim(msg_list): 自动修剪对话历史防止超出 token 限制 核心思路保留系统人设 保留最新对话 保证格式合法 if len(msg_list) 1: # 只有 System 消息不需要截断 return msg_list trimmed trim_messages( messagesmsg_list, max_tokensMAX_CONTEXT_TOKENS, token_counterllm, strategylast, include_systemTrue, start_onhuman, allow_partialFalse ) return trimmed # 流式输出函数 def stream_response(msg_list): 流式输出模型回复打字机效果 好处用户不用等很久才看到第一个字体验更好 full_response for chunk in llm.stream(msg_list): print(chunk.content, end, flushTrue) # flushTrue 必须加 full_response chunk.content print() # 输出结束后换行 return full_response # 主循环 def main(): print( * 50) print( 欢迎使用智能客服助手) print( 输入 quit 或 exit 退出对话) print( * 50) while True: # 获取用户输入 user_input input(\n 你).strip() # 退出条件 if user_input.lower() in [quit, exit, q]: print( 感谢使用再见) break # 空输入跳过 if not user_input: continue # 记录用户消息 messages.append(HumanMessage(contentuser_input)) # 截断历史防止 token 溢出 current_messages auto_trim(messages) # 流式输出 AI 回复 print( 客服, end) ai_response stream_response(current_messages) # 记录 AI 回复到历史 messages.append(AIMessage(contentai_response)) if __name__ __main__: main() 案例5带 Token 统计的增强版场景生产环境中你需要知道每轮对话消耗了多少 token用来做成本监控。# -*- coding: utf-8 -*- 案例5带 Token 统计的客服机器人 功能在案例4基础上增加 token 消耗统计和对话轮次显示 from dotenv import load_dotenv load_dotenv() from langchain.chat_models import init_chat_model from langchain_core.messages import SystemMessage, HumanMessage, AIMessage, trim_messages # 模型初始化 llm init_chat_model(deepseek:deepseek-chat, temperature0.3) MAX_CONTEXT_TOKENS 2000 messages [ SystemMessage(content( 你是一名专业的电商客服助手。回答礼貌、简洁。 涉及订单问题时提醒用户提供订单号。 )) ] total_tokens 0 # 总 token 消耗 round_count 0 # 对话轮次 def stream_with_stats(msg_list): 流式输出 token 统计 global total_tokens full_response for chunk in llm.stream(msg_list): print(chunk.content, end, flushTrue) full_response chunk.content # 从最后一条 AIMessage 的 metadata 中提取 token 信息 # 注意不同模型的 metadata 格式可能不同 print() return full_response def main(): global total_tokens, round_count print( * 50) print( 智能客服Token 统计版) print( * 50) while True: user_input input(\n 你).strip() if user_input.lower() in [quit, exit, q]: print(f\n 本次会话统计) print(f 对话轮次{round_count} 轮) print(f 当前历史消息数{len(messages) - 1} 条不含 System) print( 再见) break if not user_input: continue round_count 1 messages.append(HumanMessage(contentuser_input)) # 截断 trimmed trim_messages( messagesmessages, max_tokensMAX_CONTEXT_TOKENS, token_counterllm, strategylast, include_systemTrue, start_onhuman, allow_partialFalse ) print(f 客服第{round_count}轮, end) ai_response stream_with_stats(trimmed) messages.append(AIMessage(contentai_response)) # 显示当前历史消息数量 print(f [当前历史{len(messages)-1} 条消息]) if __name__ __main__: main()⚠️踩坑预警flushTrue必须加否则文字会缓存看不到逐字输出效果生产环境必须开截断不然长对话必报错、Token 成本爆炸trim_messages的token_counter用模型实例llm不要用固定数字估算不同模型的 tokenizer 不一样第4章常见问题与开发规范 踩坑合集这些坑几乎每个新手都会踩一遍提前告诉你问题原因解决方案ModuleNotFoundError依赖没装好重新执行pip install langchain langchain-deepseek python-dotenvAPI Key not found.env 文件没加载检查.env文件名是否正确、是否在项目根目录、Key 是否填对429 Too Many Requests请求太频繁加延时、加重试机制或申请更高额度的 Key模型回答牛头不对马嘴消息格式混乱检查消息是否 System → Human → AI 交替排列长对话后报错/崩溃Token 超限必须加trim_messages截断历史流式输出看不到效果忘了flushTrueprint(chunk.content, end, flushTrue).env加载失败变成.env.txtWindows 文件扩展名问题文件夹 → 查看 → 勾选文件扩展名中文乱码文件编码不是 UTF-8代码第一行加# -*- coding: utf-8 -*-保存文件时用 UTF-8 编码 强制开发规范建议打印贴桌上API Key 永远不写死在代码里→ 用.envload_dotenv()消息格式严格交替→ System → Human → AI → Human → AI禁止连续同类必须做上下文截断→ 用trim_messages设置合理的max_tokensSystem 消息必须保留→include_systemTrue人设不能丢流式输出加 flush→flushTrue否则没效果统一用init_chat_model→ 不要直接 import 某个厂商的模型类代码第一行写编码声明→# -*- coding: utf-8 -*-项目路径别用中文→ 避免中文路径导致的各种诡异报错老手习惯每个项目开始时先跑通案例1的 Hello World确认环境没问题再往下写。别一上来就写大段代码最后发现是 API Key 配错了白忙半天。第5章知识点总结 核心概念速查表概念说明代码示例init_chat_modelLangChain 1.0 统一模型初始化入口init_chat_model(deepseek:deepseek-chat)SystemMessage设定 AI 身份和行为准则SystemMessage(content你是一个客服)HumanMessage用户输入的消息HumanMessage(content你好)AIMessage模型返回的回复AIMessage(content你好)invoke()同步调用等待完整结果response llm.invoke(messages)stream()流式调用逐块返回for chunk in llm.stream(messages)trim_messages消息历史截断工具trim_messages(messages, max_tokens2000, ...)temperature控制输出随机性0-1低严谨高创意.env存储 API Key 等敏感信息load_dotenv()加载 本教程 6 个案例回顾案例学到了什么核心知识点案例1Hello LangChain环境搭建、模型初始化、基础调用案例2带人设的对话System 消息、消息列表结构案例3多轮对话HumanMessage/AIMessage 交替、上下文记忆原理案例4基础客服机器人无限循环、流式输出、历史截断案例5Token 统计版客服token 监控、对话轮次管理案例6可扩展加工具/加RAG为进阶做准备 下一步学什么恭喜你看完了基础篇接下来有几个进阶方向建议按顺序来方向1RAG检索增强生成让 AI 读你的文档/知识库基于你的资料回答问题学习内容文档加载 → 文本切分 → 向量化 → 向量数据库 → 检索问答链推荐工具Chroma / FAISS LangChain RetrievalChain适用场景企业知识库、产品文档问答、个人笔记助手方向2工具调用Tool Calling让 AI 自己判断什么时候该调用什么工具学习内容tool装饰器、Agent、ReAct 模式推荐工具LangChain Agents Tavily 搜索适用场景天气查询、数据库查询、自动化办公方向3LangGraph工作流编排️把多个 Agent、工具、判断逻辑串成复杂工作流学习内容StateGraph、节点/边、条件分支、循环适用场景多步骤自动化任务、复杂客服系统方向4LangSmith监控与调试生产环境必备实时监控 Token 消耗、响应时间、错误率学习内容Tracing、Evaluations、Prompt 管理适用场景线上服务监控、模型效果评估方向5MCP 协议模型间通信让不同 AI 模型/工具之间标准化通信学习内容MCP Server/Client、工具注册适用场景多模型协作、跨系统工具调用 最后说两句LangChain 的核心思想其实就一句话让大模型从只会聊天变成能干实事。本教程的 6 个案例从最简单的打个招呼到完整的客服机器人你已经掌握了✅ 大模型应用的基本结构✅ 消息系统的运作原理✅ 多轮对话的实现方式✅ 生产级的上下文管理记住看懂了 ≠ 会写了。一定要把代码复制到本地跑一遍改改参数看看效果有什么变化。觉得有用记得收藏 转发给需要的朋友有问题欢迎在评论区交流咱们一起进步 下一篇预告《LangChain RAG让你的 AI 读懂私有文档》