# intelligent-knowledge-assistant

**Repository Path**: liux1224/intelligent-knowledge-assistant

## Basic Information

- **Project Name**: intelligent-knowledge-assistant
- **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-02
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能知识助手 (Intelligent Knowledge Assistant)

企业内部智能知识管理与问答平台，基于大模型和 RAG 技术，整合知识库管理、AI 自动整理、智能问答三大核心能力。

## 两种运行模式

| 模式 | 依赖 | 适用场景 |
|------|------|----------|
| **standalone**（默认） | 仅 Python 3.10+，零外部服务 | 本地开发、演示、小规模单机部署 |
| **full** | PostgreSQL + Milvus + Elasticsearch + Redis | 生产/企业级部署（docker compose） |

standalone 模式下，系统以单进程运行：SQLite 存储、本地向量检索（numpy）、本地全文检索、文档解析入库在进程内完成；未配置 LLM/Embedding API Key 时自动进入**离线演示模式**（哈希向量检索 + 原文摘录回答），配置真实 Key 后即为完整 RAG 体验。

## 快速开始（standalone，无需 Docker）

```bash
bash scripts/standalone.sh
```

脚本会自动完成：创建虚拟环境 → 安装后端依赖 → 构建前端（如安装了 Node.js）→ 初始化数据库并灌入演示文档 → 启动服务。

启动后：
- Web 界面：http://localhost:8000
- API 文档：http://localhost:8000/docs
- 演示账号：**admin / admin123**（超管）、**demo / demo123**（编辑）

也可以手动执行：

```bash
python3 -m venv .venv && .venv/bin/pip install -r backend/requirements.txt
.venv/bin/python scripts/seed_demo.py        # 初始化数据库 + 演示数据
.venv/bin/python run.py                      # 启动（PORT=9000 可换端口）
```

常用命令：

```bash
make standalone          # 一键启动
make standalone-reset    # 清空数据重新灌入演示文档
make seed-demo           # 仅重建演示数据
make test                # 运行后端测试（35 个，无需任何外部服务）
```

### 配置 LLM / Embedding（可选）

编辑根目录 `.env`（模板见 `.env.example`）：

```ini
LLM_API_KEY=sk-xxx            # 通义千问 / DeepSeek 等 OpenAI 兼容 API
EMBEDDING_API_KEY=sk-xxx      # 建议与 LLM 同服务商（text-embedding-v3 维度 1024）
```

重启后即从离线演示模式切换为完整 RAG（真实语义检索 + 大模型生成回答）。

## 测试文档（sample_docs/）

内置 9 个部门、30 份、6 种格式的仿真企业文档，内容真实且数字口径互相一致，用于测试解析、检索与问答：

| 目录 | 文档 | 格式 |
|------|------|------|
| 01-人事部 | 员工手册、考勤与休假制度、招聘流程、绩效考核办法、培训管理制度、薪酬福利制度 | md / txt / html / docx |
| 02-财务部 | 差旅费报销制度、年度预算管理办法、费用报销标准表、发票管理制度、采购与付款流程 | docx / md / xlsx / txt |
| 03-技术部 | 代码提交与分支管理规范、生产环境运维手册、接口设计规范、测试规范、数据库变更管理规范、上线检查清单 | md / txt / html / docx |
| 04-行政部 | 会议室管理制度、办公资产管理台账、车辆管理制度 | md / xlsx |
| 05-市场部 | 品牌视觉使用规范、市场活动策划流程 | pptx / md |
| 06-信息安全 | 数据分级与保密制度、应急响应预案、账号与权限管理制度 | md / txt |
| 07-法务部 | 合同管理制度 | txt |
| 08-产品部 | 产品需求评审流程、版本发布说明规范 | md / txt |
| 09-客服部 | 客户投诉处理办法、客服工单管理规范 | md / html |

`scripts/generate_sample_docs.py` 负责生成其中的二进制格式（docx/xlsx/pptx），修改内容后重新执行即可；`scripts/seed_demo.py` 支持增量灌库（已有的文档自动跳过）。

推荐测试问题（无 Key 离线模式下也可验证检索链路）：

- 住宿费报销标准是多少？
- 季度考核 C 级会有什么后果？
- 遭遇勒索病毒应该怎么处理？
- 数据订正的批量上限是多少？
- 客户投诉的分级响应时限？

## 快速开始（full 模式，Docker）

```bash
cp .env.example .env        # 填入 LLM API Key 等
docker compose up -d
```

compose 已注入 `APP_MODE=full` 与 PostgreSQL/Milvus/ES/Celery 连接配置；启动后访问 http://localhost（前端）、http://localhost:8000/docs（API）。

## 项目结构

