企业官网建设流程全解析

这类教程最怕的就是堆砌概念，把一堆听起来高大上的词（RAG、Agent、Langchain）扔给你，却不告诉你它们在实际项目里是怎么串起来的，更不告诉你一个普通开发者从零开始到底该怎么走。

我花了不少时间梳理了从2024年到2026年初这段时间里，AI Agent开发领域真正沉淀下来的、能落地的实践路径。这篇文章不讲虚的，就围绕一个核心目标：让你能基于现有开源工具，搭建一个能跑起来、能解决实际问题的AI Agent系统，并且知道每一步为什么这么做，以及出了问题该往哪看。

特别说明一下，这里的“双非”不是指学历，而是指非顶尖实验室、非大厂核心团队的普通开发者或小团队。我们的资源有限，不能盲目追新论文或烧钱的闭源大模型，必须把每一分算力和时间都花在刀刃上。所以，整个指南的基调是：务实、可复现、优先选择成熟稳定的方案。

下面，我会按照一个真实项目的推进顺序，把RAG、Agent、Langchain这些组件拆开揉碎了讲，重点不是背概念，而是搞清楚它们在一个系统里各自扮演什么角色，以及如何组合。

1. 先别急着学框架，搞明白你要解决什么问题

很多教程一上来就让你装Langchain，跑Hello World，但你很可能不知道为什么要用它。我们先退一步，想清楚AI Agent到底是什么，以及RAG和Agent是什么关系。

1.1 AI Agent的核心：感知、规划、执行、学习

你可以把一个AI Agent想象成一个虚拟的、有一定自主能力的“员工”。给它一个目标（比如“帮我分析这份财报”），它不会只生成一段话就结束。它会：

1. 感知：理解你的指令和当前环境（比如能访问哪些工具、数据库）。
2. 规划：拆解目标，决定先做什么、后做什么（比如先查公司历史数据，再计算财务比率，最后生成总结）。
3. 执行：调用具体的工具去完成任务（调用搜索API、运行Python代码、查询数据库）。
4. 学习（可选）：根据结果调整后续行动。

关键理解：一个只会和你聊天的ChatBot不是Agent，它只有“感知”和简单的“执行”（生成文本）。Agent必须有“规划”和调用外部工具“执行”的能力。

1.2 RAG是Agent的“长期记忆”和“知识库”

RAG（检索增强生成）解决的是大模型“知识截止”和“胡言乱语”的问题。它让模型在回答前，先从你提供的知识库（比如公司文档、产品手册）里检索相关片段，然后基于这些确凿的依据来生成答案。

在Agent系统里，RAG模块通常扮演一个“专用工具”的角色。当Agent规划发现需要查询特定知识时，就会调用这个RAG工具。例如，Agent接到任务“回答客户关于产品A的保修政策”，它的规划可能是：1) 调用RAG工具，查询“产品A 保修”；2) 将检索到的政策文本交给大模型；3) 让大模型生成用户友好的回答。

所以，RAG和Agent不是二选一，而是组合关系。RAG让Agent变得更专业、更可靠。

1.3 Langchain/LangGraph是“胶水”和“调度中心”

这是最容易混淆的地方。Langchain不是一个具体的AI模型，而是一个框架。它帮你把大模型（OpenAI、通义千问、DeepSeek等）、各种工具（搜索引擎、计算器、RAG系统）、记忆模块等“零件”方便地组装在一起，并定义它们之间协作的流程。

• Langchain：更侧重于构建单一的、链式（Chain）的工作流。比如“用户提问 -> 检索知识 -> 生成回答”这样一个固定管道。它适合逻辑相对固定的场景。
• LangGraph：是Langchain团队推出的，用于构建有状态、可循环、可分支的复杂Agent。它用“图”的概念来定义Agent的行为，节点是执行步骤（或工具），边是步骤之间的流转条件。这让Agent能处理“尝试方案A，如果失败则换方案B”这类需要决策和循环的任务。

对于入门和大多数应用，Langchain就足够了。当你需要Agent能处理非常复杂的、多步骤的、有依赖关系的任务时，再研究LangGraph。

现在你明白了，我们要搭建的系统大概是：用Langchain作为框架，把大模型、RAG工具、以及其他API工具组装成一个能自主规划并执行任务的AI Agent。

2. 环境准备与核心工具选型：走稳定路线，别追新

对于资源有限的我们，稳定压倒一切。下面是我验证过、社区活跃、文档相对友好的组合。

2.1 基础运行环境

