企业官网建设流程全解析

双非背景入局 AI Agent 开发，真正的问题不是学不会，而是学习材料太散。LangGraph、RAG、私有化部署、调优、对齐……这些概念单独搜都能看到教程，串起来却容易卡在中间：LangGraph 的 State 到底怎么理解，RAG 知识库怎么和 Agent 对接，模型部署上线后为什么回答质量下降。这篇指南把 7 天的学习路径收敛成一条主线：先跑通最小 Agent，再加入 RAG 知识库，然后封装成私有化服务，最后通过日志和评测做调优与对齐。目标不是让零基础的人七天变成什么都懂的“大神”，而是能独立搭出一个可演示、可部署、可继续扩展的 Agent 项目。

先说明一点：本文不假设你有名校背景，也不假设你能申请到大量算力。你只需要一台能运行 Python 的电脑，一个愿意持续动手的节奏，以及不回避报错日志的耐心。AI Agent 开发更像是“工程能力 + 模型理解”的组合，而不是“论文推导能力”的比拼。下面直接进入技术主线。

1. 先看清 AI Agent 开发的技术栈，再决定 7 天怎么分配

1.1 AI Agent、LangGraph 和 RAG 分别解决什么问题

AI Agent 不是一个新的模型，而是一种应用形态。它让大模型不只是回答单轮问题，而是能根据用户目标，自主完成多步操作：理解任务、拆解步骤、调用工具、读取知识、整理结果。真实项目里的 Agent 往往要串联查询数据库、调用内部 API、检索知识库、生成报告等动作，这就需要一套“编排框架”来管理流程。

LangGraph 就是用来编排 Agent 流程的图框架。它把 Agent 的执行过程建模成一张有向图：节点是动作，边是动作之间的跳转，状态对象会在图里流转。相比写一串 if else 调用大模型，LangGraph 更强调流程可视化、分支可控、可恢复，适合从简单问答升级到多工具协同的工程场景。

RAG 解决的是知识时效和事实准确的问题。大模型训练数据有截止时间，也没有企业内部资料，直接问会“一本正经地胡说八道”。RAG 先把文档切块、向量化、存入知识库，用户提问时检索最相关的片段，再拼进 Prompt 让模型基于这些片段回答。RAG 和 Agent 的关系是互补：Agent 负责“怎么调用”，RAG 负责“给模型提供依据”。

三者合在一起就是常见的企业 Agent 形态：Agent 决定要不要查知识库，RAG 返回候选资料，Agent 把资料交给模型生成带来源的回答。7 天路线要做的，就是一步步把这个链路落地。

1.2 双非背景的学习路径不能按科班顺序走

科班路线通常是：机器学习理论、深度学习、NLP、Transformer、微调、部署。这条路径很完整，但对入局 Agent 开发来说太慢，而且很多内容在初期用不到。

更务实的学习顺序是：先理解应用层流程，再根据需要去补充底层知识。第一天不需要懂 Attention 公式，但要知道一个 Agent 从输入到输出经过哪些环节；第二天不需要会训练模型，但要能修改 LangGraph 的节点函数；第三天不需要研究所有切块算法，但要能跑通一个 RAG 检索闭环。

这种路径的核心逻辑是“用项目带知识”。每做一个功能，遇到不会的地方，再针对性查资料。双非背景的优势在于工程落地训练通常更多，而 Agent 开发恰好吃工程能力。不要因为没写过论文就觉得自己不能入场，代码运行结果不会看学历。

1.3 7 天时间线和每日验收标准

以下是可行的 7 天节奏，适合每天投入 3 到 5 小时的人。时间紧张时可以拉长到 10 天，但顺序不建议乱。

不要跳过验收标准。每个任务做完后写一句“这个环节是通过什么命令或日志确认成功的”，这对后面排查问题非常关键。

2. 环境和依赖准备：先跑通最小 Agent 再谈深度

2.1 Python 环境、依赖安装和版本确认

推荐使用 Python 3.9 或更高版本。不要在系统全局环境里直接装包，先建虚拟环境，避免项目之间依赖冲突。

