mirror of
https://github.com/666ghj/MiroFish.git
synced 2026-05-02 08:31:58 +00:00
08688a892d
- Modified the backend setup script to clear the virtual environment before installation. - Improved README.md by restructuring the prerequisites section into a table for better readability. - Added installation instructions for the `uv` package and clarified terminal requirements post-installation.
209 lines
4.6 KiB
Markdown
209 lines
4.6 KiB
Markdown
# MiroFish 🐟
|
||
|
||
**简洁通用的群体智能引擎，预测万物**
|
||
|
||
MiroFish 是一个基于多智能体（Multi-Agent）技术的社交媒体舆情模拟平台，能够模拟 Twitter/Reddit 等社交媒体上的用户行为，预测舆情发展趋势。
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
MiroFish/
|
||
├── backend/ # Flask 后端服务
|
||
│ ├── app/ # 应用核心代码
|
||
│ ├── scripts/ # OASIS 模拟脚本
|
||
│ ├── requirements.txt
|
||
│ └── run.py # 后端启动入口
|
||
├── frontend/ # Vue 3 前端
|
||
│ ├── src/
|
||
│ ├── package.json
|
||
│ └── vite.config.js
|
||
├── .env.example # 环境变量示例
|
||
├── docker-compose.yml # Docker 部署配置
|
||
├── package.json # 根目录启动脚本
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
|
||
在开始之前，请确保已安装以下工具：
|
||
|
||
| 工具 | 版本要求 | 说明 | 安装检查 |
|
||
|------|---------|------|---------|
|
||
| **Node.js** | 18+ | 前端运行环境，包含 npm | `node -v` |
|
||
| **Python** | 3.11+ | 后端运行环境 | `python --version` |
|
||
| **uv** | 最新版 | Python 包管理器（替代 pip） | `uv --version` |
|
||
|
||
#### 安装 uv
|
||
|
||
```bash
|
||
# macOS/Linux
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
|
||
# Windows (PowerShell)
|
||
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
|
||
|
||
# 或使用 Homebrew (macOS)
|
||
brew install uv
|
||
```
|
||
|
||
> ⚠️ 安装 uv 后需要**重新打开终端**或执行 `source ~/.zshrc` (macOS/Linux) 使其生效。
|
||
|
||
### 配置环境变量
|
||
|
||
```bash
|
||
# 复制示例配置文件
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，填入必要的 API 密钥
|
||
```
|
||
|
||
必需的环境变量：
|
||
|
||
```env
|
||
# LLM 配置（支持 OpenAI 格式的任意 LLM）
|
||
LLM_API_KEY=your_api_key
|
||
LLM_BASE_URL=https://api.openai.com/v1
|
||
LLM_MODEL_NAME=gpt-4o-mini
|
||
|
||
# Zep Cloud 配置
|
||
ZEP_API_KEY=your_zep_api_key
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 部署方式一：源码部署（开发推荐）
|
||
|
||
使用 `concurrently` 同时启动前后端，**跨平台兼容**（Windows/macOS/Linux）。
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
# 一键安装所有依赖（根目录 + 前端 + 后端）
|
||
npm run setup:all
|
||
```
|
||
|
||
或者分步安装：
|
||
|
||
```bash
|
||
# 安装 Node 依赖（根目录 + 前端）
|
||
npm run setup
|
||
|
||
# 安装 Python 依赖（自动创建虚拟环境）
|
||
npm run setup:backend
|
||
```
|
||
|
||
### 2. 启动服务
|
||
|
||
```bash
|
||
# 同时启动前后端（在项目根目录执行）
|
||
npm run dev
|
||
```
|
||
|
||
服务地址：
|
||
- 前端：`http://localhost:3000`
|
||
- 后端 API：`http://localhost:5001`
|
||
|
||
### 单独启动
|
||
|
||
```bash
|
||
# 仅启动后端
|
||
npm run backend
|
||
|
||
# 仅启动前端
|
||
npm run frontend
|
||
```
|
||
|
||
---
|
||
|
||
## 🐳 部署方式二：Docker 部署（生产推荐）
|
||
|
||
### 前置要求
|
||
|
||
- Docker 20.10+
|
||
- Docker Compose v2+
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 构建并启动所有服务
|
||
docker compose up -d
|
||
|
||
# 查看日志
|
||
docker compose logs -f
|
||
|
||
# 停止服务
|
||
docker compose down
|
||
```
|
||
|
||
服务地址：
|
||
- 前端：`http://localhost:3000`
|
||
- 后端 API：`http://localhost:5001`
|
||
|
||
### 仅构建镜像
|
||
|
||
```bash
|
||
# 构建后端镜像
|
||
docker build -t mirofish-backend ./backend
|
||
|
||
# 构建前端镜像
|
||
docker build -t mirofish-frontend ./frontend
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠 技术栈
|
||
|
||
### 后端
|
||
- **框架**: Flask 3.x
|
||
- **LLM 调用**: OpenAI SDK
|
||
- **图谱存储**: Zep Cloud
|
||
- **模拟引擎**: OASIS (camel-oasis)
|
||
|
||
### 前端
|
||
- **框架**: Vue 3 + Composition API
|
||
- **构建工具**: Vite
|
||
- **可视化**: D3.js
|
||
- **HTTP 客户端**: Axios
|
||
|
||
---
|
||
|
||
## ⚙️ 环境变量说明
|
||
|
||
| 变量名 | 必需 | 说明 | 默认值 |
|
||
|--------|------|------|--------|
|
||
| `LLM_API_KEY` | ✅ | LLM API 密钥 | - |
|
||
| `LLM_BASE_URL` | ❌ | LLM API 地址 | `https://api.openai.com/v1` |
|
||
| `LLM_MODEL_NAME` | ❌ | 模型名称 | `gpt-4o-mini` |
|
||
| `ZEP_API_KEY` | ✅ | Zep Cloud API 密钥 | - |
|
||
| `FLASK_DEBUG` | ❌ | 调试模式 | `true` |
|
||
| `FLASK_HOST` | ❌ | 后端监听地址 | `0.0.0.0` |
|
||
| `FLASK_PORT` | ❌ | 后端端口 | `5001` |
|
||
|
||
---
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Q: 后端启动报错 "LLM_API_KEY 未配置"
|
||
A: 确保 `.env` 文件在项目根目录，且配置了正确的 API 密钥。
|
||
|
||
### Q: 前端无法连接后端
|
||
A: 检查后端是否正常运行在 5001 端口，前端开发服务器会自动代理 `/api/*` 请求。
|
||
|
||
### Q: OASIS 模拟启动失败
|
||
A: 确保已安装 `camel-oasis` 和 `camel-ai` 依赖，且 LLM API 配置正确。
|
||
|
||
### Q: 运行 `npm run setup:backend` 报错 "uv: command not found"
|
||
A: uv 未安装或未加入 PATH。请先安装 uv（参考前置要求），安装后**重新打开终端**再执行。
|
||
|
||
### Q: Windows 上 Python 虚拟环境激活失败
|
||
A: 使用 `.venv\Scripts\activate` 而不是 `source .venv/bin/activate`。
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT License
|