Mulai menggunakan Foundry Local

Foundry Local memungkinkan eksekusi lokal model bahasa besar (LLM) langsung di perangkat Windows Anda, sebagai bagian dari Microsoft Foundry pada Windows. Ini adalah alternatif yang baik ketika Anda perlu masuk lebih dalam dari API AI Windows, atau perlu mendukung perangkat keras yang bukan Copilot+ PC. Tidak diperlukan izin khusus atau membuka kunci token. SDK asli berjalan dalam proses aplikasi Anda dan tidak memerlukan Foundry Local CLI atau server REST lokal terpisah. Pola yang sama berfungsi di aplikasi konsol, aplikasi WinUI 3, aplikasi WPF, atau host .NET lainnya.

Logo teknologi yang terkait dengan Foundry Local

Note

Dokumentasi lengkap untuk Foundry Local — termasuk CLI, manajemen model, server REST opsional, Python SDK, dan banyak lagi — dipertahankan dalam dokumentasi Microsoft Foundry. Tautan di halaman ini membawa Anda ke sana saat diperlukan. Gunakan tombol kembali browser Anda atau remah roti untuk kembali ke dokumen AI Windows kapan saja.

Jika Anda tidak yakin apakah Foundry Local adalah pilihan yang tepat untuk skenario Anda, lihat Memilih solusi AI Windows Anda sebelum melanjutkan.

Prerequisites

  • Windows 11, versi 24H2 (build 26100) atau yang lebih baru
  • .NET 9.0 SDK atau yang lebih baru
  • Perangkat x64 atau Arm64 dengan memori dan ruang disk yang cukup untuk model yang Anda pilih
  • Akses internet untuk mengunduh paket awal, model, dan komponen runtime

SDK Windows dapat menggunakan varian model CPU, GPU, dan NPU yang kompatibel. GPU, NPU, atau Copilot+ PC khusus tidak diperlukan saat model yang dipilih memiliki varian CPU yang kompatibel. Akselerasi dan performa yang tersedia bergantung pada perangkat, model, dan penyedia eksekusi Anda.

Note

Panduan singkat ini menggunakan Phi-4 Mini, yang saat ini merupakan model Microsoft Phi terbaru yang tersedia melalui alias phi-4-miniFoundry Local. Alias katalog Lokal Foundry dan model yang direkomendasikan dapat berubah seiring berkembangnya katalog.

Phi-4 Mini terpisah dari Phi Silica, model API AI Windows yang dikirim dengan Windows. Phi Silica tetap menjadi Fitur Akses Terbatas dan memerlukan token pembuka kunci. Fitur ini dijadwalkan akan digantikan oleh Aion Instruct, yang tidak memerlukan token Fitur Akses Terbatas. Lihat Mulai menggunakan Phi Silica untuk detail akses dan garis waktu transisi.

Opsional: Instal Foundry Local CLI

Alur kerja SDK dalam panduan memulai cepat ini tidak memerlukan CLI. Instal hanya jika Anda juga ingin memeriksa dan mengelola model dari terminal:

winget install Microsoft.FoundryLocal

Kemudian tutup dan buka kembali terminal Anda sehingga foundry perintah ada di PATH Anda. Memverifikasi:

foundry --version

Membuat proyek

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

Paket NuGet mencakup biner Windows asli, sehingga proyek memerlukan kerangka kerja target Windows dan pengidentifikasi runtime. Buka FoundryLocalDemo.csproj dan ganti <PropertyGroup> blok dengan:

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

Kemudian pulihkan untuk menghasilkan file aset untuk target baru:

dotnet restore

Menginstal paket NuGet

Instal paket Windows stabil saat ini:

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

Paket ini mencakup ChatMessage dan jenis terkait yang digunakan oleh API chat native Foundry Local. Ini memilih varian model yang kompatibel untuk perangkat saat ini dan dapat menggunakan penyedia eksekusi ML Windows untuk akselerasi perangkat keras.

Note

Jika Anda perlu menargetkan platform non-Windows, gunakan Microsoft.AI.Foundry.Local sebagai gantinya. Ini menyediakan cakupan API Foundry Local yang sama tanpa integrasi Windows ML.

Perintah di atas menginstal paket stabil saat ini. tutorial WinUI menggunakan .NET 10 dan mengunci versi paket agar Anda dapat mengikuti ulang seluruh panduannya.

Mulai cepat: menjalankan model

