企业官网建设流程全解析

双非入局 AI Agent 开发：LangGraph + RAG + 私有化部署的一条落地路线

先说结论：AI Agent 不是另一个“调参比赛”，它比拼的是你把大模型接进真实业务系统的能力。这也是双非背景的同学最适合切入的位置——不需要发论文，不需要卷硬件，只需要把 LangGraph、RAG、私有化部署、调优这些工程链路跑通，就能拿出一个能演示、能上线、能写进简历的项目。

这篇文章的目标很直接：按 7 天任务卡，带你走一遍 AI Agent 开发的核心链路。你会看到 LangGraph 怎么编排 Agent，RAG 怎么给模型接上私有知识，llama.cpp + FastAPI 怎么做私有化部署，以及调优和对齐到底在调什么。7 天成不了“大神”，但 7 天足够搭建第一个完整可运行的 Agent 项目，并且在过程中建立一套可复用的工程思路。

1. 核心能力速览

2. AI Agent 入局前的三个核心概念

2.1 Agent 到底是什么

AI Agent 和大模型聊天机器人的本质区别在于：Agent 能在大模型驱动下自主完成“理解目标 → 拆解步骤 → 调用工具 → 观察结果 → 修正策略”的循环。它不再是一问一答的对话框，而是一个有状态、有工具、有记忆的任务执行体。

从工程实现看，一个 Agent 至少包含四部分：

• 模型层：负责推理和生成，可以是 OpenAI API，也可以是本地部署的开源模型。
• 规划层：决定下一步执行什么操作，LangGraph 中的节点和条件边就是规划逻辑的载体。
• 工具层：通过 Function Calling / Tool Calling 调用外部工具，例如搜索、计算器、数据库查询、ES 日志检索接口。
• 记忆层：保存短期上下文和长期知识，短期记忆在 LangGraph State 里流转，长期记忆可以落到向量库或外部存储。

2.2 双非背景入局 Agent 的机会点

学校背景在 Agent 开发这个方向上权重不高，因为这个方向还处在工程范式快速演进的阶段。企业要的不是“名校光环”，而是能快速上手 LangGraph、能调通 RAG、能把模型部署到内网的人。这些能力全部可以靠本地项目证明。

近期搜索热度里大量出现 LangGraph 教程、LangGraph 官方文档、RAG 实战、Agent 项目 GitHub 相关关键词，说明整个社区也在同步学习。此时入局，不用跟存量卷，而是在增量市场里抢身位。

2.3 2026 年值得关注的 Agent 趋势

保守判断，接下来几个方向会持续升温：

• 多 Agent 协作框架：多个子 Agent 分别承担规划、检索、执行角色，LangGraph 子图是实现这种结构的基础能力。
• 工具调用协议标准化：MCP 这类协议试图解决 Agent 与外部工具连接的碎片化问题，熟悉 LangChain / LangGraph 后再看 MCP 会非常快。
• Agent 评估体系化：单纯跑通功能不再有说服力，RAG 的引用溯源、Groundedness、工具调用成功率会逐渐成为项目验收标配。
• 端侧和私有化部署：数据不出内网的需求越来越明确，llama.cpp、vLLM、FastAPI 这套组合会成为 Agent 工程落地的基本功。

3. 环境准备与前置条件

3.1 开发环境清单

3.2 显存和资源占用怎么判断

很多同学问“我的显卡能不能跑”，答案通常不是拍脑袋，而是按公式估算：

• 模型加载显存 ≈ 参数量 × 每个权重字节数。
• 7B 模型用 4bit 量化，权重大约 4GB 左右，加上 KV Cache 和推理中间态，实际显存会更高。
• 上下文越长、并发数越大、批量数越大，KV Cache 占用越多。

所以不要轻信“4G 显存跑 7B”这类说法，正确做法是先用 ollama 或 llama.cpp 在目标机器上实际跑一次，观察nvidia-smi和启动日志。学习阶段完全可以用 API 先跑通逻辑，再迁移到本地模型。

3.3 第一个任务：建立最小可运行环境

