Introducción a Foundry Local

Foundry Local habilita la ejecución local de modelos de lenguaje grande (LLM) directamente en el dispositivo Windows, como parte de Microsoft Foundry en Windows. Es una buena alternativa cuando necesita profundizar más que las API de inteligencia artificial de Windows o necesita admitir hardware que no sea un Copilot+ PC. No se requieren permisos especiales ni tokens de desbloqueo. El SDK nativo se ejecuta en el proceso de la aplicación y no requiere la CLI local de Foundry ni un servidor REST local independiente. El mismo patrón funciona en una aplicación de consola, una aplicación WinUI 3, una aplicación WPF o cualquier otro host de .NET.

Logotipos de tecnologías asociadas a Foundry Local

Note

La documentación completa de Foundry Local (incluida la CLI, la administración de modelos, el servidor REST opcional, Python SDK, etc.) se mantiene en la documentación de Microsoft Foundry. Los vínculos de esta página le llevan allí cuando sea necesario. Use el botón Atrás de tu navegador o la ruta de navegación ('breadcrumb') para volver a los documentos de inteligencia artificial de Windows en cualquier momento.

Si no está seguro de si Foundry Local es la opción adecuada para su escenario, consulte Choose la solución de inteligencia artificial de Windows antes de continuar.

Prerequisites

  • Windows 11, versión 24H2 (compilación 26100) o posterior
  • SDK de .NET 9.0 o posterior
  • Un dispositivo x64 o Arm64 con suficiente memoria y espacio en disco para el modelo seleccionado
  • Acceso a Internet para las descargas iniciales de paquetes, modelos y componentes en tiempo de ejecución

El SDK de Windows puede usar variantes de modelo de CPU, GPU y NPU compatibles. No se requiere una GPU dedicada, NPU o Copilot+ PC cuando el modelo seleccionado tiene una variante de CPU compatible. La aceleración y el rendimiento disponibles dependen del dispositivo, el modelo y el proveedor de ejecución.

Note

En este inicio rápido se usa Phi-4 Mini, actualmente el último modelo Microsoft Phi disponible a través del alias phi-4-minilocal de Foundry. Los alias de catálogo local de Foundry y los modelos recomendados pueden cambiar a medida que evoluciona el catálogo.

Phi-4 Mini es independiente de Phi Silica, el modelo de la API de IA de Windows que se incluye con Windows. PhiLice sigue siendo una característica de acceso limitado y requiere un token de desbloqueo. Está programado para reemplazarse por Aion Instruct, que no requerirá un token de característica de acceso limitado. Consulte Introducción a PhiLice para obtener detalles de acceso y la escala de tiempo de transición.

Opcional: Instalación de la CLI local de Foundry

El flujo de trabajo del SDK de esta guía de inicio rápido no requiere la CLI. Instálelo solo si también desea inspeccionar y administrar modelos desde un terminal:

winget install Microsoft.FoundryLocal

A continuación, cierre y vuelva a abrir el terminal para que el comando esté en la foundry ruta de acceso. Compruebe lo siguiente:

foundry --version

Creación de un proyecto

dotnet new console -n FoundryLocalDemo
cd FoundryLocalDemo

El paquete NuGet incluye archivos binarios nativos Windows, por lo que el proyecto necesita un marco de destino Windows e identificadores en tiempo de ejecución. Abra FoundryLocalDemo.csproj y reemplace el <PropertyGroup> bloque por:

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

A continuación, restaure para generar el archivo de recursos para el nuevo destino:

dotnet restore

Instalación del paquete NuGet.

Instale el paquete de Windows estable actual:

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

El paquete incluye el ChatMessage y los tipos relacionados que utiliza la API local de chat nativo de Foundry. Selecciona una variante de modelo compatible para el dispositivo actual y puede usar los proveedores de ejecución de Windows ML para la aceleración de hardware.

Note

Si necesita tener como destino plataformas que no son de Windows, use Microsoft.AI.Foundry.Local en su lugar. Proporciona la misma superficie de API local de Foundry sin la integración de ML de Windows.

El comando anterior instala el paquete estable actual. El tutorial de WinUI usa .NET 10 y fija las versiones de los paquetes para que puedas reproducir todo el recorrido.

Inicio rápido: ejecución de un modelo

