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. Yerel SDK uygulama işleminizde çalışır ve Foundry Local CLI veya ayrı bir yerel REST sunucusu gerektirmez. 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, isteğe bağlı REST sunucusu, Python SDK ve daha fazlası dahil olmak üzere Foundry Local için tam belgeler Microsoft Dökümhane 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 11, sürüm 24H2 (derleme 26100) veya üzeri
  • .NET 9.0 SDK veya üzeri
  • Seçtiğiniz model için yeterli bellek ve disk alanına sahip bir x64 veya Arm64 cihazı
  • İlk paket, model ve çalışma zamanı bileşeni indirmeleri için İnternet erişimi

Windows SDK'sı uyumlu CPU, GPU ve NPU model çeşitlemelerini kullanabilir. Seçilen model uyumlu bir CPU değişkenine sahip olduğunda ayrılmış GPU, NPU veya Copilot+ PC gerekli değildir. Kullanılabilir hızlandırma ve performans cihazınıza, modelinize ve yürütme sağlayıcınıza bağlıdır.

Note

Bu hızlı başlangıçta, şu anda Foundry Local diğer adı üzerinden kullanılabilen en son Microsoft Phi modeli olan phi-4-mini kullanılır. Foundry Local katalog takma adları ve önerilen modeller, katalog zaman içinde değiştikçe değişebilir.

Phi-4 Mini, Windows ile birlikte gelen Windows yapay zeka API'si modeli Phi Silica'dan ayrıdır. Phi Silica, Sınırlı Erişim özelliği olmayı sürdürmektedir ve bir kilit açma belirteci gerektirir. Yerine, Sınırlı Erişim Özelliği belirteci gerektirmeyen Aion Instruct'ın geçirilmesi planlanmaktadır. Erişim ayrıntıları ve geçiş zaman çizelgesi için bkz . Phi Silica'yı kullanmaya başlama .

İsteğe bağlı: Foundry Yerel CLI'sini yükleme

Bu hızlı başlangıçtaki SDK iş akışı CLI gerektirmez. Yalnızca modelleri bir terminalden incelemek ve yönetmek istiyorsanız 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

Geçerli kararlı Windows paketini yükleyin:

dotnet add package Microsoft.AI.Foundry.Local.WinML

Bu paket, Foundry Local yerel sohbet API’si tarafından kullanılan ChatMessage ve ilgili türleri içerir. Geçerli cihaz için uyumlu bir model çeşidi seçer ve donanım hızlandırma için Windows ML yürütme sağlayıcılarını kullanabilir.

Note

Windows olmayan platformları hedeflemeniz gerekiyorsa bunun yerine Microsoft.AI.Foundry.Local kullanın. Windows ML tümleştirmesi olmadan aynı Foundry Yerel API yüzeyini sağlar.

Yukarıdaki komut geçerli kararlı paketi yükler. WinUI öğreticisi .NET 10 kullanır ve paket sürümlerini sabitler; böylece öğreticideki adımların tamamını yeniden uygulayabilirsiniz.

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

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 uyumlu bir donanım çeşidi seçebilmesi için GetModelAsyncmodelin diğer adını (tam model kimliği değil) iletir. Modele ve cihaza bağlı olarak, bu Snapdragon'daki bir QNN NPU değişkeni, NVIDIA'daki bir CUDA değişkeni veya bir CPU değişkeni olabilir.

İsteğe bağlı CLI’yi yüklediyseniz, mevcut takma adları görmek için onu çalıştırın:

foundry model list

Örneğin, Microsoft Phi-4 Mini modeli için kullanınphi-4-mini. Katalog zaman içinde değişir, bu nedenle güncel diğer adlar ve kullanılabilir varyantlar için Foundry Yerel model kataloğunu kontrol edin.

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 Microsoft Dökümhane belgelerinde verilmiştir.

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

(foundry-local olmadan PyPI üzerindeki -sdk 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("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()

Çalıştırın:

python app.py

Yürütme sağlayıcısı kurulumu, hata işleme ve model listesi de dahil olmak üzere tam Python hızlı başlangıç için Microsoft Foundry belgelerindeki Foundry Yerel'i kullanmaya 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.

Eksiksiz bir uygulama kılavuzu için WinUI öğreticisine geçin. Bu, model indirme için açık onayı, ilerlemeyi, iptali, erişilebilirliği ve çıktının gözden geçirilmesini kapsar.

WinUI uygulamasına yerel yapay zeka ekleme

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
İsteği yeniden deneyin ve seçili modelin cihazınız için uyumlu bir değişkene sahip olduğunu onaylayın. Sorun devam ederse daha küçük bir model veya CPU değişkeni seçin ve cihazda yeterli kullanılabilir belleğe sahip olup olmadığını denetleyin.

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