简介

本文详细介绍了一个基于LangChain 1.1架构的工业级Agentic RAG系统开发实战指南，重点解决了DeepSeek-V3.2适配问题。系统采用Agent架构实现自主决策能力，通过动态中间件机制自适应生成System Prompt，并实现了基于Artifact的透明化引用和双重切分检索策略。文章提供了完整的项目架构解析、数据流转流程和核心代码实现，为开发者提供了一套轻量级企业级RAG应用的标准模板。

---

这绝对是全网独家的工业级智能体系统开发实战指南！团队突破性独家攻克：DeepSeek-V3.2 适配难题，二次开发适配版源码，彻底释放 DeepSeek-V3.2 推理调用工具全部潜能～

手把手教你带你实操工业级Agentic RAG系统开发！前端展示如下：

本项目不仅仅是一个简单的文档问答工具，而是基于 LangChain 1.1 最新架构 打造的 Agentic RAG（代理式检索增强生成） 系统。不同于传统 RAG 机械式的“检索-生成”流程，本系统赋予了大模型“自主决策”的能力，并引入了后端中间件机制，实现了真正的智能化知识服务。

完整的项目源码+讲解视频整理上传至大模型技术社区啦，欢迎点击：https://brmes.xet.tech/s/4mjiyo加入社区免费获取～话不多说，开启今天的干货内容分享

---

核心功能与技术亮点：

1. Agentic RAG 决策架构 (LangChain 1.1 Standard)

• 摒弃过时的 Chain 模式，采用 Agent（智能体） 架构。模型不再是被动接收上下文，而是化身为“决策者”。它能根据用户问题，自主判断是直接进行闲聊，还是调用工具去知识库中检索信息，实现了“所答即所问”的灵活交互。

2. 动态中间件与自适应 System Prompt

• 亮点技术：实现了“上下文感知”的中间件机制。
• 核心逻辑：系统在构建向量库时，会自动提取文档的各级标题（Header 1/2）并生成元数据。在对话开启的瞬间，中间件会读取当前挂载知识库的元数据，动态组装 System Prompt。
• 效果：如果用户关联的是《员工手册》，Agent 会自动设定人设为“HR助手”并知晓包含“休假、薪资”等主题；如果关联的是《API文档》，Agent 则立刻切换为“技术专家”。彻底解决了传统 RAG 系统提示词千篇一律、缺乏针对性的痛点。

3. 基于 Artifact 的透明化引用机制

• 利用 LangChain 这里的 content_and_artifact 特性，实现了检索结果的**“双轨制传输”**：

• 给 AI 看：将清洗后的纯文本内容传递给大模型，保证生成的准确性。
• 给用户看：将带有**相关性评分（Score）和元数据（Metadata）**的原始文档片段（Artifact）完整透传至前端。

• 前端不仅能展示 AI 的回答，还能像搜索引擎一样列出带有置信度的“参考来源”，极大地增强了系统的可解释性和用户信任度。

4. 双重切分与混合检索策略

• 在数据处理层，采用 MarkdownHeader切分 + 递归字符切分 的双重策略，既保留了文档的语义结构（章节归属），又控制了 Token 长度。结合 FAISS 高性能向量库与 DeepSeek-V3 强力底座，确保了在复杂文档场景下的高精度召回。

• 项目结构介绍

项目架构深度解析：基于 LangChain 1.1 的 Agentic RAG 系统

在构建复杂的 AI 应用时，良好的工程结构是成功的基石。本项目采用**分层架构（Layered Architecture）**设计，基于 FastAPI 框架和 LangChain 1.1+ 标准，实现了高内聚、低耦合的后端系统。

1. 项目目录结构全景图

首先，让我们通过目录树来俯瞰整个后端项目（backend/）的物理结构：

