暴躁哐哐Heliki AI社区

Appearance

课程环境准备 ​

课程简介 ​

本课将指导你如何搭建运行示例代码所需的环境，包括获取课程代码、安装依赖以及配置必要的云服务账号。

加入学习社区 ​

在克隆仓库前，推荐加入 AI Agents for Beginners Discord 频道，以便在配置或课程学习过程中与其他学习者交流、提问。

克隆或 Fork 仓库 ​

首先请克隆或 Fork 官方仓库，确保你拥有一份可自由修改的课程代码。可直接访问 Fork 链接 创建个人副本。

创建完成后，你的 GitHub 账户下会出现 Fork 版本的课程仓库：

Fork 仓库示意图

建议：浅克隆（适用于工作坊或 Codespaces） ​

完整仓库包含较大的历史记录和资源（约 3 GB）。若只参加工作坊或仅需部分课程文件，可通过浅克隆或稀疏克隆大幅减少下载量。

快速浅克隆：保留最小历史但包含所有文件 ​

以下命令中的 <your-username> 请替换为你 Fork 仓库的用户名（若使用上游仓库也可替换为官方地址）。

仅获取最新一次提交：

bash
git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git

克隆指定分支：

bash
git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git

部分（稀疏）克隆：最小化文件体积并自选目录 ​

此方式依赖 Git 2.25+，建议使用支持部分克隆能力的新版 Git：

bash
git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git

进入仓库目录：

macOS 或 Linux：

bash
cd ai-agents-for-beginners

Windows PowerShell：

powershell
Set-Location ai-agents-for-beginners

选择需要的课程文件夹（以下示例选择第 0、1 课）：

bash
git sparse-checkout set 00-course-setup 01-intro-to-ai-agents

如仅需代码文件，可在确认文件无误后删除 .git 目录以释放空间（注意：此举不可逆，将失去全部 Git 功能）。

macOS 或 Linux：

bash
rm -rf .git

Windows PowerShell：

powershell
Remove-Item -Recurse -Force .git

使用 GitHub Codespaces（可避免本地下载大文件） ​

  1. 在 GitHub Codespaces 中为该仓库创建新的 Codespace。
  2. 在 Codespaces 终端中运行前述浅克隆或稀疏克隆命令，仅拉取所需课程目录。
  3. 可选：克隆后删除 .git 目录以释放空间。
  4. 若直接打开仓库也可使用 Codespaces 默认开发容器，但仍可能下载超出所需内容。通过浅克隆可更好控制磁盘占用。

提示 ​

  • 若计划提交改动或记录学习进度，请始终使用自己的 Fork 地址。
  • 后续若需要更多历史或文件，可继续 fetch 或调整 sparse-checkout 设置。

运行示例代码 ​

本课程提供一系列 Jupyter Notebook，帮助你通过实操掌握智能体构建方法。

代码示例涉及以下技术栈：

需 GitHub 账号（免费）：

  1. Semantic Kernel 智能体框架 + GitHub Models Marketplace（文件后缀 semantic-kernel.ipynb）
  2. AutoGen 框架 + GitHub Models Marketplace（文件后缀 autogen.ipynb）

需 Azure 订阅：

  1. Azure AI Foundry + Azure AI Agent Service（文件后缀 azureaiagent.ipynb）

建议尽量体验三类示例，以便比较不同方案的优劣。你选择的运行方案将决定需要完成的配置步骤。

环境要求 ​

  • Python 3.12 及以上
    • 若未安装 Python 3.12，请先安装，再使用该版本创建虚拟环境，确保依赖版本匹配。

示例：

创建虚拟环境目录：

bash
python3 -m venv venv

激活虚拟环境：

macOS 与 Linux：

bash
source venv/bin/activate

Windows：

powershell
venv\Scripts\activate
  • GitHub 账号：访问 GitHub Models Marketplace
  • Azure 订阅：访问 Azure AI Foundry
  • Azure AI Foundry 账号：访问 Azure AI Agent Service

仓库根目录提供 requirements.txt，包含运行 Notebook 所需的全部 Python 包：

bash
pip install -r requirements.txt

建议始终在虚拟环境中安装依赖，避免与本地其他项目冲突。

配置 VS Code ​

确保 VS Code 使用的是正确的 Python 解释器版本。

VS Code Python 选择示例

GitHub Models 示例配置 ​

步骤 1：获取 GitHub Personal Access Token（PAT） ​

