先说个我观察了很久的现象不少刚接触AI代理的同学模型原理背得头头是道提示词也写得很溜结果一到动手就卡在第一步——环境搭建。群里每天都有人发“import报错”“装到一半装不下去”“版本冲突”这类求救帖说实话这些问题九成都是因为心里没底不知道环境搭建到底在干嘛也不知道装完以后怎么验证。这堂课我用15分钟带你走一遍完整流程从零安装、创建隔离环境、装依赖、跑通你的第一个AI代理整条链路清清楚楚后面第3课、第4课再学什么都不会再被环境问题绊倒。先说明一下这课适合谁。你不需要有Linux运维经验不需要会写复杂的编译命令甚至不用提前装好Python——所有东西我们从头来。你只要有一台能联网的电脑Windows、macOS、Linux都行剩下的事跟着我做就行。咱们的目标是15分钟之后你的终端里能跑起来一个真正会“调用工具”的最小AI代理而不是又一个“Hello World”。1. 环境搭建的整体思路先看清全貌再动手1.1 环境搭建到底是在解决什么问题很多新手把环境搭建理解成“装个软件”这个认知太浅了。AI代理项目的环境搭建本质上要解决三个层面的问题解释器、依赖库、运行配置。解释器就是Python本身它决定了代码能用哪些语法、能跑哪些框架。依赖库是项目用到的第三方代码比如调用大模型要用的SDK、处理数据的工具库。运行配置包括系统的环境变量、API密钥、模型地址这些“开关”。三层里任何一层出问题你的AI代理都跑不起来。我做一个生活化的类比你就懂了环境搭建相当于搬家之前先给新房子通水电。Python解释器是水电管线本身依赖库是家具电器配置是电闸和总阀门。你把高级家具搬进来结果电压不对、水管没接好再好的家具也发挥不了作用。很多同学报错报得一头雾水就是因为分不清到底是“管线”的问题还是“家具”的问题所以排查时像无头苍蝇。所以咱们这节课的思路很简单先立起一根干净的“管线”再把“家具”搬进来最后通电测试。管线只要搭一次后面所有AI代理项目都能复用。1.2 技术选型为什么是Miniconda加Python 3.10环境搭建的方案五花八门我推荐的组合是“Miniconda Python 3.10 pip”。先说Miniconda它是个轻量级的Python环境管理工具比完整版Anaconda小得多但核心功能全在。为什么非要用环境管理工具因为AI代理项目之间的依赖经常冲突。今天这个项目要Python 3.8明天那个项目要3.11这个库要numpy 1.24那个库要numpy 2.0。如果你不分环境全装到系统里很快就会乱成一锅粥。Miniconda让你可以创建多个相互隔离的“小房间”每个房间有自己独立的Python版本和依赖库互不影响。Python版本我选3.10理由很简单目前主流AI生态包括LangChain、LlamaIndex、各类Agent框架对3.10的兼容性最稳定。3.8太老部分新库已经开始放弃支持3.12、3.13虽然新但有些底层库还没跟上容易踩坑。3.10处于“刚好成熟”的位置这是我从实际项目里踩出来的经验不是拍脑袋。依赖安装用pip它是Python官方的包管理工具。有些教程会用conda install装包我的建议是能用pip就用pip因为AI生态里绝大多数库在pip源里更新最快、最全。conda只用来管Python版本和环境各司其职分工明确。1.3 本课的验收标准什么样的状态算“环境搭好了”先定个验收标准不然你永远不知道自己有没有搭好。我这节课的验收标准是三行命令执行python --version能看到Python 3.10.x。执行pip list能看到openai、langchain等核心依赖。执行python agent_demo.py能看到你的AI代理调用工具后返回一段合理的回答。这三件事全部通过你的环境搭建才算完成而不是“装完软件就叫搭好了”。很多人失败就是因为在“装完”和“能跑”之间少了一段验证结果到了真正跑项目时才被一堆隐藏问题打个措手不及。为了让你对“15分钟”有个体感我把时间预算拆给你看阶段预估耗时说明下载并安装Miniconda3分钟看网速用镜像源会快很多创建Python 3.10环境2分钟conda create的过程安装项目依赖库5分钟pip install依赖大小不同有波动编写最小代理并运行5分钟手写或用我给的代码验证输出如果你的网络状况比较好整个流程甚至用不了15分钟。但如果你遇到网络慢、依赖下载失败的情况也别慌第4节我把高频问题和解决方案都整理好了直接对照处理就行。2. 动手实操Miniconda安装与开发环境创建2.1 下载安装Miniconda选对版本是关键安装Miniconda的第一步是下载安装包。官网是repo.anaconda.com/miniconda页面里有Windows、macOS、Linux三个系统的安装包。这里我强调一句一定要看准版本Windows用户选“Windows-x86_64.exe”macOS用户要区分Intel芯片和Apple Silicon芯片分别选“x86_64”和“arm64”版本选错了装上去跑不动。下载安装包时如果觉得官网速度慢我建议直接用国内高校的软件镜像源。具体做法是在浏览器里搜索“TUNA Miniconda”找到清华开源软件镜像站里面有最新的Miniconda安装包下载速度快很多。安装过程基本就是一路点“Next”但有两个地方要注意。第一个是在“Advanced Installation Options”这一步会问你要不要把Miniconda加到系统PATH里这里我强烈建议勾上。如果不勾你之后在终端里执行conda命令就会提示找不到还得手动配环境变量非常麻烦。第二个是安装路径最好不要带空格和中文比如C:\miniconda就比C:\Users\张三\miniconda省心得多后面你会感谢这个决定。macOS和Linux用户安装更简单下载完脚本后在终端里执行bash Miniconda3-latest-Linux-x86_64.sh一路输入yes确认协议和初始化就行。安装完以后关闭并重新打开终端执行conda --version能输出版本号就说明装好了。2.2 创建隔离环境给AI代理一个独立“小房间”Miniconda装好之后咱们来创建第一个独立环境。打开终端执行conda create -n agent python3.10 -y这条命令的意思是创建一个名字叫agent的环境并在这个环境里安装Python 3.10。-y参数是跳过确认提示不然它还要问你一次“是否继续”。第一次执行时conda会自动下载Python 3.10的包耐心等一会儿就行。创建完成以后执行conda activate agent你会看到命令行前面的提示符变成了(agent)这就说明你已经进入了这个独立的“小房间”。这里有个常见误区很多人创建完环境忘了activate直接就跑命令结果用的还是系统里的旧Python。记住看到命令前有(agent)这个前缀才算真的进去了。再补充一个小技巧你可以通过conda env list查看当前机器上所有环境。输出里会有一个base环境和咱们刚建的agent环境。base是conda自带的默认环境我建议你不要在base里装任何项目依赖让它保持干净只当“管理台”用。2.3 安装核心依赖一条命令装完AI代理常用库环境激活以后接下来安装依赖。我用一个最小集帮你把AI代理的基础设施搭起来pip install openai langchain langchain-openai python-dotenv这里简单解释一下每个库是干嘛的。openai是OpenAI提供的Python客户端SDK它可以用来调用各类大模型接口包括OpenAI官方服务以及兼容OpenAI接口的本地模型服务。langchain是目前最流行的AI代理编排框架它帮我们处理大模型的调用、工具的定义和代理的执行流程。langchain-openai是LangChain和OpenAI SDK之间的适配层没有它两者接不上这是新手最容易漏装的库。python-dotenv用来读取.env配置文件方便我们管理API密钥不把密钥硬编码在代码里。如果你准备用本地模型比如Ollama跑一个开源模型那还需要装一个东西pip install ollama要注意至少对OpenAI SDK 1.x版本来说通过设置base_url你可以直接用它访问Ollama的本地接口所以ollama这个库主要提供的是更简单的本地模型管理能力。咱们先把它装上后面会用到。装完后执行pip list确认这几个库都在列表里。如果一切顺利你的“小房间”就已经有了Python解释器、AI编排框架、模型SDK环境搭建的硬骨头已经啃完了。3. 快速启动第一个AI代理最小可运行代码3.1 规划项目结构别把代码堆在同一个文件里很多教程喜欢把代码全部塞进一个文件里跑通完事我不建议这么做。因为AI代理项目一旦开始变复杂你会需要管理配置、工具、代理逻辑、入口文件全部挤在一个文件里后期维护就是折磨。咱们从第一课就养成好习惯用清晰的项目结构。在某个目录下创建一个agent-demo文件夹里面建三个文件agent-demo/ ├── .env # 存放API密钥等配置不要提交到代码仓库 ├── agent.py # 代理主逻辑 └── requirements.txt # 记录项目依赖清单.env文件用keyvalue的格式存配置比如# .env OPENAI_API_KEYsk-你的密钥 OPENAI_BASE_URLhttps://api.openai.com/v1 MODEL_NAMEgpt-4o-mini等一下我知道你要问什么如果没有OpenAI的API密钥怎么办没关系你现在不用急着去申请任何付费服务。另一个思路是把模型换成本地模型跑用Ollama在本地起一个兼容OpenAI接口的服务完全不需要API密钥。两种方式我在下面都会演示你选一种方便的上手就行。requirements.txt把依赖写清楚方便以后一键恢复环境。内容就是咱们刚才用pip装的几行openai langchain langchain-openai python-dotenv以后在新机器上部署时只需要执行pip install -r requirements.txt就能装好所有依赖。这个习惯在团队协作时特别重要对方不用问你“装了什么包”一个文件全部解决。3.2 写一个调用工具的AI代理本地模型版咱们写一个真正意义上的“AI代理”它不只会聊天还会根据用户问题去调用一个工具然后基于工具结果生成回答。这是代理和聊天机器人的核心区别。先看用本地Ollama模型的版本。前提是你机器上装好了Ollama并已经拉取了一个模型比如qwen2.5:7b或llama3.1:8b。然后agent.py的关键代码如下from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain.tools import tool from langchain_core.prompts import PromptTemplate # 定义一个时间工具AI代理可以决定何时调用它 tool def get_current_time() - str: 返回当前的日期和时间格式为 YYYY-MM-DD HH:MM:SS。 from datetime import datetime return datetime.now().strftime(%Y-%m-%d %H:%M:%S) # 本地Ollama服务兼容OpenAI接口 llm ChatOpenAI( base_urlhttp://localhost:11434/v1, api_keyollama, modelqwen2.5:7b, temperature0.7, ) prompt PromptTemplate.from_template( 你是AI代理你可以使用工具回答问题。\n 可用工具\n{tools}\n 工具名称{tool_names}\n 当前对话\n{chat_history}\n 用户输入{input}\n 思考过程{agent_scratchpad} ) agent create_react_agent(llmllm, tools[get_current_time], promptprompt) executor AgentExecutor(agentagent, tools[get_current_time], verboseTrue) if __name__ __main__: result executor.invoke({input: 现在几点了}) print(\n最终回答, result[output])这段代码的核心逻辑是代理先“思考”判断需不需要调用get_current_time这个工具如果需要就调用拿到结果后把结果融入回答再返回给用户。verboseTrue会在终端打印出代理的完整“思考链”这样你能直观看到它每一步在做什么。3.3 写一个调用工具的AI代理云端API版没有本地模型也没关系用云端API更轻便。你只需要改一行代码把LLM的初始化换成import os from dotenv import load_dotenv load_dotenv() llm ChatOpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), modelos.getenv(MODEL_NAME, gpt-4o-mini), )其余代码不用动。用python-dotenv读取.env里的密钥好处是密钥不会硬编码到代码里你的代码可以放心发到Git仓库.env文件单独放进.gitignore就行。这里我多说一句base_url这个参数你可能会觉得眼熟它是OpenAI客户端的标准配置项用来指向任何兼容OpenAI协议的服务端包括本地的Ollama、各种云厂商的兼容端点全都能用同一个SDK搞定。理解这一点后你以后换模型服务只需要改环境变量代码完全不用动这是AI代理开发里非常重要的“可移植性”思维。3.4 运行并看懂输出第一次看到代理“思考”代码写好后在agent-demo目录下执行python agent.py第一次运行终端会输出一段看起来比较啰嗦的过程信息类似 Entering new AgentExecutor chain... Thought: 用户想知道当前时间我需要调用工具获取准确的时间。 Action: get_current_time Action Input: {} Observation: 2025-05-18 14:23:45 Thought: 我已经拿到了准确时间可以回答用户了。 Final Answer: 现在是2025年5月18日14点23分45秒。看到这段信息恭喜你你的第一个AI代理已经跑通了。注意观察AgentExecutor的“思考链”它先思考再决定调用工具看到工具返回的结果后用这个结果组织语言最后输出回答。这个“思考-调用-观察-回答”的循环就是AI代理最核心的行为模式后面无论你做什么复杂的代理应用底层都是这个循环的变体。如果屏幕上没有输出这段内容而是报错了别急下一节就是专门解决这类问题的。可能你已经踩到坑了往下拉对照处理。4. 常见问题与排查技巧实录4.1 高频问题速查表我把自己和学员在实际操作中遇到最多的问题整理成了表格你按图索骥就行。现象根本原因解决方案执行conda提示找不到命令安装时没有加入PATH或终端没重启重启终端Windows上手动把Miniconda的Scripts目录加入环境变量PATHpython --version显示Python 2.x系统自带的旧Python版本抢先了执行conda activate agent后再检查确认which python指向conda环境pip install非常慢或超时默认PyPI源在国外网络不稳临时换源pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名安装langchain-openai报版本冲突本地已有新/旧版本langchain不兼容用pip freeze查看版本把langchain核心库升级到最新再重装适配层运行代码报ModuleNotFoundError当前没有activate环境或依赖没装全检查命令行前缀是否有(agent)执行pip list确认依赖存在连接Ollama服务超时Ollama服务没启动或端口不对另开终端执行ollama serve确认访问http://localhost:11434/v1/models能返回JSON模型下载卡在中间不动模型文件较大网络被中断Ollama默认模型存储目录可用环境变量OLLAMA_MODELS改到空间充足的盘重新拉取4.2 独家避坑心得版本固定比“最新”更重要这一条是我最想嘱咐你的。很多人在环境搭建阶段喜欢装“最新版”觉得越新越好实际上这是最大的坑。AI生态的库之间依赖关系非常紧密langchain更新得飞快今天装的最新版可能明天就和一个旧工具库不兼容。我的习惯是一旦环境跑通立刻用pip freeze requirements.txt生成一个完整的版本快照。这样你的环境就是“可复现”的不管过了多久、换到哪台机器都能恢复成同一个状态。版本快照文件里每一行都会写死版本号比如langchain0.2.14而不是宽松的langchain。另外升级依赖时一定要克制。如果项目能跑就别手痒执行pip install --upgrade把所有包升级一遍。“能用就别动”是我在AI项目上吃得最开的生存法则。有一次我就是手痒升级了某个底层库结果连锁反应导致整个代理框架崩了排查了两小时才定位到是版本回退问题真是血泪教训。4.3 排查思路从“现象”到“根因”的三步法遇到报错不要抓瞎我教你一个标准的三步排查法顺序不能乱。第一步报错信息里找关键行。Python报错一般会明确指出在哪个文件的第几行出错比如File agent.py, line 25。不要从头读一整个命令行直接看最后几行那里通常藏着真正原因。第二步判断报错类型。ModuleNotFoundError是缺依赖ImportError可能是依赖版本不对ConnectionError是网络问题TypeError是代码数据类型搞错了。判断类型之后你的搜索方向就清晰了直接搜对关键词比复制整段报错有效率得多。第三步确认当前环境。报错之前先执行conda env list和which python确认你当前动的确实是你以为的那个环境。很多“诡异问题”最后查出来都是环境串了在A环境里改了代码却用B环境在跑那不出问题才有鬼。4.4 关于系统差异Windows和macOS的几个小坑虽然跨平台是Python的优势但环境搭建阶段还是有几处系统差异容易踩坑。Windows用户最常遇到的是路径分隔符和终端命令差异。在本课里所有命令在PowerShell和CMD里都能用但如果你看到报错提示路径里有反斜杠转义问题建议在Python代码里用Path(agent-demo/.env)这种写法不要手写\。另外Windows上有时会遇到DLL加载失败这通常是缺少Visual C运行库去微软官网装最新的“Visual C Redistributable”就能解决。macOS用户要注意的是如果你用的是Apple Silicon芯片某些底层库可能没有对应的arm64预编译包安装时会自动进入编译源码模式耗时很长。解决方法是先看库的官方文档是否支持arm64如果支持就正常装不支持就考虑用conda来装这个特定库因为conda会提供对应架构的预编译包。Linux用户比较省心但要注意系统自带的Python是很多系统工具依赖的千万别用系统Python跑项目更别用sudo pip install否则可能把系统环境搞坏。用conda虚拟环境的话这些风险都能规避。5. 从“能跑”到“好用”环境的长期管理与扩展5.1 让环境可复现导出和恢复环境咱们前面生成过requirements.txt这还不够完整因为conda环境的Python版本信息没记录。我建议环境稳定后把环境信息完整导出成一份YAML文件conda env export environment.yml这个文件不仅记录了所有pip包还记录了conda包的完整列表和版本号在未来复现环境时更可靠。恢复环境时执行conda env create -f environment.yml它会创建一个和之前完全一致的环境连包版本都不差。这在你换了新电脑、或者和队友合作时价值巨大至少能避免“我机器上明明能跑到你机器上就报错”这种经典撕逼场景。5.2 日常开发的8个环境管理小习惯这几条是我长期在做AI代理开发时沉淀下来的习惯篇幅不长但每条背后都有实实在在的倒霉经历支撑。给每个项目建独立环境不要复用。环境名和项目名一致比如agent-demo就建agent-demo环境省得将来分不清。环境命名用小写字母和短横线不要用空格和中文。第一次跑通项目立刻生成requirements.txt和environment.yml。删除环境用conda env remove -n 环境名别手动删文件夹容易留下残骸。定期执行pip list --outdated只看不升了解有哪些更新动态。遇到错误先conda activate检查环境标识再试运行代码顺序别反。不要随意用conda install往环境里塞包除非pip确实装不了否则p环境依赖越来越乱。把.env文件看成项目的“钥匙串”密钥只放这里不进代码。5.3 下一步环境搭建之后怎么继续进阶环境搭好了第一个代理也跑通了接下来你的学习路线就很清晰了。第3课我会讲怎么给代理增加更多工具比如让它搜索网页、读写文件、调外部API第4课会讲怎么把代理接上聊天UI让它在对话框里和你对话再往后就是记忆机制、多代理协作、嵌入和向量检索。但归根结底后面所有玩法的地基就是你今天花15分钟搭好的这套环境。地基一旦牢固后面不管盖什么楼都稳。你也不要觉得“我只是照着敲了一遍命令好像没学到什么”——恰恰相反环境搭建这个技能本身就是靠“重复”才能内化的你今天遇到一次报错、解决一次问题比看十篇教程都有用。再分享一个小经验建议你今天跑通以后故意把它弄坏一次。没错主动删掉一个依赖、或者把Python版本换掉然后尝试自己修好。这个过程会让你对环境的理解上一个台阶比重复地“照着装”收益大得多。我个人就是在这种“故意拆家再装修”的过程中才真正理解了conda和pip之间到底是怎么回事。好看到这里你的AI代理开发之旅的环境基础已经打好了。关掉教程打开终端从执行第一条conda create命令开始吧。15分钟以后你就拥有一个能自己调工具的AI代理了。