backend/├── .env                        # [配置层] 环境变量 (API Key, Base URL)├── requirements.txt            # [依赖层] 项目依赖库列表├── data/                       # [持久化层] 数据存储中心│   ├── uploads/                # 存放用户上传的原始 Markdown 文件│   └── vector_stores/          # 存放 FAISS 向量索引文件及 metadata.json└── app/                        # [应用核心层]    ├── __init__.py    ├── main.py                 # [入口] FastAPI 应用实例，CORS 配置，服务启动    ├── core/                   # [核心配置]    │   └── config.py           # 模型(LLM/Embedding)初始化单例，路径常量配置    ├── schemas/                # [数据契约]    │   └── api_schemas.py      # Pydantic 模型，定义前后端交互的 JSON 格式    ├── api/                    # [接口层]    │   └── endpoints.py        # 路由定义，处理 HTTP 请求与响应    └── services/               # [业务逻辑层] (核心大脑)        ├── file_service.py     # 负责文件清洗、切分、向量化、元数据提取        └── agent_service.py    # 负责动态 Agent 编排、Prompt 注入、工具绑定

2. 核心模块功能详解

我们将系统划分为四个关键层次，每一层都有明确的职责边界：

第一层：接口层 (API Layer)

• 文件：app/api/endpoints.py
• 职责：系统的“门面”。只负责接收 HTTP 请求、验证数据格式（通过 Schemas）、调用下层服务，并返回标准响应。
• 设计原则：不做业务逻辑。你不会在这里看到 LangChain 的代码，只会看到参数解析和函数调用。

第二层：业务逻辑层 (Service Layer) —— 核心大脑

这是本项目最厚重、含金量最高的部分：

• file_service.py (数据工厂)

• ETL 处理：读取 Markdown -> 提取 Header 元数据 -> 双重切分（Header + Character）。
• 向量化：调用 Embedding 模型生成向量。
• 兼容性保障：处理 Windows 路径问题，生成 index.faiss 和 metadata.json。

• agent_service.py (智能编排)

• 中间件逻辑：在运行时读取 metadata.json，动态生成 System Prompt。
• 动态工具绑定：利用闭包（Closure）在函数内部动态定义 retrieve_context 工具，并绑定当前的向量库。
• 执行与解析：运行 Agent，并解析复杂的 content_and_artifact 结构，分离出答案和引用来源。

第三层：核心配置层 (Core Layer)

• 文件：app/core/config.py
• 职责：管理全局单例。确保 DeepSeek LLM 和 OpenAI Embedding 模型只被初始化一次，避免重复开销。

第四层：数据契约层 (Schemas Layer)

• 文件：app/schemas/api_schemas.py
• 职责：定义“共同语言”。使用 Pydantic 严格定义了前端传什么（如 kb_name）、后端回什么（如 DocSource），确保前后端联调顺畅。

3. 数据流转全生命周期 (Data Flow)

当用户发起一次“关联知识库的对话”请求时，数据是如何流转的？

1. Request: 前端发送 POST /api/chat，携带 { “query”: “病假”, “kb_name”: “staff_kb” }。
2. Routing: main.py 接收请求，转发给 endpoints.py。
3. Validation: ChatRequest Schema 验证数据格式是否合法。
4. Service Invocation: 接口层调用 AgentService.chat_with_agent()。
5. Middleware Execution (AgentService):

• 加载 staff_kb/metadata.json，发现主题包含“休假制度”。
• 生成 System Prompt：“你是一个基于‘休假制度’知识库的助手…”。
• 加载 FAISS 索引，动态创建 retrieve_context 工具。

6. Agent Reasoning: DeepSeek 模型思考 -> 决定调用工具 -> 获得检索结果（含 Score）。

7. Response Construction: AgentService 解析执行结果，分离出 Answer 和 Artifacts。

8. Return: 接口层将结果封装为 JSON 返回前端。

9. 架构设计总结

