Informazioni di riferimento su Foundry Local SDK

Informazioni di riferimento su C# SDK

Installare i pacchetti

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

Gli esempi C# nel repository GitHub sono progetti preconfigurati. Se stai creando da zero, dovresti leggere il riferimento del Foundry Local SDK per ulteriori dettagli su come configurare il tuo progetto C# con Foundry Local.

Configurazione del progetto

I repository di esempio includono un .csproj file che gestisce automaticamente il rilevamento della piattaforma. Se si compila un progetto da zero, usare questa configurazione come riferimento:

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

La tabella seguente illustra le impostazioni principali del progetto:

Avvio rapido

Usare questo frammento di codice per verificare che l'SDK possa inizializzare e accedere al catalogo del modello locale.

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

In questo esempio viene stampato il numero di modelli disponibili per l'hardware.

Esempi

• Per le applicazioni di esempio che illustrano come usare l'SDK C# locale di Foundry, vedere Foundry Local C# SDK Samples GitHub repository.

Informazioni di riferimento sulle API

• Per altre informazioni su Foundry Local C# SDK, vedere Foundry Local C# SDK API Reference (Informazioni di riferimento sull'API C# locale di Foundry).

API di trascrizione audio nativa

C# SDK include un client audio nativo per la trascrizione di file audio su dispositivo tramite i modelli Whisper. L'inferenza viene eseguita in-process senza bisogno del server REST.

Ottenere un client audio

Dopo aver caricato un modello Whisper, ottenere un client audio:

var audioClient = await model.GetAudioClientAsync();

Metodi di trascrizione audio

Impostazioni di AudioClient

Esempio

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

Riferimenti:

• Trascrivere file audio con Foundry Local

Informazioni di riferimento su JavaScript SDK

Installare i pacchetti

npm install foundry-local-sdk openai

Avvio rapido

Usare questo frammento di codice per verificare che l'SDK possa inizializzare e accedere al catalogo del modello locale.

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

In questo esempio viene restituito l'elenco dei modelli disponibili per l'hardware.

Esempi

• Per applicazioni di esempio che illustrano come usare il Foundry Local JavaScript SDK, consultare l'archivio GitHub dedicato agli esempi del Foundry Local JavaScript SDK.

Informazioni di riferimento sulle API

• Per altre informazioni su Foundry Local JavaScript SDK, vedere Foundry Local JavaScript SDK API Reference (Informazioni di riferimento sull'API JavaScript SDK locale di Foundry).

References

• Eseguire l'integrazione con gli SDK di inferenza
• Usare l'API di completamento della chat nativa di Foundry

Informazioni di riferimento su Python SDK

Installare i pacchetti

pip install foundry-local-sdk openai

Avvio rapido

Usare questo frammento di codice per verificare che l'SDK possa inizializzare e accedere al catalogo del modello locale.

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

In questo esempio viene stampato il numero di modelli disponibili per l'hardware.

Esempi

• Per applicazioni di esempio che illustrano come usare Foundry Local Python SDK, vedere Foundry Local SDK Samples GitHub repository.

Configurazione

La Configuration classe consente di personalizzare il comportamento dell'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"},
)

API di base

API di completamento della chat nativa

Dopo aver caricato un modello, ottenere un client di chat:

client = model.get_chat_client()

API di trascrizione audio nativa

Dopo aver caricato un modello Whisper, ottenere un client audio:

audio_client = model.get_audio_client()

Riferimenti:

• Trascrivere file audio con Foundry Local
• Usare l'API di completamento della chat nativa di Foundry
• Usare i completamenti della chat tramite il server REST

Informazioni di riferimento su Rust SDK

Installare i pacchetti

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

Avvio rapido

Usare questo frammento di codice per verificare che l'SDK possa inizializzare e accedere al catalogo del modello locale.

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

In questo esempio viene stampato il numero di modelli disponibili per l'hardware.

Esempi

• Per applicazioni di esempio che illustrano come usare Foundry Local Rust SDK, vedere Foundry Local SDK Samples GitHub repository.

Configurazione

Lo FoundryLocalConfig struct consente di personalizzare il comportamento dell'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 di base

API di completamento della chat nativa

Dopo aver caricato un modello, creare un client di chat con impostazioni facoltative:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);

Tipi di messaggio: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage, ChatCompletionRequestMessage.

API di trascrizione audio nativa

Dopo aver caricato un modello Whisper, creare un client audio:

let audio_client = model.create_audio_client();

Riferimenti:

• Trascrivere file audio con Foundry Local
• Usare l'API di completamento della chat nativa di Foundry
• Usare i completamenti della chat tramite il server REST

Riferimento SDK C++

Prerequisites

Il C++ SDK fornisce un wrapper header-only sul runtime nativo Foundry Local. L'applicazione distribuita non richiede la CLI locale di Foundry o un runtime di .NET.

Clonare l'esempio di chat nativa per iniziare con un progetto CMake configurato:

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

Gli esempi C++ richiedono:

• CMake 3.20 o versione successiva.
• Un compilatore C++20.
• L'interfaccia della riga di comando di NuGet in PATH.

Configurare e compilare l'esempio:

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

Durante la configurazione, l'esempio ripristina la versione 2.2.1 del pacchetto NuGet Microsoft.AI.Foundry.Local.Runtime in build/_packages. Il pacchetto contiene gli header C++ e le librerie native per Windows, Linux e macOS. Non è necessario un pacchetto WinML separato.

La configurazione di CMake seleziona gli asset di runtime per il sistema operativo e l'architettura e copia le librerie native necessarie accanto al file eseguibile. In macOS e Linux eseguire il file eseguibile da build. Su Windows, eseguire il file .exe da build.

Selezionare asset nativi corrispondenti al sistema operativo e all'architettura dell'applicazione:

Aggiungere Aggiungi build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include al percorso di inclusione del compilatore. Collegare la libreria nativa del pacchetto build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native cartella:

• foundry_local.libsu Windows.
• libfoundry_local.so su Linux.
• libfoundry_local.dylib su macOS.

Distribuire il runtime nativo e le librerie di dipendenze corrispondenti accanto al file eseguibile o nel percorso di ricerca della libreria della piattaforma. Mantieni insieme le versioni ripristinate dei pacchetti. Non combinare header e librerie native da versioni diverse.

Avvio rapido

Sostituire il main.cpp dell'esempio con il codice seguente per inizializzare l'SDK e contare i modelli nel catalogo:

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

L'esempio stampa Models available: seguito dal numero di modelli del catalogo. Non scarica né carica un modello. Mantenere attivo il gestore durante l'uso di oggetti catalogo, modello o metadati ottenuti da esso.

Riferimento: dichiarazioni wrapper C++ per Configuration, Managere Catalog.

API di base

Il wrapper usa l'inizializzazione all'acquisizione della risorsa (RAII) per rilasciare handle nativi quando gli oggetti escono dall'ambito.

Informazioni di riferimento sulle API ed esempi

Usare l'intestazione pubblica e gli esempi gestiti per i flussi di lavoro completi di API e inferenza:

• Dichiarazioni API C++.
• Esempi locali di Foundry.