Guia de migração do SDK local da Foundry

Este guia fornece instruções para migrar o seu código da versão antiga do Foundry Local SDK para a versão atual. O novo SDK remove a dependência da CLI local da Foundry e, por isso, permite enviar as suas aplicações sem que os utilizadores tenham de instalar a CLI ou configurar um ambiente local da Foundry. O novo SDK inclui também melhorias na API para melhor usabilidade e desempenho.

Guia de Migração do SDK C#

Para melhorar a sua capacidade de distribuir aplicações usando IA no dispositivo, há alterações substanciais na arquitetura do SDK C# em versões 0.8.0 e versões posteriores. Nesta secção, descrevemos as principais alterações para o ajudar a migrar as suas aplicações para a versão mais recente do SDK.

Observação

Na versão 0.8.0 do SDK e posteriores, há alterações na API que causam incompatibilidades com as versões anteriores (<=0.3.0).

O diagrama seguinte mostra como a arquitetura anterior – para versões anteriores 0.8.0 – dependia fortemente do uso de um servidor web REST para gerir modelos e inferências, como concluições de chat:

O SDK usaria uma Chamada Procedural Remota (RPC) para encontrar o executável CLI Local da Foundry na máquina, iniciar o servidor web e depois comunicar-se com ele via HTTP. Esta arquitetura tinha várias limitações, incluindo:

• Complexidade na gestão do ciclo de vida do servidor web.
• Implementação desafiante: Os utilizadores finais precisavam de ter a CLI local da Foundry instalada nas suas máquinas e na sua aplicação.
• A gestão de versões do CLI e do SDK pode causar problemas de compatibilidade.

Para resolver estas questões, a arquitetura redesenhada em versão 0.8.0 e posteriormente utiliza uma abordagem mais simplificada. A nova arquitetura é a seguinte:

Nesta nova arquitetura:

• A sua aplicação é independente. Não é necessário instalar a CLI local do Foundry separadamente na máquina do utilizador final, facilitando a implementação de aplicações.
• O servidor web REST é opcional. Ainda podes usar o servidor web se quiseres integrar com outras ferramentas que comunicam via HTTP. Leia Sobre a utilização das conclusões do chat via servidor REST com o Foundry Local para obter detalhes sobre como utilizar esta funcionalidade.
• O SDK tem suporte nativo para completação de conversas e transcrições de áudio, permitindo construir aplicações de IA conversacional com menos dependências. Leia a API de completação nativa de chat do Use Foundry para detalhes sobre como utilizar esta funcionalidade.
• Em dispositivos Windows, pode utilizar uma build do Windows ML que gere aceleração de hardware para os modelos no dispositivo, integrando o runtime e os drivers adequados.

Alterações da API

Versão 0.8.0 e versões posteriores fornecem uma API mais orientada a objetos e componível. O principal ponto de entrada continua a ser a FoundryLocalManager classe, mas em vez de ser um conjunto plano de métodos que operam através de chamadas estáticas para uma API HTTP sem estado, o SDK expõe agora métodos na FoundryLocalManager instância que mantêm o estado sobre o serviço e os modelos.

Primitivo	Versões < 0.8.0	Versões >= 0.8.0
Configuração	N/A	config = Configuration(...)
Contacta o Gestor	mgr = FoundryLocalManager();	await FoundryLocalManager.CreateAsync(config, logger); var mgr = FoundryLocalManager.Instance;
Aceder ao Catálogo	N/A	catalog = await mgr.GetCatalogAsync();
Modelos de Lista	mgr.ListCatalogModelsAsync();	catalog.ListModelsAsync();
Get Model	mgr.GetModelInfoAsync("aliasOrModelId");	catalog.GetModelAsync(alias: "alias");
Obtenha Variante	N/A	model.SelectedVariant;
Definir Variante	N/A	model.SelectVariant();
Descarregue um modelo	mgr.DownloadModelAsync("aliasOrModelId");	model.DownloadAsync()
Carregar um modelo	mgr.LoadModelAsync("aliasOrModelId");	model.LoadAsync()
Descarregar um modelo	mgr.UnloadModelAsync("aliasOrModelId");	model.UnloadAsync()
Listar modelos carregados	mgr.ListLoadedModelsAsync();	catalog.GetLoadedModelsAsync();
Obtenha caminho do modelo	N/A	model.GetPathAsync()
Início do serviço	mgr.StartServiceAsync();	mgr.StartWebServerAsync();
Parar serviço	mgr.StopServiceAsync();	mgr.StopWebServerAsync();
Localização do cache	mgr.GetCacheLocationAsync();	config.ModelCacheDir
Lista de modelos em cache	mgr.ListCachedModelsAsync();	catalog.GetCachedModelsAsync();

