【Agent从入门到实践】28 开发第一个Agent——开发准备：环境搭建（Python、依赖库、大模型API密钥）

文章目录

- 前言
- 一、第一步：安装Python（关键：选对版本！）
- - [1. 下载Python（分系统操作）](#1. 下载Python（分系统操作）)
  - [2. 验证是否安装成功](#2. 验证是否安装成功)
  - [3. 新手避坑：环境变量配置](#3. 新手避坑：环境变量配置)
- 二、第二步：配置依赖库（Agent开发必备）
- - [1. 创建虚拟环境（可选但推荐）](#1. 创建虚拟环境（可选但推荐）)
  - [2. 一键安装核心依赖库](#2. 一键安装核心依赖库)
  - [3. 依赖库说明（知道用啥、为啥用）](#3. 依赖库说明（知道用啥、为啥用）)
  - [4. 避坑：pip安装慢/失败怎么办？](#4. 避坑：pip安装慢/失败怎么办？)
  - [5. 验证依赖是否安装成功](#5. 验证依赖是否安装成功)
- 三、第三步：获取大模型API密钥（关键：Agent的"大脑"）
- - [选项1：获取OpenAI API密钥（推荐新手）](#选项1：获取OpenAI API密钥（推荐新手）)
  - - 步骤：
    - 注意事项：
  - 选项2：获取国产大模型API密钥（无需科学上网）
  - - 通义千问（推荐）：
    - 智谱清言：
  - 选项3：本地大模型（进阶，无需API密钥）
- 四、第四步：配置环境变量（安全存储API密钥）
- - [1. 创建.env文件](#1. 创建.env文件)
  - [2. 写入API密钥](#2. 写入API密钥)
  - [3. 验证.env文件是否生效](#3. 验证.env文件是否生效)
- 五、第五步：测试大模型调用（确保环境能跑通）
- - [测试1：调用OpenAI GPT-3.5](#测试1：调用OpenAI GPT-3.5)
  - 测试2：调用通义千问（如果用国产模型）
  - 运行测试代码
- 六、常见问题：避坑指南（新手必看）
- - [1. Python版本不对，依赖安装失败？](#1. Python版本不对，依赖安装失败？)
  - [2. 调用大模型提示"API key is invalid"？](#2. 调用大模型提示“API key is invalid”？)
  - [3. 调用OpenAI提示"Connection error"？](#3. 调用OpenAI提示“Connection error”？)
  - [4. 依赖库版本冲突？](#4. 依赖库版本冲突？)
  - [5. Windows系统激活虚拟环境提示"权限不够"？](#5. Windows系统激活虚拟环境提示“权限不够”？)
- 七、总结：环境搭建完成，准备开发Agent！

目前国内还是很缺AI人才的，希望更多人能真正加入到AI行业，共同促进行业进步。想要系统学习AI知识的朋友可以看看我的教程http://blog.csdn.net/jiangjunshow，教程通俗易懂，风趣幽默，从深度学习基础原理到各领域实战应用都有讲解。

前言

各位小伙伴，前面咱们把Agent的记忆系统讲透了，现在终于要进入实战环节------开发你的第一个Agent！但动手前，得先把"地基"打牢：环境搭建。这一步看似简单，却有很多新手踩坑：Python版本不对、依赖库冲突、API密钥配置错误......今天咱们就用最通俗的语言，手把手带你搞定所有准备工作，确保后续开发一路顺畅！

核心准备3件事：

安装Python（选对版本，避免兼容问题）；
配置依赖库（Agent开发必备，一键安装）；
获取大模型API密钥（OpenAI+国产模型，按需选择）。

全程跟着做，5分钟就能搞定，之后直接复制代码就能跑Agent！

一、第一步：安装Python（关键：选对版本！）

Agent开发依赖的很多库（比如LangChain、chromadb）对Python版本有要求，推荐安装Python 3.10或3.11版本（最稳定，兼容性最好），别装3.9及以下（可能缺依赖），也别装最新的3.12+（部分库还没适配）。

1. 下载Python（分系统操作）

Windows系统：

打开官网：https://www.python.org/downloads/
下滑找到"Python 3.11.9"（或3.10.14，都是LTS长期支持版），点击"Download Windows Installer"；
下载后打开安装包，务必勾选"Add Python.exe to PATH"（自动配置环境变量，否则后续命令行用不了）；
点击"Install Now"，等待安装完成（默认路径即可，不用改）。

Mac系统：

方式1（推荐）：用Homebrew安装（先装Homebrew，打开终端输入：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"）；
终端输入：brew install python@3.11（自动安装3.11版本，且配置环境变量）；
方式2：官网下载安装包（https://www.python.org/downloads/），双击安装，步骤和Windows类似。

Linux系统（Ubuntu/Debian）：

终端输入：sudo apt update（更新软件源）；
输入：sudo apt install python3.11 python3.11-pip（安装Python 3.11和pip）。

2. 验证是否安装成功

打开终端（Windows按Win+R，输入cmd；Mac/Linux直接打开终端）；
输入：python --version（Windows）或python3 --version（Mac/Linux）；
如果显示"Python 3.11.9"（或3.10.x），说明安装成功！

3. 新手避坑：环境变量配置

如果输入python --version提示"不是内部或外部命令"，说明环境变量没配置好：

Windows：重新运行安装包，选择"Modify"，勾选"Add Python.exe to PATH"，再点"Next"完成配置；
Mac/Linux：终端输入echo 'export PATH="/usr/local/bin/python3.11:$PATH"' >> ~/.bashrc（或.zshrc），然后输入source ~/.bashrc（或.zshrc）生效。

二、第二步：配置依赖库（Agent开发必备）

Agent开发需要用到的核心库，咱们一次性装齐，后续开发直接用。

1. 创建虚拟环境（可选但推荐）

虚拟环境能隔离不同项目的依赖，避免冲突（比如A项目需要1.0版本，B项目需要2.0版本），步骤如下：

终端输入：python -m venv agent-env（Windows）或python3 -m venv agent-env（Mac/Linux）；
激活虚拟环境：
- Windows（cmd）：agent-env\Scripts\activate.bat；
- Windows（PowerShell）：.\agent-env\Scripts\Activate.ps1；
- Mac/Linux：source agent-env/bin/activate；
激活后，终端前面会显示"(agent-env)"，说明进入虚拟环境，后续安装依赖都在这个环境里。

2. 一键安装核心依赖库

复制下面的命令，粘贴到终端执行（网速慢可以换国内镜像源，后面会说）：

bash 复制代码

pip install --upgrade pip  # 先升级pip到最新版本
pip install langchain langchain-openai langchain-community chromadb sentence-transformers openai python-dotenv fastapi uvicorn pydantic pandas numpy

3. 依赖库说明（知道用啥、为啥用）

不用死记硬背，了解核心作用就行：

langchain：Agent开发框架，封装了记忆、工具调用、大模型交互等核心功能，不用从零写代码；
langchain-openai/langchain-community：LangChain和OpenAI、国产模型的对接库；
chromadb：向量数据库，用来存Agent的短期/长期记忆；
sentence-transformers：嵌入模型库，把文字转成向量（记忆存储和检索的核心）；
openai：OpenAI官方SDK，调用GPT-3.5/4o模型；
python-dotenv：加载环境变量（存API密钥，避免硬编码）；
fastapi/uvicorn：后续部署Agent用的Web框架，能对外提供API服务；
pydantic：数据校验，让Agent的输入输出更规范；
pandas/numpy：处理结构化数据（比如长期记忆里的订单、用户信息）。

4. 避坑：pip安装慢/失败怎么办？

换国内镜像源（清华源、阿里云），安装命令加-i 镜像地址：

bash 复制代码

# 示例：用清华源安装
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple langchain chromadb sentence-transformers openai python-dotenv

常用国内镜像源：

清华源：https://pypi.tuna.tsinghua.edu.cn/simple
阿里云：https://mirrors.aliyun.com/pypi/simple/
豆瓣源：https://pypi.doubanio.com/simple/

5. 验证依赖是否安装成功

终端输入pip list，如果能看到以下库（版本号可能略有差异，不影响），说明安装成功：

复制代码

langchain==0.1.10
chromadb==0.4.20
sentence-transformers==2.2.2
openai==1.13.3
python-dotenv==1.0.1
fastapi==0.109.2
uvicorn==0.27.0

三、第三步：获取大模型API密钥（关键：Agent的"大脑"）

Agent需要大模型（比如GPT-3.5/4o、通义千问、智谱清言）才能生成回答，API密钥是调用大模型的"钥匙"。下面提供两种选择：优先用OpenAI（体验好、文档全），不想用国外的就用国产模型（无需科学上网）。

选项1：获取OpenAI API密钥（推荐新手）

步骤：

打开OpenAI官网：https://platform.openai.com/（需要科学上网，没有的话直接看选项2）；
注册/登录账号（用邮箱、Google账号都可以）；
登录后，点击右上角头像→"View API keys"；
点击"Create new secret key"，输入密钥名称（比如"agent-dev"），点击"Create secret key"；
生成后立刻复制保存（只显示一次，刷新页面就没了），别泄露给别人！

注意事项：

OpenAI有免费额度（新账号送几美元），用完后需要充值（支持信用卡）；
调用模型时，注意选择"gpt-3.5-turbo"（性价比高，适合开发测试），别选"gpt-4o"（贵，测试成本高）；
密钥要妥善保存，别写在代码里（后面用.env文件存储）。

选项2：获取国产大模型API密钥（无需科学上网）

如果没有科学上网，推荐用通义千问 （阿里）或智谱清言（智谱AI），国内访问快，有免费额度。

通义千问（推荐）：

打开官网：https://dashscope.console.aliyun.com/；
用阿里云账号登录（没有就注册，实名认证后可用）；
登录后，点击左侧"API-KEY管理"→"创建API-KEY"；
生成后复制保存，同样别泄露。

智谱清言：

打开官网：https://open.bigmodel.cn/；
注册/登录账号，实名认证；
点击右上角头像→"API密钥"→"创建密钥"；
复制保存密钥。

选项3：本地大模型（进阶，无需API密钥）

如果不想调用云端API（怕花钱、要离线使用），可以用本地大模型（比如Llama 3、Qwen-Lite），但需要电脑配置够（至少8G显存），步骤稍复杂，新手建议先从云端API开始，后续再尝试本地模型。

四、第四步：配置环境变量（安全存储API密钥）

绝对不要把API密钥直接写在代码里（比如api_key="sk-xxx"），万一代码泄露，别人会盗用你的额度！正确做法是用.env文件存储，步骤如下：

1. 创建.env文件

在你的项目文件夹（比如"agent-dev"）里，新建一个文件，命名为.env（注意前面有个点，没有文件名，只有后缀）；
Windows系统创建时，可能提示"文件名不能为空"，可以先命名为"env.txt"，然后重命名为".env"（删除.txt后缀，确认即可）。

2. 写入API密钥

打开.env文件，按以下格式写入你的API密钥（选一个就行，或都写）：

复制代码

# OpenAI API密钥（如果用OpenAI）
OPENAI_API_KEY="sk-你的OpenAI密钥"

# 通义千问API密钥（如果用通义千问）
DASHSCOPE_API_KEY="你的通义千问密钥"

# 智谱清言API密钥（如果用智谱清言）
ZHIPU_API_KEY="你的智谱清言密钥"

示例（替换成你的密钥）：

复制代码

OPENAI_API_KEY="sk-abcdefghijklmnopqrstuvwxyz1234567890"
DASHSCOPE_API_KEY="sk-1234567890abcdefghijklmnopqrstuv"

3. 验证.env文件是否生效

写一段简单的Python代码，测试是否能读取到API密钥：

python 复制代码

# 文件名：test_env.py
from dotenv import load_dotenv
import os

# 加载.env文件
load_dotenv()

# 读取API密钥
openai_key = os.getenv("OPENAI_API_KEY")
dashscope_key = os.getenv("DASHSCOPE_API_KEY")

print("OpenAI API密钥：", openai_key)
print("通义千问API密钥：", dashscope_key)

运行代码：

终端进入项目文件夹，输入python test_env.py；
如果能打印出你的密钥（部分字符可能隐藏，正常），说明配置成功！

五、第五步：测试大模型调用（确保环境能跑通）

最后做个小测试，调用大模型生成一句话，确认整个环境没问题：

测试1：调用OpenAI GPT-3.5

python 复制代码

# 文件名：test_llm.py
from dotenv import load_dotenv
import os
from openai import OpenAI

# 加载.env文件
load_dotenv()

# 初始化OpenAI客户端
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    timeout=30  # 超时时间30秒
)

# 调用GPT-3.5生成回答
try:
    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": "用一句话介绍Agent是什么"}]
    )
    # 打印结果
    print("GPT-3.5回答：", response.choices[0].message.content.strip())
except Exception as e:
    print("调用失败：", str(e))

测试2：调用通义千问（如果用国产模型）

python 复制代码

# 文件名：test_llm_qwen.py
from dotenv import load_dotenv
import os
from http import HTTPStatus
import dashscope

# 加载.env文件
load_dotenv()

# 初始化通义千问API密钥
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# 调用通义千问生成回答
try:
    response = dashscope.Generation.call(
        model='qwen-turbo',  # 通义千问轻量版，免费额度足够测试
        messages=[{"role": "user", "content": "用一句话介绍Agent是什么"}],
        result_format='message',
        temperature=0.4
    )
    if response.status_code == HTTPStatus.OK:
        print("通义千问回答：", response.output.choices[0].message.content.strip())
    else:
        print("调用失败：", response.code, response.message)
except Exception as e:
    print("调用失败：", str(e))

运行测试代码

终端输入python test_llm.py（或test_llm_qwen.py）；
如果能打印出大模型的回答（比如"Agent是能自主理解任务、调用工具、持续互动的智能助手"），说明环境完全没问题！

六、常见问题：避坑指南（新手必看）

1. Python版本不对，依赖安装失败？

卸载当前Python，重新安装3.10或3.11版本；
安装时务必勾选"Add Python.exe to PATH"。

2. 调用大模型提示"API key is invalid"？

检查.env文件里的密钥是否正确（有没有多空格、少字符）；
确认密钥没过期（OpenAI密钥长期有效，国产模型密钥一般也长期有效）；
重新生成新密钥，替换.env文件里的旧密钥。

3. 调用OpenAI提示"Connection error"？

检查科学上网是否正常（节点是否能访问国外网站）；
更换节点，或暂时改用国产模型。

4. 依赖库版本冲突？

卸载冲突的库，重新安装指定版本（比如pip uninstall langchain，再pip install langchain==0.1.10）；
用虚拟环境隔离（前面推荐的步骤，一定要做！）。

5. Windows系统激活虚拟环境提示"权限不够"？

以管理员身份打开终端，再执行激活命令；
或在PowerShell中输入Set-ExecutionPolicy RemoteSigned，选择"Y"允许执行脚本。

七、总结：环境搭建完成，准备开发Agent！

到这里，Agent开发的"地基"已经打牢：

有了Python运行环境（3.10/3.11）；
装好了所有核心依赖库（LangChain、Chroma、大模型SDK等）；
配置了API密钥（安全存储，不泄露）；
测试了大模型调用（能正常生成回答）。