离线私有化AI智能应用｜前后端分离 + Docker 容器化交付

离线私有化AI智能应用｜前后端分离 + Docker 容器化交付

项目成果

1. 项目langgraph的编排流，因为有巡逻机器人执行任务项目需求，就写了多个分支
2. 针对公司知识库助手项目，采用的内容检索不合格就多次重写（rewrite）的方式
3. 构建前端页面，将查询检索到最高分的内容在前端展示
4. 离线私有化 AI 智能应用｜前后端分离 + Docker 容器化交付
5. 基于 Langchain+LangGraph+MCP 的离线私有 AI Agent 智能调度系统
6. Ollama 驱动 Qwen2.5‑7B/BGE‑M3 实现无网络私有化部署

二、项目架构

项目架构

• 基于 Windows 开发环境搭建前后端分离架构，后端依托 LangChain+LangGraph+Flask框架，采用MCP协议实现AI Agent业务逻辑，前端使用 HTML+Live‑Server +Nginx 实现高效本地调试；
• 通过Ollama承载 Qwen2.5‑7B对话模型、BGE‑M3向量模型，实现完全离线私有部署，适配物理隔离无网络场景；
• 整体使用 Docker 容器化打包交付，降低研发迭代成本与现场部署实施成本。
• 采用LangGraph实现工作流编排，结合Agent和RAG技术构建完整对话流程。
• 适用典型场景：用户输入诉求→Agent意图识别→工具调用决策→结果路由→最终回复生成

2. 项目流程

• 核心路径：
  • 用户输入→Agent节点（意图识别）→条件边判断是否调用工具
  • 工具调用→路由判断（检索工具/计算工具）→文档评分/直接生成
  • 文档评分→相关性达标则生成回复，否则重写查询（最多循环3次）
• 关键节点：Agent节点：实现React模式的智能体，决策是否调用工具
  • 条件边：包含 tools_conditiontools判断和 、
  • 动态路由并行处理：支持多工具线程池并发执行（默认5线程）

项目技术

1. 核心功能（state）

1）状态图对话流程

• 五大节点：Agent节点：分析用户问题并决策工具调用
  • Tools节点：并行执行工具调用的枢纽
  • Grade节点：评估检索文档与问题的相关性
  • Rewrite节点：重写用户查询改进意图识别
  • Generator节点：生成最终回复内容
• 动态路由：工具路由：通过 tools_conditiontools
  • 实现调用决策结果路由： route_after_tools
  • 决定下一步流向文档路由： grade_documents
  • 控制重写或生成：rewrite / generate

2）工具调用并行处理

• 工具管理：
  • 动态路由：检索类工具自动路由到评分节点，其他直达generate节点
  • 配置类：通过ToolConfig管理工具列表和路由配置
• 并发机制：
  • 并行工具节点:ParalleTooINode，提高效率，相比串行执行提升3-5倍响应速度
  • 线程池(ThreadPoolExecutor)：实现多工具并行执行，默认5个工作线程
  • 使用线程池并行执行多个工具调用，提高效率，支持最大工作线程数配

3）会话存储记忆管理

• 数据库架构PostgreSQL和pgvector
  • 持久化：支持自动提交和连接状态监控
  • 连接池管理:使用ConnectionPool管理PostgreSQL数据库连接，支持自动提交、超时设置和连接池状态监控
• 记忆分级：
  • 长期记忆：通过PostgresSaver保存对话状态检查点跨线程持久化，通过PostgresStore存储用户记忆(store_memory)，支持记忆搜索和存储(如用户输入包含“记住”时保存)
  • 短期记忆：线程池内保存对话检查点（Immemory）
• 健壮性设计：
  • 故障转移：连接异常时自动切换备用数据源
  • 重试机制：数据库操作最多重试3次（基于tenacity库）

4）自然语言处理模板

• 语言模型：大模型通过get_llm获取对话模型(llm_chat)，嵌入模型：使用 llm_embedding，用于处理用户输入和生成回复
• 处理输入特征提示工程：四大模板：包含代理、重写、评分、生成专用模板
• 结构化输出：强制模型返回JSON格式结果（DocumentRelevanceScore），引入pydantic定义结果结构解析类，用于管理输出数据格式后端返回json格式化
• 消息过滤：仅保留最近5条AI和用户的对话记录，内容清洗：去除系统提示词等非对话内容

5）日志与错误处理

• 日志记录:使用logging模块和ConcurrentRotatingFileHandler记录详细日志(DEBUG级别)，支持文件轮转(SMB,3个备份)，后续可以自己实现日志归档
• 错误处理:多层次异常捕获(如数据库连接、工具调用、状态访问等)，记录错误并提供默认路由或提示用户

6）用户交互与响应输出

