Referência do SDK local do Foundry

O Foundry Local SDK permite-lhe disponibilizar funcionalidades de IA nas suas aplicações que utilizam modelos locais de IA através de uma API simples e intuitiva. O SDK abstrai as complexidades da gestão de modelos de IA e proporciona uma experiência fluida para integrar capacidades locais de IA nas suas aplicações. Esta referência documenta implementações de SDK para C#, C++, JavaScript, Python e Rust.

O SDK não exige que a CLI Local do Foundry esteja instalada na máquina do utilizador final, permitindo-lhe enviar as suas aplicações sem passos adicionais de configuração para os seus utilizadores – as suas aplicações são autónomas. Os benefícios extra do Foundry Local SDK incluem:

  • Deteção e otimização por hardware: Avaliação automática de capacidades para GPU, NPU e CPU.
  • Gestão de fornecedores de execução (Windows): Download e registo automáticos dos fornecedores de execução ONNX Runtime apropriados (CUDA, Vitis, QNN, OpenVINO, TensorRT) com base nas capacidades do dispositivo.
  • Suporte a Metal via WebGpu (macOS): Suporte nativo para execução de modelos em Apple Silicon com desempenho otimizado.
  • Aquisição de modelos: Download contínuo do Catálogo de Modelos Foundry com versionamento, atualizações e seleção automática de modelos otimizada por hardware com suporte a backup.
  • Tempo de execução eficiente: Adiciona aproximadamente 20 MB ao tamanho da aplicação, funciona em dispositivos desde telemóveis a desktops.
  • Compatibilidade com APIs OpenAI: Integração fácil com modelos e ferramentas OpenAI.
  • Servidor REST opcional: Executar o Foundry Local como um serviço local acessível por outras aplicações.

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 está a construir do zero, deve ler a referência do Foundry Local SDK para mais detalhes sobre como configurar o seu projeto C# com o Foundry Local.

Configuração do Project

Os repositórios de exemplos incluem um .csproj ficheiro que gere automaticamente a deteção de plataformas. Se está a construir um projeto do zero, use esta 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 seguinte explica as definições chave do projeto:

Configuração Descrição
TargetFramework Aponta para a versão .NET exigida pelo exemplo.
RuntimeIdentifier Por defeito o identificador de runtime do SDK atual, garantindo que os binários corretos da plataforma são selecionados.
Microsoft.AI.Foundry.Local O pacote Foundry Local SDK para Windows, macOS e Linux.

Início Rápido

Use este excerto para verificar se o SDK pode inicializar-se e aceder ao catálogo local de modelos.

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 o seu hardware.

Samples

  • Para aplicações de exemplo que demonstram como usar o Foundry Local C# SDK, consulte o repositório GitHub Foundry Local C# SDK.

Referência da API

API nativa de transcrição áudio

O SDK C# inclui um cliente de áudio nativo para transcrever ficheiros de áudio no dispositivo usando modelos Whisper. Isto executa inferência em processo sem necessidade do servidor web REST.

Obtenha 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 áudio

Método Signature Descrição
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> Os resultados de transcrição dos fluxos são apresentados em partes. Cada bloco tem uma propriedade Text.

Definições do AudioClient

Propriedade Tipo Descrição
Language string Código da linguagem ISO 639-1 (por exemplo, "en"). Melhora a precisão.
Temperature float Temperatura de amostragem (0,0–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 JavaScript

Instalar pacotes

npm install foundry-local-sdk openai

Início Rápido

Use este excerto para verificar se o SDK pode inicializar-se e aceder ao catálogo local de modelos.

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 apresenta a lista de modelos disponíveis para o seu hardware.

Samples

Referência da API

Referências

Referência do SDK Python

Instalar pacotes

pip install foundry-local-sdk openai

Início Rápido

Use este excerto para verificar se o SDK pode inicializar-se e aceder ao catálogo local de modelos.

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 o seu hardware.

Samples

  • Para aplicações de exemplo que demonstrem como usar o SDK de Python Local da Foundry, consulte o repositório GitHub Foundry Local SDK Samples.

Configuração

A Configuration classe permite-lhe 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 candidatura.
log_level str Nível de registo (por exemplo, "info", "debug").
model_cache_dir str Diretório para modelos em cache.
web dict Configuração do serviço web com chave urls.

API principal

Método Descrição
FoundryLocalManager.initialize(config) Inicialize o gestor singleton com um Configuration.
FoundryLocalManager.instance Aceda à instância de gestor inicializada.
manager.catalog.list_models() Liste todos os modelos disponíveis no catálogo.
manager.catalog.get_model(alias) Arranja um modelo por pseudónimo.
manager.catalog.get_cached_models() Lista os modelos na cache local.
manager.catalog.get_loaded_models() Lista de modelos atualmente carregados.
model.download(progress_callback) Descarrega o modelo (salta se estiver em cache).
model.load() Carregue o modelo para inferência.
model.unload() Descarrega o modelo.
model.is_cached Verifica se o modelo está armazenado em cache localmente.
model.is_loaded Verifica se o modelo está carregado.

API Nativo de Conclusões de Chat

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

client = model.get_chat_client()
Método Descrição
client.complete_chat(messages) Crie uma resposta completa por chat.
client.complete_streaming_chat(messages) Stream em blocos de resposta no chat.

API nativa de transcrição áudio

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) Transcreve um ficheiro áudio. Devolve um objeto com uma text propriedade.

