MiroFish — 群体智能预测引擎深度分析
简洁通用的群体智能引擎，预测万物
A Simple and Universal Swarm Intelligence Engine, Predicting Anything
1. 项目概述
| 属性 | 内容 |
|---|
| 项目 | MiroFish by 666ghj |
| 许可证 | AGPL-3.0 |
| 孵化方 | 盛大集团 (Shanda Group) |
| 代码量 | ~21,030 行 Python |
| 技术栈 | Flask (Python 3.11-3.12) + Vue 3 (Vite) + Zep Cloud + OASIS + OpenAI SDK |
| 生态位 | 多Agent社会仿真 → 预测分析报告 |
| 核心依赖 | camel-oasis==0.2.5, camel-ai==0.2.78, zep-cloud==3.13.0 |
核心思想：从现实世界提取"种子信息"（新闻、政策草案、金融信号），自动构建高保真平行数字世界，让成千上万个具备独立人格、长期记忆与行为逻辑的智能体自由交互与社会演化，从而推演未来走向。
2. 系统架构（5步工作流）
Step 1：图谱构建 — Graph Building
| 组件 | 作用 | 核心逻辑 |
|---|
OntologyGenerator |
分析文本→设计本体 |
LLM自动生成10个实体类型 + 6-10个关系类型；强制包含 Person/Organization 兜底类型；所有输出转为 Zep API 兼容格式 |
GraphBuilderService |
调用 Zep Cloud 建图 |
文本分块(chunk=500/overlap=50) → 分批发送(batch=3) → 轮询等待 Zep 处理完成 → 返回 graph_id |
TextProcessor |
文本预处理 |
PDF/TXT/MD 解析，分块策略 |
关键技术决策：使用 Zep Cloud 作为知识图谱后端，而非本地 Neo4j。Zep 提供 GraphRAG 能力（实体提取+关系发现+语义搜索），支持边的时间维度（valid_at/invalid_at），天然适配社会模拟中的"随时间变化的关系"。
Step 2：环境搭建 — Environment Setup
| 组件 | 作用 | 核心逻辑 |
|---|
ZepEntityReader |
从 Zep 读取实体 |
分页遍历 nodes + edges，按实体类型过滤，附带边信息丰富 |
OasisProfileGenerator |
实体→Agent人设 |
LLM生成详细人设(bio/persona/MBTI/兴趣/立场)；支持并行生成(默认3并发)；区分个人实体和群体实体 |
SimulationConfigGenerator |
LLM自动生成模拟参数 |
分步生成策略：①时间配置 → ②事件配置 → ③分批Agent配置(每批15个) → ④平台配置 |
亮点：每个 Agent 的人设包含完整的 MBTI 性格类型、国家、职业、感兴趣话题，且通过 Zep 混合搜索（edges+nodes 双通道并行，RRF 重排序）从图数据库中检索相关上下文来丰富人设，使得生成的 Agent 更加"真实"。
Step 3：双平台并行模拟 — Simulation
| 组件 | 作用 | 核心逻辑 |
|---|
run_twitter_simulation.py |
Twitter 平台模拟 |
OASIS 引擎，支持发帖/点赞/转发/关注/引用 |
run_reddit_simulation.py |
Reddit 平台模拟 |
OASIS 引擎，支持发帖/评论/点赞/踩/搜索/趋势 |
run_parallel_simulation.py |
双平台并行调度 |
多进程同时运行 Twitter + Reddit，IPC 通道支持采访命令 |
SimulationRunner |
后台运行管理 |
subprocess + 监控线程；实时解析 actions.jsonl 输出状态 |
ZepGraphMemoryManager |
实时记忆更新(可选) |
将 Agent 活动（发帖/点赞/评论等）动态写回 Zep 图谱 |
模拟配置关键参数：
- 时间流速：每轮模拟60分钟（加速），默认模拟72小时（3天）
- 作息模型：中国作息时间，晚间19-22点高峰（×1.5），凌晨低谷（×0.05）
- 平台差异：Twitter 偏时效性(recency_weight=0.4)，Reddit 偏热度(popularity_weight=0.4)
- 回声室效应：可配置强度参数
- 病毒传播：可配置阈值（Twitter 10/Reddit 15次互动触发扩散）
Step 4：报告生成 — Report Generation
| 组件 | 作用 |
|---|
ReportAgent |
ReACT 模式报告生成器 |
ZepToolsService |
3种检索工具：InsightForge(深度)/PanoramaSearch(广度)/QuickSearch(快速) |
ReportManager |
报告生命周期管理 + 持久化 |
报告生成流程：
- 规划阶段：LLM 基于模拟需求+图谱信息生成目录大纲
- 分段生成：每章使用 ReACT 多轮推理，自主调用检索工具
- 反思机制：每段内容有2轮反思优化
- 完整日志：agent_log.jsonl 记录每一步推理和工具调用
Step 5：深度交互 — Deep Interaction
- 与模拟世界中的任意 Agent 进行 1v1 对话（Interview模式）
- 与 ReportAgent 进行对话，继续追问报告内容
- IPC 通道支持：采访 Agent 时自动添加前缀禁止其调用工具
3. 技术架构深度剖析
3.1 图谱记忆层 — Zep Cloud
Zep 是 MiroFish 的核心基础设施，承担：
- 知识图谱：实体节点 + 关系边，支持时间维度
- 本体管理：动态定义实体类型和关系类型
- 长期记忆：Agent 的社会行为（发帖/互动/关系变化）实时写回图谱
- 语义搜索：RRF 混合搜索，同时检索 edges 和 nodes
限制：最多10种自定义实体类型 + 10种自定义边类型
3.2 模拟引擎层 — OASIS (CAMEL-AI)
OASIS 提供底层社交模拟能力：
- 每个 Agent 有独立 LLM 驱动的人格和决策逻辑
- 支持 Twitter 和 Reddit 两种社交平台的行为模型
- Agent 间通过 feed（信息流）进行交互
- MiroFish 在此基础上增加了：中国作息时间模版、LLM 智能配置生成、双平台并行调度
3.3 LLM 驱动层
所有智能环节均通过 LLM 自动化（支持任意 OpenAI SDK 兼容 API，推荐 Qwen-Plus）：
- 本体设计（Ontology）
- Agent 人设生成（Profile）
- 模拟参数配置（Config）
- 报告生成（Report）
- Agent 行为决策（OASIS 内部）
3.4 前端层
- Vue 3 + Vue Router + Pinia 状态管理
- 5步引导式 UI（Graph Build → Env Setup → Simulation → Report → Interaction）
- 可视化图谱面板（GraphPanel.vue）
- 中英文双语支持（i18n）
3.5 关键数据流
[用户上传] → PDF/TXT/MD
↓
[OntologyGenerator] → LLM 分析 → 实体类型 + 关系类型定义
↓
[GraphBuilderService] → Zep Cloud → 知识图谱 (graph_id)
↓
[ZepEntityReader] → 读取实体 → 按类型过滤
↓
[OasisProfileGenerator] → Zep 混合检索丰富上下文 → LLM 生成人设
↓
[SimulationConfigGenerator] → LLM 分步生成配置
↓
[SimulationRunner] → OASIS 双平台并行模拟 → actions.jsonl
↓
[ZepGraphMemoryManager] → 实时写回 Zep（可选）
↓
[ReportAgent] → ReACT 多轮检索生成 → 最终报告
4. 如何用于"构建虚拟世界做预测分析"
4.1 适用场景
| 场景 | 示例 | 输入 |
|---|
| 舆情推演 | 武大舆情事件推演 | 新闻报道+政策草案 |
| 文学预测 | 红楼梦失传结局推演 | 前80回全文 |
| 金融市场(即将推出) | 政策对股市影响 | 经济数据+政策信号 |
| 时政新闻(即将推出) | 选举/外交事件推演 | 新闻+外交声明 |
4.2 预测能力来源
- 群体涌现：个体Agent的简单交互，在系统层面产生不可预测的涌现行为
- 高保真映射：Zep 图谱+LLM人设确保 Agent 的行为逻辑与真实世界对应实体高度一致
- 动态演化：模拟过程中 Agent 关系随时间变化，模拟真实社会的时间效应
- 平行实验：支持"上帝视角"注入变量，比较不同条件下的推演结果
- 多维度分析：ReportAgent 可以从多个角度（事实、实体、关系链）深度分析模拟结果
4.3 局限性
- LLM 成本：所有环节依赖 LLM，消耗较大（官方建议先小规模测试）
- Zep 平台依赖：图谱和记忆完全依赖 Zep Cloud，无法本地部署
- 模拟规模：Agent 数量受 OASIS 引擎和 LLM 推理速度限制
- 验证困难：预测结果难以量化验证（这是所有预测系统的共同挑战）
5. Docker-Compose 部署分析
5.1 架构概览 — 单容器单体部署
MiroFish 的 Docker 部署采用前端+后端合一的单容器架构，无独立数据库/缓存/队列容器。镜像托管于 GitHub Container Registry (GHCR)。
| 属性 | 值 |
|---|
| 镜像仓库 | ghcr.io/666ghj/mirofish:latest |
| 加速镜像 | ghcr.nju.edu.cn/666ghj/mirofish:latest（南大镜像） |
| 容器策略 | restart: unless-stopped |
| 暴露端口 | 3000（前端 Vite Dev Server） + 5001（Flask API） |
| 持久化卷 | ./backend/uploads:/app/backend/uploads（仅上传目录） |
5.2 Dockerfile 分析
| 阶段 | 指令 | 分析 |
|---|
| 基础镜像 |
FROM python:3.11 |
官方 Python 3.11 Debian 镜像，约 900MB。非 slim 版本，包含完整编译工具链 |
| Node.js 安装 |
apt-get install nodejs npm |
从 apt 仓库安装，不通过 nvm/nvm。版本不由代码控制（依赖Debian仓库） |
| uv 工具 |
COPY --from=ghcr.io/astral-sh/uv:0.9.26 |
多阶段构建复制 uv，版本锁定为 0.9.26。uv 是 Rust 编写的 Python 包管理器 |
| 缓存策略 |
先复制 package*.json/pyproject.toml 再 RUN |
利用 Docker 层缓存：依赖文件不变时不重复安装，加速CI |
| 依赖安装 |
npm ci + uv sync --frozen |
npm ci 严格按 lockfile 安装（比 npm install 更快更确定）；uv sync --frozen 禁止更新 lockfile |
| 启动命令 |
CMD ["npm", "run", "dev"] |
以开发模式运行，非生产级 HTTP 服务（Vite Dev Server + Flask dev server） |
5.3 GitHub Actions CI
| 配置 | 细节 |
|---|
| 触发器 | tag push（版本发布） + manual workflow_dispatch |
| 权限 | packages: write（推送到 GHCR） |
| 多架构 | QEMU + Buildx，支持 arm64/amd64 |
| 镜像标签 | tag名 + SHA + latest |
5.4 .dockerignore
排除项：.git/, .github/, .env, node_modules/, __pycache__/, frontend/dist/, backend/uploads/
注意：.env 在 ignore 列表中，但 docker-compose.yml 通过 env_file 字段注入，不影响运行。
5.5 关键问题
| 问题 | 风险 | 评估 |
|---|
| 开发模式启动 |
Vite Dev Server 带 hot reload，非生产优化；Flask dev server 单线程 |
⚠️ 不适合生产部署，需 Nginx 反向代理或改用 gunicorn |
| 无多阶段构建 |
最终镜像包含源码、编译工具、开发依赖 |
⚠️ 镜像体积大（~1.5GB+），建议生产用多阶段分离 |
| 单容器架构 |
前端静态文件与后端进程耦合，无法独立扩缩容 |
✅ 小规模场景够用，大规模需拆分 |
| 无健康检查 |
Docker 无法检测应用是否真正就绪 |
⚠️ 建议添加 healthcheck 和 depends_on 条件 |
| 权限过大 |
CI workflow 使用 GITHUB_TOKEN 直接 push packages |
✅ 标准做法，仅限于 tag 触发 |
6. 算力接入分析
6.1 计算模型 — 纯 API 调用，无本地 GPU
MiroFish 的计算模式为完全云端的 LLM API 调用，自身不进行任何本地模型推理。服务器端仅运行 Python 编排逻辑 + 文件 I/O。
| 环节 | API 调用频次 | Token 消耗 | 备注 |
|---|
| 本体生成 (Ontology) | 1次/项目 | 高（含全量文档） | max_tokens=4096 |
| 人设生成 (Profile) | N次/实体（并行3路） | 高（含Zep检索上下文） | 未设 max_tokens 上限 |
| 配置生成 (Config) | ~4次/项目 | 中 | response_format=json_object |
| OASIS 模拟 | M×R 次（Agent数×轮数） | 极高 | 主要开销来源，每轮每个Agent需多次 LLM 推理 |
| 报告生成 (Report) | 多轮 ReACT | 高 | 每章节多次推理+检索 |
6.2 LLM 接入配置
| 配置项 | 默认值 | 推荐值 |
|---|
LLM_API_KEY | -（必填） | 阿里百炼 DashScope |
LLM_BASE_URL | https://api.openai.com/v1 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
LLM_MODEL_NAME | gpt-4o-mini | qwen-plus |
LLM_BOOST_API_KEY | -（可选） | OASIS 模拟专用（低成本模型） |
LLM_BOOST_BASE_URL | -（可选） | 加速模型 API 地址 |
LLM_BOOST_MODEL_NAME | -（可选） | OASIS 模拟用加速模型名 |
6.3 算力瓶颈分析
| 瓶颈 | 原因 | 影响 |
|---|
| 🔴 LLM API 延迟 |
每轮模拟每个 Agent 做一次 LLM 推理决策 |
10个Agent × 72轮 = 720次LLM调用；40轮需数小时 |
| 🔴 API 并发限制 |
OASIS 内部串行或有限并行 |
模拟速度受限于 LLM 服务商的速率限制 |
| 🟡 Token 成本 |
每个 Agent 的 prompt 包含历史记忆+人设+上下文 |
long-context 模型成本高；官方建议<40轮测试 |
| 🟢 本地服务器 |
仅负责编排逻辑+文件系统 IPC |
CPU/内存需求低，1核2GB即可运行 |
| 🟢 GPU |
完全不需要 |
无需 GPU 服务器，节省计算成本 |
6.4 加速架构
LLM_BOOST 机制：用户可配置一个加速模型（更小/更快/更便宜）专用于 OASIS 模拟中的 Agent 决策步骤，而本体/人设/报告等关键环节使用主模型。这种分层策略可显著降低成本和延迟：
- 主模型（LLM_*）：本体设计 + 人设生成 + 报告生成 — 需要高推理质量
- 加速模型（LLM_BOOST_*）：OASIS Agent 行为决策 — 需要快速响应，质量可适度降低
6.5 本机算力评估
| 资源 | 需求 | 备注 |
|---|
| CPU | ≥2 核 | 并行 Profile 生成用到 3 线程 |
| RAM（Flask） | ~500MB - 1GB | 取决于图谱数据量 |
| RAM（OASIS） | ~500MB - 2GB | OASIS 子进程内存 |
| 磁盘 | ≥10GB | 模拟日志 + 报告数据 |
| GPU | ❌ 不需要 | 所有推理走 API |
| 网络 | 需稳定连接 Zep Cloud + LLM API | 不能离线运行 |
7. 遥测和泄露分析
7.1 遥测/埋点扫描结果
未发现任何遥测 SDK 或数据采集代码：
| 扫描项 | 结果 | 说明 |
|---|
| sentry-sdk / posthog / amplitude | ❌ 未依赖 | 后端 pyproject.toml 和 uv.lock 中无记录 |
| 前端埋点（GA/gtag/umami/clarity/fullstory） | ❌ 未使用 | frontend/src/ 中无相关代码 |
| 前端依赖中的 sentry | ⚠️ 仅在 package-lock.json 中作为间接依赖 | 极可能是 d3.js 或其他可视化库的传递依赖，未在代码中 import |
| 自建遥测/事件上报 | ❌ 无 | 所有 HTTP 出站只到 Zep Cloud 和 LLM API，无其他第三方域名 |
7.2 通信链路分析
[用户浏览器]
↓ axios ←→ [Flask API :5001]
↓
┌────────┴────────┐
↓ ↓
[Zep Cloud API] [LLM API]
↑ ↑
知识图谱/长期记忆 Agent 行为推理
进程内通信：
[Flask 主进程]
↓ subprocess + 文件系统 IPC (ipc_commands/ + ipc_responses/)
[OASIS 模拟子进程]
↓ actions.jsonl (日志)
[Flask 主进程] ← 监控线程轮询
7.3 数据流向 — 上传内容去向
| 用户数据 | 流向 | 存储位置 | 隐私风险 |
|---|
| 上传文档（PDF/TXT/MD） |
本地文件系统 → Zep Cloud → 图谱节点 |
本地 uploads/ + Zep Cloud 服务器（美国/新加坡） |
⚠️ 文档内容经 Zep AI 处理并存储在 Zep |
| 模拟需求描述 |
→ LLM API（OpenAI/阿里百炼/Qwen） |
LLM 服务商服务器（符合各服务商数据策略） |
⚠️ 用户文本经第三方 LLM 处理 |
| Agent 人设和活动 |
→ Zep Cloud（实时图谱更新） |
Zep Cloud 服务器 |
⚠️ 模拟行为数据外传 |
| 日志文件 |
本地文件系统 |
logs/ + uploads/simulations/ |
✅ 本地存储，不外传 |
7.4 日志系统分析
| 日志类别 | 存储 | 格式 | 内容 |
|---|
| 应用日志 | logs/YYYY-MM-DD.log | 详细文本（带行号） | 函数调用、API响应、错误堆栈 |
| 模拟日志 | uploads/simulations/{id}/simulation.log | 文本 | OASIS 子进程 stdout/stderr |
| 动作日志 | uploads/simulations/{id}/{platform}/actions.jsonl | JSON Lines | 每个 Agent 的每条动作（发帖/点赞等） |
| 报告日志 | uploads/reports/{id}/agent_log.jsonl | JSON Lines（完整内容） | ReportAgent 每一步推理和工具调用 |
日志轮转：10MB 文件大小上限，保留最近5个备份（RotatingFileHandler）。
7.5 安全风险评估
| 风险项 | 描述 | 严重度 | 建议 |
|---|
| API Key 泄露 |
LLM_API_KEY / ZEP_API_KEY 通过环境变量传递，会被子进程继承（os.environ继承） |
🔴 高 |
OASIS 子进程通过 os.environ["OPENAI_API_KEY"] 传递 API key，子进程日志中不会输出 key 本身（仅在内存中），但任何代码注入或 core dump 都可能泄露 |
| Flask SECRET_KEY 硬编码 |
默认值 'mirofish-secret-key'，未设置时使用 |
🟡 中 |
生产部署务必在 .env 中设置 SECRET_KEY |
| Flask Debug 默认开启 |
FLASK_DEBUG 缺省为 True |
🟡 中 |
Debug 模式暴露 Werkzeug debugger，可远程执行代码。生产应关闭 |
| 无认证/鉴权 |
API 接口无用户认证、无请求签名 |
🟡 中 |
Docker 部署暴露 5001 端口，任何人都可调用 API。建议加反向代理 + 认证 |
| IPC 无加密 |
通过文件系统 JSON 文件通信，明文读写 |
🟢 低 |
IPC 仅在本地进程间，非网络通信。但本地文件权限需控制 |
| 上传文件无沙箱 |
支持 PDF/TXT/MD 上传，无内容沙箱 |
🟢 低 |
上传文件被解析为文本后通过 LLM 处理，恶意 PDF 可能触发 XML 注入？（PyMuPDF 解析有历史 CVE） |
| 无限速控制 |
API 无 rate limiting |
🟡 中 |
恶意调用可耗尽 LLM API 配额 |
| 图谱数据在 Zep Cloud |
用户文档全部内容上传至 Zep Cloud 处理 |
⚠️ 需评估 |
Zep 的隐私策略和数据存储位置需确认。敏感数据需注意 |
7.6 第三方服务依赖
| 服务 | 用途 | 数据交互 | 替代方案 |
|---|
Zep Cloud (app.getzep.com) |
知识图谱+长期记忆+语义搜索 |
全文内容 + 图谱结构 + Agent 行为 |
❌ 无本地替代，当前是硬依赖 |
| LLM API（如 OpenAI / 阿里百炼） |
所有 AI 推理 |
文档文本 + 提示词 + Agent 决策 |
✅ 可切换任意 OpenAI SDK 兼容 API |
| GitHub Container Registry |
Docker 镜像分发 |
无用户数据 |
✅ 可迁移到其他 registry |
7.7 结论
技术上无恶意遥测：源码审计未发现主动的数据采集、用户行为追踪或数据外泄代码。但存在架构性隐私风险：所有用户上传内容需经过 Zep Cloud 和 LLM API 处理，数据离开用户控制范围。对于敏感信息的预测分析，需确认 Zep 和 LLM 提供商的隐私协议是否允许。
8. 部署要点
| 组件 | 方式 | 端口 |
|---|
| 前端 (Vue 3) | npm run dev 或 Docker | 3000 |
| 后端 (Flask) | npm run backend 或 Docker | 5001 |
| 环境变量 | .env 文件 | LLM_API_KEY + ZEP_API_KEY |
| Python管理 | uv (比 pip 更快) | Python 3.11-3.12 |
核心依赖版本约束
- Python ≥3.11, ≤3.12（3.13+ 有兼容性问题）
- camel-oasis==0.2.5
- camel-ai==0.2.78
- zep-cloud==3.13.0
9. 关键设计决策总结
| 决策 | 选择 | 理由 |
|---|
| 图谱后端 |
Zep Cloud（非本地 Neo4j） |
内置 GraphRAG + 时间维度语义 + 托管服务免运维 |
| 模拟引擎 |
OASIS by CAMEL-AI |
成熟的社交模拟开源引擎，双平台支持 |
| LLM API |
OpenAI SDK 兼容（推荐 Qwen-Plus） |
统一接口，可切换任意模型 |
| 人设生成 |
LLM 驱动（非规则引擎） |
更丰富、更真实、更贴合上下文 |
| 配置生成 |
LLM 分步生成（非人工配置） |
全程自动化，降低使用门槛 |
| 报告生成 |
ReACT 模式 + 检索工具 |
自主规划+多轮推理，比直接生成更深入 |
| 部署架构 |
单容器（前端+后端合一） |
配置简单，小规模够用；镜像托管 GHCR |
| LLM 加速 |
可选加速模型（LLM_BOOST） |
OASIS 用低成本快速模型，关键环节用主模型 |