LangChain实战指南：从模型接入到RAG与Agent开发全解析

1. 先搞清楚 LangChain 到底能帮你解决什么实际问题

如果你正在接触大模型应用开发，或者想把大模型能力集成到自己的业务系统里，那么 LangChain 是你绕不开的一个框架。它不是一个模型，而是一个“胶水”和“脚手架”，核心价值在于把大模型、外部数据、工具调用和复杂逻辑编排成一个可执行的、稳定的应用。

很多人一上来就去看它的几十个模块，结果越看越懵。其实，从实际落地的角度看，LangChain 主要解决三类问题：

1. 模型接入与切换：你的代码里可能今天用 OpenAI，明天要换成本地部署的 Qwen，后天又要测试 Claude。如果每次换模型都重写一遍请求、解析、错误处理的代码，会非常痛苦。LangChain 提供了一个统一的接口（LLM/ChatModel），让你用几乎相同的代码调用不同的模型。
2. Prompt 管理与复杂编排：简单的问答可以直接写 Prompt。但如果你需要根据用户问题动态选择上下文、进行多步推理、或者把一个大任务拆成几个小任务依次执行，手动拼接字符串会变成一场灾难。LangChain 提供了PromptTemplate、LCEL（LangChain 表达式语言）等，让你能像搭积木一样声明式地构建复杂的工作流。
3. 连接外部世界：大模型本身的知识是静态的，且可能过时。要让模型能“联网搜索”、“查询数据库”、“操作软件”，就需要Agent（智能体）。而要让模型能“阅读”你的私有文档（如公司手册、产品PDF），就需要RAG（检索增强生成）。LangChain 为这两者提供了标准化的组件和设计模式。

所以，这个教程的目标不是让你背 API，而是让你掌握如何用 LangChain 的思维，把一个模糊的 AI 想法，变成一个可运行、可调试、可扩展的工程项目。我会从环境配置开始，带你走过单模型调用、Prompt 编排、Agent 开发，最终完成一个 RAG 项目，过程中会穿插大量我实际踩过的坑和调试经验。

2. 环境配置：别在第一步就卡住

LangChain 是 Python 库，所以一个干净的 Python 环境是基础。我强烈建议使用conda或venv创建独立的虚拟环境，避免包冲突。

2.1 基础环境搭建

首先，确保你的 Python 版本在 3.8 以上。然后创建并激活虚拟环境：

# 使用 conda conda create -n langchain-env python=3.10 conda activate langchain-env # 或使用 venv python -m venv langchain-env source langchain-env/bin/activate # Linux/macOS langchain-env\Scripts\activate # Windows

接下来安装 LangChain。注意，LangChain 是一个庞大的项目，包含了核心包和许多社区集成包。对于初学者，先安装核心包和常用的集成。

pip install langchain langchain-community

langchain是核心，langchain-community包含了大量第三方集成（如各种数据库、工具等）。

2.2 模型提供商接入：从 OpenAI 到本地模型

模型是核心。我们从一个最简单的例子开始：调用 OpenAI 的 GPT 模型。你需要一个 OpenAI 的 API Key。

pip install openai

然后在代码中设置环境变量并使用：

import os from langchain_openai import ChatOpenAI # 建议将 API Key 设置在环境变量中，不要硬编码在代码里 os.environ["OPENAI_API_KEY"] = "your-api-key-here" llm = ChatOpenAI(model="gpt-3.5-turbo") response = llm.invoke("Hello, world!") print(response.content)

这是最顺畅的路径。但如果你无法访问或希望使用本地模型，比如 Qwen，就需要换一种方式。这也是搜索热词里cursor接入本地模型、codex接入第三方模型背后大家关心的问题。

接入本地/第三方模型的关键：大多数开源模型都提供了兼容 OpenAI API 格式的本地服务（如使用 Ollama 、 vLLM 或 OpenAI-Compatible 项目部署）。一旦部署好，你就可以像调用 OpenAI 一样调用它们。

