一、Python環境、Jupyter與Pycharm

安裝Python

由于RAG項目中所需要的Python版本必須高于3.8，經過篩選，最終選擇了3.10.11這個版本

py --version
Python 3.10.11

安裝過程略過，但對于幾個基礎的命令作個筆記記錄

where python

找到python啟動器的位置

D:\>where python
C:\Users\xxxxx\AppData\Local\Programs\Python\Python310\python.exe

py -0

py -0 這個命令可以在有多個版本的Python的情況下，查看Python啟動器默認執行的是哪個版本（帶 * 標記的這個就是默認版本），多個版本的情況下，如果想改變Python啟動器的默認版本，有兩種方式：1、設置環境變量 PY_PYTHON=3.10 ；2、改配置置文件 %LOCALAPPDATA%\py.ini

D:\>py -0
Installed Pythons found by py Launcher for Windows-3.10-64 *

Python啟動器的默認執行版本與環境變量PATH中的Phthon版本設定問題：

兩者并不是同步的，因為Python啟動器用的python版本并不依賴于PATH環境變量。

pip命令

pip命令最常見的用法就是安裝依賴工具包

D:\PythonWorkspace\wow-rag\rag-venv>pip install fastapiLooking in indexes: https://mirrors.aliyun.com/pypi/simple/
Requirement already satisfied: fastapi in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (0.116.1)
Requirement already satisfied: starlette<0.48.0,>=0.40.0 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from fastapi) (0.47.1)
Requirement already satisfied: typing-extensions>=4.8.0 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from fastapi) (4.14.1)
Requirement already satisfied: pydantic!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0,>=1.7.4 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from fastapi) (2.11.7)
Requirement already satisfied: typing-inspection>=0.4.0 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from pydantic!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0,>=1.7.4->fastapi) (0.4.1)
Requirement already satisfied: annotated-types>=0.6.0 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from pydantic!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0,>=1.7.4->fastapi) (0.7.0)
Requirement already satisfied: pydantic-core==2.33.2 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from pydantic!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0,>=1.7.4->fastapi) (2.33.2)
Requirement already satisfied: anyio<5,>=3.6.2 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from starlette<0.48.0,>=0.40.0->fastapi) (4.9.0)
Requirement already satisfied: sniffio>=1.1 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from anyio<5,>=3.6.2->starlette<0.48.0,>=0.40.0->fastapi) (1.3.1)
Requirement already satisfied: idna>=2.8 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from anyio<5,>=3.6.2->starlette<0.48.0,>=0.40.0->fastapi) (3.10)
Requirement already satisfied: exceptiongroup>=1.0.2 in d:\pythonworkspace\wow-rag\rag-venv\lib\site-packages (from anyio<5,>=3.6.2->starlette<0.48.0,>=0.40.0->fastapi) (1.3.0)
Note: you may need to restart the kernel to use updated packages.

有多個版本的Python時，可以用py命令帶上版本號來對指定的版本安裝依賴包，例：

py -3.10 -m pip install langchain

安裝 langchain 包到 Python 3.10 的環境中

Python的虛擬環境

虛擬環境是一個 獨立的 Python 環境目錄（包含解釋器、pip、安裝包等），本質是一個文件夾，在實際項目中，對每個項目單獨創建一個虛擬環境是有重要意義的，這可以讓每個項目所依賴的包與其他項目的依賴包進行隔離，避免工具包的版本沖突導致的各種問題。

虛擬環境通常在項目的根目錄下創建，用命令行創建一個虛擬環境的示例（rag-env是虛擬環境的目錄）：

py -3.10 -m venv rag-env

虛擬環境的激活：在 rag-env\Scripts 目錄下執行active.bat （必須CMD窗口執行），關閉就是執行 deactive.bat

重要：安裝項目依賴的工具包之前激活該項目的虛擬環境，避免工具包未正確安裝導致運行代碼的時候出現報錯：

ModuleNotFoundError: No module named 'pandas'

一旦你激活了某個虛擬環境，后續在該命令行中執行的所有 Python 相關命令（如 python, pip, conda, pytest 等），都是作用在這個被激活的虛擬環境中的。

一個命令行窗口只能管理一個虛擬環境的狀態（激活/關閉），命令行窗口關閉后，激活的虛擬環境會自動關閉。想要管理多個虛擬環境的狀態，可以開多個命令行。

