一、项目落地背景

日常远程接单中，很多中小企业行政、财务团队存在重复文档处理痛点：

海量 Excel、PDF、Word 文件依靠人工筛选、汇总、查询，操作重复、耗时久，手工统计极易出现数据错漏。

基于该需求，独立开发一套本地部署轻量化智能文档助手，融合 RAG 检索增强与 ReAct 智能体推理能力，不用部署云服务器，客户本地 Windows 电脑即可运行，自动完成表格批量处理、文档问答、数据报表生成，大幅降低办公重复人力成本。

整套项目单人独立完成需求拆解、前后端编码、智能体逻辑调优、Windows 环境兼容适配全流程开发交付。

二、完整技术栈拆解

后端核心 AI 框架

• LangChain 0.2.x：搭建 ReAct 智能体推理主架构，标准化封装结构化业务工具
• ChromaDB 本地向量库：实现离线文档向量存储、语义检索，保障本地文件数据安全
• 大模型能力：对接阿里云百炼 Qwen-plus API，提供自然语言问答、逻辑推理能力
• Web 服务：Flask 轻量框架搭建后端接口，支撑前端交互、任务进度推送

前端界面

React 框架开发可视化对话页面，包含对话交互窗口、文件目录展示、任务进度可视化组件，操作门槛低，非技术人员可直接使用

文档处理底层能力（Python）

• 多格式解析：PDF、Excel、Word 全类型文档自动读取、文本提取
• Excel 自动化工具：批量读取多表格、条件筛选、数据去重、字段匹配、报表导出
• Windows 环境兼容：修复中文路径、中文内容编码乱码、大文件内存溢出问题

三、系统整体功能模块

项目封装 7 套可自主调度的业务工具，智能体可根据用户提问自动选择工具执行，无需人工手动切换功能：

1. Excel 数据表智能分析
   支持批量读取本地文件夹内所有 xlsx 表格，根据自然语言指令完成数据筛选、统计、批量合并、重复数据清洗，自动输出汇总报表
2. PDF/Word 文档问答检索
   上传业务文档后，直接用自然语言提问，系统检索文档原文给出精准答案，无需人工翻阅长文件
3. 自动生成标准化业务报告
   基于表格、文档内原始数据，一键生成结构化文字报告
4. 邮件通知自动推送
   数据处理完成后，可调用工具自动生成内容并发送邮件通知相关人员
5. 本地文件目录浏览工具
   智能体可自主读取指定文件夹内全部文档，识别文件类型、自动重命名归类
6. 超大文件自适应读取工具
   区分小文件 / 大文件两套文本提取策略，平衡信息完整性与运行性能
7. 全流程任务进度可视化
   前端实时展示文档解析、向量入库、检索、推理每一步进度，客户直观掌握运行状态

四、核心架构：ReAct 智能体 + RAG 检索增强

1.ReAct 自主推理调度

基于结构化工具封装，智能体可理解用户复杂问题，自主判断需要调用哪一套文档工具，多轮循环执行多步骤任务。
示例：用户提问「找出 9 月业绩不达标的供应商」，智能体自动执行：读取 Excel 文件→筛选对应月份数据→提取目标商户名称→返回对话结果，全程无需人工分步操作。

2.RAG 本地向量检索

文档上传后自动拆分文本、向量化存入本地 ChromaDB；用户提问时先检索文档原文，再结合大模型生成答案，杜绝 AI 幻觉，回答全部基于本地真实业务文件。

3.本地离线运行设计

所有文件数据保存在客户本地电脑，不上传第三方云端，适配企业内部敏感财务、供应商数据场景，无服务器部署成本。

五、开发过程踩坑与优化方案

1.Windows 中文编码、中文路径报错

初期读取带中文名称 / 中文目录的 Excel、PDF 直接崩溃，统一文件读取编码为 utf-8-sig，路径做转义兼容，完整适配 Windows 系统。

2.超大文件内存溢出、推理卡顿

设计动态文本截断策略：10MB 以内文档完整提取文本；超大型文件自动切换精简提取模式，限制单次读取行数，解决内存占用过高、程序崩溃问题。

3.ReAct 智能体无限循环推理

优化循环终止判定逻辑，增加最大执行轮数限制、结果校验机制，避免大模型陷入无意义重复工具调用，提升系统稳定性。

4.中文文档语义检索精度不足

针对中文办公文本微调文本分割块大小、向量检索相似度阈值，大幅提升表格、PDF 业务内容匹配准确率。

5.多 Excel 批量处理逻辑繁琐

封装通用表格处理工具类，支持自定义字段匹配规则，客户可按需新增筛选、统计逻辑，工具可快速迭代扩展。

六、接单落地经验

1.中小企业办公类 AI 工具，优先做本地轻量化交付，客户不用承担服务器、云存储费用，接单竞争力更强；

2.AI Agent 类项目交付时，一定要配套可视化 Web 界面，纯脚本交付客户使用门槛高，可视化界面能大幅提升客户满意度、复购率；

3.代码合规把控：项目全程自主重构核心逻辑，不直接使用 GPL 传染性开源代码片段，避免商用交付版权风险；

4.每完成一款垂直场景 AI 工具，复盘技术细节发布社区，既能完善个人技术作品背书，也能提升平台派单匹配权重，更容易接到 AI 开发、自动化脚本类订单。

这套本地 RAG+ReAct 文档智能助手，适配财务、行政、供应链等多中小企业办公场景，可按需迭代新增表格处理、文档问答能力。

有 Python AI Agent、LangChain 开发、办公自动化接单相关问题，欢迎评论交流，后续持续分享远程 AI 项目落地实战干货。