Partilhar via

Referência do SDK local do Foundry

O Foundry Local SDK permite-lhe disponibilizar funcionalidades de IA nas suas aplicações capazes de utilizar 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#, 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

Se estiver a desenvolver ou a enviar no Windows, selecione o separador Windows. O pacote Windows integra-se com o runtime Windows ML — fornece a mesma área de superfície da API com uma maior amplitude de aceleração por 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 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.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 seguinte explica as definições chave do projeto:

Configuração Descrição
TargetFramework No Windows, os alvos net9.0-windows10.0.26100 para aceleração de hardware do WinML. Noutras plataformas, os alvos net9.0.
WindowsAppSDKSelfContained Definido para false para usar o SDK de Aplicações Windows instalado pelo sistema em vez de o agrupar.
WindowsPackageType Defina para None para compilar como uma aplicação desktop não empacotada (sem embalagem em MSIX).
EnableCoreMrtTooling Definido para false desativar as ferramentas de recursos do MRT Core, que não são necessárias para aplicações de consola.
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.WinML Pacote exclusivo para Windows que utiliza WinML para aceleração de hardware e gestão automática de fornecedores 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 Linux e hardware compatível com CUDA.

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

Se estiver a desenvolver ou a enviar no Windows, selecione o separador Windows. O pacote Windows integra-se com o runtime Windows ML — fornece a mesma área de superfície da API com uma maior amplitude de aceleração por hardware.

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

Se estiver a desenvolver ou a enviar no Windows, selecione o separador Windows. O pacote Windows integra-se com o runtime Windows ML — fornece a mesma área de superfície da API com uma maior amplitude de aceleração por hardware.

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

Se estiver a desenvolver ou a enviar no Windows, selecione o separador Windows. O pacote Windows integra-se com o runtime Windows ML — fornece a mesma área de superfície da API com uma maior amplitude de aceleração por hardware.

cargo add foundry-local-sdk --features winml
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:

  • Last updated on