Foundry Local을 시작하십시오.

Foundry Local을 사용하면 Windows Microsoft Foundry의 일부로 Windows 디바이스에서 직접 LLM(대규모 언어 모델)을 로컬로 실행할 수 있습니다. Windows AI API보다 더 깊이 들어가거나 Copilot+ PC 아닌 하드웨어를 지원해야 하는 경우 좋은 대안입니다. 특별한 사용 권한이나 잠금 해제 토큰은 필요하지 않습니다. 이 토큰은 전적으로 사용자 고유의 하드웨어에서 실행됩니다. 동일한 패턴은 콘솔 앱, WinUI 3 앱, WPF 앱 또는 다른 .NET 호스트에서 작동합니다.

Prerequisites

• Windows 10 빌드 26100 이상(Windows 11 24H2 이상 권장)
• .NET 9.0 SDK 이상
• DirectX 12 지원 GPU(통합 또는 불연속). 패키지는 WinML 하드웨어 가속을 사용하며 실제 GPU 하드웨어가 필요합니다. GPU 통과가 없는 가상 머신은 지원되지 않습니다.

Foundry 로컬 CLI 설치

winget을 사용하여 CLI를 설치합니다.

winget install Microsoft.FoundryLocal

그런 다음 foundry 명령이 PATH에 등록되도록 터미널을 닫았다가 다시 엽니다. 확인:

foundry --version

프로젝트 만들기

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

NuGet 패키지에는 네이티브 Windows 이진 파일이 포함되어 있으므로 프로젝트에는 Windows 대상 프레임워크 및 런타임 식별자가 필요합니다. FoundryLocalDemo.csproj을 열고 <PropertyGroup> 블록을 다음 내용으로 바꾸세요:

<PropertyGroup>
  <OutputType>Exe</OutputType>
  <TargetFramework>net9.0-windows10.0.26100.0</TargetFramework>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
  <RuntimeIdentifiers>win-x64;win-arm64</RuntimeIdentifiers>
</PropertyGroup>

그런 다음 복원하여 새 대상에 대한 자산 파일을 생성합니다.

dotnet restore

NuGet 패키지 설치

ONNX 런타임을 통해 사용 가능한 최상의 하드웨어(퀄컴 NPU, NVIDIA GPU 또는 CPU)를 자동으로 사용하는 WinML 패키지를 설치합니다.

dotnet add package Microsoft.AI.Foundry.Local.WinML --version 1.0.0
dotnet add package Betalgo.Ranul.OpenAI --version 9.1.0

Betalgo.Ranul.OpenAI 패키지는 Foundry 로컬 채팅 API에서 사용하는 ChatMessage 및 관련 타입을 제공합니다.

빠른 시작: 모델 실행

내용을 다음으로 바꾼 다음 Program.cs실행합니다dotnet run. 이 프로그램은 Foundry Local을 초기화하고, 필요한 경우 모델을 다운로드하고, 채팅 완료를 실행하고, 정리합니다.

using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging.Abstractions;
using Betalgo.Ranul.OpenAI.ObjectModels.RequestModels;

// 1. Initialize Foundry Local. The SDK starts the service automatically if needed.
await FoundryLocalManager.CreateAsync(
    new Configuration { AppName = "my-app" },
    NullLogger.Instance);

var manager = FoundryLocalManager.Instance;
try
{
    // 2. Look up the model in the catalog by alias.
    var catalog = await manager.GetCatalogAsync();
    var model = await catalog.GetModelAsync("phi-3.5-mini")
        ?? throw new Exception(
            "Model 'phi-3.5-mini' not found in catalog. " +
            "Ensure Foundry Local is installed and has internet access.");

    // 3. Download the model if it is not already cached (2.53 GB).
    if (!await model.IsCachedAsync())
    {
        Console.Write("Downloading phi-3.5-mini...");
        await model.DownloadAsync(progress =>
        {
            Console.Write($"\rDownloading phi-3.5-mini  {progress,5:F1}%");
        });
        Console.WriteLine();
    }

    // 4. Load the model into memory.
    await model.LoadAsync();

    // 5. Run a chat completion.
    var chatClient = await model.GetChatClientAsync();
    var response = await chatClient.CompleteChatAsync(new[]
    {
        new ChatMessage { Role = "system", Content = "You are a helpful assistant." },
        new ChatMessage { Role = "user", Content = "Explain async/await in C# in two sentences." }
    });

    if (!response.Successful)
        throw new Exception(
            $"Chat completion failed: {response.Error?.Message ?? "unknown error"} " +
            $"(code: {response.Error?.Code})");

    var content = response.Choices![0].Message.Content;
    if (string.IsNullOrEmpty(content))
        throw new Exception(
            "Model returned empty content. " +
            "Verify that your device has a DirectX 12-capable GPU. " +
            "Virtual machines without GPU passthrough are not supported.");

    Console.WriteLine(content);
}
finally
{
    // 6. Clean up — always runs even if an earlier step throws.
    manager.Dispose();
}

스트리밍 응답

UI 앱에서 사용자 환경을 개선하려면 응답 토큰을 토큰별로 스트리밍합니다. 이 코드 조각은 위의 chatClient에서 계속되며, 5단계에서 유래합니다.

using var cts = new CancellationTokenSource();

await foreach (var chunk in chatClient.CompleteChatStreamingAsync(
    new[] { new ChatMessage { Role = "user", Content = "Write a haiku about Windows." } },
    cts.Token))
{
    Console.Write(chunk.Choices?[0]?.Message?.Content);
}
Console.WriteLine();

