Compartilhar via

Referência do SDK Local do Foundry

O SDK Local do Foundry permite que você envie recursos de IA em seus aplicativos capazes de usar modelos de IA locais por meio de uma API simples e intuitiva. O SDK abstrai as complexidades do gerenciamento de modelos de IA e fornece uma experiência perfeita para integrar recursos locais de IA em seus aplicativos. Essa referência documenta implementações do SDK para C#, JavaScript, Python e Rust.

O SDK não exige que a CLI Local do Foundry seja instalada no computador de usuários finais, permitindo que você envie seus aplicativos sem etapas extras de instalação para seus usuários – seus aplicativos são independentes. Os benefícios extras do SDK Local do Foundry incluem:

  • Detecção e otimização de hardware: avaliação automática de funcionalidade para GPU, NPU e CPU.
  • Execution provider management (Windows): download automático e registro de provedores de execução do ONNX Runtime apropriados (CUDA, Vitis, QNN, OpenVINO, TensorRT) com base nos recursos do dispositivo.
  • Compatível com Metal via WebGPU (macOS): suporte nativo para execução de modelos no Apple Silicon com performance otimizada.
  • Aquisição de modelo: download contínuo do Catálogo de Modelos do Foundry com controle de versão, atualizações e seleção automática de modelos otimizados para hardware, com suporte para fallback.
  • Runtime eficiente: adiciona aproximadamente 20 MB ao tamanho do aplicativo, compatível com dispositivos desde smartphones até desktops.
  • Compatibilidade da API openai: fácil integração com modelos e ferramentas do OpenAI.
  • Servidor REST opcional: execute Foundry Local como um serviço local acessível por outros aplicativos.

Referência do SDK do C#

Instalar pacotes

Se você estiver desenvolvendo ou enviando em Windows, selecione a guia Windows. O pacote Windows integra-se ao runtime Windows ML – ele fornece a mesma área de superfície de API com uma amplitude maior de aceleração de hardware.

dotnet add package Microsoft.AI.Foundry.Local.WinML
dotnet add package OpenAI

Os exemplos de C# no repositório GitHub são projetos pré-configurados. Se você estiver criando do zero, leia a referência do SDK Local do Foundry para obter mais detalhes sobre como configurar seu projeto em C# com o Foundry Local.

configuração de Project

Os repositórios de exemplo incluem um .csproj arquivo que manipula a detecção de plataforma automaticamente. Se você estiver criando um projeto do zero, use essa configuração como referência:

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

A tabela a seguir explica as principais configurações do projeto:

Configurações Descrição
TargetFramework No sistema Windows, os destinos net9.0-windows10.0.26100 para a aceleração de hardware do WinML. Em outras plataformas, os alvos net9.0.
WindowsAppSDKSelfContained Defina como false para usar o SDK do Aplicativo Windows instalado pelo sistema em vez de agrupá-lo.
WindowsPackageType Configure None para criar como um aplicativo de desktop não empacotado (sem empacotamento MSIX).
EnableCoreMrtTooling Defina como false para desabilitar as ferramentas de recursos do MRT Core, pois não são necessárias para aplicativos de console.
RuntimeIdentifier O padrão é o identificador de runtime do SDK atual, garantindo que os binários de plataforma corretos sejam selecionados.
Microsoft.AI.Foundry.Local.WinML Pacote somente para Windows que usa o WinML para aceleração de hardware e gestão automática dos provedores de execução.
Microsoft.AI.Foundry.Local Pacote multiplataforma para macOS, Linux e Windows sem WinML.
Microsoft.ML.OnnxRuntime.Gpu / OnnxRuntimeGenAI.Cuda Pacotes de suporte para GPU do Linux para hardware habilitado para CUDA.

Início Rápido

Use este trecho de código para verificar se o SDK pode inicializar e acessar o 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()}");

Este exemplo imprime o número de modelos disponíveis para seu hardware.

Samples

Referência de API

API de Transcrição de Áudio Nativo

O SDK do C# inclui um cliente de áudio nativo para transcrever arquivos de áudio no dispositivo usando modelos Whisper. Isso executa a inferência em processo sem precisar do servidor Web REST.

Obter um cliente de áudio

Depois de carregar um modelo Whisper, obtenha um cliente de áudio:

var audioClient = await model.GetAudioClientAsync();

Métodos de transcrição de áudio

Método Signature Descrição
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> Transmite os resultados da transcrição parte por parte. Cada parte tem uma propriedade Text.

Configurações do AudioClient

Propriedade Tipo Descrição
Language string Código de idioma ISO 639-1 (por exemplo, "en"). Melhora a precisão.
Temperature float Temperatura de amostragem (0,0 a 1,0). Valores mais baixos são mais determinísticos.

Exemplo

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

