知衍 AI：基于 LangGraph ReAct Agent 的知识管理平台

一、项目概述

知衍 AI 是一个以 AI Agent 驱动的知识管理平台，核心理念是"导入 → 进化 → 游戏化学习 → 可视化"的闭环。用户可以将任意文本、网页、图片、视频素材导入平台，由 AI Agent 自动将原始素材进化为结构化文档，再通过 3 种游戏类型和 3D 知识图谱实现深度掌握。平台同时支持团队协作、四级权限模型和双币种虚拟经济体系。

系统后端采用 FastAPI 异步框架，约 10,000 行 Python 代码，前端为 Vue 3 SPA 单页应用，约 15,000 行。适用于个人知识管理、团队学习协作、教育资源整理等场景。

二、技术架构

Nginx (反向代理 + 静态服务)
  └── frontend/dist (Vue 3 SPA)
         │
    FastAPI 后端
  ┌─────────────────────────────────┐
  │  LangGraph Agent 层              │
  │  ├── 素材问答 Agent              │
  │  ├── 智能客服 Agent              │
  │  ├── 游戏出题 Agent              │
  │  └── 知识进化 Agent              │
  ├─────────────────────────────────┤
  │  业务层 (团队、货币、认证)         │
  ├─────────────────────────────────┤
  │  基础设施层                       │
  │  ├── BGE-M3 向量嵌入 (1024维)     │
  │  ├── 多媒体处理 (FFmpeg + OCR)    │
  │  ├── MCP 协议网页抓取             │
  │  └── 混合检索 (Milvus + 关键词)   │
  └─────────────────────────────────┘
         │
    Docker 托管服务 (可选)
  Redis | Elasticsearch | RabbitMQ | Milvus

技术选型说明：FastAPI 提供异步 HTTP 和 WebSocket 的原生支持，配合 httpx 异步客户端，整个请求链路从 API 到 LLM 调用均为非阻塞。SQLite 作为嵌入式数据库实现了零配置部署，无需独立数据库进程。LangGraph 的 create_react_agent 作为统一的 Agent 框架，DeepSeek 作为 LLM 后端，通过 langchain_deepseek 的 ChatDeepSeek 封装调用。BGE-M3 提供 1024 维向量嵌入，支持 ONNX 运行时加速，在 CPU 环境下推理速度提升 3-5 倍。Milvus Lite 实现本地嵌入式向量存储，同样无需独立服务进程。

三、核心功能模块

3.1 知识素材管理

支持 5 种素材导入方式：文件上传（TXT、Markdown、PDF、Word）、文本粘贴、网页抓取、图片 OCR、视频文字提取。网页抓取通过 MCP 协议或 httpx 直接抓取实现，图片通过 PaddleOCR 进行文字识别，视频通过 FFmpeg 提取关键帧后进行 OCR 和音频转写。所有素材统一转为文本格式，入库后自动分类、状态追踪（pending→processing→ready→error），支持重试和删除。

设计上，多媒体处理对上层完全透明——无论素材是什么格式，Agent 和业务逻辑只看到统一的文本内容，降低了后续模块的复杂度。

3.2 AI 知识进化

支持自动进化和人工审核两种模式。自动进化由 LangGraph ReAct Agent 执行四步流水线将原始素材转化为结构化 Markdown 文档。人工审核模式下，Agent 生成进化建议，用户在审核界面逐条确认或修改后应用。进化历史支持版本追溯，每次进化都会保存新旧内容的完整记录。

3.3 游戏化学习

3 种游戏类型 × 3 级难度：知识点卡片对对碰（闪卡记忆）、知识大富翁（棋盘闯关）、智识对弈（概念配对）。题目由 AI Agent 从素材中自动生成，每道题包含题目描述、4 个选项、正确答案、解释说明和知识点主题。游戏结果持久化存储，支持积分和经验累积，与虚拟经济系统联动。

3.4 3D 知识图谱

基于 ECharts GL 的 3D 力导向图，将知识点之间的关联关系以三维节点和连线形式呈现。支持节点自由拖拽、缩放、旋转、主题筛选和掌握度评分色阶。在连线计算上做了特殊优化——通过 Map 去重过滤掉自环引用、零权重关系、重复连线和极短连线，确保图谱清晰可读，避免无效信息的视觉干扰。

3.5 智能客服

基于平台内置帮助文档（7 大类 30+ 篇文章）的智能客服，覆盖快速开始、知识库、进化、游戏、图谱、账号设置、使用规范等所有功能模块。对话支持 SSE 流式逐 token 输出，用户提问后立即看到检索匹配结果，然后逐字显示回答，体验接近实时对话。架构上采用预检索 + Agent 补充检索的混合模式——先通过关键词匹配快速命中目标文章，再由 Agent 判断是否需要补充检索，兼顾了响应速度和回答质量。

3.6 团队协作与虚拟经济

