# knowledge

**Repository Path**: carllee34/knowledge

## Basic Information

- **Project Name**: knowledge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 金融知识库智能化系统

## 项目概述

本项目是一个基于前后端分离架构设计的金融知识库智能化系统，旨在为金融行业提供统一的知识管理、智能检索和合规保障平台。系统采用 **FastAPI + React** 技术栈，集成大语言模型（LLM）和向量数据库技术，提供高性能、现代化的知识服务。

## 主要特性

- **智能检索**：支持自然语言语义搜索和多维度筛选
- **智能问答**：基于知识库的AI问答系统，支持对话历史
- **合规管理**：自动化合规检查和风险评估
- **知识发现**：智能内容推荐和关联分析
- **知识图谱**：基于 LLM 的实体/关系抽取，图谱可视化浏览
- **MCP 服务**：以标准 MCP 协议对外开放知识库与图谱查询能力
- **用户认证**：注册/登录，JWT Token 认证，管理员与普通用户角色
- **多格式支持**：支持PDF、Word、Excel等多种文档格式
- **前后端分离**：FastAPI 高性能后端 + React 现代前端

## 技术架构

```
┌─────────────────────────────────────────────────────────────┐
│                        前端 (Frontend)                       │
│  React 18 + TypeScript + Vite + Tailwind CSS               │
│  端口: 8080                                                │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP / WebSocket
┌────────────────────────▼────────────────────────────────────┐
│                        后端 (Backend)                        │
│  FastAPI + Uvicorn（单 worker，因数据在内存中）              │
│  端口: 8000                                                │
│  自动 API 文档: /docs                                       │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                      数据层 (Data Layer)                     │
│  内存向量索引 + Pickle 持久化 (默认)                        │
│  Neo4j (可选，知识图谱)                                     │
│  PostgreSQL / MongoDB / Redis (预留，当前未使用)           │
└─────────────────────────────────────────────────────────────┘
```

## 技术栈

### 后端
- **Web框架**: FastAPI (ASGI, 原生 async)
- **AI框架**: OpenAI 兼容接口
- **向量检索**: 内存 FAISS-like 索引 + NumPy
- **文档处理**: PyPDF2, python-docx, openpyxl, python-pptx
- **数据验证**: Pydantic v2
- **部署**: Uvicorn + Docker

### 前端
- **框架**: React 18 + TypeScript
- **构建工具**: Vite
- **路由**: React Router v6
- **样式**: Tailwind CSS
- **图标**: Lucide React
- **HTTP客户端**: Axios

## 快速开始

### 环境要求

- Docker 20.10+
- Docker Compose 2.0+
- Node.js 18+ (前端开发)
- Python 3.10+ (后端开发)

### Docker 部署（推荐）

1. **克隆项目**
```bash
git clone <repository-url>
cd knowledgeS
```

2. **配置环境变量**
```bash
cp .env.example .env
# 编辑 .env 文件，配置 OPENAI_API_KEY 等必要变量
```

3. **启动所有服务**
```bash
docker compose up -d --build
```

前端镜像为多阶段构建（Node 阶段执行 `npm run build`，Nginx 阶段提供静态文件并反向代理 `/api` 到后端），无需在宿主机预先构建 `dist/`。

4. **验证服务状态**
```bash
docker compose ps
```

注意：compose 中的 PostgreSQL / MongoDB / Redis 为预留服务（当前后端未连接），Neo4j 仅在配置 `GRAPH_STORAGE_TYPE=neo4j` 时使用；核心功能只依赖 backend 与 frontend 两个服务。

### 服务访问地址

- **前端Web界面**: http://localhost:8080
- **后端API文档**: http://localhost:8000/docs
- **API健康检查**: http://localhost:8000/api/v1/health

### 手动安装（开发环境）

