# agent_work_plus

**Repository Path**: luotianhang/agent_work_plus

## Basic Information

- **Project Name**: agent_work_plus
- **Description**: 公司AI行政助手，开除公司行政不在是梦
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能 Agent 网页版

基于 **MiniMax-M2.7** 大模型 + **Qwen3-VL-Embedding-2B** 本地多模态向量模型构建的智能 Agent。
所有操作（对话、导入文档、知识库管理、原文预览/下载）全部在网页上完成。

## 四大核心能力

| 能力 | 说明 |
|------|------|
| 💬 对话 | 自然语言多轮对话 |
| 🧠 记忆 | 内存会话记忆，记住上下文 |
| 🛠️ 工具调用 | 计算器、当前时间、天气查询、知识库检索 |
| 📚 RAG | 多通道检索：文字向量 + 图片视觉向量 + 图片 OCR 文本 |

## 文档抽取与检索增强（亮点）

为了让"知识被完全利用"，文档导入会同时走三条管道：

1. **文字结构化抽取**（[document_parser.py](document_parser.py)）
   - **PDF**：PyMuPDF 抽文字、**表格**、**超链接**、**目录书签**
   - **DOCX**：段落 + 表格 + **页眉页脚** + **文本框** + **脚注/尾注**
   - **PPTX**：所有 shape（含分组递归）+ 表格 + **图表 chart** + **备注页 notes**
   - **XLSX**：工作表 + **单元格批注**
2. **图片视觉向量化**：PDF 整页、DOCX/PPTX/XLSX 嵌入图全部送入 Qwen3-VL embedding，让"图本身"被文字 query 召回
3. **图片 OCR 文字**：每张图（PDF 整页 + 嵌入图）跑 RapidOCR，识别文字作为单独 chunk 入库并挂图片路径，扫描件 PDF、流程图标注、截图里的字都能被纯文字检索命中

切片用**语义切片**（按段落 → 标点 → 不在词中间切断），相邻片有 overlap，避免等宽硬切丢上下文。

## 原文链接与下载

每次回答附带：
- **🔗 原始文档链接**（Streamlit 静态服务）— 点击新标签打开
  - PDF：浏览器内置阅读器预览，URL 带 `#page=N` 锚点**自动跳到命中页**
  - 图片：直接预览
  - Office / CSV：触发下载，本地用 Office/WPS 打开
- **⬇ 下载按钮**：兜底直接下载原文件
- **📎 相关文档页面**：命中的 PDF 整页图、DOCX/PPTX 嵌入图等也直接展示出来

## 技术栈

- **核心编排**：LangGraph
- **向量数据库**：Chroma（本地持久化）
- **Embedding**：本地 Qwen3-VL-Embedding-2B（2048 维多模态，离线）/ 备用 fastembed BGE
- **OCR**：RapidOCR (ONNX，CPU)
- **对话记忆**：纯内存（按会话保留）
- **前端界面**：Streamlit（含静态文件服务）
- **大模型**：MiniMax-M2.7（OpenAI 兼容接口）
- **文档解析**：PyMuPDF / python-docx / python-pptx / openpyxl
- **GPU 加速**：PyTorch 2.11.0+cu128，内置 RTX 5090（sm_120）支持

## 项目结构

```
agent_work_plus/
├── config.py              # 全局配置（API、模型、Embedding 后端、RAG/OCR/图文 参数）
├── tools.py               # 工具集（计算器/时间/天气/知识库检索）
├── document_parser.py     # 多格式抽取（pdf/docx/pptx/xlsx/csv/txt/md → text + images）
├── ocr_utils.py           # RapidOCR 单例封装
├── knowledge_base.py      # RAG 知识库（Chroma + 三通道入库 + 语义切片）
├── agent_core.py          # LangGraph 编排核心（对话+工具循环+记忆）
├── app.py                 # Streamlit 前端（对话 + 知识库管理 + 原文链接）
├── ingest.py              # 命令行批量导入
├── test_agent.py          # 端到端测试脚本
├── requirements.txt       # 依赖清单
├── .streamlit/config.toml # Streamlit 配置（含静态服务开关）
├── static/files/          # 上传原始文档副本（用于预览/下载链接）
├── pretrain/Qwen/Qwen3-VL-Embedding-2B/   # 本地 embedding 模型
└── data/
    ├── chroma_db/         # 向量库持久化
    ├── knowledge/         # 命令行默认导入目录
    ├── page_images/       # PDF 整页图 + 嵌入图（持久化）
    └── ingested.json      # 已导入文件清单（去重记录）
```

## 快速启动

### 前提条件

- Python 3.10+
- **（推荐）NVIDIA GPU + CUDA**：自动启用 GPU 加速。安装 CUDA 12.8+ 版 PyTorch（torch 2.11.0+cu128），已内置 RTX 5090（sm_120）支持。
- 如无 GPU，CPU 模式也可运行（首次加载 Qwen 模型约需几十秒；图文模式入库较慢）。

### 首次启动（创建环境 + 安装依赖）

```powershell
cd d:\workspace\agent_work\agent_work_plus
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
streamlit run app.py
```

> 如需 CUDA 加速，额外安装 GPU 版 torch：
> ```powershell
> pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
> ```

### 日常启动

```powershell
cd d:\workspace\agent_work\agent_work_plus
.\venv\Scripts\activate
streamlit run app.py
```

启动后浏览器访问：**http://localhost:8502**

## 网页使用流程

### 一、导入文档（左侧边栏「📚 知识库」）

1. 拖入或选择文件（多选），格式：`txt` `md` `pdf` `docx` `pptx` `xlsx` `xls` `csv`
2. 点「📥 导入到知识库」，进度条结束即可提问
3. 也可展开「✍️ 或粘贴文本入库」直接粘贴文字