课程示例使用 GitHub Models Marketplace，可免费调用部分大型语言模型以构建智能体。

需要参考官方文档创建 GitHub Personal Access Token。

访问 个人访问令牌设置 并遵循最小权限原则，仅勾选运行示例所需权限。

  1. 在左侧 Developer settings 中选择 Fine-grained tokens。 Developer settings 入口

    点击 Generate new token。

    生成令牌

  2. 为令牌填写易于识别的名称，并设置合理的有效期。

    令牌有效期建议：推荐 30 天；如果希望更高安全性，可缩短至 7 天内完成课程。

    设置名称与有效期

  3. 将令牌作用域限制在你 Fork 的仓库。

    限制仓库范围

  4. 在 Permissions 页面中选择 Account 标签，点击 “+ Add permissions”，搜索 Models 并勾选。

    添加 Models 权限

  5. 在生成令牌前确认权限设置是否正确。

    核对权限

  6. 生成令牌前，确保已准备好安全的存储位置（例如密码管理器），因为 GitHub 仅显示一次令牌明文。

    安全保存令牌

复制新生成的令牌，下一步将写入 .env 文件。

步骤 2：创建 .env 文件 ​

在终端运行：

bash
cp .env.example .env

命令会复制示例文件并生成 .env，随后在编辑器中打开 .env，将令牌粘贴到 GITHUB_TOKEN 字段。

填写 GitHub Token

完成后即可运行 GitHub Models 相关示例。

Azure AI Foundry 与 Azure AI Agent Service 配置 ​

步骤 1：获取 Azure 项目 Endpoint ​

按照文档 Hub resources overview 创建 Azure AI Foundry 的 Hub 与项目，并在项目 Overview 页面获取连接字符串。

项目连接字符串示例

步骤 2：创建 .env 文件 ​

同样执行：

bash
cp .env.example .env

在 .env 中找到 PROJECT_ENDPOINT 字段，并粘贴刚获取的项目 Endpoint。

步骤 3：登录 Azure ​

出于安全考虑，官方建议使用 Keyless Authentication 通过 Microsoft Entra ID 认证 Azure OpenAI。

打开终端执行：

bash
az login --use-device-code

按提示完成登录后，选择需要使用的订阅。

Azure Search 与 Azure OpenAI 额外环境变量 ​

Lesson 05（Agentic RAG）示例会用到 Azure Search 与 Azure OpenAI。若需运行这些 Notebook，请在 .env 中补充以下变量：

项目概览页 ​

  • AZURE_SUBSCRIPTION_ID：在项目 Overview 页的 Project details 区域查看。
  • AZURE_AI_PROJECT_NAME：同样位于 Overview 页顶部。
  • AZURE_OPENAI_SERVICE：在 Included capabilities 标签的 Azure OpenAI Service 模块中查看。

Management Center ​

  • AZURE_OPENAI_RESOURCE_GROUP：在项目 Overview 页面点击 Project properties 查看。
  • GLOBAL_LLM_SERVICE：在 Connected resources 中寻找 Azure AI Services 连接名称；如未列出，可前往 Azure Portal 的资源组查看。

Models + Endpoints 页面 ​

  • AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME：选择嵌入模型（如 text-embedding-ada-002），记录部署名称。
  • AZURE_OPENAI_CHAT_DEPLOYMENT_NAME：选择聊天模型（如 gpt-4o-mini），记录部署名称。

Azure Portal ​

  • AZURE_OPENAI_ENDPOINT：在 Azure Portal 的 Azure AI Services 资源中，进入 Resource Management → Keys and Endpoint，复制 Language APIs 对应地址。
  • AZURE_OPENAI_API_KEY：在同一页面复制 KEY 1 或 KEY 2。
  • AZURE_SEARCH_SERVICE_ENDPOINT：打开 Azure AI Search 资源，在 Overview 页面获取。
  • AZURE_SEARCH_API_KEY：在 Settings → Keys 页面复制主或副管理员密钥。

外部页面 ​

配置 Keyless Authentication ​

为避免在代码中硬编码凭据，可使用 Azure SDK 提供的 DefaultAzureCredential：

python
from azure.identity import DefaultAzureCredential, InteractiveBrowserCredential

排障与求助 ​

如果在配置过程中遇到问题，可前往 Azure AI Community Discord 或在 GitHub Issues 留言。

下一篇 ​

环境准备就绪后，即可开始深入了解智能体概念与应用场景：

01 智能体概念与应用场景