企业官网建设流程全解析

MiroFish 本地部署指南：4 条命令跑通群体智能预测引擎

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

MiroFish 是一款简洁通用的群体智能预测引擎：你上传一份种子材料（新闻、报告甚至小说片段），它会自动构建出一个由大量智能体构成的平行世界，让智能体在其中自由交互、演化，最终给你一份预测报告和一个可交互的数字沙盘。本文带你用源码部署的方式，从零基础把 MiroFish 在本地跑起来，10 分钟内完成首次页面访问。

读完本文，你将能够：独立完成环境检查、用 4 条命令启动本地服务、修改端口与模型配置，并在卡住时按清单快速定位问题。

确认 MiroFish 的运行前置条件

动手之前先花 30 秒确认本机工具链是否齐全。MiroFish 采用前后端分离结构：前端是 Vite 开发的 Vue 应用，后端是 Flask 服务，两者由项目根目录的package.json统一调度，所以你需要同时具备 Node.js 和 Python 环境。

uv 之于 Python，就像 npm 之于前端，装好后所有包管理都交给它。如果你机器上已经有 Docker，也可以在后面看到一条docker-compose up -d的替代路线，两条路线最终访问的都是同一个界面。

确认以上全部就绪后，进入下一步。

4 条命令快速启动 MiroFish 本地服务

下面是最短路径：克隆、配置、装依赖、启动，总共 4 条命令。

克隆仓库并进入目录

# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/mi/MiroFish # 进入项目目录 cd MiroFish

执行后你会看到：终端提示克隆完成，ls目录下有backend/、frontend/、.env.example等文件。

💡提示：clone 地址走的是 gitcode 镜像，国内网络下载更快。

创建配置文件并填入密钥

# 复制配置模板 cp .env.example .env # 编辑 .env，填入 LLM_API_KEY 和 ZEP_API_KEY 两个密钥

执行后你会看到：项目根目录多出一个.env文件。.env是系统的配置面板，改完重启即生效，MiroFish 的模型地址、密钥都在这一个文件里。

⚠️注意：LLM_API_KEY和ZEP_API_KEY不填，后端启动时会直接校验失败并退出。

一键安装前后端依赖

# 同时安装前端 npm 依赖和后端 Python 依赖 npm run setup:all

执行后你会看到：终端先后滚动 npm 和 uv 两段安装日志，最后以无报错结束。这个命令会在backend/下创建一个 Python 虚拟环境（相当于一个隔离小房间，装的包不影响系统），首次运行大约需要 2~5 分钟。

💡提示：setup:all是根目录package.json里的别名，等于"前后端npm install+ 后端uv sync"三连。

同时启动前后端服务

# 启动后端(5001)和前端(3000) npm run dev

执行后你会看到：终端出现 backend 和 frontend 两路日志，浏览器自动打开http://localhost:3000。前端开发服务器就像前台，会把所有/api请求转交给 5001 端口的后端，所以你只需记住 3000 这一个地址。

💡提示：如果 3000 端口被占用，别担心，第 4 板块会讲怎么改端口。

按需调整端口、模型与模拟轮数

跑通之后，下面三个配置是日常最常用的，每个都对应一个明确目标。

接入自己的 LLM 模型

目标：把默认的阿里百炼qwen-plus换成你自己的 OpenAI 兼容接口。需要改的文件：项目根目录.env。

# ===== LLM API 配置（支持 OpenAI SDK 格式的任意 LLM API）===== -LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 -LLM_MODEL_NAME=qwen-plus +LLM_BASE_URL=https://api.openai.com/v1 # 改成你自己的接口地址 +LLM_MODEL_NAME=gpt-4o-mini # 改成你账号里可用的模型名

验证方法：重启npm run dev，在后端日志里看到无报错的启动信息后，发起一次少于 40 轮的小模拟，能正常出结果即接入成功。

修改前后端监听端口

目标：本机 3000 或 5001 端口已被其他服务占用。端口就像门牌号，一扇门只能挂一个号码，所以只要改，就要前后端一起改。需要改的文件：.env和frontend/vite.config.js。

# frontend/vite.config.js server: { - port: 3000, + port: 3005, // 前端改为 3005 proxy: { '/api': { - target: 'http://localhost:5001', + target: 'http://localhost:5011', // 代理目标同步改成后端新端口

# .env +FLASK_PORT=5011 # 后端监听端口，backend/run.py 会读取这个环境变量

验证方法：重启npm run dev，访问http://localhost:3005，页面能打开且图谱功能可用即改好。

⚠️注意：两处必须同时改，只改一端会出现"页面能开、但所有请求都报错"的半瘫痪状态。

调低模拟轮数控制成本

目标：先用小轮数试跑，避免默认 10 轮模拟带来较多的 API 消耗。需要改的文件：.env。

# .env +OASIS_DEFAULT_MAX_ROUNDS=3 # 默认 10 轮，小试可先降到 3 轮

后端在backend/app/config.py中读取该变量，改完重启即生效。验证方法：在 Web 界面发起一次模拟，观察模拟进度，轮数明显变少即配置成功。

逐个排查 5 个高频卡点

如果按上面的步骤走不通，对照下面这份清单从上往下查。

1. 症状：后端启动即退出，终端打印"LLM_API_KEY 未配置"等配置错误。原因：.env没创建，或两个必填密钥没填。解法：

   cp .env.example .env # 编辑 .env，填入 LLM_API_KEY 和 ZEP_API_KEY

2. 症状：npm run dev报 3000 端口被占用，或页面打不开。原因：端口与本机其他服务冲突。解法：

   lsof -i:3000 # 确认占用端口的进程

   然后按"修改前后端监听端口"一节的步骤改端口。

3. 症状：页面能打开，但加载后数据为空或提示接口错误。原因：5001 端口的后端没起来，前端代理无处转发。解法：查看终端里 backend 一路的日志，多为.env配置或依赖问题，修正后重新执行npm run dev。

4. 症状：npm run setup:all中途超时或大量下载失败。原因：默认 npm 源在当前网络下不稳定。解法：

   npm config set registry https://registry.npmmirror.com npm run setup:all

5. 症状：模拟过程特别慢，API 账单涨得快。原因：默认 10 轮模拟、双平台并行，单次消耗不低。解法：在.env中加OASIS_DEFAULT_MAX_ROUNDS=3先试跑，跑通后再逐步调大。

部署完成之后，可以继续阅读 README-ZH.md 了解从图谱构建到深度互动的完整工作流程，或直接浏览 backend/app/ 下的后端源码对照各阶段实现；若遇到清单之外的报错，可到项目 Issue 区检索，QQ 群与社区频道的入口在 README-ZH.md 顶部有说明。

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