跳到正文
AI Agent 教程 · 卷 0 · 学习地图

环境准备(一):机器、账户与终端

本合集目录
本章目录

单册说明:本文件是「AI Agent 完整教程」卷 0 的第 3 章,可独立阅读。 前置:无(但建议先读第 2 章的七层模型,理解"为什么要装这些东西")。

项 内容
所属卷 卷 0 · 学习地图(第 3 / 6 章)
前置章节 无(建议先读第 2 章)
本章产出 一个干净的实验目录 ai-agent-lab + 三个配好的环境变量
对应代码 code/check_env.py(本章末用它验证)
配图 图 0-6(三条路线)、图 0-7(实验目录与权限)
读完的判定 能打开终端、进入实验目录、说出三个环境变量各管什么

3.1 先确定路线,再决定要准备什么

同样是"学 Agent",不同路线的环境要求差别很大。先选路线,别盲目装东西。

三条路线:先选路,再决定要准备什么

路线 模型跑在哪 设备要求 数据是否出本机 适合谁
云端 API 服务商的服务器 只要能上网,8GB 内存够 会发到服务商 绝大多数人,建议从这里开始
客户端 云端为主 同上,另需装一个软件 取决于客户端 想尽快用起来的人
本地模型 你自己的显卡 16GB 内存 + 8GB 以上显存 不出机器 数据敏感、断网环境、想省钱

建议:先走云端 API,把整条链路跑通。 本地模型是"当你明确知道自己需要它"时的选择,不是入门的第一步——它会让你在第一周就卡在显存和环境依赖上。

判断标准很实在:如果你现在连一次 API 调用都没跑通过,本地模型一定不是你的下一步。 先把云端跑通,你才知道"模型服务"这件事长什么样,后面换本地时才有对照物。


3.2 系统与硬件底线

项 最低 舒适 说明
系统 Windows 10 / macOS 12 / 主流 Linux Windows 11 / macOS 14+ 太老的系统会遇到 TLS 与编码问题
内存 8 GB 16 GB 本地跑模型要 32 GB 起
硬盘 5 GB 空闲 50 GB 模型文件很大,动辄 4–8 GB
显卡 不需要 8 GB 显存以上 只有本地模型路线需要
网络 能访问你的模型服务 稳定、低延迟 见 3.8 代理部分

3.3 账户清单

必需一个:模型服务账号。选择标准只有三条——能不能连上、额度够不够、模型名是什么。

类型 特点 注意
海外官方服务 模型最全、更新最快 需要网络条件;按量计费,注意额度
国内官方服务 直连稳定、有发票、合规 模型名与海外不同,代码里要改 AI_MODEL
聚合/中转服务 一个 Key 调多家模型 稳定性参差;不要把重要数据交给不明来源的中转

可选:GitHub 账号(存代码、找开源项目);客户端账号(部分客户端需要登录)。

关于密钥的一条硬规则:不要用别人的 Key,也不要把自己的 Key 发给任何人,包括发给我。 任何要求你"把 Key 贴进来测试"的场景都是风险场景。

选账号时最容易忽略的一件事:确认你拿到的模型名到底是什么。三家服务商的命名规则完全不同,同一个模型在不同平台可能叫 gpt-4o-mini、gpt-4o-mini-2024-07-18 或别的名字。这个名字就是你后面要填进 AI_MODEL 的值——填错的典型症状是 404(见 4.6 节)。


3.4 终端最小知识

后面所有命令都在终端里敲。不需要学 shell 编程,会这五个就够:

目的 Windows (PowerShell) macOS / Linux (bash/zsh)
我在哪 pwd pwd
看目录里有什么 ls 或 dir ls
进目录 cd 路径 cd 路径
回上一级 cd .. cd ..
运行 Python 脚本 python 脚本名.py python3 脚本名.py

