EN
02 / 07第 5 章：建立基本 RAG 流程 · 2 分鐘 · 2026-10-05

5.2 開發環境設定

準備 Python 環境、安裝套件，以及怎麼安全地處理 API 金鑰。

RAG下一篇 →

先把範例需要的 Python 環境和套件固定下來。環境設定看似和 RAG 無關，卻最常造成「同一份程式在別台電腦跑不起來」。

需要什麼

  • Python：建議 3.10 以上。
  • 幾個套件：
    • sentence-transformers：嵌入模型。
    • chromadb：向量資料庫。
    • 你要用的 LLM 的 SDK，例如 anthropic。
  • 一個 LLM 的 API 金鑰（可選）：要呼叫雲端模型才需要。沒有的話，範例也能跑到「組好提示詞」那一步。

用虛擬環境

不同專案需要的套件版本不同，建議每個專案都用自己的虛擬環境，避免互相干擾。

方法一：uv（推薦）

uv 是一個很快的 Python 工具，可以直接用一行指令執行程式，不用先手動建環境：

uv run --with chromadb --with sentence-transformers rag_demo.py

方法二：venv 加 pip

python -m venv .venv

啟動環境（Windows PowerShell）：

.venv\Scripts\Activate.ps1

啟動環境（macOS / Linux）：

source .venv/bin/activate

安裝套件：

pip install chromadb sentence-transformers anthropic

記錄套件版本

AI 相關的套件更新很快，介面常有變動。建議把用到的版本記下來，之後才能重現：

pip freeze > requirements.txt

第一次執行會下載模型

SentenceTransformer("...") 第一次執行時，會自動從網路下載模型檔，需要一點時間和硬碟空間，之後會用快取。

注意　在 Windows 上，如果看到關於 symlink 的警告，只是快取方式的提醒，不影響結果。想關掉可以設定環境變數 HF_HUB_DISABLE_SYMLINKS_WARNING=1。

API 金鑰：不要寫在程式碼裡

呼叫雲端 LLM 需要 API 金鑰。金鑰絕對不要直接寫進程式碼，更不能上傳到 GitHub。 一旦外流，別人可以用你的額度。

正確的做法是放在環境變數。程式從環境讀取：

import os

api_key = os.environ.get("ANTHROPIC_API_KEY")

設定環境變數（PowerShell，只對目前這個視窗有效）：

$env:ANTHROPIC_API_KEY = "你的金鑰"

macOS / Linux：

export ANTHROPIC_API_KEY="你的金鑰"

也有人用 .env 檔案存放，再用套件讀進來。如果這樣做，一定要把 .env 加進 .gitignore，確保它不會被提交。

很多 SDK 會自動讀取特定名稱的環境變數，所以不用把金鑰在程式裡傳來傳去。

專案的資料夾結構

本文的範例很小，一個檔案就夠了。實際專案通常會這樣整理：

my-rag/
├── data/              # 原始文件
├── rag.py             # 主要程式
├── requirements.txt   # 套件版本
├── .gitignore         # 記得排除 .env、.venv、向量資料庫的資料夾
└── .env               # API 金鑰（不要上傳）

如果向量資料庫存在本機的資料夾（例如 Chroma 的持久化資料夾），也要考慮要不要加入 .gitignore，因為它可能很大，而且可以隨時從原始文件重建。

檢查環境是否正常

跑一個最簡單的測試，確認套件都裝好了：

import chromadb
from sentence_transformers import SentenceTransformer

print("chromadb", chromadb.__version__)
model = SentenceTransformer("paraphrase-multilingual-MiniLM-L12-v2")
print("嵌入維度：", model.get_sentence_embedding_dimension())

能順利印出結果，就代表環境準備好了。

← 全部文章