準備開發環境和 API 金鑰

這一課做完，你會有一個能呼叫大模型的 Python 環境，以及一個確認它可用的檢查指令碼。整個過程半小時左右，大部分時間花在註冊賬號上。

裝 Python 和 uv

這門課用 uv 管理 Python 環境。它是一個 Python 的包管理工具，比 pip 加 venv 的傳統組合快得多，而且它會順手幫你裝好合適版本的 Python，你不用先單獨裝 Python。

macOS 和 Linux 在終端裡執行：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows 在 PowerShell 裡執行：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

用 Homebrew 的話，brew install uv 也可以。裝好之後，重新開啟一個終端視窗，執行 uv --version，能看到版本號就說明裝好了。

如果你已經習慣了 pip 和 venv，或者用 conda，也完全可以繼續用。這門課的程式碼只依賴幾個常見的包，用什麼工具裝都行。下面的命令我會同時給出 pip 的寫法。

建一個專案

找個放程式碼的地方，建一個專案目錄：

uv init --no-package ai-course
cd ai-course
uv add openai

--no-package 的意思是"這只是一個放指令碼的專案，不打算打包釋出"。不加這個參數，新版本的 uv 會生成一套打包用的目錄結構（src/ 目錄和構建配置），對這門課來說是多餘的。

uv init 生成了這些檔案：

ai-course/
  .git/             uv 顺手帮你初始化了 git 仓库
  .gitignore        已经写好了该忽略的文件，包括 .venv
  .python-version   这个项目用哪个版本的 Python
  main.py           一个打印 Hello 的示例脚本
  pyproject.toml    项目信息和依赖列表
  README.md

uv add openai 又多出兩樣東西：.venv 目錄是這個專案的虛擬環境，openai 就裝在裡面；uv.lock 記錄了每個包精確的版本號，別人拿到你的專案執行 uv sync，就能裝出一模一樣的環境。同時 openai 被寫進了 pyproject.toml 的 dependencies 裡。

試一下能不能執行：

uv run main.py

看到 Hello from ai-course! 就對了。

以後執行這個專案裡的指令碼，用 uv run：

uv run python 你的脚本.py

uv run 會自動使用專案的虛擬環境，你不用手動啟用它。

用 pip 的寫法是這樣的，效果一樣：

mkdir ai-course && cd ai-course
python3 -m venv .venv
source .venv/bin/activate      # Windows 用 .venv\Scripts\activate
pip install openai

這種寫法每次開啟新終端都要重新執行 source .venv/bin/activate，然後直接用 python 你的脚本.py 執行。

為什麼要虛擬環境

每個專案用自己的一套包，互不干擾。你今天給這門課裝了 openai 最新版，明天另一個老專案需要舊版，兩個都能正常工作。如果把所有包都裝進系統的 Python，遲早會遇到版本打架，而且很難收拾。

編輯器

用你順手的編輯器就行。沒有偏好的話，推薦 VS Code，再裝上微軟官方的 Python 擴充套件。用 VS Code 開啟 ai-course 目錄後，按 Ctrl+Shift+P（macOS 是 Cmd+Shift+P），輸入 "Python: Select Interpreter"，選 .venv 裡的那個 Python。這樣編輯器才能認出你裝的包，不會滿屏紅色波浪線。

申請 DeepSeek API 金鑰

1. 開啟 DeepSeek 開放平臺，用手機號註冊並登入。
2. 在左側選單進入"充值"，充一點錢。學完第一部分一般花不到 1 美元，充最低的金額就夠了。
3. 進入 API keys 頁面，點"建立 API key"，起個名字，比如"ai-course"。
4. 複製生成的金鑰。它以 sk- 開頭，只會顯示這一次，關掉頁面就再也看不到了。沒複製下來的話，刪掉重新建一個就是。

把金鑰設定成環境變數

金鑰等於你賬戶裡的錢。任何拿到它的人都能用你的餘額呼叫模型。所以有一條規矩：金鑰永遠不要寫進程式碼檔案裡。

寫進程式碼有什麼問題？程式碼會被提交到 git，推到 GitHub，分享給同事，貼到網上問問題。每一步都可能把金鑰帶出去。GitHub 上一直有人專門掃描公開倉庫裡的金鑰，洩露之後很快就會被盜用。

正確的做法是把金鑰放在環境變數裡，程式碼執行時再去讀。這門課統一用三個環境變數：

之所以不用 DeepSeek 官方文件裡的 DEEPSEEK_API_KEY 這個名字，是因為這門課的程式碼要能在不同服務商之間切換。以後你想換成別家，只改這三個變數的值，一行程式碼都不用動。

macOS 和 Linux：開啟 ~/.zshrc（macOS 預設的 shell 是 zsh）或者 ~/.bashrc（大多數 Linux），在末尾加上：

export LLM_API_KEY="sk-你的密钥"
export LLM_BASE_URL="https://api.deepseek.com"
export LLM_MODEL="deepseek-flash"

儲存後，關掉終端重新開啟，或者執行 source ~/.zshrc。

Windows：在 PowerShell 裡執行下面三行，它們會把變數永久儲存到你的使用者賬戶裡：

setx LLM_API_KEY "sk-你的密钥"
setx LLM_BASE_URL "https://api.deepseek.com"
setx LLM_MODEL "deepseek-flash"

setx 設定的變數對當前視窗不生效，要關掉 PowerShell 重新開啟。這是 Windows 上最常見的坑：明明設定了，程式卻說找不到。

另一種辦法：.env 檔案

