Hugging Face Agents Course 快速上手:3 步装好环境并构建你的第一个 AI Agent
Hugging Face Agents Course(agents-course)是 Hugging Face 开源的 AI Agent 课程,内容从 Agent 概念讲到 smolagents、LangGraph、LlamaIndex 的实战,最后以基准测试收尾。面向会写基础 Python 的读者,照本文跟做后,你将拥有一个可运行的课程环境,并能开始 Unit 1 的第一个 Agent。
🔧 第 1 步:克隆课程并安装最小依赖
git clone https://gitcode.com/GitHub_Trending/ag/agents-course
这条命令把课程仓库拉到本地,units/ 目录下的 mdx 文件就是各单元的课程正文。
cd agents-course
python -m venv agents-env && source agents-env/bin/activate
第一行进入课程目录;第二行创建虚拟环境并立即激活,让课程依赖不污染你机器上的全局 Python。
课程声明的核心依赖在 quiz/pyproject.toml 里,直接安装这 4 个包即可:
pip install "datasets>=3.2.0" "huggingface-hub>=0.27.1" "ipykernel>=6.29.5" "requests>=2.32.3"
四个包分别负责读取课程数据、访问 Hub、注册 Jupyter 内核和发起 HTTP 请求,装齐后课程主流程就能跑。
✅ 第 2 步:用 2 条命令验证环境
python --version
输出应为 3.11 或更高,这是课程要求的最低 Python 版本。
python -c "import ipykernel, requests, huggingface_hub, datasets"
没有任何报错,说明 4 个核心依赖全部就位,Jupyter 内核也已注册,可以放心打开 Notebook。
🚀 第 3 步:用 smolagents 跑通第一个 Agent
先安装课程主打的轻量框架:
pip install "smolagents[all]"
smolagents 用代码块执行动作、用运行结果做观察,all 附加项会一并装上常用工具。
然后按 units/en/unit1/tutorial.mdx 的官方教程操作:复制课程提供的 Agent 模板 Space,填入你的模型 Token,补全 app.py 里的工具定义,就能看到 Agent 完成图片生成、网页搜索这类任务。教程里每一步都有截图说明,跟着做即可。
按需加料:本地模型与其他框架
用 Ollama 跑本地模型
不想依赖云端 API 的话,从 Ollama 官网下载安装后执行:
ollama pull qwen2:7b
这条命令把 7B 参数的模型下载到本地。onboarding 章节 给了完整示例:用 smolagents 的 LiteLLMModel 指向 127.0.0.1:11434 的本地接口,代码不用其他改动。
学到对应单元再装框架
Unit 2 分三章讲三个框架,目录见 units/en/unit2/。建议学到哪章装哪个,避免一次装多套依赖冲突:
pip install langgraph langchain-openai "llama-index-llms-huggingface-api" "llama-index-embeddings-huggingface"
这是 LangGraph 与 LlamaIndex 两条线常用的包组合,按需取舍。
排错:常见问题怎么处理
依赖冲突。 重建虚拟环境重新安装,不要试图在旧环境里逐个回退版本。
下载慢或超时。 给 pip 配置一个镜像索引源后重试,命令行加 -i 参数指定镜像地址即可。
smolagents 导入失败。 先确认当前在虚拟环境里,再升级 pip:pip install -U pip,多数情况是内核或构建工具过旧。
下一步清单
-
python --version输出 3.11+,2 条验证命令均无报错 - smolagents 安装成功,教程里的第一个 Agent 跑通一次
- 确定模型来源:本地 Ollama 或云端 Token,并完成一次简单调用
- 打开 units/en/_toctree.yml 通读单元目录,排好学习顺序
- 进入 units/en/unit1/ 开始正式课程
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



