需要本地模拟文档引发的舆论/市场情绪时，用 Neo4j +…

在本地环境用 Neo4j 图记忆和 Ollama LLM 从任意文档生成数百个智能体，逐小时模拟社交媒体反应、观点迁移并生成报告。

适用场景

解决思路

1. 推荐用 Docker 安装：git clone https://github.com/nikmcfly/MiroFish-Offline.git，cd MiroFish-Offline，cp .env.example .env，docker compose up -d，然后 docker exec mirofish-ollama ollama pull qwen2.5:32b 和 docker exec mirofish-ollama ollama pull nomic-embed-text，最后 docker compose ps 检查服务并打开 http://localhost:3000。
2. 手动安装 Neo4j：docker run -d --name neo4j -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/mirofish neo4j:5.15-community。
3. 手动安装 Ollama：ollama serve &，然后 ollama pull qwen2.5:32b、ollama pull qwen2.5:14b、ollama pull nomic-embed-text。
4. 手动安装后端：cp .env.example .env 并编辑 .env，cd backend，pip install -r requirements.txt，python run.py，后端监听 http://localhost:5000。
5. 手动安装前端：cd frontend，npm install，npm run dev，前端监听 http://localhost:3000。
6. 配置 .env 的 LLM 部分：LLM_API_KEY=ollama，LLM_BASE_URL=http://localhost:11434/v1，LLM_MODEL_NAME=qwen2.5:32b；配置 Neo4j：NEO4J_URI=bolt://localhost:7687，NEO4J_USER=neo4j，NEO4J_PASSWORD=mirofish；配置 Embeddings：EMBEDDING_MODEL=nomic-embed-text，EMBEDDING_BASE_URL=http://localhost:11434；可选换成任意 OpenAI-compatible provider。
7. 初始化 GraphStorage：从 backend.storage.base 导入 GraphStorage，从 backend.storage.neo4j_storage 导入 Neo4jStorage，用 Neo4jStorage 传入 uri、user、password、embedding_model、embedding_base_url、llm_base_url、llm_api_key、llm_model。
8. 从文档构建知识图谱：从 backend.services.graph_builder 导入 GraphBuilder，builder = GraphBuilder(storage=storage)，读取文档文本，调用 builder.build(content=document_text, title='Q4 Earnings Report', source_type='financial_report')，得到 graph_id。
9. 创建并运行模拟：从 backend.services.simulation 导入 SimulationService，sim = SimulationService(storage=storage)，调用 sim.create_environment(graph_id=graph_id, agent_count=200, simulation_hours=24, platform='twitter') 得到 sim_id，platform 可选 twitter、reddit、weibo，再调用 sim.run(sim_id=sim_id)，读取 result['post_count'] 和 result['sentiment_over_time']。
10. 查询模拟结果：从 backend.services.report 导入 ReportAgent，report_agent = ReportAgent(storage=storage)，调用 report_agent.generate(sim_id=sim_id, focus_group_size=10, include_graph_search=True)，读取 report['summary']、report['key_narratives']、report['sentiment_shift']、report['influential_agents']。
11. 与模拟智能体聊天：从 backend.services.agent_chat 导入 AgentChatService，chat = AgentChatService(storage=storage)，调用 chat.list_agents(sim_id=sim_id, limit=10) 取 agent_id，再调用 chat.send(agent_id=agent_id, message='Why did you post that criticism about the earnings report?')，读取 response['reply']。
12. 在知识图谱上做混合搜索：从 backend.services.search 导入 SearchService，search = SearchService(storage=storage)，调用 search.query(text='executive compensation controversy', graph_id=graph_id, top_k=5, vector_weight=0.7, bm25_weight=0.3)，读取每条结果的 entity、relationship、score。
13. 实现自定义 GraphStorage 后端：继承 GraphStorage 并实现 store_entity、store_relationship、vector_search、keyword_search、get_agent_memory、update_agent_memory，然后通过 Flask app.extensions['neo4j_storage'] = MyCustomStorage(...) 注册。
14. Flask 应用集成：在 create_app() 中创建 Neo4jStorage 实例并放入 app.extensions['neo4j_storage']，然后注册 graph_bp、simulation_bp、report_bp 蓝图。
15. 在 Flask 路由中访问存储：用 current_app.extensions['neo4j_storage'] 获取 storage，从 request.json 取 graph_id、agent_count、simulation_hours 等，创建 SimulationService 并调用 create_environment 和 run，返回 jsonify(result)。
16. 使用 REST API：POST /api/graph/build 上传文档并建图，GET /api/graph/:id 获取图实体和关系，POST /api/simulation/create 创建模拟环境，POST /api/simulation/run 执行模拟，GET /api/simulation/:id/results 获取帖子、情绪和指标，GET /api/simulation/:id/agents 列出智能体，POST /api/report/generate 生成报告，POST /api/agent/:id/chat 与智能体聊天，GET /api/search 做混合搜索；用 curl -X POST 并设置 Content-Type: application/json 访问这些端点。
17. 按硬件选择模型：快速测试/开发用 qwen2.5:7b（6GB VRAM、16GB RAM），平衡质量用 qwen2.5:14b（10GB VRAM、16GB RAM），生产质量用 qwen2.5:32b（24GB VRAM、32GB RAM），仅 CPU 用 qwen2.5:7b（无 VRAM、16GB RAM）；改 .env 的 LLM_MODEL_NAME 后重启后端即可切换。
18. 跑 PR 危机测试流水线：初始化 storage，定义 test_press_release(text)，用 GraphBuilder 建图，用 SimulationService 创建 agent_count=300、simulation_hours=48 的模拟并运行，用 ReportAgent.generate(focus_group_size=15) 生成报告，返回 sentiment_peak、key_narratives、risk_score、recommended_edits。
19. 换用任意 OpenAI-compatible provider：修改 .env 的 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_NAME，例如 Anthropic、OpenAI、Local LM Studio。
20. 排查 Neo4j 连接拒绝：运行 docker ps | grep neo4j、nc -zv localhost 7687、docker logs neo4j --tail 50。
21. 排查 Ollama 模型未找到：运行 ollama list、ollama pull qwen2.5:32b、ollama pull nomic-embed-text、curl http://localhost:11434/api/tags。
22. 排查显存不足：在 .env 设 LLM_MODEL_NAME=qwen2.5:14b 或 qwen2.5:7b，然后 cd backend && python run.py 重启后端。
23. 排查 Embedding 维度不匹配：nomic-embed-text 产生 768 维向量；换 embedding 模型后在 Neo4j browser 执行 DROP INDEX entity_embedding IF EXISTS;，再重启 MiroFish 重建索引。
24. 排查 Docker Ollama 容器无法访问 GPU：在 docker-compose.yml 的 ollama 服务下添加 deploy.resources.reservations.devices，driver: nvidia，count: 1，capabilities: [gpu]。
25. 优化 CPU 上模拟慢：使用 qwen2.5:7b，将 agent_count 降到 50–100，将 simulation_hours 降到 6–12；CPU 推理 7b 模型约 5–10 tokens/sec。
26. 排查前端连不上后端：检查 frontend/.env 的 VITE_API_BASE_URL=http://localhost:5000，并运行 curl http://localhost:5000/api/health。
27. 按项目结构定位文件：backend/run.py 是入口，backend/app.py 是 Flask factory 和 DI 装配，backend/storage/base.py 是 GraphStorage 抽象接口，backend/storage/neo4j_storage.py 是 Neo4j 实现，backend/services/ 下有 graph_builder.py、simulation.py、report.py、agent_chat.py、search.py，backend/routes/ 下有 graph.py、simulation.py、report.py，frontend 是 Vue 3 英文 UI，根目录有 docker-compose.yml、.env.example、README.md。

适用边界 · 注意事项

• 没有安装 Docker、Neo4j、Ollama，或无法在本地运行 LLM 时不要使用。
• 硬件资源不足（无 GPU、显存小于 6GB、内存小于 16GB）时不适合跑完整模拟，只能降级模型和规模。
• 需要高并发、生产级 SLA 或完全避免本地运维时，应改用托管服务。