Condividi tramite

Guida alla migrazione di Foundry Local SDK

Questa guida fornisce istruzioni per la migrazione del codice dalla versione legacy di Foundry Local SDK alla versione corrente. Il nuovo SDK rimuove la dipendenza dall'interfaccia della riga di comando locale di Foundry e pertanto consente di spedire le applicazioni senza richiedere agli utenti di installare l'interfaccia della riga di comando o configurare un ambiente Foundry locale. Il nuovo SDK include anche miglioramenti all'API per migliorare l'usabilità e le prestazioni.

Guida alla migrazione di C# SDK

Per migliorare la possibilità di distribuire applicazioni usando l'intelligenza artificiale su dispositivo, sono state apportate modifiche sostanziali all'architettura di C# SDK nella versione 0.8.0 e versioni successive. In questa sezione vengono illustrate le modifiche chiave per facilitare la migrazione delle applicazioni alla versione più recente dell'SDK.

Annotazioni

Nella versione 0.8.0 dell'SDK e versioni successive sono state apportate modifiche di rilievo nell'API rispetto alle versioni precedenti (<=0.3.0).

Il diagramma seguente mostra come l'architettura precedente, per le versioni anteriori a 0.8.0, si basava fortemente sull'uso di un server REST per gestire modelli e attività di inferenza, come le completamenti delle chat.

Diagramma dell'architettura precedente per Foundry Local.

L'SDK usa una chiamata procedurale remota (RPC) per trovare l'eseguibile dell'interfaccia della riga di comando locale di Foundry nel computer, avviare il server Web e quindi comunicare con esso tramite HTTP. Questa architettura presentava diverse limitazioni, tra cui:

  • Complessità nella gestione del ciclo di vita del server Web.
  • Distribuzione impegnativa: gli utenti finali devono avere installato l'interfaccia della riga di comando Fonderia Locale sui loro computer e sulla loro applicazione.
  • La gestione delle versioni dell'interfaccia della riga di comando e dell'SDK potrebbe causare problemi di compatibilità.

Per risolvere questi problemi, l'architettura riprogettata in versione 0.8.0 e versioni successive usa un approccio più semplificato. La nuova architettura è la seguente:

Diagramma della nuova architettura per Foundry Local.

In questa nuova architettura:

  • L'applicazione è autonoma. Non richiede che l'interfaccia della riga di comando locale di Foundry venga installata separatamente nel computer dell'utente finale, semplificando la distribuzione delle applicazioni.
  • Il server Web REST è facoltativo. È comunque possibile usare il server Web se si vuole integrare con altri strumenti che comunicano tramite HTTP. Per informazioni dettagliate su come usare questa funzionalità, vedere Usare i completamenti della chat tramite il server REST con Foundry Local .
  • L'SDK offre il supporto nativo per i completamenti delle chat e le trascrizioni audio, consentendo di creare applicazioni di intelligenza artificiale conversazionale con un minor numero di dipendenze. Per informazioni dettagliate su come usare questa funzionalità, vedere Usare l'API di completamento della chat nativa di Foundry .
  • Nei dispositivi Windows è possibile usare una build Windows ML che gestisce l'accelerazione hardware per i modelli nel dispositivo eseguendo il pull del runtime e dei driver corretti.

Modifiche all'API

La versione 0.8.0 e versioni successive forniscono un'API più orientata agli oggetti e componibile. Il punto di ingresso principale continua a essere la FoundryLocalManager classe , ma invece di essere un set flat di metodi che operano tramite chiamate statiche a un'API HTTP senza stato, l'SDK ora espone metodi sull'istanza FoundryLocalManager che mantengono lo stato sul servizio e sui modelli.

Primitivo Versioni < 0.8.0 Versioni >= 0.8.0
Configuration N/A config = Configuration(...)
Recupera il manager mgr = FoundryLocalManager(); await FoundryLocalManager.CreateAsync(config, logger);
var mgr = FoundryLocalManager.Instance;
Ottenere il catalogo N/A catalog = await mgr.GetCatalogAsync();
Elenco Modelli mgr.ListCatalogModelsAsync(); catalog.ListModelsAsync();
Ottenere un modello mgr.GetModelInfoAsync("aliasOrModelId"); catalog.GetModelAsync(alias: "alias");
Get Variant N/A model.SelectedVariant;
Imposta variante N/A model.SelectVariant();
Scaricare un modello mgr.DownloadModelAsync("aliasOrModelId"); model.DownloadAsync()
Caricare un modello mgr.LoadModelAsync("aliasOrModelId"); model.LoadAsync()
Scaricare un modello mgr.UnloadModelAsync("aliasOrModelId"); model.UnloadAsync()
Elencare i modelli caricati mgr.ListLoadedModelsAsync(); catalog.GetLoadedModelsAsync();
Ottenere il percorso del modello N/A model.GetPathAsync()
Avviare il servizio mgr.StartServiceAsync(); mgr.StartWebServerAsync();
Arrestare il servizio mgr.StopServiceAsync(); mgr.StopWebServerAsync();
Percorso della cache mgr.GetCacheLocationAsync(); config.ModelCacheDir
Elencare i modelli memorizzati nella cache mgr.ListCachedModelsAsync(); catalog.GetCachedModelsAsync();

