Guide de migration du Kit de développement logiciel (SDK) local Foundry

Ce guide fournit des instructions pour migrer votre code de la version héritée du SDK Local Foundry vers la version actuelle. Le nouveau SDK supprime la dépendance vis-à-vis de l’interface CLI locale Foundry et vous permet donc d’expédier vos applications sans exiger que vos utilisateurs installent l’interface CLI ou configurent un environnement Foundry local. Le nouveau SDK inclut également des améliorations apportées à l’API pour améliorer la facilité d’utilisation et les performances.

Guide de migration du Kit de développement logiciel (SDK) C#

Pour améliorer votre capacité à expédier des applications à l’aide de l’IA sur appareil, il existe des modifications substantielles apportées à l’architecture du SDK C# dans la version 0.8.0 et les versions ultérieures. Dans cette section, nous décrivons les principales modifications pour vous aider à migrer vos applications vers la dernière version du SDK.

Note

Dans la version 0.8.0 du Kit de développement logiciel (SDK) et les versions ultérieures, il y a des ruptures dans l’API par rapport aux versions précédentes (<=0.3.0).

Le diagramme suivant montre comment l’architecture précédente - pour les versions antérieures à - 0.8.0 s’appuyait fortement sur l’utilisation d’un serveur web REST pour gérer les modèles et l’inférence comme les achèvements de conversation :

Diagramme de l’architecture précédente pour Foundry Local.

Le Kit de développement logiciel (SDK) utilise un appel procédural distant (RPC) pour rechercher l’exécutable CLI local Foundry sur l’ordinateur, démarrer le serveur web, puis communiquer avec lui via HTTP. Cette architecture a eu plusieurs limitations, notamment :

  • Complexité de la gestion du cycle de vie du serveur web.
  • Déploiement difficile : les utilisateurs finaux ont dû installer l’interface CLI locale Foundry sur leurs ordinateurs et votre application.
  • La gestion des versions de l’interface CLI et du Kit de développement logiciel (SDK) peut entraîner des problèmes de compatibilité.

Pour résoudre ces problèmes, l’architecture repensée dans la version 0.8.0 et les versions ultérieures utilise une approche plus rationalisée. La nouvelle architecture est la suivante :

Diagramme de la nouvelle architecture pour Foundry Local.

Dans cette nouvelle architecture :

  • Votre application est autonome. L’interface CLI locale Foundry n’est pas nécessaire pour être installée séparément sur l’ordinateur de l’utilisateur final, ce qui facilite le déploiement d’applications.
  • Le serveur web REST est facultatif. Vous pouvez toujours utiliser le serveur web si vous souhaitez intégrer d’autres outils qui communiquent via HTTP. Lisez Complétions de chat via le serveur REST avec Foundry Local pour plus d'informations sur cette fonctionnalité.
  • Le SDK prend en charge nativement les saisies semi-automatiques et les transcriptions audio, ce qui vous permet de créer des applications IA conversationnelles avec moins de dépendances. Pour des détails sur l'utilisation de cette fonctionnalité, lisez l'API de complétions de chat native Foundry Local.
  • Sur les appareils Windows, vous pouvez utiliser une build Windows ML qui gère l’accélération matérielle pour les modèles sur l’appareil en intégrant le bon runtime et les pilotes appropriés.

Modifications d'API

La version 0.8.0 et les versions ultérieures fournissent une API plus orientée objet et composable. Le point d’entrée principal continue d’être la FoundryLocalManager classe, mais au lieu d’être un ensemble plat de méthodes qui fonctionnent via des appels statiques à une API HTTP sans état, le SDK expose désormais des méthodes sur l’instance FoundryLocalManager qui conservent l’état sur le service et les modèles.