注：使用PyCharm創建一個項目可以指定的策略來為項目創建一個新的虛擬環境，且在PyCharm中運行Python程序的時候不需要手動激活虛擬環境，PyCharm會幫用戶做這件事。

Jupyter與Jupyter Book

Jupyter適用于做Python的小實驗，比用PyCharm更簡潔方便。使用Jupyter需要的前提條件是：

1、安裝Python

2、在項目的根目錄下創建該項目的虛擬環境，例：py -3.10 -m venv rag-venv

3、已激活虛擬環境（命令行前綴顯示虛擬環境的目錄名，如： rag-env）

(rag-venv) C:\Users\YourName\YourProject>

安裝Jupyter的步驟

1、（建議）使用阿里的鏡像源，提高下載速度

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

2、安裝Jupyter

pip install notebook

3、確認已裝好

jupyter --version

4、啟動Jupyter（在虛擬環境中執行）

jupyter notebook

瀏覽器中打開 http://localhost:8888，這是 Jupyter 的控制面板，你可以：

新建一個 Notebook（點擊右上角 New → 選擇 Python 3.10 環境）
編寫代碼，運行、保存等

5、退出 Jupyter 后，如果不再工作，可關閉虛擬環境（執行 \Scripts目錄下的 deactive.bat）

在 Jupyter Notebook 中，界面是由一個個可以運行代碼或寫文字的“格子”（單元格，ode cell）組成的。每個格子可以：

輸入一段 Python 代碼
按下 Shift + Enter 運行這段代碼
結果會顯示在格子下方
你可以隨時插入新格子、刪除、復制、重新運行等

你可以在Jupyter Notebook中寫python 代碼、調試、展示結果等操作。比命令行好用，比PyCharm方便。

每個代碼格子都要單獨運行，才能執行其中的代碼，除非你選擇了批量執行（比如，菜單欄中執行 Restart & Run All，這會重騎Python的環境并按順序運行所有的代碼格子）。

Pycharm

與IDEA同為JetBrains下的產品，因此，很多設計特點可以參照IDEA來對標。

與IDEA一樣，免費使用的版本為社區版（Community），本次安裝的版本為 PyCharm Community 2023.3.5，安裝過程略。

首次啟動時的幾個設置：

Import Settings：
- 選擇 Do not import settings（針對首次使用者）。
UI 界面主題選擇：
- 推薦選擇 Darcula（深色） 或 Light（淺色），可隨時更改。
插件推薦（可跳過）

項目與虛擬環境

與IDEA中對Java的版本設置相似，PyCharm中也可以設置全局Python的版本，但是不建議設置全局共享的Python解釋器，因為這樣很容易造成依賴沖突。

因此，對每個項目構建一個該項目的虛擬環境是實際項目中規范的做法。

新建項目的示例：

File→New Project：Interpreter Type 選 Custom enviroment?

這樣就可以在創建項目目錄的同時，在項目的目錄下構建該項目的虛擬環境。

在虛擬環境的目錄里，可以看到有一個python.exe，在 項目文件夾\虛擬環境文件夾\Scripts\? 這個目錄下，這是系統安裝的Python(多版本的話指向的是默認版本)的一個副本，副本的意思是基于系統安裝的Python復制必要的解釋器文件，并創建一個獨立的依賴空間（包的安裝路徑、sys.path 等都被重定向到了虛擬環境下的 Lib/ 和 Scripts/ 目錄）。這樣的話，在這個虛擬環境中裝包、運行腳本，不會影響或依賴全局安裝。

這里可以類比 Docker來理解：

虛擬環境機制	Docker 概念類比
`python.exe` + Lib	鏡像的運行時
虛擬環境目錄結構	容器文件系統
`Scripts/activate`	啟動入口（類似 entrypoint）
pip install 的包	容器內的依賴

用Conda構建虛擬環境

Conda 是一個跨平臺的包管理 + 環境管理工具，類似于 pip + virtualenv 的合體，而且不限于 Python 包。

Conda的能力	作用
📦 包管理	安裝、卸載、更新第三方庫（不只是 Python 庫）
🌍 環境管理	創建、切換、隔離多個 Python 環境（或其他語言環境）
🏗? Python 版本管理	每個環境可以使用不同版本的 Python
💼 支持非 Python 包	可安裝 C/C++ 編譯的科學計算包（如 numpy、pandas、opencv 等）而不需你配置編譯器

與前面的創建虛擬環境的方式相比，使用Conda最大的優勢是支持非Python包的安裝與管理