L'API consente a Foundry Local di essere più configurabile tramite il server Web, la registrazione, la posizione della cache e la selezione delle varianti del modello. Ad esempio, la Configuration classe consente di configurare il nome dell'applicazione, il livello di registrazione, gli URL del server Web e le directory per i dati dell'applicazione, la cache dei modelli e i log:

var config = new Configuration
{
    AppName = "app-name",
    LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information,
    Web = new Configuration.WebService
    {
        Urls = "http://127.0.0.1:55588"
    },
    AppDataDir = "./foundry_local_data",
    ModelCacheDir = "{AppDataDir}/model_cache",
    LogsDir = "{AppDataDir}/logs"
};

Informazioni di riferimento sulle API

Guida alla migrazione di JavaScript SDK

Per migliorare la possibilità di distribuire applicazioni usando l'intelligenza artificiale su dispositivo, esistono modifiche sostanziali all'architettura di JavaScript SDK. In questa sezione vengono illustrate le modifiche chiave per facilitare la migrazione delle applicazioni alla versione più recente dell'SDK.

Annotazioni

Nella versione 0.9.0 di JavaScript SDK e versioni successive sono state apportate modifiche di rilievo nell'API rispetto alle versioni precedenti (<=0.5.0).

Il diagramma seguente illustra come l'architettura precedente si basava molto sull'uso di un server Web REST per gestire modelli e inferenze come i completamenti della chat:

Diagramma dell'architettura precedente per Foundry Local.

L'SDK usa una chiamata procedurale remota (RPC) per trovare l'eseguibile dell'interfaccia della riga di comando locale di Foundry nel computer, avviare il server Web e quindi comunicare con esso tramite HTTP. Questa architettura presentava diverse limitazioni, tra cui:

  • Complessità nella gestione del ciclo di vita del server Web.
  • Distribuzione impegnativa: gli utenti finali devono avere installato l'interfaccia della riga di comando Fonderia Locale sui loro computer e sulla loro applicazione.
  • La gestione delle versioni dell'interfaccia della riga di comando e dell'SDK potrebbe causare problemi di compatibilità.

Per risolvere questi problemi, l'architettura riprogettata usa un approccio più semplificato. La nuova architettura è la seguente:

Diagramma della nuova architettura per Foundry Local.

In questa nuova architettura:

  • L'applicazione è autonoma. Non richiede che l'interfaccia della riga di comando locale di Foundry venga installata separatamente nel computer dell'utente finale, semplificando la distribuzione delle applicazioni.
  • Il server Web REST è facoltativo. È comunque possibile usare il server Web se si vuole integrare con altri strumenti che comunicano tramite HTTP.
  • L'SDK offre il supporto nativo per i completamenti delle chat e le trascrizioni audio, consentendo di creare applicazioni di intelligenza artificiale conversazionale con un minor numero di dipendenze.

Modifiche all'API

La versione più recente offre un'API più orientata agli oggetti e componibile. Il punto di ingresso principale continua a essere la FoundryLocalManager classe , ma invece di essere un set flat di metodi che operano tramite chiamate statiche a un'API HTTP senza stato, l'SDK ora espone metodi sull'istanza FoundryLocalManager che mantengono lo stato sul servizio e sui modelli.

Primitivo Versione precedente Versione corrente
Configuration N/A config = { appName: "app-name", ... }
Recupera il manager mgr = new FoundryLocalManager(); mgr = FoundryLocalManager.create(config);
Ottenere il catalogo N/A catalog = mgr.catalog;
Elenco Modelli mgr.listCatalogModels(); catalog.getModels();
Ottenere un modello mgr.getModelInfo("aliasOrModelId"); catalog.getModel(alias);
Get Variant N/A model.id;
Imposta variante N/A model.selectVariant(modelId);
Scaricare un modello mgr.downloadModel("aliasOrModelId"); model.download();
Caricare un modello mgr.loadModel("aliasOrModelId"); model.load();
Scaricare un modello mgr.unloadModel("aliasOrModelId"); model.unload();
Elencare i modelli caricati mgr.listLoadedModels(); catalog.getLoadedModels();
Ottenere il percorso del modello N/A model.path;
Avviare il servizio mgr.startService(); mgr.startWebService();
Arrestare il servizio N/A mgr.stopWebService();
Percorso della cache mgr.getCacheLocation(); config.modelCacheDir
Elencare i modelli memorizzati nella cache mgr.listCachedModels(); catalog.getCachedModels();

