6.3 KiB

Raw Blame History

MiroFish Neo4j 二开版

English | 中文

本项目基于原始开源仓库 666ghj/MiroFish 进行二次开发。

本版本的核心改动是：将原项目中的 Zep Cloud 图谱记忆与检索依赖替换为本地 Neo4j 后端，使项目可以使用本地图数据库完成实体关系存储、图谱检索、报告工具调用和模拟后的记忆更新，同时保留原 MiroFish 的多智能体模拟流程。

本项目遵守原仓库一致的开源协议：AGPL-3.0。

主要改动

使用本地 Neo4j 替代 Zep Cloud 图谱存储与检索。
新增 Neo4j 图谱构建、实体读取、记忆更新和搜索服务。
新增图数据库后端工厂，支持按配置切换图谱后端。
修复并增强报告工具输出：
- Deep Insight
- Panorama Search
- Quick Search
新增 LLM 429 限流等待与重试逻辑。
新增足球场景的比分概率计算与报告注入。
新增本地 Neo4j Docker Compose 配置。

功能说明

上传种子文档并抽取实体关系。
将抽取结果写入本地 Neo4j 图谱。
生成模拟 Agent 和社交行为配置。
运行双平台社交模拟。
基于图谱检索生成预测报告。
在足球比赛场景中输出胜平负概率、最可能比分、期望进球和比分矩阵。

项目结构

frontend/                 Vue + Vite 前端
backend/                  Flask 后端
backend/app/services/     模拟、报告、图谱与适配服务
backend/app/services/adapters/
                           Neo4j 图谱适配实现
backend/app/utils/neo4j/  Neo4j 驱动与 Schema 工具
locales/                  多语言文案
static/                   静态图片资源

环境要求

Node.js 18+
Python 3.11 - 3.12
uv
Docker（用于快速启动 Neo4j）
一个兼容 OpenAI SDK 格式的 LLM API Key

环境变量配置

复制示例文件：

cp .env.example .env

最小本地配置示例：

LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

GRAPH_BACKEND=neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=neo4j

可选的 LLM 限流重试配置：

LLM_RATE_LIMIT_MAX_ATTEMPTS=20
LLM_RATE_LIMIT_INITIAL_DELAY=30
LLM_RATE_LIMIT_MAX_DELAY=180
LLM_RATE_LIMIT_BACKOFF_FACTOR=1.5

启动 Neo4j

项目提供了本地 Neo4j 的 Docker Compose 文件：

docker compose -f docker-compose.neo4j.yml up -d

默认地址：

Neo4j Browser：http://localhost:7474
Bolt URI：bolt://localhost:7687
默认账号：neo4j / password

请确保 .env 中的 NEO4J_PASSWORD 与 Docker Compose 中配置的密码一致。

安装依赖

一次性安装前后端依赖：

npm run setup:all

也可以分开安装：

npm run setup
npm run setup:backend

运行项目

同时启动前端和后端：

npm run dev

服务地址：

前端：http://localhost:3000
后端 API：http://localhost:5001

单独启动：

npm run backend
npm run frontend

Docker 运行

根目录的 docker-compose.yml 可用于启动应用容器。若使用本地 Neo4j 图谱后端，建议先启动 Neo4j：

docker compose -f docker-compose.neo4j.yml up -d

再启动应用：

docker compose up -d

默认会读取根目录下的 .env，并映射端口 3000（前端）/5001（后端）。

基本使用流程

启动 Neo4j。
启动后端和前端。
打开 http://localhost:3000。
创建或打开项目。
上传种子文档。
构建图谱。
生成模拟配置。
启动模拟。
生成预测报告。

报告检索工具

报告 Agent 可以调用以下图谱检索工具：

Deep Insight：将问题拆解为多个子问题，并收集相关事实、实体和关系链。
Panorama Search：返回图谱中的全景实体和事实。
Quick Search：对图谱事实、节点名称和节点摘要进行轻量关键词搜索。
Interview Agents：结合模拟或图谱上下文生成面向 Agent 的回答。

在 Neo4j 二开版中，检索工具会输出前端可直接解析的文本结构，因此报告时间线能够展示事实、实体和关系链，而不是空白 JSON。

足球比分概率报告

当模拟需求或种子数据包含足球、比分、泊松、lambda、xG、expected goals 等信号时，后端会尝试抽取：

lambda_home
lambda_away
xG / expected goals
主客队信息

并生成：

主胜 / 平局 / 客胜概率
最可能比分 Top Scorelines
期望进球
比分概率矩阵

该部分会作为确定性计算结果注入报告，避免报告只停留在 LLM 的泛化描述。

日志位置

常用本地日志：

log/backend-restart.out.log
log/backend-restart.err.log
log/frontend-direct.out.log
log/frontend-direct.err.log
backend/uploads/reports/<report_id>/agent_log.jsonl
backend/uploads/reports/<report_id>/console_log.txt

常见问题

Neo4j 连接失败

确认 Neo4j 已启动，并检查 .env 中的 Neo4j 配置是否与 Docker Compose 一致。

docker compose -f docker-compose.neo4j.yml ps

LLM 返回 429

后端已内置限流重试逻辑。遇到 429 时会根据 LLM_RATE_LIMIT_* 配置等待后继续重试。

Deep Insight / Panorama Search / Quick Search 内容为空

请确认项目已经成功构建图谱。Neo4j 检索会搜索关系事实、节点名称和节点摘要；如果图谱本身没有内容，工具也无法返回有效结果。

报告缺少比分预测

请确认模拟需求或种子数据包含足球相关关键词，并提供可抽取的 lambda_home、lambda_away、xG 或 expected goals 信息。

开源协议

本项目继承原仓库协议，使用 AGPL-3.0。

如果你部署、分发，或通过网络提供该软件服务，请遵守 AGPL-3.0 的相关要求。

致谢

本项目基于 666ghj/MiroFish 进行二次开发。感谢原作者及所有贡献者的开源工作。

6.3 KiB Raw Blame History Unescape Escape