Agent 开发环境准备：虚拟环境与解释器

环境准备

手写 Agent 之前先把 Python 环境理顺: 一个独立的虚拟环境, 装好依赖, 让编辑器和终端都用对解释器, 最后跑一次自检脚本确认能调通模型.

📌 下文命令里的 <项目目录> 指你放这个练习的目录, 换成自己的路径即可.

为什么用独立虚拟环境

系统全局 Python 里通常装着一堆别的项目的包, openai 这类库的版本会互相牵扯. 项目用独立 venv, requirements.txt 才有意义, 换一台机器也能一次装齐.

创建虚拟环境

Windows 环境

在 PowerShell 里进入代码目录:

cd "<项目目录>"
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

不激活也能用: 直接调 .venv\Scripts\python.exe, 省得被 PowerShell 执行策略拦. 想激活就用:

.\.venv\Scripts\Activate.ps1

被拦的话先跑一次 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

让 VS Code 用这个解释器

Ctrl + Shift + P → Python: Select Interpreter → 输入解释器路径... → 粘贴 .venv\Scripts\python.exe 的绝对路径.

下拉列表里通常看不到它: venv 埋得比较深, 路径还可能带中文, 自动扫描不会下探这么远. 手动填路径最省事, 选一次就会记住, 右下角状态栏会显示 .venv.

验证解释器

python -c "import sys; print(sys.executable)"

输出的路径里要带 .venv\Scripts\python.exe. 显示的是系统 Python 路径, 说明没选对解释器, 或者终端是选之前开着的——新开一个终端再试.

WSL 环境

Windows 的 .venv 和 WSL 的虚拟环境分开使用, 建议把 Linux 环境放到家目录下, 例如 ~/.venvs/agent.

首次创建与安装依赖

以下命令在 Ubuntu 的 Bash 终端执行. 如果创建环境时提示 ensurepip is not available, 先安装虚拟环境组件; 已经装过就跳过:

sudo apt-get update
sudo apt-get install -y python3-venv

进入代码目录, 创建并激活环境, 再安装项目依赖:

cd "<项目目录>"

python3 -m venv ~/.venvs/agent
source ~/.venvs/agent/bin/activate

python -m pip install -r requirements.txt

创建环境和安装依赖通常只做一次; 依赖清单更新后再安装. 关闭终端不会删除虚拟环境或已安装的包.

每次打开终端后激活

source ~/.venvs/agent/bin/activate

激活只影响当前终端: 它会把虚拟环境的 bin 目录放到 PATH 前面, 让 python 和 pip 优先使用这个环境里的版本. 新终端需要重新激活.

📌 文件名是 activate, 最后有一个 e. 写成 activat 会报 No such file or directory, 环境也不会激活.

验证当前解释器:

python -c 'import sys; print(sys.executable)'
python -m pip --version

路径应指向 ~/.venvs/agent/bin/python 对应的绝对路径. 如果显示 /usr/bin/python3, 说明还在用系统 Python; 激活成功后提示符通常也会显示 (agent).

退出与直接运行

deactivate

退出只取消当前终端的激活状态, 不删除环境. 也可以不激活, 直接指定虚拟环境里的解释器:

~/.venvs/agent/bin/python -c 'import sys; print(sys.executable)'

命令格式固定, 换项目时改环境路径即可. 创建用的是环境目录 ~/.venvs/agent, 激活用的是目录中的脚本 ~/.venvs/agent/bin/activate.

检查环境

Windows 终端:

cd "<项目目录>"
python 00-check-env.py

WSL 终端:

source ~/.venvs/agent/bin/activate
cd "<项目目录>"
python 00-check-env.py

正常输出分几段, 逐段对:

输出	表示
BASE_URL = https://api.deepseek.com	地址对了
MODEL = deepseek-flash	模型名对了
连接成功，可用模型：[...]	网络通, 凭证可用
对话成功：'通了'	真的能出结果

看到「环境没问题」就算过了.

💡 每跑一次会真实调用一次模型, 费用可以忽略, 但别写成循环反复跑.

常见报错

现象	原因	处理
ensurepip is not available	WSL 缺少虚拟环境组件	安装 python3-venv 后重新创建环境
激活时报 No such file or directory	路径或 activate 拼写错误	核对路径, 确认末尾有 e
WSL 提示 python 找不到	虚拟环境未激活	先执行 source 激活命令
/usr/bin/python3: No module named pip	调用了系统 Python	激活后用 python -m pip
Invalid port: ':1]'	NO_PROXY 里有 [::1]	去掉方括号再试
APIConnectionError	代理没开或网络不通	确认代理端口在跑
提示 MODEL 不在列表里	模型名写错	改成 deepseek-flash

收工自检

• 解释器指向当前系统的独立环境: Windows 的 .venv 或 WSL 的 ~/.venvs/agent
• python 00-check-env.py 输出「环境没问题」
• git status 里看不到 .venv

更新记录: 2026-11-02 发布版, 去掉本地路径和凭证配置细节, 保留虚拟环境, 解释器选择与自检部分.