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 ada izin khusus atau token pembuka kunci yang diperlukan — ini berjalan sepenuhnya pada perangkat keras Anda sendiri. 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, REST API, Python SDK, dan banyak lagi — dipertahankan dalam dokumentasi Azure AI 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
  • GPU berkemampuan DirectX 12 (terintegrasi atau diskrit). Paket ini WinML menggunakan akselerasi perangkat keras dan memerlukan perangkat keras GPU nyata — mesin virtual tanpa passthrough GPU (penyaluran GPU langsung) tidak didukung.

Menginstal Foundry Local CLI

Instal CLI menggunakan winget:

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 WinML, yang secara otomatis menggunakan perangkat keras terbaik yang tersedia (Qualcomm NPU, GPU NVIDIA, atau CPU) melalui ONNX Runtime:

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 menyediakan ChatMessage dan jenis terkait yang digunakan oleh API obrolan Foundry Local.

Note

Jika Anda perlu menargetkan platform non-Windows, gunakan Microsoft.AI.Foundry.Local sebagai gantinya. API identik; paket tersebut menghilangkan akselerasi perangkat keras khusus Windows.

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

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

Teruskan alias model (bukan ID model lengkap) ke GetModelAsync agar Foundry Local secara otomatis memilih varian perangkat keras terbaik — misalnya, varian NPU QNN di Snapdragon, varian CUDA di NVIDIA, atau penggantian CPU di lokasi lainnya.

Jalankan CLI untuk melihat alias yang tersedia:

foundry model list

Alias umum: phi-3.5-mini, , phi-4qwen2.5-0.5b (terkecil - baik untuk pengujian cepat), qwen2.5-7b, deepseek-r1-7b. Katalog lengkap berada di foundrylocal.ai/models.

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 di dokumen Azure AI 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("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()

Jalankan:

python app.py

Untuk panduan memulai cepat Python lengkap — termasuk konfigurasi penyedia eksekusi, penanganan kesalahan, dan daftar model — lihat bagian Mulai dengan Foundry Local di dokumen Azure AI 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.

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
Backend WinML memerlukan GPU berkemampuan DirectX 12. Mesin virtual tanpa passthrough GPU mengembalikan respons yang berhasil dengan konten kosong. Jalankan pada perangkat keras fisik dengan GPU diskrit atau terintegrasi.

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