Primitif Versions < 0.8.0 Versions >= 0.8.0
Configuration N/A config = Configuration(...)
Obtenir le gestionnaire mgr = FoundryLocalManager(); await FoundryLocalManager.CreateAsync(config, logger);
var mgr = FoundryLocalManager.Instance;
Obtenir le catalogue N/A catalog = await mgr.GetCatalogAsync();
Répertorier les modèles mgr.ListCatalogModelsAsync(); catalog.ListModelsAsync();
Obtenir un modèle mgr.GetModelInfoAsync("aliasOrModelId"); catalog.GetModelAsync(alias: "alias");
Obtenir un variant N/A model.SelectedVariant;
Définir le variant N/A model.SelectVariant();
Télécharger un modèle mgr.DownloadModelAsync("aliasOrModelId"); model.DownloadAsync()
Charger un modèle mgr.LoadModelAsync("aliasOrModelId"); model.LoadAsync()
Décharger un modèle mgr.UnloadModelAsync("aliasOrModelId"); model.UnloadAsync()
Répertorier les modèles chargés mgr.ListLoadedModelsAsync(); catalog.GetLoadedModelsAsync();
Obtenir le chemin d’accès au modèle N/A model.GetPathAsync()
Démarrer le service mgr.StartServiceAsync(); mgr.StartWebServerAsync();
Arrêter le service mgr.StopServiceAsync(); mgr.StopWebServerAsync();
Emplacement du cache mgr.GetCacheLocationAsync(); config.ModelCacheDir
Répertorier les modèles mis en cache mgr.ListCachedModelsAsync(); catalog.GetCachedModelsAsync();

L’API permet à Foundry Local d’être plus configurable sur le serveur web, la journalisation, l’emplacement du cache et la sélection de variantes de modèle. Par exemple, la Configuration classe vous permet de configurer le nom de l’application, le niveau de journalisation, les URL de serveur web et les répertoires pour les données d’application, le cache de modèle et les journaux :

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

Référence d’API

Guide de migration du Kit de développement logiciel (SDK) JavaScript

Pour améliorer votre capacité à expédier des applications à l’aide de l’IA sur appareil, il existe des modifications substantielles apportées à l’architecture du Kit de développement logiciel (SDK) JavaScript. Dans cette section, nous décrivons les principales modifications pour vous aider à migrer vos applications vers la dernière version du SDK.

Note

Dans la version 0.9.0 du Kit de développement logiciel (SDK) JavaScript et dans les versions ultérieures, l’API a subi des modifications majeures par rapport aux versions précédentes (<=0.5.0).

Le diagramme suivant montre comment l’architecture précédente s’appuyait fortement sur l’utilisation d’un serveur web REST pour gérer les modèles ainsi que l’inférence, comme les complétions de chat.

Diagramme de l’architecture précédente pour Foundry Local.

Le Kit de développement logiciel (SDK) utilise un appel procédural distant (RPC) pour rechercher l’exécutable CLI local Foundry sur l’ordinateur, démarrer le serveur web, puis communiquer avec lui via HTTP. Cette architecture a eu plusieurs limitations, notamment :

  • Complexité de la gestion du cycle de vie du serveur web.
  • Déploiement difficile : les utilisateurs finaux ont dû installer l’interface CLI locale Foundry sur leurs ordinateurs et votre application.
  • La gestion des versions de l’interface CLI et du Kit de développement logiciel (SDK) peut entraîner des problèmes de compatibilité.

Pour résoudre ces problèmes, l’architecture repensée utilise une approche plus rationalisée. La nouvelle architecture est la suivante :

Diagramme de la nouvelle architecture pour Foundry Local.

Dans cette nouvelle architecture :

  • Votre application est autonome. L’interface CLI locale Foundry n’est pas nécessaire pour être installée séparément sur l’ordinateur de l’utilisateur final, ce qui facilite le déploiement d’applications.
  • Le serveur web REST est facultatif. Vous pouvez toujours utiliser le serveur web si vous souhaitez intégrer d’autres outils qui communiquent via HTTP.
  • Le SDK prend en charge nativement les saisies semi-automatiques et les transcriptions audio, ce qui vous permet de créer des applications IA conversationnelles avec moins de dépendances.

Modifications d'API

La dernière version fournit une API plus orientée objet et composable. Le point d’entrée principal continue d’être la FoundryLocalManager classe, mais au lieu d’être un ensemble plat de méthodes qui fonctionnent via des appels statiques à une API HTTP sans état, le SDK expose désormais des méthodes sur l’instance FoundryLocalManager qui conservent l’état sur le service et les modèles.

Primitif Version précédente Version actuelle
Configuration N/A config = { appName: "app-name", ... }
Obtenir le gestionnaire mgr = new FoundryLocalManager(); mgr = FoundryLocalManager.create(config);
Obtenir le catalogue N/A catalog = mgr.catalog;
Répertorier les modèles mgr.listCatalogModels(); catalog.getModels();
Obtenir un modèle mgr.getModelInfo("aliasOrModelId"); catalog.getModel(alias);
Obtenir un variant N/A model.id;
Définir le variant N/A model.selectVariant(modelId);
Télécharger un modèle mgr.downloadModel("aliasOrModelId"); model.download();
Charger un modèle mgr.loadModel("aliasOrModelId"); model.load();
Décharger un modèle mgr.unloadModel("aliasOrModelId"); model.unload();
Répertorier les modèles chargés mgr.listLoadedModels(); catalog.getLoadedModels();
Obtenir le chemin d’accès au modèle N/A model.path;
Démarrer le service mgr.startService(); mgr.startWebService();
Arrêter le service N/A mgr.stopWebService();
Emplacement du cache mgr.getCacheLocation(); config.modelCacheDir
Répertorier les modèles mis en cache mgr.listCachedModels(); catalog.getCachedModels();