A API permite que o Foundry Local seja mais configurável através do servidor web, registo, localização de cache e seleção de variantes do modelo. Por exemplo, a Configuration classe permite-lhe configurar o nome da aplicação, o nível de registo, URLs do servidor web e diretórios para dados de aplicação, cache de modelos e registos:

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

Referência da API

• Para mais detalhes sobre o Foundry Local C# SDK, leia a Foundry Local C# SDK API Reference.

Guia de Migração do SDK JavaScript

Para melhorar a sua capacidade de lançar aplicações usando IA no dispositivo, há alterações substanciais na arquitetura do SDK JavaScript. Nesta secção, descrevemos as principais alterações para o ajudar a migrar as suas aplicações para a versão mais recente do SDK.

Observação

Na versão 0.9.0 do SDK JavaScript e posteriores, existem alterações disruptivas na API em relação às versões anteriores (<=0.5.0).

O diagrama seguinte mostra como a arquitetura anterior dependia fortemente do uso de um servidor web REST para gerir modelos e inferências, como conclusãos de chat:

O SDK usaria uma Chamada Procedural Remota (RPC) para encontrar o executável CLI Local da Foundry na máquina, iniciar o servidor web e depois comunicar-se com ele via HTTP. Esta arquitetura tinha várias limitações, incluindo:

• Complexidade na gestão do ciclo de vida do servidor web.
• Implementação desafiante: Os utilizadores finais precisavam de ter a CLI local da Foundry instalada nas suas máquinas e na sua aplicação.
• A gestão de versões do CLI e do SDK pode causar problemas de compatibilidade.

Para resolver estas questões, a arquitetura redesenhada utiliza uma abordagem mais simplificada. A nova arquitetura é a seguinte:

Nesta nova arquitetura:

• A sua aplicação é independente. Não é necessário instalar a CLI local do Foundry separadamente na máquina do utilizador final, facilitando a implementação de aplicações.
• O servidor web REST é opcional. Ainda podes usar o servidor web se quiseres integrar com outras ferramentas que comunicam via HTTP.
• O SDK tem suporte nativo para completação de conversas e transcrições de áudio, permitindo construir aplicações de IA conversacional com menos dependências.

Alterações da API

A versão mais recente oferece uma API mais orientada a objetos e componível. O principal ponto de entrada continua a ser a FoundryLocalManager classe, mas em vez de ser um conjunto plano de métodos que operam através de chamadas estáticas para uma API HTTP sem estado, o SDK expõe agora métodos na FoundryLocalManager instância que mantêm o estado sobre o serviço e os modelos.

Primitivo	Versão Anterior	Versão Atual
Configuração	N/A	config = { appName: "app-name", ... }
Contacta o Gestor	mgr = new FoundryLocalManager();	mgr = FoundryLocalManager.create(config);
Aceder ao Catálogo	N/A	catalog = mgr.catalog;
Modelos de Lista	mgr.listCatalogModels();	catalog.getModels();
Get Model	mgr.getModelInfo("aliasOrModelId");	catalog.getModel(alias);
Obtenha Variante	N/A	model.id;
Definir Variante	N/A	model.selectVariant(modelId);
Descarregue um modelo	mgr.downloadModel("aliasOrModelId");	model.download();
Carregar um modelo	mgr.loadModel("aliasOrModelId");	model.load();
Descarregar um modelo	mgr.unloadModel("aliasOrModelId");	model.unload();
Listar modelos carregados	mgr.listLoadedModels();	catalog.getLoadedModels();
Obtenha caminho do modelo	N/A	model.path;
Início do serviço	mgr.startService();	mgr.startWebService();
Parar serviço	N/A	mgr.stopWebService();
Localização do cache	mgr.getCacheLocation();	config.modelCacheDir
Lista de modelos em cache	mgr.listCachedModels();	catalog.getCachedModels();

