企业官网建设流程全解析

5分钟跑通MiroFish：从克隆仓库到生成第一份预测报告

【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish

手里有一份报告，想看看舆论接下来会怎么发酵？把文件丢给 MiroFish 部署后的界面，用大白话写清预测需求，它会在一个平行的数字世界里跑出成千上万个智能体替你"预演"，最后吐出一份可读的预测报告。这篇教程只做一件事：带你在自己电脑上把 MiroFish 跑起来，再顺手告诉你想深入改造时该从哪儿下手。

跑起来之前的两件事：两个 API Key 和环境要求

MiroFish 的智能体大脑依赖 LLM，长期记忆则托管在 Zep Cloud，所以启动前必须先备好两把钥匙：

# 1. 克隆代码 git clone https://gitcode.com/GitHub_Trending/mi/MiroFish cd MiroFish # 2. 生成 .env 并填入两把 Key cp .env.example .env

打开.env，重点填LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_NAME（README 默认给的是阿里百炼的 qwen-plus 示例）和ZEP_API_KEY，不打算用加速通道就把LLM_BOOST_*那几行留空或删掉。💡 本机源码方式需要 Node 18+、Python 3.11~3.12 和 uv（uv --version确认）；Docker 方式只需装好 Docker Compose v2，镜像里已经把环境打好了。

本机部署 MiroFish：四步从克隆到启动

适合想边跑边看代码、随时打断点的人。

第一步：一键装全量依赖

npm run setup:all

这条命令会顺序装好根目录、前端和后端（后端用uv sync自动建虚拟环境），不用手动venv、不用分别pip install。

第二步：同时拉起前后端

npm run dev

concurrently会把两个进程挂在同一终端，前端跑在 3000、后端在 5001，/api请求由 frontend/vite.config.js 里的代理转发到后端。只跑单侧可以用npm run backend或npm run frontend。

第三步：浏览器验证

打开http://localhost:3000，首页出现"上传任意报告，即刻推演未来"的入口、右侧有文件拖拽区，就说明前后端都通了；5001 端口能直接返回响应，说明后端 Flask 也活着。

第四步：上传种子，走完五步工作流

传一份 PDF 或长文本，描述你想预测什么，系统会按「图谱构建 → 环境搭建 → 开始模拟 → 报告生成 → 深度互动」推进，全程可在页面看进度。第一次跑建议把轮数压到 40 以下，省 token 也更稳。

Docker 一键拉起 MiroFish：最省事的体验方式

只想看效果、不想装一堆工具链的话，走容器路线最快：

cp .env.example .env docker compose up -d

compose 文件已经把3000:3000、5001:5001端口映射好，也把backend/uploads挂到容器里做持久化，重启不丢上传材料。拉取ghcr.io镜像慢的话，docker-compose.yml里留了注释掉的加速地址，替换后再up -d一次即可。

# 看状态和日志 docker compose ps docker compose logs -f mirofish

到这里就算搭好了，浏览器照样访问 3000。

MiroFish 部署后自检：界面、流程、图谱三查

三条检查点，任一异常先回头查.env。

首页能打开，上传区可交互

首页能看到文件拖拽框、下方有"预测需求"输入框，说明前端资源与静态路由都正常。

五步工作流能走完

上传后依次经过图谱构建、环境搭建、开始模拟、报告生成、深度互动五步，每一步都有明确状态标签。若卡在"图谱构建"，九成是 Zep key 没生效或 LLM 调不通，看后端日志即可定位。

图谱能渲染、节点可点开

进到图谱页，能看到大量节点与红色关系线、右侧弹出 Node Details 面板显示实体属性与摘要——这就是智能体交互后沉淀下来的记忆结构，是判断链路是否真正跑通最直观的信号。

MiroFish 二次开发：改代码前先看这三个目录

改完npm run dev下即时生效，不用重启容器。要提 PR 的话：从 main 拉feature/xxx分支 → 改代码 → 跑一遍backend/tests/下已有的 pytest 用例 → 推送后到代码托管平台发起 PR。⚠️ 本地.env千万别提交，.gitignore里已经列了，但改分支合并前再核对一次。

MiroFish 部署常见卡点：端口、镜像与 API 额度

端口被占

3000 或 5001 冲突时，sudo lsof -i :3000找出占用进程，kill掉；或者改docker-compose.yml左侧主机端口（3001:3000）再重启。

拉镜像慢或失败

ghcr.io网络不稳时切换到 compose 文件里注释好的加速地址，或docker pull单拉一次缓存后再up -d。

LLM / Zep 报错

401、403一律先看.env里 key 有没有多空格、是否复制漏字符；quota exceeded说明 Zep 免费额度用尽，Zep Cloud 每月有免费额度、够轻量使用，重度跑批建议控制并发与轮数。

哪条路适合你

三条路没有优劣，只有场景差异。跑通之后，你的下一步大概率是去backend/app/services/里挑一个文件读一遍——到那时，这篇教程就完成使命了。

【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish