Foundry Local을 사용하면 Windows
메모
FOUNDry Local에 대한 전체 설명서(CLI, 모델 관리, 선택적 REST 서버, Python SDK 등)는 Microsoft Foundry 설명서에서 유지 관리됩니다. 이 페이지의 링크는 필요할 때 해당 페이지로 이동됩니다. 언제든지 브라우저의 뒤로 가기 버튼 또는 이동 경로를 사용하여 Windows AI 문서로 돌아갈 수 있습니다.
Foundry Local이 시나리오에 적합한지 확신이 안 드시면 계속하기 전에 Windows AI 솔루션 선택하기를 참조하세요.
Prerequisites
- Windows 11 버전 24H2(빌드 26100) 이상
- .NET 9.0 SDK 이상
- 선택한 모델에 충분한 메모리와 디스크 공간이 있는 x64 또는 Arm64 디바이스
- 초기 패키지, 모델 및 런타임 구성 요소 다운로드에 대한 인터넷 액세스
Windows SDK는 호환되는 CPU, GPU 및 NPU 모델 변형을 사용할 수 있습니다. 선택한 모델에 호환되는 CPU 변형이 있는 경우 전용 GPU, NPU 또는 Copilot+ PC 필요하지 않습니다. 사용 가능한 가속 및 성능은 디바이스, 모델 및 실행 공급자에 따라 달라집니다.
메모
이 빠른 시작에서는 현재 Foundry 로컬 별칭을 통해 사용할 수 있는 최신 Microsoft Phi 모델인 Phi-4 Mini를 phi-4-mini사용합니다. Foundry 로컬 카탈로그 별칭 및 권장 모델은 카탈로그가 진화함에 따라 변경됩니다.
Phi-4 Mini는 Windows 함께 제공되는 Windows AI API 모델인 Phi Silica와는 별개입니다. Phi Silica는 제한된 액세스 기능으로 남아 있으며 잠금 해제 토큰이 필요합니다. Limited Access Feature 토큰이 필요하지 않은 Aion Instruct로 대체될 예정입니다. 액세스 세부 정보 및 전환 일정은 Phi Silica 시작하기에서 확인하세요.
선택 사항: Foundry 로컬 CLI 설치
이 빠른 시작의 SDK 워크플로에는 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 패키지 설치
현재 안정적인 Windows 패키지를 설치합니다.
dotnet add package Microsoft.AI.Foundry.Local.WinML
패키지에는 Foundry Local 네이티브 채팅 API에서 사용되는 ChatMessage 및 관련 형식이 포함됩니다. 현재 디바이스에 대해 호환되는 모델 변형을 선택하고 하드웨어 가속에 Windows ML 실행 공급자를 사용할 수 있습니다.
메모
Windows 이외의 플랫폼을 대상으로 지정해야 하는 경우 대신 Microsoft.AI.Foundry.Local 사용합니다. Windows ML 통합 없이 동일한 Foundry 로컬 API 표면을 제공합니다.
위의 명령은 현재 안정적인 패키지를 설치합니다. WinUI 자습서에서는 .NET 10을 사용하며 전체 절차를 완전히 재현할 수 있도록 패키지 버전을 고정합니다.
빠른 시작: 모델 실행
내용을 다음으로 바꾼 다음 Program.cs실행합니다dotnet run. 이 프로그램은 Foundry Local을 초기화하고, 필요한 경우 모델을 다운로드하고, 채팅 완료를 실행하고, 정리합니다.
using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging.Abstractions;
using Betalgo.Ranul.OpenAI.ObjectModels.RequestModels;
// 1. Initialize the native in-process Foundry Local SDK.
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-4-mini")
?? throw new Exception(
"Model 'phi-4-mini' not found in catalog. " +
"Check your internet connection and available model aliases.");
// 3. Download the model if it is not already cached.
if (!await model.IsCachedAsync())
{
Console.Write("Downloading phi-4-mini...");
await model.DownloadAsync(progress =>
{
Console.Write($"\rDownloading phi-4-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. " +
"Try the request again or select another compatible model variant.");
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이 호환되는 하드웨어 변형을 선택할 수 있도록 모델 별칭 (전체 모델 ID 아님) GetModelAsync 을 전달합니다. 모델 및 디바이스에 따라 스냅드래곤의 QNN NPU 변형, NVIDIA의 CUDA 변형 또는 CPU 변형일 수 있습니다.
선택적 CLI를 설치한 경우 실행하여 사용 가능한 별칭을 확인합니다.
foundry model list
예를 들어 Microsoft Phi-4 Mini 모델에 사용합니다phi-4-mini. 카탈로그는 시간이 지남에 따라 변경되므로 Foundry 로컬 모델 카탈로그 에서 현재 별칭 및 사용 가능한 변형을 확인합니다.
Python 빠른 시작
Foundry Local은 Python, JavaScript(Node.js) 및 Rust도 지원합니다. 다음은 패턴이 작동하는지 확인하는 최소한의 Python 예제입니다. 네 가지 언어 모두에 대한 전체 연습은 Microsoft 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
Important
foundry-local PyPI의 패키지(제외-sdk)는 관련 없는 타사 패키지입니다.
foundry-local-sdk 또는 foundry-local-sdk-winml 설치하여 Microsoft Foundry 로컬 SDK를 가져옵니다.
app.py을 만듭니다.
from foundry_local_sdk import Configuration, FoundryLocalManager
FoundryLocalManager.initialize(Configuration(app_name="my-app"))
manager = FoundryLocalManager.instance
model = manager.catalog.get_model("phi-4-mini")
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 빠른 시작은 Microsoft Foundry 설명서에서 Foundry Local 시작(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()을(를) 호출합니다.
전체 애플리케이션 연습을 위해 WinUI 자습서를 계속 진행합니다. 명시적 모델 다운로드 동의, 진행률, 취소, 접근성 및 출력 검토에 대해 설명합니다.
클라우드로의 대비책
복원력 있는 다중 계층 패턴을 위해 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 전체 카탈로그를 찾습니다.
모델은 빈 콘텐츠를 반환합니다.
요청을 다시 시도하고 선택한 모델에 디바이스에 호환되는 변형이 있는지 확인합니다. 문제가 계속되면 더 작은 모델 또는 CPU 변형을 선택하고 디바이스에 사용 가능한 메모리가 충분한지 확인합니다.
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 로컬 SDK 참조 - SDK 설정 및 API 지침
- Windows ML — 모든 EP 제어를 사용하여 고유한 ONNX 모델을 가져옵니다.
- Windows AI 솔루션 사용 - 모든 Windows AI 옵션 비교