250 lines
8.4 KiB
Markdown
250 lines
8.4 KiB
Markdown
# MiroFish 仓库详细介绍
|
||
|
||
MiroFish 是一个面向**社会舆论模拟**的全栈项目,核心基于 OASIS 框架实现多平台(Twitter/Reddit)的智能体(Agent)舆论仿真,结合 GraphRAG(图谱增强检索生成)、本体生成、模拟管控等能力,提供从本体构建、图谱生成到多轮模拟、报告输出的完整舆论模拟解决方案。
|
||
|
||
## 一、项目整体架构
|
||
|
||
项目采用前后端分离架构,技术栈覆盖 Python(后端)、Vue.js(前端),核心分为**后端服务层**、**模拟执行层**、**前端交互层**三大模块,整体架构如下:
|
||
|
||
```Plain
|
||
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 是一个功能完整、架构清晰的社会舆论模拟平台,结合了知识图谱、智能体仿真、全栈交互等技术,适用于舆论研究、智能体仿真等领域的开发者和研究者。 |