AGENTS.md

文档摘要

AGENTS.md 初学者开发者指南：贡献于EdgeAI 本文档为开发者、AI代理和贡献者提供了关于本仓库的全面信息。内容涵盖了设置、开发工作流、测试以及最佳实践。最后更新日期：2025年10月30日 | 文档版本：3.0 目录项目概述仓库结构先决条件设置命令开发工作流测试说明代码风格指南拉取请求指南翻译系统 Foundry Local集成构建与部署常见问题与故障排除附加资源项目特定说明获取帮助项目概述 EdgeAI for Beginners 是一个全面的教育性仓库，旨在教授使用小型语言模型（SLMs）进行边缘AI开发。课程内容包括EdgeAI基础知识、模型部署、优化技术以及使用Microsoft Foundry Local和各种AI框架的生产级实现。

AGENTS.md

初学者开发者指南：贡献于EdgeAI

本文档为开发者、AI代理和贡献者提供了关于本仓库的全面信息。内容涵盖了设置、开发工作流、测试以及最佳实践。

最后更新日期：2025年10月30日 | 文档版本：3.0

项目概述

EdgeAI for Beginners 是一个全面的教育性仓库，旨在教授使用小型语言模型（SLMs）进行边缘AI开发。课程内容包括EdgeAI基础知识、模型部署、优化技术以及使用Microsoft Foundry Local和各种AI框架的生产级实现。

关键技术：

Python 3.8+（AI/ML示例的主要语言）
.NET C#（AI/ML示例）
JavaScript/Node.js与Electron（用于桌面应用程序）
Microsoft Foundry Local SDK
Microsoft Windows ML
VSCode AI工具包
OpenAI SDK
AI框架：LangChain、Semantic Kernel、Chainlit
模型优化：Llama.cpp、Microsoft Olive、OpenVINO、Apple MLX

仓库类型： 包含8个模块和10个综合示例应用的教育内容仓库

架构： 多模块学习路径，提供展示边缘AI部署模式的实践示例

仓库结构


edgeai-for-beginners/
├── introduction.md          # Course introduction and overview
├── Module01-07/            # Core educational modules (Markdown)
├── Module08/               # Foundry Local toolkit with 10 samples
│   ├── samples/01-06/     # Foundation samples (Python)
│   ├── samples/07/        # API client (Python)
│   ├── samples/08/        # Windows 11 chat app (Electron)
│   └── samples/09-10/     # Advanced multi-agent systems (Python)
├── Workshop/               # Hands-on workshop materials
│   ├── samples/           # Workshop Python samples with utilities
│   │   ├── session01/     # Chat bootstrap samples
│   │   ├── session02-06/  # Progressive workshop sessions
│   │   └── util/          # Workshop utility modules
│   ├── notebooks/         # Jupyter notebook tutorials
│   └── scripts/           # Validation and testing tools
├── translations/          # Multi-language translations (50+ languages)
├── translated_images/     # Localized images
└── imgs/                  # Course images and assets

先决条件

必需工具

Python 3.8+ - 用于AI/ML示例和笔记本
Node.js 16+ - 用于Electron示例应用程序
Git - 用于版本控制
Microsoft Foundry Local - 用于本地运行AI模型

系统要求

内存：最低8GB，推荐16GB以上以支持多模型场景
存储：至少10GB可用空间用于模型和依赖项
操作系统：Windows 10/11、macOS 11+或Linux（Ubuntu 20.04+）
硬件：支持AVX2的CPU；推荐使用GPU（CUDA、Qualcomm NPU）

知识要求

具备Python编程的基础知识
熟悉命令行界面
理解AI/ML概念（用于示例开发）
熟悉Git工作流和拉取请求流程

设置命令

仓库设置


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

# No build step required - this is primarily an educational content repository

Python示例设置（模块08和Workshop示例）


# Create and activate virtual environment
python -m venv .venv
# On Windows
.venv\Scripts\activate
# On macOS/Linux
source .venv/bin/activate

# Install Foundry Local SDK and dependencies
pip install foundry-local-sdk openai

# Install additional dependencies for Module08 samples
cd Module08
pip install -r requirements.txt

# Install Workshop dependencies
cd ../Workshop
pip install -r requirements.txt

Node.js示例设置（示例08 - Windows聊天应用）


cd Module08/samples/08
npm install

# Start in development mode
npm run dev

# Build for production
npm run build

# Create installer
npm run dist

Foundry Local设置

Foundry Local是运行示例所需的工具。请从官方仓库下载并安装：

安装：

