写了几年代码之后，我越来越觉得：很多新手根本不是被“AI 应用开发”这个方向劝退的，而是被“装环境”三个字劝退的。明明照着教程一步一步点，最后却在第一行import requests上看到红色报错，那种挫败感能把一整天的学习热情浇灭。这篇《30天从零玩转AI应用开发》第 3 篇，我就把“Python 环境搭建 + API 请求重构”两件事合在一起讲透。目标很直接：让你从零开始，把开发环境搭到“零报错”，然后亲手写出第一段真正能调通 API 的 Python 代码——不是复制粘贴就跑不动的那种，而是你理解每一行在干嘛、出了问题也知道去哪查的那种。

1. 别急着写代码，先搞懂“Python 环境”这四个字到底包含什么

1.1 你遇到的“环境坏了”，八成不是 Python 坏了

先说一个我帮人排查环境时最常看到的误解：很多人以为 Python 环境就是“电脑里装了一个叫 Python 的软件”。一听“环境搭建失败”，第一反应就是“重装一遍”。但真正的 Python 环境，其实是四样东西叠在一起：

• Python 解释器：真正负责执行.py文件的程序，也就是你安装的 Python 本体。
• 第三方库：像requests、python-dotenv这类别人写好的工具包，靠pip安装。
• 虚拟环境：把当前项目的第三方库隔离到一个独立文件夹里，不让它们污染系统全局。
• 环境变量 PATH：告诉终端“你在哪个目录输入 python，我都能找到解释器”。

这四个环节里，任何一环出了问题，你都会觉得“Python 坏了”。但绝大多数情况下，Python 本身没坏，坏的是“路径不对”“库没装进当前环境”“版本对不上”这些外围问题。所以排查环境问题的第一步永远是搞清楚：你现在用的是哪个 Python？它装在了哪里？

在终端里依次敲这三条命令，基本能定位 80% 的问题：

python --version python -m pip --version where python # Windows 用 where，macOS/Linux 用 which python

如果你发现自己装着不止一个 Python，比如系统自带的、某个软件内置的、官网安装包装的，混在一起，那后面所有报错都变得不可预测。这也是我为什么建议：在正式动手前，先花五分钟确认“唯一版本”。

1.2 为什么“我明明照着教程做了”还是失败

“我明明照着教程做了”这句话我听了太多次。最后发现，原因通常不在你的操作，而在于教程默认的环境和你实际的环境不一样。最典型的三个差异：

• 教程作者用的是 Python 3.11，你装的是 3.8——某些第三方库在高版本上有新写法，低版本不支持；
• 教程在虚拟环境里执行命令，你在全局环境里执行——库装到了不同的地方；
• 教程用的终端已经激活了环境，你的终端没有——于是python指向的解释器都不一样。

所以，不存在“万能教程”。你能做的是先掌握一套“确认环境”的标准动作，把它变成肌肉记忆。无论看谁的教程，先把python --version和pip show requests这类检查命令跑一遍，确认环境一致了再继续。以后每一次遇到奇怪报错，都先回到这套检查动作，而不是急着重装。

2. 三件套装完再动手：解释器、虚拟环境、依赖清单

2.1 安装解释器时那个 “Add to PATH” 勾选框，真的是命门

只要是 Windows 用户，安装 Python 官方安装包的时候，第一步就会看到一排选项，最底下有一个容易忽略的勾选框：Add python.exe to PATH。这个框默认是不勾的，很多新手直接点 Install Now，装完全家桶，开开心心打开终端敲python，结果等来一句“不是内部或外部命令”。

原因很简单：PATH 就是系统的“通讯录”，你告诉终端 python 在哪，它才找得到。没勾选等于没给解释器“报名”，系统自然不知道去哪找它。这时候不需要把电脑翻个底朝天，两个办法任选：

