跳到主要內容

【2026 最新】UMAP 0.6 教學:繁中筆記向量怎麼畫成地圖?六步檢查群集與升級差異

最後更新: ·
UMAP 0.6 教學:繁中筆記向量地圖的群集判讀與近鄰檢查

你把幾十篇繁中筆記畫成一張點點地圖,咖啡在左邊、跑步在右邊,中間還浮著幾個孤島。這些島真的代表不同主題嗎?這篇 UMAP 0.6 教學,帶你把「圖很漂亮」往前推一步:點回原文,核對原始向量的鄰居,再判斷該整理哪一筆。

本文寫給第一次接觸降維、願意複製 Python 程式的讀者。你會完成一個 CPU 小型檢查流程:保留筆記 ID、固定向量,比較相容配置與新配置,匯出可點選的 HTML 和參數紀錄。起步使用 24 筆原創假筆記與字面向量;已有語意 Embedding 的人,可以換成自己的固定檔案。

以下依 2026 年 11 月 16 日查閱的官方文件與 0.6.0 原始碼整理,採文件導向教學;本機未完成 UMAP 執行,因此不列 AlphaLab 耗時成績。程式產生的秒數與近鄰紀錄,留給你在自己的環境驗收。

先說結論:UMAP 地圖=向量鄰近關係的二維草圖

地圖幫你找問題,原文幫你判答案。UMAP 是降維方法:把原本有很多欄數字的資料,安排到較少維度,這裡用兩個座標方便看。Embedding(嵌入向量)則是上游把文字轉成數字表示的結果;兩者負責不同工作。

  • 先固定同一份輸入,再比較 UMAP 設定;否則連筆記表示都變了。
  • 兩團點、孤島或緊密小球,都先當成待核對線索;回查來源 ID 與原始近鄰。
  • UMAP 0.6 的相容配置與新配置要明寫;升級套件,不代表已切換新流程。

一、UMAP 0.6 教學先認三個零件:筆記、向量、地圖

把筆記庫想成一間圖書館。原文是書,向量像每本書的一張數字卡片,UMAP 則像替卡片排一張桌面座位圖。卡片把什麼視為相近,先由上游表示與距離規則決定;桌面上的安排又會壓縮資訊,所以要保留一條走回書架的路。

依 官方原理說明,實作上的核心是先建立帶權重的近鄰圖,再尋找低維度配置。近鄰圖像「誰跟誰關係比較近」的連線清單;初始化是先擺一個起點;配置最佳化再反覆調整座位。換句話說,最後的點位同時受到輸入、距離與配置方法影響。

它適合協助找疑似重複、切段不自然、跨主題筆記,以及值得人工抽查的區域。若你現在要解決的是「問一句話,找哪些文件」,先讀 BM25、Embedding 與混合搜尋;本篇接的是資料進庫前的探索檢查。

UMAP 0.6 教學:保留來源、固定向量、畫圖與回查原文的四步檢查流程
流程示意,非實際降維結果:地圖上的每個可疑點,都要能回到同一筆原文。

二、第一、二步:準備環境,再鎖住來源與向量

第 1 步:「先裝哪個?」使用獨立環境與指定版本

以下指令用於已有 Python 3.11 的 macOS/Linux 終端機。先建立空資料夾,再複製執行;在這個資料夾內建立下面兩個程式檔。套件名稱是 umap-learn,Python 裡匯入的是 umap。PyPI 的 0.6.0 發布頁可核對版本與相依條件。

mkdir umap-notes-demo
cd umap-notes-demo
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install "umap-learn==0.6.0" plotly
python -m pip freeze > requirements.lock.txt

驗收方式是執行 python -c "import importlib.metadata as m; print(m.version('umap-learn'))",確認輸出 0.6.0。鎖版檔記下這次解析出的相依套件;日後重建環境,可用 python -m pip install -r requirements.lock.txt,同時保留 Python、作業系統與硬體紀錄。