Windows：winget install Microsoft.FoundryLocal
macOS：brew tap microsoft/foundrylocal && brew install foundrylocal
手动安装：从发布页面下载

快速开始：


# Run your first model (auto-downloads if needed)
foundry model run phi-4-mini

# List available models
foundry model ls

# Check service status
foundry service status

注意：Foundry Local会自动为您的硬件选择最佳模型版本（CUDA GPU、Qualcomm NPU或CPU）。

开发工作流

内容开发

本仓库主要包含Markdown教育内容。进行更改时：

编辑适当模块目录下的.md文件
遵循现有的格式模式
确保代码示例准确且经过测试
必要时更新对应的翻译内容（或由自动化处理）

示例应用开发

对于模块08的Python示例（示例01-07、09-10）：


cd Module08
python samples/01/chat_quickstart.py "Test message"

对于Workshop Python示例：


cd Workshop/samples/session01
python chat_bootstrap.py "Test message"

对于Electron示例（示例08）：


cd Module08/samples/08
npm run dev  # Development with hot reload

测试示例应用

Python示例没有自动化测试，但可以通过运行进行验证：


# Test basic chat functionality
python samples/01/chat_quickstart.py "Hello"

# Test with specific model
set MODEL=phi-4-mini
python samples/02/openai_sdk_client.py

Electron示例具有测试基础设施：


cd Module08/samples/08
npm test           # Run unit tests
npm run test:e2e   # Run end-to-end tests
npm run lint       # Check code style

测试说明

内容验证

仓库使用自动化翻译工作流。翻译无需手动测试。

内容更改的手动验证：

通过预览.md文件检查Markdown渲染
验证所有链接指向有效目标
测试文档中包含的代码片段
确保图片正确加载

示例应用测试

模块08/示例/08（Electron应用）具有全面测试：


cd Module08/samples/08

# Run all tests
npm test

# Run unit tests only
npm test -- --testPathPattern=unit

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

# Check test coverage
npm test -- --coverage

Python示例需手动测试：


# Module08 samples
python samples/01/chat_quickstart.py "Test prompt"
python samples/04/chainlit_rag.py
python samples/09/multi_agent_system.py

# Workshop samples
cd Workshop/samples/session01
python chat_bootstrap.py "Test prompt"

# Use Workshop validation tools
cd Workshop/scripts
python validate_samples.py  # Validate syntax and imports
python test_samples.py      # Run smoke tests

代码风格指南

Markdown内容

