EdgeAI初学者工作坊

EdgeAI 初学者工作坊

构建生产级边缘 AI 应用的实践学习路径

通过 Microsoft Foundry Local，从首次聊天生成到多代理编排，掌握本地 AI 部署的技能，分为六个渐进式课程。

简介

欢迎参加 EdgeAI 初学者工作坊——这是一个实用的、动手操作的指南，帮助您构建完全在本地硬件上运行的智能应用程序。通过使用 Microsoft Foundry Local 和小型语言模型（SLM）进行逐步挑战的练习，本次工作坊将理论性的边缘 AI 概念转化为实际技能。

为什么选择这个工作坊？

边缘 AI 革命已经到来

全球组织正在从依赖云的 AI 转向边缘计算，主要有以下三个关键原因：

1. 隐私与合规性 - 在本地处理敏感数据，无需通过云传输（符合 HIPAA、GDPR、金融法规）
2. 性能 - 消除网络延迟（本地 50-500ms vs 云端往返 500-2000ms）
3. 成本控制 - 消除按令牌计费的 API 成本，并在无云费用的情况下扩展

但边缘 AI 与众不同

在本地运行 AI 需要新的技能：

• 针对资源限制选择和优化模型
• 本地服务管理和硬件加速
• 针对小型模型的提示工程
• 边缘设备的生产部署模式

本次工作坊将传授这些技能

通过 6 个重点课程（总时长约 3 小时），您将从“Hello World”进阶到部署生产级的多代理系统——所有内容均在您的机器上本地运行。

学习目标

完成本次工作坊后，您将能够：

核心能力

1. 部署和管理本地 AI 服务

   • 安装和配置 Microsoft Foundry Local
   • 为边缘部署选择合适的模型
   • 管理模型生命周期（下载、加载、缓存）
   • 监控资源使用并优化性能

2. 构建 AI 驱动的应用

   • 本地实现 OpenAI 兼容的聊天生成
   • 为小型语言模型设计有效的提示
   • 处理流式响应以改善用户体验
   • 将本地模型集成到现有应用中

3. 创建 RAG（检索增强生成）系统

   • 使用嵌入构建语义搜索
   • 在领域特定知识中支持 LLM 响应
   • 使用行业标准指标评估 RAG 质量
   • 从原型扩展到生产

4. 优化模型性能

   • 为您的用例基准测试多个模型
   • 测量延迟、吞吐量和首令牌时间
   • 根据速度/质量权衡选择最佳模型
   • 在实际场景中比较 SLM 与 LLM 的权衡

5. 编排多代理系统

   • 为不同任务设计专用代理
   • 实现代理记忆和上下文管理
   • 在复杂工作流中协调代理
   • 在多个模型之间智能路由请求

6. 部署生产级解决方案

   • 实现错误处理和重试逻辑
   • 监控令牌使用和系统资源
   • 使用模型工具模式构建可扩展架构
   • 规划从边缘到混合（边缘+云）的迁移路径

学习成果

您将构建的内容

到工作坊结束时，您将完成以下内容：

能力矩阵

职业技能

完成工作坊后，您将能够：

✅ 构建隐私优先的应用

• 本地处理 PHI/PII 的医疗应用
• 符合合规要求的金融服务
• 数据主权需求的政府系统

✅ 优化边缘环境

• 资源有限的物联网设备
• 离线优先的移动应用
• 低延迟实时系统

✅ 设计智能架构

• 用于复杂工作流的多代理系统
• 混合边缘-云部署
• 成本优化的 AI 基础设施

✅ 领导边缘 AI 项目

• 评估项目的边缘 AI 可行性
• 选择合适的模型和框架
• 构建可扩展的本地 AI 解决方案

️ 工作坊结构

课程概览（6 节课 × 30 分钟 = 3 小时）

快速开始

前提条件

系统要求：

• 操作系统：Windows 10/11、macOS 11+ 或 Linux (Ubuntu 20.04+)
• 内存：最低 8GB，推荐 16GB+
• 存储：至少 10GB 可用空间用于模型
• 处理器：支持 AVX2 的现代处理器
• GPU（可选）：支持 CUDA 的显卡或 Qualcomm NPU 加速

软件要求：

• Python 3.8+ (下载)
• Microsoft Foundry Local (安装指南)
• Git (下载)
• Visual Studio Code（推荐）(下载)

三步设置

1. 安装 Foundry Local

Windows:

winget install Microsoft.FoundryLocal
​

macOS:

brew tap microsoft/foundrylocal
brew install foundrylocal
​

验证安装：

foundry --version
foundry service status
​

确保 Azure AI Foundry Local 在固定端口运行

# Set FoundryLocal to use port 58123 (default)
foundry service set --port 58123 --show

# Or use a different port
foundry service set --port 58000 --show
​

验证是否正常工作：

# Check service status
foundry service status

# Test the endpoint
curl http://127.0.0.1:58123/v1/models
​

查找可用模型
要查看 Foundry Local 实例中可用的模型，可以查询模型端点：

# cmd/bash/powershell
foundry model list
​

使用 Web 端点

# Windows PowerShell
powershell -Command "Invoke-RestMethod -Uri 'http://127.0.0.1:58123/v1/models' -Method Get"

# Or using curl (if available)
curl http://127.0.0.1:58123/v1/models
​

2. 克隆代码库并安装依赖项

# Clone repository
git clone https://github.com/microsoft/edgeai-for-beginners.git
cd edgeai-for-beginners/Workshop

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.\.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
​

3. 运行您的第一个示例