团队功能支持创建、邀请成员、角色分配。四级权限模型覆盖个人数据隔离和团队三级角色（owner 拥有管理权、admin 拥有内容管理权、member 拥有查看和参与权）。虚拟经济采用双币种体系——学识币用于日常消费（AI 问答、OCR、视频转写等），真知晶用于高级功能（知识进化、游戏生成）。每日配额按操作类型独立计算，商店系统支持道具购买，形成"使用→消耗→购买→使用"的良性循环。

四、重点技术实现

4.1 AI Agent 统一架构：LangGraph ReAct

项目最初采用固定流程调用 LLM（“伪 Agent”），即代码里预先写好调用顺序和参数，LLM 只是被动执行。这种方式无法应对多样化的知识处理场景——比如素材问答中，有些问题一句话就能回答，有些需要检索全文，有些需要多次从不同角度检索，固定的调用流程无法覆盖这些变化。

为此，项目经历了从固定管线到自研 AgentRuntime（260 行 ReAct 循环），再到全面迁移到 LangGraph 的架构演进。LangGraph 的 create_react_agent 提供了标准化的 ReAct 模式——LLM 在"思考→行动→观察→思考"的循环中自主决策：何时调用工具、调用哪个工具、用什么参数、是否需要再次调用。迁移后，四个 Agent 共享同一套基础设施（LLM 构建、步骤提取、回答提取），通过不同的工具集和 System Prompt 实现差异化业务逻辑，代码量大幅减少的同时获得了框架内置的流式输出、消息历史管理、工具调用追踪等能力。

4.2 知识进化：四步流水线 + 双重审核 + 智能重试

这是项目中最复杂的 Agent。直接让 LLM 一次性生成完整文档容易出现结构混乱、知识点遗漏、与原文雷同度过高等问题。因此将进化过程拆解为四个独立步骤，每步由 LLM 独立完成，有明确的输入输出约束：

• 分析（analyze）：提取主题、关键知识点、知识缺口、术语、质量问题
• 扩展（expand）：补充定义、原理机制、概念关系、示例、应用场景、注意事项
• 撰写（compose）：基于前两步的分析和扩展结果，生成结构化 Markdown 文档
• 审核（review）：双重校验，确定性规则检查 + AI 评分

审核阶段是质量保障的核心。确定性规则检查包括：计算原文与进化文档的相似度（通过 SequenceMatcher 算法，相似度过高则判定为简单改写而非真正进化）、检查 Markdown 结构是否有 4 个以上标题、是否包含示例和应用章节、是否包含边界和注意事项章节。AI 审核则由 LLM 独立评分（0-100）并输出问题列表。两者都通过才视为合格。

当审核未通过时，系统根据 issues 类型智能回溯到对应步骤重试——覆盖不足则重新扩展→撰写→审核，结构问题则重新撰写→审核，最多 3 轮。这种设计避免了全盘重来的效率浪费。

LLM 输出的 JSON 经常出现截断、格式错误等情况，项目中实现了 3 层容错解析：标准 JSON 解析 → 截断 JSON 修复（通过逐字符跟踪引号配对状态，精确截断到最后一个完整字符串，补上缺失的括号）→ 激进修复（切掉不完整行，补括号）。这种逐层 fallback 在实际部署中极大提升了稳定性。

4.3 游戏出题：LLM 自检验证 + 多层解析

游戏出题 Agent 需要 LLM 从素材中生成题目，并确保格式正确。核心挑战是 LLM 输出的 JSON 格式多变，有时包裹在 markdown code fence 中，有时带有前置说明文字，有时 JSON 结构不完整。

设计上让 LLM 在生成题目后调用验证工具自检——验证失败则根据错误信息修正后重新生成，形成"生成→验证→修正"的自我纠错循环。题目 JSON 解析采用 3 层策略应对各种非标准格式：先尝试提取 markdown code fence 中的内容，再通过括号匹配定位 JSON 边界，最后用正则表达式兜底。题目后处理包含自动推断素材来源（通过关键词匹配计算题目主题与各素材的相似度）、去重、干扰项校验（不能与答案相同，最多 3 个）。

4.4 混合检索体系

检索体系覆盖了"语义检索→关键词匹配→全文检索"三个层次，并设计了多级 fallback 确保系统在任何情况下都能提供基本可用性。

BGE-M3 向量嵌入：1024 维归一化向量，支持 torch、ONNX、OpenVINO 三种运行时后端。ONNX 模式在 CPU 上有 3-5 倍的推理加速，对生产环境更友好。模型通过懒加载单例模式管理，首次使用时加载，后续请求复用。

Milvus 向量存储：通过 Milvus Lite 本地嵌入式部署，用于游戏出题的知识点向量匹配——通过语义相似度将题目与知识点进行关联，实现智识对弈游戏的配对逻辑。

多级 Fallback：Agent 不可用或 API Key 未配置时，系统自动降级为本地关键词匹配检索。这种设计确保了即使没有外部 API 依赖，所有核心功能仍然可用。