例如，你用 Ollama 在本地运行了 Qwen2.5 模型：

ollama run qwen2.5:7b

默认会在http://localhost:11434提供 API。在 LangChain 中，你可以使用ChatOpenAI类，但修改base_url和api_key（如果不需要则随便填一个）。

from langchain_openai import ChatOpenAI # 指向本地 Ollama 服务 llm = ChatOpenAI( base_url="http://localhost:11434/v1", api_key="ollama", # Ollama 通常不需要鉴权，但字段需要存在 model="qwen2.5:7b" ) response = llm.invoke("请用中文回答，法国的首都是哪里？") print(response.content)

这里有个大坑：不同本地部署方案对 API 的支持程度不同。如果报错，第一件事是先用curl命令测试你的本地模型服务是否真的返回了 OpenAI 兼容的格式。

curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5:7b", "messages": [{"role": "user", "content": "Hello"}], "stream": false }'

如果这个curl命令能返回正确的 JSON，那么 LangChain 接入大概率没问题。如果失败，问题出在模型服务端，而不是 LangChain 配置。

2.3 必备工具包安装

根据你要做的任务，可能还需要安装其他包：

# 用于 RAG：文档加载、文本分割、向量数据库 pip install langchain-text-splitters langchain-chroma pypdf # 用于 Agent：可能需要一些工具库，如计算、搜索 pip install langchain-experimental # 包含一些实验性工具和Agent pip install wikipedia # 示例工具 # 用于更复杂的流程编排（LangGraph） pip install langgraph

环境准备好后，我们不要急着写复杂应用，先从最核心的“对话”开始。

3. 模型接入与 Prompt 编排：从一次对话到可控流程

很多教程把 Prompt 编排讲得很玄乎，其实本质就是如何动态地、结构化地生成给模型的指令。

3.1 基础 PromptTemplate：告别字符串拼接

假设你想做一个翻译机器人，需要将用户输入的语言翻译成目标语言。

错误做法（字符串拼接）：

user_input = "Hello" target_lang = "法语" prompt = f"请将以下英文翻译成{target_lang}：{user_input}" # 当变量多、结构复杂时，这里会变得难以维护

正确做法（使用 PromptTemplate）：

from langchain.prompts import ChatPromptTemplate template = ChatPromptTemplate.from_messages([ ("system", "你是一个专业的翻译助手。"), ("user", "请将以下 {source_lang} 文本翻译成 {target_lang}：{text}") ]) prompt = template.invoke({ "source_lang": "英语", "target_lang": "法语", "text": "Hello, world!" }) print(prompt.to_string()) # 输出结构化的消息列表，可以直接发给 ChatModel llm = ChatOpenAI(model="gpt-3.5-turbo") response = llm.invoke(prompt) print(response.content)

ChatPromptTemplate的好处是它管理了消息角色（system, user, assistant），并且能安全地处理变量注入，避免 Prompt 注入攻击。

3.2 LCEL：把工作流连起来

LCEL（LangChain Expression Language）是 LangChain V1 的核心。它让你能用|操作符把组件链起来，像管道一样处理数据。

上面“模板 -> 模型 -> 输出”的过程，用 LCEL 可以写成一行链：

from langchain.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI llm = ChatOpenAI(model="gpt-3.5-turbo") translation_prompt = ChatPromptTemplate.from_template( "将以下 {source_lang} 文本翻译成 {target_lang}：{text}" ) # 定义链：prompt | llm translation_chain = translation_prompt | llm # 运行链 result = translation_chain.invoke({ "source_lang": "英语", "target_lang": "日语", "text": "Good morning" }) print(result.content)

这看起来只是语法糖，但当链变复杂时，其价值就体现出来了。例如，我们想在翻译后，让模型对翻译结果进行简要评价：