python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate pip install --upgrade pip pip install langgraph langchain langchain-community fastapi uvicorn chromadb sentence-transformers

依赖版本变化很快，安装完成后先确认版本，再继续后面的步骤：

pip show langgraph langchain fastapi

不同版本的 LangGraph API 可能有差异。比如StateGraph在早期版本和较新版本中引入方式不同，add_conditional_edges的参数形式也调整过多次。如果按教程写代码报错提示找不到某个类，优先检查版本号并去对应版本文档查找。

模型接入有两种方式，学习阶段至少要选一种跑通：

• 调用云端模型 API，使用langchain-openai或langchain-google-genai等适配器，申请 API Key 后直接使用。
• 本地模型，使用llama-cpp-python加载 GGUF 格式模型，适合练习私有化部署。

建议学习阶段先选云端 API，因为响应更快，能让你专注理解 Agent 编排逻辑；到第 6 天再切换到本地模型，练习私有化场景。

2.2 用 LangGraph 搭一个最小 ReAct Agent

不引入工具和外部知识，先把 LangGraph 的最小结构跑通。结构上需要三样东西：状态定义、节点函数、图编译。

from typing import TypedDict from langgraph.graph import StateGraph, END class AgentState(TypedDict): messages: list def call_model(state: AgentState): prompt = "\n".join(state["messages"]) reply = f"已收到：{prompt}" return {"messages": [f"assistant: {reply}"]}

这里的AgentState定义了图上流转的数据结构。节点函数接收state，处理后返回一个词典，这个词典只会更新对应的字段，不会覆盖整个状态。这是 LangGraph 最重要的设计：状态是增量更新的。

接下来把节点加入图并连接：

graph = StateGraph(AgentState) graph.add_node("agent", call_model) graph.set_entry_point("agent") graph.add_edge("agent", END) app = graph.compile() result = app.invoke({"messages": ["你好，请介绍一下你自己"]}) print(result)

compile()会把图转换为可执行对象，invoke()是同步运行入口。运行后你会看到输出里包含agent节点返回的新消息。这个最小闭环虽然还没有真正调用大模型，但已经足够说明 LangGraph 的基本运行方式。

2.3 本地验证：从输入到输出的完整闭环

写完代码后不要只看代码能运行，还要验证三个点：

1. 初始状态是否正确传入。
2. 节点返回的字段是否出现在最终结果里。
3. 修改messages内容后，输出是否跟着变化。

验证时可以在代码里加一行临时打印，观察调用顺序：

def call_model(state: AgentState): print("当前 state:", state["messages"]) prompt = "\n".join(state["messages"]) reply = f"已收到：{prompt}" return {"messages": [f"assistant: {reply}"]}

如果输出里出现多个 “当前 state” 打印，说明图里存在多次执行或循环；如果没有打印，说明节点没有被调用。这个习惯在看 LangGraph 循环和分支时会非常有用。

这里还要提醒一个常见坑：不要一开始就同时装 langchain、langgraph、chromadb、fastapi 一大堆依赖然后对着报错改。先把最小 Agent 跑通，再逐步加组件。依赖越少，问题越好定位。

3. LangGraph 核心机制：状态、节点和条件路由

3.1 StateGraph 的状态传递和节点设计

LangGraph 的图由状态驱动。状态不只是一个普通字典，还定义了每个字段如何更新。默认情况下，节点返回的是字段替换；如果某个字段需要追加，可以使用Annotated配合 reducer 函数。

from typing import Annotated, TypedDict from operator import add class AgentState(TypedDict): messages: Annotated[list, add] next_action: str

这里的addreducer 表示新返回的messages会追加到已有列表，而不是覆盖。这种设计方便节点之间累积信息，比如每轮对话都保留历史记录。

节点设计原则：一个节点只做一件事。命名要能表达动作，比如retrieve_docs、call_model、check_answer，不要写一个几百行的大函数包办所有逻辑。这样之后想要增加并行分支或子图，改动的成本会低很多。

