# aikb

**Repository Path**: kingecg/aikb

## Basic Information

- **Project Name**: aikb
- **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-01-29
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Knowledge Base (AIKB)

基于 LangChain.js 和 Ollama 构建的智能知识库系统，提供文档处理、知识检索、智能对话和推理能力。

## 功能特性

- 📚 **文档处理**: 支持 PDF、DOCX、TXT 格式文档上传和处理
- 🔍 **知识检索**: 向量相似性搜索与 MMR 多样性优化
- 💬 **智能对话**: 支持流式响应和工具调用的聊天接口
- 🧠 **推理引擎**: 结合知识库的智能推理和问题解决
- 🔧 **工具集成**: 支持 MCP (Model Context Protocol) 工具动态注册
- ⚡ **流式响应**: 实时 SSE 流式输出，优化用户体验
- 🛡️ **安全可靠**: 输入验证、错误处理和工具执行安全机制

## 系统架构

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   客户端    │────▶│   API层     │────▶│  服务层     │
└─────────────┘     └─────────────┘     └─────────────┘
                           │                    │
                    ┌─────────────┐     ┌─────────────┐
                    │  中间件     │     │ LangChain   │
                    │  (认证/限流)│     │  集成层     │
                    └─────────────┘     └─────────────┘
                                             │
                                    ┌─────────────────┐
                                    │ 基础设施层       │
                                    │ (Ollama/Chroma) │
                                    └─────────────────┘
```

## 快速开始

### 环境要求

- Node.js 18+
- Ollama (本地 LLM 服务)
- ChromaDB (向量数据库，可选)

### 1. 安装依赖

```bash
# 克隆项目
git clone <repository-url>
cd aikb

# 安装依赖
npm install
```

### 2. 配置环境

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，根据实际情况修改配置
```

### 3. 启动服务

```bash
# 开发模式（带热重载）
npm run dev

# 生产构建
npm run build
npm start

# 运行测试
npm test
```

### 4. 访问服务

服务器启动后，访问以下地址：

- API 文档: http://localhost:3000
- 健康检查: http://localhost:3000/api/health/health
- 就绪检查: http://localhost:3000/api/health/ready

## API 接口

### 知识库管理

```http
POST /api/knowledge/upload
Content-Type: multipart/form-data

文件上传，支持 PDF、DOCX、TXT 格式
```

```http
POST /api/knowledge/retrieve
Content-Type: application/json

{
  "query": "查询内容",
  "maxResults": 5,
  "similarityThreshold": 0.7
}
```

### 聊天接口

```http
POST /api/chat/stream
Content-Type: application/json
Accept: text/event-stream

{
  "message": "用户消息",
  "sessionId": "会话ID",
  "context": {
    "toolsEnabled": true
  }
}
```

### 推理接口

```http
POST /api/chat/reason/stream
Content-Type: application/json
Accept: text/event-stream

{
  "query": "推理问题",
  "sessionId": "会话ID",
  "knowledgeBaseOnly": true
}
```

### 工具管理

```http
POST /api/tools/register
Content-Type: application/json

{
  "description": "MCP 工具描述",
  "serverUrl": "http://localhost:8080"
}
```

## 配置说明

### 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `PORT` | 3000 | 服务端口 |
| `NODE_ENV` | development | 运行环境 |
| `OLLAMA_BASE_URL` | http://localhost:11434 | Ollama 服务地址 |
| `OLLAMA_MODEL` | deepseek-r1:1.5b | 使用的模型 |
| `CHROMA_URL` | http://localhost:8000 | ChromaDB 地址 |
| `MAX_FILE_SIZE` | 10485760 | 最大文件大小 (10MB) |
| `MCP_TOOLS_DIR` | ./tools | MCP 工具目录 |

### 模型配置

系统使用以下模型：

- **对话模型**: deepseek-r1:1.5b (可通过 Ollama 获取)
- **嵌入模型**: nomic-embed-text (文本嵌入)

## 开发指南

### 项目结构

```
aikb/
├── src/
│   ├── config/          # 配置模块
│   ├── services/        # 服务层
│   │   └── knowledge/   # 知识库服务
│   ├── agents/          # 代理层
│   ├── tools/           # 工具管理
│   ├── api/             # API 层
│   │   ├── controllers/ # 控制器
│   │   ├── middleware/  # 中间件
│   │   └── routes/      # 路由
│   ├── utils/           # 工具函数
│   └── index.ts         # 应用入口
├── tests/               # 测试文件
├── uploads/             # 上传文件存储
├── knowledge/           # 知识库文件
└── tools/               # MCP 工具定义
```

### 代码规范

- 使用 TypeScript 进行类型检查
- ESLint + Prettier 代码格式化
- 遵循项目约定的命名规范
- 编写清晰的错误处理和日志记录

### 添加新功能

1. **添加新工具**:
   - 在 `src/tools/builtin.ts` 中定义新工具
   - 遵循 `ToolDefinition` 接口
   - 注册到推理代理中

2. **添加新 API**:
   - 在 `src/api/controllers/` 创建控制器
   - 在 `src/api/routes/` 添加路由
   - 更新主路由配置

3. **添加新服务**:
   - 在 `src/services/` 创建服务模块
   - 实现清晰的接口定义
   - 集成到主应用中

## 部署

### 本地部署

1. 确保 Ollama 和 ChromaDB 服务正在运行
2. 配置环境变量
3. 构建并启动应用

### 生产部署建议

- 使用 Nginx 反向代理
- 配置 SSL/TLS 加密
- 设置系统服务（systemd）
- 监控和日志管理

## 故障排除

### 常见问题

1. **Ollama 连接失败**
   - 检查 Ollama 服务是否运行
   - 验证 `OLLAMA_BASE_URL` 配置

2. **ChromaDB 连接失败**
   - 检查 ChromaDB 服务状态
   - 验证 `CHROMA_URL` 配置
   - 或设置 `USE_CHROMA=false` 使用内存向量存储

3. **文件上传失败**
   - 检查文件大小限制
   - 验证文件类型支持
   - 检查上传目录权限

4. **工具调用失败**
   - 检查 MCP 服务地址
   - 验证工具定义格式
   - 查看服务日志

### 日志查看

```bash
# 查看应用日志
tail -f logs/app.log

# 查看错误日志
tail -f logs/app-error.log
```

## 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 许可证

本项目采用 ISC 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 联系方式

- 项目地址: [GitHub Repository](https://github.com/yourusername/aikb)
- 问题反馈: [Issues](https://github.com/yourusername/aikb/issues)

---

**注意**: 本项目处于开发阶段，API 可能会有变更。建议在生产环境使用前进行全面测试。