企业知识库智能问答 Agent（React + Nest）

资料获取

百度网盘（本文档及配套资料）

分享名称：agent项目react+node
链接：https://pan.baidu.com/s/1Hj0NHtioPG2HNBIR97vPRg?pwd=1234
提取码：1234

网盘内另有 《代码仓库地址.md》，用于克隆前后端源码。建议先读本文了解项目，再按该文档拉代码。

一、项目是什么

这是一套企业知识库智能问答 演示系统：员工登录后，可针对已授权的知识库提问（差旅报销、制度条款等），系统通过 RAG（检索增强生成） 从文档片段中找依据再回答，并展示引用来源；查不到依据时会拒答，不瞎编。

在 RAG 之外，系统还演示了 Agent 工程里常见的进阶能力：

LangGraph 意图分叉：制度问题走检索问答，工单/订单走 Tool
SSE 流式输出：回答逐字显示
多轮会话：左侧会话列表，历史落 Postgres
Redis 限流：同一用户每分钟最多 20 次提问
HITL 人机审核：「关闭工单」类高风险写操作需人工点同意后才执行

整体定位是简历 / 面试可演示的完整链路，而不是只调一次大模型 API。

二、架构概览

text 复制代码

浏览器  React + Vite  :5173
    │  fetch + Cookie（Vite 代理 /api → Nest）
    ▼
Nest.js  :8787
    ├── JwtGuard 登录鉴权、KbGrant 知识库授权
    ├── 知识库 CRUD、文档上传、分块索引
    ├── AgentService（LangGraph 图 + SSE 流式）
    ├── Postgres + pgvector（用户、库、文档、向量、会话）
    └── Redis（限流计数；图 checkpoint 用 MemorySaver）
    ▼
外部 API
    ├── DeepSeek（聊天，deepseek-v4-flash）
    └── 通义 / OpenAI 兼容（Embedding，如 text-embedding-v3 1024 维）

前后端两个独立工程、两个终端进程 ：前端只写页面，后端写接口与 AI 逻辑；模型 Key 只放在后端 .env，不进前端。

三、技术栈

层级	技术
前端	React 19、Vite 6、TypeScript、Ant Design 6、React Router
后端	Nest.js 11、tsx 热重载、Prisma 7 + `@prisma/adapter-pg`
AI	LangChain、LangGraph、ChatOpenAI（DeepSeek 兼容）
数据库	PostgreSQL 16 + pgvector（业务表与向量同库）
缓存	Redis 7（限流）
容器	Docker Compose（postgres、redis）

四、已实现功能（Demo 清单）

阶段	能力	简要说明
登录	Cookie + JWT	admin / staff 角色，知识库按授权过滤
知识库	CRUD	建库、改名、删除
文档	上传 md/txt	预览、抽屉全文
索引	分块 + Embedding + pgvector	建立索引、debug-search 调试检索
RAG	retrieve → generate	引用片段、无依据拒答
会话	左右布局	新建 / 改名 / 删除会话，消息落库
SSE	流式问答	逐 token 渲染，Vite 代理关闭 SSE 缓冲
Tool	意图分叉	查工单 T-1001、订单 O-9001
Redis	限流	超限返回 429
HITL	关闭工单审批	先 pending，点同意再执行关闭

未做完或可选：Compose 一键部署、trace 与评测表等。

五、LangGraph 意图图（核心逻辑）

text 复制代码

START → route（识别 rag / tool / hitl）
          ├─ rag  → retrieve → generate → END
          ├─ tool → lookup   → summarize → END
          └─ hitl → hitl（待审批提示）→ END

关闭工单：用户点「同意」→ 调用 resume 接口 → 真正关闭工单

路由规则示例：

含「关闭工单」+ T-xxxx → hitl（不直接改数据）
含「工单 / 订单 / T- / O-」→ tool
其余 → rag（向量检索 + 生成）