• 重新运行安装包，选择 Modify，把 Add python.exe to PATH 勾上，再完成安装；
• 手动配置：到“系统属性 → 环境变量 → Path”里，把 Python 的安装目录和Scripts子目录添加进去，比如C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\和它下面的Scripts\。

macOS 和 Linux 用户一般没这个困扰，官方包会处理好软链接。这里我额外说一句版本建议：新手选 Python 3.10 到 3.12 这一档就好。太老的版本，新的第三方库可能已经放弃支持；太新的版本，个别库的预编译包没跟上，容易遇到“编译失败”的奇怪问题。3.11 或 3.12 是当前最稳妥的选择。

2.2 虚拟环境 venv：每个项目一个独立工作台

装好解释器之后，下一步就是创建虚拟环境。很多人觉得这步多余：“我直接 pip install 不就行了？”能行，但后患无穷。你装十个项目，十个项目的依赖全堆在系统全局里：项目 A 要 requests 2.28，项目 B 要 requests 2.31，版本冲突时你会被折磨到怀疑人生。虚拟环境就是把每个项目的第三方库关进各自的“独立房间”，互不干扰。

建环境的命令非常简单，在项目目录下执行：

python -m venv .venv

这里我坚持用python -m venv而不是直接venv，因为它会显式使用你当前指定的解释器，避免系统里出现多个 Python 时选错人。创建完.venv文件夹后，还要“激活”它，让后续的python和pip命令都指向这个环境：

# Windows 终端（CMD 或 PowerShell） .venv\Scripts\activate # macOS / Linux source .venv/bin/activate

激活成功最明显的标志，是命令行前面多了一个(.venv)前缀。看到它，说明你现在所有操作都发生在独立环境里。以后每天开始写代码，第一件事就是激活环境，而不是直接双击一个.py文件。

2.3 requirements.txt：把依赖清单锁死

环境是临时的，但项目要长期维护。你不能指望别人手动一个个安装所有依赖，所以需要一个清单文件：requirements.txt。养成两个习惯：

# 在当前环境里安装本次需要的库 pip install requests python-dotenv # 把这个环境的所有依赖导出成清单 pip freeze > requirements.txt

以后换电脑、别人拉你的代码，只需要一行命令还原：

pip install -r requirements.txt

还有一个新手容易忽略的细节：pip默认下载源在国外公共服务器，国内网络环境下载第三方库经常慢到让人抓狂，甚至直接超时。解决办法是把下载源切到国内公共镜像。Windows 用户在用户主目录下新建一个pip.ini文件，macOS/Linux 用户新建~/.pip/pip.conf，写入：

[global] index-url = https://pypi.tuna.example.com/simple

镜像源的公共地址网上随便一搜就有，选一个离你近的、能访问的即可。切换完以后，pip install requests通常几秒钟就能完成，这也是“零报错”体验的重要一环。

3. “重构”到底是重构什么：从能用的脚本到能长期维护的模块

3.1 第一版代码：能跑，但我劝你别这么交作业

有了环境，就可以写 API 请求了。我见过太多新手的第一版请求代码长这样：

import urllib.request api_key = "sk-xxxxx你的密钥" url = "https://api.example-ai.com/v1/responses" data = '{"model": "example-model", "messages": [{"role": "user", "content": "你好"}]}'.encode("utf-8") req = urllib.request.Request( url, data=data, headers={ "Authorization": "Bearer " + api_key, "Content-Type": "application/json", }, ) resp = urllib.request.urlopen(req) print(resp.read().decode("utf-8"))

它能跑通，但这代码有几个明显问题，恰恰是“重构”要解决的：

• API Key 硬编码：密钥直接写在代码里，将来代码上传到 Git 仓库，等于把密码公开；
• 没有超时控制：网络一卡，脚本可能永远卡在那里不动；
• 没有异常处理：请求失败、返回 401、密钥错了，统统变成一串难懂的报错直接让程序崩溃；
• 不可复用：换一个请求，就必须复制粘贴改一遍，几个接口下来代码就爆炸了。

