这次我们来看一个关于 LangChain 大模型应用开发的系统性实战教程。这个教程的核心目标非常明确不是空谈概念而是手把手教你从零开始构建能够真正解决企业级问题的 RAG检索增强生成系统和 Agent智能体应用。对于想进入大模型应用开发领域或者希望将大模型能力集成到现有业务中的开发者来说这是一个极具实操性的学习路径。教程的重点在于“实战”和“就业”。它假设你具备基础的 Python 编程能力然后带你一步步打通从环境搭建、核心概念理解、到项目架构设计、代码实现、效果优化的全链路。你会学到如何让大模型“读懂”你的私有数据RAG以及如何让大模型“使用工具”完成复杂任务Agent。学完之后你将有能力独立设计和开发一个具备实用价值的大模型应用原型。本文将以这个教程为蓝本为你拆解其中的核心模块、技术选型、实战步骤以及避坑指南。我们将重点关注以下几个实操环节如何搭建一个可运行的本地大模型环境例如使用 Ollama如何利用 LangChain 框架快速构建 RAG 流水线如何设计并实现一个能调用外部 API 或工具的 Agent以及如何将这些组件整合成一个完整的项目。无论你是想个人学习还是为团队技术选型做准备这篇文章都能提供清晰的路线图和可落地的代码示例。1. 核心能力速览在深入细节之前我们先通过一个表格快速了解通过本教程你将掌握的核心能力、所需的技术栈以及最终能构建出的项目形态。能力项说明与目标核心框架LangChain当前最主流的大模型应用开发框架用于编排提示词、模型、记忆、工具链等组件。关键技术RAG (检索增强生成)解决大模型知识陈旧、幻觉问题让其能基于私有知识库回答问题。Agent (智能体)让大模型具备推理和工具调用能力可完成搜索、计算、数据查询等复杂任务。大模型接入支持多种模型接口包括 OpenAI API、国内大模型 API如智谱、讯飞、以及本地部署模型如通过 Ollama 运行的 Llama、Qwen 等。开发语言Python全程使用 Python 进行开发需要熟悉基本语法和虚拟环境管理。向量数据库教程通常会涉及ChromaDB或FAISS等轻量级向量数据库用于存储和检索文档嵌入。项目产出可运行的企业级应用原型例如智能客服助手、内部知识库问答系统、自动化数据分析 Agent 等。硬件门槛开发阶段普通 CPU/GPU 电脑即可。若使用本地大模型则需要根据模型大小准备足够内存如 7B 模型约需 8GB 内存。生产部署需根据并发量评估。学习成果掌握从零搭建、调试、优化一个大模型应用的完整流程具备解决实际业务需求的能力。2. 适用场景与使用边界学习 LangChain 并构建 RAG 与 Agent 系统主要面向以下几类场景和开发者适用场景企业内部知识库问答将公司内部的文档、手册、报告等非结构化数据构建成知识库员工可以通过自然语言快速查询例如“我们公司今年的Q3市场策略是什么”。智能客服与助手基于产品文档和客服历史记录构建能准确回答用户问题的客服机器人减轻人工压力。自动化流程Agent创建能自动执行任务的智能体例如根据邮件内容自动创建工单、监控数据异常并生成报告、从网页抓取信息并整理成表格等。个性化内容生成结合用户画像和特定领域资料生成个性化的营销文案、产品描述或学习建议。代码辅助与解释构建能理解项目代码库的助手用于代码搜索、功能解释和生成单元测试。适合的开发者有一定 Python 基础希望切入 AI 应用开发领域的工程师。后端/全栈开发需要为大模型能力设计稳定、可扩展的接口和服务。数据工程师/分析师希望用自然语言交互的方式查询和分析数据。产品经理或业务人员想快速验证大模型解决特定业务问题的可行性原型。使用边界与注意事项并非银弹RAG 能缓解幻觉但不能100%杜绝Agent 能调用工具但复杂逻辑的规划和纠错能力仍有局限。系统设计需包含人工审核或回退机制。数据安全与隐私如果处理企业内部敏感数据务必确保整个流水线数据预处理、嵌入、存储、推理部署在可控的私有环境中慎用第三方云服务。成本与性能使用商用 API 需考虑 token 消耗成本使用本地模型需权衡响应速度、硬件成本和模型效果。需要进行充分的压力测试和性能评估。版权与合规为 RAG 系统灌入的数据必须确保拥有合法使用权。Agent 调用的外部工具或 API 也需遵守其服务条款。3. 环境准备与前置条件开始实战之前需要准备好开发环境。以下是基于 Python 生态的通用准备清单具体版本可能因教程使用的库而略有差异。基础环境操作系统Windows 10/11, macOS, 或 Linux (推荐 Ubuntu)。本文示例以 Linux/macOS 命令为主Windows 用户可使用 WSL2 或 Git Bash。Python版本 3.8 或 3.9LangChain 对 3.10 也支持良好。建议使用conda或venv创建独立的虚拟环境。包管理工具pip最新版。核心工具安装创建并激活虚拟环境强烈推荐# 使用 conda conda create -n langchain-env python3.9 conda activate langchain-env # 或使用 venv python -m venv langchain-env source langchain-env/bin/activate # Linux/macOS # langchain-env\Scripts\activate # Windows安装 LangChain 及相关核心库pip install langchain langchain-communitylangchain是核心框架langchain-community包含了许多第三方集成工具。安装嵌入模型和向量数据库库# 安装 OpenAI 嵌入库如果使用 OpenAI 的 embedding 模型 pip install openai # 或安装 sentence-transformers 库用于本地嵌入模型 pip install sentence-transformers # 安装向量数据库 Chroma轻量易于上手 pip install chromadb # 或安装 FAISS (Facebook AI Similarity Search) pip install faiss-cpu # CPU 版本 # pip install faiss-gpu # GPU 版本如需加速安装文本加载与分割库pip install pypdf # 用于读取PDF pip install python-docx # 用于读取Word pip install unstructured # 用于解析多种格式文档 pip install tiktoken # 用于文本分词OpenAI 模型需要大模型接入准备选项A使用云端 API如 OpenAI需要准备相应的 API Key并设置环境变量。export OPENAI_API_KEYyour-api-key-here # Linux/macOS # set OPENAI_API_KEYyour-api-key-here # Windows CMD选项B使用本地模型如通过 Ollama需要先安装并运行 Ollama。# 前往 Ollama 官网下载安装 # 启动 Ollama 服务后拉取一个模型例如 Llama 3.1 ollama pull llama3.1:8b # 然后在 Python 中通过 langchain_community.llms 调用4. 项目一构建你的第一个 RAG 系统RAG 系统的核心流程是加载文档 - 分割文本 - 向量化 - 存储 - 检索 - 增强提示 - 生成答案。下面我们一步步实现一个最简单的本地知识库问答系统。4.1 文档加载与处理假设我们有一个knowledge_base.pdf文件。首先需要将其加载并分割成适合处理的文本片段chunks。from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter # 1. 加载PDF文档 loader PyPDFLoader(./knowledge_base.pdf) documents loader.load() # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个 chunk 的最大字符数 chunk_overlap50, # chunk 之间的重叠字符数保持上下文连贯 separators[\n\n, \n, 。, , , , , ] # 分割符优先级 ) chunks text_splitter.split_documents(documents) print(f原始文档被分割成了 {len(chunks)} 个文本块。)4.2 向量化与存储接下来我们将文本块转换为向量嵌入并存入向量数据库。from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma # 使用一个开源的句子嵌入模型本地运行无需API Key embeddings_model HuggingFaceEmbeddings( model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ) # 创建向量数据库并将 chunks 向量化后存入 vectorstore Chroma.from_documents( documentschunks, embeddingembeddings_model, persist_directory./chroma_db # 指定持久化目录 ) print(向量数据库创建并持久化完成。)4.3 检索与问答链现在我们可以基于这个向量数据库进行检索并将检索到的相关文档作为上下文交给大模型生成最终答案。from langchain.chains import RetrievalQA from langchain_community.llms import Ollama # 1. 初始化本地大模型通过 Ollama llm Ollama(modelllama3.1:8b, temperature0.1) # temperature 控制创造性 # 2. 从磁盘加载已创建的向量数据库 vectorstore Chroma( persist_directory./chroma_db, embedding_functionembeddings_model ) # 3. 将向量数据库转换为一个检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 每次检索最相关的3个片段 # 4. 创建检索问答链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 将检索到的文档“塞”进提示词 retrieverretriever, return_source_documentsTrue # 返回参考来源 ) # 5. 进行提问 question “我们公司的主要产品是什么” result qa_chain.invoke({query: question}) print(f问题{question}) print(f答案{result[result]}) print(f参考来源) for doc in result[source_documents]: print(f - {doc.metadata.get(source, N/A)} (页码{doc.metadata.get(page, N/A)}))至此一个最基础的 RAG 系统就搭建完成了。你可以通过更换文档、调整 chunk 大小、尝试不同的嵌入模型和 LLM 来优化效果。5. 项目二打造一个能调用工具的 AgentAgent 的核心在于让 LLM 学会“思考”和“使用工具”。我们将构建一个能查询天气和进行简单计算的智能体。5.1 定义工具首先我们需要定义 Agent 可以使用的工具。每个工具都是一个函数并配以清晰的描述帮助 LLM 理解何时使用它。from langchain.agents import tool import requests import json tool def get_weather(city: str) - str: 根据城市名称查询当前的天气情况。 # 这里使用一个模拟的天气API实际项目中请替换为真实API # 例如https://api.openweathermap.org/data/2.5/weather?q{city}appid{your_key} weather_data { Beijing: 晴25°C, Shanghai: 多云28°C, Guangzhou: 雷阵雨30°C } return weather_data.get(city, f抱歉未找到{city}的天气信息。) tool def calculator(expression: str) - str: 计算一个数学表达式的值。支持加减乘除和括号。 try: # 警告使用 eval 有安全风险仅用于演示。生产环境应使用安全计算库如 ast.literal_eval 或自定义解析器。 result eval(expression) return f{expression} {result} except Exception as e: return f计算错误{e}5.2 创建 Agent 并为其配备工具我们将使用 LangChain 的create_react_agent来构建一个采用 ReAct 推理框架的智能体。from langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_community.llms import Ollama # 1. 拉取一个预设的 ReAct 提示词模板 prompt hub.pull(hwchase17/react) # 2. 初始化 LLM llm Ollama(modelllama3.1:8b, temperature0) # 3. 定义工具列表 tools [get_weather, calculator] # 4. 创建 Agent agent create_react_agent(llm, tools, prompt) # 5. 创建 Agent 执行器它负责运行 Agent 的思考-行动循环 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 打印详细的思考过程便于调试 handle_parsing_errorsTrue # 优雅地处理解析错误 )5.3 运行 Agent 进行测试现在我们可以向 Agent 提出需要它使用工具才能解决的问题。# 测试场景1需要计算 result1 agent_executor.invoke({input: “请计算 (15 7) * 3 的值是多少”}) print(result1[output]) # 测试场景2需要查询信息 result2 agent_executor.invoke({input: “北京和上海的天气怎么样”}) print(result2[output]) # 测试场景3混合任务 result3 agent_executor.invoke({input: “如果北京气温25度上海气温28度两地的平均气温是多少”}) print(result3[output])当verboseTrue时你会在控制台看到类似以下的思考过程这对于调试 Agent 的行为至关重要 Entering new AgentExecutor chain... 我需要计算两地的平均气温。首先我需要知道北京和上海的气温。我可以使用天气查询工具。 Action: get_weather Action Input: {city: 北京} Observation: 晴25°C Thought: 我得到了北京的气温是25°C。现在需要上海的气温。 Action: get_weather Action Input: {city: 上海} Observation: 多云28°C Thought: 现在我有了两个温度25 和 28。我需要计算它们的平均值。我可以使用计算器工具。 Action: calculator Action Input: (25 28) / 2 Observation: (25 28) / 2 26.5 Thought: 我计算出了平均气温是26.5°C。 Action: 最终答案 Action Input: 北京和上海的平均气温是26.5°C。 Finished chain.通过这个例子你可以看到 Agent 如何自主规划、调用工具并整合信息来解决问题。6. 进阶整合构建企业级应用原型将 RAG 和 Agent 结合起来可以构建更强大的应用。例如一个企业内部助手既能回答基于知识库的问题又能执行预定任务如查询数据库、发送邮件。6.1 架构设计一个简单的整合架构如下输入解析接收用户问题。路由判断问题类型是知识库问答还是需要执行任务。RAG 流程如果是知识类问题走 RAG 流程从向量库检索并生成答案。Agent 流程如果是任务型问题交给 Agent由其调用相应工具处理。响应合成将结果返回给用户。6.2 代码示例基于 LLM 的路由器我们可以用另一个 LLM 来判断用户意图实现简单的路由。from langchain.prompts import ChatPromptTemplate from langchain.schema.output_parser import StrOutputParser # 定义路由提示词 route_prompt ChatPromptTemplate.from_messages([ (system, “你是一个智能路由助手。请根据用户的问题判断其意图类别只输出‘knowledge’或‘action’。 - 如果问题是关于公司制度、产品信息、历史文档等需要从知识库查找的输出‘knowledge’。 - 如果问题是要求执行一个具体操作如计算、查询、通知等输出‘action’。 用户问题{question}”), ]) # 创建路由链 route_chain route_prompt | llm | StrOutputParser() # 模拟用户输入 user_questions [ “我们公司的年假制度是怎样的”, “帮我计算一下项目预算硬件成本5万人力成本每月2万共6个月。” ] for q in user_questions: decision route_chain.invoke({question: q}) print(f问题{q} - 路由决策{decision}) if knowledge in decision.lower(): # 调用前面构建的 qa_chain rag_result qa_chain.invoke({query: q}) print(f [RAG回答]{rag_result[result][:100]}...) # 截断显示 elif action in decision.lower(): # 调用前面构建的 agent_executor agent_result agent_executor.invoke({input: q}) print(f [Agent回答]{agent_result[output]}) else: print(f [无法处理]将转接至人工客服。)6.3 添加记忆与对话状态为了让助手能进行多轮对话需要引入记忆Memory功能。LangChain 提供了多种记忆组件。from langchain.memory import ConversationBufferMemory from langchain.chains import ConversationChain # 为对话链添加记忆 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) conversation_chain ConversationChain(llmllm, memorymemory, verboseTrue) print(conversation_chain.invoke({input: “你好我叫张三。”})[response]) print(conversation_chain.invoke({input: “你还记得我的名字吗”})[response])这样你的应用就具备了上下文对话的能力可以更自然地与用户交互。7. 性能优化与最佳实践构建可用的原型只是第一步要让其达到“企业级”还需要关注性能、稳定性和可维护性。1. 文本分割策略优化Chunk Size太小会丢失上下文太大会降低检索精度并增加 LLM 处理负担。通常 500-1000 字符是一个不错的起点需根据文档特点调整。分割依据对于技术文档按章节 (\n##) 分割可能比按字符数更好。可以结合使用RecursiveCharacterTextSplitter和MarkdownHeaderTextSplitter。2. 检索优化多路检索 (Multi-Query Retrieval)让 LLM 根据原始问题生成多个相关问题并行检索然后合并结果提高召回率。重排序 (Re-ranking)初步检索出 N 个片段后使用一个更精细的交叉编码器模型对它们进行重排序将最相关的放在前面提升精度。元数据过滤在存储时为每个 chunk 添加元数据如文档来源、章节、日期。检索时可以添加过滤器例如“只检索 2023 年之后的财务报告”。3. Agent 稳定性提升工具描述清晰工具函数的docstring必须精确描述其功能和输入格式这是 LLM 能否正确调用的关键。限制工具集不要一次性给 Agent 太多工具这会导致其困惑。可以根据任务场景动态加载不同的工具包。设置超时与重试对于调用外部 API 的工具必须设置超时和重试机制避免整个 Agent 进程卡死。验证工具输出在工具返回结果给 LLM 前可以加入一层校验确保输出格式正确、内容合理。4. 系统监控与日志记录所有交互记录用户的输入、系统的中间步骤检索到的文档、调用的工具、LLM 的思考过程以及最终输出。这对于调试和效果分析至关重要。监控关键指标平均响应时间、Token 消耗量、检索命中率、工具调用成功率、用户满意度如有反馈机制。实现版本管理对提示词模板、数据索引、模型版本进行管理任何更改都应可追溯、可回滚。8. 部署与上线考量当原型验证通过准备部署时需要考虑以下方面1. 服务化使用FastAPI或Flask将你的应用封装成 RESTful API 服务。为 RAG 和 Agent 分别设计清晰的端点例如/rag/query和/agent/run。2. 异步处理对于耗时的操作如文档解析、向量化、复杂 Agent 任务使用asyncio或任务队列如Celery进行异步处理避免阻塞 HTTP 请求。3. 可扩展性向量数据库生产环境可能需从单机 Chroma 升级到支持分布式的向量数据库如Weaviate、Qdrant或Pinecone云服务。缓存对常见的查询结果进行缓存例如使用Redis可以大幅降低响应时间和 API 调用成本。负载均衡如果使用本地模型可能需要部署多个模型实例并通过负载均衡器来分配请求。4. 安全与权限API 认证为你的服务接口添加 API Key 或 JWT 认证。输入输出过滤对用户输入进行清洗防止提示词注入攻击对模型输出进行内容安全过滤。数据访问控制在 RAG 系统中实现基于用户或角色的文档访问权限控制确保用户只能检索其有权访问的内容。9. 常见问题与排查方法在开发和部署过程中你可能会遇到以下典型问题问题现象可能原因排查方式解决方案RAG 回答不相关或胡言乱语1. 检索到的文档不相关。2. chunk 大小不合适上下文断裂。3. LLM 的提示词未将上下文与问题很好结合。1. 检查检索环节打印出每次检索到的source_documents内容看是否与问题匹配。2. 调整chunk_size和chunk_overlap。3. 检查并优化RetrievalQA的chain_type和提示词。1. 优化检索器尝试search_typemmr最大边际相关性或增加k值。2. 使用重排序模型。3. 在提示词中明确要求“仅根据上下文回答”。Agent 不调用工具或调用错误1. 工具描述 (docstring) 不清晰。2. LLM 能力不足无法理解任务。3. 工具输入参数解析失败。1. 开启verboseTrue观察 Agent 的思考链看它在哪一步出错。2. 检查工具函数的输入输出是否符合 LangChaintool装饰器的要求。1. 重写工具描述确保简洁、准确。2. 尝试更强的 LLM如 GPT-4。3. 使用handle_parsing_errorsTrue并添加错误处理逻辑。本地模型响应速度极慢1. 模型太大硬件资源不足。2. 未使用 GPU 加速或 GPU 内存不足。3. 推理参数如max_tokens设置过高。1. 使用nvidia-smi(Linux) 或任务管理器观察 GPU 利用率和内存占用。2. 检查 Ollama 或 transformers 是否配置了正确的 GPU 后端。1. 换用更小的模型如 7B 参数。2. 确保安装了pyTorch的 CUDA 版本。3. 调整max_tokens、启用流式输出以提升感知速度。向量数据库检索为空1. 文档未成功向量化或存入。2. 检索时使用的嵌入模型与存入时不同。3. 查询文本与文档语义差异太大。1. 检查chroma_db目录下是否有文件生成。2. 确认embedding_function在存入和读取时是同一个实例。3. 尝试用更简单的关键词查询。1. 重新运行from_documents过程确保无报错。2. 使用完全相同的嵌入模型配置。3. 考虑对查询进行扩展或重写。服务部署后内存持续增长内存泄漏常见于未正确管理 LLM 实例、向量数据库连接或大对象。使用内存分析工具如memory_profiler定位增长点。1. 确保在 Web 框架如 FastAPI中使用单例模式管理 LLM 和向量库连接。2. 定期重启工作进程如果使用多进程部署。10. 总结与下一步行动指南通过本教程的拆解你应该对如何使用 LangChain 构建企业级 RAG 和 Agent 系统有了一个从理论到实战的完整认知。这条路线的价值在于它提供了一套标准化、可组装的框架让你能快速将大模型能力转化为解决实际业务问题的应用。最值得尝试的起点环境跑通在你的电脑上按照第 3、4 节的步骤成功运行起第一个 RAG 问答程序。这是建立信心的关键一步。更换数据源不要只停留在 PDF尝试加载 Markdown、Word、Excel 甚至数据库数据体验不同加载器的使用。自定义工具为你最熟悉的领域比如查询公司内部 API、操作 JIRA 任务编写一个简单的 Agent 工具并让 Agent 成功调用它。最容易踩的坑环境依赖Python 包版本冲突是常态务必使用虚拟环境并仔细阅读官方文档的安装要求。模型选择不要盲目追求大参数模型。对于特定垂直领域一个 7B 或 13B 的经过精调的模型效果可能远好于通用的 70B 模型。提示词工程RAG 和 Agent 的效果严重依赖提示词。多花时间迭代和测试你的提示词这是性价比最高的优化手段。后续深入方向探索 LangGraph当你的 Agent 需要处理更复杂、有状态的工作流时如审批流程、多步骤数据分析LangChain 的 LangGraph 库提供了基于图的可视化编排能力是进阶的必学内容。评估与迭代建立评估体系用量化指标如答案准确性、相关性来驱动你的系统迭代而不是凭感觉。关注生态LangChain 生态发展极快新的工具、集成和最佳实践不断涌现。关注其官方文档、博客和社区如 Discord、GitHub保持学习。掌握 LangChain 这套“组合拳”意味着你不仅学会了使用几个工具更掌握了一种构建复杂 AI 应用的方法论。从今天开始选择一个你手头最需要被自动化的任务或最想被解答的知识库动手构建你的第一个智能体吧。