Referência do SDK Local do Foundry

O SDK Local do Foundry permite que você incorpore recursos de IA em seus aplicativos que usam 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#, 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 modelos: download direto do Catálogo de Modelos da Foundry com controle de versões, atualizações e seleção automática de modelos otimizados para o hardware, com suporte a alternativas.
  • Tempo de execução eficiente: adiciona aproximadamente 20 MB ao tamanho do aplicativo e funciona em dispositivos que vão desde celulares até computadores.
  • 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

dotnet add package Microsoft.AI.Foundry.Local
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.19041.0</TargetFramework>
    <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>

  <ItemGroup>
    <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 Tem como destino a versão .NET exigida pelo exemplo.
RuntimeIdentifier O valor padrão é o identificador de tempo de execução do SDK atual, garantindo que os binários corretos para a plataforma sejam selecionados.
Microsoft.AI.Foundry.Local O pacote do SDK Local do Foundry para Windows, macOS e Linux.

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

npm install foundry-local-sdk 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

pip install foundry-local-sdk 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) Inicialize 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 (pula esta etapa se estiver 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 blocos de respostas do 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

cargo add foundry-local-sdk
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 (pula esta etapa se estiver 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 blocos de respostas 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:

Referência do SDK do C++

Prerequisites

O SDK do C++ fornece um wrapper somente de cabeçalho sobre o runtime nativo do Foundry Local. Seu aplicativo implantado não requer a CLI Local do Foundry ou um runtime .NET.

Clone o exemplo de chat nativo para começar com um projeto do CMake configurado:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/cpp/foundry-local/native-chat-completions

Os exemplos do C++ exigem:

Configure e compile o exemplo:

cmake -S . -B build
cmake --build build --config Release

Durante a configuração, o exemplo restaura a versão 2.2.1 do Microsoft.AI.Foundry.Local.Runtime pacote NuGet para build/_packages. O pacote contém os cabeçalhos C++ e bibliotecas nativas para Windows, Linux e macOS. Você não precisa de um pacote WinML separado.

A configuração do CMake seleciona os ativos de runtime para seu sistema operacional e arquitetura e copia as bibliotecas nativas necessárias ao lado do executável. No macOS e no Linux, execute o executável a partir de build. Em Windows, execute o .exe arquivo de build.

Selecione ativos nativos que correspondam ao sistema operacional e à arquitetura do aplicativo:

Sistema operacional Architecture Identificador de runtime (RID)
Windows x64 ou ARM64 win-x64 ou win-arm64
Linux x64 ou ARM64 linux-x64 ou linux-arm64
macOS Apple Silicon (ARM64) osx-arm64

Adicione Adicione build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include ao caminho de inclusão do compilador. Vincular a biblioteca nativa do pacote de build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native diretório:

  • foundry_local.libno Windows.
  • libfoundry_local.so no Linux.
  • libfoundry_local.dylib no macOS.

Coloque as bibliotecas de dependência e runtime nativo correspondentes ao lado do executável ou no caminho de pesquisa da biblioteca da plataforma. Mantenha juntas as versões dos pacotes restaurados. Não misture cabeçalhos e bibliotecas nativas de versões diferentes.

Início Rápido

Substitua o main.cpp do exemplo pelo seguinte código para inicializar o SDK e contar os modelos no catálogo:

#include <foundry_local/foundry_local_cpp.h>

#include <iostream>

using namespace foundry_local;

int main() {
    try {
        Manager manager{Configuration("app-name")};
        auto models = manager.GetCatalog().GetModels();
        std::cout << "Models available: " << models.size() << "\n";
    } catch (const Error& error) {
        std::cerr << "Foundry Local error [" << error.Code()
                  << "]: " << error.what() << "\n";
        return 1;
    }
    return 0;
}

O exemplo imprime Models available: seguido pela contagem de modelos do catálogo. Ele não baixa nem carrega um modelo. Mantenha o gerente em execução enquanto você usa objetos de catálogo, modelo ou metadados obtidos dele.

Referência: declarações de wrapper C++ para Configuration, Managere Catalog.

API principal

O wrapper usa aquisição de recurso na inicialização (RAII) para liberar identificadores nativos quando os objetos saem do escopo.

API Descrição
Manager{Configuration("app-name")} Inicialize um gerente com um nome de aplicativo.
manager.GetCatalog() Obtenha o catálogo de modelos.
catalog.GetModels() Liste os modelos no catálogo.
catalog.GetModel(alias) Procure um modelo por alias. Verifique o ponteiro retornado antes de usá-lo.
model->Download() Baixe um modelo para o cache local.
model->Load() Carregue um modelo para inferência.
model->Unload() Descarregue um modelo da memória.
ChatSession::ProcessRequest(request) Execute uma solicitação de chat e retorne uma resposta.

Referência da API e exemplos

Use o cabeçalho público e os exemplos mantidos para os fluxos de trabalho completos de API e inferência:

  • Última atualização em