Reemplace el contenido de Program.cs por lo siguiente y, a continuación, ejecute dotnet run. El programa inicializa Foundry Local, descarga el modelo si es necesario, ejecuta una finalización de chat y limpia.

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

Respuestas de transmisión

Para obtener una mejor experiencia de usuario en las aplicaciones de interfaz de usuario, transmita el token de respuesta uno por uno. Este fragmento de código continúa desde el inicio rápido anterior: chatClient procede del paso 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();

Ajuste de los parámetros de generación

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

Alias de modelo

Pase un alias de modelo (no un identificador de modelo completo) a GetModelAsync para que Foundry Local pueda seleccionar una variante de hardware compatible. Dependiendo del modelo y del dispositivo, puede tratarse de una variante de QNN para la NPU de Snapdragon, una variante CUDA en NVIDIA o una variante para CPU.

Si instaló la CLI opcional, ejecútelo para ver los alias disponibles:

foundry model list

Por ejemplo, use phi-4-mini para el modelo Microsoft Phi-4 Mini. El catálogo cambia con el tiempo, así que compruebe el catálogo de modelos local de Foundry para ver los alias actuales y las variantes disponibles.

inicio rápido de Python

Foundry Local también admite Python, JavaScript (Node.js) y Rust. Este es el ejemplo mínimo de Python para confirmar que el patrón funciona: el tutorial completo de los cuatro idiomas se encuentra en la documentación de Microsoft Foundry.

Instale una de las siguientes opciones: no instale ambas, ya que tienen dependencias en conflicto 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

Importante

El foundry-local paquete de PyPI (sin -sdk) es un paquete de terceros no relacionado. Instale foundry-local-sdk o foundry-local-sdk-winml para obtener el SDK local de Microsoft Foundry.

Creación de 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()

Ejecútelo:

python app.py

Para obtener el inicio rápido completo de Python, incluida la configuración del proveedor de ejecución, el control de errores y la lista de modelos, consulte Introducción a Foundry Local en la documentación de Microsoft Foundry.

Usar desde una aplicación WinUI 3 o WPF

Inicialice una vez en App.xaml.cs o App.cs:

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

A continuación, resuelva FoundryLocalManager.Instance cualquier lugar de la aplicación. Llame Dispose() al controlador de salida de la aplicación.

Para ver un tutorial completo de la aplicación, continúe con el tutorial de WinUI. Abarca el consentimiento explícito para descargar modelos, el progreso, la cancelación, la accesibilidad y la revisión del resultado.

Adición de inteligencia artificial local a una aplicación winUI

Recurso alternativo a la nube

Combine Foundry Local con Windows API de IA y Azure OpenAI para un patrón resistente de varios niveles. Consulte Choose la solución de inteligencia artificial de Windows para obtener un ejemplo compilable completo.

Troubleshooting

OGA Error: N instances of struct Generators::Model were leaked
Estas advertencias aparecen después de que el programa salga y son benignas. Proceden del monitoreo de recursos nativos de la biblioteca subyacente ONNX Runtime GenAI (OGA). La salida es correcta; las advertencias no indican un problema con el código.

Error in cpuinfo: Unknown chip model name 'Snapdragon...'
Esta advertencia de ONNX Runtime significa que la biblioteca no reconoce el SoC de ARM para la detección de características de CPU. Vuelve a valores predeterminados seguros y se ejecuta normalmente la inferencia. No es necesario realizar ninguna acción.

Model '...' not found in catalog
El SDK captura el catálogo de modelos de Internet. Compruebe la conexión de red. Si no se encuentra un alias de modelo específico, ejecute foundry model list para ver los alias disponibles o examine el catálogo completo en foundrylocal.ai/models.

El modelo devuelve contenido vacío
Vuelva a intentar la solicitud y confirme que el modelo seleccionado tiene una variante compatible para el dispositivo. Si el problema continúa, seleccione un modelo más pequeño o una variante de CPU y compruebe que el dispositivo tiene suficiente memoria disponible.

foundry-local-sdk-winml requires onnxruntime-core==X.Y.Z, but you have ... which is incompatible
Este conflicto de dependencias pip significa que foundry-local-sdk-winml y foundry-local-sdk están instalados, anclan versiones diferentes de onnxruntime-core y no pueden coexistir. Desinstale uno:

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

A continuación, vuelva a instalar la que quiera. El uso de un entorno virtual evita este problema por completo.

  • Last updated on