from langchain.schema.output_parser import StrOutputParser from langchain.schema.runnable import RunnablePassthrough # 第一个链：翻译 translation_chain = translation_prompt | llm | StrOutputParser() # 第二个链：评价。注意：这里的输入是上一个链的输出（翻译结果） evaluation_prompt = ChatPromptTemplate.from_template( "你是一名翻译质检员。请对以下翻译结果进行简要评价（1-2句话）：{translated_text}" ) evaluation_chain = evaluation_prompt | llm | StrOutputParser() # 组合链：先翻译，再将翻译结果传递给评价链 # RunnablePassthrough() 用于传递初始的输入变量，这里我们用不上全部，需要自定义 def combine_inputs(data): # 先运行翻译链，得到翻译文本 translated = translation_chain.invoke(data) # 返回一个字典，包含评价链需要的 `translated_text` return {"translated_text": translated} full_chain = ( RunnablePassthrough() # 接收原始输入 | combine_inputs # 自定义函数，生成中间结果 | evaluation_chain # 执行评价 ) # 现在 full_chain 的输入依然是 {source_lang, target_lang, text} final_result = full_chain.invoke({ "source_lang": "英语", "target_lang": "日语", "text": "Good morning" }) print(final_result)

LCEL 的强大在于它的声明式和可组合性。你可以轻松地调试链中的任何一步，也可以将链序列化保存。对于企业级项目，这种可维护性和可观测性至关重要。

3.3 更复杂的编排：条件判断与分支

现实任务很少是直线。例如，根据用户问题类型，决定是调用通用模型还是专业模型。这需要用到RunnableBranch。

from langchain.schema.runnable import RunnableBranch # 假设我们有两个不同的 LLM（可以是同一个模型的不同版本，或不同厂商的模型） general_llm = ChatOpenAI(model="gpt-3.5-turbo") expert_llm = ChatOpenAI(model="gpt-4") # 或另一个本地专家模型 # 定义一个路由函数：如果问题包含“法律”关键词，走专家链，否则走通用链 def route_question(input_dict): question = input_dict["question"].lower() if "法律" in question or "合同" in question: return "legal" else: return "general" # 定义两个处理分支 general_chain = ( ChatPromptTemplate.from_template("你是一个助手，请回答：{question}") | general_llm | StrOutputParser() ) legal_chain = ( ChatPromptTemplate.from_template("你是一名法律AI助手，请严谨地回答以下法律相关问题：{question}") | expert_llm | StrOutputParser() ) # 创建分支 branch = RunnableBranch( (lambda x: route_question(x) == "legal", legal_chain), general_chain # 默认分支 ) # 运行 result = branch.invoke({"question": "签署劳动合同需要注意什么？"}) print(f"法律问题结果：{result}") result2 = branch.invoke({"question": "今天天气怎么样？"}) print(f"通用问题结果：{result2}")

通过 LCEL 和分支，你就能构建出有一定逻辑判断能力的应用流程。这是通向 Agent 的基础。

4. Agent 智能体开发：让模型学会使用工具

Agent 是 LangChain 中最激动人心也最容易让人困惑的部分。简单说，Agent = LLM + 思考规划 + 工具使用。模型不再只是生成文本，而是可以主动调用搜索引擎、计算器、数据库等外部工具来完成任务。

4.1 Agent 的核心三要素

1. 工具（Tools）：Agent 可以调用的函数。比如：搜索网络、查询数据库、执行代码、调用 API。
2. LLM：作为 Agent 的“大脑”，负责理解目标、规划步骤、决定使用哪个工具、解析工具结果。
3. 代理（Agent）：将 LLM 和工具组合在一起的执行框架。它定义了 LLM 与工具交互的流程（ReAct、OpenAI Functions 等）。

4.2 创建一个最简单的 Agent

我们创建一个能使用计算器和搜索维基百科的 Agent。首先安装必要库：

pip install langchain langchain-community wikipedia numexpr

