LLM Zoomcamp 2026 环境搭建指南：用 uv 与 Jupyter 从零初始化 Agentic RAG 项目

LLM Zoomcamp 2026 环境搭建指南：用 uv 与 Jupyter 从零初始化 Agentic RAG 项目

【免费下载链接】llm-zoomcampLLM Zoomcamp - a free online course about real-life applications of LLMs. In 10 weeks you will learn how to build an AI system that answers questions about your knowledge base. Register here 👇🏼项目地址: https://gitcode.com/GitHub_Trending/ll/llm-zoomcamp

本文是 LLM Zoomcamp 2026 第一期课程（Agentic RAG）的环境准备篇，面向需要从零搭建 RAG 开发环境的读者。你将掌握两条并行路径：在本机用uv初始化项目，或在 GitHub Codespaces 中获得统一可复现的云端环境；学会用uv add一次性安装请求、检索、模型调用与笔记本运行所需的全部依赖；并掌握 API Key 的安全存放（.env+.gitignore）与 OpenAI 兼容提供商的切换方式，最终在 Jupyter 中验证 OpenAI 客户端可以正常发起调用。

本模块需要哪些前置条件

在第一期模块中，你要构建的是一个"从零写起"的 RAG 系统：不克隆任何现成代码，而是亲手把搜索、提示词与 LLM 调用一步步搭起来（模块整体脉络见 README.md）。整个模块的运行环境要求非常克制：

• Python（3.14 或更高版本）：官方推荐使用 3.14+；仓库内的 pyproject.toml 同时声明了requires-python = ">=3.12"的兼容下限，可作为最低基线参考；
• 一个 OpenAI 账号，或任何 OpenAI 兼容的提供商（如 Groq、Gemini、Ollama）；
• 对 Python 与命令行的基本熟悉：能运行终端命令、能阅读简单的 Python 脚本即可。

LLM 的调用在课程中被当作"黑盒"处理——不深究内部原理、不自行托管模型，而是通过 API 调用云端模型。因此整个环境只需要"Python + Jupyter + 一个 API Key"，这也是本模块能快速起步的原因。

创建项目：两条路径，任选其一

课程刻意设计成"不克隆、从零开始"，让你亲自经历项目的每一步初始化。你可以选择在本地创建，也可以选择在 GitHub Codespaces 上创建。

路径一：在本地创建项目

先安装uv——这是一个用 Rust 编写的 Python 包管理器，以速度与便捷著称，课程的作者已将全部项目迁移到它上面。Mac 或 Linux 下：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows 下（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

如果你更习惯传统方式，也可以用pip install uv安装。

随后创建项目文件夹并初始化：

mkdir llm-zoomcamp-2026-code cd llm-zoomcamp-2026-code uv init

uv init会生成一份pyproject.toml和基本的项目结构。这正是仓库中 code/pyproject.toml 的雏形——随着课程推进，这份文件会不断累积课程所需的核心依赖。

路径二：在 GitHub Codespaces 上创建

课程推荐使用 Codespaces，理由很实际：所有学员获得完全一致的 Ubuntu、Python 与 Docker 环境，遇到问题时相互帮助的成本大幅降低。

设置步骤：

1. 在 GitHub 上新建一个仓库，名称随意，例如llm-zoomcamp-2026-code或introduction-to-rag，记得勾选添加 README；
2. 打开仓库，点击绿色的<> Code按钮，切换到Codespaces标签页，创建 Codespace。

创建完成后，你就拥有了一个云端远程环境。默认打开的是浏览器内编辑器，如果想获得更好的体验，可以点击左下角的Codespaces按钮，在下拉菜单中选择 "Open in Visual Studio Code Desktop"，用桌面版 VS Code 连接。