L'API consente a Foundry Local di essere più configurabile tramite il server Web, la registrazione, la posizione della cache e la selezione delle varianti del modello. Ad esempio, config consente di configurare il nome dell'applicazione, il livello di registrazione, gli URL del server Web e le directory per i dati dell'applicazione, la cache dei modelli e i log:

const config = {
  appName: "app-name",
  logLevel: "info",
  webServiceUrls: "http://127.0.0.1:55588",
  appDataDir: "./foundry_local_data",
  modelCacheDir: "{appDataDir}/model_cache",
  logsDir: "{appDataDir}/logs",
};

Nella versione precedente di Foundry Local JavaScript SDK non è stato possibile configurare queste impostazioni direttamente tramite l'SDK, che ha limitato la possibilità di personalizzare il comportamento del servizio.

References

Guida alla migrazione di Python SDK

Per migliorare la possibilità di spedire applicazioni usando l'intelligenza artificiale su dispositivo, esistono modifiche sostanziali all'architettura di Python SDK. In questa sezione vengono illustrate le modifiche chiave per facilitare la migrazione delle applicazioni alla versione più recente dell'SDK.

Annotazioni

Nella versione più recente Python SDK (1.0.0), nell'API sono state apportate modifiche di rilievo rispetto alle versioni precedenti (<=0.5.1).

Il diagramma seguente illustra come l'architettura precedente si basava molto sull'uso di un server Web REST per gestire modelli e inferenze come i completamenti della chat:

Diagramma dell'architettura precedente per Foundry Local.

L'SDK usa una chiamata procedurale remota (RPC) per trovare l'eseguibile dell'interfaccia della riga di comando locale di Foundry nel computer, avviare il server Web e quindi comunicare con esso tramite HTTP. Questa architettura presentava diverse limitazioni, tra cui:

  • Complessità nella gestione del ciclo di vita del server Web.
  • Distribuzione impegnativa: gli utenti finali devono avere installato l'interfaccia della riga di comando Fonderia Locale sui loro computer e sulla loro applicazione.
  • La gestione delle versioni dell'interfaccia della riga di comando e dell'SDK potrebbe causare problemi di compatibilità.

Per risolvere questi problemi, l'architettura riprogettata usa un approccio più semplificato. La nuova architettura è la seguente:

Diagramma della nuova architettura per Foundry Local.

In questa nuova architettura:

  • L'applicazione è autonoma. Non richiede che l'interfaccia della riga di comando locale di Foundry venga installata separatamente nel computer dell'utente finale, semplificando la distribuzione delle applicazioni.
  • Il server Web REST è facoltativo. È comunque possibile usare il server Web se si vuole integrare con altri strumenti che comunicano tramite HTTP.
  • L'SDK offre il supporto nativo per i completamenti delle chat e le trascrizioni audio, consentendo di creare applicazioni di intelligenza artificiale conversazionale con un minor numero di dipendenze.

Modifiche all'API

La versione più recente offre un'API più orientata agli oggetti e componibile. Il punto di ingresso principale continua a essere la FoundryLocalManager classe, ma il modello di inizializzazione, la gestione dei modelli e l'inferenza sono stati tutti modificati in modo significativo.

Primitivo Versione precedente (foundry-local) Versione corrente (foundry-local-sdk)
Pacco pip install foundry-local pip install foundry-local-sdk
Importa from foundry_local import FoundryLocalManager from foundry_local_sdk import Configuration, FoundryLocalManager
Configuration N/A config = Configuration(app_name="app-name")
Recupera il manager manager = FoundryLocalManager(alias) FoundryLocalManager.initialize(config)
manager = FoundryLocalManager.instance
Ottenere il catalogo N/A catalog = manager.catalog
Elenco Modelli manager.list_catalog_models() catalog.list_models()
Ottenere un modello manager.get_model_info(alias) catalog.get_model(alias)
Scaricare un modello manager.download_model(alias) model.download(progress_callback)
Caricare un modello manager.load_model(alias) model.load()
Scaricare un modello manager.unload_model(alias) model.unload()
Elencare i modelli caricati manager.list_loaded_models() catalog.get_loaded_models()
Elencare i modelli memorizzati nella cache manager.list_cached_models() catalog.get_cached_models()
Percorso della cache manager.get_cache_location() config.model_cache_dir
Avviare il servizio manager.start_service() manager.start_web_service()
Endpoint del servizio manager.endpoint manager.urls