A API permite que o Foundry Local seja mais configurável através do servidor web, registo, localização de cache e seleção de variantes do modelo. Por exemplo, o config permite-lhe configurar o nome da aplicação, o nível de registo, os URLs do servidor web e os diretórios para os dados da aplicação, o cache de modelos e os registos:

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

Na versão anterior do Foundry Local JavaScript SDK, não era possível configurar estas definições diretamente através do SDK, o que limitava a capacidade de personalizar o comportamento do serviço.

Referências

• Integrar com SDKs de inferência
• Use a API nativa de completação de chat local Foundry

Guia de Migração do SDK Python

Para melhorar a sua capacidade de lançar aplicações usando IA no dispositivo, há mudanças substanciais na arquitetura do SDK Python. Nesta secção, descrevemos as principais alterações para o ajudar a migrar as suas aplicações para a versão mais recente do SDK.

Observação

Na versão mais recente do Python SDK (1.0.0), há alterações quebrantes na API em relação às versões anteriores (<=0.5.1).

O diagrama seguinte mostra como a arquitetura anterior dependia fortemente do uso de um servidor web REST para gerir modelos e inferências, como conclusãos de chat:

O SDK usaria uma Chamada Procedural Remota (RPC) para encontrar o executável CLI Local da Foundry na máquina, iniciar o servidor web e depois comunicar-se com ele via HTTP. Esta arquitetura tinha várias limitações, incluindo:

• Complexidade na gestão do ciclo de vida do servidor web.
• Implementação desafiante: Os utilizadores finais precisavam de ter a CLI local da Foundry instalada nas suas máquinas e na sua aplicação.
• A gestão de versões do CLI e do SDK pode causar problemas de compatibilidade.

Para resolver estas questões, a arquitetura redesenhada utiliza uma abordagem mais simplificada. A nova arquitetura é a seguinte:

Nesta nova arquitetura:

• A sua aplicação é independente. Não é necessário instalar a CLI local do Foundry separadamente na máquina do utilizador final, facilitando a implementação de aplicações.
• O servidor web REST é opcional. Ainda podes usar o servidor web se quiseres integrar com outras ferramentas que comunicam via HTTP.
• O SDK tem suporte nativo para completação de conversas e transcrições de áudio, permitindo construir aplicações de IA conversacional com menos dependências.

Alterações da API

A versão mais recente oferece uma API mais orientada a objetos e componível. O principal ponto de entrada continua a ser a FoundryLocalManager classe, mas o padrão de inicialização, a gestão do modelo e a inferência mudaram significativamente.

Primitivo	Versão Anterior (foundry-local)	Versão Atual (foundry-local-sdk)
Embalagem	pip install foundry-local	pip install foundry-local-sdk
Importação	from foundry_local import FoundryLocalManager	from foundry_local_sdk import Configuration, FoundryLocalManager
Configuração	N/A	config = Configuration(app_name="app-name")
Contacta o Gestor	manager = FoundryLocalManager(alias)	FoundryLocalManager.initialize(config) manager = FoundryLocalManager.instance
Aceder ao Catálogo	N/A	catalog = manager.catalog
Modelos de Lista	manager.list_catalog_models()	catalog.list_models()
Get Model	manager.get_model_info(alias)	catalog.get_model(alias)
Descarregue um modelo	manager.download_model(alias)	model.download(progress_callback)
Carregar um modelo	manager.load_model(alias)	model.load()
Descarregar um modelo	manager.unload_model(alias)	model.unload()
Listar modelos carregados	manager.list_loaded_models()	catalog.get_loaded_models()
Lista de modelos em cache	manager.list_cached_models()	catalog.get_cached_models()
Localização do cache	manager.get_cache_location()	config.model_cache_dir
Início do serviço	manager.start_service()	manager.start_web_service()
Ponto final de serviço	manager.endpoint	manager.urls

