准备开发环境和 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 接口的服务都只需要这三样东西：密钥、地址、模型名。换服务商只要改这三个变量的值。