Conda有兩個版本，Anaconda和Miniconda，以下是這兩個版本的對比

特性	Anaconda	Miniconda
📦 包含內容	Python + Conda + 300+ 常用數據科學包 + Navigator GUI	僅 Python + Conda + 少量基礎依賴（輕量命令行版）
🛠 安裝體積	≈?4?GB，安裝后環境龐大	約?480?MB，下載快，安裝輕便
🧰 適用人群	希望開箱即用，零配置即可使用數據科學工具	想控制包安裝，節省空間，只安裝所需包
🛠 包管理方式	GUI + CLI（conda install）	純命令行（conda install）
📡 非 Python 包支持	支持 C/C++ 庫、R 等	同 Anaconda（都使用 Conda 包管理）
?? 包更新頻率	默認 conda 通道中包更新較慢	輕量，建議通過 conda-forge 或 mamba 加速

這里選用Anaconda，因為這對初學者更友好一點。

Anaconda的對虛擬環境的創建有兩種方式：

方式	命令	環境位置	適用場景
方式 A：命名環境法（命名環境撥法）	`conda create -n myenv python=3.10`	? 一個統一的目錄，如：Anaconda 的目錄：`…/anaconda3/envs/myenv/`	? 推薦用于多個項目共享某個環境，統一管理
方式 B：路徑方式（項目內環境）	`conda create -p ./venv python=3.10`	? 在項目的目錄下創建，如 `./venv/`	? 推薦用于項目內綁定，方便遷移、開源

兩種方式的區別可簡單理解為：虛擬環境的安裝位置一個在統一的目錄里（比如Anaconda下的目錄），另一個在項目的目錄里，使用PyCharm新建項目的時候分別在不同的虛擬環境目錄下選擇python解釋器（后面的詳細步驟也會提到），核心區別的詳細對比如下：

特性	命名環境（-n myenv）	路徑環境（-p ./venv）
📁 環境放在哪里	系統集中目錄（如 `anaconda3/envs/`）	項目目錄下（如 `./venv/`）
🔄 是否推薦復用	? 支持復用（多個項目可用）	? 項目獨占，不復用
🧳 可遷移性	? 環境與項目分離（不便遷移）	? 項目打包帶走環境更方便
🛠 開發效率	快速使用已有環境，無需重復安裝	需要每次創建、安裝依賴
🤝 團隊協作	不易同步環境，需導出 `.yml`	配合環境文件更清晰可控
📦 PyCharm 支持	自動識別，配置簡單	需手動指向解釋器路徑

使用Anaconda創建項目的步驟描述

1、創建項目目錄

# 創建項目目錄
mkdir MyProject && cd MyProject# 創建目錄結構
mkdir app tests
echo > README.md
echo > app/main.py
echo > app/__init__.py
echo > tests/test_main.py

2、創建Conda虛擬環境（這里用“命名環境法”）

# 創建環境（可自定義名稱和版本）
conda create -n myproject_env python=3.10# 激活環境
conda activate myproject_env# 安裝開發常用包
conda install pytest# 如果用 pip 也可以混合使用
pip install requests

3、在 PyCharm 中打開項目并配置解釋器

打開 PyCharm → Open → 選擇你的項目目錄（如 D:\Projects\MyProject）
菜單欄：File → Settings → Project → Python Interpreter
添加解釋器：選擇
- Conda Environment → Existing Environment
- 指向：
```
...\anaconda3\envs\myproject_env\python.exe
```

4、設置項目入口

右鍵 main.py → Mark as Entry Point（或者設置運行配置）
或在頂部菜單選擇：
- Run → Edit Configurations → + → Python
- Script path 選 app/main.py
- Name 起個名字 Run App
- Interpreter 選你剛配置的 Conda 解釋器
- Apply → OK

5、設置 app/ 為源碼目錄（非常重要）

右鍵 app/ → Mark Directory as → Sources Root
這樣導入 from utils import xxx 就不會報錯。

6.、導出 environment.yml（可選，但推薦）

將當前環境依賴導出成配置文件：

conda env export --from-history > environment.yml

這樣你可以：

保留環境快照
遷移到新機器時 conda env create -f environment.yml 即可重建

最終實現的項目目錄結構如下：

MyProject/
├── .idea/              ← PyCharm 配置（自動生成）
├── app/                ← 源代碼
├── tests/              ← 測試
├── README.md
├── environment.yml