一天一个开源项目（第78篇）：MiroFish - 用群体智能引擎预测未来

引言

“不预测个体，而是仿真群体。”

这是"一天一个开源项目"系列的第78篇。今天的项目是MiroFish（GitHub）。

传统预测工具的逻辑是：收集数据 → 跑模型 → 输出数字。但这有一个根本局限：模型是静态的，而现实世界是动态博弈的结果。舆论风向、市场情绪、政策响应，这些都是无数个体相互作用后涌现出来的集体现象——你很难用线性回归去拟合一场舆论风暴。

MiroFish换了一种思路：不拟合，而是重演。通过多智能体仿真，让数千个虚拟的"人"在一个模拟平台里互动，用群体行为的演化来预测真实世界的走向。这不是预测数字，而是预测故事。

56k+ Stars，8.6k+ Forks——在多智能体仿真赛道上的现象级项目。作者是北京邮电大学学生白富（666ghj），同时也是 BettaFish（40.5k Stars）的作者，两个项目构成一套完整的"数据采集 → 仿真预测"流水线。

你将学到什么

• MiroFish 的核心哲学：为什么群体仿真比统计预测更接近真相
• 五阶段仿真流水线：从知识图谱构建到深度交互报告
• GraphRAG 在仿真中的角色：给智能体注入领域知识
• Zep Cloud 跨会话记忆：让智能体"记得"自己的历史
• "上帝模式"变量注入：运行时 what-if 分析

前置知识

• 了解多智能体系统（MAS）的基本概念
• Python 基础（可选，用于理解配置逻辑）
• 对舆情分析或趋势预测有一定兴趣

项目背景

它是什么？

MiroFish是一个群体智能预测引擎，通过构建包含数千个 AI 智能体的虚拟社会，仿真真实群体对某个话题的演化过程，从而生成趋势预测报告。

项目名称来自Miro——灵感来源于人类集体智慧的涌现现象，就像一群鱼（Fish）可以形成远超个体能力的群体行为。

它解决的核心问题是：

传统方法： 历史数据 → 统计模型 → "下个月销量是 X" 问题：无法解释为什么，无法应对突发事件 MiroFish 方法： 种子知识 + 多智能体仿真 → 群体行为演化 → "在这些条件下，群体会这样反应" 优势：可解释、可干预、可做 what-if 分析

关于作者

• GitHub: 666ghj
• 背景: 北京邮电大学学生，盛大集团支持
• 另一项目: BettaFish（40.5k ⭐）——从 30+ 平台采集情感数据，是 MiroFish 的数据供给端
• 定位: 两个项目构成完整闭环：BettaFish 采集 → MiroFish 仿真预测

项目数据

• ⭐GitHub Stars: 56,400+
• 🍴Forks: 8,600+
• 📝最新版本: v0.1.2
• 📄协议: AGPL-3.0（Copyleft，SaaS 部署需开源）
• 🌐语言构成: Python 57.6% + Vue.js 41.2%
• 🤝核心依赖: CAMEL-AI OASIS、camel-ai 0.2.78、Zep Cloud 3.13.0、GraphRAG、PyMuPDF

主要功能

核心：五阶段仿真流水线

MiroFish 的仿真过程分为五个严格顺序的阶段：

阶段 1：图谱构建（Graph Building） 种子文档（PDF/URL）→ PyMuPDF 提取 → GraphRAG 构建知识图谱 输出：领域知识图谱（实体 + 关系） 阶段 2：环境准备（Environment Setup） CAMEL-AI OASIS 初始化虚拟平台 为每个智能体分配 Zep Cloud 长期记忆 注入知识图谱上下文 阶段 3：并行仿真（Parallel Simulation） 双平台同时运行（提高置信度） 数千个智能体互动 N 轮 智能体行为由 LLM 驱动 + 个性档案约束 阶段 4：报告生成（Report Generation） 聚合仿真轨迹 LLM 总结群体行为模式 生成结构化趋势报告 阶段 5：深度交互（Deep Interaction） 用户可向报告提问 支持"上帝模式"变量注入（运行时 what-if） RAG 检索仿真记录回答问题

GraphRAG：给仿真注入领域知识

MiroFish 使用 GraphRAG 而非普通 RAG，原因很直观：

# 普通 RAG：文档 → 向量 → 检索相似段落# 问题：只能回答"有哪些事实"，无法推理关系# GraphRAG：文档 → 实体抽取 → 关系图谱 → 图遍历# 优势：可以推理"A 影响 B，B 又会如何影响 C"

在仿真中，智能体需要理解复杂的因果关系（如"政策 X 会影响群体 Y 的行为"），GraphRAG 的图结构比向量检索更擅长这类推理。

