Compartir vía

Referencia del SDK local de Foundry

El SDK local de Foundry le permite enviar características de inteligencia artificial en las aplicaciones que son capaces de usar 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#, 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

Si está desarrollando o distribuyendo en Windows, seleccione la pestaña Windows. El paquete de Windows se integra con el entorno de ejecución Windows ML y ofrece la misma superficie de API con una gama más amplia de aceleración de hardware.

dotnet add package Microsoft.AI.Foundry.Local.WinML
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.26100</TargetFramework>
    <WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
    <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>

  <!-- Windows: WinML for hardware acceleration -->
  <ItemGroup Condition="$([MSBuild]::IsOSPlatform('Windows'))">
    <PackageReference Include="Microsoft.AI.Foundry.Local.WinML" />
  </ItemGroup>

  <!-- Non-Windows: standard SDK -->
  <ItemGroup Condition="!$([MSBuild]::IsOSPlatform('Windows'))">
    <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 En Windows, apunta a net9.0-windows10.0.26100 para la aceleración por hardware de WinML. En otras plataformas, apunta a net9.0.
WindowsAppSDKSelfContained Establezca en false para utilizar el SDK de aplicaciones de Windows instalado en el sistema en lugar de empaquetarlo.
WindowsPackageType Establezca en None para compilar como una aplicación de escritorio sin empaquetar (sin empaquetado MSIX).
EnableCoreMrtTooling Establézcalo en false para deshabilitar las herramientas de recursos de MRT Core, que no son necesarias para las aplicaciones de consola.
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.WinML Paquete exclusivo para Windows que utiliza WinML para la aceleración de hardware y la gestión automática de proveedores de ejecución.
Microsoft.AI.Foundry.Local Paquete multiplataforma para macOS, Linux y Windows sin WinML.
Microsoft.ML.OnnxRuntime.Gpu / OnnxRuntimeGenAI.Cuda Paquetes de compatibilidad con GPU de Linux para hardware compatible con CUDA.

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

Si está desarrollando o distribuyendo en Windows, seleccione la pestaña Windows. El paquete de Windows se integra con el entorno de ejecución Windows ML y ofrece la misma superficie de API con una gama más amplia de aceleración de hardware.

npm install foundry-local-sdk-winml 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

Si está desarrollando o distribuyendo en Windows, seleccione la pestaña Windows. El paquete de Windows se integra con el entorno de ejecución Windows ML y ofrece la misma superficie de API con una gama más amplia de aceleración de hardware.

pip install foundry-local-sdk-winml 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

Si está desarrollando o distribuyendo en Windows, seleccione la pestaña Windows. El paquete de Windows se integra con el entorno de ejecución Windows ML y ofrece la misma superficie de API con una gama más amplia de aceleración de hardware.

cargo add foundry-local-sdk --features winml
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:

  • Last updated on