第 2 步:「還沒有 Embedding?」先用字面向量跑通管線

把下面存成 starter.py。它用 字元 TF-IDF把兩字、三字片段轉成特徵,方便觀察有共同用字的筆記。這是字面向量熱身版,並非語意 Embedding 模型。它可以教你檢查資料與畫圖,不能用來判定某個語意模型是否理解繁中同義句。

import json, hashlib
from pathlib import Path
from sklearn.feature_extraction.text import TfidfVectorizer
import numpy as np

# Original fictional notes: lexical practice, not a semantic embedding model.
texts = [
    '咖啡研磨太細,手沖流速會變慢。',
    '手沖咖啡先固定水溫,再調整研磨粗細。',
    '咖啡粉量固定,記錄水量與萃取時間。',
    '淺焙咖啡酸味明顯,先記下沖煮參數。',
    '咖啡豆密封保存,避免潮濕與日照。',
    '手沖濾杯不同,注水方式也要記錄。',
    '跑步先慢走暖身,再開始輕鬆跑。',
    '跑步訓練記錄距離、時間與感受。',
    '長跑補水先練習,避免比賽臨時更換。',
    '跑鞋是否合腳,要看腳趾空間與摩擦。',
    '跑步後安排恢復日,觀察疲勞感受。',
    '跑步配速先維持穩定,再延長距離。',
    '程式版本更新前,先備份設定檔。',
    '程式測試失敗,先保存輸入與錯誤訊息。',
    '資料備份應定期練習還原流程。',
    '程式修改一次一項,方便定位問題。',
    '資料檔案附上版本與雜湊,方便核對。',
    '程式輸出保留來源識別碼,方便回查。',
    '手沖咖啡先固定水溫,再調整研磨粗細。',
    '手沖咖啡先固定水溫,再微調研磨粗細。',
    '跑步訓練記錄距離、時間與感受。',
    '咖啡沖煮紀錄也可以寫成程式整理。',
    '用程式整理每週跑步距離與恢復紀錄。',
    '筆記裡的咖啡與跑步,可以共用資料備份流程。',
]
rows = [{'id': f'n{i+1:02d}', 'text': t} for i, t in enumerate(texts)]
vec = TfidfVectorizer(analyzer='char', ngram_range=(2, 3))
X = vec.fit_transform(texts).toarray().astype('float32')
Path('notes.json').write_text(json.dumps(rows, ensure_ascii=False), encoding='utf-8')
np.save('vectors.npy', X)
Path('vectors.ids.json').write_text(json.dumps([r['id'] for r in rows]))
record = {
    'vector_kind': 'character-tfidf-not-semantic-embedding',
    'encoder': 'TfidfVectorizer', 'analyzer': 'char', 'ngram_range': [2, 3],
    'files': {f: hashlib.sha256(Path(f).read_bytes()).hexdigest()
              for f in ['notes.json', 'vectors.npy', 'vectors.ids.json']},
}
Path('input_record.json').write_text(json.dumps(record, indent=2))
print('Created 24 fictional notes and frozen lexical vectors.')

執行 python starter.py 後,應出現 notes.json、vectors.npy、vectors.ids.json 與 input_record.json。它們分別保留原文、向量、向量列的 ID 順序,以及輸入雜湊和轉換方式。行數相同還不夠,列的身分與順序也要相同。

換成自己的語意 Embedding 時,從同一次匯出產生原文、向量和 ID 清單;將輸入紀錄中的 vector_kind、模型完整名稱、revision、文字前處理、截斷規則及向量維度一併寫好,再重算檔案雜湊。不要在每次改 UMAP 參數時重新編碼。已有索引的人,可接著讀 Encoder 分流與增量索引教學,先確定輸出的表示一致。

三、第三、四步:UMAP 0.6 教學實作,畫圖並保留驗收紀錄

第 3 步:「舊圖要保留,還是試新流程?」把配置寫清楚