所谓“API 请求重构”，不是把代码改得花哨，而是把它从“一次性脚本”升级成“可复用、可维护、可排查”的小模块。

3.2 第二版：用 requests 加环境变量管理密钥

第一件事，换掉urllib。用它写请求不是不行，但你需要手写太多底层细节。requests是当前 Python 生态里调用 HTTP 接口最主流的库，它的语义更清晰，超时、Session、异常体系都做得更顺手。打个比方：urllib像自己买菜做饭洗锅，requests像用半成品菜包，省心且稳定。

第二件事，把密钥从代码里挪出来。新建一个.env文件，内容很简单：

EXAMPLE_AI_API_KEY=sk-xxxxx你的密钥

然后在代码里用python-dotenv加载它：

import os from dotenv import load_dotenv load_dotenv() # 读取当前目录下的 .env api_key = os.getenv("EXAMPLE_AI_API_KEY")

这样密钥就和代码分开了。以后不管谁拿到你的代码，看到的只是os.getenv(...)，真正的密钥只躺在你本地。这里有个红线要强调：一定要把.env加进.gitignore文件，否则你下次提交代码时，密钥又会跟着文件一起传上去。.gitignore里至少写这四行：

.env .venv/ __pycache__/ *.pyc

3.3 第三版：封装成函数，团队代码风格从这里开始

环境变量解决安全，requests 解决易用性，但还没解决“复用”。所以第三版，把它封装成一个函数：

import os import time import requests from dotenv import load_dotenv load_dotenv() API_KEY = os.getenv("EXAMPLE_AI_API_KEY") API_URL = "https://api.example-ai.com/v1/responses" def chat_once(messages, model="example-model", timeout=20): headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } body = {"model": model, "messages": messages} try: resp = requests.post(API_URL, json=body, headers=headers, timeout=timeout) resp.raise_for_status() # 状态码不是 2xx 时主动抛异常 return resp.json() except requests.Timeout: print("请求超时，请检查网络或调大 timeout 参数") return None except requests.RequestException as exc: print(f"请求失败：{exc}") return None

这一版有几个关键设计值得说：

• timeout=20是必填项：显式给请求设置最大等待时间，防止网络异常时程序无限挂起；
• json=body代替手动字符串：requests 会自动把字典转为 JSON，并帮你设置正确的 Content-Type，少了一整类低级 bug；
• resp.raise_for_status()：HTTP 状态码只要不是 2xx，立刻抛出异常，你不需要自己判断 200 还是 201；
• 捕获requests.RequestException：这是 requests 所有网络异常的基类，捕获它就能覆盖超时、连接失败、证书错误等绝大多数情况。

到这里，“重构”才算真正完成。你手里的不再是“写给机器看的脚本”，而是“给别人也能看懂、以后自己也能维护”的小模块。

4. 零报错版 API 请求模板：直接照着抄

4.1 项目文件结构

空讲太多不如给一份可以直接落地的模板。我建议你新建项目时，文件结构保持这样：

my-ai-app/ ├── .env # 存放密钥，不提交到 git ├── .gitignore # 忽略敏感文件和虚拟环境 ├── requirements.txt # 依赖清单 ├── api_client.py # API 请求封装模块 └── main.py # 使用示例

每个文件各司其职。.env只放密钥，api_client.py只放请求逻辑，main.py只放业务调用。新手最容易犯的毛病是把所有代码塞进一个文件，最后几百行堆在一起，改一处崩三处。

4.2 api_client.py 完整代码

这个文件我尽量写得通用，你把自己的接口地址、密钥字段名替换一下就能用：

