Referencia del SDK local de Foundry

El SDK de Foundry local le permite incorporar funciones de IA en las aplicaciones que usan modelos de IA locales a través de una API sencilla e intuitiva. El SDK abstrae las complejidades de la administración de modelos de inteligencia artificial y proporciona una experiencia perfecta para integrar las funcionalidades de inteligencia artificial local en las aplicaciones. Esta referencia documenta implementaciones del SDK para C#, C++, JavaScript, Python y Rust.

El SDK no requiere que la CLI local de Foundry esté instalada en el equipo de usuarios finales, lo que le permite enviar las aplicaciones sin pasos de configuración adicionales para los usuarios: las aplicaciones son independientes. Entre las ventajas adicionales del SDK local de Foundry se incluyen:

  • Detección y optimización de hardware: evaluación automática de la funcionalidad para GPU, NPU y CPU.
  • Administración del proveedor de Windows (Windows): descarga automática y registro de los proveedores de ejecución de ONNX adecuados (CUDA, Vitis, QNN, OpenVINO, TensorRT) en función de las funcionalidades del dispositivo.
  • Compatibilidad con Metal a través de WebGpu (macOS): compatibilidad nativa para ejecutar modelos en Apple Silicon con un rendimiento optimizado.
  • Adquisición de modelos: descarga sin problemas del catálogo de modelos de Foundry con control de versiones, actualizaciones y selección automática de modelos optimizados para hardware y soporte de respaldo.
  • Tiempo de ejecución eficaz: agrega aproximadamente 20 MB al tamaño de la aplicación, se ejecuta en dispositivos desde teléfonos móviles a escritorios.
  • Compatibilidad con la API de OpenAI: integración sencilla con modelos y herramientas de OpenAI.
  • Servidor REST opcional: ejecute Foundry Local como un servicio local accesible por otras aplicaciones.

Referencia del SDK de C#

Instalación de paquetes

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

Los ejemplos de C# del repositorio de GitHub son proyectos preconfigurados. Si va a compilar desde cero, debe leer la referencia del SDK local de Foundry para obtener más detalles sobre cómo configurar el proyecto de C# con Foundry Local.

Configuración de Project

Los repositorios de ejemplo incluyen un .csproj archivo que controla la detección de plataforma automáticamente. Si va a compilar un proyecto desde cero, use esta configuración como referencia:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <!-- Windows: target Windows SDK for WinML hardware acceleration -->
  <PropertyGroup Condition="$([MSBuild]::IsOSPlatform('Windows'))">
    <TargetFramework>net9.0-windows10.0.19041.0</TargetFramework>
    <Platforms>ARM64;x64</Platforms>
    <WindowsPackageType>None</WindowsPackageType>
    <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
  </PropertyGroup>

  <!-- Non-Windows: standard .NET -->
  <PropertyGroup Condition="!$([MSBuild]::IsOSPlatform('Windows'))">
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(RuntimeIdentifier)'==''">
    <RuntimeIdentifier>$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AI.Foundry.Local" />
  </ItemGroup>

  <!-- Linux GPU support -->
  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <PackageReference Include="Microsoft.ML.OnnxRuntime.Gpu" />
    <PackageReference Include="Microsoft.ML.OnnxRuntimeGenAI.Cuda" />
  </ItemGroup>

  <!-- Shared utilities -->
  <ItemGroup>
    <Compile Include="../Shared/*.cs" />
  </ItemGroup>

</Project>

En la tabla siguiente se explica la configuración clave del proyecto:

Configuración Descripción
TargetFramework Tiene como destino la versión de .NET requerida por el ejemplo.
RuntimeIdentifier El valor predeterminado es el identificador de tiempo de ejecución del SDK actual, lo que garantiza que se seleccionen los binarios de plataforma correctos.
Microsoft.AI.Foundry.Local El paquete del SDK local de Foundry para Windows, macOS y Linux.

Inicio rápido

Use este fragmento de código para comprobar que el SDK puede inicializar y acceder al catálogo de modelos local.

using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging;
using System.Linq;

var config = new Configuration
{
  AppName = "app-name",
  LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information,
};

using var loggerFactory = LoggerFactory.Create(builder =>
{
  builder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Information);
});
var logger = loggerFactory.CreateLogger<Program>();

await FoundryLocalManager.CreateAsync(config, logger);
var manager = FoundryLocalManager.Instance;

var catalog = await manager.GetCatalogAsync();
var models = await catalog.ListModelsAsync();

Console.WriteLine($"Models available: {models.Count()}");

En este ejemplo se imprime el número de modelos disponibles para tu hardware.

Muestras

Referencia de las API

API de transcripción de audio nativa

El SDK de C# incluye un cliente de audio nativo para transcribir archivos de audio en el dispositivo mediante modelos de Whisper. Esto ejecuta la inferencia en proceso sin necesidad del servidor web REST.

Obtención de un cliente de audio

Después de cargar un modelo de Whisper, obtenga un cliente de audio:

var audioClient = await model.GetAudioClientAsync();

Métodos de transcripción de audio

Método Signature Descripción
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> Transmite los resultados de la transcripción en trozos. Cada fragmento tiene una Text propiedad .

