技术百科首页 >如何运行 MiroFish（场景预测与多智能体仿真）探索独特的 AI 预测引擎

如何运行 MiroFish（场景预测与多智能体仿真）探索独特的 AI 预测引擎

v_cloudbuilder 2026-05-1212

作者：Pavol Labuda

MiroFish 是一款基于 AI 的工具，借助 LLM 和 Zep 实现知识图谱生成与仿真。
部署本身很简单，但远程访问可能会遇到坑——前端可能尝试通过 localhost 访问后端，导致浏览器报 "Network Error"。

本指南将演示如何使用 Docker Compose 部署 MiroFish，并修复常见的远程服务器访问问题。

采购建议（推荐配置）

为确保 MiroFish 获得最佳性能（尤其是多智能体仿真和 GraphRAG 处理），通过我的专属链接购买 Lighthouse 实例时，建议选择以下规格：

msedge_ASM9JKPjPm.png

  1. 选择地域： 选择海外地域（如硅谷、法兰克福、新加坡），这样访问 LLM API（如 Gemini 或 ChatGPT）时延迟更低。
  2. 选择实例规格：
    • 最低配置： 2 vCPU、4GB 内存（适用于小型图谱/测试）。
    • 推荐配置： 4 vCPU、8GB 内存或更高（仿真流畅，嵌入生成更快）。
  3. 选择应用： 选择 Docker（基于 Ubuntu Server）。
    msedge_caEVnzETYu.png
  4. 完成购买： 你可以通过我的专属链接直接购买实例：
    👉 立即部署 MiroFish 就绪的 Lighthouse 实例

💡 小贴士： 通过此链接购买，你可能获得双倍代金券奖励！

环境要求

开始之前，请确保你拥有：

  • 一台已安装 Docker 和 Docker Compose 的 Linux 服务器或虚拟机
  • LLM API Key，例如 DeepSeek 或其他受支持的服务商
  • 用于 GraphRAG 记忆的 Zep API Key
  • 已开放的防火墙端口：
    • 前端 3000
    • 后端 5001

前置准备

在配置 MiroFish 之前，请确认以下事项：

  • 是否已准备好腾讯云 Lighthouse 实例？
  • 是否已配置系统？ 确保服务器已安装 Docker 和 Docker Compose。
  • API Key 是否已就绪？
    • LLM API Key（如 DeepSeek、OpenAI）。
    • 用于 GraphRAG 记忆的 Zep API Key。

首次使用提示： 如果你还没有部署 Lighthouse 实例，可以点击此处先部署一个实例。
💡 小贴士： 通过此专属链接购买，你可能获得双倍代金券奖励！

如果你已有 Lighthouse 实例，但缺少必要的 API Key 或 Docker 环境，请先准备好再继续。

1) 连接到 Lighthouse 实例

  1. 登录腾讯云并进入 控制台。
    00.png

  2. 在腾讯云控制台中，通过 所有产品 进入 腾讯云 Lighthouse 实例页面。
    01.png
    02.png

  3. 使用 登录 按钮或 SSH 远程连接，进入 腾讯云 Lighthouse 实例。
    03.png
    04.png
    05.png

2) 部署 MiroFish

1) 创建部署目录并进入：

mkdir -p mirofish
cd mirofish

你将在该目录中放置 docker-compose.yml 和 .env 两个文件。

2) 创建 .env 文件

在项目根目录创建环境变量文件：

nano .env

粘贴以下内容，并将占位符替换为你自己的值：

# 前端 -> 后端 API 地址
# 仅当所有服务都运行在你本机时才使用 localhost。
# 远程虚拟机请使用公网 IP 或域名。
VITE_API_BASE_URL=http://<YOUR_VM_IP_OR_DOMAIN>:5001

# LLM 服务商配置
LLM_API_KEY=<YOUR_LLM_API_KEY>
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL_NAME=deepseek-chat

# 用于记忆 / GraphRAG 的 Zep
ZEP_API_KEY=<YOUR_ZEP_API_KEY>

关于远程访问的重要说明

如果你从另一台电脑的浏览器打开前端，localhost 指的是你自己的电脑，而不是服务器。
所以你必须设置：

VITE_API_BASE_URL=http://<YOUR_VM_IP_OR_DOMAIN>:5001

如果你使用域名，请确保它指向服务器，且浏览器可访问。

在 Lighthouse 中开放防火墙

端口与 docker-compose.yml 文件中保持一致，即 5001 和 3000。

image

3) 创建 docker-compose.yml

创建 Compose 文件：

nano docker-compose.yml

使用以下配置：

services:
  mirofish:
    # 主镜像
    image: ghcr.nju.edu.cn/666ghj/mirofish:latest
    # 备用镜像源：
    # image: ghcr.io/666ghj/mirofish:latest

    container_name: mirofish
    env_file:
      - .env
    ports:
      - "3000:3000"
      - "5001:5001"
    restart: unless-stopped
    volumes:
      - ./backend/uploads:/app/backend/uploads

可选说明

  • volumes 行用于将上传的文件保留在宿主机上。
  • 如果镜像拉取速度慢，可以根据可用性切换镜像源。
  • 如果你想使用镜像源中最新的 UI 代码，仅当项目明确要求时才从源码重新构建。对大多数用户来说，预构建镜像已经足够。

4) 启动 MiroFish

在后台运行容器：