有些人喜歡把金鑰寫在專案目錄下的 .env 檔案裡，用 python-dotenv 這個包在程式啟動時讀進來。這也可以，但一定要先把 .env 加進 .gitignore：

echo ".env" >> .gitignore

先加 .gitignore，再建 .env。順序反了，你可能在某次 git add . 時就把它提交上去了。一旦提交過，就算後來刪掉，它也還留在 git 的歷史記錄裡。遇到這種情況，別想著怎麼清歷史，直接去平臺上把這個金鑰刪掉，重新建一個。

檢查一下

把下面的指令碼儲存成 check_env.py：

"""检查三个环境变量有没有设置好，并用一次最便宜的请求确认密钥可用。"""
import os
import sys

from openai import APIConnectionError, AuthenticationError, OpenAI

key = os.environ.get("LLM_API_KEY")
base_url = os.environ.get("LLM_BASE_URL", "https://api.deepseek.com")
model = os.environ.get("LLM_MODEL", "deepseek-flash")

if not key:
    sys.exit("没有找到 LLM_API_KEY。设置完环境变量后，要重新打开一个终端窗口才会生效。")

# 只显示密钥的开头和结尾，避免截图时泄露
print(f"密钥：{key[:5]}...{key[-4:]}")
print(f"地址：{base_url}")
print(f"模型：{model}")

client = OpenAI(api_key=key, base_url=base_url)
try:
    available = [m.id for m in client.models.list().data]
except AuthenticationError:
    sys.exit("密钥不对（401）。检查有没有复制完整、有没有多出空格。")
except APIConnectionError:
    sys.exit("连不上服务器。检查地址有没有写错，或者网络是否需要代理。")

print(f"这个密钥能用的模型：{', '.join(available)}")
if model not in available:
    print(f"注意：{model} 不在列表里，调用时可能会报错或被映射到别的模型。")
else:
    print("一切正常，可以开始上课了。")

執行：

uv run python check_env.py

我執行的結果是這樣的（金鑰中間部分被隱去了）：

密钥：sk-7f...805f
地址：https://api.deepseek.com
模型：deepseek-flash
这个密钥能用的模型：deepseek-flash, deepseek-v4-pro
一切正常，可以开始上课了。

最後一行出現"一切正常"，環境就準備好了。倒數第二行列出的是你的金鑰能呼叫的模型，截至 2026 年 9 月，DeepSeek 提供 deepseek-flash 和 deepseek-v4-pro 兩個。這門課預設用 deepseek-flash，它便宜、速度快，課程裡的任務它都能做好。

這個指令碼呼叫的是"列出模型"的介面，它不生成任何文字，所以不花錢。

換成別的服務商

這門課的程式碼只依賴 OpenAI 的 Python SDK，所有相容 OpenAI 介面的服務都能用。下面幾家都有中文文件，地址和模型名以各自官方文件為準（截至 2026 年 9 月）：

有兩點要注意。

第一，各家"相容 OpenAI 介面"的程度不完全一樣。最基本的對話呼叫都能用，但工具呼叫、JSON 輸出、流式輸出這些功能，有的模型不支援，有的細節不同。後面的課用到這些功能時，我會說明哪些是 DeepSeek 特有的。

第二，本地的 Ollama 完全免費，也不用聯網，但是在普通筆記本上能跑的模型比較小，效果明顯不如雲端的大模型，有些課的練習可能做不出來。建議先用雲端模型把第一部分學完，第 10 模組會專門講本地部署。

常見問題

執行指令碼提示 ModuleNotFoundError: No module named 'openai'：包裝在了專案的虛擬環境裡，但你執行的是系統的 Python。用 uv run python ... 執行，或者先啟用虛擬環境。

提示"沒有找到 LLM_API_KEY"，可我明明設定了：設定環境變數之後要重新開啟終端。在 VS Code 裡執行的話，要把整個 VS Code 關掉重開，只關掉裡面的終端面板不夠。

401 錯誤：金鑰複製得不完整，或者前後多了空格、引號。也可能是這個金鑰已經在平臺上被刪掉了。

402 錯誤或者提示餘額不足：去平臺充值。

練習

1. 在終端裡執行 echo $LLM_MODEL（Windows PowerShell 用 echo $env:LLM_MODEL），確認能打印出模型名。
2. 故意把 LLM_API_KEY 改錯一個字母再執行 check_env.py，看看報錯資訊是什麼樣的。改完記得改回來。在終端裡臨時改一個變數，可以這樣寫：LLM_API_KEY=sk-wrong uv run python check_env.py，它只對這一條命令生效。
3. 如果你有通義千問或 Kimi 的賬號，照著上面的表格把三個變數換成那家的值，再執行一次 check_env.py。

自測

1. 為什麼不能把 API 金鑰直接寫在程式碼裡？

程式碼會被提交到 git、推到 GitHub、發給別人。每一步都可能讓金鑰洩露，而拿到金鑰的人可以直接花你賬戶裡的錢。放在環境變數裡，程式碼檔案本身不含任何秘密，可以放心分享。

2. 在 Windows 上用 setx 設定了 LLM_API_KEY，馬上執行指令碼，卻提示找不到。為什麼？

setx 把變數寫進了使用者配置，但已經開啟的視窗不會重新讀取配置。關掉 PowerShell（或者整個 VS Code）重新開啟就好。

3. 這門課為什麼用 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL 這三個變數，而不是 DEEPSEEK_API_KEY？

為了切換服務商時不用改程式碼。所有相容 OpenAI 介面的服務都只需要這三樣東西：金鑰、地址、模型名。換服務商只要改這三個變數的值。