从零开始学习LangChain1.0

AI_小站

墨衍会员 · AI 创作全网分发码龄3年

关注

原创最新推荐文章于 2026-06-21 08:24:23 发布 852 阅读 AI 写同款· GEO 优化 ›

实战LLM应用（2）：搭建LangChain开发环境至此，本地langchain架构调用本地部署LLM流程跑通，建议后续每次开发工作在虚拟环境进行。阅读详情

引言

2025年10月20日, LangChain推出了1.0版本，在对象管理和消息结构上做了一些优化，新老版本的主要区别如下：

旧 LangChain (<1.0)	新 LangChain (1.0+)
Chain & Agent 各自为政	全部整合为基于 LangGraph 的 Agent 抽象
流程线性、难分支	流程图化，可并行、循环、条件判断
简单字符串消息	标准化的结构化消息格式（支持 reasoning、tool_call 等）
各模型接口不统一	统一消息格式和工具调用接口
向后兼容	旧版在 `langchain-classic` 中保留

本文根据新文档[1]对 LangChain 进行学习和实践，当前采用的版本是1.0.2。

快速上手

首先安装Langchain：

uv add langchain

官方给的示例采用claude-sonnet-4-5作为基础模型，在国内使用颇为不便。

下面的示例，我改成DeepSeek-V3.2，为此，需要额外安装两个依赖：

uv add dotenv langchain-openai

dotenv 用来动态加载环境变量，首先需要创建一个.env文件，然后将硅基流动平台[2]的 API-KEY 填进去：

SILICONFLOW_API_KEY=自己的apikey(sk-开头)

配置完后，就可以运行下面的示例，创建一个调用工具的 agent：

import osfrom dotenv import load_dotenvfrom langchain.agents import create_agentfrom langchain_openai import ChatOpenAIload_dotenv()defget_weather(city: str) -> str:"""Get weather for a given city."""returnf"It's always sunny in {city}!"llm = ChatOpenAI(    base_url="https://api.siliconflow.cn/v1",    api_key=os.getenv("SILICONFLOW_API_KEY"),    model="deepseek-ai/DeepSeek-V3.2-Exp",)agent = create_agent(    model=llm,    tools=[get_weather],    system_prompt="You are a helpful assistant",)response = agent.invoke(    {"messages": [{"role": "user", "content": "what is the weather in sf"}]})print(response)

这个示例是给定了一个函数，用来反馈模拟的天气信息，正常运行，返回的response包含以下内容：

顺序	消息类型	含义
①	HumanMessage	用户提问
②	AIMessage（带 tool_call）	模型决定调用工具
③	ToolMessage	工具执行的结果
④	AIMessage	模型根据工具返回结果生成最终回答

在步骤2中，实现第一次交互，模型发现该问题可以通过调用工具解决：

