Foundry Local'ı kullanmaya başlama

Foundry Local, Windows üzerinde Microsoft Foundry'nin bir parçası olarak büyük dil modellerinin (LLM) doğrudan Windows cihazınızda yerel olarak yürütülmesini sağlar. Windows AI API'lerinden daha derine gitmeniz veya Copilot+ PC olmayan donanımları desteklemeniz gerektiğinde iyi bir alternatiftir. Özel izinler veya kilit açma belirteçleri gerekmez; tamamen kendi donanımınızda çalışır. Aynı desen konsol uygulamasında, WinUI 3 uygulamasında, WPF uygulamasında veya başka bir .NET ana bilgisayarında da çalışır.

Foundry Local ile ilişkili teknolojilerin logoları

Note

Cli, model yönetimi, REST API, Python SDK ve daha fazlası dahil olmak üzere Foundry Local belgelerinin tamamı Azure Yapay Zeka Atölyesi belgelerinde tutulur. Bu sayfadaki bağlantılar gerektiğinde sizi oraya götürür. İstediğiniz zaman Windows yapay zeka belgelerine dönmek için tarayıcınızın geri düğmesini veya içerik haritasını kullanın.

Foundry Local'ın senaryonuz için doğru seçim olup olmadığından emin değilseniz devam etmeden önce bkz. Windows AI çözümünüzü bulma.

Prerequisites

  • Windows 10 derleme 26100 veya üzeri (Windows 11 24H2 veya üzeri önerilir)
  • .NET 9.0 SDK veya üzeri
  • DirectX 12 özellikli GPU (tümleşik veya ayrık). Paket WinML donanım hızlandırma kullanır ve gerçek GPU donanımı gerektirir; GPU geçişi olmayan sanal makineler desteklenmez.

Foundry Yerel CLI'sını yükleme

Winget kullanarak CLI'yi yükleyin:

winget install Microsoft.FoundryLocal

Ardından, komutun PATH'inizde olması için foundry terminalinizi kapatıp yeniden açın. Doğrula

foundry --version

Bir proje oluştur

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

NuGet paketi yerel Windows ikili dosyaları içerdiğinden projenin Windows bir hedef çerçeveye ve çalışma zamanı tanımlayıcılarına ihtiyacı vardır. FoundryLocalDemo.csproj açın ve <PropertyGroup> bloğunu şununla değiştirin:

<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>

Ardından yeni hedef için varlık dosyasını oluşturmak üzere geri yükleyin:

dotnet restore

NuGet paketini yükleme

ONNX Çalışma Zamanı aracılığıyla otomatik olarak en iyi kullanılabilir donanımı (Qualcomm NPU, NVIDIA GPU veya CPU) kullanan WinML paketini yükleyin:

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

Paket, Betalgo.Ranul.OpenAI Foundry Yerel sohbet API'si tarafından kullanılan ChatMessage ve ilgili türleri içerir.

Note

Windows olmayan platformları hedeflemeniz gerekiyorsa bunun yerine Microsoft.AI.Foundry.Local kullanın. API aynıdır; bu paket, Windows özgü donanım hızlandırmasını atlar.

Hızlı başlangıç: model çalıştırma

Program.cs içeriğini aşağıdakilerle değiştirin ve ardından dotnet run çalıştırın. Program Foundry Local'ı başlatır, gerekirse modeli indirir, sohbet tamamlama işlemini çalıştırır ve temizler.

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();
}

Akış yanıtları

Kullanıcı arabirimi uygulamalarında daha iyi bir kullanıcı deneyimi için yanıt belirtecini belirteçe göre akışla aktarın. Bu kod parçacığı yukarıdaki hızlı başlangıçtan devam eder— chatClient 5. adımdan gelir:

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();

Oluşturma parametrelerini ayarlama

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

Model diğer adları

