8.4 KiB
MiroFish 仓库详细介绍
MiroFish 是一个面向社会舆论模拟的全栈项目,核心基于 OASIS 框架实现多平台(Twitter/Reddit)的智能体(Agent)舆论仿真,结合 GraphRAG(图谱增强检索生成)、本体生成、模拟管控等能力,提供从本体构建、图谱生成到多轮模拟、报告输出的完整舆论模拟解决方案。
一、项目整体架构
项目采用前后端分离架构,技术栈覆盖 Python(后端)、Vue.js(前端),核心分为后端服务层、模拟执行层、前端交互层三大模块,整体架构如下:
MiroFish/
├── backend/ # 后端核心代码
│ ├── app/ # Web服务(FastAPI/Flask)、业务服务、数据模型
│ └── scripts/ # 模拟执行脚本(Twitter/Reddit仿真)
├── frontend/ # 前端交互界面
│ ├── src/api/ # 接口封装
│ ├── src/components/ # 页面组件
│ └── package-lock.json # 前端依赖
└── LICENSE # 开源许可证(基于GPL类协议)
二、核心功能模块
1. 本体(Ontology)生成与管理
核心模块:backend/app/services/ontology_generator.py
-
功能:根据输入的文档/模拟需求,自动生成自定义实体/关系类型的 Python 代码(兼容 Zep Cloud 本体规范),支持实体属性定义、关系类型映射、边的源目标配置。
-
关键能力:
-
标准化实体类(继承
EntityModel)和关系类(继承EdgeModel); -
自动生成
ENTITY_TYPES/EDGE_TYPES字典,适配图谱构建; -
支持关系的 source_targets 映射配置。
-
2. GraphRAG 图谱构建
核心模块:
-
前端接口:
frontend/src/api/graph.js -
后端逻辑:
backend/app/services/graph_builder_service.py(关联代码片段) -
功能:基于生成的本体,构建面向舆论模拟的知识图谱,支持:
-
上传文档+模拟需求,生成本体;
-
按项目维度构建图谱,实时查询构建进度;
-
图谱数据查询、项目信息获取。
-
-
交互流程:前端通过
/api/graph/ontology/generate生成本体 →/api/graph/build构建图谱 →/api/graph/task/{taskId}查询构建状态。
3. 多平台舆论模拟(核心能力)
(1)模拟载体:Twitter/Reddit 双平台
核心脚本:
-
backend/scripts/run_twitter_simulation.py:Twitter 平台模拟 -
backend/scripts/run_reddit_simulation.py:Reddit 平台模拟 -
核心逻辑:
-
加载模拟配置(总时长、每轮分钟数、Agent 配置);
-
初始化 LLM 模型、Agent 图谱、OASIS 仿真环境;
-
执行多轮模拟循环(按时间切片激活不同 Agent);
-
支持初始事件(如初始帖子发布)、Agent 行为决策(基于 LLM);
-
模拟完成后生成数据库记录,支持后续 Interview 交互。
-
(2)Agent 配置与 Profile 管理
核心模块:backend/app/services/oasis_profile_generator.py
-
定义
OasisAgentProfile数据结构,支持:-
通用字段(user_id、persona、bio 等);
-
平台专属字段(Reddit 的 karma、Twitter 的 follower_count 等);
-
多格式转换(Reddit/Twitter/通用字典);
-
关联实体信息(source_entity_uuid/type)。
-
(3)模拟管控:IPC 命令交互
核心模块:
-
backend/scripts/run_reddit_simulation.py(IPCHandler 类) -
backend/app/services/simulation_ipc.py(IPC 数据结构) -
功能:模拟运行中支持动态命令交互,如:
-
INTERVIEW:单 Agent 采访(获取特定 Agent 舆论观点); -
BATCH_INTERVIEW:批量 Agent 采访; -
CLOSE_ENV:关闭模拟环境;
-
-
命令/响应通过文件系统交互(JSON 格式),保证跨进程通信可靠性。
4. 模拟报告与状态管理
(1)报告状态接口
核心模块:
-
后端:
backend/app/api/report.py -
前端:
frontend/src/api/report.js -
功能:
-
检查模拟报告状态(
/api/report/check/{simulation_id}); -
判断是否解锁 Interview 功能(仅报告完成后解锁);
-
返回报告 ID、状态(completed/failed)等关键信息。
-
(2)任务进度管理
核心模块:backend/app/models/task.py
-
定义
Task数据类,统一管理任务状态:-
基础字段(task_id、type、status、created_at/updated_at);
-
进度字段(progress 百分比、progress_detail 详细进度);
-
结果/错误字段(result、error);
-
支持字典序列化(to_dict),适配前端展示。
-
5. 通用工具能力
(1)重试机制
核心模块:backend/app/utils/retry.py
-
实现
call_with_retry函数,支持:-
可配置重试次数、初始延迟、退避因子;
-
指定需要重试的异常类型;
-
随机化延迟时间,避免并发重试冲突;
-
完整的日志记录(失败原因、重试间隔)。
-
(2)文本预处理
核心模块:backend/app/services/text_processor.py
-
标准化文本格式:
-
统一换行符(\r\n → \n);
-
移除连续空行(保留最多2个换行);
-
行首行尾空白清理。
-
(3)项目文件管理
核心模块:backend/app/models/project.py
- 提供
get_project_files方法,按项目 ID 读取文件列表,支持项目维度的文件管理。
三、前端交互核心流程
前端基于 Vue.js 开发,核心交互流程:
-
Step 1:本体生成 → 上传文档+模拟需求,调用
/api/graph/ontology/generate生成本体; -
Step 2:图谱构建 → 调用
/api/graph/build构建 GraphRAG 图谱,实时展示进度(0-100%); -
模拟配置 → 选择平台(Twitter/Reddit)、设置模拟参数(时长、Agent 数量);
-
模拟运行 → 启动模拟,实时监控状态,模拟完成后生成报告;
-
Agent 采访 → 报告完成后解锁 Interview 功能,动态交互获取 Agent 观点;
-
报告查看 → 查询报告状态,导出/查看模拟结果。
四、技术亮点
-
多平台适配:基于 OASIS 框架实现 Twitter/Reddit 差异化模拟,适配不同平台的 Agent 行为特征;
-
GraphRAG 融合:本体生成+图谱构建,强化模拟的知识驱动能力;
-
可靠的重试机制:API 调用失败时自动重试,支持退避策略,提升稳定性;
-
动态管控能力:IPC 命令交互支持模拟运行中动态采访,而非仅静态输出;
-
全栈交互:前端进度可视化、后端状态管理、模拟层可配置化,形成完整闭环。
五、适用场景
-
社会舆论研究:模拟特定事件在社交平台的传播路径、Agent 观点演化;
-
智能体仿真:验证不同人格/属性的 Agent 在舆论场中的行为模式;
-
GraphRAG 落地:结合本体生成的图谱增强检索,提升模拟的知识准确性。
六、部署与运行
-
后端依赖:需安装 OASIS 框架、Zep Cloud 客户端、SQLite(模拟数据库)、异步依赖(asyncio)等;
-
前端依赖:通过
npm install安装前端包(package-lock.json 已锁定版本); -
模拟启动:
-
Twitter 模拟:执行
backend/scripts/run_twitter_simulation.py; -
Reddit 模拟:执行
backend/scripts/run_reddit_simulation.py;
-
-
Web 服务:启动后端 Web 服务(如 FastAPI),前端访问对应端口即可交互。
七、开源许可证
项目 LICENSE 文件包含 GPL 类开源协议条款,核心强调:
-
允许自由使用、修改、分发;
-
衍生作品需保持开源;
-
需保留原始版权声明,且不承担使用风险。
综上,MiroFish 是一个功能完整、架构清晰的社会舆论模拟平台,结合了知识图谱、智能体仿真、全栈交互等技术,适用于舆论研究、智能体仿真等领域的开发者和研究者。