如果你正在学 LangChain却又感觉看完官方文档一头雾水——不知道 Model 怎么接、Agent 怎么调、RAG 怎么落地那这应该是目前最适合跟着一步步敲代码的入门到实战路线。这篇文章不堆概念直接按“搭环境 - 构建 Model - 串 Chain - 做 Agent - 接 RAG - 跑一个完整项目”的顺序带你走一遍每个环节给出可运行的代码和验证方式。1. 核心能力速览这一节先给结论让你快速判断接下来要读的内容适不适合你当前的需求。能力项说明框架定位LangChain 是面向大模型应用开发的编排框架核心解决 Model 调用、Prompt 管理、记忆、Agent 工具调用、RAG 检索增强等工程化问题开发语言Python 为主社区也有 JavaScript/TypeScript 版本模型接入支持 OpenAI 兼容接口、DeepSeek、智谱、通义千问、Ollama 本地模型、Hugging Face 模型等本地部署门槛纯 API 模式下无显卡要求使用 Ollama 本地模型时需要按模型实际体积预留内存或显存具体以模型官方说明为准核心功能Model 构建、Prompt 模板、Chain 链式调用、Memory 记忆、Agent 智能体、RAG 检索增强、批量任务是否支持 API 服务可以基于 FastAPI 封装为接口服务LangChain 本身不直接提供 HTTP Server是否支持批量任务支持可通过 for 循环、异步任务或队列方式对多条输入批量执行 Chain/Agent适合场景智能问答、文档知识库、自动化工作流、代码助手、数据分析 Agent、客服系统等学习成本概念较多建议先掌握 Model - Chain - Agent - RAG 这条主线再扩展记忆和工具从材料看当前 LangChain 生态已经非常成熟围绕它衍生出了 LangGraph用于有状态、可编排的 Agent 流程等进阶框架。所以在学会基础之后我会专门用一节讲清楚 LangChain 和 LangGraph 的关系避免你学完基础再绕弯路。2. 适用场景与使用边界LangChain 不是大模型本身而是“连接大模型与业务逻辑的胶水层”。这意味着你需要先有大模型的访问能力再考虑用 LangChain 做编排。2.1 适合什么场景快速构建问答机器人通过 Prompt Template 固定问答格式通过 Memory 维护多轮上下文。企业内部知识库结合向量数据库做 RAG让模型基于你的文档回答问题。自动化业务流程Agent 调用搜索、计算、数据库查询等工具自动完成多步任务。批量内容处理对大量文本统一进行摘要、分类、关键词提取。快速验证模型能力切换不同模型供应商时只需修改少量配置。2.2 不适合什么场景如果你的需求只是“调用一次 API 拿到结果”直接用requests或 OpenAI SDK 反而更轻量。如果你的应用需要复杂的并行分支、状态机式流程控制LangChain 基础版会显得力不从心这时候要考虑 LangGraph。如果你没有模型访问权限LangChain 本身不会给你提供模型能力。2.3 使用边界与合规提醒调用外部模型 API 时务必确认服务商的使用条款和数据隐私政策不要将敏感数据直接发送给第三方模型。使用 Agent 工具调用时工具可能执行搜索、文件操作、命令执行等动作必须在沙箱环境内测试限制工具的权限范围。构建知识库 RAG 时注意文档版权和数据来源合法性。如果使用本地模型请从正规渠道下载模型文件并核对模型许可证。3. 环境准备与前置条件LangChain 的环境准备非常简单这是它适合入门的原因之一。无论你用的是 Windows、macOS 还是 Linux只要本机有 Python 3.9 以上环境即可。3.1 安装 Python 与虚拟环境建议为项目单独创建虚拟环境避免依赖冲突。# 创建虚拟环境 python -m venv langchain-demo # 激活虚拟环境 # Windows langchain-demo\Scripts\activate # macOS / Linux source langchain-demo/bin/activate3.2 安装 LangChain 核心依赖pip install -U langchain langchain-community langchain-openai如果你想调用本地 Ollama 模型额外安装pip install ollama如果你计划使用 RAG 和向量数据库安装pip install chromadb pypdf docx2txt3.3 模型访问方式确认LangChain 可以接入两大类模型云端 API 模型需要 API Key。常见的有 OpenAI、DeepSeek、智谱 GLM、通义千问等。国内用户建议优先选择合规合法的国内服务商并在环境变量中配置。本地模型通过 Ollama 等工具在本地部署开源模型无需 API Key但需要足够的磁盘空间和内存/显存。这里给出一个本地 Ollama 的下载安装思路以 Linux/macOS 为例Windows 请从官网下载安装包# 安装 Ollama官方脚本 curl -fsSL https://ollama.com/install.sh | sh安装完成后拉取模型ollama pull qwen2.5:7b注意大模型体积较大下载前务必确认磁盘空间和本机硬件配置。3.4 环境变量配置在项目根目录创建.env文件写入你的 API Key# .env 文件示例 OPENAI_API_KEYsk-xxxxxxxx这里要特别说明如果使用国内模型服务环境变量名称可能不同请以具体服务商的文档为准。同时.env文件必须加入.gitignore避免密钥泄露。4. 大模型 Model 构建与基础调用这是整个 LangChain 学习路径的第一关把模型封装成统一接口。掌握这一节后面所有的 Chain 和 Agent 都建立在此之上。4.1 从最基础的调用开始LangChain 中最基础的类是ChatOpenAI它兼容 OpenAI 的 Chat Completions 接口。如果你使用的是 DeepSeek、智谱等国内模型只要服务商提供 OpenAI 兼容接口就可以通过base_url参数指向对应服务地址。from langchain_openai import ChatOpenAI # 接入 OpenAI 或兼容接口的大模型 llm ChatOpenAI( modelgpt-4o-mini, temperature0.7, api_keysk-xxxx, # 生产环境建议从环境变量读取 )调用模型response llm.invoke(用一句话介绍 LangChain) print(response.content)运行这段代码你能看到模型返回的文本内容。这是最原始的模型调用。4.2 使用 Ollama 接入本地模型如果你的机器有足够的内存或显存可以尝试本地部署。Ollama 提供了本地 OpenAI 兼容接口LangChain 接入方式如下from langchain_openai import ChatOpenAI llm ChatOpenAI( modelqwen2.5:7b, base_urlhttp://localhost:11434/v1, api_keyollama, # 本地服务不需要真实密钥 temperature0.5, )这种方式的好处是数据不出本地适合隐私要求高的场景。4.3 批量调用与异步调用LangChain 支持批量调用和异步调用。批量调用适合对大量独立文本并行处理能显著减少循环时间。prompts [ 请总结LangChain 是什么, 请总结什么是 RAG, 请总结什么是 Agent, ] # 批量调用 responses llm.batch(prompts) for text, res in zip(prompts, responses): print(f输入{text}) print(f输出{res.content}) print(- * 30)异步调用适合在 FastAPI 等服务中配合await使用import asyncio async def async_demo(): llm ChatOpenAI(modelgpt-4o-mini) resp await llm.ainvoke(写一句关于编程的格言) print(resp.content) asyncio.run(async_demo())到这里你已经完成了 LangChain 的 Model 层构建。下一步我们要把模型调用包装成可复用的业务逻辑这就是 Chain。5. Prompt 模板与 Chain 链式调用直接调用 Model 只是最基础的玩法。实际开发中我们需要为不同场景定制 Prompt并且把多步操作串成一条流水线这正是 Chain 的价值。5.1 使用 PromptTemplate 固定输入格式from langchain_core.prompts import PromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini) prompt PromptTemplate.from_template( 你是{role}。请用{language}回答以下问题{question} ) # 生成完整的 prompt 文本 formatted_prompt prompt.format( role资深编程导师, language中文, question如何学习大模型开发 ) response llm.invoke(formatted_prompt) print(response.content)5.2 使用 LCEL 构建可组合的 ChainLangChain 的现代写法是 LCELLangChain Expression Language用|操作符把 Prompt、Model、OutputParser 串起来。这种方式清晰、可读性高、便于部署。from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini) prompt ChatPromptTemplate.from_template( 你是专业的编程领域作者请用通俗易懂的方式解释{topic} ) # 用管道符串联 prompt - model - parser chain prompt | llm | StrOutputParser() # 执行 chain result chain.invoke({topic: 什么是 LangChain Chain}) print(result)这里说明一下各个部分的作用ChatPromptTemplate接收用户输入渲染成完整的对话消息。ChatOpenAI将消息发给模型。StrOutputParser从模型输出中提取纯文本内容。5.3 多步 Chain先分析再生成更复杂的场景下你可能需要让模型先做一步分析再基于分析结果做二次生成。from langchain_core.prompts import ChatPromptTemplate analysis_prompt ChatPromptTemplate.from_template( 请分析这段代码的主题和技术要点{code} ) summary_prompt ChatPromptTemplate.from_template( 根据下面的技术分析写一段面向初中级开发者的学习建议\n{analysis} ) analysis_chain analysis_prompt | llm | StrOutputParser() full_chain analysis_chain | (lambda analysis: summary_prompt.format(analysisanalysis)) | llm | StrOutputParser() code_snippet def add(a, b): return a b print(full_chain.invoke({code: code_snippet}))通过这种组合方式你可以把任意多的处理步骤串起来实现简单的自动化分析流程。6. 记忆管理让模型记住上下文第一次接触 LangChain 的人最常遇到的问题就是模型不记得上一轮说过什么。这是因为 Chat 模型默认是无状态的。要保存多轮对话必须引入记忆机制。6.1 使用 ConversationBufferMemoryfrom langchain.memory import ConversationBufferMemory from langchain_core.chat_history import InMemoryChatMessageHistory from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder # 创建记忆对象 memory ConversationBufferMemory(return_messagesTrue) # 在 prompt 中声明历史消息占位符 prompt ChatPromptTemplate.from_messages( [ (system, 你是一个乐于助人的助手。), MessagesPlaceholder(variable_namehistory), (human, {input}), ] )在实际使用中你需要把invoke替换为predict方式LangChain 会自动维护历史消息。以下是一个简化示例from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_core.chat_history import InMemoryChatMessageHistory from langchain_core.runnables.history import RunnableWithMessageHistory llm ChatOpenAI(modelgpt-4o-mini) prompt ChatPromptTemplate.from_messages( [ (system, 你是一个负责的助手回答尽量简洁。), MessagesPlaceholder(variable_namehistory), (human, {input}), ] ) chain prompt | llm # 使用 RunnableWithMessageHistory 自动管理历史 with_history RunnableWithMessageHistory( chain, lambda session_id: InMemoryChatMessageHistory(), input_messages_keyinput, history_messages_keyhistory, ) # 第一轮对话 result1 with_history.invoke( {input: 我叫老王是一名后端工程师}, config{configurable: {session_id: session-1}} ) print(result1.content) # 第二轮对话模型应该记得用户的名字 result2 with_history.invoke( {input: 我叫什么名字}, config{configurable: {session_id: session-1}} ) print(result2.content)运行代码后第二轮对话模型会回答“你的名字是老王”。这说明记忆已经生效。6.2 更省 Token 的记忆方式ConversationBufferMemory会把所有历史消息都传给模型。对话变长之后Token 消耗会迅速膨胀。更工程化的做法是使用摘要记忆或向量检索记忆只保留真正的关键信息。这一部分在项目实战时可以按需引入。7. 智能 Agent 开发让模型会调用工具Agent 是 LangChain 学习路径中最有实战价值的一环。它让模型不再只是“生成文字”而是能够自主决定调用哪些工具、执行什么操作、如何处理结果。7.1 Agent 的工作原理一个大致的 Agent 执行流程是这样的用户提出任务。模型分析任务决定是否需要调用工具。如果需要模型输出结构化工具调用指令。程序执行对应工具把结果返回给模型。模型根据工具结果生成最终回答。这个循环在 LangChain 中叫 AgentExecutor 或 Agent Loop。7.2 定义一个简单的数学工具import math def multiply_numbers(a: float, b: float) - float: 计算两个数字的乘积 return a * b def calculate_square_root(x: float) - float: 计算一个数字的平方根 return math.sqrt(x)7.3 基于 create_tool_calling_agent 构建 Agent新版 LangChain 推荐使用create_tool_calling_agent它需要内置工具列表、模型和 Prompt 结构。from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_openai import ChatOpenAI from langchain_core.tools import tool # 用装饰器定义工具 tool def multiply_numbers(a: float, b: float) - float: 计算两个数字的乘积。 return a * b tool def calculate_square_root(x: float) - float: 计算一个数字的平方根。 return math.sqrt(x) llm ChatOpenAI(modelgpt-4o-mini, temperature0) prompt ChatPromptTemplate.from_messages( [ (system, 你是一个数学计算助手请调用可用工具解决问题。), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ] ) # 创建 agent agent create_tool_calling_agent(llm, [multiply_numbers, calculate_square_root], prompt) # 创建执行器 agent_executor AgentExecutor( agentagent, tools[multiply_numbers, calculate_square_root], verboseTrue, # 打开详细日志观察工具调用过程 ) # 执行任务 result agent_executor.invoke({input: 计算 12 乘以 8 的结果然后再计算结果的平方根}) print(result[output])运行后你会在控制台看到 Agent 一步步执行工具调用的日志。如果模型选用了正确的工具并得到计算结果说明 Agent 构建成功。7.4 接入搜索类工具实际项目中你还可以给 Agent 注册搜索工具、数据库查询工具、文件读取工具等。做法与上面完全一致写一个函数加上tool装饰器然后传入 Agent 的工具列表即可。需要注意工具能力越强Agent 的权限边界越重要。建议在工具函数内部增加校验逻辑限制输入范围和外部资源访问。8. LangChain 与 LangGraph 的选择很多初学者会被这两个名字搞混。这里用最简洁的方式说明区别。LangChain负责基础的应用编排包括模型调用、Prompt 管理、Chain、RAG、简单的 Agent 执行。适合快速开发和中小型应用。LangGraph专注于构建有状态、可编排、支持分支与循环的 Agent 工作流。适合复杂流程、多 Agent 协作、需要人工干预的执行场景。学习路线建议先掌握 LangChain 的 Model、Chain、Agent 基础再接触 LangGraph 做流程控制。9. RAG 检索增强生成实战RAG 是目前大模型落地最常见的技术方案。它的核心思路是先在你的文档库里检索相关内容再把检索结果放进 Prompt 里一起提交给模型让模型基于你提供的资料回答。9.1 RAG 的三个基本步骤文档加载与拆分。文本向量化并存入向量数据库。检索相关文本块并生成回答。9.2 完整代码示例from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables import RunnablePassthrough from langchain_core.output_parsers import StrOutputParser # 1. 加载 PDF 文档 loader PyPDFLoader(your_document.pdf) pages loader.load() # 2. 文本拆分 text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, ) docs text_splitter.split_documents(pages) # 3. 向量化并存储 embeddings OpenAIEmbeddings() vectorstore Chroma.from_documents(docs, embeddings) # 4. 创建检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 5. 构建 RAG Prompt prompt ChatPromptTemplate.from_template( 请仅根据以下资料回答问题。如果资料中没有相关信息请明确回答“资料中未找到相关信息”。 资料 {context} 问题{question} ) # 6. 构建 RAG Chain llm ChatOpenAI(modelgpt-4o-mini) def format_docs(docs): return \n\n.join([doc.page_content for doc in docs]) rag_chain ( { context: retriever | format_docs, question: RunnablePassthrough(), } | prompt | llm | StrOutputParser() ) # 7. 提问 question 这份文档的核心观点是什么 answer rag_chain.invoke(question) print(answer)9.3 批量 RAG 问答面对大量问题时可以批量调用 RAG Chainquestions [ 文档中提到了哪些技术方案, 文档的作者是谁, 文档的发布时间是什么时候, ] for q in questions: print(f问题{q}) print(f回答{rag_chain.invoke(q)}) print(- * 40)10. 综合项目实战知识库问答 API 服务把前面所有知识点串起来可以做一个基于 FastAPI 的知识库问答 API 服务。这个项目中你会用到 Model、Chain、RAG、Agent 的完整组合同时会学会如何通过接口对外提供能力。10.1 项目目录结构langchain-project/ ├── .env ├── requirements.txt ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 入口 │ ├── rag.py # RAG 相关逻辑 │ └── agent.py # Agent 相关逻辑 └── docs/ └── knowledge.pdf # 知识库文档10.2 FastAPI 接口代码from fastapi import FastAPI from pydantic import BaseModel from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate app FastAPI(titleLangChain Demo API) class QueryRequest(BaseModel): question: str session_id: str default class QueryResponse(BaseModel): answer: str prompt ChatPromptTemplate.from_template( 你是智能客服助手请回答{question} ) llm ChatOpenAI(modelgpt-4o-mini) chain prompt | llm app.post(/api/chat, response_modelQueryResponse) async def chat(request: QueryRequest): response chain.invoke({question: request.question}) return QueryResponse(answerresponse.content) app.get(/health) async def health_check(): return {status: ok}10.3 启动服务uvicorn app.main:app --host 0.0.0.0 --port 8000启动后访问http://127.0.0.1:8000/docs可以直接调试接口。10.4 接口调用验证import requests url http://127.0.0.1:8000/api/chat payload { question: 用一句话总结什么是大模型, session_id: test-1 } response requests.post(url, jsonpayload, timeout30) print(response.json())预期返回{ answer: 大模型是指在海量数据上预训练得到的、具有大量参数的深度学习模型。 }到这里你已经完成了一个最小可用的大模型应用服务。接下来可以把它接上企业微信机器人、前端页面或者内部系统。11. 资源占用与性能优化关于性能直接说结论LangChain 本身的资源占用非常低真正的资源瓶颈在模型侧。11.1 云端 API 模式使用 OpenAI 兼容 API 时本机只需要 CPU 和内存要求很低。显存占用为零因为推理发生在服务商侧。此时影响性能和成本的是模型选择越大的模型延迟越高、单价越贵。Token 数量历史记忆越长单次请求越慢。并发数高并发需要控制 API 调用上限建议设置限流。11.2 本地模型模式使用 Ollama 等本地模型时性能取决于模型大小和硬件配置。以常见 7B 量级模型为例通常建议至少 16GB 内存并且开启 GPU 加速。实际显存占用取决于量化方式和上下文长度需要以本机实测为准。11.3 降低 Token 消耗与延迟的建议1. 控制 Prompt 长度删除无关背景信息。 2. 使用摘要记忆替换完整历史记忆。 3. RAG 检索时限制返回的文档块数量例如从 5 块降到 3 块。 4. 对于简单任务使用更小的模型。 5. 设置合理的 temperature 参数减少不必要的随机性。 6. 批量任务优先使用 llm.batch() 而不是 for 循环逐个调用。11.4 端口冲突与进程残留多次运行服务后端口可能被占用。排查和解决方式如下# 查看端口占用Linux/macOS lsof -i :8000 # 查看端口占用Windows netstat -ano | findstr 8000确认占用进程后可以结束进程或更换服务端口。12. 常见问题与排查方法问题现象可能原因排查方式解决方案安装包超时网络原因重试安装更换镜像源pip install -i https://pypi.tuna.tsinghua.edu.cn/simpleAPI Key 报错 401密钥无效或未正确配置检查环境变量重新生成密钥确认 .env 文件被正确加载模型返回内容异常模型不理解任务或参数设置过高简化 Prompt降低 temperature增加 few-shot 示例Agent 不调用工具工具描述不清晰或未传入工具列表开启 verboseTrue优化工具描述确认 tools 参数已传入本地 Ollama 加载慢模型体积大、磁盘速度慢观察内存和磁盘 IO改用量化版本模型升级硬件RAG 回答不准确文档拆分不合理检查检索结果缩小 chunk_size增大重叠区调整检索 k 值接口服务启动报错端口被占用查看端口占用更换端口--port 8001批量任务中途失败网络抖动或限流添加异常捕获加入重试逻辑和断点续传机制12.1 一个批量任务重试模板import time from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min2, max10)) def safe_invoke(chain, input_data): return chain.invoke(input_data) questions [问题1, 问题2, 问题3] results [] for q in questions: try: result safe_invoke(rag_chain, q) results.append(result) except Exception as e: print(f处理失败{q}, 错误{e}) results.append(None) print(批量处理完成成功数量, len([r for r in results if r is not None]))这个模板用到了tenacity重试库实际项目中建议加入。13. 最佳实践与常见坑位避开最后这部分是把 LangChain 项目从“能跑”推向“稳定可用”的经验总结。13.1 工程化建议第一次开发先使用最小参数配置跑通全链路再逐步增加复杂度。模型、Prompt、向量库配置全部写在配置文件中禁止硬编码。保留一套最小的可运行示例代码方便出问题时对比排查。文档、代码、输出结果分目录管理统一命名规范。本地模型文件单独存放不要放在项目目录中避免误删或同步仓库时上传大文件。为接口服务增加访问鉴权限制内网访问不要直接暴露到公网。13.2 Prompt 设计建议明确角色和任务目标。提供必要的示例few-shot效果通常优于纯指令。对关键输出格式给出模板便于后续用代码解析。固定 Prompt 版本修改 Prompt 后要回归测试。13.3 数据与版权合规接入任何 AI 能力前确认符合所在地区和组织的合规要求。RAG 知识库中的文档需要有合法来源。涉及用户数据的项目必须做脱敏处理。模型输出不能直接作为法律、医疗、金融等领域的最终决策依据。13.4 从入门到实战的推荐路线第 1 周掌握 Model 构建、Prompt 模板、Chain 串接。 第 2 周掌握 Memory 和基础工具调用。 第 3 周实现一个基础 Agent 并配合 RAG 构建知识库。 第 4 周用 FastAPI 封装接口加入鉴权和批量任务支持。14. 从 LangChain 到 LangGraph下一步怎么走当你已经把 Agent、RAG、批量任务都跑通之后下一个自然的方向是 LangGraph。它解决的问题是 LangChain 在大规模 Agent 编排上的短板状态管理、分支控制、循环、人工审批节点等。简单对比维度LangChainLangGraph核心能力模型调用、链式组合、简单 Agent复杂流程编排、有状态 Agent 工作流学习曲线较平缓需要理解图Graph和状态State概念适用场景快速原型、中小型应用多步骤业务流程、多 Agent 协作与 LangChain 关系基础框架基于 LangChain 生态的进阶框架建议先把你刚才做的问答服务、Agent 工具调用在 LangChain 中完全跑通再切换到 LangGraph 学习。这次从 Model 构建到 Agent 开发再到 RAG 和接口服务整条路径已经完整走了一遍。最值得先动手验证的是 Chapter 7 的 Agent 工具调用——它能让你直观感受到模型“自主决策调用工具”的过程也是理解 LangChain 编排价值的关键一步。最容易踩的坑主要集中在两个地方一是 API Key 环境变量没有正确加载导致反复 401二是向量库依赖安装不完整导致 RAG 链路无法运行。如果在这两步卡住优先检查依赖列表和配置文件。后续扩展方向可以考虑把 Agent 工具从数学计算换成数据库查询、把 RAG 换成支持多文档格式、把你的 FastAPI 服务封装成企业内部工具接入协同办公系统。准备好后就可以直接进入 LangGraph 阶段了。
LangChain入门到实战：从Model构建到Agent与RAG落地
如果你正在学 LangChain却又感觉看完官方文档一头雾水——不知道 Model 怎么接、Agent 怎么调、RAG 怎么落地那这应该是目前最适合跟着一步步敲代码的入门到实战路线。这篇文章不堆概念直接按“搭环境 - 构建 Model - 串 Chain - 做 Agent - 接 RAG - 跑一个完整项目”的顺序带你走一遍每个环节给出可运行的代码和验证方式。1. 核心能力速览这一节先给结论让你快速判断接下来要读的内容适不适合你当前的需求。能力项说明框架定位LangChain 是面向大模型应用开发的编排框架核心解决 Model 调用、Prompt 管理、记忆、Agent 工具调用、RAG 检索增强等工程化问题开发语言Python 为主社区也有 JavaScript/TypeScript 版本模型接入支持 OpenAI 兼容接口、DeepSeek、智谱、通义千问、Ollama 本地模型、Hugging Face 模型等本地部署门槛纯 API 模式下无显卡要求使用 Ollama 本地模型时需要按模型实际体积预留内存或显存具体以模型官方说明为准核心功能Model 构建、Prompt 模板、Chain 链式调用、Memory 记忆、Agent 智能体、RAG 检索增强、批量任务是否支持 API 服务可以基于 FastAPI 封装为接口服务LangChain 本身不直接提供 HTTP Server是否支持批量任务支持可通过 for 循环、异步任务或队列方式对多条输入批量执行 Chain/Agent适合场景智能问答、文档知识库、自动化工作流、代码助手、数据分析 Agent、客服系统等学习成本概念较多建议先掌握 Model - Chain - Agent - RAG 这条主线再扩展记忆和工具从材料看当前 LangChain 生态已经非常成熟围绕它衍生出了 LangGraph用于有状态、可编排的 Agent 流程等进阶框架。所以在学会基础之后我会专门用一节讲清楚 LangChain 和 LangGraph 的关系避免你学完基础再绕弯路。2. 适用场景与使用边界LangChain 不是大模型本身而是“连接大模型与业务逻辑的胶水层”。这意味着你需要先有大模型的访问能力再考虑用 LangChain 做编排。2.1 适合什么场景快速构建问答机器人通过 Prompt Template 固定问答格式通过 Memory 维护多轮上下文。企业内部知识库结合向量数据库做 RAG让模型基于你的文档回答问题。自动化业务流程Agent 调用搜索、计算、数据库查询等工具自动完成多步任务。批量内容处理对大量文本统一进行摘要、分类、关键词提取。快速验证模型能力切换不同模型供应商时只需修改少量配置。2.2 不适合什么场景如果你的需求只是“调用一次 API 拿到结果”直接用requests或 OpenAI SDK 反而更轻量。如果你的应用需要复杂的并行分支、状态机式流程控制LangChain 基础版会显得力不从心这时候要考虑 LangGraph。如果你没有模型访问权限LangChain 本身不会给你提供模型能力。2.3 使用边界与合规提醒调用外部模型 API 时务必确认服务商的使用条款和数据隐私政策不要将敏感数据直接发送给第三方模型。使用 Agent 工具调用时工具可能执行搜索、文件操作、命令执行等动作必须在沙箱环境内测试限制工具的权限范围。构建知识库 RAG 时注意文档版权和数据来源合法性。如果使用本地模型请从正规渠道下载模型文件并核对模型许可证。3. 环境准备与前置条件LangChain 的环境准备非常简单这是它适合入门的原因之一。无论你用的是 Windows、macOS 还是 Linux只要本机有 Python 3.9 以上环境即可。3.1 安装 Python 与虚拟环境建议为项目单独创建虚拟环境避免依赖冲突。# 创建虚拟环境 python -m venv langchain-demo # 激活虚拟环境 # Windows langchain-demo\Scripts\activate # macOS / Linux source langchain-demo/bin/activate3.2 安装 LangChain 核心依赖pip install -U langchain langchain-community langchain-openai如果你想调用本地 Ollama 模型额外安装pip install ollama如果你计划使用 RAG 和向量数据库安装pip install chromadb pypdf docx2txt3.3 模型访问方式确认LangChain 可以接入两大类模型云端 API 模型需要 API Key。常见的有 OpenAI、DeepSeek、智谱 GLM、通义千问等。国内用户建议优先选择合规合法的国内服务商并在环境变量中配置。本地模型通过 Ollama 等工具在本地部署开源模型无需 API Key但需要足够的磁盘空间和内存/显存。这里给出一个本地 Ollama 的下载安装思路以 Linux/macOS 为例Windows 请从官网下载安装包# 安装 Ollama官方脚本 curl -fsSL https://ollama.com/install.sh | sh安装完成后拉取模型ollama pull qwen2.5:7b注意大模型体积较大下载前务必确认磁盘空间和本机硬件配置。3.4 环境变量配置在项目根目录创建.env文件写入你的 API Key# .env 文件示例 OPENAI_API_KEYsk-xxxxxxxx这里要特别说明如果使用国内模型服务环境变量名称可能不同请以具体服务商的文档为准。同时.env文件必须加入.gitignore避免密钥泄露。4. 大模型 Model 构建与基础调用这是整个 LangChain 学习路径的第一关把模型封装成统一接口。掌握这一节后面所有的 Chain 和 Agent 都建立在此之上。4.1 从最基础的调用开始LangChain 中最基础的类是ChatOpenAI它兼容 OpenAI 的 Chat Completions 接口。如果你使用的是 DeepSeek、智谱等国内模型只要服务商提供 OpenAI 兼容接口就可以通过base_url参数指向对应服务地址。from langchain_openai import ChatOpenAI # 接入 OpenAI 或兼容接口的大模型 llm ChatOpenAI( modelgpt-4o-mini, temperature0.7, api_keysk-xxxx, # 生产环境建议从环境变量读取 )调用模型response llm.invoke(用一句话介绍 LangChain) print(response.content)运行这段代码你能看到模型返回的文本内容。这是最原始的模型调用。4.2 使用 Ollama 接入本地模型如果你的机器有足够的内存或显存可以尝试本地部署。Ollama 提供了本地 OpenAI 兼容接口LangChain 接入方式如下from langchain_openai import ChatOpenAI llm ChatOpenAI( modelqwen2.5:7b, base_urlhttp://localhost:11434/v1, api_keyollama, # 本地服务不需要真实密钥 temperature0.5, )这种方式的好处是数据不出本地适合隐私要求高的场景。4.3 批量调用与异步调用LangChain 支持批量调用和异步调用。批量调用适合对大量独立文本并行处理能显著减少循环时间。prompts [ 请总结LangChain 是什么, 请总结什么是 RAG, 请总结什么是 Agent, ] # 批量调用 responses llm.batch(prompts) for text, res in zip(prompts, responses): print(f输入{text}) print(f输出{res.content}) print(- * 30)异步调用适合在 FastAPI 等服务中配合await使用import asyncio async def async_demo(): llm ChatOpenAI(modelgpt-4o-mini) resp await llm.ainvoke(写一句关于编程的格言) print(resp.content) asyncio.run(async_demo())到这里你已经完成了 LangChain 的 Model 层构建。下一步我们要把模型调用包装成可复用的业务逻辑这就是 Chain。5. Prompt 模板与 Chain 链式调用直接调用 Model 只是最基础的玩法。实际开发中我们需要为不同场景定制 Prompt并且把多步操作串成一条流水线这正是 Chain 的价值。5.1 使用 PromptTemplate 固定输入格式from langchain_core.prompts import PromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini) prompt PromptTemplate.from_template( 你是{role}。请用{language}回答以下问题{question} ) # 生成完整的 prompt 文本 formatted_prompt prompt.format( role资深编程导师, language中文, question如何学习大模型开发 ) response llm.invoke(formatted_prompt) print(response.content)5.2 使用 LCEL 构建可组合的 ChainLangChain 的现代写法是 LCELLangChain Expression Language用|操作符把 Prompt、Model、OutputParser 串起来。这种方式清晰、可读性高、便于部署。from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini) prompt ChatPromptTemplate.from_template( 你是专业的编程领域作者请用通俗易懂的方式解释{topic} ) # 用管道符串联 prompt - model - parser chain prompt | llm | StrOutputParser() # 执行 chain result chain.invoke({topic: 什么是 LangChain Chain}) print(result)这里说明一下各个部分的作用ChatPromptTemplate接收用户输入渲染成完整的对话消息。ChatOpenAI将消息发给模型。StrOutputParser从模型输出中提取纯文本内容。5.3 多步 Chain先分析再生成更复杂的场景下你可能需要让模型先做一步分析再基于分析结果做二次生成。from langchain_core.prompts import ChatPromptTemplate analysis_prompt ChatPromptTemplate.from_template( 请分析这段代码的主题和技术要点{code} ) summary_prompt ChatPromptTemplate.from_template( 根据下面的技术分析写一段面向初中级开发者的学习建议\n{analysis} ) analysis_chain analysis_prompt | llm | StrOutputParser() full_chain analysis_chain | (lambda analysis: summary_prompt.format(analysisanalysis)) | llm | StrOutputParser() code_snippet def add(a, b): return a b print(full_chain.invoke({code: code_snippet}))通过这种组合方式你可以把任意多的处理步骤串起来实现简单的自动化分析流程。6. 记忆管理让模型记住上下文第一次接触 LangChain 的人最常遇到的问题就是模型不记得上一轮说过什么。这是因为 Chat 模型默认是无状态的。要保存多轮对话必须引入记忆机制。6.1 使用 ConversationBufferMemoryfrom langchain.memory import ConversationBufferMemory from langchain_core.chat_history import InMemoryChatMessageHistory from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder # 创建记忆对象 memory ConversationBufferMemory(return_messagesTrue) # 在 prompt 中声明历史消息占位符 prompt ChatPromptTemplate.from_messages( [ (system, 你是一个乐于助人的助手。), MessagesPlaceholder(variable_namehistory), (human, {input}), ] )在实际使用中你需要把invoke替换为predict方式LangChain 会自动维护历史消息。以下是一个简化示例from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_core.chat_history import InMemoryChatMessageHistory from langchain_core.runnables.history import RunnableWithMessageHistory llm ChatOpenAI(modelgpt-4o-mini) prompt ChatPromptTemplate.from_messages( [ (system, 你是一个负责的助手回答尽量简洁。), MessagesPlaceholder(variable_namehistory), (human, {input}), ] ) chain prompt | llm # 使用 RunnableWithMessageHistory 自动管理历史 with_history RunnableWithMessageHistory( chain, lambda session_id: InMemoryChatMessageHistory(), input_messages_keyinput, history_messages_keyhistory, ) # 第一轮对话 result1 with_history.invoke( {input: 我叫老王是一名后端工程师}, config{configurable: {session_id: session-1}} ) print(result1.content) # 第二轮对话模型应该记得用户的名字 result2 with_history.invoke( {input: 我叫什么名字}, config{configurable: {session_id: session-1}} ) print(result2.content)运行代码后第二轮对话模型会回答“你的名字是老王”。这说明记忆已经生效。6.2 更省 Token 的记忆方式ConversationBufferMemory会把所有历史消息都传给模型。对话变长之后Token 消耗会迅速膨胀。更工程化的做法是使用摘要记忆或向量检索记忆只保留真正的关键信息。这一部分在项目实战时可以按需引入。7. 智能 Agent 开发让模型会调用工具Agent 是 LangChain 学习路径中最有实战价值的一环。它让模型不再只是“生成文字”而是能够自主决定调用哪些工具、执行什么操作、如何处理结果。7.1 Agent 的工作原理一个大致的 Agent 执行流程是这样的用户提出任务。模型分析任务决定是否需要调用工具。如果需要模型输出结构化工具调用指令。程序执行对应工具把结果返回给模型。模型根据工具结果生成最终回答。这个循环在 LangChain 中叫 AgentExecutor 或 Agent Loop。7.2 定义一个简单的数学工具import math def multiply_numbers(a: float, b: float) - float: 计算两个数字的乘积 return a * b def calculate_square_root(x: float) - float: 计算一个数字的平方根 return math.sqrt(x)7.3 基于 create_tool_calling_agent 构建 Agent新版 LangChain 推荐使用create_tool_calling_agent它需要内置工具列表、模型和 Prompt 结构。from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_openai import ChatOpenAI from langchain_core.tools import tool # 用装饰器定义工具 tool def multiply_numbers(a: float, b: float) - float: 计算两个数字的乘积。 return a * b tool def calculate_square_root(x: float) - float: 计算一个数字的平方根。 return math.sqrt(x) llm ChatOpenAI(modelgpt-4o-mini, temperature0) prompt ChatPromptTemplate.from_messages( [ (system, 你是一个数学计算助手请调用可用工具解决问题。), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ] ) # 创建 agent agent create_tool_calling_agent(llm, [multiply_numbers, calculate_square_root], prompt) # 创建执行器 agent_executor AgentExecutor( agentagent, tools[multiply_numbers, calculate_square_root], verboseTrue, # 打开详细日志观察工具调用过程 ) # 执行任务 result agent_executor.invoke({input: 计算 12 乘以 8 的结果然后再计算结果的平方根}) print(result[output])运行后你会在控制台看到 Agent 一步步执行工具调用的日志。如果模型选用了正确的工具并得到计算结果说明 Agent 构建成功。7.4 接入搜索类工具实际项目中你还可以给 Agent 注册搜索工具、数据库查询工具、文件读取工具等。做法与上面完全一致写一个函数加上tool装饰器然后传入 Agent 的工具列表即可。需要注意工具能力越强Agent 的权限边界越重要。建议在工具函数内部增加校验逻辑限制输入范围和外部资源访问。8. LangChain 与 LangGraph 的选择很多初学者会被这两个名字搞混。这里用最简洁的方式说明区别。LangChain负责基础的应用编排包括模型调用、Prompt 管理、Chain、RAG、简单的 Agent 执行。适合快速开发和中小型应用。LangGraph专注于构建有状态、可编排、支持分支与循环的 Agent 工作流。适合复杂流程、多 Agent 协作、需要人工干预的执行场景。学习路线建议先掌握 LangChain 的 Model、Chain、Agent 基础再接触 LangGraph 做流程控制。9. RAG 检索增强生成实战RAG 是目前大模型落地最常见的技术方案。它的核心思路是先在你的文档库里检索相关内容再把检索结果放进 Prompt 里一起提交给模型让模型基于你提供的资料回答。9.1 RAG 的三个基本步骤文档加载与拆分。文本向量化并存入向量数据库。检索相关文本块并生成回答。9.2 完整代码示例from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables import RunnablePassthrough from langchain_core.output_parsers import StrOutputParser # 1. 加载 PDF 文档 loader PyPDFLoader(your_document.pdf) pages loader.load() # 2. 文本拆分 text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, ) docs text_splitter.split_documents(pages) # 3. 向量化并存储 embeddings OpenAIEmbeddings() vectorstore Chroma.from_documents(docs, embeddings) # 4. 创建检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 5. 构建 RAG Prompt prompt ChatPromptTemplate.from_template( 请仅根据以下资料回答问题。如果资料中没有相关信息请明确回答“资料中未找到相关信息”。 资料 {context} 问题{question} ) # 6. 构建 RAG Chain llm ChatOpenAI(modelgpt-4o-mini) def format_docs(docs): return \n\n.join([doc.page_content for doc in docs]) rag_chain ( { context: retriever | format_docs, question: RunnablePassthrough(), } | prompt | llm | StrOutputParser() ) # 7. 提问 question 这份文档的核心观点是什么 answer rag_chain.invoke(question) print(answer)9.3 批量 RAG 问答面对大量问题时可以批量调用 RAG Chainquestions [ 文档中提到了哪些技术方案, 文档的作者是谁, 文档的发布时间是什么时候, ] for q in questions: print(f问题{q}) print(f回答{rag_chain.invoke(q)}) print(- * 40)10. 综合项目实战知识库问答 API 服务把前面所有知识点串起来可以做一个基于 FastAPI 的知识库问答 API 服务。这个项目中你会用到 Model、Chain、RAG、Agent 的完整组合同时会学会如何通过接口对外提供能力。10.1 项目目录结构langchain-project/ ├── .env ├── requirements.txt ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 入口 │ ├── rag.py # RAG 相关逻辑 │ └── agent.py # Agent 相关逻辑 └── docs/ └── knowledge.pdf # 知识库文档10.2 FastAPI 接口代码from fastapi import FastAPI from pydantic import BaseModel from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate app FastAPI(titleLangChain Demo API) class QueryRequest(BaseModel): question: str session_id: str default class QueryResponse(BaseModel): answer: str prompt ChatPromptTemplate.from_template( 你是智能客服助手请回答{question} ) llm ChatOpenAI(modelgpt-4o-mini) chain prompt | llm app.post(/api/chat, response_modelQueryResponse) async def chat(request: QueryRequest): response chain.invoke({question: request.question}) return QueryResponse(answerresponse.content) app.get(/health) async def health_check(): return {status: ok}10.3 启动服务uvicorn app.main:app --host 0.0.0.0 --port 8000启动后访问http://127.0.0.1:8000/docs可以直接调试接口。10.4 接口调用验证import requests url http://127.0.0.1:8000/api/chat payload { question: 用一句话总结什么是大模型, session_id: test-1 } response requests.post(url, jsonpayload, timeout30) print(response.json())预期返回{ answer: 大模型是指在海量数据上预训练得到的、具有大量参数的深度学习模型。 }到这里你已经完成了一个最小可用的大模型应用服务。接下来可以把它接上企业微信机器人、前端页面或者内部系统。11. 资源占用与性能优化关于性能直接说结论LangChain 本身的资源占用非常低真正的资源瓶颈在模型侧。11.1 云端 API 模式使用 OpenAI 兼容 API 时本机只需要 CPU 和内存要求很低。显存占用为零因为推理发生在服务商侧。此时影响性能和成本的是模型选择越大的模型延迟越高、单价越贵。Token 数量历史记忆越长单次请求越慢。并发数高并发需要控制 API 调用上限建议设置限流。11.2 本地模型模式使用 Ollama 等本地模型时性能取决于模型大小和硬件配置。以常见 7B 量级模型为例通常建议至少 16GB 内存并且开启 GPU 加速。实际显存占用取决于量化方式和上下文长度需要以本机实测为准。11.3 降低 Token 消耗与延迟的建议1. 控制 Prompt 长度删除无关背景信息。 2. 使用摘要记忆替换完整历史记忆。 3. RAG 检索时限制返回的文档块数量例如从 5 块降到 3 块。 4. 对于简单任务使用更小的模型。 5. 设置合理的 temperature 参数减少不必要的随机性。 6. 批量任务优先使用 llm.batch() 而不是 for 循环逐个调用。11.4 端口冲突与进程残留多次运行服务后端口可能被占用。排查和解决方式如下# 查看端口占用Linux/macOS lsof -i :8000 # 查看端口占用Windows netstat -ano | findstr 8000确认占用进程后可以结束进程或更换服务端口。12. 常见问题与排查方法问题现象可能原因排查方式解决方案安装包超时网络原因重试安装更换镜像源pip install -i https://pypi.tuna.tsinghua.edu.cn/simpleAPI Key 报错 401密钥无效或未正确配置检查环境变量重新生成密钥确认 .env 文件被正确加载模型返回内容异常模型不理解任务或参数设置过高简化 Prompt降低 temperature增加 few-shot 示例Agent 不调用工具工具描述不清晰或未传入工具列表开启 verboseTrue优化工具描述确认 tools 参数已传入本地 Ollama 加载慢模型体积大、磁盘速度慢观察内存和磁盘 IO改用量化版本模型升级硬件RAG 回答不准确文档拆分不合理检查检索结果缩小 chunk_size增大重叠区调整检索 k 值接口服务启动报错端口被占用查看端口占用更换端口--port 8001批量任务中途失败网络抖动或限流添加异常捕获加入重试逻辑和断点续传机制12.1 一个批量任务重试模板import time from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min2, max10)) def safe_invoke(chain, input_data): return chain.invoke(input_data) questions [问题1, 问题2, 问题3] results [] for q in questions: try: result safe_invoke(rag_chain, q) results.append(result) except Exception as e: print(f处理失败{q}, 错误{e}) results.append(None) print(批量处理完成成功数量, len([r for r in results if r is not None]))这个模板用到了tenacity重试库实际项目中建议加入。13. 最佳实践与常见坑位避开最后这部分是把 LangChain 项目从“能跑”推向“稳定可用”的经验总结。13.1 工程化建议第一次开发先使用最小参数配置跑通全链路再逐步增加复杂度。模型、Prompt、向量库配置全部写在配置文件中禁止硬编码。保留一套最小的可运行示例代码方便出问题时对比排查。文档、代码、输出结果分目录管理统一命名规范。本地模型文件单独存放不要放在项目目录中避免误删或同步仓库时上传大文件。为接口服务增加访问鉴权限制内网访问不要直接暴露到公网。13.2 Prompt 设计建议明确角色和任务目标。提供必要的示例few-shot效果通常优于纯指令。对关键输出格式给出模板便于后续用代码解析。固定 Prompt 版本修改 Prompt 后要回归测试。13.3 数据与版权合规接入任何 AI 能力前确认符合所在地区和组织的合规要求。RAG 知识库中的文档需要有合法来源。涉及用户数据的项目必须做脱敏处理。模型输出不能直接作为法律、医疗、金融等领域的最终决策依据。13.4 从入门到实战的推荐路线第 1 周掌握 Model 构建、Prompt 模板、Chain 串接。 第 2 周掌握 Memory 和基础工具调用。 第 3 周实现一个基础 Agent 并配合 RAG 构建知识库。 第 4 周用 FastAPI 封装接口加入鉴权和批量任务支持。14. 从 LangChain 到 LangGraph下一步怎么走当你已经把 Agent、RAG、批量任务都跑通之后下一个自然的方向是 LangGraph。它解决的问题是 LangChain 在大规模 Agent 编排上的短板状态管理、分支控制、循环、人工审批节点等。简单对比维度LangChainLangGraph核心能力模型调用、链式组合、简单 Agent复杂流程编排、有状态 Agent 工作流学习曲线较平缓需要理解图Graph和状态State概念适用场景快速原型、中小型应用多步骤业务流程、多 Agent 协作与 LangChain 关系基础框架基于 LangChain 生态的进阶框架建议先把你刚才做的问答服务、Agent 工具调用在 LangChain 中完全跑通再切换到 LangGraph 学习。这次从 Model 构建到 Agent 开发再到 RAG 和接口服务整条路径已经完整走了一遍。最值得先动手验证的是 Chapter 7 的 Agent 工具调用——它能让你直观感受到模型“自主决策调用工具”的过程也是理解 LangChain 编排价值的关键一步。最容易踩的坑主要集中在两个地方一是 API Key 环境变量没有正确加载导致反复 401二是向量库依赖安装不完整导致 RAG 链路无法运行。如果在这两步卡住优先检查依赖列表和配置文件。后续扩展方向可以考虑把 Agent 工具从数学计算换成数据库查询、把 RAG 换成支持多文档格式、把你的 FastAPI 服务封装成企业内部工具接入协同办公系统。准备好后就可以直接进入 LangGraph 阶段了。