# knowledge_system

**Repository Path**: ranfusheng/knowledge_system

## Basic Information

- **Project Name**: knowledge_system
- **Description**: 基于chromadb开发的知识库管理系统，可以扩展不同的分词器。存在多个集合，每个集合表示一类数据，实现知识库的crud、文档解析、文档分块，以及知识库内容分块预览，完整文档的可视化以及编辑。外加mcp服务暴露，接口调用情况记录。可进行文档的管理与编辑（含文档归类）。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Knowledge System

**Knowledge System** 是一个基于 ChromaDB 开发的知识库管理系统，为个人和小型团队提供高效、灵活的知识管理和检索能力。

---

## 📋 核心功能

- **多集合管理**：创建多个知识库集合，每个集合表示一类数据
- **文档处理**：支持 Word (.docx)、Markdown (.md)、TXT 等格式的文档解析
- **文档分块**：支持固定长度分块，可配置分块大小和重叠大小
- **混合搜索**：结合向量相似度搜索和关键词搜索，提供精准的检索结果
- **文档预览与编辑**：支持文档块预览和完整文档可视化编辑
- **文档归类**：支持文档的管理与分类
- **版本管理**：保留文档的最近几个历史版本，支持查看和回滚
- **MCP 服务**：暴露 MCP 服务供其他 AI 助手调用知识库
- **接口记录**：记录所有接口调用情况，便于审计和分析
- **嵌入模型配置**：提供友好的配置界面，用户可选择和配置不同的云端嵌入服务

---

## 🏗️ 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| **前端框架** | React 18 + TypeScript + Vite | 现代化前端框架，提供类型安全 |
| **UI 组件库** | Ant Design 5 | 企业级 UI 组件库 |
| **后端框架** | Python + FastAPI | 高性能异步 Web 框架 |
| **数据验证** | Pydantic | 数据验证和序列化 |
| **向量数据库** | ChromaDB (嵌入式模式) | 轻量级向量数据库，无需额外服务 |
| **中文分词** | Jieba | 流行的中文分词器 |
| **英文分词** | 内置分词器 | 基于正则表达式的英文分词 |
| **嵌入模型** | 云端嵌入服务 | 支持 OpenAI、Cohere、Azure OpenAI、自定义服务 |
| **文档解析** | python-docx / markdown2 | 文档格式解析 |
| **文档存储** | 本地文件系统 | 本地存储原始文档和版本文件 |
| **MCP 服务** | FastMCP / MCP Python SDK | MCP 协议实现 |

---

## 🚀 快速开始

### 选项 1：本地开发（推荐）

```bash
# 克隆仓库
git clone <your-repo-url>
cd knowledge_system

# 安装依赖（使用 uv 包管理器）
uv sync

# 初始化项目
uv run knowledge-system init

# 启动后端服务（端口 8000）
uv run knowledge-system app

# 另开终端，启动前端开发服务器（端口 5173）
cd console
npm install --legacy-peer-deps
npm run dev
```

| 服务 | 地址 | 说明 |
|------|------|------|
| 前端开发 | http://localhost:5173 | Vite 热更新，自动代理 API 请求 |
| 后端 API | http://localhost:8000 | FastAPI + 自动文档 |
| MCP 服务 | http://localhost:8002/sse | AI 助手集成 |

> **说明**：开发模式下，前端通过 Vite 代理将 `/api` 请求转发到后端 8000 端口。

### 选项 2：生产模式（前端 + 后端合并）

```bash
# 构建前端
cd console
npm install --legacy-peer-deps
npm run build

# 启动合并服务（前端 + 后端在 8000 端口）
cd ..
uv run knowledge-system app

# 另开终端，启动 MCP 服务（独立端口 8002）
uv run knowledge-system mcp
```

| 路径 | 服务 | 端口 |
|------|------|------|
| `/` | 前端静态文件 | 8000 |
| `/api/*` | REST API | 8000 |
| `/sse` | MCP 服务 | 8002 |

