# documind

**Repository Path**: poetic_Coding/documind

## Basic Information

- **Project Name**: documind
- **Description**: DocuMind — 智能文档理解与多源数据融合系统
让 AI 读懂每一份文档，让数据自动流向每一个表格!
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DocuMind V5 · 智能文档理解与多源数据融合系统

> 竞赛级精度 · Hybrid RAG · 行组 LLM · Function Calling · WebSocket 实时进度

---

## 🏗️ 技术架构

```
┌─────────────────────────────────────────────────────┐
│  Frontend (Vue3 + Pinia + Vite)                      │
│  ├── M1: 文档对话/编辑 (Chat + Editor)                │
│  ├── M2: 文档管理 (DocManager)                        │
│  └── M3: 智能填表 (TableFiller + WebSocket 进度)      │
├─────────────────────────────────────────────────────┤
│  Backend (FastAPI + asyncio)                         │
│  ├── M1 Editor    - 6种编辑操作 + Function Calling    │
│  ├── M2 Parser    - 4种格式 (DOCX/XLSX/MD/TXT)       │
│  ├── RAG Engine   - ChromaDB + BM25 + RRF Fusion     │
│  └── M3 Filler    - 行组LLM + 低置信重试 + 输出写入  │
├─────────────────────────────────────────────────────┤
│  Storage                                             │
│  ├── SQLite (aiosqlite) - 文档/任务/对话元数据        │
│  └── ChromaDB           - 向量索引                   │
└─────────────────────────────────────────────────────┘
```

## 🚀 快速启动

### 方式一：Docker Compose（推荐）

```bash
# 1. 克隆 & 配置
cp .env.example .env
# 编辑 .env 填入至少一个 LLM 提供商的 API Key

# 2. 一键启动
docker-compose up -d

# 3. 访问
# 前端: http://localhost
# API:  http://localhost:8000/docs
```

### 方式二：本地开发

**Backend**
```bash
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp ../.env.example .env  # 填入 API Key
python main.py
```

**Frontend**
```bash
cd frontend
npm install
npm run dev    # http://localhost:5173
# 生产构建
npm run build  # 输出到 backend/static/dist
```

---

## 🔑 LLM 提供商配置

在 `.env` 中配置，**至少填写一个**：

| 提供商 | 推荐模型 | Function Calling | 特点 |
|-------|---------|-----------------|------|
| SiliconFlow | Qwen2.5-72B-Instruct | ✅ | 免费额度大 |
| DashScope | qwen-plus | ✅ | 阿里云，稳定 |
| Moonshot | moonshot-v1-8k | ❌ | 长上下文 |
| Zhipu | glm-4-flash | ✅ | 国产，快速 |
| Ollama | qwen2.5:7b | ❌ | 本地运行 |

---

## 📐 核心设计亮点

### G1: 按 row_key 分组的 LLM 调用策略
```
同一行的所有字段 → 一次 LLM 调用 → 显著减少 API 调用次数
```

### BUG-2: ChromaDB metadata 类型统一
```python
# 所有 metadata 值强制转 str，防止 Chroma filter 类型报错
clean_metas = [{k: str(v) for k, v in m.items()} for m in metadatas]
```

### BUG-3: 后台解析独立 Session
```python
async def _parse_background(doc_id, file_path):
    async with AsyncSessionFactory() as db:  # 独立 session，防止冲突
        await kb_service.parse_and_store(doc_id, file_path, db)
```

### BUG-7: RAG Context 注入 System Prompt
```python
system = f"基于以下参考内容回答：\n{context}\n..."  # context 注入 system，非 user
```

### G6: 多策略 JSON 清洗
```python
def _parse_json_safe(text):
    # 1. 直接解析
    # 2. 提取 ```json ... ```
    # 3. 正则找第一个 { } 或 [ ]
    # 4. 记录日志并返回空
```

---

## 📁 项目结构

```
documind/
├── backend/
│   ├── main.py              # FastAPI 应用入口 + 启动预热
│   ├── config.py            # 多提供商配置
│   ├── database.py          # aiosqlite 异步数据库
│   ├── models/
│   │   ├── db_models.py     # SQLAlchemy ORM
│   │   └── schemas.py       # Pydantic V2 模型
│   ├── modules/
│   │   ├── chat/
│   │   │   ├── llm_client.py    # 多提供商LLM + Function Calling
│   │   │   └── chat_handler.py  # NL2Action + RAG 处理
│   │   ├── document_parser/
│   │   │   ├── docx_parser.py   # Word 文档解析
│   │   │   ├── xlsx_parser.py   # Excel 行级KV序列化
│   │   │   ├── md_parser.py     # Markdown 解析
│   │   │   └── txt_parser.py    # 文本（编码自动检测）
│   │   ├── rag_engine/
│   │   │   ├── embedder.py       # 多提供商嵌入
│   │   │   ├── vector_store.py   # ChromaDB（BUG-2修复）
│   │   │   ├── bm25_retriever.py # BM25（线程池G7）
│   │   │   └── hybrid_retriever.py # RRF融合
│   │   └── table_filler/
│   │       ├── template_parser.py # 模板解析（BUG-4）
│   │       ├── filler.py          # 行组策略填表（G1）
│   │       └── output_writer.py   # 结果写入+高亮
│   ├── routers/             # FastAPI 路由
│   └── services/
│       ├── knowledge_base.py # KB 单例（BUG-1/BUG-8）
│       └── doc_editor.py     # 6种编辑操作
├── frontend/
│   └── src/
│       ├── views/           # 4个主视图
│       ├── stores/          # Pinia 状态
│       ├── api/             # Axios 封装
│       └── styles/          # 全局设计系统 CSS
└── docker-compose.yml
```

---

## 📊 M3 智能填表流程

```
上传模板 (.xlsx/.docx)
    ↓ 解析空字段 + 识别 row_key / col_key / data_type
    ↓ 按 row_key 分组 (G1优化)
    ↓ 并发RAG检索 (hybrid: dense + BM25)
    ↓ 每行组一次LLM调用 (减少API消耗)
    ↓ WebSocket 实时推送 field_done 事件
    ↓ 低置信字段扩展重查
    ↓ 写入结果文件 (绿色=高置信 / 红色=待审)
    ↓ 下载 + 查看 DocuMind说明 Sheet
```

---

## 🎨 UI 设计语言

**深空工业美学** - 专为高精度 AI 系统设计：

- **色彩**: 深空黑底 `#050810` + 电光青 `#00e5ff` 强调
- **字体**: `Syne`（标题）+ `IBM Plex Mono`（代码/数据）+ `Noto Sans SC`（正文）
- **动效**: 扫描线脉冲、渐入动画、实时数据流
- **信息密度**: 高密度但清晰，适合数据分析场景

---

## ⚙️ 环境变量完整列表

见 `.env.example`

---

## 🔧 常见问题

**Q: hash 嵌入会影响精度吗？**
A: hash 仅用于开发/测试，生产建议配置 `EMBEDDING_PROVIDER=siliconflow` 或 `dashscope`

**Q: 如何提升填表准确率？**
A: 1. 上传更多相关文档 2. 降低 `CONFIDENCE_THRESHOLD` 查看更多结果 3. 使用更强的 LLM（72B+ 模型）

**Q: ChromaDB 报维度不匹配？**
A: 切换了嵌入提供商后需清除旧数据，或系统会自动重建 Collection（BUG-6修复）