🤖 AI Knowledge Base

一个功能完善的企业级 AI 知识库系统，支持文档管理、智能问答、RAG 检索增强生成等功能。

✨ 功能特性

🎯 核心功能

📚 智能文档管理
- 支持多种文档格式（PDF、Word、TXT、Markdown等）
- 自动文档解析和向量化
- 智能分块策略（滑动窗口、递归分块）
- 文档预览和管理
💬 智能问答系统
- 基于 RAG 的上下文感知问答
- 多轮对话支持
- 流式响应（SSE）
- 引用来源追踪
🔍 高级检索
- 向量相似度搜索
- 混合检索（向量 + 关键词）
- 重排序优化
- 多文档协同检索
👥 用户管理
- 完整的用户认证系统（JWT）
- 角色权限管理（用户/管理员）
- 个人中心和设置
🎨 现代化界面
- 响应式设计，支持移动端
- 深色/浅色主题切换
- 流畅的动画效果
- 直观的用户体验

🚀 技术亮点

⚡ 高性能：Redis 缓存 + 异步处理
🔒 安全可靠：JWT 认证 + 权限控制
📦 容器化部署：Docker Compose 一键启动
🎯 可扩展：微服务架构，易于扩展
🌐 多模型支持：OpenAI、通义千问、GLM等

🛠️ 技术栈

后端

技术	版本	说明
Python	3.11+	核心语言
FastAPI	0.104+	Web 框架
PostgreSQL	15+	关系数据库
ChromaDB	0.4+	向量数据库
Redis	7.0+	缓存系统
MinIO	Latest	对象存储
SQLAlchemy	2.0+	ORM 框架
Pydantic	2.0+	数据验证
LangChain	0.1+	LLM 编排

前端

技术	版本	说明
React	18.3+	UI 框架
TypeScript	5.5+	类型安全
Vite	5.0+	构建工具
Chakra UI	3.0+	组件库
Zustand	4.5+	状态管理
React Router	6.0+	路由管理
Axios	1.7+	HTTP 客户端

📁 项目结构

ai-knowledge-base/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── api/               # API 路由
│   │   │   ├── v1/
│   │   │   │   ├── auth.py          # 认证接口
│   │   │   │   ├── documents.py     # 文档管理
│   │   │   │   ├── qa.py            # 问答接口
│   │   │   │   ├── users.py         # 用户管理
│   │   │   │   └── admin.py         # 管理后台
│   │   ├── core/              # 核心配置
│   │   │   ├── config.py            # 配置管理
│   │   │   ├── security.py          # 安全相关
│   │   │   └── database.py          # 数据库连接
│   │   ├── models/            # 数据模型
│   │   │   ├── user.py              # 用户模型
│   │   │   ├── document.py          # 文档模型
│   │   │   └── conversation.py      # 对话模型
│   │   ├── schemas/           # Pydantic 模式
│   │   ├── services/          # 业务逻辑
│   │   │   ├── auth/                # 认证服务
│   │   │   ├── knowledge/           # 知识库服务
│   │   │   │   ├── chunking.py      # 文档分块
│   │   │   │   ├── embedding.py     # 向量化
│   │   │   │   └── retrieval.py     # 检索服务
│   │   │   ├── llm/                 # LLM 服务
│   │   │   ├── cache/               # 缓存服务
│   │   │   └── storage/             # 存储服务
│   │   └── utils/             # 工具函数
│   ├── tests/                 # 测试文件
│   ├── requirements.txt       # Python 依赖
│   └── Dockerfile            # 后端镜像
│
├── frontend/                  # 前端应用
│   ├── src/
│   │   ├── api/              # API 客户端
│   │   ├── components/       # 通用组件
│   │   │   ├── layout/            # 布局组件
│   │   │   ├── ui/                # UI 组件
│   │   │   └── ThemeToggle.tsx    # 主题切换
│   │   ├── features/         # 功能模块
│   │   │   ├── auth/              # 认证模块
│   │   │   ├── documents/         # 文档管理
│   │   │   ├── qa/                # 问答模块
│   │   │   ├── profile/           # 个人中心
│   │   │   ├── settings/          # 系统设置
│   │   │   └── admin/             # 管理后台
│   │   ├── hooks/            # 自定义 Hooks
│   │   ├── stores/           # Zustand 状态
│   │   │   ├── authStore.ts       # 认证状态
│   │   │   ├── chatStore.ts       # 对话状态
│   │   │   ├── documentStore.ts   # 文档状态
│   │   │   └── themeStore.ts      # 主题状态
│   │   ├── pages/            # 页面组件
│   │   ├── styles/           # 样式文件
│   │   │   └── theme.css          # 主题样式
│   │   ├── types/            # TypeScript 类型
│   │   └── utils/            # 工具函数
│   ├── public/               # 静态资源
│   ├── package.json          # 前端依赖
│   └── Dockerfile           # 前端镜像
│
├── docker-compose.yml        # Docker 编排
├── .env.example             # 环境变量示例
└── README.md                # 项目文档