然后编写代码：

import os from langchain.agents import AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain import hub from langchain_community.tools import WikipediaQueryRun, Tool from langchain_community.utilities import WikipediaAPIWrapper from langchain_experimental.tools import PythonREPLTool # 1. 定义工具 # 工具1：Python REPL（可以执行数学计算） python_repl = PythonREPLTool() # 工具2：维基百科搜索 api_wrapper = WikipediaAPIWrapper(top_k_results=2, doc_content_chars_max=500) wikipedia = WikipediaQueryRun(api_wrapper=api_wrapper) # 将工具包装成 LangChain Tool 对象 tools = [ Tool( name="Calculator", func=python_repl.run, description="用于执行数学计算。输入应该是一个有效的 Python 数学表达式，例如：`2 + 2` 或 `sqrt(25)`。" ), Tool( name="Wikipedia", func=wikipedia.run, description="用于搜索维基百科，获取关于人物、地点、公司、历史事件等的事实信息。输入应该是一个搜索查询词。" ) ] # 2. 初始化 LLM llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) # 3. 获取一个预设的 Prompt（来自 LangChain Hub） # 这个 Prompt 包含了 ReAct 框架的指令：思考（Thought）、行动（Action）、观察（Observation） prompt = hub.pull("hwchase17/react-chat") # 4. 创建 Agent agent = create_react_agent(llm, tools, prompt) # 5. 创建 Agent 执行器 agent_executor = AgentExecutor( agent=agent, tools=tools, verbose=True, # 开启详细日志，可以看到 Agent 的思考过程 handle_parsing_errors=True, # 处理解析错误 max_iterations=5 # 限制最大迭代次数，防止死循环 ) # 6. 运行 Agent result = agent_executor.invoke({ "input": "请先计算 15 的平方根，然后搜索一下爱因斯坦的生平。", "chat_history": [] # 如果是多轮对话，这里需要传入历史 }) print(result["output"])

运行这段代码，你会看到控制台输出类似以下内容（因为verbose=True）：

> Entering new AgentExecutor chain... Thought: 用户问了两件事：计算15的平方根，然后搜索爱因斯坦的生平。我需要按顺序使用工具。 Action: Calculator Action Input: math.sqrt(15) Observation: 3.872983346207417 Thought: 我得到了计算结果。现在需要搜索爱因斯坦的生平。 Action: Wikipedia Action Input: Albert Einstein Observation: Page: Albert Einstein Summary: Albert Einstein was a German-born theoretical physicist... Thought: 我已经完成了用户要求的两个任务。 Final Answer: 15的平方根约为3.873。阿尔伯特·爱因斯坦是德裔理论物理学家，他最著名的成就是提出了相对论，并因此获得了1921年诺贝尔物理学奖。 > Finished chain.

这就是 Agent 的工作过程：LLM（Thought）决定下一步做什么，选择工具（Action）并生成输入，执行工具得到结果（Observation），然后根据结果进行下一步思考，直到得出最终答案。

4.3 Agent 开发中的关键坑点

1. 工具描述（Description）至关重要：LLM 根据工具的描述来决定是否以及如何使用它。描述必须清晰、准确，说明工具的用途、输入格式和限制。模糊的描述会导致 Agent 错误调用工具。
2. 控制迭代与超时：必须设置max_iterations和（可选的）max_execution_time。否则一个陷入循环的 Agent 会无限消耗你的 Token。
3. 错误处理：handle_parsing_errors=True是必要的，因为 LLM 有时会生成不符合格式的文本，导致解析失败。更好的做法是自定义一个错误处理回调。
4. 对本地模型不友好：许多开源模型在遵循复杂的 ReAct 格式指令上表现不佳，导致 Action 解析失败。如果使用本地模型，可能需要更简单的 Agent 类型（如ZERO_SHOT_REACT_DESCRIPTION）或进行额外的 Prompt 调优。
5. 成本与延迟：Agent 的每一步思考（Thought）和行动（Action）都是一次 LLM 调用，对于按 Token 收费的 API，成本会显著增加。需要权衡任务复杂度和成本。