怎么打开终端:

  • Windows:开始菜单搜 PowerShell(或 Windows Terminal),右键"以普通用户身份运行"即可,不需要管理员权限;
  • macOS:Command + 空格 搜 终端,或在 VS Code 里按 Ctrl + ` 打开集成终端。

一个必须理解的概念:路径分绝对和相对。

  • 绝对路径:从根开始写全,如 C:\Users\你\ai-agent-lab(Windows)或 /Users/你/ai-agent-lab(macOS);
  • 相对路径:相对"我现在在哪",如 inbox/notes.md、../output。

第 5 章的 Agent 会被限制只能使用相对路径,而且必须落在实验目录内——这不是多此一举,是防止它把文件写到你的系统目录里(5.3 节有实测)。


3.5 四个路径坑(都真实踩过)

坑 现象 处理
中文路径 某些工具打开项目报错、乱码、找不到文件 实验目录用纯英文,如 ai-agent-lab;中文只放在文件名和内容里
空格路径 命令被截断,报"找不到 xxx" 路径带空格时用引号包住:cd "D:/my project"
CRLF 换行 用 Windows 写的脚本在 Linux/远端跑,报 bad interpreter 或奇怪的 \r 错误 编辑器里把换行设为 LF;或用 .editorconfig 统一
PowerShell 执行策略 运行 .ps1 脚本提示"禁止运行脚本" 不要改系统策略,改用 python xxx.py 或 .cmd/.bat 绕开

这四个坑的共同点是:它们在报错信息里从不直接说"是路径问题"。所以遇到"明明文件在那儿却找不到",先看路径有没有中文、空格、换行符。


3.6 密钥怎么放

密钥(API Key)本质是钱。放错地方的代价很直接:被别人拿走刷额度。

三种放法,从差到好:

放法 安全性 说明
直接写死在代码里 ❌ 最差 一旦分享代码或传到 GitHub,等于公开
写在配置文件里并入版本管理 ❌ 差 同上,历史记录里还会有
放在环境变量里 ✅ 推荐 代码里只读变量名,不出现值

设置环境变量:

# Windows PowerShell(setx 写入用户级,永久生效,但要重开终端)
setx AI_API_KEY "sk-你的密钥"
setx AI_BASE_URL "https://api.openai.com/v1"
setx AI_MODEL "gpt-4o-mini"

# macOS / Linux(写入当前 shell 会话;要永久生效需追加到 ~/.zshrc 或 ~/.bashrc)
export AI_API_KEY="sk-你的密钥"
export AI_BASE_URL="https://api.openai.com/v1"
export AI_MODEL="gpt-4o-mini"

三个细节,错了会查很久:

  1. setx 之后必须重开终端,当前窗口读不到新值;
  2. Windows 下不要在值里加引号后再带空格,setx AI_API_KEY "sk-x " 会把尾部空格也存进去,导致 401;
  3. 如果你用 export 但每次新开终端都失效,说明你写入的是当前会话,需要写进 shell 的启动文件。

验证是否生效:

# Windows
echo $env:AI_API_KEY

# macOS / Linux
echo $AI_API_KEY

三个变量各管什么(这张表在第 4 章会再用到):

变量 含义 配错的典型症状
AI_BASE_URL 去哪找服务(地址) 404 / 连不上
AI_API_KEY 你是谁(凭据) 401 / 403
AI_MODEL 用哪个模型(型号) 404 / 400

3.7 目录约定

本教程统一使用一个实验目录,好处是:所有代码、数据、产物都在一处,删掉就等于清零,不会污染你的电脑。

实验目录:把"权限"设计进文件夹

ai-agent-lab/                 ← 实验根目录(LAB)
├── inbox/                    ← 放待处理的东西:待整理的文件、待读的文档
│   ├── notes.md
│   └── data.csv
├── output/                   ← Agent 只能往这里写
│   └── (Agent 的产物)
└── code/                     ← 本教程的脚本
    ├── check_env.py
    ├── hello_model.py
    └── first_agent.py

默认位置:~/ai-agent-lab(即 Windows 的 C:\Users\你的用户名\ai-agent-lab,macOS 的 /Users/你的用户名/ai-agent-lab)。想换位置,设一个环境变量 AI_LAB 即可,三个脚本都读它。

为什么把 inbox 和 output 分开:这是权限设计,不是整理癖。第 5 章的 Agent 对 inbox 只有读权限,对 output 才有写权限。这样即使它判断错了,最坏结果也只是在 output 里多一个文件。

建目录的命令(两条选一条,任选平台):

# 方式一:让脚本帮你建(推荐,连演示数据一起准备)
python first_agent.py --setup

# 方式二:手工建
mkdir -p ~/ai-agent-lab/inbox ~/ai-agent-lab/output ~/ai-agent-lab/code

3.8 代理与网络

能直连就不走代理。只有在确认直连不通时,才配代理,否则会引入新的变量(很多"连不上"其实是代理配错)。

# Windows PowerShell
setx HTTPS_PROXY "http://127.0.0.1:7890"
setx HTTP_PROXY  "http://127.0.0.1:7890"
setx NO_PROXY    "localhost,127.0.0.1,api.weixin.qq.com"

# macOS / Linux
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"

两个坑:

  • 端口写错:7890、7897、1080、10809 是不同软件的不同默认端口,别照抄。看你代理软件里写的"混合端口/HTTP 端口"是多少;
  • NO_PROXY 没设:本地服务和某些国内接口被强行绕进代理,表现为"明明没墙却连不上"。本地地址一律加进 NO_PROXY。

验证方法(比 ping 有用):

curl -I https://api.openai.com/v1/models
  • 返回 401 → 网络是通的(只是没带密钥),这是好消息;
  • 返回 000 / 超时 / 证书错误 → 网络层有问题,先解决网络,别改代码。

为什么 401 是好消息:它证明你已经和服务端握上手了,只是没出示凭据。而 000 说明连话都没说上。这两种情况的排查路径完全不同——这个判断法在第 4 章会展开成一张四步定位图。


3.9 本章验收 + 排错表

验收(应当会):

  1. 应当会打开终端,用 cd 进入你的实验目录,并说出当前路径;
  2. 应当会设置并验证三个环境变量(AI_API_KEY / AI_BASE_URL / AI_MODEL);
  3. 应当会解释为什么密钥不能写进代码,以及为什么 inbox 和 output 要分开。

排错表:

症状 最可能原因 修法
python 不是内部或外部命令 未安装或未加入 PATH 装 Python 3.9+,安装时勾选 "Add to PATH"
setx 后读不到变量 没重开终端 关掉窗口重开
echo $AI_API_KEY 有值但脚本报 401 值里带空格/引号/换行 重新 setx,值不要带引号,别多敲空格
中文目录下脚本报编码错误 路径含中文 换纯英文目录
curl 返回 000 网络/代理/DNS 先直连试,再配代理;用 --noproxy "*" 排除代理干扰
证书错误 CERTIFICATE_VERIFY_FAILED 代理做了证书拦截、系统时间不对 系统时间校准;代理放行该域名;必要时换直连

3.10 下一步

环境打底完成,接着打通三条链路 → 第 4 章 环境准备(二):三条链路打通

回看:第 2 章 七层模型 · 返回导读