节点之间通过 state 通信，而不是通过全局变量。全局变量在单线程调试时看起来很顺手，一旦图里出现并发或恢复现场，就会变成数据混乱的源头。把信息都放进 state，才能保证每次执行结果是可预期的。

3.2 conditional_edges 实现分支和循环

条件路由是 Agent 的核心能力。没有条件路由，图只能按固定顺序执行；加上conditional_edges，Agent 才能根据用户输入决定下一步走向。

def route_by_last_action(state: AgentState) -> str: if state["next_action"] == "retrieve": return "retrieve" if state["next_action"] == "finish": return "finish" return "call_model" graph.add_conditional_edges( "agent", route_by_last_action, { "retrieve": "retrieve_docs", "call_model": "agent", "finish": END, } )

route_by_last_action的返回值必须能在映射字典里找到对应目标。如果返回了一个不存在的 key，运行时会报错。这个报错信息通常会直接告诉你未匹配到哪个键，排查时先看函数返回值，再看映射字典。

循环也是这样实现：某个条件分支把下一个节点指回自身或前面的节点。Agent 如果认为工具结果不足，可以再次调用工具或模型，形成“思考 - 行动 - 观察”的循环。要注意设置最大迭代次数，否则模型反复触发某个分支会导致死循环。

def should_continue(state: AgentState) -> str: if len(state["messages"]) > 10: return "end" return "agent"

限定循环次数是生产环境必备的防御手段。

3.3 子图、并行分支和长期记忆的落地方式

子图用于复用流程。比如一个“文档问答”子图，可以在多个父图中被引用。LangGraph 支持把编译好的图作为节点加入另一个图，本质上和普通节点一样接收 state 并返回 state。

并行分支适合同时调用多个工具的场景。比如用户问“对比这份文档和昨天报表的数据”，Agent 可以并行启动两个检索节点，再把结果合并给下一个节点。LangGraph 的fanout写法在版本间差异较大，学习时不用急着追新特性，先理解“多路输入汇合到一个节点”的语义即可。实现时只要确保每个分支都写入 state 的不同字段，就不会互相覆盖。

长期记忆是 Agent 从 Demo 走向实用必须解决的问题。对话内的短期记忆通过 state 保存，跨会话记忆需要把关键信息持久化到外部存储。LangGraph 新版本中的 checkpointer 机制可以保存图的执行状态，但落地时要结合数据库设计自己的记忆 schema：用户 ID、会话 ID、摘要、关键事实、过期时间。不要把所有历史都塞进 Prompt，上下文长度有限，而且无关信息会干扰模型判断。

4. RAG 知识库：文档加载、切块、向量检索和引用溯源

4.1 RAG 是什么，和 Agent 如何配合

RAG 全称是 Retrieval-Augmented Generation，意思是在生成前先做检索。它解决的问题很直接：模型不知道的知识，通过检索外部文档来补上。

RAG 的完整链路包括：

1. 文档解析和清洗。
2. 文档切块。
3. Embedding 向量化。
4. 向量数据库存储。
5. 用户查询时召回相关片段。
6. 把片段拼进 Prompt。
7. 模型生成带依据的回答。

在 Agent 流程里，RAG 不是独立的问答接口，而是 Agent 的一个工具或一个子图。Agent 先判断用户问题是否需要查内部资料，需要时调用 RAG 检索，再根据结果生成回答。这样不会所有问题都走知识库，也能在知识库没有答案时让 Agent 明确说“不知道”。

4.2 文档加载解析全流程：PDF、Markdown 和表格

文档加载是 RAG 最容易低估的一步。PDF 里的文字层级、表格、图片注释，Markdown 里的代码块，Word 里的批注，每种格式都有不同坑。

以 LangChain 为例，加载 PDF 和 Markdown 的常见写法：

from langchain_community.document_loaders import PyPDFLoader, TextLoader pdf_loader = PyPDFLoader("./docs/help.pdf") pdf_docs = pdf_loader.load() md_loader = TextLoader("./docs/guide.md", encoding="utf-8") md_docs = md_loader.load()