4.4 多智能体与 LangGraph

当单个 Agent 不够用时，就需要多个 Agent 协作，这就是LangGraph的领域。LangGraph允许你定义由多个节点（可以是 LLM、工具、函数或其他 Agent）和边（控制流）组成的图。

例如，一个客服系统可能包含：路由Agent（判断问题类型）->技术客服Agent（处理技术问题）->订单查询Agent（处理订单问题）->汇总Agent（整理最终回复）。LangGraph可以清晰地管理这种复杂的状态和流程。

由于LangGraph概念更复杂，建议在熟练掌握单 Agent 后，再基于官方文档和示例进行学习。搜索热词中的langchain和langgraph的区别可以简单理解为：LangChain 是构建单链或单 Agent 的框架，而 LangGraph 是构建多 Agent 协作工作流的框架。

5. RAG 项目实战：构建你的私有知识库问答系统

RAG（检索增强生成）是目前将大模型与私有数据结合最主流、最有效的方法。其核心流程是：检索（Retrieve）相关文档片段 -> 将它们与问题一起组合成 Prompt -> 生成（Generate）答案。

5.1 RAG 系统构建四步法

我们以一个“公司内部知识库问答”为例，使用 PDF 文档作为数据源。

第一步：文档加载与分割

from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter # 1. 加载文档 loader = PyPDFLoader("./path/to/your/company_handbook.pdf") documents = loader.load() # 2. 分割文本 # 为什么分割？因为大模型有上下文长度限制，且整篇文档检索效率低。 text_splitter = RecursiveCharacterTextSplitter( chunk_size=500, # 每个片段的最大字符数 chunk_overlap=50, # 片段之间的重叠字符，避免上下文断裂 separators=["\n\n", "\n", "。", "，", " ", ""] # 分割符优先级 ) chunks = text_splitter.split_documents(documents) print(f"原始文档页数：{len(documents)}，分割后片段数：{len(chunks)}")

分割参数调优：chunk_size和chunk_overlap是 RAG 效果的关键。太小会丢失上下文，太大会引入噪声。对于通用文档，500-1000 是个不错的起点。对于代码或技术文档，可以按函数或章节分割。

第二步：向量化与存储

我们需要将文本片段转换成向量（嵌入），并存入向量数据库，以便后续相似度检索。

from langchain_openai import OpenAIEmbeddings from langchain_chroma import Chroma # 使用 OpenAI 的嵌入模型（也可换为本地模型，如 BGE） embeddings = OpenAIEmbeddings(model="text-embedding-3-small") # 创建向量数据库（这里使用 Chroma，轻量且易用） # persist_directory 指定持久化目录，否则数据只在内存中 vectorstore = Chroma.from_documents( documents=chunks, embedding=embeddings, persist_directory="./chroma_db" # 数据将保存到此目录 ) vectorstore.persist() # 显式保存

关键选择：

• 嵌入模型：选择与你的语言（中/英）和领域匹配的模型。OpenAI 的嵌入效果好但需付费。中文可考虑BAAI/bge-large-zh等开源模型，通过HuggingFaceEmbeddings接入。
• 向量数据库：Chroma 适合轻量级和原型开发。生产环境可以考虑 Qdrant、Weaviate、Pinecone（云服务）等，它们在规模、性能和功能上更强大。

第三步：检索

构建一个检索器，它能根据用户问题，从向量库中找到最相关的文本片段。