使用一致的标题层级（#用于标题，##用于主要部分，###用于子部分）
包含带语言说明的代码块：python, bash, ```javascript
遵循现有的表格、列表和强调格式
保持行可读性（目标约80-100字符，但不严格限制）
对内部引用使用相对链接

Python代码风格

遵循PEP 8规范
适当使用类型提示
为函数和类添加文档字符串
使用有意义的变量名
保持函数专注且简洁

JavaScript/Node.js代码风格


# Electron sample follows ESLint configuration
cd Module08/samples/08
npm run lint        # Check for style issues
npm run lint:fix    # Auto-fix style issues
npm run format      # Format with Prettier

关键约定：

示例08提供了ESLint配置
使用Prettier进行代码格式化
使用现代ES6+语法
遵循代码库中的现有模式

拉取请求指南

贡献工作流

Fork仓库并从main创建新分支
根据代码风格指南进行更改
按照上述测试说明进行彻底测试
使用清晰的消息提交，遵循规范化提交格式
推送到您的Fork并创建拉取请求
在审查期间响应维护者的反馈

分支命名约定

feature/<module>-<description> - 用于新功能或内容
fix/<module>-<description> - 用于错误修复
docs/<description> - 用于文档改进
refactor/<description> - 用于代码重构

提交消息格式

遵循规范化提交：


<type>(<scope>): <description>

[optional body]

[optional footer]

示例：


feat(Module08): add intent-based routing notebook
docs(AGENTS): update Foundry Local setup instructions
fix(samples/08): resolve Electron build issue

标题格式


[ModuleXX] Brief description of change

或


[Module08/samples/XX] Description for sample changes

行为准则

所有贡献者必须遵守Microsoft开源行为准则。请在贡献之前查看CODE_OF_CONDUCT.md。

提交前检查

对于内容更改：

预览所有修改的Markdown文件
验证链接和图片是否正常工作
检查拼写和语法错误

对于示例代码更改（模块08/示例/08）：


npm run lint
npm test

对于Python示例更改：

测试示例是否成功运行
验证错误处理是否正常
检查与Foundry Local的兼容性

审查流程

教育内容更改需审查准确性和清晰度
代码示例需测试功能性
翻译更新由GitHub Actions自动处理

翻译系统

重要： 本仓库使用GitHub Actions进行自动翻译。

翻译文件位于/translations/目录（支持50多种语言）
通过co-op-translator.yml工作流自动化处理
请勿手动编辑翻译文件 - 它们会被覆盖
仅编辑根目录和模块目录中的英文源文件
推送到main分支时会自动生成翻译

Foundry Local集成

大多数模块08示例需要运行Microsoft Foundry Local。

安装与设置

安装Foundry Local：


# Windows
winget install Microsoft.FoundryLocal

# macOS
brew tap microsoft/foundrylocal
brew install foundrylocal

安装Python SDK：


pip install foundry-local-sdk openai

启动Foundry Local


# Start service and run a model (auto-downloads if needed)
foundry model run phi-3.5-mini

# Or use model aliases for automatic hardware optimization
foundry model run phi-4-mini
foundry model run qwen2.5-0.5b
foundry model run qwen2.5-coder-0.5b

# Check service status
foundry service status

# List available models
foundry model ls

SDK使用（Python）


from foundry_local import FoundryLocalManager
import openai

# Use model alias for automatic hardware optimization
alias = "phi-4-mini"

# Create manager (auto-starts service and loads model)
manager = FoundryLocalManager(alias)

# Configure OpenAI client for local Foundry service
client = openai.OpenAI(
    base_url=manager.endpoint,
    api_key=manager.api_key
)

# Use the model
response = client.chat.completions.create(
    model=manager.get_model_info(alias).id,
    messages=[{"role": "user", "content": "Hello!"}]
)

验证Foundry Local


# Service status and endpoint
foundry service status

# List loaded models (REST API)
curl http://localhost:<port>/v1/models

# Note: Port is displayed when running 'foundry service status'

示例所需环境变量

大多数示例使用以下环境变量：


# Foundry Local configuration
# Note: The SDK (FoundryLocalManager) automatically detects endpoint
set MODEL=phi-4-mini  # or phi-3.5-mini, qwen2.5-0.5b, qwen2.5-coder-0.5b
set API_KEY=            # Not required for local usage

# Manual endpoint (if not using SDK)
# Port is shown via 'foundry service status'
set BASE_URL=http://localhost:<port>

# For Azure OpenAI fallback (optional)
set AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
set AZURE_OPENAI_API_KEY=your-api-key
set AZURE_OPENAI_API_VERSION=2024-08-01-preview

注意：使用FoundryLocalManager时，SDK会自动处理服务发现和模型加载。模型别名（如phi-3.5-mini）确保为您的硬件选择最佳版本。

构建与部署

内容部署

本仓库主要是文档内容 - 无需构建过程。

示例应用构建

Electron应用（模块08/示例/08）：


cd Module08/samples/08

# Development build
npm run dev

# Production build
npm run build

# Create Windows installer
npm run dist

# Create portable executable
npm run pack

Python示例：
无需构建过程 - 示例直接使用Python解释器运行。

常见问题与故障排除

提示：查看GitHub问题以获取已知问题和解决方案。

严重问题（阻塞）

Foundry Local未运行

问题： 示例因连接错误而失败

解决方案：


# Check if service is running
foundry service status

# Start service with a model
foundry model run phi-4-mini

# Or explicitly start service
foundry service start

# List loaded models
foundry model ls

# Verify via REST API (port shown in 'foundry service status')
curl http://localhost:<port>/v1/models

常见问题（中等）

Python虚拟环境问题

问题： 模块导入错误

解决方案：


# Ensure virtual environment is activated
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Electron构建问题

问题： npm安装或构建失败

解决方案：


cd Module08/samples/08
# Clean install
npm run clean
rm -rf node_modules package-lock.json
npm install

工作流问题（轻微）

翻译工作流冲突

问题： 翻译PR与您的更改冲突

解决方案：

仅编辑英文源文件
让自动化翻译工作流处理翻译
如果发生冲突，在翻译合并后将main合并到您的分支

模型下载失败

问题： Foundry Local无法下载模型

解决方案：


# Check internet connectivity
# Clear model cache and retry
foundry model remove <model-alias>
foundry model run <model-alias>

# Check available disk space (models can be 2-16GB)
# Verify firewall settings allow downloads

附加资源

学习路径

初学者路径： 模块01-02（7-9小时）
中级路径： 模块03-04（9-11小时）
高级路径： 模块05-07（12-15小时）
专家路径： 模块08（8-10小时）
实践Workshop： Workshop材料（6-8小时）

关键模块内容

模块01： EdgeAI基础知识和真实案例研究
模块02： 小型语言模型（SLM）家族和架构
模块03： 本地和云部署策略
模块04： 使用多个框架进行模型优化（Llama.cpp、Microsoft Olive、OpenVINO、Qualcomm QNN、Apple MLX）
模块05： SLMOps - 生产操作
模块06： AI代理和函数调用
模块07： 平台特定实现
模块08： Foundry Local工具包，包含10个综合示例

外部依赖

Microsoft Foundry Local - 本地AI模型运行时，兼容OpenAI API
Llama.cpp - 优化框架
Microsoft Olive - 模型优化工具包
OpenVINO - Intel的优化工具包

项目特定说明

模块08示例应用

仓库包含10个综合示例应用：

01-REST聊天快速入门 - 基本OpenAI SDK集成
02-OpenAI SDK集成 - 高级SDK功能
03-模型发现与基准测试 - 模型比较工具
04-Chainlit RAG应用 - 检索增强生成
05-多代理编排 - 基本代理协调
06-模型作为工具路由器 - 智能模型路由
07-直接API客户端 - 低级API集成
08-Windows 11聊天应用 - 原生Electron桌面应用
09-高级多代理系统 - 复杂代理编排
10-Foundry 工具框架 - LangChain/Semantic Kernel 集成

工作坊示例应用

工作坊包括6个循序渐进的实践课程：

课程 01 - 使用 Foundry Local 集成进行聊天启动
课程 02 - 使用 RAGAS 进行 RAG 管道和评估
课程 03 - 开源模型的基准测试
课程 04 - 模型比较与选择
课程 05 - 多代理编排系统
课程 06 - 模型路由与管道管理

每个示例展示了使用 Foundry Local 进行边缘 AI 开发的不同方面。

性能考量

SLMs 针对边缘部署进行了优化（2-16GB RAM）
本地推理提供 50-500ms 的响应时间
量化技术实现了 75% 的大小缩减，同时保留 85% 的性能
使用本地模型实现实时对话功能

安全与隐私

所有处理均在本地完成 - 无数据发送至云端
适用于隐私敏感型应用（医疗、金融）
符合数据主权要求
Foundry Local 完全运行于本地硬件

获取帮助

文档

主 README: README.md - 仓库概览和学习路径
学习指南: STUDY_GUIDE.md - 学习资源和时间表
支持: SUPPORT.md - 如何获取帮助
安全性: SECURITY.md - 报告安全问题

社区支持

GitHub 问题: 报告错误或请求功能
GitHub 讨论: 提问和分享想法
Foundry Local 问题: Foundry Local 的技术问题

联系方式

维护者: 查看 CODEOWNERS
安全问题: 按照 SECURITY.md 中的负责任披露流程
微软支持: 对于企业支持，请联系微软客户服务

其他资源

Microsoft Learn: AI 和机器学习学习路径
Foundry Local 文档: 官方文档
社区示例: 查看 GitHub 讨论了解社区贡献

这是一个专注于教授边缘 AI 开发的教育性仓库。主要的贡献模式是改进教育内容以及添加/增强示例应用，以展示边缘 AI 概念。

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

AGENTS.md

文档摘要

AGENTS.md

目录

项目概述

仓库结构

先决条件

必需工具

推荐工具

系统要求

知识要求

设置命令

仓库设置

Python示例设置（模块08和Workshop示例）

Node.js示例设置（示例08 - Windows聊天应用）

Foundry Local设置

开发工作流

内容开发

示例应用开发

测试示例应用

测试说明

内容验证

示例应用测试

代码风格指南

Markdown内容

Python代码风格

JavaScript/Node.js代码风格

拉取请求指南

贡献工作流

分支命名约定

提交消息格式

标题格式

行为准则

提交前检查

审查流程

翻译系统

Foundry Local集成

安装与设置

启动Foundry Local

SDK使用（Python）

验证Foundry Local

示例所需环境变量

构建与部署

内容部署

示例应用构建

常见问题与故障排除

严重问题（阻塞）

Foundry Local未运行

常见问题（中等）

Python虚拟环境问题

Electron构建问题

工作流问题（轻微）

翻译工作流冲突

模型下载失败

附加资源

学习路径

关键模块内容

外部依赖

项目特定说明

模块08示例应用

工作坊示例应用

性能考量

安全与隐私

获取帮助

文档

社区支持

联系方式

其他资源