A API permite que o Foundry Local seja mais configurável através do servidor web, registo, localização de cache e seleção de variantes do modelo. Por exemplo, a Configuration classe permite-lhe configurar o nome da aplicação, o nível de registo, URLs do servidor web e diretórios para dados de aplicação, cache de modelos e registos:

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",
)

Referências

• Usar conclusões de chat via servidor REST
• Use a API nativa de completação de chat local Foundry

Guia de Migração do SDK Rust

Para melhorar a sua capacidade de distribuir aplicações usando IA no dispositivo, há alterações substanciais na arquitetura do SDK Rust. Nesta secção, descrevemos as principais alterações para o ajudar a migrar as suas aplicações para a versão mais recente do SDK.

Observação

Na versão mais recente do Rust SDK (1.0.0), há alterações quebrantes na API em relação à versão anterior. O nome da caixa mudou de foundry-local para foundry-local-sdk.

O diagrama seguinte mostra como a arquitetura anterior dependia fortemente do uso de um servidor web REST para gerir modelos e inferências, como conclusãos de chat:

O SDK usaria uma Chamada de Procedimento Remoto (RPC) para encontrar o executável do Foundry CLI Local na máquina, iniciar o servidor web e depois comunicar com ele através de HTTP. Esta arquitetura tinha várias limitações, incluindo:

• Complexidade na gestão do ciclo de vida do servidor web.
• Implementação desafiante: Os utilizadores finais precisavam de ter a CLI local da Foundry instalada nas suas máquinas e na sua aplicação.
• A gestão de versões do CLI e do SDK pode causar problemas de compatibilidade.

Para resolver estas questões, a arquitetura redesenhada utiliza uma abordagem mais simplificada. A nova arquitetura é a seguinte:

Nesta nova arquitetura:

• A sua aplicação é independente. Não é necessário instalar a CLI local do Foundry separadamente na máquina do utilizador final, facilitando a implementação de aplicações.
• O servidor web REST é opcional. Ainda podes usar o servidor web se quiseres integrar com outras ferramentas que comunicam via HTTP.
• O SDK tem suporte nativo para completação de conversas e transcrições de áudio, permitindo construir aplicações de IA conversacional com menos dependências.

Alterações da API

A versão mais recente oferece uma API mais orientada a objetos e componível. O padrão builder foi substituído por uma abordagem baseada em configuração, e a gestão de modelos utiliza agora objetos dedicados Model .

Primitivo	Versão Anterior (foundry-local)	Versão Atual (foundry-local-sdk)
Crate	foundry-local	foundry-local-sdk
Configuração	N/A	FoundryLocalConfig::new("app-name")
Contacta o Gestor	FoundryLocalManager::builder().build().await?	FoundryLocalManager::create(config)?
Aceder ao Catálogo	N/A	manager.catalog()
Modelos de Lista	manager.list_catalog_models().await?	manager.catalog().get_models().await?
Get Model	manager.get_model_info(alias).await?	manager.catalog().get_model(alias).await?
Descarregue um modelo	manager.download_model(alias).await?	model.download(callback).await?
Carregar um modelo	manager.load_model(alias).await?	model.load().await?
Descarregar um modelo	manager.unload_model(alias).await?	model.unload().await?
Listar modelos carregados	manager.list_loaded_models().await?	manager.catalog().get_loaded_models().await?
Lista de modelos em cache	manager.list_cached_models().await?	manager.catalog().get_cached_models().await?
Início do serviço	manager.start_service()?	manager.start_web_service().await?
Ponto final	manager.endpoint()?	manager.urls()
Chamadas HTTP	reqwest::Client (REST manual)	SDK nativo: model.create_chat_client()

O novo SDK fornece clientes nativos de chat e áudio, eliminando a necessidade de pedidos HTTP manuais na maioria dos casos:

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

Referências

• Usar conclusões de chat via servidor REST
• Use a API nativa de completação de chat local Foundry