# 从已持久化的目录加载向量库 vectorstore = Chroma( persist_directory="./chroma_db", embedding_function=embeddings ) # 创建检索器。search_type 可选 "similarity"（相似度）或 "mmr"（最大边际相关性，兼顾相关性和多样性） retriever = vectorstore.as_retriever( search_type="similarity", search_kwargs={"k": 4} # 返回最相关的 4 个片段 ) # 测试检索 query = "公司年假政策是怎样的？" relevant_docs = retriever.invoke(query) print(f"检索到 {len(relevant_docs)} 个相关片段") for i, doc in enumerate(relevant_docs): print(f"\n--- 片段 {i+1} ---\n{doc.page_content[:300]}...") # 打印前300字符

第四步：生成

将检索到的上下文和原始问题组合，发送给 LLM 生成答案。

from langchain.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI from langchain.schema.runnable import RunnablePassthrough from langchain.schema.output_parser import StrOutputParser # 1. 定义 Prompt 模板 template = """你是一个专业的公司知识库助手。请严格根据以下上下文信息回答问题。 如果你不知道答案，就如实说不知道，不要编造信息。 上下文信息： {context} 问题：{question} 请根据上下文提供准确、简洁的答案：""" prompt = ChatPromptTemplate.from_template(template) # 2. 定义 LLM llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) # 3. 构建 RAG 链 # 链的流程：传入问题 -> 检索器获取上下文 -> 格式化 Prompt -> LLM 生成 -> 解析输出 rag_chain = ( {"context": retriever, "question": RunnablePassthrough()} | prompt | llm | StrOutputParser() ) # 4. 提问 question = "公司年假政策是怎样的？" answer = rag_chain.invoke(question) print(f"问题：{question}") print(f"答案：{answer}")

至此，一个最基本的 RAG 流水线就完成了。用户的问题会先检索知识库，然后将相关片段作为上下文提供给 LLM，从而生成基于你私有知识的答案。

5.2 提升 RAG 效果的实战技巧

基础的 RAG 很容易搭建，但效果往往不尽如人意。以下是几个必须关注的优化点：

1. 检索质量是天花板：如果检索到的文档不相关，LLM 再强也无力回天。优化方法：
   • 优化分割策略：尝试不同的chunk_size和分割符。对于结构化文档（如 Markdown），可以按标题分割。
   • 优化检索器：尝试MMR搜索，或在检索后增加一个LLM 重排序步骤，用一个小模型对检索结果进行相关性排序。
   • 混合检索：结合关键词检索（如 BM25）和向量检索，取长补短。
2. Prompt 工程：给模型的指令要清晰。明确告诉它“基于上下文”、“不要编造”、“如果上下文没有就说不知道”。在上下文中用明显的标记（如## 上下文 ##）分隔。
3. 引用溯源：对于企业应用，知道答案来自哪份文档、哪一页非常重要。在分割文档时，务必保留元数据（如source,page）。在生成答案后，可以将引用的片段 ID 或源信息一并返回。
4. 处理“未命中”：当检索器返回的片段相关性都很低时，应该有一个降级策略，比如直接让 LLM 回答“知识库中未找到相关信息”，或者转而进行通用问答。
5. 评估与迭代：建立评估集（一组问题+标准答案），定期跑测试，查看检索命中率、答案准确率。这是优化 RAG 系统的唯一科学方法。

6. 从 Demo 到企业级项目：必须考虑的工程问题

把 Demo 跑通只是第一步。要用于实际生产，你必须考虑以下问题：

6.1 配置管理与安全

• API Key 等敏感信息：绝对不要硬编码在代码中。使用环境变量（os.getenv）或专业的密钥管理服务（如 AWS Secrets Manager, HashiCorp Vault）。
• 配置分离：将模型类型、API Base URL、温度参数、块大小等配置项放在配置文件（如config.yaml或.env）中，便于不同环境（开发、测试、生产）切换。

6.2 可观测性与日志

• 记录每一次 LLM 调用：包括输入的 Prompt、收到的响应、Token 使用量、耗时。这对于调试、成本分析和效果优化至关重要。LangChain 提供了回调机制（Callbacks），可以方便地集成日志系统。
• 记录 Agent 的思考过程：生产环境 Agent 出错时，完整的 Thought-Action-Observation 链条是排查问题的唯一线索。

