在实际企业级应用开发中大模型LLM的直接调用往往无法满足复杂业务需求。开发者需要处理上下文管理、工具调用、记忆、流程编排等一系列工程化问题。LangChain 作为一个开源框架正是为了解决这些挑战而生它将大模型与外部数据源、计算工具、业务流程连接起来构建出真正可用的智能应用。而 RAG检索增强生成和 Agent智能体则是当前最受关注的两大应用范式前者让大模型“有据可查”后者让大模型“有手有脚”。本文旨在提供一个系统性的实战指南面向有一定 Python 基础、希望将大模型能力落地到企业级项目的开发者。我们将从零开始手把手带你理解 LangChain 的核心概念并完成两个核心实战项目一个企业级 RAG 知识库问答系统和一个具备自主决策与工具调用能力的 Agent。整个过程将覆盖从环境搭建、核心组件理解、代码实现、调试优化到生产级考量的完整链路。学完后你将能够独立设计并实现基于 LangChain 的智能应用并具备排查常见问题和进行架构设计的能力。1. 理解 LangChain 的核心为什么需要它而不仅仅是调用 API直接调用 OpenAI 或 Claude 的 API 看似简单但在构建复杂应用时你会迅速遇到瓶颈。LangChain 提供了一套标准化的抽象和组件将大模型应用开发中的通用模式固化下来。1.1 大模型原生应用的三大挑战上下文长度限制所有大模型都有固定的上下文窗口如 128K tokens。当需要处理长文档、多轮对话历史或大量私有知识时如何有效且经济地将相关信息放入上下文是一个工程问题。缺乏“行动”能力大模型本质是文本生成器它无法直接查询数据库、调用 API、执行代码或操作文件系统。如何让模型根据需求自主选择并调用外部工具是构建智能体的核心。状态与记忆管理在多轮对话或长流程任务中应用需要维护对话历史、中间结果和任务状态。如何高效、持久地管理这些信息并让模型在正确的时机访问它们需要一套机制。LangChain 通过引入Chains、Agents、Memory、Retrieval等核心概念为这些挑战提供了解决方案。1.2 LangChain 核心组件速览在动手之前需要先理解几个关键抽象。它们是你构建应用的“积木”。Models (LLMs/Chat Models)模型的抽象层。支持 OpenAI、Anthropic、本地模型通过 Ollama、vLLM 等等多种后端。ChatModels专门用于处理结构化消息System, Human, AI。Prompts提示词模板。将用户输入、上下文、示例等动态组合成最终发送给模型的提示避免字符串拼接的混乱。Indexes / Retrievers索引与检索器。这是 RAG 的基石。Document Loaders从各种源PDF、网页、数据库加载文档Text Splitters进行切分Vector Stores进行向量化存储Retrievers负责根据问题检索相关片段。Chains链。将多个组件模型、提示、工具等按顺序组合起来形成一个可复用的工作流。例如一个简单的问答链可能包含“检索 - 组合提示 - 调用模型”三个步骤。Agents智能体。赋予模型使用工具的能力。Agent包含一个核心的“大脑”通常是 LLM和一个“工具包”。大脑根据用户目标和当前状态决定下一步是调用工具还是直接给出答案。Memory记忆。用于在链或代理的多次调用之间持久化状态。可以是简单的对话缓冲区也可以是更复杂的向量存储记忆。Callbacks回调。用于日志记录、监控、流式输出等是生产环境可观测性的重要部分。理解了这些组件我们就知道 LangChain 项目本质上是在用代码“组装”这些积木。下面我们从环境准备开始。2. 环境准备与项目初始化搭建可复现的开发环境一个清晰、隔离的环境是项目成功的第一步。我们将使用 Conda 管理 Python 环境并用 Poetry 或 pip 管理依赖。2.1 基础环境配置首先确保你的系统已安装 Python推荐 3.9和 Conda。# 1. 创建并激活一个专用的 Conda 环境 conda create -n langchain-demo python3.10 conda activate langchain-demo # 2. 升级 pip 并安装基础包 pip install --upgrade pip2.2 依赖安装与版本管理LangChain 生态庞大我们根据项目需求分层安装。核心是langchain和langchain-community。对于 RAG我们需要向量数据库和嵌入模型对于 Agent我们需要工具库。创建一个requirements.txt文件来管理依赖# 核心框架 langchain0.1.0 langchain-community0.0.10 langchain-core0.1.0 # 用于连接 OpenAI 等模型 (如果你使用 OpenAI API) langchain-openai0.0.5 openai1.6.1 # 用于本地嵌入模型和 LLM (可选节省成本/离线) langchain-ollama0.1.0 ollama # 需要单独安装 Ollama 服务 # 向量数据库 (以 Chroma 为例轻量级) chromadb0.4.22 langchain-chroma0.1.0 # 文档加载与处理 pypdf3.17.4 # 处理 PDF unstructured0.12.2 # 处理多种文档格式 tiktoken0.5.2 # Token 计数 # 工具调用相关 (用于 Agent) langchain-experimental0.0.50 # 包含一些实验性功能如高级 Agent requests2.31.0 # 用于编写调用 API 的工具 langsmith0.0.87 # 可选用于实验追踪和评估 # 其他工具 python-dotenv1.0.0 # 管理环境变量 jupyter1.0.0 # 用于交互式实验使用 pip 安装pip install -r requirements.txt关键解释这里我们同时准备了云端OpenAI和本地Ollama两套方案。langchain-openai是官方集成包比直接用openai包更方便。chromadb是一个轻量级的向量数据库适合学习和开发。生产环境可能会考虑Weaviate、Pinecone或Qdrant。2.3 项目结构与配置管理建立一个清晰的项目目录并管理好敏感信息如 API Key。my_langchain_project/ ├── .env # 存储环境变量切勿提交到 Git ├── .gitignore ├── requirements.txt ├── config/ │ └── settings.py # 应用配置 ├── src/ │ ├── __init__.py │ ├── rag/ # RAG 相关模块 │ │ ├── __init__.py │ │ ├── document_loader.py │ │ ├── vector_store.py │ │ └── chain.py │ ├── agent/ # Agent 相关模块 │ │ ├── __init__.py │ │ ├── tools.py │ │ └── agent.py │ └── utils/ │ └── logger.py ├── data/ # 存放原始文档 │ └── knowledge_base.pdf ├── notebooks/ # 用于探索性实验的 Jupyter Notebook │ └── 01_rag_exploration.ipynb └── tests/ # 单元测试在.env文件中配置你的密钥# .env OPENAI_API_KEYsk-你的OpenAI密钥 # 如果使用其他模型如 Anthropic ANTHROPIC_API_KEY你的Anthropic密钥 # LangSmith 用于追踪可选 LANGSMITH_API_KEY你的LangSmith密钥 LANGSMITH_PROJECTmy-project在config/settings.py中加载配置# config/settings.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的变量 OPENAI_API_KEY os.getenv(OPENAI_API_KEY) if not OPENAI_API_KEY: raise ValueError(请在 .env 文件中设置 OPENAI_API_KEY) # 模型配置 OPENAI_MODEL gpt-4-turbo-preview # 或 gpt-3.5-turbo EMBEDDING_MODEL text-embedding-3-small # 向量数据库路径 VECTOR_STORE_PATH ./data/vector_store环境准备好后我们开始第一个实战项目构建企业级 RAG 系统。3. 实战一构建企业级 RAG 知识库问答系统RAG 的核心思想是当用户提问时先从你的知识库向量数据库中检索出最相关的文档片段然后将这些片段和问题一起交给大模型让模型生成基于这些“证据”的答案。这显著提升了答案的准确性和可控性并减少了模型“胡言乱语”的可能。3.1 文档加载与预处理从原始数据到结构化文本原始文档PDF、Word、网页需要被转换成纯文本并切分成适合检索的片段Chunks。# src/rag/document_loader.py from langchain_community.document_loaders import PyPDFLoader, UnstructuredFileLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.schema import Document from typing import List import os def load_and_split_documents(file_path: str, chunk_size1000, chunk_overlap200) - List[Document]: 加载并分割文档。 Args: file_path: 文档路径 chunk_size: 每个文本块的最大字符数 chunk_overlap: 块之间的重叠字符数用于保持上下文连贯 Returns: 分割后的 Document 对象列表 # 根据文件类型选择加载器 if file_path.endswith(.pdf): loader PyPDFLoader(file_path) else: # Unstructured 可以处理多种格式 loader UnstructuredFileLoader(file_path) raw_documents loader.load() # 使用递归字符分割器它会优先按段落、句子、单词等分隔符分割 text_splitter RecursiveCharacterTextSplitter( chunk_sizechunk_size, chunk_overlapchunk_overlap, length_functionlen, separators[\n\n, \n, 。, , , , , , ] ) split_docs text_splitter.split_documents(raw_documents) print(f原始文档加载了 {len(raw_documents)} 个文档分割为 {len(split_docs)} 个块。) return split_docs # 使用示例 if __name__ __main__: docs load_and_split_documents(./data/knowledge_base.pdf) print(docs[0].page_content[:500]) # 打印第一个块的前500字符关键参数解释chunk_size这是最重要的参数之一。太小会丢失上下文太大会引入噪声且检索效率低。通常 500-1500 字符是一个起点需要根据你的文档内容技术文档、对话记录、法律条文进行调整。chunk_overlap重叠部分可以防止一个完整的句子或概念被硬生生切断有助于提升检索片段的质量。separators分割符优先级列表。RecursiveCharacterTextSplitter会按顺序尝试用这些分隔符分割直到块大小符合要求。3.2 向量化与存储构建知识库的“记忆”将文本块转换为向量嵌入并存入向量数据库以便进行相似性搜索。# src/rag/vector_store.py from langchain_openai import OpenAIEmbeddings from langchain_chroma import Chroma from langchain.schema import Document from typing import List import os from config.settings import EMBEDDING_MODEL, OPENAI_API_KEY, VECTOR_STORE_PATH def create_vector_store(documents: List[Document], persist_directory: str VECTOR_STORE_PATH): 创建或更新向量存储。 # 初始化嵌入模型 embeddings OpenAIEmbeddings( modelEMBEDDING_MODEL, openai_api_keyOPENAI_API_KEY ) # 创建 Chroma 向量存储并持久化到本地目录 vector_store Chroma.from_documents( documentsdocuments, embeddingembeddings, persist_directorypersist_directory ) vector_store.persist() # 确保写入磁盘 print(f向量存储已创建并保存至{persist_directory}) return vector_store def load_vector_store(persist_directory: str VECTOR_STORE_PATH): 加载已存在的向量存储。 embeddings OpenAIEmbeddings(modelEMBEDDING_MODEL, openai_api_keyOPENAI_API_KEY) vector_store Chroma( persist_directorypersist_directory, embedding_functionembeddings ) return vector_store # 使用示例构建知识库 if __name__ __main__: from document_loader import load_and_split_documents docs load_and_split_documents(./data/your_document.pdf) vs create_vector_store(docs)嵌入模型选择OpenAIEmbeddings是付费服务质量高且稳定。如果考虑成本或数据隐私可以使用开源的本地嵌入模型例如通过OllamaEmbeddings调用nomic-embed-text或bge系列模型。3.3 构建检索问答链将检索与生成串联这是 RAG 的核心执行单元。我们使用RetrievalQA链它封装了检索、提示组合和模型调用的完整流程。# src/rag/chain.py from langchain.chains import RetrievalQA from langchain_openai import ChatOpenAI from langchain.prompts import PromptTemplate from config.settings import OPENAI_MODEL, OPENAI_API_KEY def create_retrieval_qa_chain(vector_store, k4): 创建检索问答链。 Args: vector_store: 已加载的向量存储对象 k: 检索返回的最相关文档数量 # 1. 定义 LLM llm ChatOpenAI( model_nameOPENAI_MODEL, temperature0.1, # 低温度使输出更确定、更基于事实 openai_api_keyOPENAI_API_KEY ) # 2. 从向量存储创建检索器 retriever vector_store.as_retriever( search_typesimilarity, # 相似度搜索 search_kwargs{k: k} # 返回 top K 个结果 ) # 3. 自定义提示模板指导模型基于上下文回答 prompt_template 请根据以下上下文信息回答问题。如果你不知道答案就诚实地回答不知道不要编造信息。 上下文 {context} 问题{question} 请基于上下文给出准确、简洁的答案 PROMPT PromptTemplate( templateprompt_template, input_variables[context, question] ) # 4. 创建链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 将所有检索到的文档“塞”进上下文 retrieverretriever, chain_type_kwargs{prompt: PROMPT}, return_source_documentsTrue # 返回源文档便于调试和溯源 ) return qa_chain # 使用示例运行问答 if __name__ __main__: from vector_store import load_vector_store vector_store load_vector_store() qa_chain create_retrieval_qa_chain(vector_store) question 公司今年的战略重点是什么 result qa_chain.invoke({query: question}) print(f问题{question}) print(f答案{result[result]}) print(\n--- 参考来源 ---) for i, doc in enumerate(result[source_documents][:2]): # 显示前两个来源 print(f[{i1}] {doc.page_content[:200]}...)关键配置解释temperature控制模型输出的随机性。对于事实性问答建议设置为较低值如 0.1使输出更稳定、更依赖上下文。search_type“similarity”是余弦相似度搜索。还有“mmr”最大边际相关性可以在相关性和多样性之间取得平衡。chain_type“stuff”是最简单的方式将所有检索到的文档合并成一个上下文。如果文档总长度可能超过模型上下文限制需要考虑“map_reduce”、“refine”或“map_rerank”等更复杂的方式。k检索数量。不是越多越好过多的不相关文档会干扰模型。通常从 3-5 开始调整。3.4 运行与验证测试你的 RAG 系统现在我们可以编写一个简单的脚本或交互式程序来测试整个流程。# run_rag.py import sys sys.path.append(.) from src.rag.vector_store import load_vector_store from src.rag.chain import create_retrieval_qa_chain def main(): print(正在加载向量知识库...) vector_store load_vector_store() qa_chain create_retrieval_qa_chain(vector_store, k3) print(RAG 系统已就绪。输入 quit 退出。\n) while True: question input(\n请输入你的问题) if question.lower() in [quit, exit, q]: break if not question.strip(): continue print(思考中...) try: result qa_chain.invoke({query: question}) print(f\n答案{result[result]}) # 可选显示来源 show_source input(是否显示来源(y/n): ).lower() if show_source y: for i, doc in enumerate(result[source_documents]): print(f\n--- 来源 {i1} ---) print(doc.page_content[:300]) except Exception as e: print(f处理问题时出错{e}) if __name__ __main__: main()运行python run_rag.py输入关于你知识库文档的问题观察系统是否能返回基于文档的准确答案并查看其引用的来源。这是验证 RAG 是否正常工作的关键一步。4. 实战二打造具备工具调用能力的智能体Agent如果说 RAG 扩展了模型的“知识”那么 Agent 则扩展了模型的“能力”。一个 Agent 可以理解用户目标规划步骤并调用预定义的工具如搜索、计算、API 调用来完成任务。4.1 定义工具赋予 Agent “双手”工具是 Agent 与环境交互的接口。每个工具都是一个函数有明确的名称、描述和参数。# src/agent/tools.py from langchain.tools import tool from datetime import datetime import requests import json tool def get_current_time(format: str %Y-%m-%d %H:%M:%S) - str: 获取当前的日期和时间。可以指定格式默认是 YYYY-MM-DD HH:MM:SS。 return datetime.now().strftime(format) tool def search_weather(city: str) - str: 查询指定城市的当前天气。需要提供城市名例如‘北京’或‘Shanghai’。 # 注意这里使用一个模拟的免费天气 API 示例实际使用时请替换为可靠的 API # 并妥善处理 API Key 和错误 try: # 示例 URL实际不可用 # url fhttps://api.weatherapi.com/v1/current.json?keyYOUR_KEYq{city} # response requests.get(url, timeout10) # data response.json() # return f{city}的天气是{data[current][condition][text]}温度 {data[current][temp_c]}°C # 模拟返回 return f[模拟] {city}的天气晴温度 22°C。提示请接入真实天气 API。 except Exception as e: return f查询天气时出错{e} tool def calculate(expression: str) - str: 执行一个数学计算表达式并返回结果。例如‘3 5 * 2’。注意使用 eval请确保输入安全。 # 警告在生产环境中直接使用 eval 是危险的应使用更安全的计算库如 ast.literal_eval 或自定义解析器 # 此处仅用于演示。 try: # 极其简化的安全过滤生产环境必须加强 if any(keyword in expression.lower() for keyword in [import, os, sys, exec, eval, __]): return 表达式包含不安全字符拒绝计算。 result eval(expression) return f{expression} {result} except Exception as e: return f计算表达式‘{expression}’时出错{e} # 将所有工具放在一个列表中 AGENT_TOOLS [get_current_time, search_weather, calculate]工具定义要点清晰的描述tool装饰器会使用函数的 docstring 作为工具描述。这是 Agent 决定是否以及如何使用该工具的主要依据必须准确。强类型的参数使用 Python 类型注解如city: str有助于 LangChain 为 Agent 生成更准确的调用模式。安全性像calculate工具中的eval是极度危险的。真实项目中必须使用沙箱或安全的数学表达式解析库如numexpr。4.2 创建智能体组装“大脑”与“工具箱”我们将使用 LangChain 的create_react_agent来构建一个 ReAct 模式的 Agent。ReActReasoning Acting是一种让模型在思考生成推理轨迹和行动调用工具之间交替进行的范式效果很好。# src/agent/agent.py from langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI from src.agent.tools import AGENT_TOOLS from config.settings import OPENAI_MODEL, OPENAI_API_KEY def create_agent_executor(): 创建并返回一个配置好的 Agent 执行器。 # 1. 定义 LLM 作为 Agent 的大脑 llm ChatOpenAI( model_nameOPENAI_MODEL, temperature0, # Agent 需要确定性高的决策 openai_api_keyOPENAI_API_KEY ) # 2. 从 LangChain Hub 拉取一个预设的 ReAct 提示词 # 这个提示词指导模型如何思考、使用工具和格式化输出 prompt hub.pull(hwchase17/react) # 3. 创建 ReAct Agent agent create_react_agent(llm, AGENT_TOOLS, prompt) # 4. 创建执行器它负责运行 Agent处理工具调用循环 agent_executor AgentExecutor( agentagent, toolsAGENT_TOOLS, verboseTrue, # 打印详细的思考过程便于调试 handle_parsing_errorsTrue, # 优雅地处理 Agent 输出解析错误 max_iterations5, # 防止 Agent 陷入无限循环 early_stopping_methodgenerate # 当 Agent 认为任务完成时停止 ) return agent_executor # 使用示例 if __name__ __main__: agent_executor create_agent_executor() questions [ 现在几点了, 北京和上海的天气怎么样, 计算一下 (15 7) * 3 等于多少, 先查一下伦敦的天气然后告诉我现在的时间。 ] for question in questions: print(f\n{*50}) print(f用户问题{question}) print(f{*50}) try: result agent_executor.invoke({input: question}) print(f最终答案{result[output]}) except Exception as e: print(f执行出错{e})运行这个脚本你会看到类似以下的输出展示了 Agent 的思考过程因为verboseTrue用户问题北京和上海的天气怎么样 进入新的 Agent 执行链... 思考我需要分别查询北京和上海的天气。我有搜索天气的工具。 行动search_weather 行动输入北京 观察[模拟] 北京的天气晴温度 22°C。提示请接入真实天气 API。 思考现在查询上海的天气。 行动search_weather 行动输入上海 观察[模拟] 上海的天气多云温度 25°C。提示请接入真实天气 API。 思考我现在有了两个城市的信息可以总结回答了。 行动generate 行动输入北京天气晴朗22°C上海多云25°C。 最终答案北京天气晴朗气温22摄氏度上海多云气温25摄氏度。关键配置解释verboseTrue在开发阶段务必开启这是理解 Agent 决策逻辑、排查问题的最重要手段。max_iterations安全护栏。防止 Agent 因逻辑错误或工具失败而无限循环。handle_parsing_errorsTrue当 Agent 的输出不符合工具调用格式时尝试让模型重新生成。这能提高系统的鲁棒性。4.3 高级主题使用 LangGraph 编排复杂多智能体工作流当任务变得非常复杂需要多个 Agent 协作或有严格的状态流转需求时基础的AgentExecutor可能不够用。这时可以使用LangGraph它允许你用图Graph的方式来定义和控制工作流。LangGraph 与 LangChain 的关系LangChain 提供了构建链和智能体的基础组件而 LangGraph 是建立在 LangChain 之上的一个库专门用于编排有状态、多步骤、可能循环或分支的复杂工作流。一个简单的 LangGraph 智能体示例# src/agent/langgraph_agent.py (高级示例) from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated import operator from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from src.agent.tools import AGENT_TOOLS from langchain_core.messages import HumanMessage from config.settings import OPENAI_MODEL, OPENAI_API_KEY # 1. 定义状态结构 class AgentState(TypedDict): messages: Annotated[list, operator.add] # 消息历史 current_task: str # 当前任务描述 # 2. 初始化 LLM 和基础 Agent llm ChatOpenAI(modelOPENAI_MODEL, temperature0, openai_api_keyOPENAI_API_KEY) prompt hub.pull(hwchase17/react) base_agent create_react_agent(llm, AGENT_TOOLS, prompt) agent_executor AgentExecutor(agentbase_agent, toolsAGENT_TOOLS, verboseFalse) # 3. 定义节点函数 def call_agent(state: AgentState): 调用 Agent 处理当前任务 task state[current_task] result agent_executor.invoke({input: task}) return {messages: [HumanMessage(contentf任务‘{task}’完成。结果{result[output]})]} def decide_next_step(state: AgentState): 根据结果决定下一步简化示例总是结束 # 这里可以加入复杂的逻辑例如分析结果决定是继续、分支还是结束 print(决策节点任务已完成准备结束。) return end # 4. 构建图 workflow StateGraph(AgentState) workflow.add_node(agent, call_agent) # 添加 Agent 节点 workflow.add_node(decide, decide_next_step) # 添加决策节点 workflow.set_entry_point(agent) # 设置入口 workflow.add_edge(agent, decide) # agent 执行完后到 decide workflow.add_edge(decide, END) # decide 决定后结束 # 5. 编译图 app workflow.compile() # 6. 运行 initial_state {messages: [], current_task: 计算 (1234)*2 的值并告诉我现在的时间。} result app.invoke(initial_state) print(最终状态消息, result[messages])这个例子展示了如何将 Agent 执行作为一个节点嵌入到更大的、可编程的工作流中。对于需要审核、循环检查、多专家协作等场景LangGraph 是更强大的工具。5. 生产级考量与常见问题排查将原型部署到生产环境需要解决一系列工程问题。5.1 性能、成本与稳定性优化方面问题优化策略检索质量检索到的文档不相关导致答案不准。1.调整分块策略尝试不同chunk_size和chunk_overlap。2.优化嵌入模型评估不同嵌入模型在您领域数据上的表现。3.使用混合搜索结合向量相似度语义和关键词匹配BM25。4.重排序Rerank使用更精细的模型如 Cohere Rerank对初步检索结果重新排序。响应速度首次检索或回答慢。1.缓存对常见问题的检索结果或最终答案进行缓存。2.异步处理对于耗时的文档加载和向量化使用异步操作。3.优化向量数据库使用性能更高的向量数据库如 Weaviate, Qdrant并建立索引。成本控制OpenAI API 调用费用高。1.本地模型非核心任务使用 Ollama 等本地模型。2.提示词优化精简提示词减少 token 消耗。3.缓存同上减少重复调用。4.设置预算和限流。稳定性API 调用失败或超时。1.重试机制为 LLM 和 Embedding 调用添加指数退避重试。2.降级方案主模型失败时切换到备用模型或返回兜底答案。3.超时设置合理设置请求超时时间。可观测性问题难以复现和调试。1.全面日志记录用户输入、检索到的文档、模型输入/输出、工具调用。2.使用 LangSmith集成 LangSmith 来追踪每个链和 Agent 的执行过程、耗时和中间结果。3.监控指标监控请求量、延迟、错误率、token 消耗。5.2 常见错误排查清单当你的 LangChain 应用出现问题时可以按照以下顺序排查认证与连接问题现象AuthenticationError或APIConnectionError。检查环境变量OPENAI_API_KEY等是否正确设置并已加载。网络连接是否正常。API 端点如果使用非官方服务是否正确。依赖版本冲突现象ImportError或AttributeError提示某个模块没有属性。检查pip list | grep langchain查看版本。LangChain 版本迭代快社区包langchain-community和核心包langchain-core版本不匹配是常见问题。严格按照官方文档或requirements.txt锁定版本。RAG 答案质量差现象答案与文档无关或回答“不知道”但文档中其实有。排查步骤检查检索结果在调用链之前先单独测试检索器retriever.get_relevant_documents(question)看返回的文档是否相关。检查分块查看原始文档的分块是否合理有没有把完整句子或段落切碎。检查嵌入尝试计算问题与相关文档片段的向量相似度看分数是否过低。检查提示词你的提示词是否明确要求模型“基于上下文”回答将{context}和{question}的实际内容打印出来看看组合成的最终提示词是什么样子。Agent 陷入循环或调用错误工具现象Agent 不断重复同一个动作或调用了不合适的工具。排查步骤开启verboseTrue这是最重要的调试手段查看模型的“思考”过程。优化工具描述确保工具的函数名和 docstring 清晰、无歧义能让模型准确理解其功能。调整max_iterations如果任务复杂适当增加迭代次数如果总是循环则减少次数或检查工具是否总是失败。使用更强大的模型复杂的 Agent 任务需要像 GPT-4 这类推理能力更强的模型GPT-3.5-turbo 可能无法胜任。内存Memory相关问题现象多轮对话中Agent 或 Chain 忘记了之前的对话内容。检查是否正确初始化并将在链或 Agent 之间传递了memory对象。检查记忆对象的存储上限如ConversationBufferWindowMemory的k参数。5.3 安全与合规建议输入净化对用户输入进行基本的清理和检查防止提示词注入攻击。工具安全像calculate中的eval是极端危险的示例。任何执行代码、访问文件系统或外部系统的工具都必须经过严格的安全审查和沙箱隔离。输出过滤对模型生成的内容进行审核或过滤避免产生有害或不适当的内容。数据隐私如果使用云端模型 API确保传输和处理的私有数据符合公司隐私政策。对于高度敏感数据考虑完全本地化部署。访问控制为你的智能应用添加身份认证和权限控制确保只有授权用户能访问。6. 总结与进阶方向通过以上步骤我们完成了从零搭建 LangChain 核心应用的两个典型场景RAG 和 Agent。关键在于理解 LangChain 的组件化思想——用Document Loader、Text Splitter、Vector Store、RetrievalQA链来构建知识系统用Tool、Agent、AgentExecutor来构建行动系统。要真正“吃透”并用于企业级项目下一步可以深入以下方向深入向量数据库学习 Chroma、Weaviate、Pinecone 等数据库的进阶特性如元数据过滤、多向量搜索、性能调优。探索高级 Agent 框架研究ReAct、Plan-and-Execute、OpenAI Functions等不同 Agent 范式的适用场景。学习使用LangGraph编排涉及状态、循环和分支的复杂工作流。集成外部系统将你的 LangChain 应用与现有的企业系统CRM、ERP、数据库、内部 API连接起来定义更多实用的工具。评估与迭代建立评估体系用测试集衡量 RAG 的检索准确率、答案相关性。使用 LangSmith 持续追踪生产链路的性能和质量。关注部署学习如何使用 FastAPI 或 Django 将你的应用封装成 API 服务如何容器化Docker以及如何在 Kubernetes 上部署和扩缩容。记住LangChain 是一个快速发展的生态核心在于理解其设计模式来组织你的大模型应用代码而不是死记硬背 API。当遇到问题时优先查阅官方文档并善用verboseTrue输出和 LangSmith 进行调试。从一个小而具体的功能开始逐步迭代和复杂化是掌握这项技术的最佳路径。
)