• 模块化 (Modularity)：文件处理与对话逻辑完全分离，修改向量库逻辑不会影响 Agent 对话逻辑。
• 可扩展性 (Extensibility)：如果未来要换成 ChromaDB 或其他 LLM，只需修改 file_service.py 或 config.py，无需改动上层业务。
• 标准化 (Standardization)：严格遵循 FastAPI 和 LangChain 的最佳实践，代码清晰、易读、易维护。

这套架构不仅仅是教学演示，更是一个轻量级企业级 RAG 应用的标准模板。

• 核心代码解释

from typing import List, Optional, Tuplefrom langchain.tools import toolfrom langchain.agents import create_agentfrom langchain_core.messages import AIMessage, ToolMessagefrom langchain_core.documents import Documentfrom app.core.config import get_llmfrom app.services.file_service import FileServicefrom app.schemas.api_schemas import DocSourceclass AgentService:        @staticmethod    def chat_with_agent(query: str, kb_name: Optional[str], top_k: int) -> Tuple[str, List[DocSource]]:        """        Agentic RAG 主流程：        1. 动态加载 Metadata         2. 动态生成 System Prompt        3. 动态绑定 VectorStore Tool        """        llm = get_llm()        tools = []                # 默认 System Prompt        system_context = "你是一名乐于助人的AI助手，请直接回答用户的问题。用户可以上传文档，你会基于用户上传的文档知识进行回答。"        # === 中间件逻辑：如果有知识库，则注入上下文 ===        if kb_name:            vector_store = FileService.load_vector_store(kb_name)            if vector_store:                                # 1. 读取元数据，构建动态 Prompt                metadata = FileService.load_kb_metadata(kb_name)                topics = metadata.get("topics", [])                topics_str = "、".join(topics) if topics else"通用文档"                                system_context = (                    f"你是一名基于知识库【{kb_name}】的智能助手。\n"                    f"该知识库主要包含以下主题内容：**{topics_str}**。\n"                    "当用户的问题涉及到上述内容或细节时，请务必调用 retrieve_context 工具检索信息来回答。\n"                    "如果问题与知识库无关（例如闲聊），请用你的通用知识回答，并简要告知用户该问题超出了当前知识库范围。"                )                # 2. 定义绑定了当前 vector_store 的工具                @tool(response_format="content_and_artifact")                def retrieve_context(search_query: str):                    """Retrieve information to help answer a query."""                    # 使用 with_score 是为了给前端提供置信度，虽然 LLM 主要看 content                    docs_and_scores = vector_store.similarity_search_with_score(search_query, k=top_k)                                        # 序列化给 LLM 看 (仅文本)                    serialized = "\n\n".join(                        (f"Source: {doc.metadata}\nContent: {doc.page_content}")                        for doc, score in docs_and_scores                    )                                        # 构造 Artifact (包含分数，给前端用)                    artifacts = []                    for doc, score in docs_and_scores:                        # 兼容处理：确保 artifact 里存的是易于解析的对象或原始 Document                        # 这里我们存原始 Document 对象，稍后在外部解析                        # 为了携带 score，我们动态给 doc 加个属性，或者封装一下                        doc.metadata["score"] = float(score) # 将分数注入 metadata 方便携带                        artifacts.append(doc)                                        return serialized, artifacts                                tools = [retrieve_context]        # === 创建 Agent ===        # 使用 create_agent (LangChain 1.1 标准)        agent = create_agent(llm, tools, system_prompt=system_context)        # === 执行 Agent ===        messages = [{"role": "user", "content": query}]        response = agent.invoke({"messages": messages})                # === 解析结果 ===        # 从 response['messages'] 中提取最终回答和 Artifact        final_answer = ""        sources = []        if"messages"in response:            msg_list = response["messages"]                        # 1. 获取最后一条 AI 回复            last_msg = msg_list[-1]            if isinstance(last_msg, AIMessage):                final_answer = last_msg.content            # 2. 遍历获取 ToolMessage 中的 Artifact            for msg in msg_list:                if isinstance(msg, ToolMessage) and msg.artifact:                    for doc in msg.artifact:                        if isinstance(doc, Document):                            # 从 metadata 中取出我们刚才塞进去的 score                            score = doc.metadata.get("score", 0.0)                                                        sources.append(DocSource(                                content=doc.page_content,                                metadata=doc.metadata,                                score=score                            ))                return final_answer, sources    @staticmethod    def recall_test(kb_name: str, query: str, top_k: int) -> List[DocSource]:        """        召回测试 (不走 Agent，直接查向量库)        """        vector_store = FileService.load_vector_store(kb_name)        ifnot vector_store:            raise ValueError(f"Knowledge base '{kb_name}' not found.")                    docs_and_scores = vector_store.similarity_search_with_score(query, k=top_k)                results = []        for doc, score in docs_and_scores:            results.append(DocSource(                content=doc.page_content,                metadata=doc.metadata,                score=float(score)            ))        return results

