# nb

**Repository Path**: dailycreatebug/nb

## Basic Information

- **Project Name**: nb
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KnowledgeBase · 超级知识库

AI 驱动的**多模态**知识库系统：上传任意类型的文件（文档 / 表格 / PPT / PDF /
图片 / 音频 / 视频），后台自动解析为文本、分块、向量化，提供全文 + 语义混合
检索与基于知识库的 RAG 问答。

- 后端：Python + Flask + SQLite（`backend/`）
- 前端：工业级单页应用，无构建步骤（`frontend/index.html`）
- 存储：项目根目录 `files/`（原文件）+ `data/`（数据库与向量），均已 gitignore
- 跨平台：需要 Python 3.9+；所有重依赖均为**可选分层安装**，缺什么降级什么

## 快速开始

```bash
python -m venv venv
venv/Scripts/activate            # macOS/Linux: source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env             # 可选：配置监听地址 / API KEY（留白=禁用）
python -m backend.app
```

打开 http://127.0.0.1:8000 （默认只监听本机；局域网访问把 `.env` 中
`HOST` 改为 `0.0.0.0`，并放行防火墙端口）。

## 能力分层

| 层 | 功能 | 依赖 | 缺失时行为 |
|----|------|------|-----------|
| 基础 | 文件管理、TXT/MD/PDF/Word/Excel/PPT 解析、全文检索 | `requirements.txt` | —（必装） |
| ASR | 音视频转写（FunASR 本地离线） | `requirements-asr.txt` + 系统 ffmpeg | 音视频标记为「不支持」并提示 |
| OCR | 图片文字识别（PaddleOCR） | `requirements-ocr.txt` | 图片标记为「不支持」并提示 |
| 语义 | 向量嵌入 + 语义检索 | `requirements-embed.txt` 或 .env 配 API | 混合检索自动降级为全文 |
| 问答 | RAG（OpenAI 兼容 LLM） | `.env` 配置 LLM_* | 问答页提示未配置 |

首页侧栏实时显示各模块在线状态。

## 配置（.env）

复制 `.env.example` 为 `.env`，所有 KEY 默认留白，留白即禁用对应功能：

- `HOST` / `PORT` / `MAX_WORKERS` —— 服务与解析并发
- `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` —— 任意 OpenAI 兼容接口
  （本地 Ollama 填 `http://localhost:11434/v1`，KEY 留白即可）
- `EMBEDDING_API_KEY` / `EMBEDDING_BASE_URL` / `EMBEDDING_MODEL` —— API 嵌入
- `EMBEDDING_LOCAL_MODEL` —— 本地嵌入模型（默认 bge-small-zh，CPU 可跑）

## 架构

```
上传 ──► files/ 元数据入 SQLite ──► 解析线程池（状态机 pending→parsing→done）
                                          │
        ┌─────────────┬─────────────┬─────┴──────┬──────────────┐
        text.py       pdf.py       office.py     ocr.py        asr.py
      (直接读)      (pypdf)    (docx/xlsx/pptx) (PaddleOCR)  (ffmpeg+FunASR)
        └─────────────┴─────────────┴─────┬──────┴──────────────┘
                                          ▼
                              分块(~500字/重叠50) ──► chunks 表
                                          │                │
                                    FTS5 全文索引      向量嵌入(BLOB)
                                    (CJK bigram)      (API 或本地模型)
                                          └───── 混合检索 ─────┘
                                                     │
                                            RAG 问答（带来源引用）
```

中文检索采用 **CJK 二元词组（bigram）分词**：FTS5 默认按空白切词，中文整句
会坍缩成单 token，索引与查询统一 bigram 变换后即可正常命中（`db.cjk_tokenize`）。

## 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/upload` | multipart 上传（字段 `file`，可多个），入队解析 |
| GET | `/api/files?q=&page=&size=` | 列表（文件名搜索 + 分页 + 状态） |
| GET | `/api/files/<id>` | 详情（文本预览 / 分块数 / 错误信息） |
| PATCH | `/api/files/<id>` | 重命名 `{name}` |
| DELETE | `/api/files/<id>` | 删除（文件 + 元数据 + 索引） |
| POST | `/api/files/<id>/reparse` | 重新解析 |
| POST | `/api/sync` | 目录对账：files/ 新文件入库解析，失效记录清理（启动时自动执行，前端「同步目录」按钮同款） |
| GET | `/api/files/<id>/download` | 下载原文件 |
| GET | `/api/search?q=&mode=` | 检索，mode ∈ name / text / vector / hybrid |
| POST | `/api/chat` | RAG 问答 `{question}`，返回答案 + 引用来源 |
| GET | `/api/status` | 各能力模块在线状态 |

同名文件不覆盖，自动追加 `(1)`、`(2)`… 序号。

## 测试

```bash
python make_test_files.py   # 生成各格式样例文件到系统临时目录
python e2e_test.py          # 跑通上传→解析→检索→重命名→删除→问答降级
```

## 迭代记录

- 迭代一：文件上传 / 列表 / 下载
- 迭代二~六：SQLite 元数据与状态机、文档解析管道、ASR/OCR 多模态、
  向量语义检索、RAG 问答、工业级前端（当前版本）
- 目录同步：files/ 与数据库自动对账（启动时 + 手动按钮），支持直接拷文件进目录
- 计划中：检索性能扩展（sqlite-vec）、文档在线预览、解析任务断点续跑