# library-knqa

**Repository Path**: zgz521/library-knqa

## Basic Information

- **Project Name**: library-knqa
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-06
- **Last Updated**: 2026-01-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KN-QA（图书馆 / 知识库智能问答系统）

一个开箱即用的知识库问答与智能体编排系统：支持文档上传与解析、分块与索引（Chroma 向量 + BM25 全文）、混合检索、问答对话、以及“Agent/智能体”编排与发布。

后端使用 FastAPI，前端使用 Vue 3 + Ant Design Vue，数据存储使用 MySQL。

---

## 功能简介

- 账号与权限
   - 内置登录与 JWT 鉴权
   - 首次启动会自动创建默认管理员账号：`admin / admin`
- 知识库管理
   - 创建知识库、绑定检索/分块参数
   - 上传文档并自动解析（PDF / Word / Excel 等）
   - 文档分块、向量索引（Chroma）与全文索引（BM25）落盘
- 检索与调试
   - 支持向量 / 全文 / 混合检索
   - 提供“召回测试/检索调试”页面，便于对比不同检索策略效果
- 问答与对话
   - 在“Explore/探索”页面进行知识库问答
   - 支持流式/对话式交互（含 WebSocket 相关能力）
- 智能体（Agent）与编排
   - 创建智能体、编排提示词（Prompt）并绑定多个知识库
   - 发布/取消发布智能体，查看访问 API 与日志
- 模型与接口兼容
   - 支持 Ollama 与 OpenAI 兼容接口（通过环境变量切换提供商与模型）
   - 提供 OpenAI-compat 风格接口（用于与外部工具对接）

---

## 技术栈

- 后端：FastAPI、SQLAlchemy（Async）、asyncmy、Pydantic v2
- 向量库：Chroma（本地持久化）
- 全文检索：BM25（本地索引落盘）
- 前端：Vue 3、Vite、Ant Design Vue、Pinia
- 容器化：Docker + docker-compose

---

## 功能示例

- 登录页
   - ![登录页](docs/screenshots/01-login.png)
- 知识库列表 / 创建知识库
   - ![知识库](docs/screenshots/02-kb.png)
   - ![知识库](docs/screenshots/02-kb-1.png)
- 文档上传与解析
   - ![文档上传](docs/screenshots/03-upload.png)
- 召回测试 / 检索调试
   - ![检索调试](docs/screenshots/04-retrieval-debug.png)
- 智能体编排（Prompt + 绑定知识库）
   - ![智能体编排](docs/screenshots/05-agent-compose.png)

---

## 运行前准备

### 必要依赖

- Python 3.11+
- Node.js 18+（用于本地开发前端）
- MySQL 8+（或使用 docker-compose 启动 MySQL）

### 配置文件

项目使用 `.env` 读取配置。建议以 `.env.example` 为模板：

1. 复制配置：

```bash
cp .env.example .env
```

2. 按需修改：

- MySQL：`MYSQL_HOST / MYSQL_PORT / MYSQL_USER / MYSQL_PASSWORD / MYSQL_DB`
- LLM：`LLM_PROVIDER`（`ollama` 或 `openai`），以及对应模型与 Base URL
- 其它：`CORS_ORIGINS`、分块参数、TopK 等

> 安全建议：生产环境请务必修改 `JWT_SECRET`，并重置默认管理员密码。

---

## 方式一：docker-compose 一键启动（推荐）

### 启动

在项目根目录执行：

```bash
docker-compose up -d --build
```

启动后默认端口：

- Web/后端：`http://localhost:8086`
- API 前缀：`http://localhost:8086/api`
- MySQL（宿主机端口映射）：`127.0.0.1:9206` → 容器 `3306`

默认账号：`admin / admin`

### 停止与重启

```bash
docker-compose down
docker-compose up -d
```

### 数据持久化说明

docker-compose 已配置数据卷：

- `mysql_data`：MySQL 数据目录
- `web_resource`：应用私有数据（上传文件、Chroma、BM25 索引等）挂载到容器 `/app/app/resource`
- `web_public`：公开静态资源挂载到容器 `/app/app/public`

---

## 方式二：本地安装与开发（Backend + Frontend 分离）

### 1) 启动后端（FastAPI）

1. 创建并激活虚拟环境（示例命令，可按你习惯调整）：

```bash
python -m venv .venv
```

2. 安装依赖：

```bash
pip install -r requirements.txt
```

3. 准备 `.env`（参考上文），并确保 MySQL 可连接。

4. 启动服务：

```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 2) 启动前端（Vite）

```bash
cd frontend
npm install
npm run dev
```

前端开发服务器默认端口为 `5173`，并已在 Vite 中配置：

- `/api` 代理到 `http://127.0.0.1:8000`
- `/public` 代理到 `http://127.0.0.1:8000`

---

## 方式三：本地“单体”运行（后端直接挂载前端静态资源）

该方式适合本地模拟生产：先构建前端到 `frontend_dist/`，再启动后端。

1. 构建前端（输出目录已配置为项目根目录的 `frontend_dist/`）：

```bash
cd frontend
npm install
npm run build
```

2. 启动后端：

```bash
cd ..
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

3. 访问：`http://localhost:8000`

---

## 常见问题（Troubleshooting）

- 无法连接数据库
   - 检查 `.env` 的 MySQL 配置是否正确
   - 使用 docker-compose 时，应用容器内部通过 `MYSQL_HOST=knqa_mysql` 连接 MySQL（compose 已处理）
- 首次启动较慢
   - 需要初始化依赖、创建表结构、准备索引目录等
- 默认账号安全
   - 默认 `admin/admin` 仅用于开发演示，生产务必修改密码并更换 `JWT_SECRET`

---

## 目录说明（简要）

- `app/`：后端 FastAPI 代码
- `frontend/`：前端 Vue 3 代码
- `frontend_dist/`：前端构建产物（后端在存在该目录时会挂载到 `/`）
- `app/resource/`：私有数据（上传文件、Chroma、BM25 索引等）
- `app/public/`：可公开访问的静态资源（通过 `/public` 暴露）