模块一：动态上下文注入 (Dynamic Context Injection)

在 chat_with_agent 函数的开头，我们并没有使用写死的 Prompt，而是引入了一个“中间件”逻辑：

# === 中间件逻辑 ===if kb_name:    # 1. 实时读取磁盘上的元数据 (metadata.json)    metadata = FileService.load_kb_metadata(kb_name)    topics = metadata.get("topics", [])        # 2. 动态组装 System Prompt    system_context = (        f"你是一名基于知识库【{kb_name}】的智能助手。\n"        f"该知识库主要包含以下主题内容：**{topics_str}**。\n"        "..."    )

• 技术解读：

• 按需加载：只有当用户指定了 kb_name 时，系统才会去加载对应的向量库和元数据。
• Prompt 模板化：利用 Python 的 f-string，将提取到的 topics（如“薪资管理”、“API接口”）嵌入到系统提示词中。
• 价值：这让 Agent 具备了元认知能力。它知道自己“懂什么”，从而在回答问题时更自信，或者在遇到无关问题时能准确拒绝。

模块二：运行时工具绑定 (Runtime Tool Binding)

请注意 retrieve_context 函数定义的位置——它是在 chat_with_agent 函数内部定义的，而不是全局定义的。

# 在函数内部定义 Tool@tool(response_format="content_and_artifact")def retrieve_context(search_query: str):    # 这里直接使用了外部作用域的 vector_store 变量    docs_and_scores = vector_store.similarity_search_with_score(search_query, k=top_k)    # ...

• 技术解读：

• 闭包机制：这个 Tool 捕获了当前请求上下文中的 vector_store 和 top_k 参数。
• 隔离性：用户 A 的请求会生成一个绑定了 A 知识库的 Tool；用户 B 的请求会生成另一个。两者互不干扰，即使并发执行也不会串库。
• 动态挂载：tools = [retrieve_context] 这一行是在运行时决定的。如果没有知识库，tools 就是空的，Agent 自动退化为普通聊天模式。

模块三：双轨制数据流 (Content & Artifact)

我们在 @tool 装饰器中指定了 response_format=“content_and_artifact”，这是实现引用透明化的关键。

# 1. 给 LLM 看的 (Serialized)：纯文本，省 Token，易理解serialized = "\n\n".join(f"Source: {doc.metadata}\nContent: {doc.page_content}" ...)# 2. 给前端看的 (Artifact)：原始对象，带分数，结构化artifacts = []for doc, score in docs_and_scores:    doc.metadata["score"] = float(score) # 注入置信度分数    artifacts.append(doc)return serialized, artifacts

• 技术解读：

• Content (serialized)：这是喂给大模型的上下文。我们去掉了不必要的干扰信息，只保留文本和必要的元数据，帮助模型生成答案。
• Artifact (artifacts)：这是“副作用”数据。大模型看不到这个列表，但 LangChain 会把它保留在 ToolMessage 中。我们利用它将 相关性评分 (Score) 和 原始文档对象 透传给前端，用于渲染“引用来源”卡片。