0.6.0 於 2026 年 11 月 10 日發布。依 官方 optimizer 文件,0.6 預設仍走相容配置;我們把兩條路都明寫:compatibility_layout=True 搭配 spectral 與 compatibility,以及 False 搭配 recursive 與 adam。Momentum 也是新增選項,本篇先用 Adam 建立一條新配置基準。

這是同一個 0.6.0 套件內,兩套流程的比較,不是安裝兩個版本做直接競速。相容開關涵蓋的範圍比最後的最佳化器廣;若要只測 optimizer,就另做固定近鄰圖與相同初始座標的控制實驗。為了看清流程,下列練習先把執行緒固定為一條。

第 4 步:「圖做完怎麼查?」輸出可點選 HTML 與近鄰清單

把以下存成 map_notes.py,接著執行 python map_notes.py。也可以把兩個程式依序放進 Notebook;先把第二個程式最前面的執行緒設定移到 Notebook 第一格,再重啟核心依序執行,讓設定早於 NumPy/Numba 匯入。範例為了直接計算成對距離,將輸入限制在 16~2,000 筆;大型資料要另外設計抽樣與近鄰搜尋。

import os
# Set before importing NumPy / Numba. This is a controlled single-thread exercise.
for key in ['NUMBA_NUM_THREADS', 'OMP_NUM_THREADS',
            'OPENBLAS_NUM_THREADS', 'MKL_NUM_THREADS', 'VECLIB_MAXIMUM_THREADS']:
    os.environ[key] = '1'
import json, hashlib, time, statistics, platform, importlib.metadata as md
import cProfile, pstats
from pathlib import Path
import numpy as np
import umap
import plotly.graph_objects as go
from sklearn.metrics import pairwise_distances

assert md.version('umap-learn') == '0.6.0', 'Use the pinned tutorial version.'
rows = json.loads(Path('notes.json').read_text(encoding='utf-8'))
X = np.load('vectors.npy', allow_pickle=False)
ids = [r['id'] for r in rows]
assert ids == json.loads(Path('vectors.ids.json').read_text())
assert len(set(ids)) == len(ids)
assert X.ndim == 2 and len(X) == len(rows) and 16 <= len(X) <= 2000
assert np.isfinite(X).all() and (np.linalg.norm(X, axis=1) > 0).all()
X = np.ascontiguousarray(X, dtype=np.float32)
out = Path('results'); out.mkdir(exist_ok=True)
record = {
    'platform': platform.platform(), 'python': platform.python_version(),
    'versions': {p: md.version(p) for p in
                 ['umap-learn','numpy','scipy','scikit-learn','numba','pynndescent','plotly']},
    'threads': {k: os.environ[k] for k in os.environ if k.endswith('NUM_THREADS')
                or k == 'VECLIB_MAXIMUM_THREADS'},
    'inputs': {f: hashlib.sha256(Path(f).read_bytes()).hexdigest()
               for f in ['notes.json','vectors.npy','vectors.ids.json','input_record.json']},
    'vector_provenance': json.loads(Path('input_record.json').read_text()),
    'runs': [],
}

# Explicitly exclude each point itself, including when distances tie at zero.
def neighbors(data, metric, k=3):
    d = pairwise_distances(data, metric=metric)
    np.fill_diagonal(d, np.inf)
    return np.argsort(d, axis=1, kind='stable')[:, :k]

original = neighbors(X, 'cosine')
base = dict(n_components=2, metric='cosine', n_neighbors=5,
            min_dist=0.1, n_epochs=200, n_jobs=1, random_state=42)