L’API permet à Foundry Local d’être plus configurable sur le serveur web, la journalisation, l’emplacement du cache et la sélection de variantes de modèle. Par exemple, le config vous permet de configurer le nom de l'application, le niveau de journalisation, les URL des serveurs web, ainsi que les répertoires pour les données de l'application, le cache de modèle et les journaux :

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",
};

Dans la version précédente du Kit de développement logiciel (SDK) JavaScript local Foundry, vous n’avez pas pu configurer ces paramètres directement via le Kit de développement logiciel (SDK), ce qui a limité votre capacité à personnaliser le comportement du service.

References

Guide de migration du Kit de développement logiciel (SDK) Python

Pour améliorer votre capacité à expédier des applications à l’aide de l’IA sur appareil, il existe des modifications substantielles apportées à l’architecture du SDK Python. Dans cette section, nous décrivons les principales modifications pour vous aider à migrer vos applications vers la dernière version du SDK.

Note

Dans la dernière version du SDK Python (1.0.0), il y a des modifications importantes dans l'API par rapport aux versions précédentes (<=0.5.1).

Le diagramme suivant montre comment l’architecture précédente s’appuyait fortement sur l’utilisation d’un serveur web REST pour gérer les modèles ainsi que l’inférence, comme les complétions de chat.

Diagramme de l’architecture précédente pour Foundry Local.

Le Kit de développement logiciel (SDK) utilise un appel procédural distant (RPC) pour rechercher l’exécutable CLI local Foundry sur l’ordinateur, démarrer le serveur web, puis communiquer avec lui via HTTP. Cette architecture a eu plusieurs limitations, notamment :

  • Complexité de la gestion du cycle de vie du serveur web.
  • Déploiement difficile : les utilisateurs finaux ont dû installer l’interface CLI locale Foundry sur leurs ordinateurs et votre application.
  • La gestion des versions de l’interface CLI et du Kit de développement logiciel (SDK) peut entraîner des problèmes de compatibilité.

Pour résoudre ces problèmes, l’architecture repensée utilise une approche plus rationalisée. La nouvelle architecture est la suivante :

Diagramme de la nouvelle architecture pour Foundry Local.

Dans cette nouvelle architecture :

  • Votre application est autonome. L’interface CLI locale Foundry n’est pas nécessaire pour être installée séparément sur l’ordinateur de l’utilisateur final, ce qui facilite le déploiement d’applications.
  • Le serveur web REST est facultatif. Vous pouvez toujours utiliser le serveur web si vous souhaitez intégrer d’autres outils qui communiquent via HTTP.
  • Le SDK prend en charge nativement les saisies semi-automatiques et les transcriptions audio, ce qui vous permet de créer des applications IA conversationnelles avec moins de dépendances.

Modifications d'API

La dernière version fournit une API plus orientée objet et composable. Le point d’entrée principal continue d’être la FoundryLocalManager classe, mais le modèle d’initialisation, la gestion des modèles et l’inférence ont tous changé de manière significative.

Primitif Version précédente (foundry-local) Version actuelle (foundry-local-sdk)
Paquet pip install foundry-local pip install foundry-local-sdk
Importation from foundry_local import FoundryLocalManager from foundry_local_sdk import Configuration, FoundryLocalManager
Configuration N/A config = Configuration(app_name="app-name")
Obtenir le gestionnaire manager = FoundryLocalManager(alias) FoundryLocalManager.initialize(config)
manager = FoundryLocalManager.instance
Obtenir le catalogue N/A catalog = manager.catalog
Répertorier les modèles manager.list_catalog_models() catalog.list_models()
Obtenir un modèle manager.get_model_info(alias) catalog.get_model(alias)
Télécharger un modèle manager.download_model(alias) model.download(progress_callback)
Charger un modèle manager.load_model(alias) model.load()
Décharger un modèle manager.unload_model(alias) model.unload()
Répertorier les modèles chargés manager.list_loaded_models() catalog.get_loaded_models()
Répertorier les modèles mis en cache manager.list_cached_models() catalog.get_cached_models()
Emplacement du cache manager.get_cache_location() config.model_cache_dir
Démarrer le service manager.start_service() manager.start_web_service()
Point de terminaison de service manager.endpoint manager.urls