# 创建虚拟环境（示例） conda create -n agent python=3.11 -y conda activate agent # 安装基础依赖，版本以实际安装为准 pip install langchain langchain-openai langgraph pip install fastapi uvicorn httpx pip install pypdf langchain-text-splitters chromadb

这个最小环境足够支撑前 3 天的 LangGraph 和 RAG 学习。注意先确认安装的 LangChain / LangGraph 版本兼容性，新版本 API 变动较快，教程代码报错时优先查当前版本文档。

4. 第 1-2 天：LangChain 和 LangGraph 到底怎么选

4.1 两者的关系与区别

LangChain 是最早火起来的 LLM 应用开发框架，提供模型封装、Prompt 模板、输出解析器、文档加载器等基础组件。它的核心抽象是 Chain，适合线性的“先后调用”。但真实 Agent 场景经常需要条件分支、循环、人工确认、并行执行，Chain 模型表达起来很吃力。

LangGraph 是 LangChain 团队后来推出的编排框架，核心抽象是图。节点表示执行逻辑，边表示状态流转，条件边决定下一步走向。它把整个 Agent 运行过程建模成一张有向图，既保留 LangChain 的组件生态，又能表达复杂控制流。

简单结论：

• 快速做原型、调用模型解析结果，LangChain Chain 够用。
• 做真正的 Agent，要循环调用工具、要分支控制，直接上 LangGraph。
• 两者不是竞争关系，LangGraph 节点内部可以继续调用 LangChain 组件。

4.2 LangGraph 核心概念

4.3 用 LangGraph 实现一个带条件路由和循环的 Agent

下面是一个最小可用的 LangGraph 示例：模型先判断用户问题需不需要调用工具，如果不需要直接结束，如果需要则进入工具节点，然后再回到模型节点继续判断。

from typing import Literal from typing_extensions import TypedDict from langgraph.graph import StateGraph, START, END from langchain_openai import ChatOpenAI # 也可以换成本地模型端点 llm = ChatOpenAI( base_url="http://127.0.0.1:8080/v1", api_key="EMPTY", model="qwen2-7b" ) class State(TypedDict): question: str messages: list next_step: str def call_model(state: State): """模型节点：判断是否需要继续调用工具""" prompt = ( "你是 Agent 调度器。如果用户问题需要查询实时数据或外部系统，" "输出 TOOL_REQUEST；否则直接回答。问题：" + state["question"] ) response = llm.invoke(prompt) next_step = response.content.strip().upper() if "TOOL_REQUEST" in next_step: next_step = "need_tool" else: next_step = "done" return {"next_step": next_step, "messages": [response.content]} def call_tool(state: State): """工具节点：模拟一个查询外部系统的工具""" result = "已查询系统，返回结果：订单数量 128，异常 3 条" return {"messages": state["messages"] + [result], "next_step": "done"} def route(state: State) -> Literal["call_tool", "end"]: """条件边：根据模型判断决定走向""" if state["next_step"] == "need_tool": return "call_tool" return "end" # 构建图 builder = StateGraph(State) builder.add_node("call_model", call_model) builder.add_node("call_tool", call_tool) builder.add_edge(START, "call_model") builder.add_conditional_edges("call_model", route, { "call_tool": "call_tool", "end": END }) # 工具执行后回到模型节点，形成循环，最多执行若干步后结束 builder.add_edge("call_tool", "call_model") app = builder.compile() # 运行测试 result = app.invoke({"question": "帮我查一下昨天的订单异常情况"}) print(result["messages"])

这个例子同时用到了条件路由、循环边和状态传递。实际项目里还需要考虑循环步数上限，LangGraph 在检测到超过最大迭代次数时会抛出错误，避免 Agent 无限循环。

4.4 子图和并行分支

复杂项目建议拆分子图。例如主 Agent 负责整体调度，子 Agent 分别负责“日志检索”“数据分析”“报告生成”，每个子 Agent 是一个独立 StateGraph，再作为主图的一个节点接入。并行分支可以定义多个节点指向同一个后续节点，LangGraph 会将多个上游节点的返回状态做合并更新，注意避免不同节点更新同一个字段造成覆盖冲突。