cases = [
    ('compat', dict(compatibility_layout=True, init='spectral', optimizer='compatibility')),
    ('modern', dict(compatibility_layout=False, init='recursive', optimizer='adam')),
    ('seed7', dict(compatibility_layout=False, init='recursive', optimizer='adam', random_state=7)),
    ('neighbors10', dict(compatibility_layout=False, init='recursive', optimizer='adam', n_neighbors=10)),
    ('looser', dict(compatibility_layout=False, init='recursive', optimizer='adam', min_dist=0.4)),
]
texts_js = json.dumps({r['id']: r['text'] for r in rows}, ensure_ascii=True).replace('<', '\\u003c')
for name, changes in cases:
    params = base | changes
    umap.UMAP(**params).fit_transform(X)  # untimed warm-up for this path
    seconds = []
    for repeat in range(3):
        start = time.perf_counter()
        Y = umap.UMAP(**params).fit_transform(X)
        seconds.append(time.perf_counter() - start)
    projected = neighbors(Y, 'euclidean')
    checks = []
    for i, note_id in enumerate(ids):
        a, b = original[i], projected[i]
        checks.append({'id': note_id, 'original': [ids[j] for j in a],
                       'projected': [ids[j] for j in b],
                       'overlap_at_3': len(set(a) & set(b)) / 3})
    np.save(out / f'{name}.npy', Y)
    (out / f'{name}-neighbors.json').write_text(json.dumps(checks, ensure_ascii=False, indent=2))
    fig = go.Figure(go.Scatter(x=Y[:,0], y=Y[:,1], mode='markers',
        customdata=[[s] for s in ids], marker=dict(size=12, color='#445F96'),
        hovertemplate='%{customdata[0]}<extra></extra>'))
    fig.update_layout(title=f'{name}: click a point to read its source', height=600)
    handler = 'const notes = ' + texts_js + ''';
document.getElementById('{plot_id}').on('plotly_click', function(e) {
  const id = e.points[0].customdata[0];
  document.getElementById('note-text').textContent = id + ': ' + notes[id];
});'''
    graph = fig.to_html(full_html=False, include_plotlyjs=True, post_script=handler)
    page = '<!doctype html><html lang="zh-Hant"><meta charset="utf-8"><title>Notes map</title><body><pre id="note-text" style="white-space:pre-wrap">點一個點,回讀原文</pre>' + graph + '</body></html>'
    (out / f'{name}.html').write_text(page, encoding='utf-8')
    record['runs'].append({'name': name, 'params': params, 'warm_fit_seconds': seconds,
        'median_seconds': statistics.median(seconds),
        'mean_overlap_at_3': float(np.mean([c['overlap_at_3'] for c in checks]))})
    # Separate instrumented fit: profiler overhead is excluded from timings above.
    if name in ['compat', 'modern']:
        pr = cProfile.Profile(); pr.runcall(umap.UMAP(**params).fit_transform, X)
        pr.dump_stats(str(out / f'{name}.prof'))
        with (out / f'{name}-profile.txt').open('w') as f:
            pstats.Stats(pr, stream=f).sort_stats('cumulative').print_stats(
                'pairwise_distances|nearest_neighbors|fuzzy_simplicial_set|spectral_layout|recursive_init|optimize_layout')
(out / 'run.json').write_text(json.dumps(record, ensure_ascii=False, indent=2))
print('Open results/compat.html and results/modern.html, then compare neighbor IDs.')

完成後,開啟 results/compat.html 與 results/modern.html;每點一下,頁面上方應顯示那個 ID 的完整筆記。程式使用 Plotly 自包含 HTML 匯出與 plotly_click 事件,把點位接回原文。所有點先用同一顏色,避免把預先填入的主題配色誤認成自動分群結果。

分享 HTML 等於分享內嵌的原文與座標。即使畫面只顯示一筆,被內嵌的其他筆記仍能從檔案讀出;私人筆記先用本機開啟,對外分享改用已確認可公開的資料。

run.json 留下版本、執行緒、輸入雜湊、每套參數與暖機後三次的總 fit 時間;*-neighbors.json 則逐筆保存原始空間與二維空間的三個近鄰 ID。重新打開同一個 HTML、點到同一筆原文,是第一個驗收;讀回近鄰清單,是第二個。