Configuración de AudioClient

Propiedad Tipo Descripción
Language string Código de idioma ISO 639-1 (por ejemplo, "en"). Mejora la precisión.
Temperature float Temperatura de muestreo (0,0–1,0). Los valores inferiores son más deterministas.

Ejemplo

var audioClient = await model.GetAudioClientAsync();
audioClient.Settings.Language = "en";
audioClient.Settings.Temperature = 0.0f;

await foreach (var chunk in audioClient.TranscribeAudioStreamingAsync(
    "recording.mp3", CancellationToken.None))
{
    Console.Write(chunk.Text);
}

Referencias:

Referencia del SDK de JavaScript

Instalación de paquetes

npm install foundry-local-sdk openai

Inicio rápido

Use este fragmento de código para comprobar que el SDK puede inicializar y acceder al catálogo de modelos local.

import { FoundryLocalManager } from 'foundry-local-sdk';

console.log('Initializing Foundry Local SDK...');

const manager = FoundryLocalManager.create({
    appName: 'foundry_local_samples',
    logLevel: 'info'
});
console.log('✓ SDK initialized successfully');

// Explore available models
console.log('\nFetching available models...');
const catalog = manager.catalog;
const models = await catalog.getModels();

console.log(`Found ${models.length} models:`);
for (const model of models) {
    console.log(`  - ${model.alias}`);
}

En este ejemplo se genera la lista de modelos disponibles para el hardware.

Muestras

Referencia de las API

References

Referencia del SDK de Python

Instalación de paquetes

pip install foundry-local-sdk openai

Inicio rápido

Use este fragmento de código para comprobar que el SDK puede inicializar y acceder al catálogo de modelos local.

import asyncio
from foundry_local_sdk import Configuration, FoundryLocalManager


async def main():
    config = Configuration(app_name="app-name")
    FoundryLocalManager.initialize(config)
    manager = FoundryLocalManager.instance

    models = manager.catalog.list_models()
    print(f"Models available: {len(models)}")


if __name__ == "__main__":
    asyncio.run(main())

En este ejemplo se imprime el número de modelos disponibles para tu hardware.

Muestras

Configuración

La Configuration clase permite personalizar el comportamiento del SDK:

from foundry_local_sdk import Configuration

config = Configuration(
    app_name="app-name",
    log_level="info",
    model_cache_dir="./foundry_local_data/model_cache",
    web={"urls": "http://127.0.0.1:55588"},
)
Parámetro Tipo Descripción
app_name str Nombre de la aplicación.
log_level str Nivel de registro (por ejemplo, "info", "debug").
model_cache_dir str Directorio para los modelos almacenados en caché.
web dict Configuración del servicio web con urls clave.

API principal

Método Descripción
FoundryLocalManager.initialize(config) Inicialice el administrador singleton con Configuration.
FoundryLocalManager.instance Acceda a la instancia del administrador inicializada.
manager.catalog.list_models() Enumere todos los modelos disponibles en el catálogo.
manager.catalog.get_model(alias) Obtiene un modelo por alias.
manager.catalog.get_cached_models() Enumerar modelos en la memoria caché local.
manager.catalog.get_loaded_models() Enumerar los modelos cargados actualmente.
model.download(progress_callback) Descargue el modelo (omite si se almacena en caché).
model.load() Cargue el modelo para la inferencia.
model.unload() Libere el modelo.
model.is_cached Compruebe si el modelo se almacena en caché localmente.
model.is_loaded Compruebe si el modelo está cargado.

API nativa de autocompletado de chat

Después de cargar un modelo, obtenga un cliente de chat:

client = model.get_chat_client()
Método Descripción
client.complete_chat(messages) Genere una respuesta de chat completa.
client.complete_streaming_chat(messages) Transmitir fragmentos de respuesta de chat.

API de transcripción de audio nativa

Después de cargar un modelo de Whisper, obtenga un cliente de audio:

audio_client = model.get_audio_client()
Método Descripción
audio_client.transcribe(file_path) Transcriba un archivo de audio. Devuelve un objeto con una text propiedad .

Referencias:

Referencia del SDK de Rust

Instalación de paquetes

cargo add foundry-local-sdk
cargo add tokio --features full
cargo add tokio-stream anyhow

Inicio rápido

Use este fragmento de código para comprobar que el SDK puede inicializar y acceder al catálogo de modelos local.

use foundry_local_sdk::{FoundryLocalConfig, FoundryLocalManager};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let manager = FoundryLocalManager::create(FoundryLocalConfig::new("app-name"))?;

    let models = manager.catalog().get_models().await?;
    println!("Models available: {}", models.len());

    Ok(())
}

En este ejemplo se imprime el número de modelos disponibles para tu hardware.

Muestras

Configuración

La FoundryLocalConfig estructura permite personalizar el comportamiento del SDK:

use foundry_local_sdk::FoundryLocalConfig;

let config = FoundryLocalConfig::new("app-name")
    .with_log_level("info")
    .with_model_cache_dir("./foundry_local_data/model_cache")
    .with_web_urls("http://127.0.0.1:55588");