克隆前端工程后，可在其 docs/demo-LangGraph-编排写法.md 查看 StateGraph 写法说明。

六、目录结构

text 复制代码

knowledge-base-agent-node-nest/          # 后端
  src/
    agent/          AgentService、LangGraph、Tool、SSE
    auth/           登录、JWT Guard、KbGrant
    knowledge-base/ 知识库、上传、ingest、pgvector
    prisma/         schema、migrate、seed
  docker-compose.yml
  .env.example

knowledge-base-agent-react-web/          # 前端
  src/pages/
    LoginPage/      登录
    ChatPage/       对话台（会话 + SSE + HITL 按钮）
    KbPage/         知识库与文档、索引、debug-search
  docs/             按 Demo 顺序的逐步开发文档
  vite.config.ts    /api 代理到 :8787

七、本地快速启动

7.1 环境要求

Node.js 20+
Docker Desktop（Postgres + Redis）
yarn

7.2 第一次初始化（做过可跳过）

按网盘内《代码仓库地址.md》克隆代码后：

powershell 复制代码

cd knowledge-base-agent-node-nest
copy .env.example .env
# 编辑 .env：DATABASE_URL、AUTH_SECRET、DEEPSEEK_API_KEY、EMBEDDING_* 等

docker compose up -d postgres redis
yarn install
yarn prisma:migrate
yarn prisma:seed

.env 要点：

聊天：DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL（DeepSeek 仅 chat，不能当 embedding）
向量：EMBEDDING_API_KEY、EMBEDDING_MODEL（如通义 text-embedding-v3，1024 维）；入库与检索必须用同一模型和维度

7.3 日常启动（四个步骤）

打开 Docker Desktop
在后端目录执行 docker compose up -d postgres redis
两个终端分别在后端、前端目录 yarn start（:8787、:5173）
浏览器打开 http://localhost:5173/login

账号	密码	用途
staff@corp.com	staff123	对话台 `/chat`
admin@corp.com	admin123	知识库 `/admin/kb`

健康检查：http://localhost:5173/api/health → "ok": true

7.4 演示验收建议

上传 docs/samples/差旅报销.md，建立索引
问「一线城市住宿上限」→ 有引用、能答
问「查工单 T-1001」→ 笔记本 / 张三
问「关闭工单 T-1001」→ 待审批 → 点同意 → 再查 status 为 closed
同一账号连续提问 20+ 次 → 出现「太频繁」

八、主要 API（节选）

方法	路径	说明
POST	/api/auth/login	登录，Set-Cookie
GET	/api/kb	知识库列表
POST	/api/kb/:id/documents	上传文档
POST	/api/kb/:id/index	建立向量索引
GET	/api/agent/sessions	会话列表
POST	/api/agent/stream	SSE 流式问答
POST	/api/agent/resume	HITL 审批关闭工单

前端一律 fetch(..., { credentials: "include" })，经 Vite 代理访问 Nest。

九、与「对照仓」的差异

同类项目 kb-agent-platform 采用 Next.js 网关 + 独立 Agent 进程 。本系统刻意做成 React + Nest 两个工程：鉴权、数据库、LangGraph 都在 Nest 里，少一层 HTTP 转发，更适合按 Demo 文档从零手写、面试时讲清每一层职责。

十、延伸阅读（克隆前端后，见 `docs/` 目录）

文档	内容
demo开发手册.md	总路线与验收清单
快捷启动.md	每次开项目的四步
postgres使用手册.md	库、Prisma、pgvector
demo-05-RAG问答.md	RAG 图与拒答
demo-06-SSE多轮.md	流式与代理配置
demo-07-意图与Tool.md	工单 / 订单分叉
demo-08-Redis.md	限流与 MemorySaver
demo-10-HITL.md	关闭工单人机审核

本文档随项目迭代更新；源码请按网盘内《代码仓库地址.md》获取。

企业知识库智能问答 Agent（React + Nest）