Wprowadzenie do lokalnego programu Foundry

Usługa Foundry Local umożliwia lokalne wykonywanie dużych modeli językowych (LLM) bezpośrednio na urządzeniu Windows w ramach Microsoft Foundry na Windows. Jest to dobra alternatywa, jeśli musisz zagłębić się bardziej niż w interfejsy API sztucznej inteligencji Windows lub obsługiwać sprzęt, który nie jest komputerem Copilot+. Nie są wymagane żadne specjalne uprawnienia ani tokeny odblokowywania. Natywny pakiet SDK działa w procesie Twojej aplikacji i nie wymaga Foundry Local CLI ani oddzielnego lokalnego serwera REST. Ten sam wzorzec działa w aplikacji konsolowej, aplikacji WinUI 3, aplikacji WPF lub innego hosta .NET.

Logo technologii skojarzonych z rozwiązaniem Foundry Local

Note

Pełna dokumentacja dotycząca lokalnego rozwiązania Foundry — w tym interfejsu wiersza polecenia, zarządzania modelami, opcjonalnego serwera REST, zestawu SDK Python itd. — jest przechowywana w dokumentacji Microsoft Foundry. Linki na tej stronie prowadzą do Ciebie w razie potrzeby. Użyj przycisku Wstecz przeglądarki lub nawigacji ścieżkowej, aby wrócić do dokumentacji Windows AI w dowolnym momencie.

Jeśli nie masz pewności, czy Foundry Local jest właściwym wyborem dla danego scenariusza, zobacz Choose your Windows AI solution przed kontynuowaniem.

Prerequisites

  • Windows 11, wersja 24H2 (kompilacja 26100) lub nowsza
  • zestaw SDK .NET 9.0 lub nowszy
  • Urządzenie x64 lub Arm64 z wystarczającą ilością pamięci i miejsca na dysku dla wybranego modelu
  • Dostęp do Internetu w celu pobrania początkowego pakietu, modelu i komponentów środowiska uruchomieniowego

Zestaw SDK Windows może używać zgodnych wariantów modelu procesora CPU, procesora GPU i procesora NPU. Dedykowany układ GPU lub NPU ani komputer Copilot+ PC nie są wymagane, jeśli wybrany model ma zgodny wariant dla CPU. Dostępne przyspieszenie i wydajność zależą od urządzenia, modelu i dostawcy wykonywania.

Note

W tym przewodniku Szybki start użyto modelu Phi-4 Mini, obecnie najnowszego modelu Microsoft Phi dostępnego za pośrednictwem aliasu phi-4-miniFoundry Local. Aliasy katalogu lokalnego i zalecane modele mogą ulec zmianie w miarę rozwoju katalogu.

Phi-4 Mini jest oddzielny od Phi Silica, modelu interfejsu API AI systemu Windows dostarczanego z systemem Windows. Silica Phi pozostaje funkcją ograniczonego dostępu i wymaga tokenu odblokowania. Ma zostać zastąpiony przez Aion Instruct, który nie będzie wymagać tokenu funkcji o ograniczonym dostępie. Aby uzyskać szczegóły dotyczące dostępu i harmonogram przejścia, zobacz Wprowadzenie do Phi Silica.

Opcjonalnie: zainstaluj lokalny interfejs wiersza polecenia Foundry Local

Przepływ pracy zestawu SDK w tym przewodniku Szybki start nie wymaga interfejsu wiersza polecenia. Zainstaluj go tylko wtedy, gdy chcesz również sprawdzać modele i zarządzać nimi z poziomu terminalu:

winget install Microsoft.FoundryLocal

Następnie zamknij i otwórz ponownie terminal, aby polecenie foundry było dostępne w zmiennej systemowej PATH. Sprawdź:

foundry --version

Utwórz projekt

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

Pakiet NuGet zawiera natywne pliki binarne Windows, więc projekt wymaga docelowej struktury Windows i identyfikatorów środowiska uruchomieniowego. Otwórz FoundryLocalDemo.csproj i zastąp blok <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>

Następnie przywróć, aby wygenerować plik zasobów dla nowego obiektu docelowego:

dotnet restore

Instalowanie pakietu NuGet

Zainstaluj bieżący stabilny pakiet Windows:

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

Pakiet zawiera element ChatMessage oraz powiązane typy używane przez natywny interfejs API lokalnego czatu Foundry. Wybiera zgodny wariant modelu dla aktualnego urządzenia i może używać dostawców wykonania Windows ML do akceleracji sprzętowej.

Note

Jeśli musisz użyć platform innych niż Windows, zamiast tego użyj Microsoft.AI.Foundry.Local. Zapewnia ten sam interfejs API rozwiązania Foundry Local, ale bez integracji z Windows ML.

Powyższe polecenie instaluje bieżący stabilny pakiet. Samouczek WinUI korzysta z platformy .NET 10 i przypina wersje pakietów, dzięki czemu można odtworzyć cały opisany w nim proces krok po kroku.

Szybki start: uruchamianie modelu

