Condividi tramite

Informazioni di riferimento su Foundry Local SDK

Importante

  • Foundry Local è disponibile in anteprima. Le versioni di anteprima pubblica forniscono access iniziali alle funzionalità in fase di distribuzione attiva.
  • Funzionalità, approcci e processi possono subire variazioni o avere funzionalità limitate, prima della disponibilità generale (GA).

Foundry Local SDK consente di distribuire funzionalità di intelligenza artificiale nelle applicazioni in grado di sfruttare i modelli di intelligenza artificiale locale tramite un'API semplice e intuitiva. L'SDK astrae le complessità della gestione dei modelli di intelligenza artificiale e offre un'esperienza semplice per l'integrazione delle funzionalità di intelligenza artificiale locali nelle applicazioni. Questo riferimento documenta le implementazioni dell'SDK per JavaScript e C#. Altre lingue verranno aggiunte in futuro.

L'SDK non richiede l'installazione dell'interfaccia della riga di comando locale di Foundry nel computer degli utenti finali, consentendo di spedire le applicazioni senza passaggi di configurazione aggiuntivi per gli utenti. Le applicazioni sono autonome. I vantaggi aggiuntivi di Foundry Local SDK includono:

  • Rilevamento e ottimizzazione dell'hardware: valutazione automatica delle funzionalità per GPU, NPU e CPU.
  • Gestione del provider di esecuzione (Windows): download e registrazione automatici dei provider di esecuzione di RUNTIME ONNX appropriati (CUDA, Vitis, QNN, OpenVINO, TensorRT) in base alle funzionalità del dispositivo.
  • Supporto Metal tramite WebGpu (macOS): supporto nativo per l'esecuzione di modelli su Apple Silicon con prestazioni ottimizzate.
  • Acquisizione del modello: download facile da Foundry Model Catalog con controllo delle versioni, aggiornamenti e selezione automatica dei modelli ottimizzati per l'hardware con supporto di fallback.
  • Runtime efficiente: aggiunge <20 MB alle dimensioni dell'applicazione, funziona su dispositivi da telefoni cellulari a desktop.
  • Compatibilità dell'API OpenAI: facile integrazione con i modelli e gli strumenti OpenAI.
  • Server REST facoltativo: eseguire Foundry Local come servizio locale accessibile da altre applicazioni.

Informazioni di riferimento su JavaScript SDK

Configurazione del progetto

L'architettura generale di Foundry Local SDK è la seguente:

Diagramma della nuova architettura per Foundry Local.

Lo SDK è un wrapper leggero per un'API C Core Locale di Foundry (.dll/.so/.dylib) che fornisce un'interfaccia più user-friendly per gli sviluppatori JavaScript. L'SDK gestisce il caricamento della libreria nativa, la gestione della memoria e la conversione dei tipi di dati tra JavaScript e C. L'API C Foundry Local Core ha due versioni, ma la stessa superficie dell'API:

  • WindowsML (WinML): specifico di Windows che utilizza WindowsML per acquisire i driver appropriati e i provider di esecuzione per l'hardware disponibile. Questa è l'opzione consigliata per gli utenti di Windows perché offre prestazioni e compatibilità migliori con un'ampia gamma di hardware.
  • Multipiattaforma : può essere usata in Windows, macOS e Linux. Si noti che nei dispositivi macOS con Apple Silicon l'SDK multipiattaforma userà il framework Metal di Apple per l'accelerazione hardware tramite il provider di esecuzione WebGPU di runtime ONNX.

Quando si installa il pacchetto Foundry Local SDK nel progetto, è possibile scegliere di installare la versione WinML o multipiattaforma.

Usare Foundry Local nel progetto JavaScript seguendo queste istruzioni specifiche di Windows o multipiattaforma (macOS/Linux/Windows):

  1. Creare un nuovo progetto JavaScript: 
    mkdir app-name
cd app-name
npm init -y
npm pkg set type=module
  2. Installare il pacchetto Foundry Local SDK: 
    npm install --winml foundry-local-sdk
npm install openai

Avvio rapido

Usare questo frammento di codice per verificare che l'SDK possa inizializzare e accedere al catalogo del modello locale.

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

In questo esempio viene restituito l'elenco dei modelli disponibili per l'hardware.

Esempi

Informazioni di riferimento sulle API

References

Informazioni di riferimento su C# SDK

Guida alla configurazione del progetto

Sono disponibili due pacchetti NuGet per Foundry Local SDK, ovvero WinML e un pacchetto multipiattaforma, che hanno la stessa superficie API, ma sono ottimizzati per piattaforme diverse:

  • Windows: usa il pacchetto Microsoft.AI.Foundry.Local.WinML specifico per le applicazioni Windows, che usa il framework Windows Machine Learning (WinML).
  • Multipiattaforma: usa il Microsoft.AI.Foundry.Local pacchetto che può essere usato per applicazioni multipiattaforma (Windows, Linux, macOS).

A seconda della piattaforma di destinazione, seguire queste istruzioni per creare una nuova applicazione C# e aggiungere le dipendenze necessarie:

Usare Foundry Local nel progetto C# seguendo queste istruzioni specifiche di Windows o multipiattaforma (macOS/Linux/Windows):

  1. Creare un nuovo progetto C# e accederne: 
    dotnet new console -n app-name
cd app-name
  2. Aprire e modificare il app-name.csproj file in: 
    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0-windows10.0.26100</TargetFramework>
    <RootNamespace>app-name</RootNamespace>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
    <WindowsPackageType>None</WindowsPackageType>
    <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
  </PropertyGroup>

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

  <ItemGroup>
    <PackageReference Include="Microsoft.AI.Foundry.Local.WinML" Version="0.9.*" />
    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.10" />
    <PackageReference Include="OpenAI" Version="2.5.0" />
  </ItemGroup>

</Project>
  3. Creare un nuget.config file nella radice del progetto con il contenuto seguente in modo che i pacchetti vengano ripristinati correttamente: 
    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="ORT" value="https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="ORT">
      <package pattern="*Foundry*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Annotazioni

Il pacchetto NuGet Microsoft.AI.Foundry.Local è destinato a net8.0. La compatibilità verso il futuro di .NET funziona perfettamente nei progetti destinati a .NET 9, .NET 10 e versioni future, senza alcuna configurazione aggiuntiva. L'SDK usa solo le API .NET 8 e non contiene percorsi di codice specifici del framework, quindi il comportamento è identico indipendentemente dal runtime di destinazione dell'app. Puntiamo su .NET 8 in quanto è la versione LTS corrente con la base di installazione più ampia.

Avvio rapido

Usare questo frammento di codice per verificare che l'SDK possa inizializzare e accedere al catalogo del modello locale.

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

In questo esempio viene stampato il numero di modelli disponibili per l'hardware.

Esempi

Informazioni di riferimento sulle API

  • Last updated on