graphragAI

KO | EN

gitlite — search

#llm #golang #machine-learning #rust #linux #docker #nodejs #java #windows #cli #awesome-list #security #mcp #open-source

(★ 14)

讓記憶成群結隊

graphragAI Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 讓記憶成群結隊：GraphRAG 銀行理專 AI 系統

**版本**: 1.4 👤 客戶畫像 + 📞 通訊紀錄 + 完整評估框架 + 真實財經新聞 + LLM 標籤
**技術棧**: OpenAI GPT-4o + Neo4j + Python 3.11 + LlamaIndex (規劃中)

## 專案目標

以 **GraphRAG** 架構打造客製化銀行理專 AI，透過「子圖檢索（圖拓撲 + 語義）」提升：
- ✅ 關聯度（Relevance）
- ✅ 人稱一致性（PersonaConsistency）
- ✅ 背景衝突率下降 ≥30%（vs 向量 RAG baseline）

支援兩大情境：
1. **新聞級問答**：快速事實查找
2. **長篇對話**：多輪上下文穩定性

## 快速啟動

```bash
# 1. 初始化環境
make setup
source .venv/bin/activate

# 2. 安裝套件
make install

# 3. 編輯 .env（填入 OPENAI_API_KEY、NEWSAPI_KEY）
vim .env

# 4. 啟動 Neo4j
make start

# 5. 執行 Demo（vector vs graph 對比）
make demo

# 6. 執行完整評估
make eval
```

## 環境變數設定

專案透過 `.env` 控制檢索與評估行為，`src/utils/config.py` 會在啟動時載入這些值。下表整理 `.env.sample` 中的核心參數與影響：

### 檢索參數 (`# Retrieval Configuration`)
| 變數 | 預設值 | 用途 |
| --- | --- | --- |
| `SUBGRAPH_HOP_LIMIT` | `2` | 控制子圖檢索的 r-hop 範圍；數值越大，拓撲擴散越廣。 |
| `VECTOR_TOP_K` | `10` | 指定向量檢索階段保留的候選數量，供後續合併與重排。 |
| `RERANK_TOP_K` | `5` | 合併後進入重排的文段上限；適度降低可減少回覆篇幅。 |
| `ALPHA_TYPE_WEIGHT` | `0.3` | 邊權重中的類型分量 α，對應 `α*type + β*semantic + γ*topo`。 |
| `BETA_SEMANTIC_WEIGHT` | `0.4` | 邊權重中的語義分量 β。 |
| `GAMMA_TOPO_WEIGHT` | `0.3` | 邊權重中的拓撲分量 γ。 |

### 評估參數 (`# Evaluation`)
| 變數 | 預設值 | 用途 |
| --- | --- | --- |
| `EVAL_SCENARIOS` | `news,conversation` | 控制 Demo 與評估時載入的情境標籤，依序對應新聞與長篇對話用例。 |
| `MIN_PERSONA_CONSISTENCY` | `0.85` | Persona 一致性通過門檻；預設與 `src/eval/metrics.py`、`src/eval/run_evaluation.py` 中的閾值一致。 |
| `TARGET_CONFLICT_REDUCTION` | `0.30` | 目標背景衝突率下降幅度（相對向量基準）；用於評估報告的成功條件說明。 |

> 若需要調整評估門檻，請同步更新 `.env` 以及 `src/eval/run_evaluation.py` 中的對應變數，或依需求修改 `GoldenAnswer` 設定，確保報告敘述與實際判斷標準一致。

## 目錄結構

```
記憶成群結隊/
├── data/
│   ├── raw/              # 原始資料（對話 + 新聞 + 通訊紀錄 + 客戶畫像，可用真實來源覆寫）
│   ├── processed/        # ETL 後資料
│   ├── graphs/           # KG 快照（版本化）
│   └── indexes/          # 向量索引
├── src/
│   ├── etl/              # ETL pipeline
│   ├── kg/               # KG 建構與寫入
│   ├── retrieval/        # 子圖檢索 + 向量 RAG
│   ├── eval/             # 評估框架
│   └── utils/            # 工具函式
├── config/               # Schema 與配置
├── tests/                # 測試案例
├── reports/              # 評估報告
├── notebooks/            # Jupyter 分析
├── docker-compose.yml    # Neo4j 容器
├── Makefile              # 指令集
└── README.md
```

## 資料模型

### 節點類型（支援多標籤 ✨）
- **Person**: `{name, role[客戶/理專], persona_tags?, custom_labels[]}`
  - LLM 標籤範例：`資深理專`, `高資產客戶`, `風險評估專家`
- **Event**: `{type[詢問/推薦/交易/揭露], topic, amount?, product?, custom_labels[]}`
  - LLM 標籤範例：`客戶不滿`, `資產配置建議`, `投資決策`
- **Communication** 📞 (v1.4+): `{comm_id, type[電話/Email/...], direction, duration?, subject?, summary, sentiment_score, sentiment_label, key_points[], action_items[], completed}`
  - 補齊電話錄音、Email 等聯繫紀錄並內建情緒分析
- **ClientProfile** 👤 (v1.4+): `{client_id, name, age_range, risk_tolerance, investment_experience, asset_range, investment_goals[], preferred_products[], life_events[], occupation}`
  - 個性化推薦、風險管理、人生事件追蹤
- **Time**: `{ts, granularity}`
- **Location**: `{branch?, region?}`
- **Emotion**: `{polarity, intensity}`
- **Doc**: `{doc_id, title, source, spans[]}`

