# Embedding 跨機器部署方案 v1.0.0

## 分工原則

```
M5（Pipeline + 主力 Embedding）        M4（Portal + Fallback Embedding）
├── 批量 vectorize（1709 chunks）        ├── Portal search query embedding
├── EmbeddingGemma 主 server             ├── 備援 embed server
├── 模型已上線（port 11436）              └── 預設呼叫 M5 API
└── 出門 demo 可離線運作
```

## 部署架構

```
Portal Search Query
       │
       ▼
  ┌─────────────┐    成功     ┌──────────────────┐
  │ M4 Portal   │ ──────────→ │ M5:11436         │
  │ embed       │             │ EmbeddingGemma   │
  │ client      │             │ (主力)           │
  │             │    失敗     └──────────────────┘
  │ retry       │ ──────────→ ┌──────────────────┐
  │ fallback    │             │ M4:11436         │
  └─────────────┘             │ EmbeddingGemma   │
                              │ (備援)           │
                              └──────────────────┘
```

## M4 安裝步驟

```bash
# 1. 安裝 Python 依賴
pip install torch transformers flask

# 2. 登入 HuggingFace（需接受授權）
open https://huggingface.co/google/embeddinggemma-300m
huggingface-cli login --token YOUR_TOKEN

# 3. 取得 script
rsync -av accusys@192.168.110.201:/Users/accusys/momentry_core_0.1/scripts/embeddinggemma_server.py \
       ./scripts/embeddinggemma_server.py

# 4. 啟動備援 server
python3 scripts/embeddinggemma_server.py --port 11436
```

## Portal Embed Client

```javascript
async function embedQuery(text) {
  const servers = [
    'http://192.168.110.201:11436/v1/embeddings',  // M5 主力
    'http://localhost:11436/v1/embeddings',          // M4 備援
  ];
  for (const url of servers) {
    try {
      const res = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ input: text }),
      });
      const data = await res.json();
      return data.data[0].embedding;
    } catch (e) {
      continue;  // 下一台
    }
  }
  throw new Error('Embedding servers unreachable');
}
```

## 模型一致性

| 項目 | M5 | M4 |
|------|-----|-----|
| 模型 | EmbeddingGemma 300M | EmbeddingGemma 300M |
| 維度 | 768D | 768D |
| Server | Python MPS (port 11436) | Python CPU/MPS (port 11436) |
| Qdrant | 192.168.110.201:6333 | 192.168.110.201:6333 |

兩台使用同一模型、同一維度，確保 query embedding 與索引 embedding 可比對。