> **说明**：本项目使用 [uv](https://github.com/astral-sh/uv) 作为包管理工具，无需手动创建虚拟环境，`uv sync` 会自动完成依赖安装和环境配置。

### 选项 2：Docker (待实现)

```bash
docker run -p 8000:8000 \
  -v ./data:/app/data \
  -v ./logs:/app/logs \
  knowledge-system
```

---

## 📱 主要功能介绍

### 1. 集合管理
- 创建、编辑、删除知识库集合
- 每个集合可独立配置分词器和分块参数
- 关联嵌入模型配置

### 2. 文档管理
- 支持上传 Word、Markdown、TXT 格式文档
- 文档分块预览
- 文档归类和标签
- 版本控制和回滚

### 3. 搜索功能
- 混合搜索：向量相似度 + 关键词匹配
- 按集合筛选搜索范围
- 搜索结果高亮显示

### 4. 嵌入模型配置
- 支持多种云端嵌入服务：OpenAI、Cohere、Azure OpenAI
- 自定义 OpenAI 兼容服务
- 连接测试功能
- API Key 安全存储

### 5. MCP 服务
- 提供标准 MCP 协议接口
- 支持从其他 AI 助手调用知识库
- 可扩展的工具集合
- 开发模式独立端口 (8002)，生产模式集成到主服务

#### MCP 可用工具

| 工具名 | 功能 |
|--------|------|
| `list_collections` | 列出所有知识库集合 |
| `list_documents` | 列出集合中的文档 |
| `search_knowledge` | 搜索知识库 |
| `get_document_chunks` | 获取文档分块内容 |
| `get_collection_stats` | 获取集合统计信息 |

#### Claude Desktop 配置

```json
{
  "mcpServers": {
    "knowledge-system": {
      "url": "http://localhost:8002/sse"
    }
  }
}
```

---

## 📁 项目结构

```
knowledge_system/
├── console/                  # 前端 Web Console
│   ├── src/
│   │   ├── api/             # API 客户端
│   │   ├── components/      # React 组件
│   │   ├── pages/           # 页面组件
│   │   ├── stores/          # Zustand 状态管理
│   │   └── utils/           # 工具函数
│   └── package.json
├── src/
│   └── knowledge_system/    # 后端源码
│       ├── api/             # FastAPI 路由
│       ├── services/        # 业务逻辑
│       ├── parsers/         # 文档解析器
│       ├── chunkers/        # 文档分块器
│       ├── tokenizers/      # 分词器
│       ├── models/          # 数据模型
│       └── db/              # 数据库操作
├── tests/                   # 测试文件
├── docs/                    # 文档
├── .env.example             # 环境变量示例
├── pyproject.toml          # 项目配置
└── README.md
```

---

## ⚙️ 配置说明

### 环境变量

复制 `.env.example` 为 `.env` 并根据需要修改：

```bash
# API 配置
API_HOST=0.0.0.0
API_PORT=8000
API_DEBUG=true
API_CORS_ORIGINS=http://localhost:5173,http://localhost:8080

# ChromaDB 配置（嵌入式模式）
CHROMADB_PERSIST_DIRECTORY=./data/chromadb

# 文档存储配置（本地文件系统）
DOCUMENT_STORAGE_PATH=./data/documents
MAX_FILE_SIZE_MB=50

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=./logs/app.log

# MCP 服务配置（开发模式独立端口）
MCP_SERVER_PORT=8002
MCP_SERVER_AUTH_ENABLED=false

# 密钥存储配置
KEYRING_BACKEND=json
KEYRING_FILE=./data/keyring.json
```

> **注意**：生产模式下 MCP 服务自动集成到主服务 (8000)，无需单独配置端口。

### 首次使用

1. 启动服务后，在 Web 界面中配置嵌入模型
2. 创建第一个知识库集合
3. 上传文档开始使用

---

## 📖 文档

- **设计文档**：[DESIGN.md](file:///workspace/knowledge_system/DESIGN.md) - 完整的项目设计说明
- **API 文档**：(待补充) - 在线 API 文档
- **部署指南**：(待补充) - 生产环境部署指南

---

## 🛣️ 项目路线图

### Phase 1：基础功能 (MVP)
- [x] 项目框架搭建
- [x] ChromaDB 集成
- [x] 集合管理 CRUD
- [x] 文档上传和解析（docx, md, txt）
- [x] 固定长度文档分块
- [x] 向量搜索
- [x] 基础 Web UI

### Phase 2：增强功能
- [x] 混合搜索（向量 + 关键词）
- [x] 文档版本管理
- [x] 文档分类和标签
- [x] MCP 服务暴露
- [x] 完整 Web UI（文档预览、编辑）
- [x] 统计页面

### Phase 3：优化和扩展
- [ ] 性能优化
- [ ] 更多文档格式支持（PDF, Excel）
- [ ] 插件系统
- [ ] 备份和恢复
- [ ] Docker 部署优化

---

## 🤝 参与贡献

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

1. Fork 本仓库
2. 新建功能分支：`git checkout -b feat/your-feature-name`
3. 提交更改：`git commit -m "feat: add your feature"`
4. 推送到分支：`git push origin feat/your-feature-name`
5. 创建 Pull Request

请确保代码符合项目规范：
- 遵循 PEP 8 代码风格
- 添加必要的文档和注释
- 编写单元测试
- 确保所有测试通过

---

## 🔒 安全说明

- API Key 加密存储在本地
- 无需登录认证（本地使用）
- 所有数据本地存储，不上传到第三方
- 提供工具防护功能（待实现）

---

## 📄 许可证

Apache 2.0 许可证，请查看 [LICENSE](LICENSE) 文件了解详细信息。

---

## 🙏 致谢

本项目参考了以下优秀项目：
- [QwenPaw](https://github.com/agentscope-ai/QwenPaw) - 主要参考项目
- [LangChain](https://github.com/langchain-ai/langchain) - 文档处理参考
- [Chroma](https://github.com/chroma-core/chroma) - 向量数据库参考

---

**系统版本**：0.2.0  
**创建日期**：2026-05-30  
**最后更新**：2026-06-01