import os import time import requests from dotenv import load_dotenv load_dotenv() API_KEY = os.getenv("EXAMPLE_AI_API_KEY") API_URL = os.getenv("EXAMPLE_AI_API_URL", "https://api.example-ai.com/v1/responses") DEFAULT_MODEL = "example-model" def call_ai_api(messages, model=None, timeout=30, max_retries=2): """ 统一的 AI API 请求入口。 :param messages: 聊天消息列表，格式为 [{"role": "user", "content": "你好"}] :param model: 模型名称，默认使用 DEFAULT_MODEL :param timeout: 单次请求超时时间，单位秒 :param max_retries: 最多重试次数，简单网络抖动时能自动恢复 :return: 解析后的 JSON 响应；失败返回 None """ if not API_KEY: print("未找到 API Key，请检查 .env 文件是否配置了 EXAMPLE_AI_API_KEY") return None headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } body = { "model": model or DEFAULT_MODEL, "messages": messages, } for attempt in range(max_retries + 1): try: resp = requests.post(API_URL, json=body, headers=headers, timeout=timeout) resp.raise_for_status() return resp.json() except requests.Timeout: print(f"第 {attempt + 1} 次请求超时") time.sleep(1) except requests.RequestException as exc: print(f"请求异常：{exc}") # 如果是密钥或权限问题，重试一百次也一样，直接跳出 if resp is not None and resp.status_code in (401, 403): print("看起来是鉴权失败，请检查 API Key 是否有效") break time.sleep(1) return None

这个模板里我故意加了max_retries参数。真实世界里，网络不可能永远稳定，偶尔一次超时并不代表你的代码有问题，自动重试一次往往就好了。但注意：不要对鉴权失败做无限重试。401、403 是密钥本身的问题，重试只是浪费时间和接口额度。

4.3 调用示例与预期输出

写完封装，再写一个最小调用入口：

# main.py from api_client import call_ai_api message = {"role": "user", "content": "你好，请用一句话介绍你自己"} response = call_ai_api([message]) if response: print("调用成功，返回内容如下：") print(response) else: print("调用失败，请根据上方提示排查")

在终端运行：

python main.py

如果一切正常，你会看到类似这样的一段 JSON 结构输出（具体字段取决于你用的接口）：

{ "id": "xxxxxx", "object": "response", "model": "example-model", "content": "我是你的 AI 助手，很高兴认识你。" }

到这里，你已经有了一套“能跑且不容易跑崩”的 API 请求代码。不过“零报错”不能只靠运气，还需要知道报错出现以后怎么对症下药。

5. 新手最容易撞的五个报错，完整修复路径

5.1 ModuleNotFoundError: No module named 'requests'

这是最容易遇见、也最好修的一个——程序运行找不到 requests 库。先别急着pip install requests，否则你可能会装进另一个环境里。按顺序排查：

# 1. 确认当前激活了哪套环境 where python # 2. 在这个环境里看 requests 装没装 pip show requests

如果pip show requests没有输出，说明没装；如果装了但代码还是报错，多半是你激活的环境和运行代码的解释器不一致。统一操作是：激活虚拟环境后，用python -m pip install requests，再运行代码。注意用python -m pip而不是直接pip，因为前者能保证 pip 和你正在用的 Python 绑定在同一个环境里。

5.2 SSLError 证书验证失败

requests默认会验证 HTTPS 证书，这是为了保护你，而不是故意刁难你。如果调用的是正规服务商接口，证书一般没问题。真正会触发这个错误的情况，往往是接口使用了自签名证书，或者公司内网有特殊证书体系。

新手最容易踩的坑是看到报错就去搜 “关闭证书验证”，然后代码里写verify=False。能跑，但我强烈不建议一上来就这么干，这等于把安全校验整个关掉，万一中间有数据篡改，你完全无感。

正确做法分两步：

• 如果你访问的是权威公共服务，先检查本机时间是否正确——系统时间不对，证书“有效期”判断就会出错，这是最让人意想不到的一个原因；
• 如果是自建服务或自签名证书，把证书文件下载到本地，请求时显式指定：requests.post(..., verify="/path/to/server-cert.pem")。

只有在本地调试、实在找不到证书来源时，才允许临时用verify=False，并且一定要在注释里写明原因，提醒自己上线前删掉。