### 邊類型（含權重）
- `INTERACTS_WITH`, `MENTIONS`, `OCCURS_AT`, `ABOUT`, `FEELS`, `BEFORE`, `AFTER`
- `HAS_PROFILE` 👤 (v1.4+): Person → ClientProfile 客戶畫像連結
- `INITIATED_BY` / `RECEIVED_BY` 📞 (v1.4+): Communication 與 Person 的發起/接收關係
- **權重計算**: `final_edge = α*type + β*semantic + γ*topo`

### 資料來源選項
- **合成資料**：`data/generate_synthetic_data.py`（預設 100 對話 + 30 新聞 + 50 通訊紀錄 📞 + 客戶畫像 👤）
- **真實新聞**：`scripts/fetch_financial_news.py` 透過 NewsAPI 拉取即時財經新聞，覆寫 `data/raw/news.json`

```bash
# 下載 30 則財經新聞並覆寫 data/raw/news.json
uv run python scripts/fetch_financial_news.py --page-size 30

# 需要更多合成新聞，可調整參數，例如 100 篇：
uv run python data/generate_synthetic_data.py --news 100

# 調整通訊紀錄筆數或僅產生 Email/電話：
uv run python data/generate_synthetic_data.py --phone-communications 60 --email-communications 40
```

⚠️ 請確認 `.env` 或命令列提供 `NEWSAPI_KEY`，並遵守各新聞來源的使用條款。

### LLM 動態標籤 ✨
- 使用 OpenAI GPT-4o-mini，僅從受控詞彙（15 個人物類別 / 20 個事件類別）中挑選最貼切標籤
- 成本極低：處理 130 個文件僅需 ~$0.025 USD
- 支援標籤查詢：`MATCH (p:資深理專) RETURN p`
- 內建標籤收斂：相近詞彙自動整併，確保圖譜標籤乾淨一致
- 角色與事件類型映射可在 `config/llm_normalization.yaml` 自行擴充，無需修改程式

## 子圖檢索流程

1. **解析查詢** → 抽 seed nodes（人/事/時/地/情緒）
2. **r-hop 圈選** + 社群邊界 + `BEFORE`/`AFTER` 時序篩選
3. **候選集合** = 子圖文段 ∪ 向量 TopK
4. **交叉重排** → 合成回覆 + 證據鏈（doc_id + node/edge 路徑）

## 評估指標

| 指標 | 目標 | 說明 |
|------|------|------|
| **Relevance@K** | > baseline | 檢索相關性 |
| **PersonaConsistency** | ≥0.85 | 人稱與角色一致性 |
| **BackgroundConflictRate** | ↓≥30% | 背景矛盾比率下降 |
| **Latency** | < 2s | 端到端回應時間 |

## 合規與證據鏈 ⚠️

- ❌ **嚴格禁止杜撰**：所有回覆必須基於實際資料，無證據時明確表示「不知道」
  - 自然語言查詢工具強制執行證據導向回答（v1.2.1+）
  - 空結果時自動回應「資料庫中沒有找到相關記錄」
  - 禁止臆測性詞彙：「可能」、「應該」、「據推測」
  - 每個回應附加資料來源說明

- ✅ **證據鏈格式**：`[doc_id: XXX] → [Person:王小明] -INTERACTS_WITH-> [Event:基金推薦]`

- 🔒 **版本化**：`/data/graphs/v1`, `/data/graphs/v2`...

## 增量更新

```bash
# 新增資料後執行
python src/kg/incremental_update.py --version v2
```

## 開發指令

```bash
make demo      # 圖檢索 vs 向量 baseline Demo
make eval      # 圖結構評估（輸出 reports/graphrag_evaluation_report_*.json）
make eval-nl   # 自然語言 RAG 評估（需 OPENAI_API_KEY，輸出 reports/nl_rag_evaluation_report_*.json）
make test      # 執行測試
make clean     # 清理資料與容器
make stop      # 停止 Neo4j
./verify_setup.sh  # 快速檢查依賴、資料與 Neo4j 狀態（選用）

# LLM 標籤相關 ✨
uv run python scripts/etl_with_llm_sample.py  # LLM ETL（測試版）
uv run python scripts/verify_labels.py         # 驗證標籤
uv run python scripts/nl_neo4j_chat.py         # 理專自然語言查詢 Neo4j
uv run python scripts/fetch_financial_news.py  # 下載真實財經新聞
uv run python scripts/test_client_profiles.py  # 客戶畫像驗證
uv run python scripts/test_communication_records.py  # 通訊紀錄驗證
```

## 完整文檔

- 📚 [快速開始 (QUICKSTART.md)](QUICKSTART.md)
- 🏷️ [LLM 標籤提取指南 (docs/LLM_LABEL_EXTRACTION.md)](docs/LLM_LABEL_EXTRACTION.md)
- 🔍 [Cypher 查詢範例 (CHEATSHEET.md)](CHEATSHEET.md)
- 🏗️ [專案架構 (CLAUDE.md)](CLAUDE.md)
- 📝 [更新日誌 (CHANGELOG.md)](CHANGELOG.md)

## 開發貢獻

⚠️ **重要**：所有程式碼變更都必須同步更新文檔並提交到 GitHub。

詳細開發規範請參閱 [CLAUDE.md - Development Workflow & Git Policy](CLAUDE.md#development-workflow--git-policy)

## 授權

本專案為教學與研究用途。請遵守 LlamaIndex、Neo4j 與 OpenAI 使用條款。

---
**作者**: GraphRAG 團隊
**聯絡**: [您的聯絡方式]

graphragAI

graphragAI Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

graphragAI

graphragAI Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README