Referentie voor Foundry Local SDK

Met de Foundry Local SDK kunt u AI-functies inbouwen in uw toepassingen die gebruikmaken van lokale AI-modellen via een eenvoudige en intuïtieve API. De SDK abstraheert de complexiteit van het beheren van AI-modellen en biedt een naadloze ervaring voor het integreren van lokale AI-mogelijkheden in uw toepassingen. Deze referentiedocumentatie documenteert SDK-implementaties voor C#, C++, JavaScript, Python en Rust.

Voor de SDK hoeft de lokale Foundry CLI niet te worden geïnstalleerd op de computer van eindgebruikers, zodat u uw toepassingen kunt verzenden zonder extra installatiestappen voor uw gebruikers. Uw toepassingen zijn zelfstandig. De extra voordelen van de Foundry Local SDK zijn:

  • Hardwaredetectie en -optimalisatie: Automatische mogelijkheidsevaluatie voor GPU, NPU en CPU.
  • Execution Provider Management (Windows): Automatische download en registratie van de juiste ONNX Runtime-uitvoeringsproviders (CUDA, Vitis, QNN, OpenVINO, TensorRT) op basis van apparaatmogelijkheden.
  • Metal-ondersteuning via WebGpu (macOS): systeemeigen ondersteuning voor het uitvoeren van modellen op Apple Silicon met geoptimaliseerde prestaties.
  • Modelacquisitie: Naadloze download van de Foundry Model Catalog met versiebeheer, updates en automatisch hardware-geoptimaliseerde modelselectie met valback-ondersteuning.
  • Efficiënte runtime: Voegt ongeveer 20 MB toe aan app-grootte, wordt uitgevoerd op apparaten van mobiele telefoons naar desktops.
  • OpenAI API-compatibiliteit: Eenvoudige integratie met OpenAI-modellen en -hulpprogramma's.
  • Optionele REST-server: Voer Foundry Local uit als een lokale service die toegankelijk is voor andere toepassingen.

Naslaginformatie voor C# SDK

Pakketten installeren

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

De C#-voorbeelden in de GitHub opslagplaats zijn vooraf geconfigureerde projecten. Als u helemaal opnieuw bouwt, leest u de referentie voor de Local SDK van Foundry voor meer informatie over het instellen van uw C#-project met Foundry Local.

configuratie van Project

De voorbeeldopslagplaatsen bevatten een .csproj bestand waarmee platformdetectie automatisch wordt verwerkt. Als u een volledig nieuw project bouwt, gebruikt u deze configuratie als referentie:

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

In de volgende tabel worden de belangrijkste projectinstellingen uitgelegd:

Configuratie Beschrijving
TargetFramework Is bedoeld voor de .NET versie die is vereist voor het voorbeeld.
RuntimeIdentifier Standaard ingesteld op de runtime-id van de huidige SDK, zodat de juiste binaire platformbestanden worden geselecteerd.
Microsoft.AI.Foundry.Local Het Foundry Local SDK-pakket voor Windows, macOS en Linux.

Snelstart

Gebruik dit codefragment om te controleren of de SDK de lokale modelcatalogus kan initialiseren en openen.

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 dit voorbeeld wordt het aantal modellen afgedrukt dat beschikbaar is voor uw hardware.

Voorbeelden

API-referentie

Systeemeigen audiotranscriptie-API

De C#SDK bevat een systeemeigen audioclient voor het transcriberen van audiobestanden op het apparaat met behulp van Whisper-modellen. Hiermee wordt deductie in-proces uitgevoerd zonder dat u de REST-webserver nodig hebt.

Een audioclient ophalen

Nadat u een Whisper-model hebt geladen, verkrijgt u een audioclient:

var audioClient = await model.GetAudioClientAsync();

Audio-transcriptiemethoden

Methode Signature Beschrijving
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> Streamtranscriptieresultaten chunk per segment. Elk segment heeft een Text eigenschap.

AudioClient-instellingen

Vastgoed Typ Beschrijving
Language string ISO 639-1-taalcode (bijvoorbeeld "en"). Verbetert de nauwkeurigheid.
Temperature float Bemonsteringstemperatuur (0,0–1,0). Lagere waarden zijn deterministischer.

