第一节：开始使用FoundryLocal

文档摘要

第1节：开始使用 Foundry Local 概述 Microsoft Foundry Local 将 Azure AI Foundry 的功能直接带到您的 Windows 11 开发环境中，提供隐私保护、低延迟的 AI 开发体验，并配备企业级工具。本节内容涵盖了流行模型（包括 phi、qwen、deepseek 和 GPT-OSS-20B）的完整安装、配置和实际部署。学习目标完成本节后，您将能够：在 Windows 11 上安装和配置 Foundry Local 掌握 CLI 命令和配置选项了解模型缓存策略以优化性能成功运行 phi、qwen、deepseek 和 GPT-OSS-20B 模型使用 Foundry Local 创建您的第一个 AI 应用程序前置条件系统要求

第1节：开始使用 Foundry Local

概述

Microsoft Foundry Local 将 Azure AI Foundry 的功能直接带到您的 Windows 11 开发环境中，提供隐私保护、低延迟的 AI 开发体验，并配备企业级工具。本节内容涵盖了流行模型（包括 phi、qwen、deepseek 和 GPT-OSS-20B）的完整安装、配置和实际部署。

学习目标

完成本节后，您将能够：

在 Windows 11 上安装和配置 Foundry Local
掌握 CLI 命令和配置选项
了解模型缓存策略以优化性能
成功运行 phi、qwen、deepseek 和 GPT-OSS-20B 模型
使用 Foundry Local 创建您的第一个 AI 应用程序

前置条件

系统要求

Windows 11：版本 22H2 或更高
内存：最低 16GB，推荐 32GB
存储：50GB 可用空间用于模型和缓存
硬件：建议使用支持 NPU 或 GPU 的设备（如 Copilot+ PC 或 NVIDIA GPU）
网络：高速互联网连接以下载模型

开发环境


# Verify Windows version
winver

# Check available memory
Get-ComputerInfo | Select-Object TotalPhysicalMemory

# Verify PowerShell version (5.1+ required)
$PSVersionTable.PSVersion

# Set up Python environment (recommended)
py -m venv .venv
.venv\Scripts\activate

# Install required dependencies
pip install openai foundry-local-sdk

第1部分：安装和设置

步骤1：安装 Foundry Local

使用 Winget 安装 Foundry Local 或从 GitHub 下载安装程序：


# Winget (Windows)
winget install --id Microsoft.FoundryLocal --source winget

# Alternatively: download installer from the official repo
# https://aka.ms/foundry-local-installer

步骤2：验证安装


# Check Foundry Local version
foundry --version

# Verify CLI accessibility and categories
foundry --help
foundry model --help
foundry cache --help
foundry service --help

第2部分：了解 CLI

核心命令结构


# General command structure
foundry [category] [command] [options]

# Main categories
foundry model   # manage and run models
foundry service # manage the local service
foundry cache   # manage local model cache

# Common commands
foundry model list              # list available models
foundry model run phi-4-mini  # run a model (downloads as needed)
foundry cache ls                # list cached models

第3部分：模型缓存和管理

Foundry Local 实现了智能模型缓存，以优化性能和存储：


# Show cache contents
foundry cache ls

# Optional: change cache directory (advanced)
foundry cache cd "C:\\FoundryLocal\\Cache"
foundry cache ls

第4部分：模型部署实操

运行 Microsoft Phi 模型


# List catalog and run Phi (auto-downloads best variant for your hardware)
foundry model list
foundry model run phi-4-mini

使用 Qwen 模型


# Run Qwen2.5 models (downloads on first run)
foundry model run qwen2.5-7b
foundry model run qwen2.5-14b

运行 DeepSeek 模型


# Run DeepSeek model
foundry model run deepseek-r1-7b

运行 GPT-OSS-20B


# Run the latest OpenAI open-source model (requires recent Foundry Local and sufficient GPU VRAM)
foundry model run gpt-oss-20b

# Check version if you encounter errors (requires 0.6.87+ per docs)
foundry --version

第5部分：创建您的第一个应用程序

现代聊天应用程序（OpenAI SDK + Foundry Local）

使用 OpenAI SDK 和 Foundry Local 集成创建一个生产级聊天应用程序，遵循我们的示例 01 的模式。