VS Code 打开后，按ctrl+`呼出终端，用与本地完全相同的方式初始化项目：

pip install uv uv init

添加依赖：一条命令装齐五件套

初始化之后，下一步是安装本模块所需依赖：

uv add requests minsearch openai jupyter python-dotenv

这条命令会解析版本、生成锁定文件并安装，各依赖的用途如下：

仓库中实际的 pyproject.toml 展示了课程完整运行所需的依赖集合，除了上述五项，还包括psycopg[binary]（PostgreSQL 驱动，用于持久化检索）、sqlitesearch（SQLite 向量/全文检索）、sentence-transformers（嵌入模型）以及toyaikit（Part 2 的 Agent 教学框架），并给出了各包的版本下限：

[project] name = "llm-zoomcamp-2026-code" version = "0.1.0" requires-python = ">=3.12" dependencies = [ "jupyter>=1.1.1", "minsearch>=0.0.11", "openai>=2.37.0", "psycopg[binary]>=3.3.4", "python-dotenv>=1.2.2", "requests>=2.28.1", "sentence-transformers>=5.5.0", "sqlitesearch>=0.0.5", "toyaikit>=0.0.11", ]

需要说明的是：环境篇只安装前五项即可起步；其余依赖会在后续课程（数据摄取、向量检索、Agent 框架）用到时才加入，不必一次性装齐。minsearch是本模块搜索部分的主角，它是课程作者维护的教学级内存搜索引擎，概念上与 Elasticsearch/Lucene 一脉相承（文本字段、关键字字段、加权、过滤），详见后续的 Search 章节。

配置 API Key：让.env成为密钥的唯一住处

要调用 LLM，必须先有 API Key。如果你使用 OpenAI，需要注意两点：

• 需要预先充值：最低充值额为 5 美元（截至 2026 年 6 月）。本模块整节课的运行成本远低于 10 美分，这笔钱足够支撑整个学习过程；
• 建议为课程单独创建 OpenAI 项目：在 OpenAI 控制台新建一个专用项目并生成项目级 Key。这样你可以随时打开用量页面，精确看到这门课花了多少钱，与日常工作开销完全隔离。

把 Key 写进.env并加入.gitignore

最安全的存放方式是把 Key 放在一个永远不会提交到 git的.env文件中。在项目目录下创建.env：

OPENAI_API_KEY=sk-YOUR_KEY_HERE

然后编辑.gitignore，把.env加进去：

.env

永远不要提交.env到 git。请把 API Key 当作密码对待——一旦泄露，任何人都可以用你的账号产生费用。这也是本课程反复强调的一条安全底线。

启动 Jupyter 并验证客户端

依赖装好、Key 就位后，启动笔记本环境：

uv run jupyter notebook

uv run会在项目的虚拟环境中执行命令，保证 Jupyter 使用的是uv add安装的那套依赖。之后新建一个 notebook，课程后续的代码都会从各章节笔记复制到 notebook 单元中执行。

新建 notebook 后，第一件事就是验证 OpenAI 客户端能否正常工作。仓库中的 code/notebook.ipynb 就是从这个验证单元开始的：

from dotenv import load_dotenv load_dotenv() from openai import OpenAI openai_client = OpenAI()

load_dotenv()会把.env中的OPENAI_API_KEY注入进程环境变量；随后OpenAI()不传任何参数，客户端自动从环境变量读取 Key。如果你看到报错，首先检查.env中的 Key 是否复制正确、文件是否位于当前工作目录。

在后续课程中，这个openai_client会被反复使用。例如 code/rag_helper.py 中RAGBase.llm()方法的调用方式：

response = self.llm_client.responses.create( model=self.model, input=input_messages ) return response.output_text

可以看到 OpenAI 客户端走的是responses.create接口（而非旧的chat.completions），返回对象通过output_text取文本。这也提醒我们：环境验证是否通过，直接决定了后续所有 RAG 与 Agent 代码能否运行，值得在动手前花两分钟确认。

切换到 Groq 等 OpenAI 兼容提供商

如果你不想使用 OpenAI，或者想对比不同模型的表现，Groq 等提供商提供了完全兼容 OpenAI 协议的服务，切换成本极低。只需在.env中换一个 Key：

GROQ_API_KEY=your_key_here

然后在代码中显式传入 Key 与端点地址：

from openai import OpenAI import os openai_client = OpenAI( api_key=os.getenv("GROQ_API_KEY"), base_url="https://api.groq.com/openai/v1" )

关键在于base_url指向提供商的 OpenAI 兼容端点。从源码结构看，OpenAI 客户端的api_key、base_url均为可配置项，因此任何提供 OpenAI 兼容 API 的服务（Groq、Gemini、Ollama 本地模型等）都可以用同一套代码接入——课程后续的 RAG 管线也因此在模型选择上保持了高度灵活性。

可选：用 dirdotenv 自动加载.env

如果你不想在每个 notebook 里都手动调用load_dotenv()，可以使用课程作者维护的小工具dirdotenv。它会监听你的终端目录，当你cd进入某个目录时自动加载其中的.env文件：

uv tool install dirdotenv echo 'eval "$(dirdotenv hook bash)"' >> ~/.bashrc

重启终端后，只要进入项目目录，.env中的变量就会自动注入，无需再写load_dotenv()。这一步完全是锦上添花，跳过它也不会影响课程进度——手动调用load_dotenv()在每个 notebook 开头同样有效，仓库中的示例 notebook 正是这么做的。

环境自查清单

完成上述步骤后，用这份清单确认环境已就绪：

• uv init成功生成pyproject.toml，项目结构完整；
• uv add requests minsearch openai jupyter python-dotenv安装无报错；
• .env中已填写 API Key，且.gitignore已包含.env；
• uv run jupyter notebook能正常打开笔记本页面；
• 在 notebook 中执行load_dotenv()+OpenAI()不抛异常。

环境就绪后，就可以进入第一期模块的正题了：从 什么是 RAG 开始，理解为什么普通 LLM 无法回答课程专属问题，再通过 课程 FAQ 数据集、用 minsearch 构建搜索 一步步把检索增强生成的完整管线搭起来，最终在 Part 2 中通过函数调用把固定管线升级为 Agent（模块完整目录见 README.md）。

【免费下载链接】llm-zoomcampLLM Zoomcamp - a free online course about real-life applications of LLMs. In 10 weeks you will learn how to build an AI system that answers questions about your knowledge base. Register here 👇🏼项目地址: https://gitcode.com/GitHub_Trending/ll/llm-zoomcamp