导入时自动完成：文字抽取 + 嵌入图抽取 + 视觉向量化 + OCR + 原件留底（供预览/下载）。

### 二、图文模式开关

侧边栏「🖼️ 图文模式」（默认开启）：
- 开启：PDF 每页渲染成图入库 + VL 向量化，回答时附上命中页原图
- 关闭：仅文字 + 嵌入图 + OCR 通道，导入更快，适合纯文本

### 三、管理已导入文件

- 侧边栏显示已导入清单（文件名 + 片段数）
- 每条旁的 🗑 删除按钮：同步清理向量库、图片缓存与原件副本
- 顶部显示知识库片段总数

### 四、提问 + 看原文

在右侧对话框提问。Agent 自动选择工具，回答下方会附：
- 📎 **相关文档页面**：命中的 PDF 页 / 嵌入图（图文对照）
- 🔗 **原始文档**：可点击预览链接（PDF 自动跳页）+ ⬇ 下载按钮
- 🔧 **工具调用过程**：展开查看 Agent 思考链路

### 五、清空记忆

侧边栏「🗑️ 清空对话记忆」重置当前会话。

## 命令行批量导入

```powershell
# 默认从 data/knowledge 导入
python ingest.py

# 导入整个目录（递归）
python ingest.py D:\你的文档目录

# 导入指定文件
python ingest.py 报告.pdf 清单.xlsx 介绍.pptx

# 查看知识库状态
python ingest.py --status

# 强制重新导入（忽略哈希去重）
python ingest.py D:\你的文档目录 --force
```

命令行与网页**共享同一份记录**（`data/ingested.json`），可在网页清单里统一查看和删除。

### 去重与更新机制

- 基于**文件内容哈希**去重：未改动的文件再次导入自动跳过
- 文件改动后重新导入：先清理旧片段再重新入库
- 网页上传同名文件：自动覆盖更新

## Embedding 后端

通过环境变量 `AGENT_EMBED_BACKEND` 切换：

| 后端 | 说明 | 维度 | 视觉能力 |
|------|------|------|------|
| `qwen`（默认） | 本地 Qwen3-VL-Embedding-2B | 2048 | ✅ 图片 + 文字共享空间 |
| `fastembed` | BGE 中文小模型 | 512 | ❌ 仅文字 |

```powershell
$env:AGENT_EMBED_BACKEND="fastembed"; streamlit run app.py
```

> ⚠️ 切换后端后向量维度不同，需重建库：
> ```powershell
> Remove-Item -Recurse -Force data/chroma_db, data/ingested.json, data/page_images
> ```

## 配置说明

主要配置在 `config.py`，可通过环境变量覆盖：

```python
API_KEY = "sk-..."                            # MiniMax API 密钥
BASE_URL = "http://172.16.11.19:4000/v1"      # API 网关
MODEL_NAME = "MiniMax-M2.7"

EMBEDDING_BACKEND = "qwen"                     # qwen / fastembed
RAG_TOP_K = 3
CHUNK_SIZE = 500
CHUNK_OVERLAP = 50

# 图文 / OCR / 嵌入图
ENABLE_PDF_IMAGE = True                        # PDF 整页 VL 入库
PDF_IMAGE_MAX_PAGES = 10                       # 单 PDF 最多处理页数
PDF_IMAGE_DPI = 120                            # 页面渲染 DPI
ENABLE_EMBEDDED_IMAGES = True                  # DOCX/PPTX/XLSX 嵌入图入库
ENABLE_OCR = True                              # 图片 OCR → 文字 chunk
OCR_MIN_CHARS = 10                             # OCR 文本最少字符（过滤噪声）

# 原文预览/下载
UPLOADS_DIR = ".../static/files"               # 原件副本目录（Streamlit 静态服务）
```

对应环境变量：`AGENT_API_KEY` `AGENT_BASE_URL` `AGENT_MODEL` `AGENT_EMBED_BACKEND`
`AGENT_ENABLE_PDF_IMAGE` `AGENT_ENABLE_OCR` `AGENT_ENABLE_EMBEDDED_IMAGES` `AGENT_OCR_MIN_CHARS` 等。

## 命令行测试

```powershell
.\venv\Scripts\activate
python test_agent.py
```

## 常见问题

**Q：首次提问/导入很慢？**

A：第一次加载 Qwen embedding 模型约几十秒。有 NVIDIA GPU 时自动用 GPU 加速。

**Q：扫描件 PDF 能检索吗？**

A：能。`ENABLE_OCR=true` 时每页图片会跑 OCR，识别文字作为 chunk 入库，文字 query 也能命中。

**Q：导入 PDF 失败 "已加密"？**

A：先解除密码再导入（支持空密码自动解密）。

**Q：原始文档链接点击没反应？**

A：必须保留 `.streamlit/config.toml` 中 `enableStaticServing = true`。Chrome/Edge 不允许从 `http://` 页面打开 `file://`，因此走 Streamlit 静态服务（仅本机访问，默认安全）。

**Q：端口被占用？**

A：换端口启动，`streamlit run app.py --server.port 8503`；或在 `.streamlit/config.toml` 改 `port`。

**Q：换更强的 8B embedding？**

A：下载 Qwen3-VL-Embedding-8B 到 `pretrain/Qwen/` 下，改 `config.py` 中 `QWEN_EMBED_PATH`，删除旧库重建。

**Q：数据会丢吗？**

A：不会。向量库 `data/chroma_db/`、原件 `static/files/`、页面图 `data/page_images/` 都持久化保存。