四、第五步:不要先數幾團,先抽查三種筆記

先找 n02 與 n19:它們文字完全相同。再看 n20,只改了少量文字;最後看 n22,它同時談咖啡與程式。這三組用來練習辨別完全重複、近似改寫與跨主題橋接,不預先規定它們在圖上必須排成什麼形狀。

  • 查原文:它們真的重複,還是只談到相同詞?「備份咖啡筆記」和「備份訓練紀錄」可能共用字詞,卻有不同用途。
  • 查原始近鄰:打開該設定的近鄰 JSON,先看 original。這是根據原始向量與 cosine 距離取出的名單。
  • 查投影近鄰:再看 projected,這是二維座標的歐氏近鄰。名單改變,代表這一小塊地圖值得再查。

overlap_at_3 定義為「兩份前三名近鄰清單共有幾個 ID,再除以 3」。例如人工算例中,原始名單是 A、B、C,投影名單是 A、C、D,重疊就是 2/3;這是公式示意,並非本次執行結果。它量局部名單保留程度,並不量答案正確率或文字理解力。

完全相同的向量可能產生距離平手;範例把自己排除後,以固定列順序打破平手。因此,重複項很多時,單看一份前三名名單仍有侷限;可把並列候選一起人工讀過。至於群集緊密度,官方分群說明明確提醒 UMAP 可能扭曲密度,也可能把原本相連的群切開。圖可以協助提出整理假設,刪筆記前還要核對內容。

五、第六步:一次轉一顆旋鈕,再讀升級與耗時差異

程式已安排三個新配置對照:seed7 只改種子;neighbors10 把 n_neighbors 從 5 改成 10;looser 把 min_dist 從 0.1 改成 0.4。它們都對照 modern,不要把所有差異一起換掉。

  • n_neighbors 像「參考多少鄰居」:較小值偏重局部,較大值讓較廣範圍的關係參與安排。這裡的 5 與 10 是練習設定,不是繁中筆記的通用最佳值。
  • min_dist 像「座位能擠多近」:較小值通常容許更緊密的低維配置;它不是原始語意距離的去重門檻。
  • random_state 像「固定起跑抽籤」:保留一個種子方便重跑,再換種子觀察結論。左右翻轉或整張圖旋轉,和局部鄰居換人,是不同的變化。

參數含義可對照 官方參數教學。驗收時問:「同一筆可疑資料,換設定後還值得查嗎?」而非「哪一張圖分得最開?」若要把地圖接回知識庫,還要用真實查詢驗收檢索;RAG 入門可補上取資料與生成答案之間的分工。

耗時怎麼拆:把總等待與階段熱點分開讀

Numba 首次呼叫會編譯,暖機前後的秒數代表不同條件。程式先對每個配置跑一次不計時暖機,再記三次總 fit 時間,之後另跑 profiler。這份小樣本記錄可檢查你的環境與流程,不能外推到百萬筆,也沒有測到新 optimizer 的多執行緒收益。相同 n_epochs 只固定迭代預算,不保證不同配置已達相同收斂程度。

打開 compat-profile.txt 與 modern-profile.txt,分別找建圖相關的 pairwise_distances、nearest_neighbors、fuzzy_simplicial_set,初始化相關的 spectral_layout/recursive_init,以及配置相關的 optimize_layout。這些名稱依 0.6.0 原始碼辨識,適合定位熱點。

這是函式層級的階段線索,不是三段可直接相加的精準牆鐘計時。Python profiler 文件中的 cumtime 包含子呼叫;遞迴初始化本身也可能包含配置工作,Numba 內部細節未必拆開。先判斷慢在哪一類,再做專門計時;不要把巢狀時間加總成加速圖表。

小資料還有另一個陷阱:依 官方效能文件,預設在少於 4,096 筆時採精確距離路徑。因此某些近鄰搜尋函式未出現在這份 24 筆 profiler 裡,是路徑不同的線索,不能當作那一階段耗時為零。