Zep Cloud：让智能体拥有记忆

每个智能体都分配了独立的 Zep Cloud 记忆空间：

# 每个智能体拥有持久化记忆agent_memory=ZepMemory(session_id=f"agent_{agent_id}",zep_client=zep_client)# 仿真轮次之间，智能体可以"记住"之前的交互# 这使得智能体行为更连贯、更符合真实人类认知模式

这解决了多智能体仿真中的一个经典问题：如果每轮仿真智能体都"失忆"，行为就会缺乏连贯性，预测结果可信度下降。

"上帝模式"变量注入

这是 MiroFish 最有趣的功能之一——在仿真运行时注入外部变量：

# 例：分析"如果竞争对手突然降价 20%"会怎样god_mode_injection={"event":"competitor_price_cut","magnitude":-0.20,"timing":"round_15","affected_agents":"all_consumer_agents"}# 注入后，仿真会实时响应这个"外部冲击"# 输出：群体情绪变化 + 行为演化轨迹

这让 MiroFish 不仅能预测"会发生什么"，还能回答"如果我这样做，会发生什么"。

双平台并行仿真

MiroFish 同时在两个独立的虚拟平台上运行相同的仿真：

平台 A ─── 仿真结果 A ──┐ ├── 置信度评估 + 综合报告 平台 B ─── 仿真结果 B ──┘

两个平台的结果高度一致 → 高置信度结论
两个平台结果发散 → 标记为"不确定区间"，提示用户审慎解读

BettaFish + MiroFish 完整流水线

[BettaFish] [MiroFish] 微博/推特/Reddit/... → 种子数据 → 知识图谱 情感数据采集 → 智能体初始化 30+ 平台 → 仿真 → 报告 → 预测

两个项目合用，构成从"现实数据收集"到"未来趋势预测"的完整链路。

快速开始

环境要求：Python 3.10+、Node.js 16+、Docker（推荐）

# 克隆项目gitclone https://github.com/666ghj/MiroFish.gitcdMiroFish# 配置环境变量cp.env.example .env# 编辑 .env，填写以下必要配置：# - OPENAI_API_KEY（或兼容 API）# - ZEP_API_KEY（Zep Cloud 账号）# - GRAPHRAG_API_KEY# 方式一：Docker 一键启动（推荐）docker-composeup-d# 方式二：手动启动pipinstall-rrequirements.txtcdfrontend&&npminstall&&npmrun build&&cd..python app.py

访问http://localhost:5000进入 Web 界面。

第一次仿真：

1. 上传种子文档（PDF 或输入 URL） 2. 设置仿真参数（智能体数量、仿真轮次、话题） 3. 点击"开始仿真" 4. 等待约 10-30 分钟（取决于智能体数量和 API 速度） 5. 查看生成的趋势报告，支持自然语言追问

项目详细剖析

整体架构

┌─────────────────────────────────────────────────┐ │ 前端层 (Vue.js) │ │ 仿真配置 / 进度监控 / 报告展示 / 深度交互 │ └─────────────────────┬───────────────────────────┘ │ REST API ┌─────────────────────▼───────────────────────────┐ │ 后端层 (Flask + Python) │ │ 五阶段流水线编排 / 上帝模式控制器 │ └──────┬──────────────┬──────────────┬────────────┘ │ │ │ ┌──────▼──────┐ ┌─────▼──────┐ ┌───▼────────────┐ │ 知识层 │ │ 仿真层 │ │ 记忆层 │ │ GraphRAG │ │ CAMEL-AI │ │ Zep Cloud │ │ 知识图谱 │ │ OASIS 框架 │ │ 智能体记忆 │ │ PyMuPDF │ │ 双平台并行 │ │ 跨轮次持久化 │ └─────────────┘ └────────────┘ └────────────────┘

CAMEL-AI OASIS：仿真核心

CAMEL-AI OASIS 是 MiroFish 的仿真引擎，专为社会仿真设计：

fromoasisimportEnvironment,Agent,Platform# 初始化虚拟平台platform=Platform(name="simulated_weibo",max_agents=5000,interaction_rules=InteractionConfig(max_posts_per_round=10,follow_probability=0.3))# 创建具有不同个性的智能体agents=[Agent(id=i,persona=PersonaProfile(age=random.randint(18,65),occupation=random.choice(occupations),political_lean=random.gauss(0,1),activity_level=random.uniform(0.1,1.0)),memory=ZepMemory(session_id=f"agent_{i}"),knowledge_context=graphrag_context)foriinrange(5000)]# 启动仿真env=Environment(platform=platform,agents=agents)results=env.run(rounds=50,topic="新能源汽车补贴政策")