🚀 快速开始

前置要求

Docker 20.10+
Docker Compose 2.0+
Node.js 20+ (本地开发)
Python 3.11+ (本地开发)

1. 克隆项目

git clone https://github.com/yourusername/ai-knowledge-base.git
cd ai-knowledge-base

2. 配置环境变量

cp .env.example .env

编辑 .env 文件，配置以下关键参数：

# 数据库配置
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=ai_knowledge_base

# Redis 配置
REDIS_PASSWORD=your_redis_password

# MinIO 配置
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=your_minio_password

# JWT 配置
SECRET_KEY=your_super_secret_key_change_this
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# AI 模型配置
# OpenAI
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_MODEL=gpt-3.5-turbo

# 或使用通义千问
# DASHSCOPE_API_KEY=your-dashscope-api-key
# LLM_PROVIDER=dashscope
# LLM_MODEL=qwen-turbo

3. 启动服务

# 构建并启动所有服务
docker-compose up -d --build

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

4. 访问应用

前端: http://localhost:3000
后端 API: http://localhost:8000
API 文档: http://localhost:8000/docs
MinIO 控制台: http://localhost:9001

5. 默认账号

管理员账号：admin / admin123456
普通用户：testuser / testuser123

⚠️ 生产环境请务必修改默认密码！

⚙️ 配置说明

AI 模型配置

系统支持多种 LLM 提供商，在 .env 中配置：

OpenAI

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_MODEL=gpt-3.5-turbo
EMBEDDING_MODEL=text-embedding-3-small

通义千问

LLM_PROVIDER=dashscope
DASHSCOPE_API_KEY=your-api-key
LLM_MODEL=qwen-turbo
EMBEDDING_MODEL=text-embedding-v2

智谱 GLM

LLM_PROVIDER=zhipuai
ZHIPUAI_API_KEY=your-api-key
LLM_MODEL=glm-4

文档处理配置

# 分块配置
CHUNK_SIZE=500                    # 分块大小
CHUNK_OVERLAP=50                  # 分块重叠
CHUNKING_STRATEGY=recursive       # 分块策略 (recursive/sliding_window)

# 检索配置
TOP_K=5                          # 返回结果数量
SIMILARITY_THRESHOLD=0.7         # 相似度阈值
RERANK_ENABLED=true              # 是否启用重排序

📖 使用指南

上传文档

登录系统后，点击左侧菜单「文档管理」
点击「上传文档」按钮
选择文档文件（支持 PDF、Word、TXT、Markdown）
等待文档处理完成（会自动分块和向量化）

智能问答

点击左侧菜单「智能问答」
点击「新建对话」开始新对话
输入问题，系统会基于已上传的文档回答
查看答案下方的「引用来源」了解信息来源

管理后台

管理员账号登录后可访问管理后台：

用户管理：查看、编辑、删除用户
系统统计：查看使用数据和趋势
文档管理：管理所有用户的文档

🔧 开发指南

后端开发

cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 运行开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

前端开发

cd frontend

# 安装依赖
npm install

# 运行开发服务器
npm run dev

# 构建生产版本
npm run build

数据库迁移

# 生成迁移文件
alembic revision --autogenerate -m "description"

# 执行迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1

测试

# 后端测试
cd backend
pytest

# 前端测试
cd frontend
npm run test

🐳 Docker 部署

生产环境部署

# 1. 修改生产环境配置
cp .env.example .env.prod

# 2. 构建生产镜像
docker-compose -f docker-compose.prod.yml build

# 3. 启动服务
docker-compose -f docker-compose.prod.yml up -d

# 4. 查看日志
docker-compose -f docker-compose.prod.yml logs -f

服务管理

# 停止所有服务
docker-compose down

# 停止并删除数据卷
docker-compose down -v

# 重启服务
docker-compose restart

# 查看资源使用
docker stats

# 进入容器
docker-compose exec api bash
docker-compose exec frontend sh

备份和恢复

# 备份数据库
docker-compose exec db pg_dump -U postgres ai_knowledge_base > backup.sql

# 恢复数据库
docker-compose exec -T db psql -U postgres ai_knowledge_base < backup.sql

# 备份 MinIO 数据
docker-compose exec minio mc mirror minio/knowledge-base ./minio-backup

📊 API 文档

认证接口

POST /api/v1/auth/login

登录获取 Token

请求体：

{
  "username": "admin",
  "password": "admin123456"
}

响应：

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "admin"
  }
}

文档接口

POST /api/v1/documents/upload

上传文档

请求： multipart/form-data

file: 文档文件
metadata: JSON 字符串（可选）

响应：

{
  "document_id": "uuid-here",
  "filename": "document.pdf",
  "status": "processing"
}

GET /api/v1/documents