• 主循环:main函数实现交互式对话，用户输入后通过graph_response处理并输出响应，支持退出命令(quit、exit、q)
• 响应区分:区分工具输出(显示工具名称)和大模型输出(普通回复)，提升用户体验

引入langsmith 线上监测

辅助功能

• 可视化:通过save_graph_visualization将状态图保存为PNG文件，便于调试
• 配置管理:通过Config类统一管理日志文件路径、数据库URl、提示模板路径等配置

2.RAG 模块采用的检索优化方法

混合检索策略（多路信号加权融合）

• 融合BGE‑M3 向量余弦相似度（语义检索）、BM25 关键词检索、jieba 分词关键词匹配三路分数；
• 根据查询语句特征动态分配三路权重，比如查询带数字提高语义权重，长问句调整关键词权重，弥补纯向量检索对专有名词、编号、术语召回不足的问题。

动态权重自适应重排序 get_dynamic_weights

• 分析查询文本特征（数字、专业术语、标点、中文实体）自动调整语义、BM25、关键词三者权重，不是固定一套权重适配全部 query，提升不同类型问句的召回质量。
• 文档元数据管理与过滤检索，对每一个切片绑定完整元数据：doc_id、标题、文档分类、作者、chunk索引、更新时间；支持向量检索时增加where条件做元数据过滤，实现按文档类别、指定文档范围检索。

RAGAS效果评估体系

• 引入Ragas评估框架，支持Faithfulness、AnswerRelevancy、ContextRecall、SemanticSimilarity指标；
• Ragas 依赖不可用时，降级为 Embedding余弦相似度做召回评估，可量化 RAG 检索质量。

3.数据清洗与处理

1）文档切片与清洗优化

• 编写批量处理脚本，兼容 PDF、DOCX 等多种源文档格式，批量转换输出 Markdown；对转换后文本执行标准化预处理，过滤多余换行、分割标记、无效空白等噪声内容，提升后续文本分块与向量生成质量。
• 基于段落做分块，设置chunk_size=800、overlap=100上下文重叠；
• 增加超长切片二次分割逻辑，避免单块文本过大影响向量表达效果。

2）向量批处理容错

• 向量生成采用批量调用，捕获批次异常；
• 对生成向量失败的片段做降级跳过，不会因为个别文本异常导致整个入库流程中断；
• 校验向量返回数量和文档数量一致性，做数据校验。

3）结果去重机制

• 重排序之后对检索结果做文档 hash 去重，避免返回高度重复的文本片段，保证返回结果多样性。

4）文档增量 / 覆盖更新能力

支持按doc_id删除旧文档，单文件可覆盖更新向量库，不需要全量重建整个向量库；支持单文档入库、批量整体入库两套接口。

项目遇到的问题

windows系统开发遇到的坑

1.1跨域兼容性适配：Nginx 反向代理转发 MCP 协议流量

项目前期借助 Flask 跨域中间件处理前后端跨域，在 Linux 环境验证可用，切换到 Windows 开发环境后出现跨域兼容性故障。通过引入 Nginx 反向代理层做请求中转，对 MCP 协议流量做代理转发，将后端接口服务127.0.0.1:8012转发至Live‑Server 前端服务127.0.0.1:5501，规避浏览器同源策略限制，解决跨域问题。

参考方法和原理
https://blog.csdn.net/weixin_29294975/article/details/158835107

https://blog.csdn.net/ayang1986/article/details/127285533

1.2 容器化一键部署 PostgreSQL+pgvector

Windows 家庭版环境下PG原生exe安装困难，pgvector 手动部署流程繁琐，利用 Docker实现 PostgreSQL+pgvector 一键容器化部署，用于向量数据持久化存储。

结合业务场景选型对比：PostgreSQL 负责业务原始数据与向量知识库持久化存储，保证数据可靠性；后续优化要引入Redis 承担缓存、会话状态、分布式锁等高并发临时场景，冷热数据分层，兼顾数据可靠性与接口访问性能。

参考文献https://juejin.cn/post/7636343113468772386

1.3 跨平台依赖适配：处理 requirements.txt Windows 兼容问题

• 项目可通过requirements.txt一键批量安装依赖，但在 Windows 环境下部分原生包存在平台不兼容问题。依据 PyCharm 终端报错定位冲突依赖，对不兼容 Windows 的包进行注释处理，完成适配 Windows 环境的依赖安装；
• 同时部分依赖版本升级后会引发代码接口变更报错，结合终端异常信息，对受影响代码做手动调整、删减，保障项目在 Windows 平台正常运行。

2.总结：选择linux系统开发比较好，开发容易不遇到大bug

项目新需求

http://127.0.0.1:9000/patrol_rag_front_1.html  结果如下：