模块四：标准化执行与解析 (Standard Execution & Parsing)

最后是 Agent 的执行和结果提取环节，这里体现了后端开发的严谨性。

# 1. 标准化创建 Agentagent = create_agent(llm, tools, system_prompt=system_context)# 2. 执行并获取完整消息历史response = agent.invoke({"messages": messages})# 3. 解析逻辑if"messages"in response:    msg_list = response["messages"]    # 提取回答：最后一条消息通常是 AI 的回答    last_msg = msg_list[-1]        # 提取引用：遍历寻找 ToolMessage 中的 artifact 字段    for msg in msg_list:        if isinstance(msg, ToolMessage) and msg.artifact:            # ... 转换为前端所需的 DocSource 格式 ...

• 技术解读：

• create_agent：这是 LangChain 0.2/0.3 (1.1+ API) 推荐的工厂函数，它屏蔽了底层的 Prompt 拼装细节（如 AgentScratchPad）。
• 消息回溯：由于 Agent 可能进行多轮思考（虽然 RAG 通常是一轮），我们需要遍历 messages 列表来找回 Tool 的执行结果（即 artifact）。这是获取检索来源最准确的方式，比正则匹配文本要可靠得多。

3.项目运行流程

• 下载源码并解压缩
• 安装后端依赖：

cd backendpip install -r requirements.txt

• 开启后端

python -m src.server

• 安装前端依赖

cd frontendnpm install

• 开启前端

npm run dev

如何学习AI大模型？

如果你对AI大模型入门感兴趣，那么你需要的话可以点击这里大模型重磅福利：入门进阶全套104G学习资源包免费分享！

这份完整版的大模型 AI 学习和面试资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】

这是一份大模型从零基础到进阶的学习路线大纲全览，小伙伴们记得点个收藏！

第一阶段： 从大模型系统设计入手，讲解大模型的主要方法；

第二阶段： 在通过大模型提示词工程从Prompts角度入手更好发挥模型的作用；

第三阶段： 大模型平台应用开发借助阿里云PAI平台构建电商领域虚拟试衣系统；

第四阶段： 大模型知识库应用开发以LangChain框架为例，构建物流行业咨询智能问答系统；

第五阶段： 大模型微调开发借助以大健康、新零售、新媒体领域构建适合当前领域大模型；

第六阶段： 以SD多模态大模型为主，搭建了文生图小程序案例；

第七阶段： 以大模型平台应用与开发为主，通过星火大模型，文心大模型等成熟大模型构建大模型行业应用。

100套AI大模型商业化落地方案

大模型全套视频教程

200本大模型PDF书籍

👉学会后的收获：👈

• 基于大模型全栈工程实现（前端、后端、产品经理、设计、数据分析等），通过这门课可获得不同能力；

• 能够利用大模型解决相关实际项目需求： 大数据时代，越来越多的企业和机构需要处理海量数据，利用大模型技术可以更好地处理这些数据，提高数据分析和决策的准确性。因此，掌握大模型应用开发技能，可以让程序员更好地应对实际项目需求；

• 基于大模型和企业数据AI应用开发，实现大模型理论、掌握GPU算力、硬件、LangChain开发框架和项目实战技能， 学会Fine-tuning垂直训练大模型（数据准备、数据蒸馏、大模型部署）一站式掌握；

• 能够完成时下热门大模型垂直领域模型训练能力，提高程序员的编码能力： 大模型应用开发需要掌握机器学习算法、深度学习框架等技术，这些技术的掌握可以提高程序员的编码能力和分析能力，让程序员更加熟练地编写高质量的代码。

LLM面试题合集

大模型产品经理资源合集

大模型项目实战合集

👉获取方式：
😝有需要的小伙伴，可以保存图片到wx扫描二v码免费领取【保证100%免费】🆓