5. 第 3-4 天：RAG 实战，从文档到知识库

5.1 RAG 的核心链路

RAG（Retrieval-Augmented Generation）解决的核心问题是“模型不知道你的私有数据”。通用大模型的知识截止时间是训练时确定的，企业内部的制度文档、产品资料、日志信息它都没见过。RAG 的思路是先检索再生成：用户提问后，先从知识库检索相关片段，再把片段和问题一起交给大模型生成答案。

一个完整的 RAG 流程是：

1. 文档加载解析。
2. 文本切块（Chunking）。
3. 向量化（Embedding）。
4. 写入向量数据库索引。
5. 用户问题向量化。
6. 相似度检索。
7. 重排（可选）。
8. 拼接 Prompt 并生成回答。
9. 引用溯源与效果评估。

5.2 文档加载解析是第一个坑

企业级 RAG 的痛点往往不是模型不行，而是文档加载解析不过关。PDF 里既有文本又有扫描图片，有的还是表格和复杂排版；Word、Markdown、HTML 的解析方式各不相同；OCR 识别错一个字，后面整条链路都受影响。

建议按文档类型做解析策略：

5.3 切块策略直接决定检索质量

切块是 RAG 调优最高频的调整点之一。切得太小，语义不完整；切得太大，检索噪声多，还浪费上下文窗口。

常用切块方式：

• 固定大小切块：按字符数切，简单但容易切断语义，不推荐单独使用。
• 递归字符切块：优先按段落、句子、标点逐级切分，LangChain 的RecursiveCharacterTextSplitter是默认首选。
• 语义切块：先判断句子间的语义相似度，在产生主题变化的位置切分，质量更好但耗时更高。
• Markdown 标题结构切块：适合技术文档，保留标题层级作为上下文。
• 父子切块：父块保存全局信息，子块参与检索，兼顾检索精度和上下文完整性。

一个带切块和向量化的最小示例：

from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma # 1. 加载解析 PDF loader = PyPDFLoader("./docs/course.pdf") docs = loader.load() # 2. 递归字符切块 splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=80, separators=["\n\n", "\n", "。", "！", "？", "，", " ", ""] ) chunks = splitter.split_documents(docs) # 3. 向量化写入 Chroma embeddings = OpenAIEmbeddings( base_url="http://127.0.0.1:8080/v1", api_key="EMPTY", model="bge-m3" ) vectorstore = Chroma.from_documents( documents=chunks, embedding=embeddings, persist_directory="./chroma_db" ) # 4. 检索测试 retriever = vectorstore.as_retriever(search_kwargs={"k": 5}) results = retriever.invoke("课程考核方式是什么") for i, doc in enumerate(results): print(f"第{i+1}段：{doc.page_content[:100]}")

5.4 检索调优和引用溯源

检索不是“搜到就行”，企业级 RAG 必须给出证据链。调优时重点关注：

• Top-K：返回多少片段。K 太小可能漏证据，K 太大可能引入噪声。
• 阈值过滤：相似度低于某个阈值的片段直接丢弃。
• 重排（Rerank）：向量检索召回后，用重排模型精排，成本高但效果提升明显。
• 引用溯源：回答中每个关键断言都要能对应到知识库原文，这既是评估维度，也是合规要求。
• Groundedness（忠实度）：模型输出内容是否严格基于检索上下文，而不是自行编造。可以人工抽查，也可以用大模型当评估器逐条判断回答中的断言是否在上下文中存在依据。

5.5 RAG 常见失败模式

6. 第 5-6 天：私有化部署与调优

6.1 为什么必须学私有化部署

很多企业内部不允许把业务数据通过公有 API 发送出去。私有化部署的意义不是在本地跑一个模型炫耀性能，而是让 Agent 能在内网环境、离线环境、敏感数据场景下正常工作。搜索词里反复出现“大疆司空2私有化部署”“算力云私有化部署”，说明各行各业都在做这件事。

6.2 llama.cpp + FastAPI 部署方案

