企业官网建设流程全解析

打开你的浏览器收藏夹，大概率躺着这样的标题：LangChain 入门、LangGraph 实战、Agent 开发、RAG 知识库……收藏的时候信心满满，真的打开 IDE 准备写代码，又开始迷茫：到底先学哪个？项目该从哪下手？为什么照着别人的代码敲还是报错？

这不是你不够努力，而是很多人把学习顺序搞反了。LangChain、LangGraph、Agent、RAG 这四个词并不是并列的新框架，而是一条层层递进的技术链。先理解这条链，再动手写代码，才能真正把技术吃到项目里。这篇文章不打算帮你收藏更多视频，而是给出一条从入门到企业级实战的完整路线，并配上一套能直接跑通的最小示例。

1. 这篇文章真正要解决的问题

先给一个明确判断：LangChain 生态真正降低的，不是“调用大模型”的入门门槛，而是“把大模型能力编排进业务系统”的工程门槛。很多人以为学 LangChain 就是学 API，其实学的是如何组织提示词、如何管理状态、如何接入工具、如何控制流程。

不同阶段的读者，痛点完全不同：

• 刚入门的人，卡在环境配置和第一个调用上，看到的一堆概念术语让大脑过载。
• 已经会调用模型的人，不知道下一步该学什么，总觉得自己是在“调包”。
• 正在做企业项目的开发者，发现本地 Demo 跑得通，一到生产环境就崩，性能、成本、可观测性、权限管理全是问题。

所以这篇文章的重点不是列出所有 API，而是帮你建立一张地图：每个技术解决什么问题、和前后环节怎么衔接、写代码时哪里容易踩坑、生产环境怎么兜底。

读完你能得到两样东西：一条清晰的学习路线，和一套可以直接复制运行的最小代码示例。

2. 四个核心概念：LangChain、LangGraph、Agent、RAG

2.1 LangChain：编排底座

LangChain 可以理解为一个“大模型工具链的粘合层”。没有它，你需要自己写函数去拼接 Prompt、调用模型、解析输出；有了它，这些动作变成了一条标准化管道。

它的核心抽象有几个：

• Model：统一封装不同厂商的大模型接口。
• Prompt Template：把提示词变成可复用的模板，而不是散落在代码里的字符串。
• Output Parser：把模型输出解析成结构化数据，比如 JSON、列表。
• Chain：把 Prompt、Model、Parser 串起来，形成一条可执行的管道。
• Memory：在多次对话中保留历史信息，解决“模型默认无状态”的问题。
• Retriever：从外部知识源检索内容，为 RAG 打基础。

如果只看表面，很容易误以为 LangChain 只是在包装 API。它的真正价值是让你用声明式的方式组合大模型能力，后面接入 RAG、Agent 时，这套抽象能大幅降低代码的耦合度。

2.2 RAG：把私域知识接入大模型

RAG，全称 Retrieval-Augmented Generation，检索增强生成。它在模型回答问题之前，先从外部知识库检索相关文档片段，再把这些片段作为上下文传给模型。

为什么需要 RAG？大模型的知识是训练时固化的，无法覆盖你公司内部的制度、项目文档、产品手册，也无法自动更新到最新知识。RAG 的解决思路是“不重新训练模型，而是在推理时补充上下文”。

一个典型的 RAG 流程是：

1. 加载文档，比如 PDF、Markdown、文本文件。
2. 拆分成小的文本块，避免超出模型上下文窗口。
3. 用 Embedding 模型把文本块转成向量。
4. 保存到向量数据库。
5. 用户提问时，把问题转成向量，检索最相似的文本块。
6. 把检索结果拼进 Prompt，交给模型生成答案。

这里容易出问题的地方，集中在加载、拆分和检索质量上。很多人跑通了 RAG Demo，但回答效果很差，往往不是模型不行，而是文档解析太粗糙、分块策略不合理、检索召回不准确。

2.3 Agent：让模型调用工具

Agent 的核心是让模型不再是“只输出文字”，而是能够决定“调用哪个工具”来完成一个任务。比如查天气、查数据库、调用内部 API、执行计算。

传统程序是“人写死逻辑”，Agent 的思路是“模型根据用户意图动态决策”。它的基本循环是：

