From 3bdaeaf5e7a54781fa5606740640123f6c2f57ab Mon Sep 17 00:00:00 2001 From: liyizhouAI Date: Thu, 16 Apr 2026 13:00:13 +0800 Subject: [PATCH] docs: v0.3.3 - PRD rewrite + Graphiti deprecation record + deploy guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PRD.md: - Version bumped to v0.3.3 - Architecture diagram: Graphiti → CustomGraphBuilder - v0.3.3 changelog: CustomGraphBuilder, deploy.sh, CDN SPA fix, COS deploy - Infrastructure decisions table updated - Decision log: 4 new entries for 2026-04-16 - Appendix C: Full Graphiti deprecation record (10 patch attempts, why self-built) - Appendix D: Complete deployment workflow (backend/frontend/CDN/COS) README.md / README-ZH.md: - Step 1 description updated: Graphiti → custom builder with 10x concurrency --- PRD.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++--- README-ZH.md | 2 +- README.md | 2 +- 3 files changed, 134 insertions(+), 8 deletions(-) diff --git a/PRD.md b/PRD.md index 51905f43..94a033e4 100644 --- a/PRD.md +++ b/PRD.md @@ -1,6 +1,6 @@ # Foresight 先见之明 — 产品需求文档 (PRD) -> **版本**：v0.3.1 — 2026-04-15 生产链路打通 +> **版本**：v0.3.3 — 2026-04-16 CustomGraphBuilder + 一键部署 + CDN SPA 修复 > **基线**：基于 [MiroFish](https://github.com/666ghj/MiroFish) v0.1.2 二次开发，已大量重构。 --- @@ -77,10 +77,10 @@ │ 用途：本体、画像、配置、报告、模拟决策 │ Endpoint：https://open.bigmodel.cn/api/paas/v4/ │ - ├── Knowledge Graph：Graphiti + Neo4j （之前用 Zep Cloud，已弃） + ├── Knowledge Graph：CustomGraphBuilder + Neo4j（v0.3.2 替代 Graphiti） │ 部署：Docker 容器 neo4j:5.26-community - │ Embedding：BAAI/bge-m3 via SiliconFlow - │ Graphiti LLM：Qwen2.5-32B via SiliconFlow + │ 图谱构建 LLM：GLM-4-Flash（同主 LLM，自带 retry + fallback） + │ Embedding：BAAI/bge-m3 via SiliconFlow（仅下游检索用） │ ├── HF Hub Mirror：hf-mirror.com OASIS 推荐模型 twhin-bert-base │ @@ -93,8 +93,9 @@ | 决策点 | 当前选择 | 弃用方案 | 原因 | |---|---|---|---| -| LLM | 智谱 GLM-4-Flash | MiniMax M2.7 / GPT-4o-mini | Flash 单次延迟 0.5-1s，是 OASIS 高吞吐场景的最优解 | -| 知识图谱 | Graphiti + 自托管 Neo4j | Zep Cloud | 摆脱外部依赖、可控、免月费 | +| LLM | 智谱 GLM-4-Flash | MiniMax M2.7 / GPT-4o-mini | Flash 单次延迟 0.5-1s，128K context | +| 图谱构建 | **CustomGraphBuilder**（自研） | Graphiti + Qwen/GLM | Graphiti 与非 OpenAI LLM 兼容性黑洞（详见附录 C） | +| 知识图谱存储 | 自托管 Neo4j | Zep Cloud | 摆脱外部依赖、可控、免月费 | | Python | 3.11（uv 管理） | 系统 3.12 | camel-oasis<3.12 不兼容 3.12 | | 包源 | 腾讯云 PyPI 镜像 | 直连 PyPI | 国内服务器直连慢 100x | | HF 模型源 | hf-mirror.com | huggingface.co | 国内服务器连不上 hf 主站 | @@ -449,6 +450,39 @@ FLASK_DEBUG=False ## 8. v0.3 当前状态与已交付 +### v0.3.3（2026-04-16 CustomGraphBuilder + 一键部署 + CDN 修复） + +- [x] **CustomGraphBuilder 替代 Graphiti**（v0.3.2 核心交付） + - 完全自研的图谱构建器，不依赖 graphiti-core 库 + - 每 chunk 单次 LLM 调用（Graphiti 需要 4-5 次）→ 速度 4-5x + - ThreadPoolExecutor 10 并发 → 194 chunks 从 10 分钟降到 ~2 分钟 + - 直接用 cypher MERGE 写 Neo4j → 无 Graphiti 嵌套 dict / context overflow 等兼容性问题 + - 使用 Foresight LLMClient 自带 retry + fallback + token tracker + - 下游 `get_all_nodes / get_all_edges / filter_defined_entities` 完全兼容 + - 文件：`backend/app/services/custom_graph_builder.py` + +- [x] **一键部署脚本** `scripts/deploy.sh` + - `--backend`：rsync → 语法检查 → kill/restart Flask → health verify + - `--frontend`：vite build → coscmd upload → tccli CDN purge + - `--full`：两个都做 + - `--dry-run`：预演 + - 处理路径空格 / sudo rsync / Flask 存活检查 + +- [x] **CDN SPA 路由 fallback** + - 问题：Vue Router history 模式，COS 上子路径全部 404 + - 修复：`tccli cdn UpdateDomainConfig` 设置 404 → 302 跳转 `/index.html` + - 永久配置，deploy.sh 不需要每次重新设 + +- [x] **前端首次正式部署到腾讯云 COS** + - `coscmd upload -r dist/ /` → bucket `foresight-1317962478` + - CDN purge → `tccli cdn PurgePathCache` + - 包含 v0.3 所有前端改动（replay UI / 加速完成按钮 / 路由修复） + +- [x] **Graphiti 兼容层保留** + - graphiti_client.py 中的 5 层 monkey-patch 保留（driver / reranker / embedder / EntityNode / bulk_utils） + - 这些只影响旧 Graphiti 代码路径（add_episode / add_episodes_batch） + - 新 CustomGraphBuilder 完全绕过，不受影响 + ### v0.3.1 hotfix（2026-04-15 生产链路打通） 经过一次完整的端到端测试，修复了 7 个阻塞生产跑通的 bug： @@ -606,7 +640,99 @@ FLASK_DEBUG=False | 2026-04-15 | 200 agents 设为甜点 | 8G 容量 + 95% 置信度足够 | | 2026-04-15 | 上线 Manus 式 replay UI | 给客户演示 + 复盘工具 | | 2026-04-15 | v0.4 路线图：国内平台 + SaaS | 用户战略需求 | +| 2026-04-16 | v0.3.3 CustomGraphBuilder 替代 Graphiti | Graphiti 兼容性死循环，10+ 次 patch 仍无法稳定 | +| 2026-04-16 | 一键部署脚本 deploy.sh | 手动 scp 反复漏文件，accelerate 方法都没部署上 | +| 2026-04-16 | CDN SPA fallback 404→302 | coscmd 部署后前端所有子路由 404 | +| 2026-04-16 | 图谱构建并发化 (10 workers) | 串行太慢（10 分钟 → 2 分钟） | | 2026-04-15 | v0.3.1 hotfix：7 个 bug 修复 | 第一次完整 E2E 跑通压力测试 | | 2026-04-15 | LLM client 加指数退避重试 + 双 LLM fallback | GLM RPM 配额低，retry 不够兜底 | | 2026-04-15 | Replay UI 重构为 Manus cinematic 风格 | 三栏分析面板对客户演示不够"沉浸" | | 2026-04-15 | semaphore 100 → 30 | 高并发触发 GLM 限流雪崩 | + +## 附录 C：Graphiti 弃用记录 + +v0.3.2 决定用自研 CustomGraphBuilder 替代 Graphiti。以下是尝试修复 Graphiti 兼容性的完整过程。 + +### 尝试过的 10 次 Patch + +| # | 问题 | Patch 位置 | 结果 | +|---|---|---|---| +| 1 | Qwen 32B 32K context 超窗口 | ontology_generator MAX_TEXT=28000 | ✅ 但这不是主问题 | +| 2 | Neo4j TypeError 嵌套 dict | EntityNode.save monkey-patch | ❌ Graphiti 不走这条路径 | +| 3 | 同上 | bulk_utils.add_nodes_and_edges_bulk_tx | ❌ 也不走这条路径 | +| 4 | 同上 | neo4j AsyncSession.run driver 层 | ✅ 终于拦到了 | +| 5 | Qwen 累积上下文爆 60-82K | chunk_size 500→250 | ❌ 爆的是检索上下文不是 chunk | +| 6 | 同上 | 换 Qwen 72B（以为 128K） | ❌ SiliconFlow 72B 也是 32K | +| 7 | 同上 | 换智谱 GLM-4-Flash 128K | ❌ GLM 20015 "parameter invalid" | +| 8 | GLM reranker logprobs 不支持 | patch reranker.rank() | ✅ 但不是主路径 | +| 9 | GLM embedder 空 input | patch embedder.create_batch() | ✅ 但不是主路径 | +| 10 | GLM extract_nodes 全部 fail | 未找到根因 | ❌ 直接测能过、生产必挂 | + +### 为什么自研是正确决策 + +1. **Graphiti 为 OpenAI 设计**：内部 4-5 次 LLM 调用路径各自有 OpenAI 特有参数（logprobs / structured output / json_schema），非 OpenAI provider 每条路径都是独立陷阱 +2. **patch 层次太深**：至少 5 层（EntityNode / bulk_utils / driver / reranker / embedder），每层 fix 一个又冒下一个 +3. **上下文累积不可控**：Graphiti 的 episode 检索机制会从已有图谱拉上下文，后续 episode prompt 越来越长，32K 模型必爆，128K 模型也不是免费的 +4. **每 chunk 4-5 次 LLM 调用**：extract_nodes + dedupe_nodes + extract_edges + dedupe_edges + community_summary，成本和延迟 4-5x +5. **CustomGraphBuilder 只需 1 次调用/chunk**：直接 prompt → JSON → cypher MERGE，完全受控 + +### CustomGraphBuilder 架构 + +``` +输入: 完整文档文本 + ontology 定义 + ↓ +字符级切分 (250 chars, 50 overlap) + ↓ +ThreadPoolExecutor (10 workers 并发) + ↓ 每个 worker: + LLMClient.chat_json(extract prompt) ← 一次调用，自带 retry + fallback + ↓ 返回: + {"entities": [...], "relationships": [...]} + ↓ +串行 MERGE 到 Neo4j (去重 by name + group_id) + ↓ +输出: {entities_count, edges_count, chunks_processed} +``` + +### 保留的 Graphiti 代码 + +`graphiti_client.py` 中的读取方法（`get_all_nodes / get_all_edges / get_node / get_node_edges`）仍然使用 Neo4j 直接查询，**不依赖 Graphiti 库**。`add_episode / add_episodes_batch` 保留但不再被主流水线调用。5 层 monkey-patch 保留作为安全网。 + +## 附录 D：部署流程 + +### 后端部署（最常用） + +```bash +./scripts/deploy.sh # rsync + restart Flask + health verify +./scripts/deploy.sh --no-restart # 只同步代码不重启 +``` + +### 前端部署 + +```bash +./scripts/deploy.sh --frontend # vite build + coscmd upload + CDN purge +``` + +### 全量部署 + +```bash +./scripts/deploy.sh --full # 后端 + 前端 +``` + +### CDN SPA 配置（一次性） + +```bash +tccli cdn UpdateDomainConfig --cli-unfold-argument \ + --Domain foresight.yizhou.chat \ + --ErrorPage.Switch on \ + --ErrorPage.PageRules.0.StatusCode 404 \ + --ErrorPage.PageRules.0.RedirectCode 302 \ + --ErrorPage.PageRules.0.RedirectUrl "https://foresight.yizhou.chat/index.html" +``` + +### COS 配置 + +- Bucket: `foresight-1317962478` +- Region: `ap-guangzhou` +- 凭证: `~/.cos.conf`（SecretId/SecretKey） +- 工具: `coscmd`（pip install） diff --git a/README-ZH.md b/README-ZH.md index ea2770cd..03353851 100644 --- a/README-ZH.md +++ b/README-ZH.md @@ -85,7 +85,7 @@ Foresight 致力于打造映射现实的群体智能镜像，通过捕捉个体 ## 🔄 工作流程 -1. **图谱构建**：现实种子提取 & 个体与群体记忆注入 & GraphRAG（Graphiti + Neo4j）构建 +1. **图谱构建**：现实种子提取 & LLM 实体/关系抽取 & Neo4j 存储（v0.3.2 自研 CustomGraphBuilder，10 并发，替代 Graphiti） 2. **环境搭建**：实体关系抽取 & 人设生成 & 环境配置Agent注入仿真参数（支持「加速完成」按钮） 3. **开始模拟**：双平台并行模拟（Twitter + Reddit） & 自动解析预测需求 & 动态更新时序记忆 4. **报告生成**：ReportAgent 拥有丰富的工具集与模拟后环境进行深度交互 diff --git a/README.md b/README.md index b498c730..11e7d9c9 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ Click the image to watch Foresight's deep prediction of the lost ending based on ## 🔄 Workflow -1. **Graph Building**: Seed extraction & Individual/collective memory injection & GraphRAG construction (Graphiti + Neo4j) +1. **Graph Building**: Seed extraction & LLM entity/relationship extraction & Neo4j storage (v0.3.2 custom builder with 10x concurrent extraction, replacing Graphiti) 2. **Environment Setup**: Entity relationship extraction & Persona generation & Agent configuration injection (with "Skip & Continue" button) 3. **Simulation**: Dual-platform parallel simulation (Twitter + Reddit) & Auto-parse prediction requirements & Dynamic temporal memory updates 4. **Report Generation**: ReportAgent with rich toolset for deep interaction with post-simulation environment