# chat_quickstart.py (Sample 01 pattern)
import os
import sys
from openai import OpenAI

try:
    from foundry_local import FoundryLocalManager
    FOUNDRY_SDK_AVAILABLE = True
except ImportError:
    FOUNDRY_SDK_AVAILABLE = False
    print("⚠️ Install foundry-local-sdk: pip install foundry-local-sdk")

def create_client():
    """Create OpenAI client with Foundry Local or Azure OpenAI."""
    # Check for Azure OpenAI configuration
    azure_endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
    azure_api_key = os.environ.get("AZURE_OPENAI_API_KEY")
    
    if azure_endpoint and azure_api_key:
        # Azure OpenAI path
        model = os.environ.get("MODEL", "your-deployment-name")
        client = OpenAI(
            base_url=f"{azure_endpoint}/openai",
            api_key=azure_api_key,
            default_query={"api-version": "2024-08-01-preview"},
        )
        print(f" Using Azure OpenAI with model: {model}")
        return client, model
    
    # Foundry Local path with SDK management
    alias = os.environ.get("MODEL", "phi-4-mini")
    if FOUNDRY_SDK_AVAILABLE:
        try:
            # Use FoundryLocalManager for proper service management
            manager = FoundryLocalManager(alias)
            model_info = manager.get_model_info(alias)
            
            client = OpenAI(
                base_url=manager.endpoint,
                api_key=manager.api_key
            )
            model = model_info.id
            print(f" Using Foundry Local SDK with model: {model}")
            return client, model
        except Exception as e:
            print(f"⚠️ Foundry SDK failed ({e}), using manual configuration")
    
    # Fallback to manual configuration
    base_url = os.environ.get("BASE_URL", "http://localhost:8000")
    api_key = os.environ.get("API_KEY", "")
    model = alias
    
    client = OpenAI(
        base_url=f"{base_url}/v1",
        api_key=api_key
    )
    print(f" Manual configuration with model: {model}")
    return client, model

def main():
    """Main chat function."""
    client, model = create_client()
    
    print("Foundry Local Chat Interface (type 'quit' to exit)\n")
    conversation_history = []
    
    while True:
        user_input = input("You: ")
        if user_input.lower() == 'quit':
            break
        
        try:
            # Add user message to history
            conversation_history.append({"role": "user", "content": user_input})
            
            # Create chat completion
            response = client.chat.completions.create(
                model=model,
                messages=conversation_history,
                max_tokens=500,
                temperature=0.7
            )
            
            assistant_message = response.choices[0].message.content
            conversation_history.append({"role": "assistant", "content": assistant_message})
            
            print(f"Assistant: {assistant_message}\n")
            
        except Exception as e:
            print(f"Error: {e}\n")

if __name__ == "__main__":
    main()

运行聊天应用程序


# Ensure the model is running in another terminal
foundry model run phi-4-mini

# Option 1: Using FoundryLocalManager (recommended)
python chat_quickstart.py "Explain what Foundry Local is"

# Option 2: Manual configuration with environment variables
set BASE_URL=http://localhost:8000
set MODEL=phi-4-mini
set API_KEY=
python chat_quickstart.py "Write a welcome message"

# Option 3: Azure OpenAI configuration
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
set MODEL=your-deployment-name
python chat_quickstart.py "Hello from Azure OpenAI"

第6部分：故障排除和最佳实践

常见问题及解决方案


# Issue: "Could not use Foundry SDK" warning
pip install foundry-local-sdk
# Or set environment variables for manual configuration

# Issue: Connection refused
foundry service status
foundry service ps  # Check loaded models

# Issue: Model not found
foundry model list
foundry model run phi-4-mini

# Issue: Cache problems or low disk space
foundry cache ls
foundry cache clean

# Issue: GPT-OSS-20B not supported on your version
foundry --version
winget upgrade --id Microsoft.FoundryLocal

# Test API endpoint
curl http://localhost:8000/v1/models

监控系统资源（Windows）


# Quick CPU and process view
Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10
Get-Counter '\\Processor(_Total)\\% Processor Time' -SampleInterval 1 -MaxSamples 10

环境变量

