# MiniAgent
面向个人与小团队的轻量级智能体平台。
**简单架构 · 显式代码 · 易于部署 · 方便扩展**
[License](LICENSE) · [API 文档（本地启动后）](http://localhost:10088/docs)
> [!IMPORTANT]
> MiniAgent 当前处于开发阶段，数据库结构和接口会不断调整。升级前请备份 `backend/db` 与 `backend/files`。
## 项目简介
MiniAgent 提供从模型配置、知识库构建、智能体编排到最终用户对话的完整工作流。项目包含 FastAPI 后端、PureAdmin 管理后台和独立的 Workplace 用户工作台，适合用于搭建企业知识助手、内部数据助手、法律顾问以及其他垂直领域智能体。
## 核心功能
### 智能体与模型
- 创建和管理多个智能体，配置系统提示词、LLM 与工具
- 支持 OpenAI 兼容接口、Ollama 等模型服务
- 管理 LLM、Embedding、工具、领域插件与路由策略
- 基于用户—智能体授权关系控制智能体使用范围
- 支持同步调用与 SSE 流式响应
### RAG 知识库
- 管理多个知识库、文档与切片
- 支持 PDF、Word、文本、表格等常见文档格式
- ChromaDB 向量检索与 BM25 关键词检索
- 支持 RRF 融合、阈值过滤、可选重排与 Small-to-Big 检索
- 支持多知识库智能路由及领域处理插件
### SQL 与工具能力
- 使用 DuckDB 分析 CSV、Excel 等结构化数据
- SQL Agent 支持数据查询、统计分析与图表数据生成
- 可扩展工具系统与 Web Search 能力
- 智能体运行时工具缓存及配置失效机制
### 权限与运维
- JWT 登录、Access Token 自动刷新与 RBAC 权限控制
- 密码复杂度校验和登录失败锁定
- 管理员可解除用户锁定并维护用户智能体授权
- 登录日志、审计日志与系统配置管理
- API、SQLite、DuckDB 和硬件资源状态监控
### 双前端
- **Management**：基于 PureAdmin 的系统管理后台
- **Workplace**：面向最终用户的智能体工作台
- 登录、自动刷新 Token、退出登录
- 中文 `zh_CN` 与英文 `en_US`
- 多套主题色调
- 选择授权智能体
- 查询、查看、重命名和删除会话
- Markdown 消息及 SSE 流式对话
## 系统架构
```mermaid
flowchart TB
Admin["Management 管理后台"]
User["Workplace 用户工作台"]
API["FastAPI API"]
subgraph Core["应用核心"]
Auth["JWT / RBAC"]
Container["ServiceContainer"]
Agent["AgentFactory / AgentRunner"]
Tools["Tool Builder"]
KB["RAG Retrieval Pipeline"]
SQL["SQL Agent"]
end
subgraph Data["数据层"]
SQLite[(SQLite)]
DuckDB[(DuckDB)]
Chroma[(ChromaDB)]
BM25[(BM25 Index)]
Files[(Local Storage)]
end
Admin --> API
User --> API
API --> Auth
API --> Container
Container --> Agent
Agent --> Tools
Agent --> KB
Agent --> SQL
Container --> SQLite
SQL --> DuckDB
KB --> Chroma
KB --> BM25
KB --> Files
```
后端采用清晰的分层结构：
- `app/api/`：HTTP 路由、依赖注入与请求响应转换
- `app/services/`：业务逻辑
- `app/runtime/`：智能体、会话、LLM、检索等运行时组件
- `app/repositories/`：异步数据库访问
- `app/schemas/`：Pydantic 数据模型
- `app/infra/`：数据库模型、缓存、初始化与基础设施
启动过程:
- DB init — app/infra/db/initializer.py 创建 SQLite 表并从 app/infra/db/seed/ 加载种子 JSON
- ServiceContainer — 构建异步 SQLAlchemy 引擎、所有存储库和长期运行的服务
- Domain plugins — 从数据库加载领域行并通过动态导入注册知识库处理器
所有共享资源都位于 request.app.state.container 中。路由通过 Depends(get_container) 获取它。
## 技术栈
| 模块 | 技术 |
| ---------- | --------------------------------------------------- |
| 后端 | Python、FastAPI、Pydantic、SQLAlchemy Async、Loguru |
| 智能体 | LangChain、自定义 Agent Runtime |
| 管理后台 | Vue 3、TypeScript、PureAdmin、Element Plus、Pinia |
| 用户工作台 | Vue 3、TypeScript、Vite、Element Plus、Vue I18n |
| 业务数据库 | SQLite |
| 分析数据库 | DuckDB |
| 向量数据库 | ChromaDB |
| 检索 | Vector Search、BM25、RRF、Reranker |
## 目录结构
```text
miniagent/
├── backend/ # FastAPI 后端
│ ├── app/
│ │ ├── api/ # Admin、User、Auth、运维接口
│ │ ├── core/ # 配置、安全、依赖注入、i18n
│ │ ├── infra/ # ORM、数据库初始化、缓存
│ │ ├── repositories/ # 异步数据访问层
│ │ ├── runtime/ # Agent、LLM、会话与运行时组件
│ │ ├── schemas/ # Pydantic DTO
│ │ └── services/ # 业务服务
│ ├── db/ # 本地数据库与索引（运行时生成）
│ ├── files/ # 上传文件（运行时生成）
│ ├── .env.example # 环境变量模板
│ └── requirements.txt
├── management/ # PureAdmin 管理后台
├── workplace/ # 最终用户工作台
├── docker-compose.yml
├── setup.bat
├── setup.sh
└── README.md
```
## 环境要求
- Python 3.12 或更高版本
- Node.js 20.19+ 或 22.13+
- pnpm 9 或更高版本
- 可用的 LLM 服务，例如 Ollama 或 OpenAI 兼容接口
- 可选：NVIDIA GPU 与对应驱动
## 快速开始
### 1. 获取代码
```bash
git clone https://github.com/liupras/miniagent.git
cd miniagent
```
### 2. 配置并启动后端
Windows PowerShell：
```powershell
Set-Location backend
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env
```
Linux/macOS：
```bash
cd backend
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp .env.example .env
```
打开 `backend/.env`，至少修改 JWT 密钥，并配置实际使用的模型服务。然后启动 API：
```bash
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 10088
```
应用首次启动时会自动创建数据库并载入种子数据。
### 3. 启动管理后台
打开一个新终端：
```bash
cd management
pnpm install
pnpm dev
```
默认地址：