Foundry Local SDK-Referenz

Mit dem Foundry Local SDK können Sie KI-Funktionen in Ihre Anwendungen integrieren, die lokale KI-Modelle über eine einfache und intuitive API nutzen. Das SDK abstrahiert die Komplexität der Verwaltung von KI-Modellen und bietet eine nahtlose Erfahrung für die Integration lokaler KI-Funktionen in Ihre Anwendungen. Diese Referenz dokumentiert SDK-Implementierungen für C#, C++, JavaScript, Python und Rust.

Das SDK erfordert nicht, dass die Foundry Local CLI auf dem Computer der Endbenutzer installiert wird, sodass Sie Ihre Anwendungen ohne zusätzliche Einrichtungsschritte für Ihre Benutzer versenden können – Ihre Anwendungen sind eigenständig. Zu den zusätzlichen Vorteilen des Foundry Local SDK gehören:

  • Hardwareerkennung und -optimierung: Automatische Funktionsbewertung für GPU, NPU und CPU.
  • Execution Provider Management (Windows): Automatisches Herunterladen und Registrieren geeigneter ONNX-Runtime-Ausführungsanbieter (CUDA, Vitis, QNN, OpenVINO, TensorRT) basierend auf Gerätefunktionen.
  • Metal-Unterstützung über WebGpu (macOS): Native Unterstützung für das Ausführen von Modellen auf Apple Silicon mit optimierter Leistung.
  • Modellerwerb: Nahtloses Herunterladen aus dem Foundry Model Catalog mit Versionsverwaltung, Updates und automatisch hardwareoptimierter Modellauswahl mit Fallbackunterstützung.
  • Effiziente Laufzeit: Fügt ca. 20 MB zu App-Größe hinzu, wird auf Geräten von Mobiltelefonen zu Desktops ausgeführt.
  • OpenAI-API-Kompatibilität: Einfache Integration in OpenAI-Modelle und -Tools.
  • Optionaler REST-Server: Betreiben Sie Foundry Local als lokalen Dienst, der für andere Anwendungen zugänglich ist.

C# SDK-Referenz

Pakete installieren

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

Die C#-Beispiele im GitHub Repository sind vorkonfigurierte Projekte. Wenn Sie von Grund auf neu erstellen, sollten Sie die Referenz zum Foundry Local SDK lesen, um weitere Details zum Einrichten Ihres C#-Projekts mit Foundry Local zu erhalten.

Projektkonfiguration

Die Beispielrepositorys enthalten eine .csproj Datei, die die Plattformerkennung automatisch verarbeitet. Wenn Sie ein Projekt von Grund auf neu erstellen, verwenden Sie diese Konfiguration als Referenz:

<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 der folgenden Tabelle werden die wichtigsten Projekteinstellungen erläutert:

Setting Beschreibung
TargetFramework Zielt auf die .NET Version ab, die für das Beispiel erforderlich ist.
RuntimeIdentifier Standardmäßig wird der Laufzeitbezeichner der aktuellen SDK verwendet, um sicherzustellen, dass die richtigen Binärdateien für die Plattform ausgewählt werden.
Microsoft.AI.Foundry.Local Das Foundry Local SDK-Paket für Windows, macOS und Linux.

Schnellstart

Verwenden Sie diesen Codeausschnitt, um zu überprüfen, ob das SDK den lokalen Modellkatalog initialisieren und darauf zugreifen kann.

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 diesem Beispiel wird die Anzahl der verfügbaren Modelle für Ihre Hardware gedruckt.

Beispiele

API-Referenz

Native Audiotranskription-API

Das C#-SDK enthält einen systemeigenen Audioclient zum Transkribieren von Audiodateien auf dem Gerät mithilfe von Flüstermodellen. Dies führt In-Process-Inferenzen durch, ohne dass ein REST-Webserver benötigt wird.

Audio-Client holen

Nachdem ein Whisper-Modell geladen wurde, rufen Sie einen Audioclient ab:

var audioClient = await model.GetAudioClientAsync();

Audiotranskriptionsmethoden

Methode Signature Beschreibung
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> Streamt Transkriptionsergebnisse Stück für Stück. Jeder Block verfügt über eine Text Eigenschaft.

AudioClient-Einstellungen

Eigentum Typ Beschreibung
Language string ISO 639-1-Sprachcode (z. B "en". ). Verbessert die Genauigkeit.
Temperature float Probenahmetemperatur (0,0–1,0). Niedrigere Werte sind deterministischer.

Beispiel

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

