MiroFish 群体智能预测引擎部署实战：10 分钟跑出第一次推演
【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish
本文以 MiroFish 群体智能预测引擎的部署为主线，覆盖环境检查、.env 密钥配置、依赖一键安装、前后端启动与首次种子材料提交的完整操作。MiroFish 把一份文档当作种子，生成由大量具备独立人格的 Agent 构成的平行数字世界，经交互演化后产出预测报告与可对话的数字世界。按文中的"分钟"里程碑推进，约 10 分钟即可看到第一次完整推演跑起来。
⏱ 第 0 分钟 | MiroFish 本地运行环境检查
先确认运行环境齐备。后端是 Flask + Python，前端是 Vite 工程，整个安装链路由 npm scripts 串联：
node -v # 需要 18 及以上 python --version # 需要 3.11 到 3.12 之间 uv --version # Python 包管理器，建议最新版| 工具 | 版本要求 | 作用 |
|---|---|---|
| Node.js | ≥ 18 | 运行前端并驱动依赖安装 |
| Python | 3.11 – 3.12 | 运行后端服务 |
| uv | 最新版 | 管理 Python 虚拟环境与依赖 |
三条命令都应能返回版本号。不需要数据库和中间件，MiroFish 本地不依赖任何外部存储，记忆图谱能力由 Zep Cloud 服务承担。
⏱ 第 5 分钟 | .env 密钥配置与依赖安装步骤
克隆仓库并复制配置模板：
git clone https://gitcode.com/GitHub_Trending/mi/MiroFish cd MiroFish cp .env.example .env.env存放 API 密钥，仓库默认忽略该文件，不要把它提交进任何版本库。关键变量：
| 变量 | 必填 | 说明 |
|---|---|---|
LLM_API_KEY | 是 | LLM 服务密钥 |
LLM_BASE_URL | 是 | 兼容 OpenAI SDK 格式的任意地址 |
LLM_MODEL_NAME | 是 | 模型名，如 qwen-plus |
ZEP_API_KEY | 是 | Zep Cloud 密钥，每月免费额度支撑简单使用 |
LLM_BOOST_* | 否 | 加速通道，不用则从 .env 中整段移除 |
随后一次性安装全部依赖。该命令依次执行根目录 npm install、前端 npm install 与后端 uv sync，首次耗时数分钟，取决于网络：
npm run setup:all⏱ 第 10 分钟 | 前后端启动与健康检查验证
npm run dev命令拉起后，前端监听http://localhost:3000，后端 API 在http://localhost:5001。确认链路存活，敲一次健康检查：
curl http://localhost:5001/health返回包含"status": "ok"的 JSON 即表示后端就绪。单独重启某一端时，用npm run backend与npm run frontend分别启动。
打开前端地址即可看到种子材料上传区，部署核心链路至此打通。
Docker 替代启动方式
本机缺 Node 与 Python 环境时，Docker 可跳过整个安装阶段：
cp .env.example .env # 先填好密钥 docker compose up -d镜像读取根目录.env，映射 3000 与 5001 两个端口，访问地址与源码部署一致。两种方式的差异集中在四个维度：
| 对比维度 | 源码部署 | Docker 部署 |
|---|---|---|
| 代码改动反馈 | 前端热更新，后端重启生效 | 需重建或重拉镜像 |
| 上传数据持久化 | 直接写入 backend/uploads | 通过 volume 映射到本地 ./backend/uploads |
| 网络带宽要求 | npm 与 uv 两侧分别拉包 | 拉取单一镜像，首次约数分钟 |
| 服务恢复方式 | 手动重启 | restart: unless-stopped自动恢复 |
⏱ 第 15 分钟 | 提交首次种子材料与模拟全流程
上传任意种子材料——舆情报告、政策草案、小说文本均可（支持 pdf、md、txt、markdown，单文件 50 MB 以内），再用一句自然语言描述预测需求，提交。系统随后按四个阶段自动推进：
模拟流程的四个阶段
- 图谱构建：从种子材料抽取实体与关系，注入 Zep 记忆图谱；
- 环境搭建：生成 Agent 人设与模拟参数（轮数、活跃度、时间跨度）；
- 双平台模拟：Twitter 与 Reddit 风格平台并行运行，Agent 逐轮交互并更新时序记忆；
- 报告生成：Report Agent 用工具集检索模拟后的环境，输出预测报告。
调整模拟轮数与控制成本
轮数直接决定推演深度与 LLM 消耗。模拟接口接受max_rounds参数用于截断轮数，后端另有OASIS_DEFAULT_MAX_ROUNDS变量控制上限。首轮建议控制在 40 轮以内验证流程，确认结果方向正确后再放大。
报告产出后进入"深度互动"环节：可与 Report Agent 对话，也可直接盘问世界中任意一个 Agent 的行为细节。文件进、报告出，外加一个可对话的平行世界，完整闭环到此形成。
图谱构建、模拟运行、报告生成的核心逻辑集中在 backend/app/services/，调整任何提示词或参数后重启服务即可生效。
故障排除：三个高频卡点与处理
- 现象：
npm run dev报端口已被占用 →根因：3000 或 5001 被其他进程占用 →处理：lsof -i :3000定位并结束进程，或修改端口映射。 - 现象：后端启动即列出"配置错误"与缺失变量 →根因：
.env中LLM_API_KEY或ZEP_API_KEY仍是占位符 →处理：填入真实密钥，保存后重启服务。 - 现象：
setup:all长时间卡在下载 →根因：拉取依赖的网络缓慢 →处理：直接重跑一次，通常可续传；仍无进展则检查网络或代理配置。
MiroFish 部署验证清单
逐条核对，确认各链路已跑通：
node -v、python --version、uv --version均返回满足要求的版本.env中四个必填变量已填真实值，无占位符残留npm run dev同时拉起前后端，终端无报错curl http://localhost:5001/health返回包含 status: ok 的 JSON- 浏览器提交了一份种子材料，流程已推进到模拟或报告阶段
【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