• Python：版本3.9或3.10。3.11+也行，但有些老版本库可能有兼容性问题，3.9/3.10最稳妥。
• 包管理：强烈推荐用conda或venv创建独立的虚拟环境，避免包冲突。
• 代码编辑器：VS Code，装上Python和Jupyter插件。

2.2 大模型选择：API优先，本地为辅

核心原则：初期开发和验证，用云API；考虑长期成本、数据隐私或离线需求，再评估本地模型。

1. 云API（推荐入门）：

   • OpenAI GPT系列：生态最好，Langchain支持最完善，效果稳定。缺点是可能需要处理网络问题，且有使用成本。
   • 国内大厂API：阿里云通义、百度文心、讯飞星火、智谱GLM。优势是网络延迟低，符合数据合规要求。需要在Langchain中查找对应的集成包或自己封装。
   • 开源模型API服务：像DeepSeek、Qwen也提供了API。成本可能更低。
   • 怎么选：第一个项目，建议先用OpenAI的GPT-3.5-turbo。它足够便宜且智能，能让你快速验证整个Agent流程。别一上来就追求GPT-4。

2. 本地模型（谨慎选择）：

   • 何时考虑：数据极度敏感不能出域、长期调用量巨大、网络不稳定。
   • 挑战：需要足够的GPU显存（至少8GB，推荐16GB+），需要处理模型加载、推理加速（vLLM, Ollama）、tokenizer对齐等一系列问题。
   • 入门选择：可以先用Ollama在本地跑一个轻量模型（如llama3.2:1b,qwen2.5:7b）来体验流程，但生产级部署复杂得多。

行动建议：在项目根目录创建一个.env文件，存放你的API密钥，用python-dotenv包来读取。这是安全最佳实践。

# .env 文件内容 OPENAI_API_KEY=sk-your-key-here

2.3 Langchain：安装与版本控制

安装核心包即可。注意版本，不同版本API差异可能很大。

pip install langchain langchain-community langchain-openai

• langchain: 核心框架。
• langchain-community: 大量第三方工具和集成的集合。
• langchain-openai: OpenAI模型的官方集成。

重要：Langchain更新很快，教程容易过时。以官方文档为准。如果看到教程里用from langchain.llms import OpenAI这种旧写法，现在更推荐用from langchain_openai import ChatOpenAI。

2.4 向量数据库与RAG核心件

RAG的核心是：把文本切成块 -> 转换成向量（嵌入） -> 存到向量数据库 -> 检索时查询相似向量。

• 文本切分：langchain-text-splitters。负责把长文档切成语义连贯的小段。
• 嵌入模型：把文本块转换成向量。同样分API和本地。
  • API：OpenAIEmbeddings(text-embedding-3-small 性价比高)。langchain-openai包里包含。
  • 本地：sentence-transformers库，模型如all-MiniLM-L6-v2。效果不错，免费，但需要本地计算资源。
• 向量数据库：入门首选Chroma。轻量、无需外部服务、纯Python、和Langchain集成好。

  pip install chromadb

2.5 其他可能用到的工具

• 工具调用：langchain.tools模块里有很多预设工具（如搜索、计算）。你也可以用@tool装饰器自定义任何Python函数为工具。
• Agent执行器：langchain.agents模块，负责驱动Agent的规划-执行循环。
• 记忆：langchain.memory，让Agent能记住对话历史。简单场景用ConversationBufferMemory。

环境准备好了，我们开始从最简单的环节搭建：RAG知识库。

3. 第一步：构建一个稳定可用的RAG知识库

RAG是Agent的基石，这一步必须扎实。我们目标是：把一份PDF产品手册，变成一个可以被Agent查询的知识工具。

3.1 文档加载与切分：别小看这一步

假设你的产品手册是product_manual.pdf。

from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter # 1. 加载文档 loader = PyPDFLoader("./product_manual.pdf") documents = loader.load() # 2. 切分文档 text_splitter = RecursiveCharacterTextSplitter( chunk_size=500, # 每个块大约500字符 chunk_overlap=50, # 块之间重叠50字符，避免语义被割裂 length_function=len, separators=["\n\n", "\n", "。", "，", " ", ""] # 中文环境可以调整分隔符 ) docs = text_splitter.split_documents(documents) print(f"原始文档被切分成 {len(docs)} 个块")

关键参数解析：

• chunk_size：最重要。太小则信息碎片化，检索可能丢失上下文；太大则可能包含无关信息，且嵌入效果下降。500-1000是通用起点，需根据你的文档内容（是技术文档还是小说）调整。
• chunk_overlap：防止一个句子或关键概念被切成两半。设置chunk_size的10%-20%。
• separators：对于中文，确保有句号、逗号等，让切分更符合语言习惯。