Referenzen:

JavaScript SDK-Referenz

Pakete installieren

npm install foundry-local-sdk openai

Schnellstart

Verwenden Sie diesen Codeausschnitt, um zu überprüfen, ob das SDK den lokalen Modellkatalog initialisieren und darauf zugreifen kann.

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 diesem Beispiel wird die Liste der verfügbaren Modelle für Ihre Hardware ausgegeben.

Beispiele

API-Referenz

Referenzen

Python SDK-Referenz

Pakete installieren

pip install foundry-local-sdk openai

Schnellstart

Verwenden Sie diesen Codeausschnitt, um zu überprüfen, ob das SDK den lokalen Modellkatalog initialisieren und darauf zugreifen kann.

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 diesem Beispiel wird die Anzahl der verfügbaren Modelle für Ihre Hardware gedruckt.

Beispiele

Konfiguration

Mit der Configuration Klasse können Sie das SDK-Verhalten anpassen:

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"},
)
Parameter Typ Beschreibung
app_name str Name Ihrer Anwendung.
log_level str Protokollierungsebene (z. B. "info", "debug").
model_cache_dir str Verzeichnis für zwischengespeicherte Modelle.
web dict Webdienstkonfiguration mit urls Schlüssel.

Core-API

Methode Beschreibung
FoundryLocalManager.initialize(config) Initialisieren Sie den Singleton-Manager mit einem Configuration.
FoundryLocalManager.instance Greifen Sie auf die initialisierte Managerinstanz zu.
manager.catalog.list_models() Listet alle verfügbaren Modelle im Katalog auf.
manager.catalog.get_model(alias) Rufen Sie ein Modell nach Alias ab.
manager.catalog.get_cached_models() Modelle im lokalen Cache auflisten.
manager.catalog.get_loaded_models() Momentan geladene Modelle auflisten.
model.download(progress_callback) Laden Sie das Modell herunter (wird übersprungen, wenn zwischengespeichert).
model.load() Laden Sie das Modell für die Ableitung.
model.unload() Entladen Sie das Modell.
model.is_cached Überprüfen Sie, ob das Modell lokal zwischengespeichert wird.
model.is_loaded Überprüfen Sie, ob das Modell geladen wird.

API für Native-Chat-Vervollständigungen

Rufen Sie nach dem Laden eines Modells einen Chatclient ab:

client = model.get_chat_client()
Methode Beschreibung
client.complete_chat(messages) Generieren Sie eine vollständige Chatantwort.
client.complete_streaming_chat(messages) Chat-Antwortblöcke im Stream.

Native Audiotranskription-API

Nachdem ein Whisper-Modell geladen wurde, rufen Sie einen Audioclient ab:

audio_client = model.get_audio_client()
Methode Beschreibung
audio_client.transcribe(file_path) Transkribieren sie eine Audiodatei. Gibt ein Objekt mit einer text Eigenschaft zurück.

Referenzen:

Rust SDK-Referenz

Pakete installieren

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

Schnellstart

Verwenden Sie diesen Codeausschnitt, um zu überprüfen, ob das SDK den lokalen Modellkatalog initialisieren und darauf zugreifen kann.

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 diesem Beispiel wird die Anzahl der verfügbaren Modelle für Ihre Hardware gedruckt.

Beispiele

Konfiguration

Mit FoundryLocalConfig der Struktur können Sie das SDK-Verhalten anpassen:

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

Core-API

Methode Beschreibung
FoundryLocalManager::create(config) Erstellen Sie einen neuen Manager mit einem FoundryLocalConfig.
manager.catalog().get_models().await Listet alle verfügbaren Modelle auf.
manager.catalog().get_model(alias).await Rufen Sie ein Modell nach Alias ab.
manager.catalog().get_cached_models().await Modelle im lokalen Cache auflisten.
manager.catalog().get_loaded_models().await Momentan geladene Modelle auflisten.
model.download(callback).await Laden Sie das Modell herunter (wird übersprungen, wenn zwischengespeichert).
model.load().await Laden Sie das Modell für die Ableitung.
model.unload().await Entladen Sie das Modell.

API für Native-Chat-Vervollständigungen

Erstellen Sie nach dem Laden eines Modells einen Chatclient mit optionalen Einstellungen:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
Methode Beschreibung
client.complete_chat(&messages, tools).await Generieren Sie eine vollständige Chatantwort.
client.complete_streaming_chat(&messages, tools).await Chat-Antwortblöcke im Stream.