L’API permet à Foundry Local d’être plus configurable sur le serveur web, la journalisation, l’emplacement du cache et la sélection de variantes de modèle. Par exemple, la Configuration classe vous permet de configurer le nom de l’application, le niveau de journalisation, les URL de serveur web et les répertoires pour les données d’application, le cache de modèle et les journaux :

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

Guide de migration du Kit de développement logiciel (SDK) Rust

Pour améliorer votre capacité à expédier des applications à l’aide de l’IA sur appareil, il existe des modifications substantielles apportées à l’architecture du Kit de développement logiciel (SDK) Rust. Dans cette section, nous décrivons les principales modifications pour vous aider à migrer vos applications vers la dernière version du SDK.

Note

Dans la dernière version du Kit de développement logiciel (SDK) Rust (1.0.0), il existe des changements cassants dans l’API de la version précédente. Le nom du crate a été modifié de foundry-local à foundry-local-sdk.

Le diagramme suivant montre comment l’architecture précédente s’appuyait fortement sur l’utilisation d’un serveur web REST pour gérer les modèles ainsi que l’inférence, comme les complétions de chat.

Diagramme de l’architecture précédente pour Foundry Local.

Le Kit de développement logiciel (SDK) utilise un appel procédural distant (RPC) pour rechercher l’exécutable CLI local Foundry sur l’ordinateur, démarrer le serveur web, puis communiquer avec lui via HTTP. Cette architecture a eu plusieurs limitations, notamment :

  • Complexité de la gestion du cycle de vie du serveur web.
  • Déploiement difficile : les utilisateurs finaux ont dû installer l’interface CLI locale Foundry sur leurs ordinateurs et votre application.
  • La gestion des versions de l’interface CLI et du Kit de développement logiciel (SDK) peut entraîner des problèmes de compatibilité.

Pour résoudre ces problèmes, l’architecture repensée utilise une approche plus rationalisée. La nouvelle architecture est la suivante :

Diagramme de la nouvelle architecture pour Foundry Local.

Dans cette nouvelle architecture :

  • Votre application est autonome. L’interface CLI locale Foundry n’est pas nécessaire pour être installée séparément sur l’ordinateur de l’utilisateur final, ce qui facilite le déploiement d’applications.
  • Le serveur web REST est facultatif. Vous pouvez toujours utiliser le serveur web si vous souhaitez intégrer d’autres outils qui communiquent via HTTP.
  • Le SDK prend en charge nativement les saisies semi-automatiques et les transcriptions audio, ce qui vous permet de créer des applications IA conversationnelles avec moins de dépendances.

Modifications d'API

La dernière version fournit une API plus orientée objet et composable. Le modèle de générateur a été remplacé par une approche basée sur la configuration et la gestion des modèles utilise désormais des objets dédiés Model .

Primitif Version précédente (foundry-local) Version actuelle (foundry-local-sdk)
Caisse foundry-local foundry-local-sdk
Configuration N/A FoundryLocalConfig::new("app-name")
Obtenir le gestionnaire FoundryLocalManager::builder().build().await? FoundryLocalManager::create(config)?
Obtenir le catalogue N/A manager.catalog()
Répertorier les modèles manager.list_catalog_models().await? manager.catalog().get_models().await?
Obtenir un modèle manager.get_model_info(alias).await? manager.catalog().get_model(alias).await?
Télécharger un modèle manager.download_model(alias).await? model.download(callback).await?
Charger un modèle manager.load_model(alias).await? model.load().await?
Décharger un modèle manager.unload_model(alias).await? model.unload().await?
Répertorier les modèles chargés manager.list_loaded_models().await? manager.catalog().get_loaded_models().await?
Répertorier les modèles mis en cache manager.list_cached_models().await? manager.catalog().get_cached_models().await?
Démarrer le service manager.start_service()? manager.start_web_service().await?
Point de terminaison manager.endpoint()? manager.urls()
Appels HTTP reqwest::Client (REST manuel) Kit de développement logiciel (SDK) natif : model.create_chat_client()

Le nouveau Kit de développement logiciel (SDK) fournit des clients de conversation et d’audio natifs, ce qui élimine la nécessité de requêtes HTTP manuelles dans la plupart des cas :

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

  • Dernière mise à jour :