API principal

Método Descripción
FoundryLocalManager::create(config) Cree un nuevo administrador con un FoundryLocalConfig.
manager.catalog().get_models().await Enumera todos los modelos disponibles.
manager.catalog().get_model(alias).await Obtiene un modelo por alias.
manager.catalog().get_cached_models().await Enumerar modelos en la memoria caché local.
manager.catalog().get_loaded_models().await Enumerar los modelos cargados actualmente.
model.download(callback).await Descargue el modelo (omite si se almacena en caché).
model.load().await Cargue el modelo para la inferencia.
model.unload().await Libere el modelo.

API nativa de autocompletado de chat

Después de cargar un modelo, cree un cliente de chat con la configuración opcional:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
Método Descripción
client.complete_chat(&messages, tools).await Genere una respuesta de chat completa.
client.complete_streaming_chat(&messages, tools).await Transmitir fragmentos de respuesta de chat.

Tipos de mensaje: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage, ChatCompletionRequestMessage.

API de transcripción de audio nativa

Después de cargar un modelo Whisper, cree un cliente de audio.

let audio_client = model.create_audio_client();
Método Descripción
audio_client.transcribe(file_path).await Transcriba un archivo de audio. Devuelve un objeto con un text campo.

Referencias:

Referencia del SDK de C++

Prerequisites

El SDK de C++ proporciona un contenedor de solo encabezado sobre el tiempo de ejecución nativo de Foundry local. La aplicación implementada no requiere la CLI local de Foundry ni un entorno de ejecución de .NET.

Clona el ejemplo de chat nativo para empezar con un proyecto de CMake configurado:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/cpp/foundry-local/native-chat-completions

Los ejemplos de C++ requieren:

Configure y cree el ejemplo:

cmake -S . -B build
cmake --build build --config Release

Durante la configuración, el ejemplo restaura la versión 2.2.1 del Microsoft.AI.Foundry.Local.Runtime paquete NuGet en build/_packages. El paquete contiene los encabezados de C++ y las bibliotecas nativas para Windows, Linux y macOS. No necesita un paquete WinML independiente.

La configuración de CMake selecciona los recursos en tiempo de ejecución del sistema operativo y la arquitectura y copia las bibliotecas nativas necesarias junto al ejecutable. En macOS y Linux, ejecute el ejecutable desde build. En Windows, ejecute el archivo .exe desde build.

Seleccione recursos nativos que coincidan con el sistema operativo y la arquitectura de la aplicación:

Sistema operativo Architecture Identificador de tiempo de ejecución (RID)
Windows x64 o ARM64 win-x64 o win-arm64
Linux x64 o ARM64 linux-x64 o linux-arm64
macOS Silicio de Apple (ARM64) osx-arm64

Agregue Agregue build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include a la ruta de inclusión del compilador. Vincule la biblioteca nativa desde el paquete build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native directorio:

  • foundry_local.libEn Windows.
  • libfoundry_local.so en Linux.
  • libfoundry_local.dylib en macOS.

Coloque las bibliotecas de dependencias y el entorno de ejecución nativo coincidente junto al archivo ejecutable o en la ruta de búsqueda de la biblioteca de la plataforma. Mantenga juntas las versiones del paquete restauradas. No mezcle encabezados ni bibliotecas nativas de distintas versiones.

Inicio rápido

Reemplace el main.cpp del ejemplo por el código siguiente para inicializar el SDK y contar los modelos en el catálogo:

#include <foundry_local/foundry_local_cpp.h>

#include <iostream>

using namespace foundry_local;

int main() {
    try {
        Manager manager{Configuration("app-name")};
        auto models = manager.GetCatalog().GetModels();
        std::cout << "Models available: " << models.size() << "\n";
    } catch (const Error& error) {
        std::cerr << "Foundry Local error [" << error.Code()
                  << "]: " << error.what() << "\n";
        return 1;
    }
    return 0;
}

En el ejemplo se imprime Models available: seguido del recuento de modelos del catálogo. No descarga ni carga un modelo. Mantenga activo el administrador mientras usa objetos de catálogo, modelo o metadatos obtenidos de él.

Referencia: declaraciones de envoltorio de C++ para Configuration, Manager y Catalog.

API principal

El envoltorio usa resource acquisition is initialization (RAII) para liberar identificadores nativos cuando los objetos salen del ámbito.

API Descripción
Manager{Configuration("app-name")} Inicialice un gestor con un nombre de aplicación.
manager.GetCatalog() Obtenga el catálogo de modelo.
catalog.GetModels() Enumere los modelos del catálogo.
catalog.GetModel(alias) Busque un modelo por alias. Compruebe el puntero devuelto antes de usarlo.
model->Download() Descargue un modelo a la caché local.
model->Load() Cargue un modelo para la inferencia.
model->Unload() Liberar un modelo de la memoria.
ChatSession::ProcessRequest(request) Ejecute una solicitud de chat y devuelva una respuesta.

Referencia de API y ejemplos

Utilice el encabezado público y los ejemplos mantenidos para los flujos de trabajo completos de la API y la inferencia:

  • Se actualizó por última vez el