Voorbeeld

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

Referenties:

JavaScript SDK Referentie

Pakketten installeren

npm install foundry-local-sdk openai

Snelstart

Gebruik dit codefragment om te controleren of de SDK de lokale modelcatalogus kan initialiseren en openen.

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 dit voorbeeld wordt de lijst met beschikbare modellen voor uw hardware uitgevoerd.

Voorbeelden

API-referentie

Verwijzingen

Python SDK Referentie

Pakketten installeren

pip install foundry-local-sdk openai

Snelstart

Gebruik dit codefragment om te controleren of de SDK de lokale modelcatalogus kan initialiseren en openen.

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 dit voorbeeld wordt het aantal modellen afgedrukt dat beschikbaar is voor uw hardware.

Voorbeelden

Configuratie

Met Configuration de klasse kunt u het SDK-gedrag aanpassen:

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"},
)
Kenmerk Typ Beschrijving
app_name str Naam van uw toepassing.
log_level str Logboekregistratieniveau (bijvoorbeeld "info", "debug").
model_cache_dir str Map voor modellen in cache.
web dict Webserviceconfiguratie met urls sleutel.

Kern-API

Methode Beschrijving
FoundryLocalManager.initialize(config) Initialiseer de singleton manager met een Configuration.
FoundryLocalManager.instance Verkrijg toegang tot het geïnitialiseerde managerexemplaar.
manager.catalog.list_models() Geef alle beschikbare modellen in de catalogus weer.
manager.catalog.get_model(alias) Een model ophalen via een alias.
manager.catalog.get_cached_models() Geef modellen weer in de lokale cache.
manager.catalog.get_loaded_models() Lijst met modellen die momenteel zijn geladen.
model.download(progress_callback) Download het model (slaat over als het in de cache is opgeslagen).
model.load() Laad het model voor inferentie.
model.unload() Laad het model uit.
model.is_cached Controleer of het model lokaal in de cache is opgeslagen.
model.is_loaded Controleer of het model is geladen.

API voor Native Chat-voltooieningen

Nadat u een model hebt geladen, haalt u een chatclient op:

client = model.get_chat_client()
Methode Beschrijving
client.complete_chat(messages) Genereer een volledig chatantwoord.
client.complete_streaming_chat(messages) Chatantwoordsegmenten streamen.

Systeemeigen audiotranscriptie-API

Nadat u een Whisper-model hebt geladen, verkrijgt u een audioclient:

audio_client = model.get_audio_client()
Methode Beschrijving
audio_client.transcribe(file_path) Een audiobestand transcriberen. Retourneert een object met een text eigenschap.

Referenties:

Referentie Rust-SDK

Pakketten installeren

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

Snelstart

Gebruik dit codefragment om te controleren of de SDK de lokale modelcatalogus kan initialiseren en openen.

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 dit voorbeeld wordt het aantal modellen afgedrukt dat beschikbaar is voor uw hardware.

Voorbeelden

Configuratie

Met de FoundryLocalConfig struct kunt u het SDK-gedrag aanpassen:

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

Kern-API

Methode Beschrijving
FoundryLocalManager::create(config) Maak een nieuwe manager met een FoundryLocalConfig.
manager.catalog().get_models().await Geef alle beschikbare modellen weer.
manager.catalog().get_model(alias).await Een model ophalen via een alias.
manager.catalog().get_cached_models().await Geef modellen weer in de lokale cache.
manager.catalog().get_loaded_models().await Lijst met modellen die momenteel zijn geladen.
model.download(callback).await Download het model (slaat over als het in de cache is opgeslagen).
model.load().await Laad het model voor inferentie.
model.unload().await Laad het model uit.

API voor Native Chat-voltooieningen

Nadat u een model hebt geladen, maakt u een chatclient met optionele instellingen:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
Methode Beschrijving
client.complete_chat(&messages, tools).await Genereer een volledig chatantwoord.
client.complete_streaming_chat(&messages, tools).await Chatantwoordsegmenten streamen.