AIMessage(  content="I'll help you get the weather for SF (San Francisco). Let me check that for you.",  tool_calls=[    {"name": "get_weather","args": {"city": "San Francisco"},"id": "019a2bbb8379aef2b02235d132dcf621","type": "tool_call"    })

第4步，模型进行第二次交互，得到最终回答：

AIMessage(  content="It's always sunny in San Francisco! Looks like you'll have great weather there.")

需要注意的是，是否调用工具完全取决于模型自身的想法，有概率存在模型不去调用工具，而导致第一次交互就结束的情况。

在 siliconflow 中，可以在模型的选项卡中，看到模型是否具备工具调用的能力，如果配置了不会调用工具的模型，会出现异常的报错。

核心组件

智能体(Agent)

根据官方文档，智能体的定义是指语言模型与工具相结合，创建能够对任务进行推理、决定使用哪些工具并迭代地寻求解决方案的系统。

智能体停止运行有两种情况：模型发出最终输出或者达到迭代次数限制。

模型(Model)

模型是智能体的推理引擎。它们驱动智能体的决策过程，决定调用哪些工具、如何解释结果以及何时给出最终答案。

模型基本分两种模式：静态模型和动态模型。

静态模型

静态模型可以通过开篇提到的示例进行创建，除了ChatOpenAI之外，还可以用其它的拓展包去适配不同平台，具体可参考API接口文档[3]

from langchain_openai import ChatOpenAIllm = ChatOpenAI(    base_url="https://api.siliconflow.cn/v1",    api_key=os.getenv("SILICONFLOW_API_KEY"),    model="deepseek-ai/DeepSeek-V3.2-Exp",# stream_usage=True,# temperature=None,# max_tokens=None,# timeout=None,# reasoning_effort="low",# max_retries=2,)

除了示例用的基本参数外，还可以设定其它额外参数，这些参数的基本含义如下：

参数名	作用说明
`stream_usage`	是否以流式方式返回 token 消耗统计。如果为 True，将实时获取 tokens 消耗信息。
`temperature`	控制生成随机性，0 表示确定性回答，值越大越随机。
`max_tokens`	设置模型最多返回的 token 数。如果不设置则按模型默认值。
`timeout`	请求超时时间，超过该时间则中断请求。
`reasoning_effort`	推理强度设置，通常为 `"low"`, `"medium"`, `"high"`，用于推理模型（如 DeepSeek-R）。越高越慢，思考更多。
`max_retries`	API 调用失败时的最大重试次数。

动态模型

动态模型是指在运行时让Agent运行时根据当前状态和上下文信息，动态去调用不同的模型。

具体方式是wrap_model_call装饰器是创建中间件，然后在创建智能体时，添加middleware参数。

下面这个示例是根据上下文长度进行模型切换，如果上下文长度高于10，则采用advanced_model，否则采用basic_model。

如果需要在国内网络环境下跑通下面这个示例，可以参考上一节的方式去创建模型。

from langchain_openai import ChatOpenAIfrom langchain.agents import create_agentfrom langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponsebasic_model = ChatOpenAI(model="gpt-4o-mini")advanced_model = ChatOpenAI(model="gpt-4o")@wrap_model_calldefdynamic_model_selection(request: ModelRequest, handler) -> ModelResponse:"""Choose model based on conversation complexity."""    message_count = len(request.state["messages"])if message_count > 10:# Use an advanced model for longer conversations        model = advanced_modelelse:        model = basic_model    request.model = modelreturn handler(request)agent = create_agent(    model=basic_model,  # Default model    tools=tools,    middleware=[dynamic_model_selection])

工具(Tool)

工具是智能体调用以执行操作的组件。

创建工具可以采用@tool装饰器，下面是一个基本示例：

from langchain.tools import tool@tooldefsearch_database(query: str, limit: int = 10) -> str:returnf"Found {limit} results for '{query}'"

该装饰器可以进一步自定义名称和描述，下面的示例自定义了一个calculator工具，如果不定义，工具名称默认就是函数名称。

@tool("calculator", description="Performs arithmetic calculations. Use this for any math problems.")defcalc(expression: str) -> str:returnstr(eval(expression))

定义完工具后，可以在创建智能体时，通过tools参数进行指定工具，传入是一个列表，可以指定多个工具。

from langchain.tools import toolfrom langchain.agents import create_agent@tooldefsearch(query: str) -> str:returnf"Results for: {query}"agent = create_agent(model, tools=[search])

系统提示(System prompt)

系统提示是指创建Agent时，指定Agent处理任务的具体方式。

在创建Agent时，可以通过system_prompt参数进行指定。

from langchain.agents import create_agentagent = create_agent(    model,    tools,    system_prompt="You are a helpful assistant. Be concise and accurate.")

对于复杂的系统，可以进一步通过@dynamic_prompt创建中间件的方式来进行设定，这里不作详细描述。

消息(Message)

消息是模型的基本上下文单元。它们代表模型的输入和输出，携带与 LLM 交互时表示对话状态所需的内容和元数据。

在 LangChain 中，包含四种类型消息：

系统消息：告诉模型如何运行，并为交互提供上下文。
人类消息：代表用户输入以及与模型的交互
AI消息：模型生成的响应，包括文本内容、工具调用和元数据
工具消息：表示工具调用的输出

通过不同的消息定义，模型在交互时，可以辨别不同的消息来源。

短期记忆(Short-term memory)

短期记忆可以让应用程序记住单个线程或对话中的先前交互。

在创建agent时，可以指定checkpointer为InMemorySaver，用于保存保存对话历史记录，该信息临时存储在内存中，不持久。

from langchain.agents import create_agentfrom langgraph.checkpoint.memory import InMemorySaver  agent = create_agent("openai:gpt-5",    [get_user_info],    checkpointer=InMemorySaver(),  )

如果需要将记忆持久化，可以采用PostgresSaver，将记录存储到postgresql里面。

from langchain.agents import create_agentfrom langgraph.checkpoint.postgres import PostgresSaver  DB_URI = "postgresql://postgres:postgres@localhost:5442/postgres?sslmode=disable"with PostgresSaver.from_conn_string(DB_URI) as checkpointer:    checkpointer.setup() # auto create tables in PostgresSql    agent = create_agent("openai:gpt-5",        [get_user_info],        checkpointer=checkpointer,      )

除此之外，langchain还有一些接口，可以实现对记忆的修剪、删除和总结，以防超出模型的上下文窗口。

流式输出(Streaming)

流式输出逐步显示输出内容，以提升交互体验。

在langchain中，可通过以下方式获取流式响应信息：

from langchain.agents import create_agentagent = create_agent(    model="openai:gpt-5-nano")for chunk in agent.stream(      {"messages": [{"role": "user", "content": "What is the weather in SF?"}]},    stream_mode="updates",):for step, data in chunk.items():print(f"step: {step}")print(f"content: {data['messages'][-1].content_blocks}")

中间件(Middleware)

中间件提供了一种更严格地控制代理内部运行方式的方法，通过它能更好地控制Agent执行的内部逻辑。

在下图中，在agent/model/tool执行前后都可以插入中间件，以实现额外处理。

中间件有基于装饰器和基于类的两种模式。

基于装饰器的模式主要有以下分类：

装饰器	类型	触发时机 / 作用	说明
`@before_agent`	节点型	Agent 开始执行前（每次调用一次）	做初始化/准备工作，类似“启动钩子”
`@before_model`	节点型	每次模型推理前触发	可动态修改 prompt 或输入
`@after_model`	节点型	每次模型输出后触发	日志分析、结果处理、缓存
`@after_agent`	节点型	Agent 执行结束后触发（每次调用一次）	清理、总结、资源释放
`@wrap_model_call`	包裹型	拦截每次模型调用	可以修改输入/输出、跳过模型执行
`@wrap_tool_call`	包裹型	拦截每次工具调用	可实现权限控制/限流/日志/Mock 工具
`@dynamic_prompt`	便捷型	动态生成 System Prompt	相当于简化版 `@wrap_model_call`，专用于 prompt 注入

基于类的模式关键词差不多，只是调用方式略有区别。

langchain内置了一些常用中间件：

总结(Summarization):当接近Token限制时自动总结对话历史。
人机交互(HumanInTheLoop)：在工具调用执行之前，暂停代理执行，以便人工批准、编辑或拒绝。
人类提示缓存(AnthropicPromptCaching)：使用 Anthropic 模型缓存重复的提示前缀，从而降低成本。
模型调用限制(ModelCallLimit)：限制模型调用次数，以防止无限循环或过高的成本。
工具调用限制(ToolCallLimit)：限制工具调用次数，只能调用特定工具或所有工具。
模型回退(ModelFallback)：当主模型失效时，自动回退到备用模型。
PII 检测(PII)：检测和处理对话中的个人身份信息。
规划(TodoList)：为复杂的多步骤任务添加待办事项列表管理功能。
LLM工具选择器(LLMToolSelector)：使用 LLM 在调用主模型之前智能地选择相关工具。
工具重试(ToolRetry)：使用可配置的指数退避算法自动重试失败的工具调用。
LLM 工具模拟器(LLMToolEmulator)：使用 LLM 模拟工具执行以进行测试，用 AI 生成的响应替换实际的工具调用。
上下文编辑(ContextEditing)：通过精简、总结或清除工具使用情况来管理对话上下文。

结构化输出(Structured output)

结构化输出是指让Agent以特定格式返回数据。

langchain支持以下四种结构化输出模式：

Pydantic Model：带有字段验证的子类
数据类：带有类型注解的 Python 数据类
字典类：类型化字典类
JSON：包含 JSON Schema 规范的字典

以json格式化输出为例，可以通过response_format指定预定义的json格式：

from langchain.agents import create_agentcontact_info_schema = {"type": "object","description": "Contact information for a person.","properties": {"name": {"type": "string", "description": "The name of the person"},"email": {"type": "string", "description": "The email address of the person"},"phone": {"type": "string", "description": "The phone number of the person"}    },"required": ["name", "email", "phone"]}agent = create_agent(    model="openai:gpt-5",    tools=tools,    response_format=contact_info_schema  # Auto-selects ProviderStrategy)result = agent.invoke({"messages": [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]})print(result["structured_response"])