Foundry Local'ın otomatik olarak en iyi donanım varyantını seçebilmesi için, modelin takma adını (tam model kimliği değil) GetModelAsync ile geçin; örneğin, Snapdragon üzerinde QNN NPU varyantı, NVIDIA'da CUDA varyantı veya başka yerlerde CPU seçeneği kullanılır.

Kullanılabilir diğer adları görmek için CLI'yi çalıştırın:

foundry model list

Yaygın diğer adlar: phi-3.5-mini, phi-4, qwen2.5-0.5b (en küçük — hızlı test için iyidir), qwen2.5-7b, deepseek-r1-7b. Kataloğun tamamı foundrylocal.ai/models.

Python'a hızlı başlangıç

Foundry Local ayrıca Python, JavaScript (Node.js) ve Rust'ı da destekler. Desenin çalıştığını onaylamak için en düşük Python örneği aşağıda verilmiştir; dört dilin de tam kılavuzu Azure Yapay Zeka Atölyesi docs içindedir.

Aşağıdakilerden birini yükleyin; çakışan bağımlılıkları olduğundan ikisini de yüklemeyinonnxruntime-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

(-sdk olmadan PyPI üzerindeki foundry-local paketi), ilişkili olmayan bağımsız bir üçüncü taraf pakettir. Microsoft Foundry Yerel SDK'sını almak için foundry-local-sdk veya foundry-local-sdk-winml yükleyin.

Oluştur 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()

Çalıştırın:

python app.py

Yürütme sağlayıcısı kurulumu, hata işleme ve model listesi dahil olmak üzere tam Python hızlı başlangıç için Azure Yapay Zeka Atölyesi belgelerindeki Foundry Local ile çalışmaya başlama bölümüne bakın.

WinUI 3 veya WPF uygulamasından kullanma

App.xaml.cs veya App.cs içinde bir kez başlatın.

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

Ardından uygulamanın herhangi bir yerinde çözümleyin FoundryLocalManager.Instance . Çıkış işleyicisinde Dispose() öğesini uygulamada çağırın.

Buluta geri dönüş

Foundry Local ile Windows AI API'leri'ni ve Azure OpenAI'yi birleştirerek dayanıklı bir çok katmanlı yapı oluşturun. Eksiksiz bir derlenebilir örnek için bakınız Windows AI çözümünüzü seçin.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Bu uyarılar programdan çıktıktan sonra görünür ve zararsızdır. Bunlar, temel alınan ONNX Runtime GenAI (OGA) kitaplığının yerel kaynak izlemesinden gelir. Çıkışınız doğru; uyarılar kodunuzla ilgili bir sorun olduğunu göstermez.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
ONNX Çalışma Zamanı'ndan gelen bu uyarı, kitaplığın CPU özellik algılama için ARM SoC'nizi tanımadığı anlamına gelir. Güvenli varsayılanlara geri döner ve çıkarım normal şekilde çalışır. Eyleme gerek yoktur.

Model '...' not found in catalog
SDK, model kataloğunu İnternet'ten getirir. Ağ bağlantınızı denetleyin. Belirli bir model diğer adı bulunamazsa, kullanılabilir diğer adları görmek için komutunu çalıştırın foundry model list veya foundrylocal.ai/models'da tam kataloğa göz atın.

Model boş içerik döndürüyor
WinML arka ucu, DirectX 12 özellikli bir GPU gerektirir. GPU geçişi olmayan sanal makineler boş içerikle başarılı bir yanıt döndürür. Ayrık veya tümleşik GPU ile fiziksel donanım üzerinde çalıştırın.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Bu pip bağımlılığı çakışması, hem foundry-local-sdk-winml hem de foundry-local-sdk'in yüklü olduğu anlamına gelir; bu bileşenler, onnxruntime-core'nin farklı sürümlerine sabitlenmiş olup birlikte var olamazlar. Birini kaldırın:

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

Ardından istediğinizi yeniden yükleyin. Sanal ortam kullanmak bu sorunu tamamen önler.

  • Last updated on