5.3 Windows 控制台打印中文乱码

代码里print中文，Windows 自带终端经常显示成乱码或直接报UnicodeEncodeError。这不是 Python 的问题，而是控制台默认编码导致的。Windows 终端默认编码常常是 GBK，而 Python 3 的字符串是 Unicode，两者不对齐就乱了。

最简单的解决办法，在命令行运行前设置环境变量：

set PYTHONIOENCODING=utf-8

或者在代码文件最顶部写两行：

import sys import io sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")

不过更推荐的做法是：在系统环境变量里新增PYTHONIOENCODING=utf-8，一劳永逸。这样不管谁来运行你的脚本，控制台输出中文都是稳定的。

5.4 401 / 403 / 429：三类 HTTP 状态码，三种不同修法

这三个状态码几乎占据了 API 调试期 90% 的“请求失败”原因。注意，它们不是环境问题，而是请求本身的问题：

排查这类问题有个笨办法但很有效：先直接用调试工具手动发一次请求，确认 Key 有效、参数格式没问题，再回来查代码。如果手工请求也报 401，那就不是代码的事，去服务商后台重新生成一个 Key 就好。很多新手在代码里反复折腾半天，最后发现是复制 Key 时多了一个空格，这种低级错误最不值得花时间。

5.5 项目路径带中文和空格，各种“灵异事件”

最后这个最隐蔽。Windows 用户尤其容易中招：项目文件夹叫AI学习项目、我的 第一个程序，路径里带中文和空格，导致虚拟环境激活失败、pip 安装报错、运行时路径拼接出错。表现还特别“随机”，有时候能跑，有时候不能跑，毫无规律。

我的建议很粗暴也很实用：所有项目路径统一用英文、数字、下划线，中间不要加空格。比如ai_study_project、my_ai_app。这不是歧视中文，而是为了让工具链少一个可变的干扰因素。等你以后熟练了，再去处理“带中文路径”的兼容问题也来得及，新手期没必要在这里挑战自我。

到这里，环境、请求代码、报错修复三条线都已经铺完。最后用一次完整流程把这套东西串起来，你会更明显地感觉到“从零到零报错”其实只是一套固定动作。

6. 一次完整调试流程：把整套环境从零跑到通

新建一个干净的项目目录，照着下面这套动作走一遍：

mkdir ai_study_project cd ai_study_project # 创建虚拟环境 python -m venv .venv # 激活虚拟环境 # Windows: .venv\Scripts\activate source .venv/bin/activate # 安装依赖 pip install requests python-dotenv # 保存依赖清单 pip freeze > requirements.txt # 创建 .env 文件，填入你的密钥 # 创建 .gitignore，写入 .env / .venv / __pycache__/ # 把 api_client.py 和 main.py 放进项目目录 # 运行 python main.py

这套流程最大的好处是“上下文简单”：项目目录下只有你自己的文件和.venv，出问题你一眼就能看到是哪一步。我不止一次看到有人搞错了终端目录，在一个完全无关的文件夹里激活了虚拟环境，然后对着屏幕怀疑人生。所以每次跑不通，先抬头看终端当前路径。

最后分享一个我个人坚持了很久的习惯：新建项目，第一步永远是python -m venv .venv，第二步永远是激活环境，第三步才是写代码。顺序一旦固定，后面遇到的报错种类会少一大半。至于 API 请求模块，我始终建议先花十分钟把timeout、raise_for_status、os.getenv这三个知识点记牢。它们解决的是“程序会挂、错误看不清、密钥泄露”这三大新手灾难。等这三件事变成了肌肉记忆，你再去看网上那些更复杂的封装方案，会发现思路都是一样的：把代码组织成别人能读、自己能改、出问题能查的样子。

下一篇可以聊怎么把请求到的响应数据处理得更顺手，或者直接拿一个真实场景把这里封装好的call_ai_api用起来。先把今天这套模板跑通，比收藏一百篇教程都有用。