**后端**
```bash
cd backend
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

**前端**
```bash
cd frontend
npm install
npm run dev
# 访问 http://localhost:5173
```

## 使用指南

### Web 界面

1. **登录/注册** (http://localhost:8080/login)
   - 用户注册（默认普通用户角色）与登录
   - 登录后获取 JWT Token，前端自动携带访问各业务接口

2. **首页/仪表盘** (http://localhost:8080/)
   - 系统概览、快捷入口、文档快速上传
   - 系统状态和文档统计

3. **文档管理** (http://localhost:8080/documents)
   - 上传文档（支持多格式）
   - 查看文档列表、内容预览与处理状态
   - 下载/删除文档

4. **智能检索** (http://localhost:8080/search)
   - 输入自然语言查询
   - 查看相关文档和相似内容
   - 相似度评分展示

5. **智能问答** (http://localhost:8080/qa)
   - 输入问题获取AI回答
   - 查看答案来源和置信度
   - 对话历史管理

6. **合规检查** (http://localhost:8080/compliance)
   - 管理法规库
   - 对文档内容进行合规性检查
   - 查看风险评估报告

7. **智能推荐** (http://localhost:8080/recommendations)
   - 个性化知识推荐
   - 热门内容展示

8. **知识图谱** (http://localhost:8080/graph)
   - 实体/关系统计与类型浏览
   - 图谱可视化与邻居探索

### API 接口

所有接口前缀为 `/api/v1/`，完整文档见 `/docs`。**除健康检查和注册/登录外，所有接口都需要认证**：在请求头携带 `Authorization: Bearer <token>`（token 通过登录接口获取）；当后端配置了 `API_KEY` 环境变量时，也可使用 `X-API-Key: <key>` 头。

#### 登录获取 Token
```bash
curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "your-username", "password": "your-password"}'
# 响应 data.token 即为 JWT，有效期 7 天
```

#### 健康检查
```bash
curl http://localhost:8000/api/v1/health
```

#### 文档上传
```bash
curl -X POST "http://localhost:8000/api/v1/documents/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@document.pdf"
```

#### 智能搜索
```bash
curl -X POST "http://localhost:8000/api/v1/search" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "金融风险管理", "top_k": 10}'
```

#### 智能问答
```bash
curl -X POST "http://localhost:8000/api/v1/qa" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"question": "什么是巴塞尔协议？", "user_id": "user-1"}'
```

#### 合规检查
```bash
curl -X POST "http://localhost:8000/api/v1/compliance/check" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"process_id": "proc-001", "document_content": "文档内容..."}'
```

#### MCP 服务

端点 `POST /api/v1/mcp`（Streamable HTTP 传输），JWT Bearer 鉴权，对外提供 8 个只读工具（知识库检索/问答/文档读取、图谱统计/实体检索/邻居查询）。在支持 MCP 的客户端中配置：

```json
{
  "mcpServers": {
    "knowledge-base": {
      "url": "http://localhost:8000/api/v1/mcp",
      "headers": {"Authorization": "Bearer <登录获取的 JWT>"}
    }
  }
}
```

非 localhost 部署需在 `.env` 中配置 `MCP_ALLOWED_HOSTS`（逗号分隔的主机名）。

## 项目结构

```
knowledgeS/
├── backend/                  # FastAPI 后端
│   ├── app/
│   │   ├── main.py           # 应用入口
│   │   ├── routers/          # API 路由
│   │   │   ├── auth.py       #   注册/登录/用户管理（JWT）
│   │   │   ├── health.py     #   健康检查
│   │   │   ├── documents.py  #   文档上传/列表/预览/下载/删除
│   │   │   ├── search.py     #   混合检索
│   │   │   ├── qa.py         #   问答
│   │   │   ├── compliance.py #   合规检查
│   │   │   ├── recommendations.py  # 推荐
│   │   │   └── graph.py      #   知识图谱
│   │   ├── middleware/       # 预留目录（当前为空包）
│   │   ├── dependencies.py   # 依赖注入（引擎懒加载 + 认证依赖）
│   │   ├── auth_utils.py     # JWT 签发/校验、密码哈希
│   │   ├── schemas.py        # Pydantic 模型
│   │   └── config.py         # 配置管理
│   ├── core/                 # 核心逻辑
│   │   ├── knowledge.py      # 知识处理
│   │   ├── search.py         # 搜索引擎
│   │   ├── qa.py             # 问答引擎
│   │   ├── compliance.py     # 合规引擎
│   │   ├── recommend.py      # 推荐引擎
│   │   ├── llm.py            # LLM 调用
│   │   ├── embedding.py      # 向量嵌入（MockVectorizer 仅供演示）
│   │   ├── storage.py        # 存储层（内存 + pickle）
│   │   ├── entity_extractor.py  # 实体/关系抽取
│   │   ├── graph_models.py   # 知识图谱数据模型
│   │   ├── graph_storage.py  # 图谱存储（内存 / Neo4j）
│   │   └── models.py         # 数据模型
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/                 # React 前端
│   ├── src/
│   │   ├── pages/            # 页面组件（Login/Documents/Search/QA/...）
│   │   ├── components/       # 可复用组件
│   │   ├── api/              # API 客户端
│   │   ├── hooks/            # 自定义 hooks
│   │   └── types/            # TypeScript 类型
│   ├── Dockerfile            # 多阶段构建（Node 构建 + Nginx 服务）
│   └── package.json
├── docs/                     # 文档（archive/ 子目录为历史版本）
├── tests/                    # 测试
│   └── test_api_integration.py
├── docker-compose.yml
├── pyproject.toml
└── README.md
```

## 开发指南

### 代码规范
```bash
# 后端格式化
black backend/ tests/
isort backend/ tests/

# 前端格式化
cd frontend && npm run build
```

### 运行测试
```bash
# 后端 API 测试
cd tests && pytest test_api_integration.py -v
```

## 配置说明

### 环境变量

创建 `.env` 文件并配置以下变量：

```env
# 认证配置
JWT_SECRET_KEY=your-jwt-secret-key        # JWT 签名密钥，生产必须修改
API_KEY=                                   # 可选；配置后接受 X-API-Key 头认证
ADMIN_INITIAL_PASSWORD=                    # 可选；配置后启动时创建默认 admin 账号

# AI 配置
OPENAI_API_KEY=your-openai-api-key
OPENAI_API_BASE=https://ark.cn-beijing.volces.com/api/v3
LLM_MODEL=gpt-3.5-turbo
AI_TEMPERATURE=0.7

# 应用配置
SECRET_KEY=your-secret-key
CORS_ORIGINS=*
```

完整变量列表见 `.env.example`。

## 性能优化

- **单 worker 运行**: 后端 Docker 以单 worker 运行（数据在内存中，多进程会导致数据不一致；生产环境应接入真实数据库后再水平扩展）
- **前端静态资源**: Nginx 高效服务静态文件
- **懒加载引擎**: 各核心引擎按需初始化
- **数据持久化**: 内存数据在应用关闭时 pickle 持久化

## 安全考虑

- JWT Bearer Token 认证（`/api/v1/auth/login` 签发，有效期 7 天）；配置 `API_KEY` 后支持 `X-API-Key` 头
- 注册接口强制普通用户角色；默认 admin 仅在配置 `ADMIN_INITIAL_PASSWORD` 时创建
- bcrypt 密码哈希存储
- CORS 跨域控制
- 文件上传类型限制
- 请求体大小限制

## 许可证

本项目采用 MIT 许可证。