Nachrichtentypen: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage, ChatCompletionRequestMessage.

Native Audiotranskription-API

Erstellen Sie nach dem Laden eines Flüstermodells einen Audioclient:

let audio_client = model.create_audio_client();
Methode Beschreibung
audio_client.transcribe(file_path).await Transkribieren sie eine Audiodatei. Gibt ein Objekt mit einem text Feld zurück.

Referenzen:

C++-SDK-Referenz

Voraussetzungen

Das C++-SDK stellt einen Header-only-Wrapper über die native Foundry-Local-Laufzeit bereit. Ihre bereitgestellte Anwendung erfordert weder die Foundry Local CLI noch eine .NET-Laufzeit.

Klonen Sie das systemeigene Chatbeispiel, um mit einem konfigurierten CMake-Projekt zu beginnen:

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

Für die C++-Beispiele ist Folgendes erforderlich:

  • CMake 3.20 oder höher.
  • Ein C++20-Compiler.
  • Die NuGet-CLI auf Ihrem PATH.

Konfigurieren und erstellen Sie das Beispiel:

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

Während der Konfiguration stellt das Beispiel die Version 2.2.1 des Microsoft.AI.Foundry.Local.Runtime NuGet-Pakets in build/_packages wieder her. Das Paket enthält die C++-Header und systemeigene Bibliotheken für Windows, Linux und macOS. Sie benötigen kein separates WinML-Paket.

Die CMake-Konfiguration wählt die Laufzeitressourcen für Ihr Betriebssystem und die Architektur aus und kopiert die erforderlichen nativen Bibliotheken neben der ausführbaren Datei. Führen Sie unter macOS und Linux die ausführbare Datei aus build aus. Führen Sie unter Windows die .exe-Datei aus build aus.

Wählen Sie systemeigene Ressourcen aus, die dem Betriebssystem und der Architektur Ihrer Anwendung entsprechen:

Betriebssystem Architecture Laufzeit-ID (RID)
Windows x64 oder ARM64 win-x64 oder win-arm64
Linux x64 oder ARM64 linux-x64 oder linux-arm64
macOS Apple Silicon (ARM64) osx-arm64

Fügen Sie hinzu. build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include zum Include-Pfad Ihres Compilers. Native Bibliothek aus dem Paket verlinken build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native Verzeichnis:

  • foundry_local.libauf Windows.
  • libfoundry_local.so auf Linux.
  • libfoundry_local.dylib unter macOS.

Stellen Sie die übereinstimmenden nativen Laufzeit- und Abhängigkeitsbibliotheken neben Ihrer ausführbaren Datei oder im Bibliothekssuchpfad der Plattform bereit. Halten Sie die wiederhergestellten Paketversionen zusammen. Kombinieren Sie keine Header und systemeigenen Bibliotheken aus verschiedenen Versionen.

Schnellstart

Ersetzen Sie das main.cpp des Beispiels durch den folgenden Code, um das SDK zu initialisieren und die Modelle im Katalog zu zählen:

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

Das Beispiel druckt Models available: , gefolgt von der Modellanzahl des Katalogs. Es wird kein Modell heruntergeladen oder geladen. Halten Sie den Manager lebendig, während Sie Katalog-, Modell- oder Metadatenobjekte verwenden, die daraus abgerufen wurden.

Referenz: C++-Wrapperdeklarationen für Configuration, Managerund Catalog.

Core-API

Der Wrapper nutzt „Resource Acquisition Is Initialization“ (RAII), um native Handles freizugeben, wenn Objekte den Bereich verlassen.

API Beschreibung
Manager{Configuration("app-name")} Initialisieren Sie einen Manager mit einem Anwendungsnamen.
manager.GetCatalog() Rufen Sie den Modellkatalog ab.
catalog.GetModels() Modelle im Katalog auflisten
catalog.GetModel(alias) Suchen Sie ein Modell anhand eines Alias. Überprüfen Sie den zurückgegebenen Zeiger, bevor Sie ihn verwenden.
model->Download() Laden Sie ein Modell in den lokalen Cache herunter.
model->Load() Laden sie ein Modell für die Ableitung.
model->Unload() Entladen Sie ein Modell aus dem Speicher.
ChatSession::ProcessRequest(request) Führen Sie eine Chatanfrage aus, und geben Sie eine Antwort zurück.

API-Referenz und Beispiele

Nutzen Sie den öffentlichen Header und die gepflegten Beispiele für die vollständige API und die Inferenz-Workflows:

  • Zuletzt aktualisiert um