升級舊專案時,也別把相容說成所有舊檔逐位元相同。官方重現性文件將保證限於相同平台與相依版本、固定資料和種子,並以最終 0.5.x 程式線為基準;文件另列出與 0.5.12 本身有差異的修正。先保存既有座標和檢查結果,再切新配置,才有可比較的基準。

六、常見問題:八個先講答案的判斷

UMAP 會替我把繁中變成語意向量嗎?

不會在這個流程中替你做。這裡的 UMAP 接收既有數值特徵;字面 TF-IDF 與語意模型是上游不同選擇。想改語意表示,先固定模型與輸出,再重新畫圖。

圖上靠近,就可以直接刪掉一篇嗎?

先保留。靠近只提供抽查線索;回讀全文、來源與版本,確認重複資訊是否包含需要保留的差異,再決定合併。

圖上群集間的空白能當作主題差幾倍嗎?

不能從空白直接換算。二維投影壓縮了關係,跨團的遠近與大小需要更審慎解讀;本篇用原始向量近鄰和原文交叉檢查。

固定 seed 就能保證換電腦也完全一樣嗎?

不能只靠 seed。還要保留資料順序、套件、平台與數值相依環境;先比較你在意的局部關係與整理判斷,再看座標是否一致。

0.6 一定要關閉 compatibility_layout 嗎?

依目的選。保留舊流程用 True;評估新初始化與最佳化流程用 False,另存結果。本篇同時保留兩份 HTML。

有既有近鄰圖,還能照這篇比較嗎?

可以另設實驗,但控制條件要改。固定相同近鄰資訊與初始化,才較能隔離配置差異;本篇的兩套完整流程還包含初始化等變動,沒有量出重用圖的獨立收益。

一定需要 GPU 或付費 Embedding API 嗎?

本篇起步不需要。24 筆假資料由本機 TF-IDF 產生,UMAP 使用 CPU;換成語意模型時,另選你已可使用的編碼方式並保存輸出。

近鄰重疊率越高,就代表知識庫越好嗎?

不代表。它只檢查投影保留局部名單的程度;知識庫是否有用,還要測實際查詢能否找到正確內容與版本。

給新手的三個重點

第一,向量與來源 ID 要一起固定,圖才接得回資料。第二,一次只換一個條件,並保留相容配置。第三,地圖上的群集只是檢查入口,用原始近鄰與原文決定要整理什麼。

接著閱讀

左右滑動查看更多推薦

下一步:點回一筆筆記,寫下一個可驗證的整理決定

今天先跑熱身版,找到一組完全重複筆記與一筆跨主題筆記。把你在圖上看到的現象、原始近鄰 ID 和回讀原文後的判斷,各寫一句,再換一個設定重查。UMAP 地圖=向量鄰近關係的二維草圖;地圖幫你找問題,原文幫你判答案。

當你能沿著一個點走回原文,再把輸入換成自己的固定 Embedding。想把這套檢查延伸成完整應用,可以從 AI 文章總覽補齊相關觀念,或透過 AlphaLab 課程安排下一段實作。

ALPHALAB 社群

有問題?來 Telegram 聊

和 Terry、編輯、其他網友一起討論這篇文章。提問、分享觀點,回覆更即時。

加入 Telegram 討論

📩 訂閱 AlphaLab 電子報

週日 Weekly 週報+週二、週四 Alpha Signal,每週最多三封。

我們不會 spam,隨時可退訂。已訂閱?管理訂閱偏好(會寄登入連結到你的信箱)

主題篩選與退訂說明

寄送日期以台灣時間為準。主題偏好會篩選每期精選,並非每篇新文章的即時通知;當期符合主題的文章不足時會略過寄送。

未勾選任何主題會收到所有主題的精選,並不會停止寄信。

取消勾選 Alpha Signal 可停止週二、週四短報,仍保留週日週報。若要停止所有電子報,請使用信件底部的「取消訂閱」。