Referências:

Referência do SDK do JavaScript

Instalar pacotes

Se você estiver desenvolvendo ou enviando em Windows, selecione a guia Windows. O pacote Windows integra-se ao runtime Windows ML – ele fornece a mesma área de superfície de API com uma amplitude maior de aceleração de hardware.

npm install foundry-local-sdk-winml openai

Início Rápido

Use este trecho de código para verificar se o SDK pode inicializar e acessar o 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}`);
}

Este exemplo gera a lista de modelos disponíveis para seu hardware.

Samples

Referência de API

References

Referência do SDK do Python

Instalar pacotes

Se você estiver desenvolvendo ou enviando em Windows, selecione a guia Windows. O pacote Windows integra-se ao runtime Windows ML – ele fornece a mesma área de superfície de API com uma amplitude maior de aceleração de hardware.

pip install foundry-local-sdk-winml openai

Início Rápido

Use este trecho de código para verificar se o SDK pode inicializar e acessar o 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())

Este exemplo imprime o número de modelos disponíveis para seu hardware.

Samples

Configuração

A Configuration classe permite personalizar o comportamento do 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 Descrição
app_name str Nome da sua aplicação.
log_level str Nível de registro em log (por exemplo, "info", "debug").
model_cache_dir str Diretório para modelos armazenados em cache.
web dict Configuração do serviço Web com a chave urls.

API principal

Método Descrição
FoundryLocalManager.initialize(config) Inicie o gerenciador singleton com um Configuration.
FoundryLocalManager.instance Acesse a instância inicializada do gerenciador.
manager.catalog.list_models() Liste todos os modelos disponíveis no catálogo.
manager.catalog.get_model(alias) Obtenha um modelo por alias.
manager.catalog.get_cached_models() Listar modelos em cache local.
manager.catalog.get_loaded_models() Liste os modelos carregados no momento.
model.download(progress_callback) Baixe o modelo (ignora se armazenado em cache).
model.load() Carregue o modelo para inferência.
model.unload() Descarregue o modelo.
model.is_cached Verifique se o modelo está armazenado em cache localmente.
model.is_loaded Verifique se o modelo está carregado.

API Nativa de Conclusões de Conversa

Depois de carregar um modelo, obtenha um cliente de chat:

client = model.get_chat_client()
Método Descrição
client.complete_chat(messages) Gere uma resposta de chat completa.
client.complete_streaming_chat(messages) Transmitir partes de resposta de chat.

API de Transcrição de Áudio Nativo

Depois de carregar um modelo Whisper, obtenha um cliente de áudio:

audio_client = model.get_audio_client()
Método Descrição
audio_client.transcribe(file_path) Transcreva um arquivo de áudio. Retorna um objeto com uma text propriedade.

Referências:

Referência do SDK do Rust

Instalar pacotes

Se você estiver desenvolvendo ou enviando em Windows, selecione a guia Windows. O pacote Windows integra-se ao runtime Windows ML – ele fornece a mesma área de superfície de API com uma amplitude maior de aceleração de hardware.

cargo add foundry-local-sdk --features winml
cargo add tokio --features full
cargo add tokio-stream anyhow

Início Rápido

Use este trecho de código para verificar se o SDK pode inicializar e acessar o 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(())
}

Este exemplo imprime o número de modelos disponíveis para seu hardware.

Samples

Configuração

O FoundryLocalConfig struct permite personalizar o comportamento do 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 Descrição
FoundryLocalManager::create(config) Criar um novo gerente com um FoundryLocalConfig.
manager.catalog().get_models().await Listar todos os modelos disponíveis.
manager.catalog().get_model(alias).await Obtenha um modelo por alias.
manager.catalog().get_cached_models().await Listar modelos em cache local.
manager.catalog().get_loaded_models().await Liste os modelos carregados no momento.
model.download(callback).await Baixe o modelo (ignora se armazenado em cache).
model.load().await Carregue o modelo para inferência.
model.unload().await Descarregue o modelo.

API Nativa de Conclusões de Conversa

Depois de carregar um modelo, crie um cliente de chat com configurações opcionais:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
Método Descrição
client.complete_chat(&messages, tools).await Gere uma resposta de chat completa.
client.complete_streaming_chat(&messages, tools).await Transmitir segmentos de resposta do chat.

Tipos de mensagem: ChatCompletionRequestSystemMessage, , ChatCompletionRequestUserMessage. ChatCompletionRequestMessage

API de Transcrição de Áudio Nativo

Depois de carregar o modelo Whisper, crie um cliente de áudio.

let audio_client = model.create_audio_client();
Método Descrição
audio_client.transcribe(file_path).await Transcreva um arquivo de áudio. Retorna um objeto com um text campo.

Referências:

  • Last updated on