Files
Obsidian/MyArticles/MiroFish 仓库详细介绍.md
coco 8b94d76799 a
2026-07-21 13:57:15 +08:00

8.4 KiB
Raw Permalink Blame History

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 开发,核心交互流程:

  1. Step 1:本体生成 → 上传文档+模拟需求,调用 /api/graph/ontology/generate 生成本体;

  2. Step 2:图谱构建 → 调用 /api/graph/build 构建 GraphRAG 图谱,实时展示进度(0-100%);

  3. 模拟配置 → 选择平台(Twitter/Reddit)、设置模拟参数(时长、Agent 数量);

  4. 模拟运行 → 启动模拟,实时监控状态,模拟完成后生成报告;

  5. Agent 采访 → 报告完成后解锁 Interview 功能,动态交互获取 Agent 观点;

  6. 报告查看 → 查询报告状态,导出/查看模拟结果。

四、技术亮点

  1. 多平台适配:基于 OASIS 框架实现 Twitter/Reddit 差异化模拟,适配不同平台的 Agent 行为特征;

  2. GraphRAG 融合:本体生成+图谱构建,强化模拟的知识驱动能力;

  3. 可靠的重试机制:API 调用失败时自动重试,支持退避策略,提升稳定性;

  4. 动态管控能力:IPC 命令交互支持模拟运行中动态采访,而非仅静态输出;

  5. 全栈交互:前端进度可视化、后端状态管理、模拟层可配置化,形成完整闭环。

五、适用场景

  • 社会舆论研究:模拟特定事件在社交平台的传播路径、Agent 观点演化;

  • 智能体仿真:验证不同人格/属性的 Agent 在舆论场中的行为模式;

  • GraphRAG 落地:结合本体生成的图谱增强检索,提升模拟的知识准确性。

六、部署与运行

  1. 后端依赖:需安装 OASIS 框架、Zep Cloud 客户端、SQLite(模拟数据库)、异步依赖(asyncio)等;

  2. 前端依赖:通过 npm install 安装前端包(package-lock.json 已锁定版本);

  3. 模拟启动:

    1. Twitter 模拟:执行 backend/scripts/run_twitter_simulation.py;

    2. Reddit 模拟:执行 backend/scripts/run_reddit_simulation.py;

  4. Web 服务:启动后端 Web 服务(如 FastAPI),前端访问对应端口即可交互。

七、开源许可证

项目 LICENSE 文件包含 GPL 类开源协议条款,核心强调:

  • 允许自由使用、修改、分发;

  • 衍生作品需保持开源;

  • 需保留原始版权声明,且不承担使用风险。

综上,MiroFish 是一个功能完整、架构清晰的社会舆论模拟平台,结合了知识图谱、智能体仿真、全栈交互等技术,适用于舆论研究、智能体仿真等领域的开发者和研究者。