MiroFish 完整部署指南：从一条命令到第一次预测
【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish
MiroFish 是一个基于多智能体的群体智能预测引擎：你上传报告或种子材料，它在模拟环境里推演群体演化，最后输出一份预测报告。这篇指南把部署拆成了明确步骤，看完你能用 Docker 一条命令把系统跑起来，上传第一份文档，拿到第一次预测结果。
选路：三种方式各一句话判断
| 路线 | 适合谁 | 一句话判断 |
|---|---|---|
| Docker 一键 | 想体验功能、正式使用 | 只要用，不碰本地依赖 |
| 源码部署 | 想定制后端行为 | 要改代码，在本地环境里跑 |
| 开发环境 | 想贡献代码、深度定制 | 前后端同时起、改完即生效 |
前两条路线不互斥：它们共用同一个 .env 配置和同一套端口，差别只在代码跑在容器里还是跑在你机器上。
MiroFish Docker 部署步骤：四步启动
前提是机器上已经装好 Docker 和 Docker Compose；没有的话先通过系统包管理器或官网装上。
1. 拿到代码
git clone https://gitcode.com/GitHub_Trending/mi/MiroFish cd MiroFish克隆完成后，部署相关的配置都集中在根目录的 docker-compose.yml 里，不需要任何构建动作。
2. 创建配置文件
cp .env.example .env这是唯一的手工步骤，也是 MiroFish 环境变量配置的关键点。.env 里必填四项：LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_NAME 指向一个 OpenAI 兼容格式的 LLM 服务，ZEP_API_KEY 给记忆图谱服务用。示例文件里还有一段可选的 LLM 加速配置，不用就整段删掉，不要留着空值。
3. 启动容器
docker compose up -d服务在后台运行，镜像已经预构建好，本地不用装 Python 和 Node。容器对外暴露 3000（前端）和 5001（后端）两个端口，并把 ./backend/uploads 挂载进容器，上传的文件能持久保存。拉镜像慢的话，docker-compose.yml 的注释里有一个加速地址，按需替换。
4. 确认进程
docker compose logs -f看到日志没有报错、两个端口都绑定成功，部署就算完成。
源码部署与开发环境：定制和贡献时额外做的事
只想用功能的话，这一节可以跳过。它只讲相对 Docker 路线多出来的部分：本地运行环境，加依赖安装。
前置要求
| 组件 | 版本 | 检查命令 |
|---|---|---|
| Node.js | 18+ | node -v |
| Python | ≥3.11 且 ≤3.12 | python --version |
| uv | 最新版 | uv --version |
安装依赖
npm run setup:all一条命令覆盖根目录、前端 Node 依赖和后端 Python 依赖，虚拟环境自动创建。想拆开来的话，npm run setup 装前端，npm run setup:backend 装后端。
启动服务
npm run dev前后端同时拉起，各自带独立日志。调试时只想动一边，就用 npm run backend 或 npm run frontend 单独启动，配置改动立刻生效，方便打断点。代码结构值得先认识：后端在 backend/app/，api/ 是接口层，services/ 是核心逻辑；前端组件在 frontend/src/components/。
跑起来后的第一次使用：打开页面到拿到第一份预测
服务启动后，不管走哪条路线，流程都一样：
1. 访问
浏览器打开 http://localhost:3000，能看到欢迎页；后端 API 在 http://localhost:5001，页面会自己调，不用你管。
2. 上传
在上传区放入一份文档，PDF、TXT 都行，比如一份舆情报告或一段小说文本。
3. 发起
用自然语言写清需求，例如“推演这个舆情事件未来一个月的演化走向”，然后点开始。
4. 看结果
模拟跑完，你会得到一张关系图谱、一份预测报告和一个对话入口，可以直接向模拟世界里的实体提问。
消耗上有个提醒：每轮模拟都调用 LLM，成本不低。第一次先跑少于 40 轮，确认效果后再放开规模。
排障速查：现象、原因、解法一张表
遇到问题，大概率是下面四种之一；碰上 MiroFish 端口冲突，直接看第一行。
| 现象 | 原因 | 解法 |
|---|---|---|
| 页面打不开，提示端口被占用 | 3000 或 5001 被其他进程占了 | docker-compose.yml 里把宿主机侧改成 3001:3000、5002:5001，重启容器 |
| 容器起来后立刻退出 | .env 少了必填项 | 核对 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_NAME、ZEP_API_KEY 四项 |
| 拉镜像极慢 | 默认镜像源距离远 | 换 docker-compose.yml 注释里的加速地址 |
| 模拟时内存不足 | 并发智能体太多 | 在 docker-compose.yml 加资源限制、减少模拟轮数，或换更轻量的模型 |
进阶：内存限制、扩展配置与适用场景
- 内存限制：在 docker-compose.yml 给服务加一个上限（比如 4G），避免大模拟占满整机。
- 模拟规模：轮数先小后大，熟悉系统节奏再放大；Zep Cloud 每月免费额度足够支撑简单使用。
- 可扩展点：自定义智能体类型、加数据源适配器、接第三方分析工具，都可以在 backend/app/services/ 的服务层上做。
- 适用场景：金融趋势推演、舆情演化模拟、小说情节发展、政策影响评估——凡是用“种子信息 + 一个未来问题”能描述的，都可以试。
写在最后
容器跑起来，部署里最重的部分就结束，剩下的是不断上传下一份文档。真到了要改行为的阶段再切到源码路线，配置文件和端口规划都能原样带走。
【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