3.2 向量化与存储：连接Chroma

from langchain_openai import OpenAIEmbeddings from langchain.vectorstores import Chroma # 使用OpenAI的嵌入模型（需要API Key） embeddings = OpenAIEmbeddings(model="text-embedding-3-small") # 将切分好的文档转换为向量，并存入Chroma # persist_directory 指定向量数据库持久化到磁盘的路径 vectorstore = Chroma.from_documents( documents=docs, embedding=embeddings, persist_directory="./chroma_db" ) vectorstore.persist() # 显式保存到磁盘

注意：

1. 第一次运行会调用OpenAI嵌入API，将每个文本块转换为向量，会产生费用（但很低）。
2. persist_directory会创建一个本地文件夹存储向量数据。下次启动可以直接加载，无需重新嵌入。
3. 如果使用本地嵌入模型（如sentence-transformers），则无需API Key，但速度取决于你的CPU/GPU。

3.3 构建检索链：完成RAG闭环

现在，我们可以测试这个知识库了。

# 首先，加载已持久化的向量数据库（如果已经存在） vectorstore = Chroma(persist_directory="./chroma_db", embedding_function=embeddings) # 将其转换为一个检索器（Retriever） retriever = vectorstore.as_retriever( search_type="similarity", # 相似度搜索 search_kwargs={"k": 3} # 返回最相似的3个文本块 ) # 测试检索 query = "产品A的保修期是多久？" relevant_docs = retriever.invoke(query) # Langchain新版本推荐用 invoke for i, doc in enumerate(relevant_docs): print(f"--- 相关片段 {i+1} ---") print(doc.page_content[:200]) # 打印前200字符 print()

如果这一步能返回与“保修期”相关的文本片段，恭喜你，RAG知识库的核心功能就完成了。它已经是一个可以独立使用的“知识查询工具”了。

4. 第二步：打造你的第一个AI Agent

有了RAG工具，我们现在用Langchain把它和LLM组装成一个能使用工具的Agent。

4.1 定义工具：让Agent有“手”和“脚”

工具就是Agent可以调用的函数。我们先定义两个工具：一个是我们刚建的RAG知识库查询工具，另一个是一个简单的计算器工具。

from langchain.tools import tool from langchain.agents import AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain import hub # 工具1：RAG知识库查询工具 @tool def search_product_knowledge(query: str) -> str: """当用户询问关于产品特性、规格、保修、价格等信息时，使用此工具从产品知识库中查找答案。""" # 使用上一节创建的检索器 relevant_docs = retriever.invoke(query) if not relevant_docs: return "在知识库中未找到相关信息。" # 简单地将检索到的前3个片段内容拼接返回 return "\n\n".join([doc.page_content for doc in relevant_docs[:3]]) # 工具2：计算器工具（示例） @tool def calculator(expression: str) -> str: """执行数学计算。输入一个数学表达式，如 '2 + 3 * 4'，返回计算结果。""" try: # 警告：使用eval有安全风险，仅作演示。生产环境应用安全库如`numexpr` result = eval(expression) return str(result) except Exception as e: return f"计算错误：{e}" # 将工具放入列表 tools = [search_product_knowledge, calculator]

4.2 创建Agent：赋予模型“大脑”和“规划”能力

我们将使用经典的ReAct框架，它让模型以“思考（Reason）- 行动（Act）”的循环来工作。

# 1. 初始化大语言模型 llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0, openai_api_key=你的API密钥) # temperature=0 使输出更确定，适合工具调用 # 2. 从Langchain Hub拉取一个预设的ReAct提示词模板 # 这个模板会指导LLM如何格式化它的“思考”和“行动” prompt = hub.pull("hwchase17/react") # 3. 使用工具和LLM创建Agent agent = create_react_agent(llm, tools, prompt) # 4. 创建Agent执行器，它负责运行Agent的循环 agent_executor = AgentExecutor( agent=agent, tools=tools, verbose=True, # 设为True，可以看到Agent的思考过程，调试非常有用！ handle_parsing_errors=True, # 当模型输出格式错误时，尝试修复 max_iterations=5, # 限制最大循环次数，防止死循环 early_stopping_method="generate" # 当模型认为最终答案已得出时停止 )

4.3 运行与调试：看Agent如何“思考”

现在，让我们问一个需要结合知识和计算的问题。