变量	描述	默认值	是否必需
`MODEL`	模型别名或名称	`phi-4-mini`	否
`BASE_URL`	Foundry Local 基础 URL	`http://localhost:8000`	否
`API_KEY`	API 密钥（通常本地不需要）	`""`	否
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI 端点	-	用于 Azure
`AZURE_OPENAI_API_KEY`	Azure OpenAI API 密钥	-	用于 Azure
`AZURE_OPENAI_API_VERSION`	Azure API 版本	`2024-08-01-preview`	否

最佳实践

使用 OpenAI SDK：优先使用 OpenAI SDK 而非原始 HTTP 请求，以提高可维护性
FoundryLocalManager：在可用时使用官方 SDK 进行服务管理
错误处理：为生产应用程序实施适当的回退策略
定期升级：保持 Foundry Local 更新以获取新模型和修复
从小开始：从较小的模型（Phi mini、Qwen 7B）开始，然后逐步扩展
监控资源：在调整提示和设置时跟踪 CPU/GPU/内存使用情况

第7部分：实操练习

练习1：快速多模型测试


# deploy-models.ps1
$models = @(
    "phi-4-mini",
    "qwen2.5-7b"
)
foreach ($model in $models) {
    Write-Host "Running $model..."
    foundry model run $model --verbose
}

练习2：OpenAI SDK 集成测试


# sdk_integration_test.py (matching Sample 01 pattern)
import os
from openai import OpenAI
from foundry_local import FoundryLocalManager

def test_model_integration(model_alias):
    """Test OpenAI SDK integration with different models."""
    try:
        # Use FoundryLocalManager for proper setup
        manager = FoundryLocalManager(model_alias)
        model_info = manager.get_model_info(model_alias)
        
        client = OpenAI(
            base_url=manager.endpoint,
            api_key=manager.api_key
        )
        
        # Test basic completion
        response = client.chat.completions.create(
            model=model_info.id,
            messages=[{"role": "user", "content": "Say hello and state your model name."}],
            max_tokens=50
        )
        
        print(f"✅ {model_alias}: {response.choices[0].message.content}")
        return True
    except Exception as e:
        print(f"❌ {model_alias}: {e}")
        return False

# Test multiple models
models_to_test = ["phi-4-mini", "qwen2.5-7b"]
for model in models_to_test:
    test_model_integration(model)

练习3：全面服务健康检查


# health_check.py
from openai import OpenAI
from foundry_local import FoundryLocalManager

def comprehensive_health_check():
    """Perform comprehensive health check of Foundry Local service."""
    try:
        # Initialize with a common model
        manager = FoundryLocalManager("phi-4-mini")
        client = OpenAI(
            base_url=manager.endpoint,
            api_key=manager.api_key
        )
        
        # 1. Check service connectivity
        models_response = client.models.list()
        available_models = [model.id for model in models_response.data]
        print(f"✅ Service healthy - {len(available_models)} models available")
        
        # 2. Test each available model
        for model_id in available_models:
            try:
                response = client.chat.completions.create(
                    model=model_id,
                    messages=[{"role": "user", "content": "Test"}],
                    max_tokens=10
                )
                print(f"✅ {model_id}: Working")
            except Exception as e:
                print(f"❌ {model_id}: {e}")
        
        return True
    except Exception as e:
        print(f"❌ Service check failed: {e}")
        return False

comprehensive_health_check()

参考资料

开始使用 Foundry Local: https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/get-started
CLI 参考和命令概述: https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/reference/reference-cli
OpenAI SDK 集成: https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/how-to/how-to-integrate-with-inference-sdks
编译 Hugging Face 模型: https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/how-to/how-to-compile-hugging-face-models
Microsoft Foundry Local GitHub: https://github.com/microsoft/Foundry-Local
OpenAI Python SDK: https://github.com/openai/openai-python
示例 01：通过 OpenAI SDK 快速聊天: samples/01/README.md
示例 02：高级 SDK 集成: samples/02/README.md

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

作者与出处

原作者： microsoft

来源：microsoft

原文： https://github.com/microsoft/edgeai-for-beginners

许可证：MIT

整理：灏天文库整理

由灏天文库结构化整理，提供目录导航、全文检索与在线阅读，便于系统化学习