PDF 解析出来的文档对象里通常包含page_content和metadata。metadata里有页码、来源文件等字段，这些字段在引用溯源时非常有用，不要随意丢弃。

表格是 RAG 的难点。直接把 Excel 表格转成文本后按行列切，检索效果往往很差。推荐先把表格转成 Markdown 表格，再按行或按含义分组切块。比如一行一个“规则”文本，让 embedding 能检索到完整语义。

表格转 Markdown 示例： | 状态 | 说明 | 处理人 | | --- | --- | --- | | PENDING | 等待审核 | 张三 | | APPROVED | 审核通过 | 李四 |

如果原始材料是图片型 PDF，需要 OCR 识别。OCR 后要把文本块的位置信息保留下来，例如“第 3 页左上角”，方便后续定位到原文档。

4.3 切块策略与 embedding 选择

切块没有万能参数，只有适合场景的策略。这里给出常见策略对比：

RecursiveCharacterTextSplitter是按优先级依次尝试分隔符切分，初学时推荐先用它跑通：

from langchain.text_splitter import RecursiveCharacterTextSplitter splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50, separators=["\n\n", "\n", "。", ".", " "], ) chunks = splitter.split_documents(pdf_docs) print(len(chunks))

chunk_size是目标长度，实际会略长或略短。chunk_overlap是前后重叠，用来保留跨块上下文。如果检索结果经常漏掉关键信息，先调大重叠值；如果回答精读差，先检查切块是否破坏了语义。

embedding 选择要结合语言和数据特点。中文场景常用BAAI/bge-small-zh-v1.5这类模型，体积小、效果够用。加载方式和模型名要按实际安装版本调整：

from langchain_community.embeddings import HuggingFaceEmbeddings embedding = HuggingFaceEmbeddings( model_name="BAAI/bge-small-zh-v1.5" )

如果没有本地模型缓存，需要先从可用模型源下载。如果下载受限，可以换用国内模型托管平台下载。注意不要在一个项目里混用两套 embedding 模型，否则查询向量和文档向量不在同一向量空间，检索结果会失真。

4.4 检索、重排和引用溯源

检索代码的核心是把 query 向量化后到向量库找相似文档：

from langchain_community.vectorstores import Chroma vectorstore = Chroma.from_documents( documents=chunks, embedding=embedding, persist_directory="./chroma_db" ) query = "报销流程是什么？" docs = vectorstore.similarity_search(query, k=4)

k是返回的片段数量。学习时取 3 到 5 个够了；生产环境要根据真实问答情况调整。片段太少可能漏信息，太多会把无关内容塞进 Prompt，导致模型被错误上下文带偏。

只用相似度检索在真实项目里不够。推荐加入重排：先召回 20 个候选片段，再用重排模型选出最相关的 5 个。这一步能明显提升回答准确性，但会增加延迟。是否引入重排，要看对实时性的要求。

引用溯源是 RAG 容易被忽略的安全能力。生成回答时要把答案对应的来源一起返回：

def build_prompt(query, retrieved_docs): context = "\n\n".join( f"[{i+1}] {doc.page_content}" for i, doc in enumerate(retrieved_docs) ) prompt = f"请根据资料回答问题。\n资料：\n{context}\n\n问题：{query}" return prompt

在返回结果时，把retrieved_docs的metadata也拼进答案结构。用户能点开原文确认，开发者也能在评测时判断模型是不是读了正确资料。

5. 私有化部署：从本地 Notebook 到服务化

5.1 私有化部署的动机和边界

私有化部署的典型场景是企业内部知识库问答、政企数据隔离、离线环境使用。相比直接调用云端 API，私有化部署能把文档数据留在内网，也能在无外网环境运行。

但不要为了“私有化”而私有化。私有化部署要自己维护模型、依赖、资源监控和故障恢复，成本并不低。进入决策前先问三个问题：

