Freigeben über

Foundry Local SDK-Referenz

Mit dem Foundry Local SDK können Sie KI-Features in Ihren Anwendungen versenden, die lokale KI-Modelle über eine einfache und intuitive API verwenden können. 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#, 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

Wenn Sie Windows entwickeln oder versenden, wählen Sie die Registerkarte Windows aus. Das Windows-Paket ist in die Windows ML Laufzeit integriert. Es bietet den gleichen API-Oberflächenbereich mit einer breiteren Hardwarebeschleunigung.

dotnet add package Microsoft.AI.Foundry.Local.WinML
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.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>

In der folgenden Tabelle werden die wichtigsten Projekteinstellungen erläutert:

Setting Beschreibung
TargetFramework Auf Windows zielt auf net9.0-windows10.0.26100 für die WinML-Hardwarebeschleunigung ab. Auf anderen Plattformen wird auf net9.0 abgezielt.
WindowsAppSDKSelfContained Legen Sie auf false fest, um die vom System installierte Windows App SDK zu verwenden, anstatt sie zu bündeln.
WindowsPackageType Stellen Sie None ein, um als unverpackte Desktop-App zu erstellen (keine MSIX-Paketierung).
EnableCoreMrtTooling Setzen Sie false, um das MRT-Core-Ressourcentooling zu deaktivieren, das für Konsolen-Apps nicht benötigt wird.
RuntimeIdentifier Standardmäßig wird der Laufzeitbezeichner des aktuellen SDKs verwendet, um sicherzustellen, dass die richtigen Plattform-Binärdateien ausgewählt werden.
Microsoft.AI.Foundry.Local.WinML Windows-only-Paket, das WinML für die Hardwarebeschleunigung und die automatische Ausführungsanbieterverwaltung verwendet.
Microsoft.AI.Foundry.Local Plattformübergreifendes Paket für macOS, Linux und Windows ohne WinML.
Microsoft.ML.OnnxRuntime.Gpu / OnnxRuntimeGenAI.Cuda Linux GPU-Supportpakete für CUDA-fähige Hardware.

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

Wenn Sie Windows entwickeln oder versenden, wählen Sie die Registerkarte Windows aus. Das Windows-Paket ist in die Windows ML Laufzeit integriert. Es bietet den gleichen API-Oberflächenbereich mit einer breiteren Hardwarebeschleunigung.

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

Wenn Sie Windows entwickeln oder versenden, wählen Sie die Registerkarte Windows aus. Das Windows-Paket ist in die Windows ML Laufzeit integriert. Es bietet den gleichen API-Oberflächenbereich mit einer breiteren Hardwarebeschleunigung.

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

Wenn Sie Windows entwickeln oder versenden, wählen Sie die Registerkarte Windows aus. Das Windows-Paket ist in die Windows ML Laufzeit integriert. Es bietet den gleichen API-Oberflächenbereich mit einer breiteren Hardwarebeschleunigung.

cargo add foundry-local-sdk --features winml
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 Segmente von Stream-Chatantworten.

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:

  • Last updated on