# Start Foundry Local and load a model
foundry model run phi-4-mini

# Run the chat bootstrap sample
cd samples
python -m session01.chat_bootstrap "What is edge AI?"
​

✅ 成功！ 您应该看到关于边缘 AI 的流式响应。

工作坊资源

Python 示例

逐步动手示例，展示每个概念：

Jupyter Notebooks

带有解释和可视化的交互式探索：

文档

全面的指南和参考：

学习路径推荐

初学者（3-4 小时）

1. ✅ 课程 1：入门（专注于设置和基础聊天）
2. ✅ 课程 2：RAG 基础（初次可跳过评估）
3. ✅ 课程 3：简单基准测试（仅测试 2 个模型）
4. ⏭️ 暂时跳过课程 4-6
5. 构建第一个应用后再返回课程 4-6

中级开发者（3 小时）

1. ⚡ 课程 1：快速设置验证
2. ✅ 课程 2：完整 RAG 管道与评估
3. ✅ 课程 3：完整基准测试套件
4. ✅ 课程 4：模型优化
5. ✅ 课程 5-6：专注于架构模式

高级实践者（2-3 小时）

1. ⚡ 课程 1-3：快速回顾与验证
2. ✅ 课程 4：深入优化
3. ✅ 课程 5：多代理架构
4. ✅ 课程 6：生产模式与扩展
5. 扩展：构建自定义路由逻辑与混合部署

工作坊课程包（专注的 30 分钟实验）

如果您正在遵循浓缩的 6 节课程工作坊格式，请使用这些专用指南（每个指南与更广泛的模块文档相辅相成）：

每个课程文件包括：摘要、学习目标、30分钟演示流程、起始项目、验证检查表、故障排除以及对官方 Foundry Local Python SDK 的参考。

示例脚本

安装工作坊依赖项（Windows）：

cd Workshop
py -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
​

macOS / Linux：

cd Workshop
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
​

如果在不同的（Windows）机器或虚拟机上运行 Foundry Local 服务，而不是 macOS，请导出端点：

export FOUNDRY_LOCAL_ENDPOINT=http://<windows-host>:5273/v1
​

环境变量（样本通用）

如果变量未设置，脚本会回退到合理的默认值。对于单模型演示，通常只需要设置 FOUNDRY_LOCAL_ALIAS。

工具模块

所有样本现在共享一个辅助模块 samples/workshop_utils.py，提供：

• 缓存的 FoundryLocalManager + OpenAI 客户端创建
• 带可选重试 + 使用情况打印的 chat_once() 辅助函数
• 简单的令牌使用情况报告（通过 SHOW_USAGE=1 启用）

这减少了重复，并突出了高效本地模型编排的最佳实践。

可选增强功能（跨课程）

确定性快速启动

set FOUNDRY_LOCAL_ALIAS=phi-4-mini
set SHOW_USAGE=1
python Workshop\tests\smoke.py
​

期望在重复的相同输入中保持稳定的令牌计数。

RAG 评估（课程 2）

使用 rag_eval_ragas.py 计算答案的相关性、真实性和上下文精度，基于一个小型合成数据集：

cd Workshop/samples
python -m session02.rag_eval_ragas
​

通过提供更大的 JSONL 问题、上下文和真实值扩展，然后转换为 Hugging Face Dataset。

CLI 命令准确性附录

工作坊仅使用当前记录的 / 稳定的 Foundry Local CLI 命令。

引用的稳定命令

一次性提示模式

替代已弃用的 model chat 子命令，使用：

foundry model run <alias> --prompt "Your question here"
​

这将执行单次提示/响应循环，然后退出。

已移除 / 避免的模式

基准测试 & 遥测

• 延迟、p95、每秒令牌数：samples/session03/benchmark_oss_models.py
• 首令牌延迟（流式）：设置 BENCH_STREAM=1
• 资源使用情况：操作系统监控工具（任务管理器、活动监视器、nvidia-smi）。

随着新的 CLI 遥测命令在上游稳定，它们可以通过最小的编辑集成到课程 markdown 文件中。

自动化代码检查

一个自动化代码检查工具可以防止在 markdown 文件的代码块中重新引入已弃用的 CLI 模式：

脚本：Workshop/scripts/lint_markdown_cli.py

代码块中的已弃用模式将被阻止。

推荐替代：

本地运行：

python Workshop\scripts\lint_markdown_cli.py --verbose
​

GitHub Action：.github/workflows/markdown-cli-lint.yml 在每次推送 & PR 时运行。

可选的 pre-commit 钩子：

echo "python Workshop/scripts/lint_markdown_cli.py" > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
​

快速 CLI → SDK 迁移表

基准测试 Markdown 导出

使用脚本 Workshop/scripts/export_benchmark_markdown.py 运行最新的基准测试（与 samples/session03/benchmark_oss_models.py 逻辑相同），并生成一个适合 GitHub 的 Markdown 表格以及原始 JSON。

示例

python Workshop\scripts\export_benchmark_markdown.py --models "qwen2.5-0.5b,mistral-7b" --prompt "Explain retrieval augmented generation briefly." --rounds 3 --output benchmark_report.md
​

生成的文件：

在环境中设置 BENCH_STREAM=1 以包含首令牌延迟（如果支持）。

免责声明：
本文档使用AI翻译服务Co-op Translator进行翻译。尽管我们努力确保翻译的准确性，但请注意，自动翻译可能包含错误或不准确之处。原始语言的文档应被视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用此翻译而产生的任何误解或误读不承担责任。