1. 接收用户任务。
2. 模型判断需要哪个工具。
3. 调用工具，拿到结果。
4. 模型根据工具结果组织最终回答。

这里最容易踩的坑是“过度信任模型”。模型可能选错工具、传错参数，甚至在被赋予高权限工具时做出危险操作。所以在工程上，Agent 不是“给模型一个工具列表”那么简单，还需要做边界控制、参数校验、日志审计和失败回退。

2.4 LangGraph：有状态、可控的工作流引擎

LangGraph 解决的问题，是复杂流程里的“状态管理”和“流程控制”。

前面提到的 Agent 是循环过程，实际业务里往往是更复杂的流程：先做意图识别，再决定走 RAG 分支还是普通对话分支，中间可能要调用多个工具，还要处理失败重试。用普通 Python 代码写这种逻辑，容易变成一大堆 if-else 和全局状态，很难维护。

LangGraph 把流程建模成一张图（Graph），节点是处理逻辑，边是流转关系。它借鉴了图计算和状态机的设计思路，让流程变得明确、可控、可测试。

对比来看：

2.5 它们之间的关系

网上最常见的问题就是“LangGraph 会不会取代 LangChain”。更稳妥的判断是：它们有不同的定位。LangChain 提供组件和链路抽象，LangGraph 提供复杂流程的控制能力。在实际项目中，LangChain 的模型、提示词、检索器组件，完全可以嵌入 LangGraph 的节点里使用。

学习顺序建议是：先用 LangChain 跑通单条链路，再用 RAG 解决知识接入，接着用 Agent 扩展工具能力，最后用 LangGraph 把复杂流程工程化。这个顺序才是“少走弯路”的核心。

3. 环境准备与前置条件

3.1 运行环境

本文的示例代码以 Python 为主。推荐环境如下：

• Python 3.10 或更高版本，3.9 也可以，但 3.10 及以上对类型注解和异步支持更友好。
• 一个可以访问大模型 API 的环境，示例中会使用 OpenAI 兼容接口，你需要准备好 API Key。
• 操作系统不限，Windows、macOS、Linux 都可以。

LangChain 的版本迭代比较快，网上的课程标题和教程版本经常不一致。学的时候不要把版本号当成唯一标准，关键是理解对象、链、检索器、图这几个核心抽象。安装时建议直接安装最新稳定版，具体以官方文档为准。

3.2 安装依赖

建议先创建虚拟环境，避免污染系统级 Python 环境。

python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate

安装核心依赖。下面的命令会安装 LangChain、LangGraph、LangChain OpenAI 集成、文档加载器、文本拆分器和 FAISS 向量库。

pip install langchain langgraph langchain-openai langchain-community langchain-text-splitters faiss-cpu

如果你的环境网络受限，可以配置国内 PyPI 镜像：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple langchain langgraph langchain-openai langchain-community langchain-text-splitters faiss-cpu

安装完成后，建议验证一下关键包是否可用：

python -c "import langchain; import langgraph; print('ok')"

如果输出 ok，环境就准备好了。如果你使用 OpenAI 兼容的本地模型服务，比如 Ollama 或 vLLM 启动的服务，也可以在代码中把 base_url 指向本地地址，原理是一样的。

4. 学习路线与核心流程拆解

4.1 第一步：跑通一次标准模型调用

不要一上来就写 RAG 和 Agent，先完成最小闭环：一条消息进入模型，模型返回文本。这一步的目标是确认 API Key 和网络环境没问题。

如果这一步失败，后面的所有代码都没有意义。常见错误包括：API Key 写错、模型名不存在、网络不通、环境变量未读取。

4.2 第二步：加入提示词模板和输出解析

让 Prompt 变成可复用模板，让输出变成结构化数据。这步让你从“写死字符串”过渡到“组织语言资产”。在很多项目里，提示词是需要单独管理的，而不是散落在业务代码中。

4.3 第三步：实现一个最小 RAG

从本地文本文件开始，用 FAISS 做向量检索。你需要理解“文档加载、拆分、向量化、检索、生成”这五个环节。注意，这五个环节里，检索质量决定了整个 RAG 的上限。

4.4 第四步：加入 Agent 工具调用

给模型一个简单的工具，比如计算器或查天气函数，让模型学会在需要时调用工具。这步会让你理解“模型不是直接输出答案，而是先调用工具拿结果再组织答案”。