llama.cpp 的定位是把大模型跑在消费级硬件上，核心优化是 GGUF 量化和 CPU/GPU 混合推理。配套的llama-server可以直接启动一个兼容 OpenAI 格式的 HTTP 服务。Qwen2-7B 这类开源中文模型配合 GGUF 量化是常见组合。

一个典型的私有化部署架构：

用户请求 -> FastAPI 业务服务层（RAG、Agent 编排） -> llama.cpp / vLLM 模型服务（OpenAI 兼容接口） -> 向量数据库（知识库） -> 外部系统（ES、MySQL、业务 API）

启动模型服务的大致命令：

# 示例命令，模型路径和端口按实际环境调整 llama-server \ -m ./models/qwen2-7b-instruct-q4_k_m.gguf \ --host 127.0.0.1 \ --port 8080 \ --n-gpu-layers 999 \ --ctx-size 8192

其中--n-gpu-layers控制多少层加载到 GPU，如果显存不足就调小，或者不传该参数走 CPU。启动后可以用 OpenAI SDK 兼容方式调用。

6.3 用 FastAPI 封装 Agent 服务

模型服务就绪后，建议把 Agent 逻辑封装成独立 API。下面是一个最小的 FastAPI 服务模板：

from fastapi import FastAPI from pydantic import BaseModel import requests app = FastAPI() class QueryRequest(BaseModel): question: str session_id: str = "default" def call_model(messages): payload = { "model": "qwen2-7b", "messages": messages, "temperature": 0.2 } resp = requests.post( "http://127.0.0.1:8080/v1/chat/completions", json=payload, timeout=180 ) return resp.json()["choices"][0]["message"]["content"] @app.post("/agent/chat") def agent_chat(req: QueryRequest): # 这里可以串联 LangGraph 或 RAG 检索逻辑 answer = call_model([{"role": "user", "content": req.question}]) return {"answer": answer, "session_id": req.session_id} # 启动：uvicorn main:app --host 0.0.0.0 --port 8000

6.4 调优到底调什么

• Prompt 调优：系统提示词里写清楚角色、任务、输出格式、引用规则。迭代时记录每个版本的效果，而不是靠感觉改。
• 检索调优：调 chunk_size、chunk_overlap、Top-K、相似度阈值、重排开关。
• 模型参数调优：temperature 降到 0.1-0.3 适合知识问答和日志分析，降低随机性；max_tokens 控制生成长度。
• 图结构调优：LangGraph 里减少无效节点、明确条件边终止条件、给循环设上限，避免 Agent 在错误分支空转。
• 对齐调优：把“若检索结果不足以回答，必须明确说不知道”写进 Prompt，降低模型强行补全的幻觉概率。

6.5 对齐的工程化理解

对齐在 Agent 工程里不是抽象概念，而是可以用测试用例检验的指标。例如准备一组“知识库内问题”和“知识库外问题”，给 Agent 设置相同的提问，检查它是否只在有证据时回答、是否会拒绝回答超出知识范围的问题、是否会引用错误的来源。把这些用例沉淀成回归测试集，每次改动 Prompt 或切块策略后跑一遍，才能保证系统不越改越差。

7. 第 7 天：综合实战项目——ES 日志智能分析 Agent

7.1 项目目标

用前面所有知识点做一个有业务价值的项目：用户用自然语言查询日志系统，Agent 负责理解问题、生成 ES 查询条件、调用 ES REST API、分析返回结果、输出图文报告。这个项目天然覆盖了 LangGraph 编排、工具调用、私有化部署、批量任务几个核心考点。

项目结构：

• LangGraph 主图：意图识别 -> 查询参数生成 -> 调用 ES -> 结果分析 -> 生成报告。
• 工具节点：封装requests调用 ES REST API。
• RAG 节点：可选，把 ES 索引字段说明录入知识库，辅助 Agent 生成准确的查询参数。
• 批量任务：支持定时执行周期巡检，把当天异常日志汇总推送。

7.2 批量任务与失败重试

日志分析和知识库问答都属于典型批量任务。批量任务的工程要求比单次请求高很多，建议采用以下设计：

