基于 FastAPI 的多模型智能代理 + RAG 文档处理系统

1. 立项背景和目标：工程类文档（合同/标书/竣工资料）模板化强、条款重复多、人工撰写耗时。项目目标是构建一个多模型协同的 AI Agent 平台，自动完成"文档摄取—检索—生成—后处理"的闭环，降低人工撰写与合规审查成本，并通过 RAG 复用历史文档知识。

2. 软件功能和核心模块：
Agent 调度器 scheduler.py：任务规划、工具调用、记忆与反思。
RAG Pipeline（8 个可插拔 Harness）：H1 文档摄取 → H2 清洗分块 → H3 向量化入库 → H4 查询解析 → H5 混合检索 → H6 重排序 → H7 生成 → H8 后处理 pipeline.py。
工具集 tools/：OCR、长文 QA、合同风险分析、图片/视频/PPT 生成、任务规划。
API 网关、存储、对话管理、用户认证 等支撑模块。
Web 界面 static/：对话、上传、思考过程展示。

3. 业务流程与功能路径：
文档入库路径：上传文件 → /pipeline/ingest → H1 解析（电子 PDF / OCR 扫描件 / Word）→ H2 章节优先分块（512 字符 + 50 字重叠）→ H3 bge 嵌入写入 Milvus。
查询生成路径：用户请求 → /pipeline/query → H4 DeepSeek 解析意图(JSON) → H5 向量(0.7)+BM25(0.3)融合召回 → H6 MiniMax 重排 → H7 DeepSeek 生成 → H8 结构校验/脱敏/Word 导出。
反馈闭环：人工修订后通过 /pipeline/feedback 重新入库，知识库持续迭代。

1. 整体架构与设计思路：采用"网关—调度—Pipeline—工具"四层解耦架构。模型调用统一收敛到 api_gateway.py，Pipeline 以 PipelineContext 数据类在各 Harness 间流转上下文，Harness 之间通过显式依赖注入（如 H5 持有 H3 句柄）实现可插拔。技术栈分层：Web 层 FastAPI；解析层 pdfplumber/PaddleOCR/python-docx；检索层 pymilvus(HNSW M=16, efConstruction=200) + rank_bm25；生成层 SiliconFlow 多模型；存储层 Milvus + 本地文件 + JSON；鉴权层 bcrypt + Bearer Token。

2. 模块与结果（量化）：
8 个 Harness，按章节分块后典型文档 chunk 数量在数百级；嵌入维度 1024，IP 内积。
工具集 9 个（DeepSeek 3 / Qwen 5 / MiniMax 2 等，含 OCR、QA、风险分析、图片/视频/PPT 生成）。
测试 12/12 通过（DeepSeek 3、MiniMax 2、Qwen 5、Scheduler 2）， 已沉淀约 240+ 份真实工程文档（docx/doc/xlsx/pdf/jpg）作为知识源， 集合已积累多版本 WAL 数据。
支持 4 类文档类型：合同、技术方案、竣工资料、工程报告。

3. 难点与解决方案：
扫描件 PDF 无法直接取文本：H1 内置 PaddleOCR 兜底，并对 PDF 转 image 后识别；同时设 KMP_DUPLICATE_LIB_OK=TRUE 规避 Paddle 与 MKL 的 FORTRAN 冲突崩溃。
分块破坏章节语义：H2 优先按章节标题层级切分，失败再退化为滑动窗口，并构建 HierarchyNode 层级树保留上下文。
单一检索召回不准：H5 用向量(0.7)+BM25(0.3)融合，H6 再用 MiniMax 段落评分重排，提升精度。
生成模型 JSON 不稳定：H4 对 DeepSeek 输出做容错解析与意图回退。
xlrd 与 textract 版本冲突：注释掉 textract，保留 openpyxl/xlrd 单独处理 xlsx。
前端缓存导致界面不更新：在 main.py 加 no-cache 中间件兜底。