LangChain 1.3实战：从零搭建RAG与Agent应用

这次我们直接看 LangChain 1.3 的代码实战路线。如果你一直在找一套能真正从零跟到代码落地的 LangChain 教程而不是看完概念还是写不出一个完整链那这篇内容应该能帮你省不少时间。LangChain 1.x 系列迭代到现在核心库和生态已经拆得比较清楚langchain-core提供基础抽象langchain负责链和 Agent 的高层封装langchain-community和各种第三方集成包负责对接模型、向量库、工具。1.3 这个阶段最值得关注的变化是LCEL 链式写法成为主流、模型调用和工具调用的边界更清晰、可观测性和调试能力明显增强开发体验比早期版本顺滑很多。下面我会按一套完整上手路径来展开先看 LangChain 1.3 的核心能力边界然后做环境准备再手写模型调用、提示词模板、链、记忆、Agent、RAG 检索增强这几块核心代码最后补上接口服务封装、批量任务、性能观察和常见问题排查。全文代码都按可复制的标准写你只需要把模型 API Key、模型名和路径替换成自己的。1. LangChain 1.3 核心能力速览很多刚接触 LangChain 的同学会误以为它是一个“AI 应用全家桶”装上就能直接出产品。实际上 LangChain 1.x 更像是一套标准化的 LLM 应用开发框架它帮你把模型调用、提示词组织、外部工具接入、记忆存储、文档检索这些环节串起来但你仍然需要自己写业务逻辑。能力项说明项目定位LLM 应用开发编排框架提供链、Agent、记忆、RAG、工具调用等抽象核心组成langchain-core / langchain / langchain-community / 各模型供应商集成包主要功能模型调用、提示词模板、LCEL 链、记忆管理、Agent、工具调用、文档加载、向量检索编程语言Python 为主同时有 TypeScript/JavaScript 版本支持模型OpenAI、Anthropic、Google、Ollama 本地模型、阿里云、智谱等取决于对应集成包是否支持本地模型支持可通过 Ollama、vLLM、Transformers 等接入本地开源模型推荐硬件CPU 也能跑框架本身推理硬件取决于所接模型启动方式纯代码库无需独立服务直接 Python 调用是否支持 API框架本身不是服务但可基于 FastAPI/Flask 封装成 API 服务是否支持批量任务支持可 batch 调用也可配合消息队列做异步任务是否支持可视化LangSmith 提供链路追踪和调试可配合 LangGraph Studio 做 Agent 状态可视化适合场景ChatBot、RAG 知识库问答、Agent 自动化流程、文档处理、数据分析助手、企业内部工具编排LangChain 1.3 本身没有硬性显存要求显存占用完全取决于你接的模型。如果你接 OpenAI 这类云端模型本地只是发起 HTTP 请求占用几乎可以忽略。如果你通过 Ollama 接本地 7B 模型那么 8GB 显存可以跑量化版本16GB 可以比较舒服地跑 13B 以下模型显存占用需要以你实际使用的模型和上下文长度为准。有一点必须提前说明LangChain 不是低代码平台。现在很多团队也在用 Mendix 这类低代码工具快速搭业务界面但 LangChain 的定位是给开发者用的代码级编排框架它更适合需要精细控制逻辑、需要深度集成到现有系统、需要自定义工具和流程的场景。低代码平台适合业务人员快速搭演示。2. LangChain 1.3 适用场景与使用边界LangChain 1.3 能解决的典型问题有几类第一类是统一模型接入层。如果你要在不同模型供应商之间切换或者做模型降级和路由LangChain 的模型抽象能让业务代码不绑定具体厂商。你换模型时只需要改一处配置不需要把整个业务代码里的 prompt 拼接逻辑全部重写。第二类是 RAG 知识库问答。把企业内部文档切块、向量化、存入向量库用户提问时先检索相关片段再把片段和问题一起交给大模型生成答案。LangChain 1.3 在这一块的流程封装比早先版本更清晰文档加载和向量检索的接口也更稳定。第三类是 Agent 自动化任务。让 LLM 根据用户意图决定调用哪些工具比如查数据库、调 API、搜索网页、执行代码。LangChain 的 Agent 框架配合 LangGraph 可以构建有状态的多步执行流程。第四类是复杂链式任务。比如先总结文档、再抽取关键信息、再做翻译、最后输出结构化 JSON。LCEL 让这种多步管道可以用很简洁的代码串联起来。不适合的场景也要说清楚如果你的需求只是调用大模型 API 返回一句话不需要任何编排直接用openai或requests反而更轻。如果你需要的是极低延迟和高并发LangChain 不是性能瓶颈但它的抽象层会带来少量开销追求极致性能时可以考虑绕开框架直接调模型。如果你根本不写代码需要的是可视化拖拽平台那 LangChain 的代码开发模式就不适合应该去看 Dify、FastGPT 或 Mendix 这类平台。安全边界必须强调使用 LangChain 接入模型和工具时涉及企业数据、用户隐私、版权内容必须确认数据使用授权。不要把敏感数据直接发送到未经验证的第三方模型服务。Agent 调用外部工具时要限制执行权限避免模型生成的指令触发危险操作。3. LangChain 1.3 本地开发环境准备在开始写代码之前先把环境准备好。LangChain 1.3 对系统没有特别要求Windows、macOS、Linux 都可以只要 Python 环境干净。3.1 Python 环境建议使用 Python 3.10 到 3.12 版本。Python 3.9 虽然也能跑大部分功能但部分新版本依赖可能不再支持3.13 则可能遇到个别第三方库兼容问题。最稳妥的选择是 3.10 或 3.11。创建虚拟环境python -m venv langchain_env source langchain_env/bin/activate # Linux / macOS # Windows PowerShell 使用下面这行 # langchain_env\Scripts\Activate.ps13.2 安装 LangChain 相关包LangChain 1.x 采用模块化安装方式你可以只安装自己需要的包。我建议至少安装核心包和 OpenAI 集成包pip install --upgrade langchain langchain-core langchain-openai langchain-community如果你要接的是其他模型按需安装对应集成包# 接 Anthropic pip install langchain-anthropic # 接 Google Gemini pip install langchain-google-genai # 接本地 Ollama pip install langchain-ollama如果你要做 RAG还需要安装向量库相关依赖。这里以 Chroma 为例pip install langchain-chroma chromadb如果你要解析 PDF、Word 等文档可以安装文档加载器依赖pip install pypdf python-docx所有依赖的具体版本号以 pip 安装时实际解析为准不要固定一个不存在的版本号。如果你遇到依赖冲突建议把 langchain 相关包放同一个虚拟环境里统一安装避免和全局环境互相污染。3.3 配置模型 API KeyLangChain 1.3 支持通过环境变量读取 API Key。推荐使用.env文件管理然后通过python-dotenv加载pip install python-dotenv在项目根目录创建.env文件OPENAI_API_KEYsk-your-key-here # 如果你用 LangSmith 做链路追踪 LANGCHAIN_TRACING_V2true LANGCHAIN_API_KEYls-your-key-here LANGCHAIN_PROJECTlangchain-demo然后在代码中加载from dotenv import load_dotenv load_dotenv()这里强调一下.env文件不要提交到 Git 仓库要在.gitignore里加上.env。你的 API Key 一旦泄露别人就可以用你的额度调用模型服务。4. LangChain 1.3 代码实战开发下面进入核心代码实战。我们会从最基础的模型调用开始逐步搭建一个完整的 RAG 问答 Agent 工具调用项目。每一步都有可运行代码。4.1 模型调用与结构化输出先写一个最简单的模型调用确认环境和 API Key 配置正确。from langchain_openai import ChatOpenAI from dotenv import load_dotenv load_dotenv() # 初始化模型 llm ChatOpenAI( modelgpt-4o-mini, temperature0.7, timeout60, max_retries2, ) # 同步调用 response llm.invoke(用一句话解释什么是 LangChain) print(response.content)运行这段代码如果能正确输出一句话解释说明环境配置完成。这里特别注意ChatOpenAI这个类是从langchain_openai导入的早期版本的from langchain.chat_models import ChatOpenAI在 1.x 中已经标记为 deprecated新代码不要再用。1.3 阶段更推荐用with_structured_output来获取结构化结果这样可以直接拿到 JSON而不是自己用正则从文本里提取。假设我们要让模型返回一个包含姓名、年龄、职业的 JSONfrom langchain_openai import ChatOpenAI from langchain_core.pydantic_v1 import BaseModel, Field from dotenv import load_dotenv load_dotenv() class PersonInfo(BaseModel): 人物信息结构 name: str Field(description姓名) age: int Field(description年龄) job: str Field(description职业) llm ChatOpenAI(modelgpt-4o-mini, temperature0) structured_llm llm.with_structured_output(PersonInfo) result structured_llm.invoke(张三今年28岁是一名后端工程师) print(result)输出将是一个PersonInfo实例你可以直接访问result.name、result.age、result.job。这种方式比让模型输出 JSON再手动解析可靠得多强烈建议在正式项目里多用结构化输出。4.2 提示词模板与 LCEL 链有了模型调用基础接下来写真正意义上的链。LCELLangChain Expression Language是 LangChain 1.x 的核心表达方式它的典型特征是使用管道符|把组件串起来代码直观、易组合、易扩展。下面是一个典型的翻译 润色链from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from dotenv import load_dotenv load_dotenv() # 1. 定义提示词模板 prompt ChatPromptTemplate.from_messages([ (system, 你是一个专业翻译擅长把技术文档翻译成简洁准确的中文。), (human, 请翻译下面的英文内容\n{input_text}), ]) # 2. 初始化模型 llm ChatOpenAI(modelgpt-4o-mini, temperature0.2) # 3. 输出解析器 output_parser StrOutputParser() # 4. 用 LCEL 组装链 translation_chain prompt | llm | output_parser # 5. 调用链 result translation_chain.invoke({ input_text: LangChain is a framework for developing applications powered by language models. }) print(result)这个链的执行过程是prompt接收input_text变量生成消息列表交给llm生成回答再经过StrOutputParser转成纯文本输出。整条链只用三行代码就完成了组合后续要加缓存、加日志、加重试只需要在管道中插入新的组件。如果需要更复杂的提示词模板比如少样本示例、多轮对话拼接、动态变量组合ChatPromptTemplate都支持。实际项目里建议把提示词单独放到一个prompts.py文件里管理不要散落在业务代码中。4.3 记忆管理很多场景需要让模型记住多轮对话的上下文。LangChain 1.3 中记忆管理不再直接塞进链里而是推荐用langgraph的状态管理来处理会话上下文。我们先看一个简单的记忆链写法from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_core.output_parsers import StrOutputParser from langchain_core.messages import HumanMessage, AIMessage, SystemMessage from langgraph.checkpoint.memory import MemorySaver from langgraph.prebuilt import create_react_agent from dotenv import load_dotenv load_dotenv() llm ChatOpenAI(modelgpt-4o-mini, temperature0.7) # 方式一使用 MessagesPlaceholder 配合手动传入历史消息 prompt ChatPromptTemplate.from_messages([ (system, 你是一个智能助手回答要简洁友好。), MessagesPlaceholder(variable_namehistory), (human, {input}), ]) chain prompt | llm | StrOutputParser() def chat_with_history(history, user_input): 手动维护对话历史 response chain.invoke({ history: history, input: user_input, }) return response # 模拟多轮对话 history [] history.append(SystemMessage(content你是一个智能助手)) r1 chat_with_history(history, 我叫小明我喜欢编程) print(AI:, r1) history.append(HumanMessage(content我叫小明我喜欢编程)) history.append(AIMessage(contentr1)) r2 chat_with_history(history, 我叫什么名字) print(AI:, r2)更推荐的做法是用langgraph来管理有状态的多轮对话因为 LangGraph 把状态持久化、对话历史、Agent 节点都统一管理起来了后续扩展复杂流程会更容易。LangGraph 是 LangChain 官方推荐的 Agent 和状态流程编排库安装方式pip install langgraph4.4 Agent 工具调用实战Agent 是 LangChain 1.3 最具实用价值的部分。一个 Agent 可以理解用户意图自主决定调用哪些工具然后继续推理直到完成目标。先写两个简单工具一个执行加法计算一个查询天气模拟。然后通过create_react_agent让模型自主调用。from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langgraph.prebuilt import create_react_agent from langgraph.checkpoint.memory import MemorySaver from dotenv import load_dotenv load_dotenv() tool def add_numbers(a: int, b: int) - int: 将两个整数相加并返回结果。 return a b tool def get_weather(city: str) - str: 查询指定城市的天气。 # 这里是模拟数据实际应接入真实天气 API weather_map { 北京: 晴24℃, 上海: 多云27℃, 广州: 小雨30℃, } return weather_map.get(city, f{city}天气未知) tools [add_numbers, get_weather] llm ChatOpenAI(modelgpt-4o-mini, temperature0) agent create_react_agent( llm, tools, checkpointerMemorySaver(), ) # 执行带状态的 Agent 调用 config {configurable: {thread_id: conversation-1}} response agent.invoke( {messages: [{role: user, content: 帮我计算 1234 加上 5678 的结果}]}, configconfig, ) print(response[messages][-1].content) response agent.invoke( {messages: [{role: user, content: 北京现在天气如何}]}, configconfig, ) print(response[messages][-1].content)执行时模型会判断计算 1234 5678需要调用add_numbers工具于是 Agent 进入工具调用循环拿到结果后继续推理最后给出答案。thread_id保证了同一会话的状态连续性这个设计比早期版本里到处传memory要干净很多。注意工具函数的文档字符串docstring非常重要模型靠它来决定是否调用该工具、如何传参。如果你的工具经常被模型误调用先检查 docstring 是否清晰描述了功能和参数。4.5 RAG 检索增强生成实战RAG 是目前 LangChain 最广泛的应用场景。核心思路把文档切块、向量化、存入向量库用户提问时先检索最相关的片段再交给模型生成答案。这里我们做一个完整的 RAG 流程。先准备一个简单的文本文件然后加载、切分、向量化、检索、生成。from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_chroma import Chroma from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_core.runnables import RunnablePassthrough from dotenv import load_dotenv import tempfile import os load_dotenv() # 1. 准备示例文档 doc_content LangChain 是一个用于开发大语言模型应用的框架。 它提供了统一的模型接入接口支持多种模型供应商。 LCEL 是 LangChain 表达式语言用于组合链式调用。 RAG 是检索增强生成可以从外部知识库检索相关信息。 LangGraph 是 LangChain 官方推荐的 Agent 编排库。 with tempfile.NamedTemporaryFile(modew, suffix.txt, deleteFalse, encodingutf-8) as f: f.write(doc_content) doc_path f.name # 2. 加载文档 loader TextLoader(doc_path, encodingutf-8) documents loader.load() # 3. 切分文档 text_splitter RecursiveCharacterTextSplitter( chunk_size100, chunk_overlap20, ) chunks text_splitter.split_documents(documents) print(f切分为 {len(chunks)} 个片段) # 4. 向量化并存入 Chroma embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectorstore Chroma.from_documents( documentschunks, embeddingembeddings, persist_directory./chroma_db, ) # 5. 构造检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 6. 定义提示词模板 prompt ChatPromptTemplate.from_messages([ (system, 你是一个知识库问答助手。请只根据提供的上下文回答用户问题。如果上下文中没有相关信息请明确回答知识库中没有找到相关信息。\n\n上下文\n{context}), (human, {question}), ]) # 7. 组装 RAG 链 llm ChatOpenAI(modelgpt-4o-mini, temperature0) rag_chain ( {context: retriever, question: RunnablePassthrough()} | prompt | llm | StrOutputParser() ) # 8. 测试 question LCEL 是什么 result rag_chain.invoke(question) print(用户问题, question) print(回答, result) # 清理临时文件 os.unlink(doc_path)运行后模型会基于检索到的 LangChain 相关片段回答LCEL 是什么而不是凭空编造。这个流程就是 RAG 的完整链路。实际项目中文档可能来自本地文件、数据库、网页、钉钉/飞书文档、Notion 等LangChain 有对应的 Document Loader。这里有几个值得注意的细节chunk_size和chunk_overlap的取值需要根据文档特点调整不是越大越好。一般中文场景 200 到 500 字比较常用代码类文档可以更小。向量化模型选择会影响检索质量text-embedding-3-small是性能和成本的折中方案。检索器返回的片段数量k会影响回答质量和 Token 消耗。k值越大回答越充分但消耗越多。5. LangChain 1.3 功能测试与效果验证代码写出来不是终点需要验证各项功能是否正常。下面给出一套针对 LangChain 项目的测试和验证思路。5.1 模型调用测试先用最简单的问题确认模型 API 能通llm ChatOpenAI(modelgpt-4o-mini, temperature0) assert LangChain in llm.invoke(LangChain 是什么).content如果这里报错先检查 API Key 是否正确、网络能否访问模型服务、模型名是否有效。5.2 链式调用测试测试 LCEL 链的输入参数是否完整。LCEL 链如果报Missing required input variables说明invoke时传入的字典缺少某个变量。建议写一个函数封装链的调用统一处理输入输出格式def run_chain(chain, **kwargs): 安全的链调用封装 try: result chain.invoke(kwargs) return {success: True, data: result} except Exception as e: return {success: False, error: str(e)} test_result run_chain(translation_chain, input_textHello world) print(test_result)5.3 Agent 工具调用测试测试 Agent 时重点验证工具是否被正确触发。可以在工具函数内部加打印日志tool def add_numbers(a: int, b: int) - int: 将两个整数相加并返回结果。 print(f[工具调用] add_numbers({a}, {b})) return a b如果模型没有触发工具而是直接回答我会计算之类的内容说明模型没有理解你的工具描述。解决方法是优化工具 docstring明确说明参数和返回值或者换更强的模型。5.4 RAG 检索质量测试RAG 的效果好坏很大程度取决于检索质量。可以单独测试检索器docs retriever.invoke(LCEL 是什么) for i, doc in enumerate(docs): print(f--- 片段 {i1} ---) print(doc.page_content)如果检索出的片段和问题不相关需要调整切块大小、重叠长度、向量化模型或检索k值。这一步很重要很多 RAG 项目效果差不是模型问题而是检索没把对的片段捞出来。6. LangChain 1.3 接口 API 与批量任务封装LangChain 只负责业务逻辑编排但要对外提供服务必须自己封装 HTTP API。这里用 FastAPI 封装一个完整的问答接口并演示批量任务处理。6.1 用 FastAPI 封装问答服务from fastapi import FastAPI from pydantic import BaseModel from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from dotenv import load_dotenv load_dotenv() app FastAPI(titleLangChain API Service, version1.0.0) # 初始化链全局复用 prompt ChatPromptTemplate.from_messages([ (system, 你是一个智能助手。), (human, {question}), ]) llm ChatOpenAI(modelgpt-4o-mini, temperature0.7) chain prompt | llm | StrOutputParser() class QueryRequest(BaseModel): question: str class QueryResponse(BaseModel): answer: str status: str app.post(/chat, response_modelQueryResponse) async def chat(request: QueryRequest): try: answer chain.invoke({question: request.question}) return QueryResponse(answeranswer, statussuccess) except Exception as e: return QueryResponse(answerf服务异常{str(e)}, statuserror) app.get(/health) async def health(): return {status: ok}启动服务uvicorn main:app --host 127.0.0.1 --port 8000使用 curl 测试接口curl -X POST http://127.0.0.1:8000/chat \ -H Content-Type: application/json \ -d {question: LangChain 适合做什么}返回结果{answer:LangChain 适合构建基于大语言模型的应用...,status:success}这里需要提醒FastAPI 接口默认没有鉴权如果部署到公网必须加 API Key 校验或放到内网。否则任何人都可以调用你的接口消耗模型费用。6.2 Python 批量任务处理对于批量任务LangChain 的batch方法可以直接处理多个输入。适合离线批量生成、批量翻译、批量总结等场景。from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from dotenv import load_dotenv load_dotenv() prompt ChatPromptTemplate.from_messages([ (system, 你是一个高效的翻译助手把输入翻译成中文。), (human, {input_text}), ]) llm ChatOpenAI(modelgpt-4o-mini, temperature0.2) chain prompt | llm | StrOutputParser() # 批量输入 texts [ Hello, how are you?, LangChain makes LLM development easier., Python is a versatile language., RAG improves answer accuracy., ] # 批量调用 results chain.batch([{input_text: t} for t in texts]) for src, dst in zip(texts, results): print(f{src} - {dst})batch默认并发执行内部会复用连接池效率比 for 循环调用高很多。但要注意 API 限流如果调用频率过高会触发 429 错误。建议在批处理中加入重试和限速机制import time from langchain_core.runnables import RunnableLambda # 给链加一个简单的限速包装 def rate_limited_invoke(input_data): time.sleep(0.2) # 每 0.2 秒调用一次约每秒 5 次 return chain.invoke(input_data) limited_chain RunnableLambda(rate_limited_invoke) results limited_chain.batch([{input_text: t} for t in texts])6.3 异步任务队列如果是生产环境的大批量任务不要直接用同步batch处理几百条数据。正确做法是引入消息队列比如 Redis Celery 或 RabbitMQ。LangChain 链可以作为 Celery task 执行主进程只需要把任务交给队列。这里给一个用 Celery 接 LangChain 的思路# tasks.py from celery import Celery from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser app Celery(tasks, brokerredis://localhost:6379/0) prompt ChatPromptTemplate.from_messages([ (system, 你是翻译助手。), (human, {input_text}), ]) llm ChatOpenAI(modelgpt-4o-mini, temperature0) chain prompt | llm | StrOutputParser() app.task def translate_task(input_text: str) - str: 后台翻译任务 return chain.invoke({input_text: input_text})任务队列的好处是天然支持失败重试、并发控制、任务状态追踪。这是生产级批量任务的标准做法不只是 LangChain 项目任何异步任务系统都是这个思路。7. LangChain 1.3 资源占用与性能观察很多人关心 LangChain 跑起来吃多少资源。这个问题的答案取决于你接的模型类型。如果你接的是 OpenAI、Claude、Gemini 这类云端模型 API本地进程只负责拼 prompt、发 HTTP 请求、解析响应。内存占用一般在 100 到 300MB 左右CPU 占用很低显存占用为 0。这种模式下LangChain 框架本身不会成为性能瓶颈。如果你通过 Ollama 接本地开源模型资源占用就主要看模型7B 量化模型Q4大约需要 4 到 6GB 显存。13B 量化模型Q4大约需要 8 到 10GB 显存。如果上下文长度很长显存占用还会继续上涨。如何观察资源占用最简单的方式# 实时监控 GPU 显存 watch -n 1 nvidia-smi在代码中也可以查看当前进程内存import psutil import os process psutil.Process(os.getpid()) print(f当前内存占用: {process.memory_info().rss / 1024 / 1024:.2f} MB)影响 LangChain 应用性能的几个因素模型输入 Token 数。嵌入的上下文越长每次请求越慢。输出 Token 数。模型生成是逐 token 的输出越长等待越久。检索器耗时。向量检索本身很快但如果文档量很大且没有索引优化检索耗时会明显增加。重试机制。网络波动时max_retries会延长请求时间需要合理设置。并发数。batch并发过高会被模型服务限流需要做并发控制。降低资源占用的几个建议尽量复用模型实例和链实例不要每次请求都重新初始化。使用流式输出用户可以先看到部分响应感知延迟更低。RAG 场景下给向量库增加缓存对高频热点问题可以直接命中缓存跳过检索和生成。本地模型场景下如果显存不够可以降低上下文长度或使用更小的量化模型。8. LangChain 1.3 常见问题与排查方法下面整理一套高频问题的排查思路遇到问题可以先对照表格。问题现象可能原因排查方式解决方案安装 langchain 时依赖冲突Python 版本过旧或过新查看 pip 报错信息中的依赖要求使用 Python 3.10/3.11并在新虚拟环境重装调用模型报 401 错误API Key 错误或未设置检查 .env 文件和环境变量重新配置 API Key确认环境变量已加载调用模型报 404 错误模型名不存在或无权访问查看模型服务商文档替换为正确的模型名调用模型超时网络问题或模型响应过慢查看日志中的超时时间增大 timeout 参数检查网络连通性LCEL 链报缺少输入变量invoke 传入字典缺少变量检查提示词模板中的变量名补全所有需要的变量Agent 没有调用工具工具 docstring 描述不清在工具内加日志观察是否被调用优化 docstring或用更强模型RAG 检索结果不相关切块大小不合适或向量模型效果差单独测试 retriever调整 chunk_size、chunk_overlap尝试其他向量模型批处理被限流报 429并发过高触发 API 限流查看错误码增加 sleep 间隔降低并发数FastAPI 接口部署后无响应端口被占用或服务未启动查看 uvicorn 日志更换端口或重启服务LangSmith 追踪看不到数据环境变量未设置或 Key 无效检查环境变量确认 LANGCHAIN_TRACING_V2true 和 API Key 正确记录一条很常见的坑LangChain 1.x 中如果同时安装了langchain和langchain-experimental有些类会被重复定义导致导入时出现冲突。遇到这种情况尽量删除langchain-experimental或者把项目依赖固定好版本。另一个常见问题是文档加载器把 PDF 里的内容读成了乱码。PDF 解析依赖底层库扫描版 PDF 没有文字层任何解析器都读不出文字。这种情况下只能走 OCR 方案或者换带文字层的 PDF。9. LangChain 1.3 最佳实践与使用建议9.1 项目结构设计一个规范的 LangChain 项目不应该把所有代码堆在一个文件里。推荐按下面结构组织langchain_demo/ ├── .env # API Key 和环境变量 ├── .gitignore ├── requirements.txt # 依赖清单 ├── main.py # FastAPI 入口 ├── chains/ # 链的定义 │ ├── __init__.py │ ├── translation_chain.py │ └── rag_chain.py ├── agents/ # Agent 定义 │ ├── __init__.py │ └── custom_agent.py ├── tools/ # 自定义工具 │ ├── __init__.py │ ├── calculator.py │ └── weather.py ├── prompts/ # 提示词模板 │ ├── __init__.py │ └── system_prompts.py ├── services/ # 业务服务层 │ ├── __init__.py │ └── query_service.py └── data/ # 文档、向量库、模型缓存 ├── documents/ └── chroma_db/这样拆分的好处是换模型只改一个配置文件加工具只新增tools/目录下的文件调 prompt 不用动业务代码。9.2 提示词管理的工程化提示词是 LangChain 应用效果好坏的核心变量。建议正式环境的提示词不要硬编码在业务代码里放入统一的prompts模块。提示词版本化改版后要记录变更内容。对关键提示词做回归测试防止改动一个措辞导致效果大幅波动。在提示词中明确输出格式配合with_structured_output做结构化输出。9.3 工具调用的安全边界Agent 调用工具时要特别注意权限控制不要让模型直接执行宿主机 shell 命令除非你对输入做了严格白名单过滤。数据库连接凭据不要暴露给模型最好由工具函数内部持有。涉及文件删除、资金支付、发送消息等高风险操作要加人工确认环节。外部 API 调用的超时和异常处理要在工具函数内做好。9.4 成本控制LangChain 应用的成本主要来自模型 Token 消耗。控制成本的手段系统提示词尽量精简不要复制大段资料进 prompt。RAG 场景控制检索片段数量和长度不是检索越多越好。简单任务用gpt-4o-mini这类小模型复杂任务再升级到更强模型。高频场景接入缓存相同问题直接返回缓存结果。批量任务集中在非高峰时段执行部分服务商有更低的价格。9.5 数据合规与隐私保护这是绝对不能忽略的部分涉及个人隐私数据、企业敏感数据时确认数据可以发送到目标模型服务。使用开源模型本地部署可以避免数据出境风险但推理效果和算力成本需要评估。RAG 知识库中的文档内容要确认没有版权问题。存储用户数据时遵循最小化原则只保留必要的对话记录。在接口层增加访问日志便于审计和追踪异常调用。10. 总结与下一步LangChain 1.3 最值得花时间掌握的核心能力有三块LCEL 链式组合、LangGraph Agent 状态编排、RAG 检索增强流程。这三块能覆盖绝大部分生产场景其余功能都围绕它们展开。如果你刚接触这套框架建议不要一上来就追求看完全部功能文档。真正高效的路径是先跑通最简单的模型调用链然后把一个 RAG 问答做到可上线再尝试给 Agent 加一两个自定义工具。每一步都跟着上面代码过一遍比啃文档效率高很多。最容易踩的坑集中在三处一是环境依赖版本冲突建议新项目都用新虚拟环境从零安装二是模型 API Key 和网络问题导致调用失败先排除环境问题再查业务代码三是 Agent 不按预期调用工具或 RAG 检索不到有用内容这类问题多半要回到 prompt 和参数优化而不是盲目换模型。下一步你可以在这个基础上尝试用 LangGraph 构建多步骤 Agent 工作流、接入 Ollama 跑本地开源模型、把 FastAPI 服务部署到 docker 容器、结合消息队列做成生产级批量任务系统。建议先收藏这篇等真正动手写代码的时候对照着操作一遍比单独啃概念书要实用得多。