这次我们来看一个 LangChain 1.3 的实战教程。LangChain 作为当前构建大语言模型应用最流行的框架之一其核心价值在于将复杂的 LLM 交互、工具调用和流程编排标准化。对于开发者而言最关心的问题往往是它到底好不好用学习曲线陡不陡能不能快速搭建出可用的 Agent 或工作流这篇文章将直接切入 LangChain 1.3 的核心从模型初始化、工具调用到构建一个完整的 Agent 工作流并提供可直接运行的代码和面试常见问题解析。无论你是想快速上手项目还是为技术面试做准备这篇文章都能提供一条清晰的路径。LangChain 1.3 版本在工具调用、工作流编排和与 LangGraph 的集成上做了不少优化。它的特点非常明确第一提供了高度模块化的组件如模型 I/O、检索、记忆、代理等可以像搭积木一样构建应用第二支持与多种大模型OpenAI、Anthropic、本地模型等和外部工具搜索引擎、API、数据库无缝集成第三通过 Agent 和 LangGraph 支持复杂、有状态的对话和工作流。本文将重点演示如何用最少的代码实现一个具备联网搜索和计算能力的智能助手并剖析其背后的运行机制。1. 核心能力速览在深入代码之前我们先快速了解 LangChain 1.3 的核心能力和技术门槛这有助于判断它是否适合你的项目。能力项说明项目类型大语言模型应用开发框架 (Python/JS)核心功能模型 I/O 封装、提示模板、记忆管理、数据检索、工具调用、代理Agent、工作流编排LangGraph硬件门槛无特定要求。框架本身是 Python 库资源消耗取决于你集成的 LLM。调用云端 API如 GPT-4则只需网络部署本地模型则需要相应 GPU 资源。启动方式通过pip install langchain安装在 Python 脚本或 Jupyter Notebook 中导入使用。接口能力主要提供编程接口Python/JS SDK。可通过 FastAPI 等 Web 框架轻松封装成 REST API 服务。批量任务支持通过Chain或自定义逻辑处理批量输入例如批量总结文档、批量分类等。关键优势模块化设计、丰富的集成生态大量第三方工具、活跃的社区、清晰的抽象层。学习难点概念较多Chain, Agent, Tool, Memory等需要理解其设计哲学不同版本间 API 可能有变化。适合场景快速构建基于 LLM 的聊天机器人、智能客服、文档分析工具、自动化工作流、复杂决策 Agent。2. 适用场景与使用边界LangChain 不是一个“开箱即用”的最终产品而是一个开发框架。理解它能做什么、不能做什么是高效使用它的第一步。它非常适合以下场景需要连接外部知识和工具的聊天机器人比如一个能查询天气、搜索最新资讯、计算数学公式的助手。基于私有数据的问答系统利用其检索增强生成RAG能力让 LLM 基于你的文档、数据库回答问题。自动化工作流例如自动读取邮件附件、总结内容、分类并存入数据库这一系列操作可以用 LangChain 的 Chain 和 Agent 串联。复杂、多步骤的推理任务Agent 可以自主规划步骤调用不同工具来完成任务如“分析这家公司的财报并预测其下季度趋势”。原型快速验证由于其模块化特性开发者可以快速组合不同组件验证一个 AI 应用的想法是否可行。它的局限和不适合的场景超高性能、超低延迟场景LangChain 的抽象层会带来一定的开销。如果是对延迟极其敏感的单一模型调用直接使用模型的原生 SDK 可能更高效。极其简单的单一功能如果只是需要调用一次 API 完成文本生成直接使用requests库调用模型接口更直接。希望完全黑盒、无需编码LangChain 需要编程能力。如果你想要无代码平台可以考虑 Dify、Coze 等基于 LangChain 封装的在线工具。对应用体积有极端要求LangChain 及其依赖包体积不小在极度受限的环境如某些边缘设备部署可能困难。安全与合规边界模型责任LangChain 负责编排生成内容的责任最终在于你所集成的 LLM。你需要确保所用 LLM 符合内容安全政策。工具安全谨慎集成外部工具如执行 Shell 命令、访问数据库的 Tool避免产生安全漏洞。数据隐私通过 RAG 处理敏感数据时需确保数据存储、检索过程的安全并了解 LLM 服务提供商的数据使用政策。3. 环境准备与前置条件开始实战前需要准备好开发环境。以下是基于 Python 的通用环境清单。基础环境操作系统Windows 10/11, macOS, 或 Linux (推荐 Ubuntu)。LangChain 是跨平台的。Python 版本Python 3.8 或更高版本。建议使用 3.10 或 3.11以获得最好的兼容性。包管理工具pip或conda。本文使用pip。关键依赖安装核心是langchain包。但为了完成一个完整的 Agent 示例我们还需要一些额外的组件。LangChain 核心库提供基础组件。LangChain 社区工具包包含许多社区维护的 Tool 和集成。大模型接入以 OpenAI API 为例需要openai库。如果你使用其他模型如 Anthropic、本地 Hugging Face 模型则需要安装对应的库。环境变量管理推荐使用python-dotenv来管理 API 密钥等敏感信息。可选LangGraph用于构建更复杂、有状态的工作流通过langgraph安装。快速环境搭建命令打开你的终端或命令行创建一个新的项目目录并安装依赖。# 1. 创建并进入项目目录 mkdir langchain-tutorial cd langchain-tutorial # 2. 创建虚拟环境 (可选但推荐) python -m venv venv # Windows 激活 venv\Scripts\activate # macOS/Linux 激活 source venv/bin/activate # 3. 安装核心依赖 pip install langchain langchain-community langchain-openai python-dotenv # 4. 安装 LangGraph (用于高级工作流) pip install langgraph # 5. 安装 requests 库用于示例中的工具 pip install requestsAPI 密钥准备本例使用 OpenAI GPT 模型你需要准备一个 OpenAI API Key。访问 OpenAI 平台创建 API Key。在项目根目录创建.env文件将密钥写入# .env 文件内容 OPENAI_API_KEY你的-sk-...密钥确保在代码中安全加载这个密钥。4. 模型初始化与基础 Chain 使用一切从初始化 LLM 开始。这是与 LangChain 交互的起点。4.1 初始化 OpenAI 模型首先我们学习如何正确初始化一个 LLM 对象。这里使用ChatOpenAI它是 LangChain 对 OpenAI 聊天模型的封装。# 文件basic_llm.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI # 1. 从 .env 文件加载环境变量 load_dotenv() # 2. 初始化 LLM # 使用 gpt-3.5-turbo 模型温度设为 0.7 以平衡创造性和一致性 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0.7, api_keyos.getenv(OPENAI_API_KEY) # 安全地从环境变量读取 ) # 3. 进行简单的调用 response llm.invoke(你好请用一句话介绍 LangChain。) print(response.content)运行这段代码你应该能看到模型返回的一句关于 LangChain 的介绍。llm.invoke是同步调用方法。LangChain 也支持llm.ainvoke进行异步调用。4.2 使用提示模板PromptTemplate直接传递字符串给模型不够灵活。LangChain 提供了PromptTemplate来结构化提示词。# 文件prompt_template.py from langchain.prompts import PromptTemplate from langchain_openai import ChatOpenAI from dotenv import load_dotenv import os load_dotenv() llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.7) # 1. 创建模板用花括号 {} 定义变量 template 你是一位专业的{role}。 请根据以下主题生成一份简洁的提纲。 主题{topic} prompt_template PromptTemplate.from_template(template) # 2. 格式化模板传入变量值 formatted_prompt prompt_template.format(role技术作家, topic如何学习 Python) print(格式化后的提示词\n, formatted_prompt) # 3. 将格式化后的提示词传递给 LLM response llm.invoke(formatted_prompt) print(\n模型回复\n, response.content)4.3 构建第一个 ChainLLMChainChain是 LangChain 的核心抽象它将 LLM 和提示模板以及其他组件链接起来形成一个可复用的处理单元。# 文件first_chain.py from langchain.prompts import PromptTemplate from langchain.chains import LLMChain from langchain_openai import ChatOpenAI from dotenv import load_dotenv import os load_dotenv() llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.7) # 1. 定义模板和 Chain template 将以下中文翻译成英文{input_text} prompt PromptTemplate.from_template(template) # 创建 LLMChain绑定 llm 和 prompt translation_chain LLMChain(llmllm, promptprompt) # 2. 运行 Chain result translation_chain.invoke({input_text: 今天天气真好适合学习 LangChain。}) print(result[text]) # 输出The weather is really nice today, perfect for learning LangChain.LLMChain的invoke方法接收一个字典字典的键对应提示模板中的变量名。它自动完成格式化提示词、调用模型、返回结果的过程。5. 工具Tool的创建与集成Agent 之所以智能是因为它能使用工具。工具可以是任何函数比如搜索网络、查询数据库、执行计算。5.1 创建一个自定义工具我们将创建一个获取当前时间的工具和一个计算数学表达式的工具。# 文件custom_tools.py from langchain.tools import Tool from datetime import datetime import math import requests # 工具1获取当前时间 def get_current_time(_): 返回当前的日期和时间。 return datetime.now().strftime(%Y-%m-%d %H:%M:%S) # 工具2计算数学表达式使用 eval生产环境请谨慎使用 def calculate(expression: str) - str: 计算一个数学表达式例如 ‘2 3 * 4‘。 try: # 警告在生产环境中直接使用 eval 是危险的应使用安全库如 ast.literal_eval 或专门数学库 result eval(expression, {__builtins__: None}, {math: math}) return str(result) except Exception as e: return f计算错误{e} # 工具3模拟一个网络搜索实际可使用 SerpAPI、DuckDuckGo 等 def search_web(query: str) - str: 模拟网络搜索返回模拟结果。实际应接入真实搜索 API。 # 这里只是一个模拟。真实情况可以调用 SerpAPI、Google Custom Search 等。 return f关于 ‘{query}‘ 的模拟搜索结果... (此处省略) # 使用 Tool.from_function 包装函数创建 LangChain Tool 对象 time_tool Tool.from_function( funcget_current_time, nameGetCurrentTime, description当需要知道当前日期和时间时使用此工具。 ) calc_tool Tool.from_function( funccalculate, nameCalculator, description用于计算数学表达式。输入应是一个有效的数学表达式字符串如 ‘(35)*2‘。 ) search_tool Tool.from_function( funcsearch_web, nameWebSearch, description用于搜索互联网上的最新信息。输入是一个搜索查询词。 ) # 将工具放入列表供后续 Agent 使用 tools [time_tool, calc_tool, search_tool] # 测试单个工具 print(time_tool.invoke()) print(calc_tool.invoke(3.14 * 10))5.2 使用社区预置工具LangChain-Community 库提供了大量预置工具无需自己从头编写。例如使用DuckDuckGoSearchRun进行真实搜索需要安装duckduckgo-search。pip install duckduckgo-search# 文件community_tool.py from langchain_community.tools import DuckDuckGoSearchRun from langchain.tools import Tool # 创建搜索工具实例 search DuckDuckGoSearchRun() # 包装成 Tool 对象方便与 Agent 集成 ddg_tool Tool.from_function( funcsearch.run, nameDuckDuckGo Search, description使用 DuckDuckGo 搜索引擎获取实时信息。 ) # 测试 result ddg_tool.invoke(LangChain 最新版本) print(result[:500]) # 打印前500个字符6. 构建智能 Agent 工作流Agent 是 LangChain 的明星功能。它根据用户输入和可用工具自主决定是调用工具还是直接由 LLM 回答。6.1 创建并运行一个 ReAct AgentReAct 是一种经典的 Agent 推理模式。LangChain 内置了create_react_agent来简化创建。# 文件react_agent.py from langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI from dotenv import load_dotenv import os # 导入之前自定义的工具 from custom_tools import tools load_dotenv() llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyos.getenv(OPENAI_API_KEY)) # 1. 从 LangChain Hub 拉取一个 ReAct 风格的提示词模板 # 这是一个社区共享的、经过优化的提示词用于指导 Agent 进行推理和工具调用。 prompt hub.pull(hwchase17/react) # 2. 创建 ReAct Agent agent create_react_agent(llm, tools, prompt) # 3. 创建 Agent 执行器它负责运行 Agent 的循环思考-行动-观察 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 4. 运行 Agent提出一个需要结合工具才能回答的问题 question “现在是什么时间另外请计算 15 的平方根是多少” result agent_executor.invoke({input: question}) print(\n最终答案, result[output])运行这段代码你将看到verboseTrue模式下 Agent 的详细思考过程Thought/Action/Observation最终它会调用GetCurrentTime和Calculator工具并给出综合答案。6.2 使用 LangGraph 构建有状态的工作流对于更复杂、多步骤、需要记忆状态的场景LangGraph比基础的AgentExecutor更强大。它允许你以图Graph的形式定义工作流。下面我们构建一个简单的“研究助手”工作流先搜索再总结。# 文件langgraph_workflow.py from typing import TypedDict, Annotated, List import operator from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI from langchain.prompts import PromptTemplate from langchain_core.messages import HumanMessage, SystemMessage from dotenv import load_dotenv import os # 使用社区的真实搜索工具 from langchain_community.tools import DuckDuckGoSearchRun load_dotenv() llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 1. 定义工作流的状态State # 这是一个 TypedDict定义了在整个图执行过程中传递的数据结构。 class ResearchState(TypedDict): question: str # 用户原始问题 search_results: str # 搜索工具返回的结果 final_answer: str # 最终生成的答案 # 2. 定义节点Node函数 # 节点是工作流中的步骤每个节点接收状态修改后返回新状态。 def search_node(state: ResearchState) - ResearchState: 搜索节点调用搜索工具获取信息。 print(“【工作流】进入搜索节点...”) search_tool DuckDuckGoSearchRun() search_results search_tool.run(state[“question”]) # 更新状态 return {“search_results”: search_results, **state} def summarize_node(state: ResearchState) - ResearchState: 总结节点基于搜索结果让 LLM 生成最终答案。 print(“【工作流】进入总结节点...”) # 构建提示词 template “”” 你是一个研究助手。请基于以下搜索结果为用户的问题提供一个全面、简洁的答案。 如果搜索结果中没有相关信息请如实说明。 用户问题{question} 搜索结果 {search_results} 请生成答案 “”” prompt PromptTemplate.from_template(template) formatted_prompt prompt.format(questionstate[“question”], search_resultsstate[“search_results”]) # 调用 LLM response llm.invoke(formatted_prompt) # 更新状态 return {“final_answer”: response.content, **state} # 3. 构建图Graph workflow StateGraph(ResearchState) # 添加节点 workflow.add_node(“search”, search_node) workflow.add_node(“summarize”, summarize_node) # 设置边的连接关系从起点开始先搜索再总结然后结束。 workflow.set_entry_point(“search”) workflow.add_edge(“search”, “summarize”) workflow.add_edge(“summarize”, END) # 编译图得到可执行的应用 app workflow.compile() # 4. 执行工作流 initial_state {“question”: “2024年巴黎奥运会中国代表团获得了多少枚金牌”, “search_results”: “”, “final_answer”: “”} final_state app.invoke(initial_state) print(“\n” “”*50) print(“用户问题”, final_state[“question”]) print(“\n最终答案\n”, final_state[“final_answer”])这个例子展示了 LangGraph 的核心概念State、Node、Graph。你可以通过添加条件边conditional edges来构建更复杂的决策流程例如让 LLM 判断搜索结果是否足够不够则重新搜索。7. 接口 API 封装与批量任务处理将 LangChain 应用封装成 API 服务是投入生产环境的关键一步。同时处理批量任务能极大提升效率。7.1 使用 FastAPI 封装为 REST API我们将上面的 ReAct Agent 封装成一个简单的 HTTP 服务。# 文件api_server.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from langchain.agents import AgentExecutor, create_react_agent from langchain import hub from langchain_openai import ChatOpenAI from custom_tools import tools # 导入之前定义的工具列表 from dotenv import load_dotenv import os import uvicorn load_dotenv() # 初始化 LLM 和 Agent启动时初始化一次避免每次请求重复创建 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0, api_keyos.getenv(“OPENAI_API_KEY”)) prompt hub.pull(“hwchase17/react”) agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseFalse, handle_parsing_errorsTrue) app FastAPI(title“LangChain Agent API”) # 定义请求体模型 class AgentRequest(BaseModel): query: str # 定义响应体模型 class AgentResponse(BaseModel): answer: str status: str “success” app.post(“/ask”, response_modelAgentResponse) async def ask_agent(request: AgentRequest): “””接收用户查询通过 Agent 处理并返回答案。””” try: result agent_executor.invoke({“input”: request.query}) return AgentResponse(answerresult[“output”]) except Exception as e: raise HTTPException(status_code500, detailf“Agent 执行失败: {str(e)}”) app.get(“/health”) async def health_check(): return {“status”: “ok”} if __name__ “__main__”: # 启动服务监听 8000 端口 uvicorn.run(app, host“0.0.0.0”, port8000)运行python api_server.py后服务将在http://127.0.0.1:8000启动。你可以使用curl或 Postman 进行测试curl -X POST “http://127.0.0.1:8000/ask \ -H “Content-Type: application/json” \ -d ‘{“query”: “现在几点了计算一下 98 的平方。”}’7.2 批量任务处理模式LangChain 的Chain和大多数组件都支持批量输入。核心是使用invoke或batch方法处理列表。# 文件batch_processing.py from langchain.prompts import PromptTemplate from langchain.chains import LLMChain from langchain_openai import ChatOpenAI from dotenv import load_dotenv import os load_dotenv() llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0.7, api_keyos.getenv(“OPENAI_API_KEY”)) # 创建一个翻译 Chain template “将以下中文句子翻译成英文{sentence}” prompt PromptTemplate.from_template(template) translation_chain LLMChain(llmllm, promptprompt) # 待处理的批量输入 batch_inputs [ {“sentence”: “人工智能正在改变世界。”}, {“sentence”: “LangChain 简化了大模型应用的开发。”}, {“sentence”: “今天天气晴朗心情愉悦。”}, ] # 方法1使用 batch 方法如果模型支持 # results translation_chain.batch(batch_inputs) # 方法2循环调用 invoke更通用 results [] for input_dict in batch_inputs: result translation_chain.invoke(input_dict) results.append(result[‘text’]) print(f“输入: {input_dict[‘sentence’]}”) print(f“输出: {result[‘text’]}\n”) print(“批量处理完成。”)对于更复杂的 Agent 批量任务需要注意资源管理批量调用 API 可能触及速率限制需要加入延迟或使用异步。错误处理某个任务失败不应导致整个批量任务中止需要 try-catch。状态隔离确保每个任务的处理是独立的避免状态污染。8. 常见问题与排查方法在开发和部署 LangChain 应用时你可能会遇到以下典型问题。问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named ‘langchain_community’未安装langchain-community包或版本不匹配。检查pip list确认已安装。运行pip install langchain-community。确保 LangChain 核心库版本与之兼容。Agent 一直循环思考不输出最终答案Agent 无法理解任务或工具描述不清导致它在“思考”和“行动”间死循环。设置verboseTrue观察 Agent 的 Thought/Action 日志。1. 优化工具的描述description使其更精确。2. 调整提示词或使用更强大的模型如 GPT-4。3. 设置max_iterations参数限制循环次数。调用 OpenAI API 超时或报错网络问题、API 密钥错误、额度不足、或服务器端问题。检查网络连接在 OpenAI 平台验证 API Key 状态和余额。1. 使用python-dotenv正确管理密钥。2. 增加请求超时时间。3. 查看 OpenAI 官方状态页。工具调用失败Tool抛出异常工具函数内部代码有 bug或输入格式不符合预期。单独测试工具函数传入 Agent 调用时的参数。1. 在工具函数内部增加更健壮的异常处理和输入验证。2. 确保工具返回字符串类型。LangGraph工作流状态不更新节点函数没有正确返回新的状态字典或状态字段名不匹配。在每个节点函数内打印state检查输入和输出。确保节点函数返回的字典包含了所有需要传递到下一步的状态字段。可以使用{**state, “new_key”: “value”}语法。处理长文档时内存溢出或速度慢一次性将整个文档传给 LLM超出上下文长度或处理能力。监控内存使用和 API 调用耗时。使用RecursiveCharacterTextSplitter等文本分割器将文档切块结合RetrievalQA链进行检索增强生成RAG。部署为 API 后并发请求处理能力差Agent 或 Chain 初始化耗时或同步处理阻塞。使用压力测试工具如locust测试 API。1. 将 LLM 和 Chain 对象设为全局变量避免每次请求重复初始化。2. 对于高并发考虑使用异步框架如FastAPI配合async/await和 LangChain 的异步方法ainvoke。9. 最佳实践与使用建议遵循这些实践可以让你的 LangChain 项目更加稳健和高效。从简单开始逐步复杂化不要一开始就设计庞大的工作流。先验证单个 Chain 或 Tool 是否工作再组合成 Agent最后考虑用 LangGraph 编排复杂流程。管理好你的提示词Prompt提示词是 LangChain 应用的“灵魂”。将提示词模板化、模块化并存储在单独的文件或数据库中便于管理和 A/B 测试。为工具编写清晰、具体的描述Agent 依赖工具的描述来决定何时调用它。描述应准确说明工具的功能、输入格式和适用场景。实施严格的错误处理在工具函数、Chain 调用和 API 端点处都要有 try-catch。对于可能失败的步骤如网络调用设计重试机制和降级方案。关注成本和性能成本使用 Token 计数器估算 API 调用成本对批量任务尤其重要。性能使用verbose模式或 LangSmith 进行性能追踪找出瓶颈是工具调用慢还是 LLM 响应慢。利用 LangSmith 进行调试和监控LangSmith 是 LangChain 官方提供的调试和监控平台。它能可视化展示 Chain 和 Agent 的执行轨迹是排查复杂问题的利器。安全第一环境变量永远不要将 API 密钥硬编码在代码中。工具权限谨慎授予工具高权限如文件写入、系统命令执行。必要时进行沙箱隔离或输入净化。输出审查对于面向公众的应用建立对 LLM 生成内容的过滤或审查机制防止有害内容输出。为生产环境而设计API 封装使用像 FastAPI 这样的成熟框架来提供稳定、可监控的 HTTP 接口。配置化将模型类型、温度、工具列表等参数配置化便于在不同环境开发/测试/生产切换。日志记录记录详细的运行日志包括用户输入、Agent 的思考过程、工具调用结果和最终输出便于审计和问题回溯。10. 总结与下一步LangChain 1.3 通过其清晰的模块化设计大幅降低了构建复杂 LLM 应用的门槛。本次教程的核心路径是初始化模型 - 创建工具 - 组装成 Agent - 用 LangGraph 编排工作流 - 封装为 API 服务。这条路径覆盖了从开发到部署的主要环节。最值得优先尝试的是将一个具体的业务需求拆解成“LLM推理”和“工具调用”的组合。例如一个自动周报生成器工具可以读取 Git 提交、查询 JIRA 任务LLM 负责总结和润色。先用简单的 Chain 验证每个环节再用 Agent 串联起来。最容易踩的坑集中在工具描述不清导致 Agent 循环、API 密钥等配置管理不当以及对 LangChain 抽象层的性能开销预期不足。启动新项目时建议先在 LangSmith 上跑通一个最小原型它能直观展示每一步的输入输出极大提升调试效率。下一步你可以深入探索高级记忆Memory为 Agent 添加对话历史记忆构建真正连贯的聊天体验。检索增强生成RAG结合向量数据库如 Chroma, Pinecone让 LLM 基于你的私有知识库回答问题。多智能体Multi-Agent系统使用 LangGraph 协调多个具有不同专长的 Agent 协作完成任务。与前端集成将封装好的 FastAPI 服务与 Web 或移动前端连接打造完整的 AI 应用。建议将本文中的代码示例作为脚手架根据你的具体场景替换工具和调整提示词快速构建出属于你自己的智能体应用。