Referências:

Referência ao 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 excerto para verificar se o SDK pode inicializar-se e aceder ao catálogo local de modelos.

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 o seu hardware.

Samples

  • Para exemplos de aplicações que demonstram como usar o Foundry Local Rust SDK, consulte o repositório GitHub Foundry Local SDKs.

Configuração

A FoundryLocalConfig estrutura 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) Crie um novo gestor com um FoundryLocalConfig.
manager.catalog().get_models().await Liste todos os modelos disponíveis.
manager.catalog().get_model(alias).await Arranja um modelo por pseudónimo.
manager.catalog().get_cached_models().await Lista os modelos na cache local.
manager.catalog().get_loaded_models().await Lista de modelos atualmente carregados.
model.download(callback).await Descarrega o modelo (salta se estiver em cache).
model.load().await Carregue o modelo para inferência.
model.unload().await Descarrega o modelo.

API Nativo de Conclusões de Chat

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

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
Método Descrição
client.complete_chat(&messages, tools).await Crie uma resposta completa por chat.
client.complete_streaming_chat(&messages, tools).await Stream em blocos de resposta no chat.

Tipos de mensagem: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage, ChatCompletionRequestMessage.

API nativa de transcrição áudio

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

let audio_client = model.create_audio_client();
Método Descrição
audio_client.transcribe(file_path).await Transcreve um ficheiro áudio. Devolve um objeto com um text campo.

Referências:

Referência do SDK C++

Prerequisites

O SDK C++ fornece um encapsulamento só com cabeçalhos sobre o runtime nativo Foundry Local. A tua aplicação implementada não requer a CLI local do Foundry nem um runtime .NET.

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

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

Os exemplos em C++ requerem:

Configure e construa o exemplo:

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

Durante a configuração, o sample 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 as bibliotecas nativas para Windows, Linux e macOS. Não precisas de um pacote WinML separado.

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

Selecione ativos nativos que correspondam ao sistema operativo e arquitetura da sua aplicação:

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

Adicionar build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include para o caminho de inclusão do seu compilador. Liga a biblioteca nativa a partir do package's 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.

Distribua as bibliotecas nativas de runtime e dependências correspondentes ao lado do executável ou no caminho de pesquisa da biblioteca da plataforma. Manter juntas as versões restauradas dos pacotes. Não mistures 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 da contagem de modelos do catálogo. Não descarrega nem carrega um modelo. Mantenha o manager ativo enquanto utiliza objetos de catálogo, modelo ou metadados obtidos dele.

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

API principal

O wrapper utiliza aquisição de recursos é inicialização (RAII) para libertar handles nativos quando os objetos saem do escopo.

API Descrição
Manager{Configuration("app-name")} Inicialize um gerenciador com um nome de aplicação.
manager.GetCatalog() Obtenha o Model Catalog.
catalog.GetModels() Liste os modelos no catálogo.
catalog.GetModel(alias) Procura um modelo por alias. Verifica o ponteiro devolvido antes de o usar.
model->Download() Descarregue um modelo para a cache local.
model->Load() Carregue um modelo para inferência.
model->Unload() Descarrega um modelo da memória.
ChatSession::ProcessRequest(request) Faz um pedido de chat e devolve uma resposta.

Referência da API e exemplos

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

  • Última atualização a