NLP Day 2 環境與工具鏈:Colab、transformers、LangChain、向量資料庫
執行需求:CPU 可跑。今天是 NLP 系列的第二天,我們會把整個系列要用的工具鏈一次裝好並驗證。包括:Google Colab 環境設定、Python 3.12、PyTorch 2.6、Hugging Face transformers 4.49、sentence-transformers 3.4、LangChain 0.3、Chroma 0.6,以及一個最精簡的「文字 → 嵌入 → 檢索 → 生成」demo。讀完之後你會有可立即動手的環境,後續 43 篇都會用今天這套設定。
引言
Day 1 我們把整個系列的全貌攤開了,從今天開始就要動手做。但 NLP 與 LLM 的環境比 CV 還複雜:除了 PyTorch 與 torchvision,還要裝 transformers、sentence-transformers、peft、accelerate、bitsandbytes 等 Hugging Face 生態系的套件,再加上 LangChain、Chroma、Qdrant、FastAPI 等應用層套件,版本組合一錯就會出現「cannot import name」、「CUDA not available」等莫名其妙的錯誤。
今天這篇的目標是「一次把所有套件裝對、把所有可執行範例跑過一次」。具體來說,我們會做四件事:第一,介紹 Colab 與本機兩種環境;第二,用一個 requirements.txt 鎖住版本;第三,跑通 transformers 的 pipeline;第四,用 sentence-transformers + Chroma 做最簡單的「語意搜尋」demo。所有範例都設計成 CPU 可跑,但同時說明哪些步驟在 Colab T4 上會更快。
要注意的是,這個系列固定在 2025 年 3 月前存在的版本(PyTorch 2.6、transformers 4.49–4.51 世代、LangChain 0.3.x 等)。如果你在 2026 年才讀這篇文章,套件版本可能已經升級,API 也可能改變。建議對照 Hugging Face 官方文件做必要調整,但核心概念不會變。
環境選項:Colab、本機、Docker
NLP 與 LLM 開發有三種主要環境選項:
- Google Colab 免費方案:瀏覽器直接開 Notebook、T4 GPU 免費用、預裝 PyTorch 與大多數主流套件。這個系列預設環境。
- Google Colab Pro / Pro+:升級版可取用 A100、V100。微調大模型時會用到,本系列大部分篇章用不到。
- 本機 Python + 虛擬環境:用 conda 或 venv 管理,適合需要長期運行的服務。Ollama 本地推論必須在本機或 Colab。
- Docker 容器:用 Dockerfile 鎖住環境,方便重現實驗。系列最後的部署篇章(Day 40)會用到。
本系列以 Colab 為主、本機為輔。所有程式碼都設計成「複製到 Colab cell 直接執行」,不需要任何額外設定(除了少數需要 API Key 的篇章)。
Python 版本與虛擬環境
2025 年 3 月,Python 3.12 是 Colab 預設版本,也是大多數企業部署的版本。本系列不支援 Python 3.11 或更早版本(部分套件會要求 typing 模組的新功能)。如果你在本機開發,建議用 conda 或 pyenv 安裝 3.12。
先讓我們檢查 Python 版本:
import sys
print(f"Python 版本:{sys.version}")
# 輸出:Python 版本:3.12.x(依環境不同)
print(f"主要版本:{sys.version_info.major}.{sys.version_info.minor}")
# 輸出:主要版本:3.12
print(f"執行檔路徑:{sys.executable}")
# 輸出:例如 /usr/bin/python3 或 C:\Python312\python.exe
如果你的 Python 不是 3.12,建議用以下方式切換:
- Colab:在 Notebook cell 執行
!python --version確認;Colab 預設就是 3.12。 - conda:
conda create -n nlp python=3.12 -y、conda activate nlp。 - pyenv:
pyenv install 3.12、pyenv local 3.12。
requirements.txt:本系列固定版本
把整個系列要用的套件版本寫成一份 requirements.txt,方便複製到 Colab 或本機。這份清單以 2025 年 3 月可用的穩定版本為基準:
# NLP 系列固定版本(2025-03)
# 安裝:pip install -r requirements_nlp.txt
# 核心深度學習框架
torch==2.6.0
torchvision==0.21.0
# Hugging Face 生態系
transformers==4.49.0
sentence-transformers==3.4.1
datasets==3.2.0
peft==0.14.0
accelerate==1.2.0
tokenizers==0.21.0
# LLM 應用框架
langchain==0.3.13
langchain-community==0.3.13
llama-index==0.12.10
# 向量資料庫
chromadb==0.6.3
qdrant-client==1.12.0
# 文字處理
spacy==3.8.2
jieba==0.42.1
opencc-python-reimplemented==0.1.7
# 評估與輔助
scikit-learn==1.6.0
numpy==1.26.4
pandas==2.2.3
matplotlib==3.10.0
# 部署(Day 40 才會用到)
fastapi==0.115.6
uvicorn==0.32.1
streamlit==1.41.1
這個清單是 Colab 與本機通用版本。在 Colab 上,由於 transformers、sentence-transformers 等核心套件可能已經預裝成較新的版本,pip 安裝會自動覆蓋。可以加 --quiet 參數讓輸出簡潔,或者先 pip show transformers 確認再裝。
裝完之後立刻驗證:
import importlib
versions = {
"torch": "2.6",
"transformers": "4.49",
"sentence_transformers": "3.4",
"langchain": "0.3",
"chromadb": "0.6",
"peft": "0.14",
"spacy": "3.8",
"jieba": "0.42",
}
print("套件".ljust(22) + "目前版本".ljust(15) + "目標版本".ljust(10) + "狀態")
print("-" * 60)
all_ok = True
for name, target in versions.items():
try:
mod = importlib.import_module(name)
current = getattr(mod, "__version__", "未知")
ok = current.startswith(target)
status = "OK" if ok else "版本不符"
if not ok:
all_ok = False
except ImportError:
current = "未安裝"
status = "需安裝"
all_ok = False
row = name.ljust(22) + current.ljust(15) + target.ljust(10) + status
print(row)
print()
print("整體狀態:" + ("全部就緒" if all_ok else "需要調整"))
這段程式用 importlib 動態載入套件並讀版本,印出對齊的表格。實務上這段驗證腳本可以存成 check_env.py,每次新開 Colab Notebook 時跑一次,確保環境正確。實際輸出會依你的安裝版本略有不同。
Google Colab 環境設定
Colab 是這個系列最主要的執行環境。建立 Notebook 之後,建議先做以下設定:
- 執行階段類型:「執行階段」→「變更執行階段類型」選 T4 GPU。NLP 大部分篇章用不到 GPU,但 transformers 載入模型時若偵測到 GPU 會更快。
- 加速器選項:「None(僅 CPU)」就足夠跑 Day 1 到 Day 8。要跑 Day 5 的 BERT 微調或 Day 17 的 LoRA 時再切到 T4。
- 掛載 Google Drive:模型、資料集、筆記本想保留就掛 Drive。Day 2 之後會大量用到。
- Hugging Face Token:Day 13 開始若有下載受限模型的需求,可在左側「金鑰」頁籤新增 HF_TOKEN。免費模型不需要。
Colab 的預設工作目錄是 /content/。建議在這個目錄下建立 nlp-series/ 子目錄,把所有 Notebook、模型、資料集都放進去:
import os
WORK_DIR = "/content/nlp-series" if os.path.exists("/content") else "./nlp-series"
os.makedirs(WORK_DIR, exist_ok=True)
os.chdir(WORK_DIR)
print(f"目前工作目錄:{os.getcwd()}")
# 輸出:目前工作目錄:/content/nlp-series 或 ./nlp-series
print(f"內容物:{os.listdir('.')}")
# 輸出:內容物:[](剛建立時是空的)
這段程式會自動偵測 Colab 與本機環境,統一工作目錄。Colab 上會是 /content/nlp-series,本機則是 ./nlp-series。Day 1 的章節腳本可以放在這個目錄下,每次重開 Notebook 從同一個位置執行。
transformers 4.49:最小的 pipeline 範例
Hugging Face transformers 是整個系列的靈魂。先用一個最簡單的「文字分類」pipeline 確認 transformers 已經正確安裝:
from transformers import pipeline
# 情緒分類:使用 distilbert-base-uncased-finetuned-sst-2-english(約 250 MB)
classifier = pipeline(
task="sentiment-analysis",
model="distilbert-base-uncased-finetuned-sst-2-english",
)
texts = [
"I love this NLP series, it's very clear.",
"The setup is so confusing, I want to quit.",
]
results = classifier(texts)
for t, r in zip(texts, results):
print(f"文字:{t}")
print(f" 預測:{r['label']}(信心 {r['score']:.4f})")
# 輸出範例:
# 文字:I love this NLP series, it's very clear.
# 預測:POSITIVE(信心 0.9998)
# 文字:The setup is so confusing, I want to quit.
# 預測:NEGATIVE(信心 0.9997)
# 實際數字會依模型版本略有不同
這段程式示範了三個關鍵觀念:第一,pipeline(task=...) 是 transformers 的高階 API,把 tokenizer、model、後處理全部包好,一行就能跑;第二,模型會自動從 Hugging Face Hub 下載,第一次執行會看到下載進度條,之後會從本機快取讀取;第三,回傳結果是一個串列,每個元素是包含 label 與 score 的字典。如果你的環境可以連網,這段應該能順利跑完。
sentence-transformers 3.4:句向量
sentence-transformers 是後續 RAG 章節的基礎。先用一個最小的例子確認它能跑:
from sentence_transformers import SentenceTransformer
from sentence_transformers.util import cos_sim
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
sentences = [
"今天天氣真好,適合去爬山。",
"明天會下雨,應該待在家裡。",
"機器學習需要大量資料。",
]
embeddings = model.encode(sentences, normalize_embeddings=True)
print(f"句向量形狀:{embeddings.shape}")
# 輸出:句向量形狀:(3, 384)
# 計算相似度
query = "天氣不錯想去戶外走走"
query_emb = model.encode([query], normalize_embeddings=True)
sim = cos_sim(query_emb, embeddings)[0]
print(f"查詢:{query}")
for s, score in zip(sentences, sim.tolist()):
print(f" 相似度 {score:.4f}:{s}")
# 輸出範例:
# 查詢:天氣不錯想去戶外走走
# 相似度 0.4521:今天天氣真好,適合去爬山。
# 相似度 0.2188:明天會下雨,應該待在家裡。
# 相似度 0.0421:機器學習需要大量資料。
# 實際數字會依模型版本略有不同
這段程式示範 sentence-transformers 的核心功能:model.encode(sentences) 把文字轉成 384 維向量,normalize_embeddings=True 讓向量長度變成 1,這樣 cosine 相似度可以直接用內積算。可以看到「爬山」相關的句子與查詢的相似度最高,「機器學習」的句子相似度最低,符合直覺。實際數字會略有不同,但排名應該一致。
Chroma 0.6:本地向量資料庫
Chroma 是 RAG 章節最常用的向量資料庫。先用最小範例確認它能跑:
import chromadb
# PersistentClient 把索引寫到磁碟,重啟後自動載入
client = chromadb.PersistentClient(path="./chroma_store")
collection = client.get_or_create_collection(
name="nlp_demo",
metadata={"hnsw:space": "cosine"},
)
# 新增 3 筆資料
collection.add(
ids=["d1", "d2", "d3"],
documents=[
"Python 是適合初學者的程式語言。",
"transformers 提供預訓練 NLP 模型。",
"Chroma 是輕量級向量資料庫。",
],
)
# 用文字查詢(Chroma 內建預設嵌入函式)
results = collection.query(
query_texts=["我想找適合做 NLP 的函式庫"],
n_results=2,
)
print("查詢結果:")
for doc, dist in zip(results["documents"][0], results["distances"][0]):
print(f" 距離 {dist:.4f}:{doc}")
# 輸出範例:
# 查詢結果:
# 距離 0.5021:transformers 提供預訓練 NLP 模型。
# 距離 0.7801:Chroma 是輕量級向量資料庫。
# 實際數字會略有不同
import shutil
shutil.rmtree("./chroma_store")
print("已清理測試資料")
這段程式把 Chroma 的最小工作流跑過一次:建立 client、建立 collection、寫入三筆中文文件、用文字查詢回傳最相關的兩筆。get_or_create_collection 是慣用寫法,避免第二次執行時撞名。PersistentClient 把資料寫到 ./chroma_store,重啟後可繼續用。最後用 shutil.rmtree 清理測試資料。Day 23 會深入介紹 Chroma 與 Qdrant、pgvector 的比較。
完整實作:環境就緒一鍵驗證
把今天所有範例串成一個「一鍵驗證」腳本,可以貼到 Colab 第一個 cell 執行,確認整個環境都能運作:
import sys
import time
print("=" * 60)
print("NLP 系列環境驗證腳本")
print("=" * 60)
print(f"Python:{sys.version.split()[0]}")
print()
checks = []
# 1. PyTorch
try:
import torch
checks.append(("torch", torch.__version__, "可用"))
except Exception as e:
checks.append(("torch", "未安裝", str(e)))
# 2. transformers
try:
from transformers import __version__ as v
checks.append(("transformers", v, "可用"))
except Exception as e:
checks.append(("transformers", "未安裝", str(e)))
# 3. sentence-transformers
try:
import sentence_transformers
checks.append(("sentence-transformers", sentence_transformers.__version__, "可用"))
except Exception as e:
checks.append(("sentence-transformers", "未安裝", str(e)))
# 4. spaCy
try:
import spacy
checks.append(("spacy", spacy.__version__, "可用"))
except Exception as e:
checks.append(("spacy", "未安裝", str(e)))
# 5. jieba
try:
import jieba
checks.append(("jieba", jieba.__version__, "可用"))
except Exception as e:
checks.append(("jieba", "未安裝", str(e)))
# 6. LangChain
try:
import langchain
checks.append(("langchain", langchain.__version__, "可用"))
except Exception as e:
checks.append(("langchain", "未安裝", str(e)))
# 7. Chroma
try:
import chromadb
checks.append(("chromadb", chromadb.__version__, "可用"))
except Exception as e:
checks.append(("chromadb", "未安裝", str(e)))
print("套件".ljust(22) + "版本".ljust(15) + "狀態")
print("-" * 60)
for name, ver, status in checks:
print(name.ljust(22) + ver.ljust(15) + status)
print()
ready = all(c[2] == "可用" for c in checks)
print("環境狀態:" + ("就緒" if ready else "需要安裝缺少的套件"))
這段腳本的好處是「失敗明確」:每個套件用 try / except 包起來,缺哪個就會印出來。實際執行時,輸出會列出七個套件的版本與狀態。如果有套件沒裝,去 Colab 的 cell 執行 !pip install 套件名 補上,再跑一次即可。
常見錯誤與踩雷
第一個雷是「transformers 與 sentence-transformers 版本不相容」。sentence-transformers 3.4 要求 transformers ≥ 4.41、版本號需小於 5.0;如果 transformers 是 4.30 或更舊,會出現「ImportError: cannot import name 'cached_file'」。對應排查:用本篇提供的版本號,pip install transformers==4.49.0 sentence-transformers==3.4.1 一起裝。
第二個雷是「在 Colab 預設環境找不到 GPU」。Colab 免費方案的 GPU 名額有限,當 GPU 滿載時,系統會自動切回 CPU 模式(並把 !nvidia-smi 顯示為找不到裝置)。對應排查:執行階段 → 變更執行階段類型 → 確認 T4 已勾選;如果 GPU 額度用完就改用 CPU 等隔天重置。
第三個雷是「Chroma 第一次跑很慢」。Chroma 0.6 第一次啟動會下載嵌入函式的 ONNX 模型(約 80 MB),這段時間可能被誤判為當機。對應排查:第一次跑完之後,後續執行會從 ~/.cache/chroma 讀取,啟動時間縮短到 1 秒以內。
第四個雷是「sentence-transformers 模型下載卡住」。Hugging Face Hub 在某些網路環境會連不上,導致模型下載超時。對應排查:設定 HF_ENDPOINT 環境變數指向鏡像,或用 huggingface-cli login 登入後重試。本系列所有模型都來自 Hugging Face 官方 Hub,沒有鏡像需求。
效能與實務提醒
在 Colab 免費 T4 上,transformers 載入 distilbert 約 2 秒、第一次 encode 100 個句子約 0.5 秒;本機 CPU 上同樣的操作約 5–10 秒。對系列大部分篇章(Day 1 到 Day 12)來說,CPU 速度都足夠;微調篇章(Day 17、Day 21)必須用 GPU。
模型快取的位置預設在 ~/.cache/huggingface/(Linux/macOS)或 C:\Users\使用者\.cache\huggingface\(Windows)。如果你的本機磁碟空間有限,可以把快取改到外接磁碟:
export HF_HOME="/path/to/external/huggingface"
最後提醒:Colab 的工作階段會在閒置 90 分鐘後自動中斷,連續使用上限是 12 小時。長期任務(例如模型微調)建議用本機或 Colab Pro。這個系列的設計會讓每個範例都能在 12 小時內跑完,避免觸發斷線。
本機開發的注意事項
如果你選擇在本機開發而不是 Colab,有幾件事要特別注意:第一,PyTorch 的 CUDA 版本必須與 NVIDIA 驅動版本對應。可以先用 nvidia-smi 看驅動版本最高支援哪個 CUDA,再到 PyTorch 官網選對應的安裝指令(例如 CUDA 12.1 對應 pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cu121)。
第二,macOS Apple Silicon(M1/M2/M3/M4)上要裝 PyTorch 的 MPS 版本。PyTorch 2.6 已經把 MPS 列為穩定支援,安裝指令跟一般版本一樣,MPS 會自動啟用。不過 MPS 上的 transformers 速度比 CUDA 慢、比 CPU 快,介於兩者之間。
第三,Windows 上要注意路徑。Hugging Face 的快取預設在 C:\Users\使用者\.cache\huggingface,如果你換了使用者帳號(例如多人共用一台機器),快取會分開。如果你想統一管理,可以在環境變數設定 HF_HOME。
第四,Linux 上有些系統預裝的 Python 是 3.10 或更舊,安裝 3.12 時建議用 deadsnakes 這類第三方 PPA,或者直接用 conda 管理。混用系統 Python 與自裝 Python 是環境問題的最大來源,盡量避免。
第五,硬碟空間規劃。完整下載本系列用到的所有模型約需要 15 GB(bert-base-chinese 400 MB、bge-m3 2.3 GB、Qwen 2.5 系列 1.5B 到 7B 共約 6 GB、其他小模型數 GB)。如果硬碟有限,建議用到時再下載、不用就清掉,Hugging Face 提供 huggingface-cli delete-cache 工具可以批次清理舊版本快取,並保留最新的版本。
小結
今天把整個系列要用的工具鏈一次建好了:Colab 環境設定、Python 3.12、transformers 4.49、sentence-transformers 3.4、Chroma 0.6、LangChain 0.3 等都跑過了最小範例。我們用一個一鍵驗證腳本做總結,可以貼到任何 Colab Notebook 第一個 cell 確認環境就緒。明天我們會進入 Day 3,正式處理文本前處理與斷詞:spaCy、jieba,以及中文沒有空格的難題。
Ollama 與本地推論的環境選項
雖然 Day 15 才會正式介紹 Ollama,但因為很多讀者會想「先在 Colab 之外也能跑 LLM」,這裡先簡要說明。Ollama 0.6 與 0.7 世代在 2025 年 3 月是本地推論的主流選擇,安裝只要三個步驟:到 https://ollama.com 下載安裝檔、在終端機輸入 ollama pull qwen2.5:1.5b、輸入 ollama run qwen2.5:1.5b 就能開始對話。整個過程不依賴 Python、不需要 GPU,純 CPU 就能跑 1.5B 等級的小模型。
Ollama 對這個系列最大的意義在於「把 LLM 從雲端拉到本機」。Day 13 開始會大量使用 OpenAI、Anthropic 的雲端 API,但對沒有 API Key、或對資料隱私有要求的讀者來說,本地 Ollama 是必要的替代路徑。建議在這個週末就把 Ollama 裝起來、跑幾個範例 prompt,後續篇章會用得比較順。
另一個值得先裝的是 LM Studio(也是 2025 年 3 月前已發布的工具),它提供類似 Ollama 的本地推論功能,但有 GUI 介面,適合不熟命令列的讀者。不過對本系列來說,Ollama 的命令列 API 更貼近工程實務,因此我們的範例會以 Ollama 為主、LM Studio 為輔。
最後提醒一點:Ollama 的模型預設放在 ~/.ollama/models,1.5B 模型約 1 GB、7B 模型約 4–5 GB、13B 模型約 7–8 GB。如果硬碟空間有限,可以指定 OLLAMA_MODELS 環境變數把模型放到外接磁碟。
系列專案的目錄結構建議
本系列後續篇章會反覆用到模型、資料集、筆記本三類資產。建議建立統一的目錄結構方便管理:
nlp-series/
├── notebooks/ # Colab 與 Jupyter Notebook
├── data/ # 資料集(部分放 Hugging Face Cache)
├── models/ # 下載的預訓練模型(可選,大部分用 HF 快取)
├── chroma_store/ # Chroma 持久化資料
├── outputs/ # 評估結果、生成的文字
└── requirements.txt # 套件版本鎖定
這份結構不是強制規定,但能讓 45 天的實作有個一致的起點。建議在 Day 2 的最後花十分鐘建立好,後續篇章都把檔案放在對應目錄下。Colab 的 /content/ 在工作階段結束後會清空,但如果你把整個 nlp-series/ 放在 Google Drive 裡,每次開 Notebook 重新掛載就能繼續。
結語
NLP 環境的複雜度比 CV 高很多:除了深度學習框架,還要管 Hugging Face、應用框架、向量資料庫三條生態系。今天的目標是「一次裝對」——鎖版本、跑驗證、確認每個套件都能動。後續 43 篇都會用今天這套設定,環境問題從此不再是阻礙。明天,我們會進入文本前處理的細節:英文用 spaCy、中文用 jieba,並且會看到「為什麼中文斷詞比英文難太多」的實際示範。
延伸資源
- Hugging Face Transformers 4.49 安裝指南(2025):
https://huggingface.co/docs/transformers/v4.49.0/en/installation - sentence-transformers 3.4 安裝與安裝疑難排解(2025):
https://sbert.net/docs/installation.html - Chroma 0.6 快速入門(2025):
https://docs.trychroma.com/getting-started - LangChain 0.3 安裝指南(2025):
https://python.langchain.com/docs/how_to/installation/ - Google Colab 免費方案限制說明(2025):
https://research.google.com/colaboratory/faq.html
留言
張貼留言