생성 파라미터 조정

chatClient.Settings.Temperature = 0.7f;
chatClient.Settings.MaxTokens = 512;
chatClient.Settings.TopP = 0.9f;

모델 별칭

Foundry Local이 스냅드래곤의 QNN NPU 변형, NVIDIA의 CUDA 변형 또는 다른 모든 곳에서 CPU 대체와 같은 최상의 하드웨어 변형을 자동으로 선택하도록 모델 별칭 (전체 모델 ID 아님) GetModelAsync 을 전달합니다.

CLI를 실행하여 사용 가능한 별칭을 확인합니다.

foundry model list

일반적인 별칭: phi-3.5-mini, phi-4( qwen2.5-0.5b 가장 작은 - 빠른 테스트에 적합), qwen2.5-7b. deepseek-r1-7b 전체 카탈로그는 foundrylocal.ai/models.

Python 빠른 시작

Foundry Local은 Python, JavaScript(Node.js) 및 Rust도 지원합니다. 다음은 패턴이 작동하는지 확인하는 최소한의 Python 예제입니다. 네 가지 언어 모두에 대한 전체 연습은 Azure AI Foundry 문서 있습니다.

다음 중 하나를 설치합니다. 충돌하는 onnxruntime-core 종속성이 있으므로 둘 다 설치하지 마세요.

pip install foundry-local-sdk-winml   # Windows — includes hardware acceleration (recommended on Windows)
pip install foundry-local-sdk         # macOS/Linux, or Windows without hardware acceleration

app.py을 만듭니다.

from foundry_local_sdk import Configuration, FoundryLocalManager

FoundryLocalManager.initialize(Configuration(app_name="my-app"))
manager = FoundryLocalManager.instance

model = manager.catalog.get_model("qwen2.5-0.5b")
model.download(lambda p: print(f"\rDownloading {p:.0f}%", end="", flush=True))
model.load()

client = model.get_chat_client()
for chunk in client.complete_streaming_chat([{"role": "user", "content": "Why is the sky blue?"}]):
    print(chunk.choices[0].delta.content or "", end="", flush=True)
print()

model.unload()

다음을 실행합니다.

python app.py

실행 공급자 설정, 오류 처리 및 모델 목록을 비롯한 전체 Python 빠른 시작은 Azure AI Foundry 문서에서 Get started with Foundry Local을 참조하세요.

WinUI 3 또는 WPF 앱에서 사용

App.xaml.cs 또는 App.cs에서 한 번 초기화:

protected override async void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    await FoundryLocalManager.CreateAsync(
        new Configuration { AppName = "MyWinUIApp" },
        NullLogger.Instance);
    // ...
}

그런 다음 앱 어디서나 FoundryLocalManager.Instance 을 해결합니다. 앱의 종료 처리기에서 Dispose()을(를) 호출합니다.

클라우드로의 대비책

복원력 있는 다중 계층 패턴을 위해 Foundry Local을 Windows AI API 및 Azure OpenAI와 결합합니다. 컴파일 가능한 전체 예제는 Windows AI 솔루션 사용을 참조하세요.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
이러한 경고는 프로그램이 종료된 후에 표시되며 무해합니다. 기본 ONNX 런타임 GenAI(OGA) 라이브러리의 네이티브 리소스 추적에서 제공됩니다. 출력이 올바릅니다. 경고는 코드에 문제가 있음을 나타내지 않습니다.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
ONNX 런타임의 이 경고는 라이브러리가 CPU 기능 검색을 위해 ARM SoC를 인식하지 못한다는 것을 의미합니다. 안전한 기본값으로 되돌아가고 일반적으로 유추가 실행됩니다. 어떤 조치도 필요하지 않습니다.

Model '...' not found in catalog
SDK는 인터넷에서 모델 카탈로그를 가져옵니다. 네트워크 연결을 확인합니다. 특정 모델 별칭을 찾을 수 없는 경우 실행 foundry model list 하여 사용 가능한 별칭을 확인하거나 foundrylocal.ai/models 전체 카탈로그를 찾습니다.

모델은 빈 콘텐츠를 반환합니다.
WinML 백 엔드에는 DirectX 12 지원 GPU가 필요합니다. GPU 통과가 없는 가상 머신은 빈 콘텐츠로 성공적인 응답을 반환합니다. 개별 또는 통합 GPU를 사용하여 물리적 하드웨어에서 실행합니다.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
이 pip 종속성 충돌은 foundry-local-sdk-winml와 foundry-local-sdk가 모두 설치되어 있으며, 각각 onnxruntime-core의 다른 버전을 고정하여 공존할 수 없음을 의미합니다. 하나 제거:

pip uninstall foundry-local-sdk        # if you want the winml (Windows) package
pip uninstall foundry-local-sdk-winml  # if you want the cross-platform package

그런 다음 원하는 항목을 다시 설치합니다. 가상 환경을 사용하면 이 문제를 완전히 방지할 수 있습니다.

• Full Foundry 로컬 설명서 — CLI, REST API, Python SDK, 모델 관리
• Foundry 로컬 C# SDK 참조 - 전체 API 참조
• Windows ML — 모든 EP 제어를 사용하여 고유한 ONNX 모델을 가져옵니다.
• Windows AI 솔루션 사용 - 모든 Windows AI 옵션 비교