docker compose up --build -d

首次运行可能需要几分钟，因为依赖项和前端资源都需要准备。

5) 检查是否启动成功

查看日志：

docker logs -f mirofish

或者使用 Compose 日志：

docker compose logs -f

你应该看到后端和前端正常启动，没有反复报错。

mirofish  | [backend] > mirofish@0.1.0 backend
mirofish  | [backend] > cd backend && uv run python run.py
mirofish  | [backend]
mirofish  | [frontend]
mirofish  | [frontend] > mirofish@0.1.0 frontend
mirofish  | [frontend] > cd frontend && npm run dev
mirofish  | [frontend]
mirofish  | [frontend]
mirofish  | [frontend] > frontend@0.1.0 dev
mirofish  | [frontend] > vite --host
mirofish  | [frontend]
mirofish  | [backend]  * Serving Flask app 'app'
mirofish  | [backend]  * Debug mode: on
mirofish  | [backend] WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
mirofish  | [backend]  * Running on all addresses (0.0.0.0)
mirofish  | [backend]  * Running on http://127.0.0.1:5001
mirofish  | [backend]  * Running on http://172.18.0.2:5001
mirofish  | [backend] Press CTRL+C to quit
mirofish  | [backend]  * Restarting with stat
mirofish  | [frontend]
mirofish  | [frontend]   VITE v7.2.7  ready in 1131 ms
mirofish  | [frontend]
mirofish  | [frontend]   ➜  Local:   http://localhost:3000/
mirofish  | [frontend]   ➜  Network: http://172.18.0.2:3000/
mirofish  | [frontend] Error: spawn xdg-open ENOENT
mirofish  | [frontend]     at ChildProcess._handle.onexit (node:internal/child_process:285:19)
mirofish  | [frontend]     at onErrorNT (node:internal/child_process:483:16)
mirofish  | [frontend]     at process.processTicksAndRejections (node:internal/process/task_queues:82:21)
mirofish  | [backend] [17:56:23] INFO: ==================================================
mirofish  | [backend] [17:56:23] INFO: MiroFish Backend 启动中...
mirofish  | [backend] [17:56:23] INFO: ==================================================
mirofish  | [backend] [17:56:23] INFO: 已注册模拟进程清理函数
mirofish  | [backend] [17:56:24] INFO: MiroFish Backend 启动完成

6) 打开 Web UI

在浏览器中打开：

http://<YOUR_Tencent-Cloud-Lighthouse_IP_OR_DOMAIN>:3000

如果页面能加载，但生成本体或构建图谱等操作出现网络错误，通常是 .env 中的后端 URL 配置有问题。

3) 使用 MiroFish 的基本工作流

典型的 MiroFish 工作流如下：

  1. 创建新项目
    • 上传你的文档，如 PDF 或 TXT 文件
    • 添加一段提示词，描述你想提取或仿真的内容

01.png
2. 生成本体（Ontology）
- LLM 分析你的文档
- 为知识图谱创建实体与关系

02.png
3. 构建图谱
- MiroFish 对文档进行分块（chunking）
- 数据被发送给 Zep
- 基于提取到的结构构建知识图谱

05.png

  1. 创建仿真
    • 图谱准备好后，打开仿真环境
    • 与生成的实体和关系进行交互

06.png
07.png
08.png
09.png
10.png

故障排查

浏览器中出现 "Network Error"

这是远程服务器上最常见的问题。
原因：

  • 前端尝试调用 localhost:5001
  • 浏览器把 localhost 解析为本机，而不是远程虚拟机

解决方法：

  • 将 .env 中的 VITE_API_BASE_URL 设置为服务器的公网 IP 或域名
  • 修改文件后重启容器：
docker compose down
docker compose up -d

端口不通

检查虚拟机防火墙是否同时放行了以下端口：

  • 3000
  • 5001

如果你使用云厂商，还需检查云厂商的安全组或入站规则。

容器启动了但 UI 无法使用

请检查：

  • .env 与 docker-compose.yml 是否在同一目录
  • API Key 是否有效
  • VITE_API_BASE_URL 是否包含正确的主机和端口
  • 修改后是否已重启容器

日志中出现启动错误

仔细查看日志：

docker logs mirofish

常见原因：

  • 缺少环境变量
  • API Key 错误
  • 后端 URL 无效
  • 防火墙阻断访问

常用命令

停止容器：

docker compose down

重启容器：

docker compose restart

修改后重新构建：

docker compose up --build -d

实时查看日志：

docker logs -f mirofish

最小化部署清单

  • 已安装 Docker
  • 已安装 Docker Compose
  • 已创建 .env 文件
  • VITE_API_BASE_URL 指向正确的服务器
  • 已添加 API Key
  • 端口 3000 和 5001 已开放
  • 容器启动成功
  • 浏览器中打开 UI，无网络错误

加入我们的 Discord 群组！

扫描二维码加入 Lighthouse用户讨论群，解锁并交流在云端使用AI的经验。

🚀 腾讯云开发者社区与支持

1️⃣ 腾讯云开发者交流社区

Discord 解锁更多进阶玩法

点击一键加入社群

2️⃣ 专属服务支持

加入 Whatsapp/企业微信享受专属技术支持

渠道 扫描/点击进入
Whatsapp 频道
企业微信

立即部署 MiroFish 就绪的 Lighthouse 实例