6.3 性能与成本

• 缓存：对频繁出现的相似查询结果进行缓存，可以大幅降低 LLM 调用成本和延迟。LangChain 内置了InMemoryCache、RedisCache等。
• 异步处理：对于批量任务或高并发场景，使用 LangChain 的异步接口（ainvoke,abatch）可以显著提升吞吐量。
• 模型降级：非关键任务或简单任务，使用更小、更便宜的模型（如 GPT-3.5-turbo 而不是 GPT-4）。
• 限制与兜底：为 Agent 设置严格的max_iterations和max_execution_time。为 RAG 检索设置超时和重试机制。

6.4 部署与扩展

• 封装为 API 服务：使用 FastAPI 或 Flask 将你的 LangChain 应用封装成 REST API 或 WebSocket 服务。
• 容器化：使用 Docker 将应用及其依赖（Python 环境、向量数据库）打包，确保环境一致性。
• 向量数据库独立部署：生产环境不要用 Chroma 的本地模式。将向量数据库（如 Qdrant, Weaviate）作为独立服务部署，保证可扩展性和可靠性。
• 监控与告警：监控 API 的响应时间、错误率、Token 消耗。设置告警，在服务异常或成本异常时及时通知。

6.5 测试与评估

• 单元测试：测试单个组件，如文档加载器、文本分割器、检索器。
• 集成测试：测试完整的 RAG 链或 Agent 流程，使用固定的输入，验证输出是否符合预期。
• 端到端评估：定期用一批真实用户问题测试整个系统，评估答案的准确性、相关性和有用性。这需要人工或利用强模型（如 GPT-4）进行评判。

7. 常见问题排查清单

当你遇到问题时，按以下顺序排查，可以解决大部分情况：

1. 模型调用失败：
   • 检查 API Key 或本地模型服务地址是否正确。
   • 用curl或requests直接调用模型服务，确认其本身是否正常。
   • 检查网络连接和防火墙设置。
2. RAG 检索结果差：
   • 检查文本分割是否合理。打印出前几个chunk看看内容是否连贯。
   • 检查嵌入模型是否适合你的文本语言。尝试换一个嵌入模型。
   • 检查检索数量k是否合适。太小可能遗漏，太大可能引入噪声。
   • 检查向量数据库是否成功写入了数据。查看持久化目录的文件大小。
3. Agent 陷入循环或调用错误工具：
   • 检查工具描述是否清晰准确。
   • 降低 LLM 的temperature（如设为 0），减少随机性。
   • 在 Prompt 中给出更明确的步骤限制指令（如“最多思考三步”）。
   • 开启verbose=True，观察 Agent 的思考过程，看是在哪一步逻辑出了问题。
4. 程序报错AttributeError或ImportError：
   • 这通常是 LangChain 版本问题。V1 和 V0.x 版本 API 变化很大。确认你安装的是langchain>=0.1.0（即 V1 系列），并查阅对应版本的官方文档。
   • 检查是否安装了正确的集成包（如langchain-openai,langchain-community）。
5. 处理速度慢：
   • 如果是本地模型，检查 GPU 利用率。可能是模型太大或批处理设置不当。
   • 如果是 API 模型，检查是否是网络延迟。考虑使用异步调用。
   • 对于 RAG，检索步骤可能是瓶颈。考虑优化向量索引或使用更快的向量数据库。

学习 LangChain 最好的方式不是记住所有类和方法，而是理解其设计模式：用标准化的组件（Models, Prompts, Chains, Agents, Tools, RAG）去编排和连接。从一个具体的项目需求出发，选择需要的组件，像搭积木一样构建你的应用，并在过程中不断调试和优化。当你熟悉了这种模式，就能快速地将任何 AI 想法转化为可运行的代码。