Berichttypen: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage, ChatCompletionRequestMessage.

Systeemeigen audiotranscriptie-API

Nadat u een Whisper-model hebt geladen, maakt u een audioclient:

let audio_client = model.create_audio_client();
Methode Beschrijving
audio_client.transcribe(file_path).await Een audiobestand transcriberen. Retourneert een object met een text veld.

Referenties:

C++ SDK-naslagwerk

Prerequisites

De C++ SDK biedt een wrapper met alleen headers voor de systeemeigen Foundry Local-runtime. Uw geïmplementeerde toepassing vereist geen lokale CLI van Foundry of een .NET runtime.

Kloon het systeemeigen chatvoorbeeld om te beginnen met een geconfigureerd CMake-project:

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

Voor de C++-voorbeelden is het volgende vereist:

  • CMake 3.20 of hoger.
  • Een C++20-compiler.
  • Installeer de NuGet CLI op uw PATH.

Configureer en bouw het voorbeeld:

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

Tijdens de configuratie herstelt het voorbeeld versie 2.2.1 van het Microsoft.AI.Foundry.Local.Runtime NuGet-pakket in build/_packages. Het pakket bevat de C++-headers en systeemeigen bibliotheken voor Windows, Linux en macOS. U hebt geen afzonderlijk WinML-pakket nodig.

De CMake-configuratie selecteert de runtime-assets voor uw besturingssysteem en architectuur en kopieert de vereiste systeemeigen bibliotheken naast het uitvoerbare bestand. Voer in macOS en Linux het uitvoerbare bestand uit vanuit build. Voer op Windows het .exe bestand uit vanuit build.

Selecteer systeemeigen assets die overeenkomen met het besturingssysteem en de architectuur van uw toepassing:

besturingssysteem Architecture Runtime identifier (RID)
Windows x64 ofwel ARM64 win-x64 of win-arm64
Linux x64 of ARM64 linux-x64 of linux-arm64
macOS Apple silicon (ARM64) osx-arm64

toevoegen build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include naar het include-pad van uw compiler. Koppel de systeemeigen bibliotheek vanuit het package's build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native directory:

  • foundry_local.libop Windows.
  • libfoundry_local.so in Linux.
  • libfoundry_local.dylib op macOS.

Plaats de overeenkomende systeemeigen runtime- en afhankelijkheidsbibliotheken naast uw uitvoerbare bestand of in het zoekpad van de bibliotheek van het platform. Bewaar de herstelde pakketversies bij elkaar. Meng geen headers en systeemeigen bibliotheken uit verschillende versies.

Snelstart

Vervang het main.cpp van het voorbeeld door de volgende code om de SDK te initialiseren en de modellen in de catalogus te tellen:

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

Het voorbeeld drukt Models available: af, gevolgd door het aantal modellen van de catalogus. Er wordt geen model gedownload of geladen. Houd de manager beschikbaar terwijl u catalogus-, model- of metagegevensobjecten gebruikt die ermee zijn verkregen.

Naslaginformatie: C++-wrapperdeclaraties voor Configuration, Manageren Catalog.

Kern-API

De wrapper maakt gebruik van resource acquisition is initialization (RAII) om native handles vrij te geven wanneer objecten het bereik verlaten.

API Beschrijving
Manager{Configuration("app-name")} Initialiseer een manager met een toepassingsnaam.
manager.GetCatalog() Haal de modelcatalogus op.
catalog.GetModels() Geef de modellen in de catalogus weer.
catalog.GetModel(alias) Zoek een model op aan de hand van een alias. Controleer de geretourneerde aanwijzer voordat u deze gebruikt.
model->Download() Download een model naar de lokale cache.
model->Load() Laad een model voor deductie.
model->Unload() Een model uit het geheugen verwijderen.
ChatSession::ProcessRequest(request) Voer een chataanvraag uit en retourneer een antwoord.

API-verwijzing en -voorbeelden

Gebruik de openbare header en onderhouden voorbeelden voor de volledige API- en inference-workflows:

  • Laatst bijgewerkt om