question = "产品A的原价是2999元，现在有85折优惠，请问优惠后价格是多少？另外，它的保修政策是怎样的？" result = agent_executor.invoke({"input": question}) print(result["output"])

将verbose=True后，你会在控制台看到类似这样的输出：

> 进入新的Agent执行链... 思考：用户问了两个问题：计算折扣价和查询保修政策。我需要先回答哪个？问题没有明确顺序，我可以先计算价格，因为它是一个独立的计算任务，然后再查询保修政策。 行动：使用工具[calculator]计算折扣价。 行动输入：2999 * 0.85 观察：2549.15 思考：我得到了折扣价2549.15元。现在需要查询产品A的保修政策。 行动：使用工具[search_product_knowledge]查询保修政策。 行动输入：产品A 保修政策 观察：（这里会输出从知识库检索到的关于保修的文本片段） 思考：我已经获得了价格和保修信息，可以组织最终答案了。 最终答案：产品A优惠后的价格为2549.15元。关于保修政策，根据知识库：...（总结检索到的信息）...

这就是一个AI Agent在工作！它自动规划了步骤：先调用计算器，再调用知识库，最后综合信息生成回答。

常见调试点：

1. 工具描述不清：@tool装饰器下的函数文档字符串"""..."""非常重要！LLM就是靠这个描述来决定是否以及何时调用这个工具。务必写清楚工具的用途和输入格式。
2. 模型不调用工具：检查提示词（prompt）是否合适，工具描述是否清晰，或者尝试降低temperature。
3. 无限循环：设置max_iterations（如5-10次）。如果Agent不停调用工具而不给出最终答案，可能是工具返回的结果无法让它满足，需要检查工具逻辑或提示词。

5. 从Demo到应用落地：必须考虑的工程化问题

跑通一个Demo只是开始。要让这个Agent真正能用、敢用，必须解决以下问题。

5.1 记忆与多轮对话

上面的Agent是“失忆”的，每轮对话独立。要让它记住上下文，需要在AgentExecutor中加入记忆。

from langchain.memory import ConversationBufferMemory memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True) # 修改Agent Executor的创建，传入memory agent_executor = AgentExecutor( agent=agent, tools=tools, memory=memory, verbose=True, # ... 其他参数 ) # 调用时使用带记忆的输入 result = agent_executor.invoke({"input": question, "chat_history": []})

这样，后续对话中，chat_history会自动被管理，Agent就能基于之前的对话进行回答。

5.2 处理复杂任务与LangGraph

当任务需要多个步骤，且步骤之间有复杂的依赖或循环时，基础的ReAct Agent可能不够用。例如：“监控服务器日志，如果发现错误A，则执行重启服务；如果发现错误B，则发送告警邮件并等待10分钟再检查。” 这时就需要LangGraph来定义工作流。

# 这是一个概念性示例，展示LangGraph的思维 from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated import operator # 1. 定义状态（State） class AgentState(TypedDict): problem: str analysis: str action_taken: list result: str # 2. 定义节点（函数） def analyze_problem(state: AgentState): # 调用LLM分析问题 return {"analysis": "分析结果..."} def take_action_a(state: AgentState): # 执行操作A return {"action_taken": state["action_taken"] + ["A"], "result": "A完成"} def take_action_b(state: AgentState): # 执行操作B return {"action_taken": state["action_taken"] + ["B"], "result": "B完成"} # 3. 构建图 graph_builder = StateGraph(AgentState) graph_builder.add_node("analyze", analyze_problem) graph_builder.add_node("action_a", take_action_a) graph_builder.add_node("action_b", take_action_b) # 4. 定义边（流转逻辑） graph_builder.set_entry_point("analyze") # 根据分析结果，决定下一步是action_a还是action_b def decide_next_step(state): if "condition_a" in state["analysis"]: return "action_a" else: return "action_b" graph_builder.add_conditional_edges("analyze", decide_next_step) graph_builder.add_edge("action_a", END) graph_builder.add_edge("action_b", END) # 5. 编译并运行图 graph = graph_builder.compile() final_state = graph.invoke({"problem": "初始问题"})

LangGraph让你能清晰地可视化和管理复杂的工作流，适合构建企业级的自动化Agent。

5.3 RAG的优化：提升检索质量

如果你的Agent经常检索不到正确答案，问题可能出在RAG环节：

