零基础入门 LangChain 时很多人的第一反应是直接去写 Agent结果连 ChatModel 的返回对象都没搞清楚就卡住了。LangChain 本身不是一个大模型它是一套面向大模型应用开发的框架用来解决提示词管理、模型接入、工具调用、上下文记忆和应用组装这些重复工程问题。这篇文章从零开始按照 Model、Prompt、Chain、Tool、Agent、Memory 的顺序带读者搭建一个最小可运行的 AI 智能应用。代码以 Python 为准使用 OpenAI 兼容接口开发机和本地虚拟环境即可完成测试。读完以后读者可以理解 LangChain 的工作方式知道 Agent 是如何让模型调用外部工具的也能在遇到模型名、上下文窗口和工具调用相关报错时定位问题。需要先说明学习路径Agent 是 LangChain 中最吸引人的部分但它不是独立功能而是模型、提示词、工具和记忆的组合产物。因此正文先用最小示例跑通 Model再逐步加入 Prompt 和 Tool最后组装 Agent。学习顺序不对后面排查过程会非常痛苦。1. 先建立对 LangChain 的基础认知框架、组件与工作方式1.1 LangChain 到底解决什么问题大模型 SDK 本身就能完成一次对话例如直接调用 OpenAI 的接口把 messages 数组传过去拿到一段文本。既然 SDK 已经能做这件事为什么还需要 LangChain因为真实应用不只是一次对话。业务里通常需要处理这样几类重复工作根据用户输入动态构造提示词而不是手写字符串拼接。把模型返回的文本解析成 JSON、代码块或结构化字段。在多轮对话中保存历史消息控制上下文长度。让模型调用外部系统例如搜索、数据库查询、计算器、工时系统。在多个模型厂商之间切换而不改动业务代码。LangChain 把这些能力抽象成组件模型是ChatModel提示词是PromptTemplate工具是Tool记忆是MemoryAgent 是组合这些组件的执行器。对零基础读者来说核心价值不是某个 API 的用法而是组件化思维。明白了每个组件负责什么后续遇到报错才能知道问题出在哪一层。1.2 核心组件速览在动手写代码前先把常见组件的作用和典型实现对齐组件作用典型实现ChatModel封装大模型对话接口ChatOpenAIPromptTemplate生成带变量的提示词模板ChatPromptTemplate、PromptTemplateChain把多个组件组合成调用链路prompt | llm | parserTool给模型提供外部能力tool装饰的函数Agent让模型自主决定调用哪些工具create_react_agent、AgentExecutorMemory保存多轮对话上下文ConversationBufferMemoryRetriever从向量库检索相关资料用于 RAG后续扩展常见组件其中 Chain 和 Agent 的区别尤其重要。普通 Chain 是固定的链路用户输入先进 Prompt再交给模型最后经解析器输出。Agent 则不同模型输出一段“思考”框架解析出要调用的工具名和参数执行工具后把结果返回给模型模型根据结果继续思考直到给出最终答案。这个循环就是 Agent 和普通 prompt 调用的本质差异。1.3 为什么 Agent 不等于 ChatModel 调用模型只会生成文本它不会真的执行系统函数。你问模型“现在几点”模型如果不知道当前时间它只能编造一个时间。Agent 解决的是“让模型把文本决策变成程序行为”这件事。举个例子给模型提供一个get_current_time工具。用户提问后模型先输出一个 Action 指令框架解析指令后调用真实函数把函数返回值作为 Observation 放回模型上下文模型再根据真实时间生成最终回答。整个过程模型没有直接执行函数但它通过文本决策“触发”了程序执行。理解这一点就能理解 Agent 为什么需要工具描述、参数 schema 和执行循环而不是简单地在提示词里写“你会调用时间函数”就能生效。2. 环境准备Python 虚拟环境、依赖安装与模型接入配置2.1 准备 Python 环境与项目目录建议使用 Python 3.10 或更高版本。第一步确认本机 Python 版本python --version如果版本过低需要先安装新版本 Python。随后创建项目目录和虚拟环境mkdir -p langchain-demo cd langchain-demo python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate虚拟环境的作用是把项目依赖和本机全局 Python 包隔离。避免不同项目依赖冲突这是 Python 工程里最基本的一步。检查点命令行前缀出现(.venv)表示已经进入虚拟环境。2.2 安装 LangChain 相关依赖包学习环境只需要安装这几个包python -m pip install --upgrade pip python -m pip install langchain langchain-core langchain-openai python-dotenv依赖包用途langchainLangChain 生态主体包含 Agent、Memory 等组件langchain-core核心抽象如消息对象、工具、提示词模板langchain-openai通过 OpenAI 兼容接口接入大模型python-dotenv从 .env 文件加载环境变量如果后续需要社区集成工具例如网页搜索、文件读取、数据库连接器等可以再安装langchain-community。安装版本以 pip 显示的当前稳定版为准不建议盲目追求最新0.2、0.3 系列对初学者已经足够。安装完成后快速验证python -c import langchain_openai; print(langchain-openai ok) python -c from dotenv import load_dotenv; print(dotenv ok)如果能正常打印说明依赖安装没有缺失。2.3 配置模型接入环境变量与 OpenAI 兼容接口LangChain 的ChatOpenAI默认从环境变量OPENAI_API_KEY读取密钥从OPENAI_BASE_URL读取接口地址。在项目根目录创建.env文件OPENAI_API_KEYsk-你的密钥 OPENAI_BASE_URLhttps://api.openai.com/v1然后在代码里通过python-dotenv加载from dotenv import load_dotenv load_dotenv()如果使用 OpenAI 兼容接口的其他服务商把OPENAI_BASE_URL换成服务商提供的地址即可但要注意路径中通常需要保留/v1。密钥不要写进代码更不要提交到 Git 仓库。注意不要把 .env 文件提交到 Git 仓库。正确做法是把.env.example提交到仓库保留字段名和注释实际密钥留在本地或密钥管理服务中。ChatOpenAI常用参数如下参数作用常见值调大/调小的影响model模型名按服务商支持列表模型名必须准确否则直接报错temperature采样随机性0 到 1调高更发散调低更确定max_tokens单次输出上限按实际需要太小会截断输出太大会增加成本timeout请求超时时间30 到 60 秒太小容易超时太大请求会挂起base_urlOpenAI 兼容端点服务商提供的地址不填时使用官方默认地址不是所有模型都支持所有参数。例如某些推理模型对reasoning_content、thinking 字段有特殊要求某些模型不支持视觉输入。落地前要按服务商文档确认参数兼容性。3. 先从 Model 开始搭建第一个可对话程序3.1 用 ChatOpenAI 完成最小模型调用在项目目录创建01_model_basic.pyfrom dotenv import load_dotenv from langchain_core.messages import HumanMessage, SystemMessage from langchain_openai import ChatOpenAI load_dotenv() llm ChatOpenAI( modelgpt-4o-mini, temperature0.7, max_tokens512, ) messages [ SystemMessage(content你是一名 Python 后端开发导师回答要简洁、分点。), HumanMessage(content用 3 句话说明什么是 LangChain。), ] resp llm.invoke(messages) print(type(resp)) print(resp.content)运行python 01_model_basic.py这里的关键点是消息对象。SystemMessage负责定义系统人设HumanMessage是用户输入。ChatOpenAI接收的是一个消息列表而不是普通字符串。llm.invoke()返回的是AIMessage对象真正模型生成的文本在resp.content中。初学者最容易在这里犯第一个错以为invoke返回的是字符串直接拿去拼接或做len()。实际返回的是消息对象后续需要输出解析器处理。3.2 使用 PromptTemplate 和 LCEL 组合提示词链路固定 messages 的方式不适合真实业务。用户需求不同角色不同步骤数量也不同。此时应该使用提示词模板。创建02_prompt_chain.pyfrom dotenv import load_dotenv from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI load_dotenv() prompt ChatPromptTemplate.from_messages( [ (system, 你是一个严谨的{role}。), (human, 请把下面的需求拆解成{step_count}个步骤{task}), ] ) llm ChatOpenAI(modelgpt-4o-mini, temperature0.3) chain prompt | llm | StrOutputParser() result chain.invoke( { role: 技术负责人, step_count: 3, task: 搭建一个带用户登录的博客系统, } ) print(result)这段代码引入了 LangChain 最常见的组合语法 LCEL。prompt | llm | StrOutputParser()表示数据依次经过提示词模板、模型、输出解析器。StrOutputParser会自动从AIMessage中取出content所以result就是纯字符串。模板中的{role}、{step_count}、{task}是占位变量调用invoke时通过字典传入。这样业务代码只需要维护模板和变量不需要每次拼字符串。3.3 输出解析不要把 AIMessage 当字符串用很多新手在拿到模型返回后直接打印resp发现打印出来的内容看起来像字符串但一拼接就报错。这是因为AIMessage重写了显示逻辑实际对象还包含元数据。错误写法print(模型内容长度:, len(resp)) # 很可能报错正确写法print(模型内容:, resp.content) print(结束原因:, resp.response_metadata.get(finish_reason))需要结构化
零基础入门LangChain：从Model到Agent构建AI应用
零基础入门 LangChain 时很多人的第一反应是直接去写 Agent结果连 ChatModel 的返回对象都没搞清楚就卡住了。LangChain 本身不是一个大模型它是一套面向大模型应用开发的框架用来解决提示词管理、模型接入、工具调用、上下文记忆和应用组装这些重复工程问题。这篇文章从零开始按照 Model、Prompt、Chain、Tool、Agent、Memory 的顺序带读者搭建一个最小可运行的 AI 智能应用。代码以 Python 为准使用 OpenAI 兼容接口开发机和本地虚拟环境即可完成测试。读完以后读者可以理解 LangChain 的工作方式知道 Agent 是如何让模型调用外部工具的也能在遇到模型名、上下文窗口和工具调用相关报错时定位问题。需要先说明学习路径Agent 是 LangChain 中最吸引人的部分但它不是独立功能而是模型、提示词、工具和记忆的组合产物。因此正文先用最小示例跑通 Model再逐步加入 Prompt 和 Tool最后组装 Agent。学习顺序不对后面排查过程会非常痛苦。1. 先建立对 LangChain 的基础认知框架、组件与工作方式1.1 LangChain 到底解决什么问题大模型 SDK 本身就能完成一次对话例如直接调用 OpenAI 的接口把 messages 数组传过去拿到一段文本。既然 SDK 已经能做这件事为什么还需要 LangChain因为真实应用不只是一次对话。业务里通常需要处理这样几类重复工作根据用户输入动态构造提示词而不是手写字符串拼接。把模型返回的文本解析成 JSON、代码块或结构化字段。在多轮对话中保存历史消息控制上下文长度。让模型调用外部系统例如搜索、数据库查询、计算器、工时系统。在多个模型厂商之间切换而不改动业务代码。LangChain 把这些能力抽象成组件模型是ChatModel提示词是PromptTemplate工具是Tool记忆是MemoryAgent 是组合这些组件的执行器。对零基础读者来说核心价值不是某个 API 的用法而是组件化思维。明白了每个组件负责什么后续遇到报错才能知道问题出在哪一层。1.2 核心组件速览在动手写代码前先把常见组件的作用和典型实现对齐组件作用典型实现ChatModel封装大模型对话接口ChatOpenAIPromptTemplate生成带变量的提示词模板ChatPromptTemplate、PromptTemplateChain把多个组件组合成调用链路prompt | llm | parserTool给模型提供外部能力tool装饰的函数Agent让模型自主决定调用哪些工具create_react_agent、AgentExecutorMemory保存多轮对话上下文ConversationBufferMemoryRetriever从向量库检索相关资料用于 RAG后续扩展常见组件其中 Chain 和 Agent 的区别尤其重要。普通 Chain 是固定的链路用户输入先进 Prompt再交给模型最后经解析器输出。Agent 则不同模型输出一段“思考”框架解析出要调用的工具名和参数执行工具后把结果返回给模型模型根据结果继续思考直到给出最终答案。这个循环就是 Agent 和普通 prompt 调用的本质差异。1.3 为什么 Agent 不等于 ChatModel 调用模型只会生成文本它不会真的执行系统函数。你问模型“现在几点”模型如果不知道当前时间它只能编造一个时间。Agent 解决的是“让模型把文本决策变成程序行为”这件事。举个例子给模型提供一个get_current_time工具。用户提问后模型先输出一个 Action 指令框架解析指令后调用真实函数把函数返回值作为 Observation 放回模型上下文模型再根据真实时间生成最终回答。整个过程模型没有直接执行函数但它通过文本决策“触发”了程序执行。理解这一点就能理解 Agent 为什么需要工具描述、参数 schema 和执行循环而不是简单地在提示词里写“你会调用时间函数”就能生效。2. 环境准备Python 虚拟环境、依赖安装与模型接入配置2.1 准备 Python 环境与项目目录建议使用 Python 3.10 或更高版本。第一步确认本机 Python 版本python --version如果版本过低需要先安装新版本 Python。随后创建项目目录和虚拟环境mkdir -p langchain-demo cd langchain-demo python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate虚拟环境的作用是把项目依赖和本机全局 Python 包隔离。避免不同项目依赖冲突这是 Python 工程里最基本的一步。检查点命令行前缀出现(.venv)表示已经进入虚拟环境。2.2 安装 LangChain 相关依赖包学习环境只需要安装这几个包python -m pip install --upgrade pip python -m pip install langchain langchain-core langchain-openai python-dotenv依赖包用途langchainLangChain 生态主体包含 Agent、Memory 等组件langchain-core核心抽象如消息对象、工具、提示词模板langchain-openai通过 OpenAI 兼容接口接入大模型python-dotenv从 .env 文件加载环境变量如果后续需要社区集成工具例如网页搜索、文件读取、数据库连接器等可以再安装langchain-community。安装版本以 pip 显示的当前稳定版为准不建议盲目追求最新0.2、0.3 系列对初学者已经足够。安装完成后快速验证python -c import langchain_openai; print(langchain-openai ok) python -c from dotenv import load_dotenv; print(dotenv ok)如果能正常打印说明依赖安装没有缺失。2.3 配置模型接入环境变量与 OpenAI 兼容接口LangChain 的ChatOpenAI默认从环境变量OPENAI_API_KEY读取密钥从OPENAI_BASE_URL读取接口地址。在项目根目录创建.env文件OPENAI_API_KEYsk-你的密钥 OPENAI_BASE_URLhttps://api.openai.com/v1然后在代码里通过python-dotenv加载from dotenv import load_dotenv load_dotenv()如果使用 OpenAI 兼容接口的其他服务商把OPENAI_BASE_URL换成服务商提供的地址即可但要注意路径中通常需要保留/v1。密钥不要写进代码更不要提交到 Git 仓库。注意不要把 .env 文件提交到 Git 仓库。正确做法是把.env.example提交到仓库保留字段名和注释实际密钥留在本地或密钥管理服务中。ChatOpenAI常用参数如下参数作用常见值调大/调小的影响model模型名按服务商支持列表模型名必须准确否则直接报错temperature采样随机性0 到 1调高更发散调低更确定max_tokens单次输出上限按实际需要太小会截断输出太大会增加成本timeout请求超时时间30 到 60 秒太小容易超时太大请求会挂起base_urlOpenAI 兼容端点服务商提供的地址不填时使用官方默认地址不是所有模型都支持所有参数。例如某些推理模型对reasoning_content、thinking 字段有特殊要求某些模型不支持视觉输入。落地前要按服务商文档确认参数兼容性。3. 先从 Model 开始搭建第一个可对话程序3.1 用 ChatOpenAI 完成最小模型调用在项目目录创建01_model_basic.pyfrom dotenv import load_dotenv from langchain_core.messages import HumanMessage, SystemMessage from langchain_openai import ChatOpenAI load_dotenv() llm ChatOpenAI( modelgpt-4o-mini, temperature0.7, max_tokens512, ) messages [ SystemMessage(content你是一名 Python 后端开发导师回答要简洁、分点。), HumanMessage(content用 3 句话说明什么是 LangChain。), ] resp llm.invoke(messages) print(type(resp)) print(resp.content)运行python 01_model_basic.py这里的关键点是消息对象。SystemMessage负责定义系统人设HumanMessage是用户输入。ChatOpenAI接收的是一个消息列表而不是普通字符串。llm.invoke()返回的是AIMessage对象真正模型生成的文本在resp.content中。初学者最容易在这里犯第一个错以为invoke返回的是字符串直接拿去拼接或做len()。实际返回的是消息对象后续需要输出解析器处理。3.2 使用 PromptTemplate 和 LCEL 组合提示词链路固定 messages 的方式不适合真实业务。用户需求不同角色不同步骤数量也不同。此时应该使用提示词模板。创建02_prompt_chain.pyfrom dotenv import load_dotenv from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI load_dotenv() prompt ChatPromptTemplate.from_messages( [ (system, 你是一个严谨的{role}。), (human, 请把下面的需求拆解成{step_count}个步骤{task}), ] ) llm ChatOpenAI(modelgpt-4o-mini, temperature0.3) chain prompt | llm | StrOutputParser() result chain.invoke( { role: 技术负责人, step_count: 3, task: 搭建一个带用户登录的博客系统, } ) print(result)这段代码引入了 LangChain 最常见的组合语法 LCEL。prompt | llm | StrOutputParser()表示数据依次经过提示词模板、模型、输出解析器。StrOutputParser会自动从AIMessage中取出content所以result就是纯字符串。模板中的{role}、{step_count}、{task}是占位变量调用invoke时通过字典传入。这样业务代码只需要维护模板和变量不需要每次拼字符串。3.3 输出解析不要把 AIMessage 当字符串用很多新手在拿到模型返回后直接打印resp发现打印出来的内容看起来像字符串但一拼接就报错。这是因为AIMessage重写了显示逻辑实际对象还包含元数据。错误写法print(模型内容长度:, len(resp)) # 很可能报错正确写法print(模型内容:, resp.content) print(结束原因:, resp.response_metadata.get(finish_reason))需要结构化