import logging import time from datetime import datetime logging.basicConfig( filename="agent_tasks.log", level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s" ) TASKS = [ {"question": "今天订单接口的 5xx 错误数量", "priority": "high"}, {"question": "最近一小时登录失败趋势", "priority": "medium"}, {"question": "库存服务响应时间 P99 变化", "priority": "medium"}, ] def run_task(task: dict): retry_count = 0 while retry_count < 3: try: # agent_app 是上一步编译好的 LangGraph 应用 result = agent_app.invoke({"question": task["question"]}) logging.info(f"task success: {task['question']}") return result except Exception as e: retry_count += 1 logging.warning(f"task retry: {task['question']}, error: {e}") time.sleep(2 ** retry_count) logging.error(f"task failed after retries: {task['question']}") return None def run_batch(tasks: list): for idx, task in enumerate(tasks): start = datetime.now() result = run_task(task) duration = (datetime.now() - start).total_seconds() logging.info(f"batch item {idx + 1}, duration: {duration}s")

批量任务要记录每个任务的入参、出参、耗时、错误原因，一方面方便排查，另一方面输出本身就是调优的数据集。失败任务重试时采用指数退避，避免重试风暴打挂下游系统。

7.3 验收标准

项目做完后，用一组固定用例做验收：

8. 资源占用与性能观察

本地部署阶段，建议养成边运行边观察资源占用的习惯。主要工具：

• nvidia-smi观察 GPU 显存利用率。
• htop或任务管理器观察 CPU 和内存。
• 模型服务日志观察每次请求的耗时和 Token 消耗。
• time命令统计单次执行耗时。

判断性能瓶颈的通用顺序：

1. 推理耗时占比高：模型参数量大、量化位数高、并发低。
2. 检索耗时占比高：向量库数据量大、索引未优化、没有缓存。
3. 文档解析耗时高：OCR 或表格解析是常见瓶颈，批量任务建议预处理生成缓存文件。
4. 内存持续上涨：可能存在流式处理未释放、批量任务累积历史状态，LangGraph 长会话要把记忆做裁剪或持久化。

降低资源占用的可行手段：

• 用 4bit / 8bit 量化模型。
• 限制ctx-size，上下文越长 KV Cache 越大。
• 批量推理时调整 batch size。
• 给 Agent 加最大步数限制，避免无意义循环。
• 多个任务共用一个 LLM 服务实例，不要每次任务都加载一次模型。

9. 常见问题与排查方法

10. 最佳实践与合规建议

10.1 工程化建议

• 第一次跑通时全部用小数据集、小模型、低并发，能跑通再逐步放大。
• 保留一份最小可运行配置，方便随时回归对比。
• 模型文件、输入素材、输出结果分目录管理，用配置文件维护路径参数。
• 批量任务必须加日志、超时和失败重试，否则上线后很难排查。
• API 服务暴露到内网时要限制访问范围，不要直接绑定 0.0.0.0 且不加鉴权。
• 上线前用测试集跑一遍效果，人工复核重点样本。

10.2 合规提醒

需要强调一句：AI Agent 开发涉及的数据和模型使用必须注意边界。使用开源模型时遵守其开源许可；处理日志、文档、用户数据时先做脱敏和权限管理；涉及人脸、声纹、肖像、版权素材的能力，必须确认已获得合法授权。私有化部署不等于可以随意拿数据训练或对外提供服务，这一点在项目文档里最好明确写清楚。

11. 学习节奏与最后提醒

11.1 7 天任务卡

11.2 不需要等“准备好再开始”

双非背景入局 AI Agent 的重点不在于掌握所有理论，而是尽早跑通一条端到端链路。先跑通 LangGraph 最小图，再补 RAG 检索，再上私有化部署，最后做调优和对齐。遇到报错就查文档、看日志、翻版本变更，这些能力本身就是 Agent 工程师的日常。

把 7 天的成果沉淀成一篇带架构图、接口示例、性能观察记录和测试结论的项目文档，比纠结“我是不是还不够格投简历”有用得多。这套链路里的每一条技能，都能在接下来的 Agent 项目里复用。