4.5 第五步：用 LangGraph 控制流程

把上面的能力组合成一张图：根据用户输入判断走 RAG 还是普通对话，或者是否需要调用工具。这步会让你从“线性链路”走向“有状态的工作流”。

下面按这个学习路线，给出可直接运行的代码。

5. 完整示例与代码实现

5.1 LangChain 基础调用示例

先实现最基本的模型调用。这里使用 OpenAI 兼容接口，如果你使用其他服务商，只需要改模型名称和 base_url。

# 文件路径：examples/01_basic_chain.py from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser llm = ChatOpenAI( model="gpt-4o-mini", temperature=0, ) prompt = ChatPromptTemplate.from_messages([ ("system", "你是一名资深技术编辑，擅长用简洁的语言解释复杂概念。"), ("human", "请用不超过50个字解释一下：{topic}"), ]) chain = prompt | llm | StrOutputParser() result = chain.invoke({"topic": "什么是 RAG"}) print(result)

这段代码的逻辑是：先定义模型对象，设置温度和模型名；再定义提示词模板，其中{topic}是占位符；然后通过|运算符把提示词、模型、输出解析器串成一条链；最后传入参数并执行。

运行方式：

export OPENAI_API_KEY="你的API Key" python examples/01_basic_chain.py

如果 API Key 是通过环境变量配置的，代码中的ChatOpenAI会自动读取。输出应该是模型返回的一段简短解释。

5.2 最小 RAG 示例

这里用一个本地文本文件作为知识库，演示完整的 RAG 流程。先准备一份知识文件。

# 文件路径：docs/knowledge.txt LangGraph 是一个用于构建有状态 AI 应用的工作流引擎。 它适合处理需要多步决策、条件分支和工具调用的复杂场景。 RAG 技术通过在生成前检索外部知识，可以显著提升回答的准确性。 Agent 是能够根据用户意图动态调用工具的程序模块。

然后运行下面的代码：

# 文件路径：examples/02_rag.py from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.vectorstores import FAISS from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # 1. 加载文档 loader = TextLoader("docs/knowledge.txt", encoding="utf-8") docs = loader.load() # 2. 拆分文档 splitter = RecursiveCharacterTextSplitter(chunk_size=200, chunk_overlap=20) chunks = splitter.split_documents(docs) # 3. 向量化并存储 embeddings = OpenAIEmbeddings() vectorstore = FAISS.from_documents(chunks, embeddings) retriever = vectorstore.as_retriever(search_kwargs={"k": 2}) # 4. 构建生成链路 prompt = ChatPromptTemplate.from_messages([ ("system", "请根据以下资料回答问题。如果资料中没有答案，请直接说不知道。\n\n资料：\n{context}"), ("human", "{question}"), ]) llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) def format_docs(docs): return "\n\n".join(doc.page_content for doc in docs) chain = ( { "context": retriever | format_docs, "question": lambda x: x["question"], } | prompt | llm | StrOutputParser() ) # 5. 提问 result = chain.invoke({"question": "LangGraph 适合什么场景？"}) print(result)

代码的关键点有四个：

• 文档拆分使用chunk_size=200，表示每个块约 200 个字符，chunk_overlap=20表示块之间保留 20 个字符的重叠。这个参数需要根据实际文档调整。
• FAISS 是内存向量库，适合本地学习和原型验证。企业项目中通常会替换为 Milvus、pgvector 或 Elasticsearch。
• retriever | format_docs表示检索结果先经过format_docs函数格式化成字符串，再填充到 Prompt 的context位置。
• lambda x: x["question"]的作用是从输入字典中取 question 字段。

运行后，回答应该来自知识文件中的内容，而不是模型凭记忆生成的答案。这就是 RAG 的基本效果。

5.3 LangGraph 状态图示例

下面用 LangGraph 实现一个简单流程：根据用户输入判断是否需要走 RAG 分支。