1. 数据是否真的不能出内网。
2. 业务并发量有多大。
3. 团队有没有能力维护部署环境。

如果只是个人学习，可以先在本机跑一个小模型；如果是企业项目，再根据数据规模选择单机 GPU 还是集群方案。

5.2 用 FastAPI 封装 Agent+RAG 服务

把前面写好的 Agent 和 RAG 逻辑封装成 HTTP 接口，是私有化部署的基础动作。用 FastAPI 写一个最小服务：

from fastapi import FastAPI from pydantic import BaseModel class QueryRequest(BaseModel): query: str class QueryResponse(BaseModel): answer: str sources: list[str] app = FastAPI() def run_agent_pipeline(query: str): # 这里调用 LangGraph 图和向量库检索 # 返回 answer 和 sources return {"answer": "示例回答", "sources": ["docs/help.pdf#page=3"]} @app.post("/agent", response_model=QueryResponse) def agent_endpoint(req: QueryRequest): result = run_agent_pipeline(req.query) return QueryResponse(answer=result["answer"], sources=result["sources"])

启动服务：

uvicorn main:app --host 0.0.0.0 --port 8000

这样 Agent 就从“本地函数”变成了“可被前端或其他系统调用的服务”。实际项目里还要加三样东西：请求日志、异常捕获、超时控制。比如用户传了一个空 query，要返回 400 而不是让 Agent 跑一次无效流程。

如果系统并发要求高，先不要在 FastAPI 内部开大量线程，而是把模型加载和向量检索设计成独立组件。向量库可以单独启动为服务，模型推理也可以放进独立推理服务，FastAPI 只做编排。这样不会因为一次大查询阻塞所有请求。

5.3 模型加载、并发控制和内存调优

使用本地模型时，模型文件通常很大，加载一次成本高。正确的做法是启动时加载一次，各请求复用同一个模型实例，不要在每次请求里反复加载。

以llama-cpp-python加载 Qwen 等 GGUF 模型为例，思路是先加载后调用：

from llama_cpp import Llama llm = Llama( model_path="/models/qwen2-7b-instruct-q4_k_m.gguf", n_ctx=4096, n_gpu_layers=-1, verbose=False )

n_ctx控制上下文窗口长度，n_gpu_layers控制多少层放到 GPU。这两个参数直接影响内存和显存占用。7B 模型的量化版在普通消费级显卡上可以运行，但如果是 CPU 推理，单次生成速度会明显慢，学习环境要有心理准备。

内存调优优先关注以下几点：

• 上下文长度：不是越大越好，过大会增加显存占用和生成延迟。
• 并发数：单卡并发太高会显存溢出，要测出合适的上限。
• 量化精度：Q4 比 Q8 省显存但可能有精度损失，需要评测。
• 缓存：重复问题可以加语义缓存，减少重复计算。

学习环境和生产环境的差异可以用表格说明：

6. 调优与对齐：让 Agent 在真实场景里更可靠

6.1 调优先看日志和可观测性，不要盲目换模型

很多人在 Agent 回答不好时第一反应是换大模型，但真正的问题往往出在检索或 Prompt 上。调优前先建立日志，把每次请求的关键信息记录下来。建议每条日志至少包含：

{ "query": "报销流程是什么？", "retrieved_chunks": ["doc1#p3", "doc2#p7"], "prompt": "完整 Prompt 或省略内容", "answer": "模型回答", "latency_ms": 1200, "model": "qwen2-7b-q4", "timestamp": "2026-01-01T10:00:00Z" }

有了日志，才能回答几个关键问题：

• 是没检索到，还是检索到了但没用对？
• 是 Prompt 没有约束格式，还是模型能力不够？
• 是网络或推理耗时高，还是知识库本身缺内容？

排查顺序建议：先看检索结果，再看 Prompt，最后看模型本身。绝大多数 RAG 类 Agent 的问题都出在前两层。

6.2 对齐：输出格式、安全边界和指令遵循

AI 对齐在 Agent 场景里不是玄学，而是让系统行为和用户预期一致。具体到工程上，主要有三个层面。