Ganti konten Program.cs dengan yang berikut ini, lalu jalankan dotnet run. Program ini menginisialisasi Foundry Local, mengunduh model jika diperlukan, menjalankan fungsi penyelesaian obrolan, dan melakukan pembersihan.

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

Respons streaming

Untuk meningkatkan pengalaman pengguna di aplikasi UI, lakukan streaming respons secara token-demi-token. Cuplikan ini berlanjut dari panduan cepat di atas: chatClient berasal dari langkah 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();

Menyetel parameter pembuatan

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

Alias untuk model

Berikan alias model (bukan ID model lengkap) ke GetModelAsync agar Foundry Local dapat memilih varian perangkat keras yang kompatibel. Bergantung pada model dan perangkat, ini bisa menjadi varian NPU QNN pada Snapdragon, varian CUDA pada NVIDIA, atau varian CPU.

Jika Anda menginstal CLI opsional, jalankan untuk melihat alias yang tersedia:

foundry model list

Misalnya, gunakan phi-4-mini untuk model Microsoft Phi-4 Mini. Katalog berubah dari waktu ke waktu, jadi periksa katalog model Foundry Local untuk alias saat ini dan varian yang tersedia.

Panduan Cepat Python

Foundry Local juga mendukung Python, JavaScript (Node.js), dan Rust. Berikut adalah contoh Python minimal untuk mengonfirmasi pola berfungsi - panduan lengkap untuk keempat bahasa tersebut ada dalam dokumentasi Microsoft Foundry.

Instal salah satu hal berikut — jangan instal keduanya, karena keduanya memiliki dependensi yang bertentangan 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

Paket foundry-local pada PyPI (tanpa -sdk) adalah paket pihak ketiga yang tidak terkait. Instal foundry-local-sdk atau foundry-local-sdk-winml untuk mendapatkan Microsoft Foundry Local SDK.

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

Jalankan:

python app.py

Untuk panduan memulai cepat Python yang lengkap — termasuk penyiapan penyedia eksekusi, penanganan kesalahan, dan daftar model — lihat Mulai menggunakan Foundry Local di dokumentasi Microsoft Foundry.

Gunakan dari aplikasi WinUI 3 atau WPF

Inisialisasi sekali dalam App.xaml.cs atau App.cs:

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

Kemudian selesaikan FoundryLocalManager.Instance di mana saja di aplikasi. Panggil Dispose() di handler keluar aplikasi.

Untuk panduan aplikasi lengkap, lanjutkan ke tutorial WinUI. Ini mencakup persetujuan eksplisit untuk mengunduh model, progres, pembatalan, aksesibilitas, dan peninjauan output.

Menambahkan AI lokal ke aplikasi WinUI

Fallback ke cloud

Gabungkan Foundry Local dengan API AI Windows dan Azure OpenAI untuk pola multi-tingkat yang tangguh. Lihat Memilih solusi AI Windows Anda untuk contoh lengkap yang dapat dikompilasi.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Peringatan ini muncul setelah program ditutup dan tidak berbahaya. Mereka berasal dari pelacakan sumber daya asli pustaka ONNX Runtime GenAI (OGA) yang mendasarinya. Output Anda benar; peringatan tidak menunjukkan masalah dengan kode Anda.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Peringatan dari ONNX Runtime ini berarti pustaka tidak mengenali ARM SoC Anda untuk deteksi fitur CPU. Ini kembali ke default yang aman dan inferensi berjalan secara normal. Tidak ada tindakan yang diperlukan.

Model '...' not found in catalog
SDK mengambil katalog model dari internet. Periksa koneksi jaringan Anda. Jika alias model tertentu tidak ditemukan, jalankan foundry model list untuk melihat alias yang tersedia, atau telusuri katalog lengkap di foundrylocal.ai/models.

Model mengembalikan konten kosong
Coba permintaan lagi dan konfirmasikan bahwa model yang dipilih memiliki varian yang kompatibel untuk perangkat Anda. Jika masalah berlanjut, pilih model yang lebih kecil atau varian CPU dan periksa apakah perangkat memiliki cukup memori yang tersedia.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Konflik dependensi pip ini berarti baik foundry-local-sdk-winml maupun foundry-local-sdk telah diinstal — keduanya menyematkan versi yang berbeda dari onnxruntime-core dan tidak dapat hidup berdampingan. Hapus instalan satu:

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

Kemudian instal ulang yang Anda inginkan. Menggunakan lingkungan virtual menghindari masalah ini sepenuhnya.

  • Last updated on