# 文件路径：examples/03_langgraph.py from typing import TypedDict from langgraph.graph import StateGraph, START, END class State(TypedDict): input_text: str decision: str result: str def analyze(state: State): """判断用户输入是否涉及知识库查询""" text = state["input_text"] if "知识库" in text or "RAG" in text or "文档" in text: decision = "rag" else: decision = "chat" return {"decision": decision} def handle_rag(state: State): """模拟 RAG 处理流程""" return {"result": "走 RAG 流程：检索知识库后回答"} def handle_chat(state: State): """模拟普通对话流程""" return {"result": "走普通对话流程：直接回答"} graph = StateGraph(State) graph.add_node("analyze", analyze) graph.add_node("handle_rag", handle_rag) graph.add_node("handle_chat", handle_chat) graph.add_edge(START, "analyze") graph.add_conditional_edges( "analyze", lambda state: state["decision"], { "rag": "handle_rag", "chat": "handle_chat", }, ) graph.add_edge("handle_rag", END) graph.add_edge("handle_chat", END) app = graph.compile() result = app.invoke({"input_text": "我需要用 RAG 做知识库问答"}) print(result)

这段代码的核心是add_conditional_edges。它的作用是：从analyze节点出来之后，根据函数返回的decision决定下一个节点是handle_rag还是handle_chat。这就是 LangGraph 里“条件路由”的基本用法。

运行输出大概是：

{'input_text': '我需要用 RAG 做知识库问答', 'decision': 'rag', 'result': '走 RAG 流程：检索知识库后回答'}

如果你把输入改成“你好”，输出中的result会变成“走普通对话流程：直接回答”。

5.4 LangGraph Agent 工具调用示例

LangGraph 提供了一个基于 ReAct 模式的预置 Agent 实现，可以快速把工具接入模型。

# 文件路径：examples/04_agent.py from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langgraph.prebuilt import create_react_agent @tool def multiply(a: int, b: int) -> int: """返回两个整数的乘积。""" return a * b tools = [multiply] llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) agent = create_react_agent(llm, tools) response = agent.invoke( {"messages": [{"role": "user", "content": "6乘以7等于多少？"}]} ) print(response["messages"][-1].content)

@tool装饰器把一个普通函数变成模型可调用的工具。create_react_agent是 LangGraph 预置的 Agent 创建函数，它会自动处理“模型决定调用工具 → 执行工具 → 把结果返回模型 → 模型生成回答”的循环。

这里真正容易踩坑的地方是：Agent 能不能选对工具，很大程度上取决于工具的docstring写得是否清晰。模型是根据函数名、参数和 docstring 来决定是否调用该工具的，所以不要写“函数说明”这种无信息量的话，要写清楚“什么时候用、参数含义是什么”。

6. 运行结果与效果验证

如果你按顺序运行了上面的代码，验证标准如下：

• 示例 5.1 输出一段 50 字以内的 RAG 解释，说明 LangChain 基础链路正常。
• 示例 5.2 输出的回答能引用docs/knowledge.txt里的内容，说明 RAG 检索链路正常。
• 示例 5.3 能根据输入关键词进入不同分支，说明条件路由逻辑正常。
• 示例 5.4 能算出乘法结果，说明 Agent 工具调用正常。

如果运行失败，不要急着改代码，先按下面顺序排查：

1. 看 API Key 是否正确设置，错误信息是否提示 401。
2. 看网络能否访问模型服务，错误信息是否提示连接超时。
3. 看模型名是否存在，错误信息是否提示 model not found。
4. 看包版本是否兼容，错误信息是否提示某个函数不存在。

其中，包版本问题最常见。LangChain 和 LangGraph 的 API 更新频率很高，网上代码不一定适用于你安装的版本。遇到 ModuleNotFoundError 或 AttributeError 时，优先去官方文档查对应版本的写法，而不是盲目降级。

7. 常见问题与排查思路

排查问题时，建议开启 LangChain 的调试日志，它会把每一步执行的输入输出打印出来。这样能快速定位是检索环节、模型环节还是解析环节出了问题。

from langchain.globals import set_debug set_debug(True)

8. 企业级落地最佳实践与工程建议

8.1 提示词与模型的版本管理

在本地写几个 Prompt 没问题，但企业项目里，提示词会像代码一样持续迭代。建议把 Prompt 模板放到独立目录或配置中心，用版本号管理。模型名也不要散落在代码各处，统一配置在环境变量或配置文件中。

一个简单的目录结构参考：

config/ prompts/ rag_system_v1.txt chat_system_v1.txt models.yaml

