以下以 **Python 套件 `chromadb`** 為例說明。Chroma 通常不需要另外下載安裝程式，直接透過 `pip` 安裝即可。建議使用 **Python 3.9 以上**，並在虛擬環境中安裝。 ## 一、Windows 安裝 Chroma ### 1. 確認 Python 是否已安裝 開啟 **PowerShell** 或「命令提示字元」，輸入： ```powershell py --version ``` 如果顯示類似： ```text Python 3.11.8 ``` 就代表已安裝。 如果找不到 Python，可以至 Python 官方網站下載： <https://www.python.org/downloads/windows/> 安裝時請勾選： ```text Add python.exe to PATH ``` --- ### 2. 建立虛擬環境 先建立一個專案資料夾： ```powershell mkdir chroma-demo cd chroma-demo ``` 建立虛擬環境： ```powershell py -m venv .venv ``` 啟用虛擬環境： ```powershell .venv\Scripts\Activate.ps1 ``` 成功後，命令列前面通常會出現： ```text (.venv) ``` 如果 PowerShell 顯示禁止執行指令的錯誤，可以先執行： ```powershell Set-ExecutionPolicy -Scope CurrentUser RemoteSigned ``` 然後重新啟用虛擬環境。 --- ### 3. 安裝 Chroma ```powershell python -m pip install --upgrade pip python -m pip install chromadb ``` 如果使用的是命令提示字元，也可以使用： ```cmd .venv\Scripts\activate.bat python -m pip install chromadb ``` --- ## 二、macOS 安裝 Chroma ### 1. 確認 Python 是否已安裝 開啟 **Terminal**，輸入： ```bash python3 --version ``` 若顯示類似： ```text Python 3.11.8 ``` 即可使用。 如果沒有 Python，可以： 1. 從 Python 官方網站下載 macOS 版本： <https://www.python.org/downloads/macos/> 2. 或使用 Homebrew： ```bash brew install python ``` 安裝 Homebrew 的網址： <https://brew.sh/> --- ### 2. 建立虛擬環境 ```bash mkdir chroma-demo cd chroma-demo python3 -m venv .venv ``` 啟用虛擬環境： ```bash source .venv/bin/activate ``` 成功後，命令列前面通常會出現： ```text (.venv) ``` --- ### 3. 安裝 Chroma ```bash python -m pip install --upgrade pip python -m pip install chromadb ``` 使用 Apple Silicon，例如 M1、M2、M3、M4 Mac，一般可直接使用上述指令。若遇到套件相容性問題，請確認 Python 使用的是與 Mac 架構相容的版本。 --- ## 三、確認 Chroma 是否安裝成功 ### 方法 1：確認套件版本 Windows： ```powershell python -c "import chromadb; print(chromadb.__version__)" ``` macOS： ```bash python -c "import chromadb; print(chromadb.__version__)" ``` 如果成功顯示版本號，例如： ```text 1.0.0 ``` 表示 Chroma 已成功安裝。 如果出現： ```text ModuleNotFoundError: No module named 'chromadb' ``` 通常表示： - 尚未安裝 Chroma - 沒有啟用正確的虛擬環境 - `pip` 和 `python` 指向不同的 Python 此時請確認虛擬環境已啟用，並重新執行： ```bash python -m pip install chromadb ``` --- ### 方法 2：執行簡單測試程式 在專案資料夾中建立 `test_chroma.py`： ```python import chromadb client = chromadb.PersistentClient(path="./chroma_data") collection = client.get_or_create_collection(name="test_collection") collection.add( ids=["id1"], documents=["這是一筆 Chroma 測試資料"] ) result = collection.query( query_texts=["測試資料"], n_results=1 ) print("Chroma 安裝與基本操作成功") print(result) ``` 執行： ```bash python test_chroma.py ``` 如果能看到： ```text Chroma 安裝與基本操作成功 ``` 並且輸出查詢結果，就代表 Chroma 不只安裝成功，基本的資料儲存與查詢功能也能正常運作。 執行後，專案資料夾通常會產生： ```text chroma_data/ ``` 這是 Chroma 的本機持久化資料目錄。 --- ## 四、選用：啟動 Chroma Server 如果希望以獨立伺服器方式執行 Chroma，可以使用： ```bash chroma run --path ./chroma_data ``` Windows PowerShell 和 macOS Terminal 都可使用相同指令。 若啟動成功，終端機通常會顯示伺服器正在某個本機網址，例如： ```text http://localhost:8000 ``` 若系統顯示找不到 `chroma` 指令，可以改用： ```bash python -m chromadb ``` 不過實際是否支援此啟動方式會依 Chroma 版本而不同；一般而言，使用 Python API 的 `PersistentClient` 是最簡單的本機測試方式。 --- ## 五、常見問題 ### 1. `pip` 找不到 請改用： ```bash python -m pip install chromadb ``` Windows 也可以使用： ```powershell py -m pip install chromadb ``` 這樣可以確保套件安裝到目前使用的 Python 環境。 ### 2. Windows 出現權限問題 建議使用虛擬環境，不要直接安裝到系統 Python： ```powershell py -m venv .venv .venv\Scripts\Activate.ps1 python -m pip install chromadb ``` ### 3. 安裝後仍然無法 `import chromadb` 確認目前使用的 Python 和 pip 是否來自同一個環境： ```bash python -c "import sys; print(sys.executable)" python -m pip show chromadb ``` 如果 `pip show` 找不到套件，請在目前啟用的虛擬環境中重新安裝： ```bash python -m pip install chromadb ``` ### 4. 不要誤裝 `chromadb-client` 若要在本機儲存資料並使用 Chroma，通常應安裝： ```bash python -m pip install chromadb ``` `chromadb-client` 主要用於連接遠端 Chroma 伺服器，不是一般本機使用的完整套件。