Zastąp zawartość Program.cs pliku następującym kodem, a następnie uruchom polecenie dotnet run. Inicjuje Foundry Local, pobiera model w razie potrzeby, wykonuje zadanie ukończenia czatu i dokonuje czyszczenia.

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

Odpowiedzi streamingowe

Aby uzyskać lepsze doświadczenie użytkownika w aplikacjach UI, należy przesyłać strumieniowo odpowiedź token po tokenie. Ten fragment kodu kontynuuje szybki start — chatClient pochodzi z kroku 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();

Dostrajanie parametrów generowania

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

Aliasy modelu

Przekaż alias modelu (nie pełny identyfikator modelu), aby GetModelAsync program Foundry Local mógł wybrać zgodny wariant sprzętu. W zależności od modelu i urządzenia może to być wariant QNN NPU na platformie Snapdragon, wariant CUDA firmy NVIDIA lub wariant CPU.

Jeśli zainstalowano opcjonalny interfejs wiersza polecenia, uruchom go, aby wyświetlić dostępne aliasy:

foundry model list

Na przykład użyj dla phi-4-mini modelu Microsoft Phi-4 Mini. Katalog zmienia się z czasem, dlatego sprawdź lokalny katalog modeli Foundry, aby sprawdzić aktualne aliasy i dostępne warianty.

Python Szybki start

Aplikacja Foundry Local obsługuje również Python, JavaScript (Node.js) i Rust. Oto minimalny przykład Python, aby potwierdzić, że wzorzec działa — pełny przewodnik dla wszystkich czterech języków znajduje się w dokumentacji Microsoft Foundry.

Zainstaluj jedną z następujących opcji — nie instaluj obu tych elementów, ponieważ mają one sprzeczne onnxruntime-core zależności:

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

Ważna

Pakiet foundry-local w PyPI (bez -sdk) jest pakietem zewnętrznym, niezwiązanym z tym. Zainstaluj foundry-local-sdk lub foundry-local-sdk-winml, aby pobrać lokalny zestaw SDK Microsoft Foundry.

Utwórz 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()

Uruchom go:

python app.py

Aby uzyskać kompletny przewodnik Szybki start dla języka Python — obejmujący konfigurację dostawcy wykonywania, obsługę błędów i listę modeli — zobacz Rozpocznij pracę z Foundry Local w dokumentacji Microsoft Foundry.

Używanie z aplikacji WinUI 3 lub WPF

Zainicjuj raz w elem App.xaml.cs lub App.cs:

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

Następnie zastosuj FoundryLocalManager.Instance w dowolnym miejscu w aplikacji. Wywołaj Dispose() w procedurze obsługi zakończenia aplikacji.

Aby zapoznać się z kompletnym przewodnikiem dotyczącym aplikacji, przejdź do samouczka WinUI. Obejmuje wyraźną zgodę na pobranie modelu, informacje o postępie, anulowanie, funkcje ułatwień dostępu i przegląd wyników.

Dodawanie lokalnej sztucznej inteligencji do aplikacji WinUI

Powrót do chmury

Połącz aplikację Foundry Local z interfejsami API sztucznej inteligencji Windows i Azure openAI w celu uzyskania odpornego wzorca wielowarstwowego. Aby uzyskać kompletny przykład kompilowalny, zobacz Choose your Windows AI solution (Wybierz swoje rozwiązanie Windows AI).

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Te ostrzeżenia pojawiają się po zakończeniu działania programu i są łagodne. Pochodzą one z natywnego śledzenia zasobów biblioteki ONNX Runtime GenAI (OGA). Dane wyjściowe są poprawne; ostrzeżenia nie wskazują problemu z kodem.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
To ostrzeżenie ze środowiska uruchomieniowego ONNX oznacza, że biblioteka nie rozpoznaje Twojego ARM SoC do wykrywania funkcji CPU. Wraca do bezpiecznych wartości domyślnych i wnioskowanie działa normalnie. Nie jest wymagana żadna akcja.

Model '...' not found in catalog
Zestaw SDK pobiera wykaz modeli z Internetu. Sprawdź połączenie sieciowe. Jeśli nie można odnaleźć określonego aliasu modelu, uruchom polecenie foundry model list , aby wyświetlić dostępne aliasy lub przejrzyj pełny wykaz pod adresem foundrylocal.ai/models.

Model zwraca pustą zawartość
Spróbuj ponownie wysłać żądanie i upewnij się, że wybrany model ma zgodny wariant dla urządzenia. Jeśli problem będzie nadal występować, wybierz mniejszy model lub wariant procesora CPU i sprawdź, czy urządzenie ma wystarczającą ilość dostępnej pamięci.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Ten konflikt zależności pip oznacza, że zarówno foundry-local-sdk-winml, jak i foundry-local-sdk są zainstalowane — ustalają różne wersje onnxruntime-core i nie mogą współistnieć. Odinstaluj jeden program:

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

Następnie zainstaluj ponownie odpowiedni element. Korzystanie ze środowiska wirtualnego pozwala całkowicie uniknąć tego problemu.

  • Last updated on