获取文档列表

查询参数：

skip: 偏移量（默认 0）
limit: 数量限制（默认 10）

问答接口

POST /api/v1/qa/chat

发送问答请求（流式）

请求体：

{
  "conversation_id": "uuid-here",
  "query": "什么是 RAG？",
  "stream": true
}

响应： SSE 流式响应

完整 API 文档访问：http://localhost:8000/docs

🎨 主题系统

系统支持深色/浅色主题无缝切换：

特性

✅ 全局主题状态管理（Zustand）
✅ LocalStorage 持久化
✅ 所有组件适配深色模式
✅ 平滑过渡动效（0.2s）
✅ CSS 变量系统
✅ GitHub 风格配色

使用

// 在组件中使用主题
import { useThemeStore } from '@/stores/themeStore'

function MyComponent() {
  const { colorMode, toggleColorMode } = useThemeStore()
  
  return (
    <div style={{ 
      backgroundColor: 'var(--bg-subtle)',
      color: 'var(--fg-default)' 
    }}>
      当前主题: {colorMode}
      <button onClick={toggleColorMode}>切换主题</button>
    </div>
  )
}

🔍 常见问题

1. 文档上传失败

原因： MinIO 连接失败或权限问题

解决：

# 检查 MinIO 服务状态
docker-compose logs minio

# 重启 MinIO
docker-compose restart minio

# 检查环境变量配置
cat .env | grep MINIO

2. 向量检索无结果

原因： ChromaDB 未正确初始化或文档未向量化

解决：

# 检查 ChromaDB 日志
docker-compose logs chromadb

# 重新处理文档
# 在管理后台删除文档后重新上传

3. AI 回答很慢

原因： 网络问题或 API 限流

解决：

检查 API Key 配置
使用国内镜像（如通义千问）
启用 Redis 缓存
减小 TOP_K 参数

4. 前端构建失败

原因： Node 版本不兼容或依赖问题

解决：

# 使用正确的 Node 版本
nvm use 20

# 清除缓存重新安装
cd frontend
rm -rf node_modules package-lock.json
npm install

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
提交 Pull Request

代码规范

Python:

遵循 PEP 8
使用 Black 格式化
使用 mypy 类型检查

TypeScript:

遵循 ESLint 规则
使用 Prettier 格式化
严格的类型检查

📝 更新日志

v2.0.0 (2024-10-18)

新增：

✨ 完整的深色模式支持
✨ 智能文档分块策略
✨ Redis 缓存系统
✨ 流式响应优化

改进：

🎨 全新的 UI 设计
⚡ 性能优化（检索速度提升 50%）
🔒 增强的安全性

修复：

🐛 文档上传路由问题
🐛 时区显示问题
🐛 全局通知系统

v1.0.0 (2024-09-01)

🎉 首次发布

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🙏 致谢

感谢以下开源项目：

FastAPI - 现代高性能 Web 框架
LangChain - LLM 应用开发框架
Chakra UI - 优秀的 React 组件库
ChromaDB - AI 原生向量数据库
React - 构建用户界面的 JavaScript 库

📞 联系方式

项目主页: https://github.com/PLUCK823/ai-knowledge-base
问题反馈: https://github.com/PLUCK823/ai-knowledge-base/issues
邮箱: 2565796877@qq.com

⭐ Star History

如果这个项目对你有帮助，请给个 Star ⭐️

Made with ❤️ by Your Team

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.cursor/commands		.cursor/commands
.github/workflows		.github/workflows
.specify		.specify
backend		backend
frontend		frontend
specs		specs
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
env.example		env.example

License

PLUCK823/ai-knowledge-base

Folders and files

Latest commit

History

Repository files navigation

🤖 AI Knowledge Base

✨ 功能特性

🎯 核心功能

🚀 技术亮点

🛠️ 技术栈

后端

前端

📁 项目结构

🚀 快速开始

前置要求

1. 克隆项目

2. 配置环境变量

3. 启动服务

4. 访问应用

5. 默认账号

⚙️ 配置说明

AI 模型配置

OpenAI

通义千问

智谱 GLM

文档处理配置

📖 使用指南

上传文档

智能问答

管理后台

🔧 开发指南

后端开发

前端开发

数据库迁移

测试

🐳 Docker 部署

生产环境部署

服务管理

备份和恢复

📊 API 文档

认证接口

POST /api/v1/auth/login

文档接口

POST /api/v1/documents/upload

GET /api/v1/documents

问答接口

POST /api/v1/qa/chat

🎨 主题系统

特性

使用

🔍 常见问题

1. 文档上传失败

2. 向量检索无结果

3. AI 回答很慢

4. 前端构建失败

🤝 贡献指南

代码规范

📝 更新日志

v2.0.0 (2024-10-18)

v1.0.0 (2024-09-01)

📄 许可证

🙏 致谢

📞 联系方式

⭐ Star History

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages