MiroFish 本地化部署分析主仓库、Zep Cloud、离线 Fork 与真正可控的多智能体沙盘最近 MiroFish 这个项目热度非常高。它的定位很有想象力不是让一个大模型回答问题而是让系统根据用户上传的现实材料自动构建一个由大量智能体组成的“平行数字世界”再通过这些智能体之间的互动、争论、传播和行为演化推演一个复杂事件未来可能的发展方向。这类项目很容易让人兴奋。因为它把大模型应用从“问答工具”推进到了“场景模拟”。传统 ChatGPT 式问答本质上是单个模型在压缩已有知识、推理可能结果而 MiroFish 的叙事是先把现实世界里的实体、关系和背景抽出来再生成大量具有不同身份、人格、记忆和行为逻辑的 Agent让这些 Agent 在模拟环境里互动最后生成预测报告和可交互的数字沙盘。这背后代表的是一个重要方向AI 不再只是生成文本而是开始模拟系统。但真正准备部署 MiroFish 时一个问题会马上出现它到底能不能完全本地部署如果我不想用 Minimax、OpenAI、阿里百炼这类云端模型只想免费、本地、私有化运行它是否可行如果官方主仓库不支持完整本地化社区里又是怎么解决的本文围绕这个问题展开。一、MiroFish 到底是什么MiroFish 可以理解成一个“多智能体社会仿真系统”。它的基本流程大致是用户上传一份种子材料比如新闻、政策草案、金融报告、小说文本、舆情资料系统从这些材料中提取实体、关系、背景和事件脉络然后构造知识图谱再根据知识图谱生成一批 Agent Profile最后让这些 Agent 在模拟社交环境中互动生成传播、争论、态度变化、群体分化等过程并输出一份分析报告。从产品表达上看它像是“预测未来”。从工程角度看它更准确的说法是“基于种子材料的多智能体情景推演”。这两种表述有本质差别。“预测未来”容易让人误解为它真的有稳定、可验证、可量化的预测能力。但当前阶段MiroFish 更适合被看作一个复杂系统推演工具它可以帮助用户观察某类事件在不同人群、组织、媒体、平台和意见领袖之间可能如何传播也可以帮助用户构建小说角色群体、舆情传播场景、政策反应场景、市场情绪场景。它不是水晶球。它更像一个由 LLM 驱动的数字沙盘。这个定位非常重要。因为如果把它当成“绝对预测工具”会高估它如果把它当成“复杂场景模拟工具”它就很有价值。二、MiroFish 的核心架构从代码结构和运行流程看MiroFish 主要包含几层。第一层是前端界面。它提供上传材料、创建项目、查看图谱、运行模拟、生成报告、交互查看结果等功能。第二层是 Flask 后端。后端负责任务编排包括文件解析、本体生成、图谱构建、Agent Profile 生成、仿真配置生成、模拟运行、报告生成等。第三层是大模型调用层。MiroFish 并不绑定某一个模型厂商而是通过 OpenAI-compatible API 调用模型。也就是说只要你的模型服务兼容/v1/chat/completions这种接口格式理论上就可以接入 MiroFish。第四层是图谱与记忆层。主仓库默认依赖 Zep Cloud。它用 Zep 来存储和检索实体、关系、episode、上下文等内容。第五层是仿真层。MiroFish 使用 CAMEL-AI / OASIS 相关能力来模拟社交平台式的 Agent 行为。也就是说它当前更偏“社交传播仿真”和“群体行为仿真”不是机器人、物理世界、运动控制那种仿真。这几个部分中真正影响本地化程度的主要有两个大模型层和图谱记忆层。大模型层可以本地化。你可以用 Ollama、LM Studio、llama.cpp server、vLLM 等方式提供 OpenAI-compatible API。图谱记忆层才是麻烦点。主仓库默认依赖 Zep Cloud而不是本地 Neo4j、SQLite、Graphiti 或本地 JSON。所以MiroFish 官方 Docker 部署不等于完全本地部署。三、为什么说主仓库不能算完全本地化MiroFish 主仓库提供 Docker Compose。表面上看只要执行cp.env.example .envdockercompose up-d就能在本地或服务器上跑起来。Docker Compose 会启动 MiroFish 容器映射前端端口和后端端口通常是3000 - 前端 5001 - 后端 API并且会挂载上传目录./backend/uploads:/app/backend/uploads这说明前端、后端、上传文件目录都可以本地运行。但.env里仍然需要配置LLM_API_KEYxxx LLM_BASE_URLxxx LLM_MODEL_NAMExxx ZEP_API_KEYxxx这里的关键不是 LLM而是ZEP_API_KEY。如果你使用 Minimax、OpenAI、阿里百炼、DeepSeek、OpenRouter这当然是云端。如果你使用 vLLM、Ollama、LM Studio那么 LLM 可以是本地的。但只要ZEP_API_KEY仍然存在图谱记忆层就仍然依赖 Zep Cloud。所以主仓库的本地化程度应该这样描述前端本地 后端本地 上传文件本地 LLM可本地也可云端 图谱/记忆默认 Zep Cloud而不是前端本地 后端本地 LLM本地 Embedding本地 图数据库本地 图谱检索本地 记忆更新本地这就是很多人部署时容易误解的地方。Docker 只是让应用容器化。容器化不等于全链路本地化。四、Zep Cloud 为什么成为本地化卡点Zep 是一个 Agent Memory / Context Graph 服务。它不是简单的向量数据库也不是普通关系数据库。它的核心价值在于把对话、事件、文档、行为等内容组织成可检索、可更新、带时间属性的知识图谱。MiroFish 用 Zep 做什么大致包括创建 graph 设置 ontology 添加 episode 处理实体与关系 读取 nodes 读取 edges 搜索上下文 为 Agent Profile 和报告生成提供图谱记忆也就是说Zep 不只是一个旁路依赖而是 MiroFish 主流程的一部分。过去 Zep 有 Community Edition可以本地部署。但现在 Zep Community Edition 已经废弃不再维护。官方当前给出的路线是使用 Zep Cloud或者使用开源的 Graphiti企业客户可以走 BYOC。这意味着你不能简单地在本地启动一个旧版 Zep CE然后认为问题解决了。旧版能不能跑是一回事是否长期可靠、是否兼容当前 SDK、是否值得作为新项目依赖是另一回事。对个人开发者来说现实选择只有三个第一使用 Zep Cloud 免费额度。第二改造 MiroFish把 Zep 替换成本地图谱存储。第三直接使用社区离线 Fork。五、社区第一种路线主仓库 本地 LLM Zep Cloud这是最容易跑通的路线。架构是MiroFish Docker 本地 vLLM / Ollama / LM Studio Zep Cloud这种方式不算完全本地化但非常适合第一阶段测试。如果你已经有 A6000、4090、A100、H100 这类显卡可以直接用 vLLM 部署 Qwen 系列模型然后让 MiroFish 调用本地 OpenAI-compatible API。示例CUDA_VISIBLE_DEVICES0vllm serve Qwen/Qwen2.5-32B-Instruct\--host0.0.0.0\--port8000\--served-model-name qwen-local\--gpu-memory-utilization0.85\--max-model-len32768MiroFish.envLLM_API_KEYlocal LLM_BASE_URLhttp://host.docker.internal:8000/v1 LLM_MODEL_NAMEqwen-local ZEP_API_KEY你的_Zep_Cloud_Key如果 MiroFish 容器和 vLLM 服务在同一台 Linux 宿主机上可能需要在docker-compose.yml中加extra_hosts:-host.docker.internal:host-gateway这种方案的好处是非常明确的变量少排错简单主仓库兼容性最好。它的缺点也很明确材料、图谱、记忆相关数据会经过 Zep Cloud不是完全私有化。如果你只是想体验 MiroFish或者验证它是否值得深入改造这条路线最合理。不要一开始就追求完全本地化。因为 MiroFish 本身有很多不稳定因素模型 JSON 输出、ontology generation、图谱构建耗时、OASIS 仿真成本、报告生成稳定性。如果你一上来再叠加图谱层替换排错会非常混乱。六、社区第二种路线把 Zep 替换成本地 JSON 文件社区里已经有人尝试把 Zep Cloud 完全移除改成本地 JSON 文件存储。这个方向的核心思路是Zep Cloud - 本地 JSON nodes - nodes.json edges - edges.json episodes - episodes.jsonl semantic search - keyword search这种方案的优点是极其简单。它不需要 Neo4j不需要 Graphiti不需要 Zep Cloud不需要额外数据库。所有图谱节点、边、事件都写在本地目录里比如uploads/graphs/{graph_id}/它非常适合小规模 demo、离线演示、个人测试。但它的问题也同样明显。第一关键词搜索不能等价替代语义检索。第二JSON 文件不适合大规模并发写入。第三图遍历能力弱。第四长期维护、迁移、查询优化都比较麻烦。第五它更像“为了完全离线而做的轻量替换”不是严肃生产级图谱层。所以这条路线的判断是想快速离线可以 想长期做产品不够 想大规模 Agent 仿真不稳 想保持图谱能力不合适如果只是想把 MiroFish 作为个人工具或演示项目本地 JSON 方案很有性价比。如果你想把它并入自己的 AI Agent 平台、机器人云端编排系统、企业内部沙盘系统那就不该停留在 JSON 文件层。七、社区第三种路线MiroFish-Offline目前社区里更像“完整本地化方案”的是 MiroFish-Offline 这个 Fork。它做了几件关键改造Zep Cloud - Neo4j Community Edition 云端 LLM - Ollama 本地模型 云端 embedding - Ollama nomic-embed-text 中文 UI - 英文 UI它的 Docker Compose 不再只是启动 MiroFish 一个容器而是会启动多个服务MiroFish 应用 Neo4j Ollama部署流程大致是gitclone MiroFish-OfflinecdMiroFish-Offlinecp.env.example .envdockercompose up-ddockerexecmirofish-ollama ollama pull qwen2.5:32bdockerexecmirofish-ollama ollama pull nomic-embed-text然后访问http://localhost:3000这条路线的意义很大。因为它证明了一件事MiroFish 不是理论上不能完全本地化而是主仓库当前没有把本地化作为默认架构。只要把 Zep Cloud 替换成 Neo4j把 LLM 替换成本地服务把 embedding 替换成本地模型MiroFish 这类项目完全可以在本地硬件上跑。但 MiroFish-Offline 也不是完美答案。第一它是社区 Fork不是主仓库官方长期维护版本。第二它默认使用 Ollama适合快速部署但对高吞吐、大并发、显存利用率要求高的场景不如 vLLM。第三它替换了图谱存储层但你仍然需要验证图谱构建质量、查询质量、报告生成质量是否和原版一致。第四它偏英文 UI对中文材料、中文场景、中文舆情推演是否稳定需要自己测试。第五Fork 与主仓库会逐渐分叉后续主仓库的新功能、Bugfix、接口变化不一定能自动同步。所以MiroFish-Offline 是很好的参考实现但不一定适合作为长期技术底座直接依赖。八、如果是有 A6000 的服务器应该怎么选如果你有 A6000 这种 48GB 显存的卡不应该长期用 Ollama 作为核心推理服务。Ollama 的优势是简单。它适合个人电脑、快速体验、低门槛部署。但如果目标是更高吞吐、更好并发、更强显存管理、更适合生产化的 OpenAI-compatible 服务vLLM 更合适。所以更合理的本地化路线是MiroFish-Offline Neo4j 本地图数据库 vLLM 本地大模型 Ollama 只做 embedding或替换为专门的 embedding 服务示例架构MiroFish Backend - OpenAI-compatible LLM API - vLLM Qwen2.5-32B / Qwen3-32B - Graph Storage - Neo4j - Embedding API - Ollama nomic-embed-text / bge-m3 / Qwen embedding这样做比纯 Ollama 更适合你的服务器资源。模型选择上优先考虑 Qwen 系列。原因不是“Qwen 一定最强”而是 MiroFish 主仓库原本就偏 Qwen 生态很多提示词、JSON 输出、本体生成和中文场景对 Qwen 更友好。建议顺序Qwen2.5-32B-Instruct稳定、非强 reasoning适合 JSON 管线 Qwen3-32B能力更强但要处理 thinking 输出污染 Qwen3-14B测试成本低 DeepSeek-R1-Distill-Qwen-32B推理强但 JSON 稳定性风险更高 GLM-4.5-AirAgent 能力强但部署和兼容性需要单独验证不要一开始就用强 reasoning 模型跑全流程。MiroFish 的很多步骤要求模型返回严格 JSON。如果模型输出think、解释文本、Markdown code fence、多余前后缀很容易导致 JSON 解析失败。所以本地模型部署时真正关键的是两个字稳定。不是越会推理越好而是越能按格式返回越好。九、MiroFish 本地部署最常见的坑第一个坑把 Docker 部署误认为完全本地化。Docker 只是运行方式不代表依赖都在本地。只要.env里还有云端 API key就不是真正本地化。第二个坑本地模型服务地址写错。MiroFish 在 Docker 容器里访问宿主机不一定能直接用localhost。容器里的localhost指的是容器自己不是宿主机。如果 vLLM 跑在宿主机上MiroFish 容器里通常应该访问http://host.docker.internal:8000/v1Linux 下还要配extra_hosts:-host.docker.internal:host-gateway第三个坑本地模型不支持response_format。一些 OpenAI-compatible 服务只是“接口像 OpenAI”但不代表完整支持所有参数。比如某些本地模型服务对{response_format:{type:json_object}}支持不完整可能直接 500或者忽略或者返回非 JSON。第四个坑reasoning 模型污染 JSON。Qwen3、DeepSeek-R1 这类模型可能输出思考过程。即使最终答案里有 JSON只要前面夹杂了think或解释文本后端如果直接json.loads()就会失败。第五个坑仿真成本被低估。MiroFish 不是一次聊天。它会多轮调用模型生成 ontology、构建 graph、生成 profile、生成 config、运行 simulation、生成 report。Agent 数量和轮数一上来token 消耗、时间和失败概率都会上升。第六个坑把 MiroFish 当生产级预测系统。当前它更适合研究、演示、创作、辅助分析和情景推演。严肃决策不能直接依赖一次模拟结果。正确用法是把它当“生成假设和观察路径”的工具而不是当“给最终答案”的系统。十、如果我要自己长期维护应该怎么改如果只是玩直接用主仓库或 MiroFish-Offline 就够了。如果要长期维护正确做法不是简单改几个 API Key而是重构图谱层。核心是抽象一个 GraphStorage 接口。例如classGraphStorage:defcreate_graph(self,graph_id):...defset_ontology(self,ontology):...defadd_episode(self,episode):...defupsert_node(self,node):...defupsert_edge(self,edge):...defsearch(self,query):...defget_nodes(self):...defget_edges(self):...然后实现多个 backendZepGraphStorage Neo4jGraphStorage JsonGraphStorage GraphitiGraphStorage这样以后就可以通过环境变量切换GRAPH_BACKENDzep GRAPH_BACKENDneo4j GRAPH_BACKENDjson GRAPH_BACKENDgraphiti这才是合理的软件架构。主仓库现在的问题不是“不能改”而是图谱层和 Zep 的耦合比较重。社区 PR 和 Fork 本质上都在做同一件事拆掉 Zep 依赖换成本地存储。但如果只是硬改把一堆zep_xxx.py改成本地 JSON 或 Neo4j会留下新的技术债。更干净的做法是先建立抽象层再适配不同存储。长期看最好的方向应该是LLM Provider 可切换 Embedding Provider 可切换 Graph Backend 可切换 Simulation Engine 可切换 Report Agent 可切换这样 MiroFish 才能从一个“依赖特定云服务的开源项目”变成一个真正可私有化部署的多智能体仿真平台。十一、推荐路线如果只是体验 MiroFish主仓库 Docker Zep Cloud 免费额度 本地 vLLM 或云端模型这是最稳路线。如果目标是尽快完全离线MiroFish-Offline Neo4j Ollama这是最省事的完全本地化路线。如果你有 A6000并且希望性能更好MiroFish-Offline Neo4j vLLM 跑 Qwen2.5-32B / Qwen3-32B 本地 embedding 服务这是更适合服务器的路线。如果你想长期做成自己的平台Fork 主仓库 抽象 GraphStorage 支持 Zep / Neo4j / JSON / Graphiti LLM 接 vLLM Embedding 本地化 保留 Docker Compose 一键启动这是最正确但成本最高的路线。十二、和普通 Agent 项目的区别MiroFish 的价值不在于“它又调用了几个工具”。很多 Agent 项目本质上是用户提问 LLM 判断意图 调用工具 返回结果这类系统适合执行任务比如查天气、调用数据库、控制设备、写代码、整理文档。MiroFish 的逻辑不同。它更像用户提供现实材料 系统构建世界模型 生成一批具有差异化立场和行为的 Agent 让 Agent 之间互动 观察群体演化 生成结构化报告它不是任务执行 Agent而是群体模拟 Agent。这类架构对未来 AI 应用很有启发。因为现实世界里很多问题不是“查一个答案”就能解决的而是涉及多个主体、多个立场、多个时间阶段和多个反馈回路。比如一个产品发布后用户会怎么反应 一个政策出台后不同群体会怎么理解 一个舆情事件会不会扩散 一个品牌声明是否会二次引爆 一段小说剧情继续发展人物关系会如何变化 一个公司组织调整会对员工情绪产生什么影响这些问题用单轮问答很难回答。即使回答了也更像主观分析。多智能体仿真至少提供了一种新的方法把问题拆成主体、关系、环境、事件和行为然后观察系统演化。这就是 MiroFish 最值得研究的地方。十三、它适合接入什么系统MiroFish 不适合直接接入实时语音助手的低延迟链路。比如一个语音机器人用户说一句话系统要在几百毫秒到几秒内响应这种场景不适合让 MiroFish 跑完整仿真。MiroFish 更适合做后台推演模块。例如用户提交一个复杂问题 系统进入后台推演 MiroFish 构建场景并运行模拟 生成报告 前端或语音助手再把结论摘要返回给用户它适合“慢任务”不适合“实时问答”。如果放到一个更大的 AI 操作系统里MiroFish 的定位应该是不是对话层 不是语音层 不是设备控制层 而是云端智能编排中的复杂情景推演模块它可以成为 Agent 系统里的一个工具simulate_scenario(seed_docs, goal, agent_count, rounds)调用后返回关键角色 传播链条 分歧点 潜在风险 可能结果 建议动作 反事实变量这比把它当成独立玩具更有价值。十四、最终判断MiroFish 主仓库当前不能算完全本地化项目。它可以 Docker 部署可以本地跑前后端可以接本地 LLM但默认图谱记忆层仍然依赖 Zep Cloud。由于 Zep Community Edition 已经废弃主仓库不是靠简单加一个本地 Zep 容器就能完整离线。社区的解决方式主要有三种。第一种主仓库继续用 Zep Cloud但把 LLM 换成本地 Ollama、vLLM、LM Studio。这是最稳的体验路线。第二种改代码把 Zep 替换成本地 JSON 文件。这是最轻量的完全离线路线但图谱能力下降明显。第三种使用 MiroFish-Offline把 Zep 替换成 Neo4j把云端模型替换成本地 Ollama。这是目前最接近完整本地部署的社区方案。如果只是想体验优先主仓库 Zep Cloud 本地 vLLM。如果明确要求“免费、本地、离线”优先研究 MiroFish-Offline。如果想长期做成自己的系统不要直接押注某个 Fork而是 fork 主仓库抽象 GraphStorage把 Zep、Neo4j、Graphiti、本地 JSON 都做成可切换 backend。MiroFish 这个项目真正值得学习的不是某个部署脚本而是它代表的应用范式文档输入 结构化世界建模 多智能体社会模拟 群体行为涌现 报告与交互分析这是一种很有潜力的 AI 应用方向。但当前阶段它不是一个开箱即用的生产级预测平台而是一个值得研究、值得改造、值得借鉴的多智能体数字沙盘。理解这一点部署路线就清楚了。不要被“Docker 部署”误导也不要被“预测万物”迷惑。MiroFish 的正确打开方式是先把它作为实验系统跑通再判断哪些模块值得吸收最后决定是否把它改造成自己可控的本地化推演平台。