# 文件路径：config/models.yaml llm: chat_model: gpt-4o-mini embedding_model: text-embedding-3-small temperature: 0

这样改 Prompt 和换模型都不需要改业务代码。

8.2 检索质量是 RAG 的生命线

RAG 的效果上限由检索决定。模型再强，检索结果不对，回答也不会对。以下几点值得重视：

• 文档解析：PDF 转文字时，表格、图片、页眉页脚都可能引入噪声。需要验证解析结果，不要盲目相信解析库。
• 分块策略：普通文本可以按字符数分块，代码或表格可能需要按结构分块。可以从 200 到 800 之间测试，找到适合你自己文档的长度。
• 召回评估：建立一个小规模测试集，比如 50 个“问题-标准答案”对，每次调整检索参数后跑一遍，用召回率判断效果，而不是靠感官判断。
• 检索后重排：如果前期检索结果不够精准，可以引入 Rerank 模型对召回结果二次排序，但会增加系统复杂度和延迟，需权衡。

8.3 Agent 的边界与安全控制

企业级 Agent 最容易出问题的不是“模型不够聪明”，而是“权限太大”。给 Agent 挂工具时，必须遵守最小权限原则。

比如，一个只能查天气的 Agent，永远不需要数据库的删除权限。一个能调用内部 API 的 Agent，必须在工具层做参数校验，而不是信任模型每次都能传对参数。工具调用日志要完整记录，方便事后再现和审计。

如果你在生产环境使用 Agent，建议在 Agent 外层加“允许执行的工具白名单”和“敏感操作二次确认”机制。模型输出不直接执行，而是先进入校验层，通过后才真正调用系统能力。

8.4 可观测性与成本控制

在本地调试时，你看不到每一步消耗了多少 token。企业项目中，成本和延迟必须纳入监控。

需要记录的数据至少包括：

• 每次请求的输入 token 数和输出 token 数。
• 每次检索耗时、模型响应耗时。
• 每次 Agent 调用了哪些工具，参数是什么。
• 失败请求的错误类型和占比。

可以在 LangChain 的调用链路中插入日志回调，或者使用 LangSmith 这类可观测性平台。成本控制方面，可以按用户维度做配额限制，避免异常流量打爆预算。缓存也是常用手段，重复问题直接走缓存答案，能大幅降低 API 费用。

8.5 从小步验证到灰度发布

很多项目死在“第一版就想做全”。一个合理的实施路径是：

1. 先用最简单的 Chat 接口跑通业务闭环。
2. 加入 RAG，解决是否要用私域知识。
3. 评估哪些操作真正需要 Agent 调工具，不要为了 Agent 而 Agent。
4. 等流程稳定后，再用 LangGraph 把多分支逻辑可视化梳理。
5. 上线时用灰度策略，先放小流量，监控错误率和用户反馈，再逐步放量。

每一步都要有明确的验证指标。不要一次性把 LangChain、LangGraph、Agent、RAG 全部塞进一个项目，否则出问题时根本不知道是哪一环造成的。

9. 总结与后续学习方向

到这里，你应该能理解 LangChain、LangGraph、Agent、RAG 的分工，也知道了一条从零跑通到工程化落地的路径。

真正值得记住的结论是：LangChain 是编排底座，RAG 解决知识接入，Agent 扩展工具能力，LangGraph 负责复杂流程的可控执行。学习时按这个递进关系走，比同时打开五个教程更有效。

下一步你可以做三件事：

第一，把文章里的四个示例代码跑通，不用背代码，但要理解每一步改了什么会产生什么影响。第二，换一批自己的文档，做一个围绕你业务资料的知识库问答，体验从通用 Demo 到领域应用的差异。第三，阅读 LangGraph 官方文档中关于状态、节点、条件边、子图和并行分支的部分，这是从“会写示例”走向“能设计复杂工作流”的必经之路。

等技术栈熟悉后，建议深入源码看一两个核心模块。比如 LangChain 的 Chain 是如何被执行的，LangGraph 的 StateGraph 是如何管理状态的。源码里藏着文档里没写清楚的边界条件。

建议收藏这篇文章，作为你从入门到工程实践的索引。更重要的是，把示例代码跑起来，遇到报错就按文章里的排查表对照处理。技术学习没有捷径，但有一条更清晰的路，总比在收藏夹里吃灰要快得多。