多媒体素材处理管线：图片通过 PaddleOCR 进行文字识别，视频通过 FFmpeg 提取关键帧后进行 OCR 和音频转写，网页通过 MCP fetch 协议或 httpx 直接抓取后清洗 HTML。所有素材统一转为文本后纳入检索和进化流程，对上层 Agent 完全透明。

4.5 权限与虚拟经济

认证采用 JWT 双 token 机制——Access Token 有效期 30 分钟，Refresh Token 有效期 7 天，兼顾安全性和用户体验。JWT 的 payload 支持 team_id 字段，用户可在个人身份和团队身份间自由切换，API 根据当前身份返回对应的数据范围。

四级权限模型覆盖个人数据隔离和团队三级角色，数据访问层通过 SQL 查询中的 user_id 和 team_id 条件实现权限过滤。

双币种虚拟经济体系中，学识币用于日常操作（AI 问答 10 次/天、素材问答 5 次/天、OCR 3 次/天、视频转写 1 次/天），真知晶用于高级功能。每日配额按操作类型独立计算，配额消耗后可通过学识币购买额外次数。商店系统提供道具购买功能，形成完整的虚拟经济闭环。这种设计将 API 调用成本与用户行为挂钩，既控制了资源消耗，又培养了用户合理使用资源的习惯。

五、部署与运维

5.1 一键部署

项目提供了完整的 Ubuntu 一键部署脚本，覆盖 12 个步骤：系统依赖安装（Python 3.10、Node.js 22 LTS、Nginx、FFmpeg）→ Python 虚拟环境创建和依赖安装 → Systemd 服务配置实现开机自启和自动重启 → 前端 pnpm 依赖安装和 Vite 生产构建 → Nginx 配置和启动。部署后自动生成 .env 配置文件，BGE-M3 int8 ONNX 模型随压缩包分发，无需联网下载大体积模型文件。

5.2 Systemd 服务管理

后端通过 Systemd 服务实现进程守护，配置了 Restart=always 和 RestartSec=5 确保异常退出后 5 秒自动重启。日志输出到 journald，支持 journalctl -u zhiyan-backend -f 实时查看。

5.3 Nginx 配置

Nginx 同时承担反向代理和静态资源服务两个角色。前端静态资源配置 30 天缓存（Cache-Control: public, immutable），开启 Gzip 压缩减少传输体积。API 请求反向代理到本地 8000 端口，支持 WebSocket 协议升级（用于进化进度的实时推送）。SPA 路由回退配置确保前端路由刷新后正确返回首页。

5.4 Docker 基础设施

可选 Docker 服务采用懒加载模式——按需连接，连接失败不影响核心功能。Milvus Standalone 通过三容器部署（etcd 元数据存储 + MinIO 对象存储 + Milvus 向量引擎），Redis 提供缓存加速，Elasticsearch 提供全文检索，RabbitMQ 提供消息队列。所有服务均支持环境变量配置开关，未配置时系统使用本地 fallback 方案。

5.5 环境变量体系

通过 .env 文件管理所有配置，覆盖 AI API 密钥、模型路径、运行时后端、向量存储开关、多媒体处理参数、网页抓取超时等数十项配置。支持 HF_ENDPOINT 镜像源配置，适配国内网络环境下 HuggingFace 模型的下载。Agent 模块通过 AGENT_* 系列环境变量实现独立开关，方便调试和灰度发布。

六、总结

知衍 AI 是一个从"伪 Agent"到真正 LangGraph ReAct Agent 的完整架构演进实践。项目规模不大（约 25,000 行代码），但覆盖了 AI Agent 开发中遇到的大部分典型问题，其中的几个设计思路值得分享：

1. Agent 自主决策优于固定流程：将"什么时候检索、检索什么、检索几次"的决策权交给 LLM，而非硬编码，使系统能灵活应对多样化的知识处理场景。这也是 Agent 的核心价值所在——不是让 LLM 替代代码，而是让 LLM 来编排代码的执行。

2. 双重审核 + 智能回溯重试：确定性规则检查与 AI 评分的组合审核，以及根据审核结果精准回溯到对应步骤重试的机制，在实践中证明比单纯的"通过/不通过"判断更有效。它既利用了规则的可解释性和确定性，又利用了 AI 的语义理解能力。

3. 多层容错是生产环境的必需品：JSON 解析的 3 层 fallback、检索的多级降级、Agent 失败时的自动回退——这些在开发阶段看似"过度设计"的容错机制，在实际部署中却是系统稳定性的基石。LLM 的不可靠输出特性决定了容错设计不是可选项，而是必选项。

4. 多媒体素材的统一抽象：将图片、视频、网页统一转为文本，对上层业务透明。这种抽象层的设计思想可以推广到其他多模态 AI 应用场景。

5. "核心功能可用 + 基础设施按需接入"的架构理念：SQLite + Milvus Lite 的本地嵌入式方案实现了零配置部署，同时保留了接入 Redis、ES、RabbitMQ 等生产级服务的扩展能力。这种架构让项目在开发演示和生产部署之间无缝切换，非常适合中小型 AI 项目的技术选型。