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

250 lines
8.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 是一个功能完整、架构清晰的社会舆论模拟平台,结合了知识图谱、智能体仿真、全栈交互等技术,适用于舆论研究、智能体仿真等领域的开发者和研究者。