GraphRAG 知识图谱构建

fromgraphragimportGraphRAGPipeline# 从种子文档构建知识图谱pipeline=GraphRAGPipeline(input_dir="./seed_documents",output_dir="./knowledge_graph")# 提取实体和关系pipeline.run()# 输出示例：# 实体：[特斯拉, 比亚迪, 补贴政策, 消费者群体, ...]# 关系：[特斯拉 → 竞争 → 比亚迪]# [补贴政策 → 刺激 → 消费者购买意愿]# [消费者购买意愿 → 影响 → 市场份额]# 将知识图谱注入智能体上下文context=pipeline.query("新能源汽车市场的关键影响因素")

报告生成：从轨迹到洞察

defgenerate_report(simulation_results):"""从仿真轨迹生成趋势报告"""# 1. 聚合统计sentiment_evolution=aggregate_sentiment(simulation_results)opinion_clusters=cluster_opinions(simulation_results)key_events=detect_tipping_points(simulation_results)# 2. LLM 总结report_prompt=f""" 基于以下仿真数据，生成趋势分析报告： - 情感演化曲线：{sentiment_evolution}- 观点聚类：{opinion_clusters}- 关键转折点：{key_events}请分析：群体最终态度、关键驱动因素、可能的演化路径 """report=llm.complete(report_prompt)# 3. 双平台一致性检验confidence=calculate_confidence(results_platform_a=simulation_results["platform_a"],results_platform_b=simulation_results["platform_b"])returnReport(content=report,confidence=confidence)

前端技术栈

Vue.js 前端提供完整的可视化界面：

• 仿真进度监控：实时显示各阶段进度和智能体活跃度
• 知识图谱可视化：交互式展示 GraphRAG 构建的实体关系图
• 情感热力图：随仿真轮次变化的群体情感分布
• 报告阅读器：支持高亮、标注、追问的报告交互界面

为什么选择 AGPL-3.0

AGPL-3.0 是比 GPL 更严格的 Copyleft 协议：

MIT/Apache：修改后可以不开源（可以闭源商业化） GPL：本地部署衍生品需开源 AGPL：网络服务（SaaS）衍生品也必须开源 → MiroFish 选择 AGPL，意味着如果你用它搭建云服务， 必须将改动后的代码开源。个人研究和本地使用不受限制。

项目地址与资源

官方资源

• 🌟GitHub: https://github.com/666ghj/MiroFish
• 🐟配套项目: BettaFish（情感数据采集，40.5k ⭐）
• 📄OASIS 框架: https://github.com/camel-ai/oasis
• 🧠Zep Cloud: https://www.getzep.com
• 📊GraphRAG: https://github.com/microsoft/graphrag

关联技术

• CAMEL-AI: https://github.com/camel-ai/camel（多智能体框架基础）
• PyMuPDF: PDF 文档解析库
• Docker: 推荐部署方式

总结与展望

核心要点

1. 群体仿真替代统计拟合：MiroFish 不试图拟合历史数据，而是重演群体互动过程，输出的是行为演化故事而非数字预测
2. GraphRAG 知识增强：图结构知识表示让智能体具备领域因果推理能力，而非简单的事实检索
3. Zep Cloud 跨轮次记忆：解决仿真连贯性问题，使智能体行为符合真实人类认知模式
4. 上帝模式 what-if 分析：运行时变量注入将预测工具变成决策支持工具
5. 双平台置信度机制：用一致性评估代替单一预测，更诚实地呈现不确定性
6. BettaFish + MiroFish 闭环：从现实数据采集到未来趋势预测的完整链路

适合谁使用

• 研究人员：研究舆情演化、社会仿真、计算社会科学的学者
• 产品经理 / 市场分析师：需要预判市场反应、做 what-if 场景分析的决策者
• AI 工程师：研究多智能体仿真架构、GraphRAG 应用、智能体记忆系统的开发者
• 独立研究者：对群体智能涌现现象感兴趣、想用 AI 理解复杂社会系统的探索者

值得思考的问题

MiroFish 代表了 AI 预测的一种新范式：从"模型拟合"到"世界仿真"。当我们用多智能体重演现实世界时，我们实际上是在问一个更深的问题——现实本质上是一场无数智能体相互博弈的涌现结果，而真正理解这个结果，也许需要同样复杂度的仿真。

鱼群游动时没有中心指挥，却能形成壮观的整体图案。人类社会的舆论走向，会不会也是如此？

访问我的个人网站，探索更多实用知识和有趣产品