1. 切分策略不佳：调整chunk_size和chunk_overlap。对于结构化文档（如Markdown），可以使用MarkdownHeaderTextSplitter按标题切分。
2. 检索器配置：
   • search_kwargs={"k": 5}：多返回几个结果，让LLM有更多上下文。
   • search_type="mmr"：使用最大边际相关性排序，在保证相关性的同时增加多样性，避免返回内容雷同的片段。
3. 重排序：在初步检索后，用一个更精细的模型（或交叉编码器）对结果进行重排序，把最相关的排在最前。这能显著提升效果，但会增加延迟和成本。
4. 元数据过滤：在存储向量时，为每个块添加元数据（如来源文件、章节）。检索时可以过滤，例如“只在用户手册中搜索”。

5.4 部署与监控

• Web接口：用FastAPI或Flask将你的agent_executor包装成一个HTTP API。
• 异步处理：对于耗时任务，使用langchain的异步接口或结合Celery等任务队列。
• 日志记录：详细记录每个用户请求、Agent的思考步骤、工具调用和结果。这是排查问题和优化性能的关键。
• 成本监控：如果使用付费API，务必记录每次调用的token消耗，设置预算警报。
• 评估与测试：构建一个测试集，定期运行，监控Agent回答的准确率和工具调用的成功率。

6. 学习路径与求职建议：如何从“会了”到“精通”

如果你跟着做到了这里，你已经有了一个可运行的AI Agent项目原型。但要达到“就业”或独立开发的程度，还需要系统性地加深。

6.1 技术深挖路线图

1. 巩固基础：
   • Python：熟练，特别是异步编程（asyncio）。
   • Langchain核心概念：Model I/O, Chains, Agents, Tools, Memory, Indexes (RAG)。读官方文档，不要只看教程。
2. 深入RAG：
   • 学习更先进的检索技术：HyDE, RAG-Fusion, 父文档检索。
   • 实践不同的向量数据库：Pinecone(云服务)，Weaviate(开源)，Qdrant(开源，性能好)。
   • 了解重排序模型（如bge-reranker）。
3. 掌握高级Agent模式：
   • Plan-and-Execute：先让一个“规划者”LLM制定详细计划，再让一个“执行者”LLM按计划调用工具。适合复杂任务。
   • Multi-Agent：多个Agent协作，如一个负责分析，一个负责执行，一个负责审核。研究CrewAI,AutoGen框架。
   • Tool Learning：如何让Agent更好地学习使用新工具？了解Gorilla等项目。
4. 工程化与架构：
   • 学习如何将Agent部署为微服务。
   • 了解LLM应用开发框架：LangServe(Langchain官方部署工具)，Dify(低代码平台)，FastChat(本地模型服务)。
   • 关注LangGraph，这是构建复杂、有状态工作流的未来方向。

6.2 项目经验积累

• 改造现有Demo：不要满足于跑通。给你的客服Agent加上“查询物流信息”的工具；给你的数据分析Agent加上“自动生成图表”的能力。
• 从头构建一个完整项目：例如“智能个人旅行规划Agent”。它需要：1) RAG（爬取旅行攻略）， 2) 工具（查询天气API、机票比价API）， 3) 记忆（记住用户的预算和偏好）， 4) 规划（生成每日行程）。
• 参与开源项目：在GitHub上找Langchain、CrewAI等相关项目，阅读代码，尝试提交Issue或PR。

6.3 求职准备：技能如何体现

面试官不会只问你概念。准备好：

1. 项目介绍：用STAR法则描述你做的Agent项目。背景、任务、你采取的行动（技术选型、如何解决RAG检索不准、如何设计Agent流程）、结果（准确率、效率提升）。
2. 技术细节：
   • “你如何评估你的RAG系统效果？”（答：构建测试集，计算命中率、答案相关性）
   • “当Agent陷入死循环不返回答案时，你怎么调试？”（答：检查verbose日志，看是工具返回无效导致重复调用，还是提示词指令不清晰；设置max_iterations和early_stopping）
   • “Langchain和LangGraph在你项目中分别解决了什么问题？”
   • “如何降低LLM API的调用成本和延迟？”（答：缓存、对简单任务使用小模型、流式响应、优化提示词减少token）
3. 对生态的了解：能说出除了Langchain外，还有哪些流行的Agent框架（CrewAI, AutoGen），以及它们的优缺点。

这条路没有捷径。从把一个Demo跑通，到能处理真实场景的复杂问题，中间需要大量的调试、优化和学习。最有效的学习方法，就是选定一个你感兴趣的具体问题，然后用这里介绍的技术栈去解决它。每踩一个坑，你对RAG、Agent和Langchain的理解就会深一层。