L'API consente a Foundry Local di essere più configurabile tramite il server Web, la registrazione, la posizione della cache e la selezione delle varianti del modello. Ad esempio, la Configuration classe consente di configurare il nome dell'applicazione, il livello di registrazione, gli URL del server Web e le directory per i dati dell'applicazione, la cache dei modelli e i log:

from foundry_local_sdk import Configuration

config = Configuration(
    app_name="app-name",
    log_level="info",
    web={"urls": "http://127.0.0.1:55588"},
    model_cache_dir="./foundry_local_data/model_cache",
)

References

Guida alla migrazione di Rust SDK

Per migliorare la possibilità di distribuire applicazioni usando l'intelligenza artificiale su dispositivo, esistono modifiche sostanziali all'architettura di Rust SDK. In questa sezione vengono illustrate le modifiche chiave per facilitare la migrazione delle applicazioni alla versione più recente dell'SDK.

Annotazioni

Nella versione più recente di Rust SDK (1.0.0) sono state apportate modifiche di rilievo nell'API rispetto alla versione precedente. Il nome della cassa è passato da foundry-local a foundry-local-sdk.

Il diagramma seguente illustra come l'architettura precedente si basava molto sull'uso di un server Web REST per gestire modelli e inferenze come i completamenti della chat:

Diagramma dell'architettura precedente per Foundry Local.

L'SDK utilizzerebbe una chiamata procedurale remota (RPC) per trovare l'eseguibile della CLI locale di Foundry nel computer, avviare il web server e quindi comunicare con esso tramite HTTP. Questa architettura presentava diverse limitazioni, tra cui:

  • Complessità nella gestione del ciclo di vita del server Web.
  • Distribuzione impegnativa: gli utenti finali devono avere installato l'interfaccia della riga di comando Fonderia Locale sui loro computer e sulla loro applicazione.
  • La gestione delle versioni dell'interfaccia della riga di comando e dell'SDK potrebbe causare problemi di compatibilità.

Per risolvere questi problemi, l'architettura riprogettata usa un approccio più semplificato. La nuova architettura è la seguente:

Diagramma della nuova architettura per Foundry Local.

In questa nuova architettura:

  • L'applicazione è autonoma. Non richiede che l'interfaccia della riga di comando locale di Foundry venga installata separatamente nel computer dell'utente finale, semplificando la distribuzione delle applicazioni.
  • Il server Web REST è facoltativo. È comunque possibile usare il server Web se si vuole integrare con altri strumenti che comunicano tramite HTTP.
  • L'SDK offre il supporto nativo per i completamenti delle chat e le trascrizioni audio, consentendo di creare applicazioni di intelligenza artificiale conversazionale con un minor numero di dipendenze.

Modifiche all'API

La versione più recente offre un'API più orientata agli oggetti e componibile. Il modello di generatore è stato sostituito con un approccio basato sulla configurazione e la gestione dei modelli ora usa oggetti dedicati Model .

Primitivo Versione precedente (foundry-local) Versione corrente (foundry-local-sdk)
Crate foundry-local foundry-local-sdk
Configuration N/A FoundryLocalConfig::new("app-name")
Recupera il manager FoundryLocalManager::builder().build().await? FoundryLocalManager::create(config)?
Ottenere il catalogo N/A manager.catalog()
Elenco Modelli manager.list_catalog_models().await? manager.catalog().get_models().await?
Ottenere un modello manager.get_model_info(alias).await? manager.catalog().get_model(alias).await?
Scaricare un modello manager.download_model(alias).await? model.download(callback).await?
Caricare un modello manager.load_model(alias).await? model.load().await?
Scaricare un modello manager.unload_model(alias).await? model.unload().await?
Elencare i modelli caricati manager.list_loaded_models().await? manager.catalog().get_loaded_models().await?
Elencare i modelli memorizzati nella cache manager.list_cached_models().await? manager.catalog().get_cached_models().await?
Avviare il servizio manager.start_service()? manager.start_web_service().await?
Punto finale manager.endpoint()? manager.urls()
Chiamate HTTP reqwest::Client (REST manuale) Native SDK: model.create_chat_client()

Il nuovo SDK offre client audio e chat nativi, eliminando la necessità di richieste HTTP manuali nella maggior parte dei casi:

use foundry_local_sdk::{FoundryLocalConfig, FoundryLocalManager};

let config = FoundryLocalConfig::new("app-name");
let manager = FoundryLocalManager::create(config)?;

let model = manager.catalog().get_model("qwen2.5-0.5b").await?;
model.download(None).await?;
model.load().await?;

// Native chat client - no HTTP server needed
let client = model.create_chat_client().temperature(0.7).max_tokens(256);

References

  • Last updated on