```
intelligent-knowledge-assistant/
├── run.py                    # 单进程启动入口（standalone）
├── scripts/
│   ├── standalone.sh         # 一键启动脚本
│   ├── seed_demo.py          # 建库 + 灌入演示文档
│   ├── generate_sample_docs.py
│   └── dev-setup.sh
├── sample_docs/              # 测试文档（7 部门 / 6 格式）
├── backend/                  # FastAPI + SQLAlchemy + Celery（可选）
│   ├── app/
│   │   ├── api/v1/endpoints/ # auth/kb/doc/chat/ws/dashboard/kg/settings/feishu
│   │   ├── core/             # 数据库、安全（JWT）、权限
│   │   ├── models/           # SQLAlchemy 模型
│   │   ├── parsers/          # PDF/Word/PPT/Excel/HTML/TXT 解析器
│   │   ├── services/         # RAG/LLM/Embedding/分块/重排/查重/图谱
│   │   │   └── vector_store.py、keyword_search_service.py  # local/milvus、local/es 双实现
│   │   └── tasks/            # 内联任务 / Celery 双模式派发
│   └── tests/                # 35 个测试，离线可跑
├── frontend/                 # React 18 + TypeScript + Ant Design
├── docker-compose.yml        # full 模式编排
└── Makefile
```

## API 概览

| 路径 | 方法 | 说明 |
|------|------|------|
| `/api/v1/auth/register` `/login` `/me` | POST/GET | 注册 / 登录（JWT）/ 当前用户 |
| `/api/v1/auth/change-password` | POST | 修改密码 |
| `/api/v1/knowledge-bases/` | GET/POST | 知识库列表（按权限过滤）/ 创建 |
| `/api/v1/knowledge-bases/{id}` | GET/PUT/DELETE | 详情 / 编辑 / 删除（级联清理索引） |
| `/api/v1/knowledge-bases/{id}/members` | GET/POST/DELETE | 成员管理（所有者或超管） |
| `/api/v1/documents/upload` | POST | 文档上传（格式白名单 + 大小限制 + 权限校验） |
| `/api/v1/documents/` | GET | 文档列表（分页 + 状态筛选 + 标题搜索） |
| `/api/v1/documents/{id}` | GET/DELETE | 详情 / 删除（联动清理 ES/向量/文件） |
| `/api/v1/documents/{id}/duplicates` | GET | 查重（精确 hash + 语义相似度） |
| `/api/v1/chat/completions` | POST | 智能问答（返回 model / elapsed_ms） |
| `/api/v1/chat/conversations` | GET | 会话历史（含消息数） |
| `/api/v1/chat/conversations/{id}` | GET/DELETE | 会话详情 / 删除 |
| `/ws/chat?token=...` | WebSocket | 流式问答（done 帧含 model / elapsed_ms） |
| `/api/v1/models/status` `catalog` | GET | 模型状态 / 推荐目录（按内存自适应） |
| `/api/v1/models/pull` `apply` `test` | POST | 拉取模型 / 切换提供方 / 连通测试 |
| `/api/v1/integrations/feishu/webhook` | POST | 飞书机器人（验签） |

## 开发命令

```bash
make backend      # 本地启动后端 API（开发）
make frontend     # 启动前端 dev server
make test         # 后端测试
make test-cov     # 测试 + 覆盖率
make docker-up    # full 模式：Docker Compose 启动
```

## 安全要点

- JWT 认证：token 携带 `user_id`/`role`，所有业务接口校验登录态与对象级权限（owner/成员/管理员）
- 上传防护：服务端生成存储文件名（防路径穿越/覆盖）、扩展名白名单、大小限制
- 飞书 Webhook：X-Lark-Signature 验签（生产环境必须配置 `FEISHU_ENCRYPT_KEY`）
- 向量检索按知识库过滤，杜绝跨库数据泄露
- 生产部署请修改 `SECRET_KEY`，并在 `CORS_ORIGINS` 中枚举真实前端域名

## 开发计划

- [x] 项目设计 / 骨架 / 数据库迁移
- [x] 文档解析 Pipeline（PDF/Word/PPT/Excel/HTML/TXT）
- [x] RAG 混合检索（向量 + 关键词）+ 重排 + 引用溯源
- [x] standalone 单机可执行模式（SQLite + 本地索引，离线可演示）
- [x] 前端 6 个页面 + WebSocket 流式问答
- [x] 会话历史管理、复制/重新生成/停止、回答模型与耗时展示
- [x] 知识库成员协作管理（owner/成员/管理员三级权限）
- [x] 文档分页筛选搜索、查重入口
- [x] 修改密码、登录页演示账号提示
- [x] 飞书机器人（验签 + 默认知识库）
- [x] SSO/OAuth2 登录
- [x] 文档查重 / 版本对比 / 知识图谱
- [x] 35 个后端测试（离线可跑）
- [ ] 企微机器人接入
- [ ] 知识图谱交互增强
- [ ] 权限管理界面（用户/成员维护）