blog-embedding/README.md

# Blog Embedding Tools

Docusaurus blog 文章的 embedding 產生 + 相似度查詢。用 Ollama 本地跑，不吃外部 API。

## 前置

```bash
# 系統
brew install fzf        # macOS，Linux 用 apt install fzf

# Ollama
ollama pull qwen3-embedding:8b

# Python
pip install pyyaml requests numpy iterfzf
```

## 檔案說明

| 檔案 | 用途 |
|---|---|
| `blog_embeddings.py` | 掃描 blog 資料夾，為每篇文章產生 embedding，存成 JSON |
| `blog_similarity.py` | 讀取 JSON，模糊搜尋選一篇文章，列出最相似 / 最不相似的文章 |
| `blog_embeddings.json` | 輸出的資料檔（自動產生，記得加進 `.gitignore`） |

## 使用

### 1. 產生 embedding

先到 `blog_embeddings.py` 改 `BLOG_DIR` 指向你的 blog 路徑，然後：

```bash
# 增量模式（預設）：只跑新文章或改過的文章
python blog_embeddings.py

# 全部重跑
python blog_embeddings.py --full
```

### 2. 查相似度

```bash
python blog_similarity.py
```

會跳出 fzf 模糊搜尋，打字過濾、上下鍵選文章，選完印出結果。

## JSON 結構

```json
{
  "slug": "/my-post",
  "title": "文章標題",
  "file": "./blog/2024-01-01/index.md",
  "hash": "sha256...",
  "embedding": [0.012, -0.034, ...]
}
```

`hash` 是檔案內容的 SHA-256，增量模式靠它判斷文章有沒有改過。

## 備註

- Embedding model 用的是 `qwen3-embedding:8b`，中文表現很好
- 文章的 frontmatter 必須有 `slug` 才會被處理，沒有的會跳過
- 不會動到任何原始 blog 檔案