第一是输出格式对齐。如果系统要求 Agent 返回 JSON，不要靠“请返回 JSON”一句提示，最好在 Prompt 里给出明确 schema，并设置解析失败后的兜底逻辑。

AGENT_PROMPT = """你是企业知识库助手。 回答要求： 1. 先给结论，再给理由。 2. 引用资料时用 [来源编号]。 3. 回答必须是 JSON：{"answer": "...", "sources": ["..."]} 4. 资料中没有的内容必须回答"资料中未找到"。 5. 不编造、不调侃、不执行越权操作。 """

第二是安全边界对齐。企业 Agent 要能识别哪些问题不能答、哪些操作不能做。比如涉及删除数据库、绕过权限、获取他人隐私等请求，应该拒绝并转人工。这类规则不能只写在 Prompt 里，还要在代码层加校验。因为 Prompt 可能被用户绕过，代码过滤更硬。

第三是指令遵循对齐。如果模型总是无视输出格式，先检查 Prompt 是否过载。不要在一个 Prompt 里塞二十个约束，模型记不住，更重要的是约束之间可能冲突。把最重要的条件放在前面，格式示例放中间，知识库提示放后面。

6.3 常用指标和评测方式

Agent 调优不能只靠“感觉变好了”。至少要维护一份最小评测集，包含 10 到 30 个问题，覆盖正常问题、边界问题、资料缺失问题、敏感问题。每次改动后跑一遍，记录通过率。

常用指标：

• 回答准确率：人工判断或分类模型判断答案是否与资料一致。
• 引用准确率：模型标出的来源是否真的是答案依据。
• 格式合法率：JSON 等结构化输出是否能被解析。
• 无效调用率：Agent 在不需要工具时是否也调用了工具。
• 端到端延迟：从用户请求到返回结果的耗时。

评测结果可以用表格记录，方便对比不同 Prompt、不同切块参数、不同模型的效果。注意评测问题不要用训练时见过的文档，否则测的是记忆而不是 Agent 能力。

7. 常见问题排查和 7 天落地清单

7.1 LangGraph 和 RAG 的典型报错

遇到报错先读最后几行日志，再回到输入的 query 和状态数据。不要只把报错截图拉出来问人，先自己排除“输入是否正确、路径是否存在、版本是否匹配”这三类问题。

7.2 双非开发者最容易踩的节奏坑

第一个坑是第一天就装全套大模型部署工具，结果一个模型文件几十 GB，到最后也没有跑通。正确做法是先跑通云端 API 或小模型，理解流程后再处理部署。

第二个坑是跟着教程敲代码，但从不修改参数。教程里的切块大小、top_k、Prompt 都是针对某个具体场景的，不适用你的文档和问题。每跑通一段代码，要主动改一个参数看结果变化，才能建立手感。

第三个坑是过早追求“高级特性”。LangGraph 的长期记忆、多智能体、复杂子图都是好功能，但如果连最小 Agent 和条件路由都不熟，加再多的概念只会增加混乱。7 天里先把基础链路做扎实，剩下的留到第 8 天以后继续。

第四个坑是忽略文档数据质量。很多 RAG 项目效果差，不是模型问题，而是 PDF 解析出来乱码、表格被切碎、重复内容太多。数据清洗和切块占 60% 的工作量，要在第一天就建立这个意识。

7.3 7 天学习清单和下一步扩展

第 8 天开始，不要继续看零散教程。找一个自己身边真实存在的问题，比如把某本书、某个企业文档、某个开源项目的说明做成 Agent，然后不断修改检索、Prompt 和部署配置。把 7 天学到的东西套进自己的场景，才是从小白到能独立开发的分水岭。

AI Agent 开发的门槛正在从“会不会模型算法”转向“能不能把模型、数据、流程和服务工程化地组织起来”。双非背景不代表没有入场机会，关键是先有一份能运行的代码，再慢慢补原理。希望这份 7 天学习路线能帮你少走弯路，至少先把主线跑通。