Freigeben über

Foundry Local SDK-Referenz

Von Bedeutung

  • Foundry Local ist in der Vorschau verfügbar. Öffentliche Vorschauversionen bieten frühzeitigen Zugriff auf Features, die sich in der aktiven Bereitstellung befinden.
  • Features, Ansätze und Prozesse können sich vor der allgemeinen Verfügbarkeit (General Availability, GA) noch ändern oder eine eingeschränkte Funktionalität aufweisen.

Das Foundry Local SDK vereinfacht die KI-Modellverwaltung in lokalen Umgebungen, indem Steuerebenenvorgänge getrennt von Datenebenen-Ableitungscode bereitgestellt werden. Diese Referenz dokumentiert SDK-Implementierungen für Python, JavaScript, C# und Rust.

Python SDK-Referenz

Installation

Installieren Sie das Python-Paket:

pip install foundry-local-sdk

FoundryLocalManager Klasse

Die FoundryLocalManager Klasse stellt Methoden zum Verwalten von Modellen, Cache und dem lokalen Dienst "Foundry" bereit.

Initialisierung

from foundry_local import FoundryLocalManager

# Initialize and optionally bootstrap with a model
manager = FoundryLocalManager(alias_or_model_id=None, bootstrap=True)
  • alias_or_model_id (optional): Alias oder ID des Modells, das beim Start heruntergeladen und geladen werden soll
  • bootstrap: (Standardmäßig True) Wenn True, startet den Dienst, falls er nicht läuft, und lädt das Modell, wenn es bereitgestellt wird.

Eine Notiz zu Aliasen

Viele in diesem Verweis beschriebene Methoden weisen einen alias_or_model_id Parameter in der Signatur auf. Sie können entweder einen Alias oder eine Modell-ID als Wert an die Methode übergeben. Die Verwendung eines Alias erfolgt wie folgt:

  • Wählen Sie das beste Modell für die verfügbare Hardware aus. Wenn beispielsweise eine Nvidia CUDA GPU verfügbar ist, wählt Foundry Local das CUDA-Modell aus. Wenn eine unterstützte NPU verfügbar ist, wählt Foundry Local das NPU-Modell aus.
  • Sie können einen kürzeren Namen verwenden, ohne sich die Modell-ID merken zu müssen.

Tipp

Wir empfehlen, den alias_or_model_id-Parameter an einen Alias zu übergeben, weil Foundry Local, wenn Sie Ihre Anwendung bereitstellen, zur Laufzeit das beste Modell für den Rechner des Endbenutzers auswählt.

Hinweis

Wenn Sie über eine Intel NPU unter Windows verfügen, stellen Sie sicher, dass Sie den Intel NPU-Treiber für eine optimale NPU-Beschleunigung installiert haben.

Dienstleistungsmanagement

Methode Unterschrift BESCHREIBUNG
is_service_running() () -> bool Überprüft, ob der Foundry Local-Dienst ausgeführt wird
start_service() () -> None Startet den Dienst "Foundry Local".
service_uri @property -> str Gibt den Dienst-URI zurück.
endpoint @property -> str Gibt den Dienstendpunkt zurück.
api_key @property -> str Gibt den API-Schlüssel (aus der Umgebung oder Standard) zurück

Katalogverwaltung

Methode Unterschrift BESCHREIBUNG
list_catalog_models() () -> list[ FoundryModelInfo] Listet alle verfügbaren Modelle im Katalog auf.
refresh_catalog() () -> None Aktualisiert den Modellkatalog.
get_model_info() (alias_or_model_id: str, raise_on_not_found=False) -> FoundryModelInfo or None Ruft Modellinformationen nach Alias oder ID ab

Cacheverwaltung

Methode Unterschrift BESCHREIBUNG
get_cache_location() () -> str Gibt den Pfad des Modellcacheverzeichnisses zurück.
list_cached_models() () -> list[ FoundryModelInfo] Listet Modelle auf, die in den lokalen Cache heruntergeladen wurden.

Modellverwaltung

Methode Unterschrift BESCHREIBUNG
download_model() (alias_or_model_id: str, token: str = None, force: bool = False) -> FoundryModelInfo] Lädt ein Modell in den lokalen Cache herunter.
load_model() (alias_or_model_id: str, ttl: int = 600) -> FoundryModelInfo] Lädt ein Modell in den Ableitungsserver.
unload_model() (alias_or_model_id: str, force: bool = False) -> None Entlädt ein Modell vom Ableitungsserver.
list_loaded_models() () -> list[ FoundryModelInfo] Listet alle derzeit im Dienst geladenen Modelle auf.

FoundryModelInfo

Die Methodenlist_catalog_models() , list_cached_models()und list_loaded_models() geben eine Liste von FoundryModelInfo Objekten zurück. Sie können die in diesem Objekt enthaltenen Informationen verwenden, um die Liste weiter zu verfeinern. Oder rufen Sie die Informationen für ein Modell direkt ab, indem Sie die get_model_info(alias_or_model_id) Methode aufrufen.

Diese Objekte enthalten die folgenden Felder:

Feld Typ BESCHREIBUNG
alias str Alias des Modells
id str Eindeutiger Bezeichner des Modells
version str Version des Modells
execution_provider str Der Beschleuniger (Ausführungsanbieter), der zum Ausführen des Modells verwendet wird.
device_type DeviceType Gerätetyp des Modells: CPU, GPU, NPU
uri str URI des Modells
file_size_mb int Größe des Modells auf dem Datenträger in MB
supports_tool_calling bool Gibt an, ob das Modell Toolaufrufe unterstützt.
prompt_template dict \| None Eingabeaufforderungsvorlage für das Modell
provider str Anbieter des Modells, bei dem das Modell veröffentlicht wird
publisher str Herausgeber des Modells, also wer das Modell veröffentlicht hat
license str Der Name der Lizenz des Modells
task str Aufgabe des Modells. Einer der Chat-Fertigstellungen, automatische Spracherkennung
ep_override str \| None Außerkraftsetzen für den Ausführungsanbieter, wenn sich dieser von der Standardeinstellung des Modells unterscheidet

Ausführungsanbieter

Einer von:

  • CPUExecutionProvider - CPU-basierte Ausführung
  • CUDAExecutionProvider - NVIDIA CUDA GPU-Ausführung
  • WebGpuExecutionProvider - WebGPU-Ausführung
  • QNNExecutionProvider - Neurale Netzwerkausführung von Qualcomm (NPU)
  • OpenVINOExecutionProvider - Intel OpenVINO-Ausführung
  • NvTensorRTRTXExecutionProvider - NVIDIA TensorRT-Ausführung
  • VitisAIExecutionProvider: AMD Vitis AI-Ausführung

Anwendungsbeispiel

Der folgende Code veranschaulicht die Verwendung der FoundryManager Klasse zum Verwalten von Modellen und interagieren mit dem lokalen Foundry-Dienst.

from foundry_local import FoundryLocalManager

# By using an alias, the most suitable model will be selected
# to your end-user's device.
alias = "qwen2.5-0.5b"

# Create a FoundryLocalManager instance. This will start the Foundry.
manager = FoundryLocalManager()

# List available models in the catalog
catalog = manager.list_catalog_models()
print(f"Available models in the catalog: {catalog}")

# Download and load a model
model_info = manager.download_model(alias)
model_info = manager.load_model(alias)
print(f"Model info: {model_info}")

# List models in cache
local_models = manager.list_cached_models()
print(f"Models in cache: {local_models}")

# List loaded models
loaded = manager.list_loaded_models()
print(f"Models running in the service: {loaded}")

# Unload a model
manager.unload_model(alias)

Integration mit dem OpenAI SDK

Installieren Sie das OpenAI-Paket:

pip install openai

Der folgende Code zeigt, wie das FoundryLocalManager mit dem OpenAI SDK integriert wird, um mit einem lokalen Modell zu interagieren.

import openai
from foundry_local import FoundryLocalManager

# By using an alias, the most suitable model will be downloaded
# to your end-user's device.
alias = "qwen2.5-0.5b"

# Create a FoundryLocalManager instance. This will start the Foundry
# Local service if it is not already running and load the specified model.
manager = FoundryLocalManager(alias)

# The remaining code us es the OpenAI Python SDK to interact with the local model.

# Configure the client to use the local Foundry service
client = openai.OpenAI(
    base_url=manager.endpoint,
    api_key=manager.api_key  # API key is not required for local usage
)

# Set the model to use and generate a streaming response
stream = client.chat.completions.create(
    model=manager.get_model_info(alias).id,
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True
)

# Print the streaming response
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)

JavaScript SDK-Referenz

Installation

Installieren Sie das Paket von npm:

npm install foundry-local-sdk

FoundryLocalManager Klasse

Mit der FoundryLocalManager Klasse können Sie Modelle verwalten, den Cache steuern und mit dem lokalen Foundry-Dienst in Browser- und Node.js-Umgebungen interagieren.

Initialisierung

import { FoundryLocalManager } from "foundry-local-sdk";

const foundryLocalManager = new FoundryLocalManager();

Verfügbare Optionen:

  • serviceUrl: Basis-URL des Foundry Local-Dienstes
  • fetch: (optional) Benutzerdefinierte Fetch-Implementierung für Umgebungen wie Node.js

Eine Notiz zu Aliasen

Viele in diesem Verweis beschriebene Methoden weisen einen aliasOrModelId Parameter in der Signatur auf. Sie können entweder einen Alias oder eine Modell-ID als Wert an die Methode übergeben. Die Verwendung eines Alias erfolgt wie folgt:

  • Wählen Sie das beste Modell für die verfügbare Hardware aus. Wenn beispielsweise eine Nvidia CUDA GPU verfügbar ist, wählt Foundry Local das CUDA-Modell aus. Wenn eine unterstützte NPU verfügbar ist, wählt Foundry Local das NPU-Modell aus.
  • Sie können einen kürzeren Namen verwenden, ohne sich die Modell-ID merken zu müssen.

Tipp

Wir empfehlen, den aliasOrModelId-Parameter an einen Alias zu übergeben, weil Foundry Local, wenn Sie Ihre Anwendung bereitstellen, zur Laufzeit das beste Modell für den Rechner des Endbenutzers auswählt.

Hinweis

Wenn Sie über eine Intel NPU unter Windows verfügen, stellen Sie sicher, dass Sie den Intel NPU-Treiber für eine optimale NPU-Beschleunigung installiert haben.

Dienstleistungsmanagement

Methode Unterschrift BESCHREIBUNG
init() (aliasOrModelId?: string) => Promise<void> Initialisiert das SDK und lädt optional ein Modell.
isServiceRunning() () => Promise<boolean> Überprüft, ob der Foundry Local-Dienst ausgeführt wird
startService() () => Promise<void> Startet den Dienst "Foundry Local".
serviceUrl string Die Basis-URL des lokalen Foundry-Diensts.
endpoint string Der API-Endpunkt (serviceUrl + /v1).
apiKey string Der API-Schlüssel: Keine vorhanden.

Katalogverwaltung

Methode Unterschrift BESCHREIBUNG
listCatalogModels() () => Promise<FoundryModelInfo[]> Listet alle verfügbaren Modelle im Katalog auf.
refreshCatalog() () => Promise<void> Aktualisiert den Modellkatalog.
getModelInfo() (aliasOrModelId: string, throwOnNotFound = false) => Promise<FoundryModelInfo \| null> Ruft Modellinformationen nach Alias oder ID ab

Cacheverwaltung

Methode Unterschrift BESCHREIBUNG
getCacheLocation() () => Promise<string> Gibt den Pfad des Modellcacheverzeichnisses zurück.
listCachedModels() () => Promise<FoundryModelInfo[]> Listet Modelle auf, die in den lokalen Cache heruntergeladen wurden.

Modellverwaltung

Methode Unterschrift BESCHREIBUNG
downloadModel() (aliasOrModelId: string, token?: string, force = false, onProgress?) => Promise<FoundryModelInfo> Lädt ein Modell in den lokalen Cache herunter.
loadModel() (aliasOrModelId: string, ttl = 600) => Promise<FoundryModelInfo> Lädt ein Modell in den Ableitungsserver.
unloadModel() (aliasOrModelId: string, force = false) => Promise<void> Entlädt ein Modell vom Ableitungsserver.
listLoadedModels() () => Promise<FoundryModelInfo[]> Listet alle derzeit im Dienst geladenen Modelle auf.

Anwendungsbeispiel

Der folgende Code veranschaulicht die Verwendung der FoundryLocalManager Klasse zum Verwalten von Modellen und interagieren mit dem lokalen Foundry-Dienst.

import { FoundryLocalManager } from "foundry-local-sdk";

// By using an alias, the most suitable model will be downloaded
// to your end-user's device.
// TIP: You can find a list of available models by running the
// following command in your terminal: `foundry model list`.
const alias = "qwen2.5-0.5b";

const manager = new FoundryLocalManager();

// Initialize the SDK and optionally load a model
const modelInfo = await manager.init(alias);
console.log("Model Info:", modelInfo);

// Check if the service is running
const isRunning = await manager.isServiceRunning();
console.log(`Service running: ${isRunning}`);

// List available models in the catalog
const catalog = await manager.listCatalogModels();

// Download and load a model
await manager.downloadModel(alias);
await manager.loadModel(alias);

// List models in cache
const localModels = await manager.listCachedModels();

// List loaded models
const loaded = await manager.listLoadedModels();

// Unload a model
await manager.unloadModel(alias);

Integration mit OpenAI-Client

Installieren Sie das OpenAI-Paket:

npm install openai

Der folgende Code zeigt, wie man FoundryLocalManager mit dem OpenAI-Client integriert, um mit einem lokalen Modell zu interagieren.

import { OpenAI } from "openai";
import { FoundryLocalManager } from "foundry-local-sdk";

// By using an alias, the most suitable model will be downloaded
// to your end-user's device.
// TIP: You can find a list of available models by running the
// following command in your terminal: `foundry model list`.
const alias = "qwen2.5-0.5b";

// Create a FoundryLocalManager instance. This will start the Foundry
// Local service if it is not already running.
const foundryLocalManager = new FoundryLocalManager();

// Initialize the manager with a model. This will download the model
// if it is not already present on the user's device.
const modelInfo = await foundryLocalManager.init(alias);
console.log("Model Info:", modelInfo);

const openai = new OpenAI({
  baseURL: foundryLocalManager.endpoint,
  apiKey: foundryLocalManager.apiKey,
});

async function streamCompletion() {
  const stream = await openai.chat.completions.create({
    model: modelInfo.id,
    messages: [{ role: "user", content: "What is the golden ratio?" }],
    stream: true,
  });

  for await (const chunk of stream) {
    if (chunk.choices[0]?.delta?.content) {
      process.stdout.write(chunk.choices[0].delta.content);
    }
  }
}

streamCompletion();

Browsernutzung

Das SDK enthält eine browserkompatible Version, in der Sie die Dienst-URL manuell angeben müssen:

import { FoundryLocalManager } from "foundry-local-sdk/browser";

// Specify the service URL
// Run the Foundry Local service using the CLI: `foundry service start`
// and use the URL from the CLI output
const endpoint = "ENDPOINT";

const manager = new FoundryLocalManager({ serviceUrl: endpoint });

// Note: The `init`, `isServiceRunning`, and `startService` methods
// are not available in the browser version

Hinweis

Die Browserversion unterstützt die Methoden init, isServiceRunning und startService nicht. Sie müssen sicherstellen, dass der lokale Foundry-Dienst ausgeführt wird, bevor Sie das SDK in einer Browserumgebung verwenden. Sie können den Dienst mit der lokalen Cli für Foundry starten: foundry service start. Sie können die Dienst-URL aus der CLI-Ausgabe erkennen.

Anwendungsbeispiel

import { FoundryLocalManager } from "foundry-local-sdk/browser";

// Specify the service URL
// Run the Foundry Local service using the CLI: `foundry service start`
// and use the URL from the CLI output
const endpoint = "ENDPOINT";

const manager = new FoundryLocalManager({ serviceUrl: endpoint });

const alias = "qwen2.5-0.5b";

// Get all available models
const catalog = await manager.listCatalogModels();
console.log("Available models in catalog:", catalog);

// Download and load a specific model
await manager.downloadModel(alias);
await manager.loadModel(alias);

// View models in your local cache
const localModels = await manager.listLocalModels();
console.log("Cached models:", catalog);

// Check which models are currently loaded
const loaded = await manager.listLoadedModels();
console.log("Loaded models in inference service:", loaded);

// Unload a model when finished
await manager.unloadModel(alias);

C# SDK-Referenz

Neugestaltung

Um Ihre Fähigkeit zu verbessern, Anwendungen mit ai auf dem Gerät zu versenden, gibt es wesentliche Änderungen an der Architektur des C#-SDK in version 0.8.0 und höher. In diesem Abschnitt erläutern wir die wichtigsten Änderungen, mit denen Sie Ihre Anwendungen zur neuesten Version des SDK migrieren können.

Hinweis

In der SDK-Version 0.8.0 und höher gibt es Breaking Changes in der API gegenüber früheren Versionen.

Architekturänderungen

Das folgende Diagramm zeigt, wie die vorherige Architektur – für frühere Versionen vor 0.8.0 – in großem Maße auf die Verwendung eines REST-Webservers zum Verwalten von Modellen und Inferenzen wie Chatabschlüssen basiert.

Diagramm der vorherigen Architektur für Foundry Local.

Das SDK würde einen Remoteprozeduraufruf (Remote Procedural Call, RPC) verwenden, um die ausführbare Datei für die Foundry Local-CLI auf dem Computer zu finden, den Webserver zu starten und dann über HTTP mit diesem zu kommunizieren. Diese Architektur hatte mehrere Einschränkungen, darunter:

  • Komplexität beim Verwalten des Webserverlebenszyklus.
  • Anspruchsvolle Bereitstellung: Endbenutzer mussten die Foundry Local-CLI auf ihren Computern und Ihre Anwendung installiert haben.
  • Die Versionsverwaltung der CLI und des SDK kann zu Kompatibilitätsproblemen führen.

Um diese Probleme zu beheben, verwendet die neu gestaltete Architektur in der Version 0.8.0 und später einen optimierteren Ansatz. Die neue Architektur lautet wie folgt:

Diagramm der neuen Architektur für Foundry Local.

In dieser neuen Architektur:

  • Ihre Anwendung ist eigenständig. Die Lokale Cli für Foundry muss nicht separat auf dem Computer des Endbenutzers installiert werden, sodass Sie Anwendungen einfacher bereitstellen können.
  • Der REST-Webserver ist optional. Sie können den Webserver weiterhin verwenden, wenn Sie in andere Tools integriert werden möchten, die über HTTP kommunizieren. Lesen Sie Verwendung von Chat-Vervollständigungen über den REST-Server mit Foundry Local, um Details zur Nutzung dieses Features zu erfahren.
  • Das SDK bietet native Unterstützung für Chatabschlusse und Audiotranskriptionen, sodass Sie Unterhaltungs-KI-Anwendungen mit weniger Abhängigkeiten erstellen können. Ausführliche Informationen zur Verwendung dieses Features finden Sie unter Use Foundry Local Native Chat Completions API.
  • Auf Windows-Geräten können Sie einen Windows ML-Build verwenden, der die Hardwarebeschleunigung für Modelle auf dem Gerät verarbeitet, indem Sie die richtige Laufzeit und Treiber abrufen.

API-Änderungen

Version 0.8.0 und höher bietet eine objektorientiertere und komponierbare API. Der Haupteinstiegspunkt ist weiterhin die FoundryLocalManager Klasse, aber anstatt eine flache Gruppe von Methoden zu sein, die über statische Aufrufe einer zustandslosen HTTP-API ausgeführt werden, macht das SDK jetzt Methoden für die FoundryLocalManager Instanz verfügbar, die den Status über den Dienst und die Modelle beibehalten.

Primitiv Versionen < 0.8.0 Versionen >= 0.8.0
Configuration N/A config = Configuration(...)
Manager abrufen mgr = FoundryLocalManager(); await FoundryLocalManager.CreateAsync(config, logger);
var mgr = FoundryLocalManager.Instance;
Katalog abrufen N/A catalog = await mgr.GetCatalogAsync();
Modelle auflisten mgr.ListCatalogModelsAsync(); catalog.ListModelsAsync();
Modell abrufen mgr.GetModelInfoAsync("aliasOrModelId"); catalog.GetModelAsync(alias: "alias");
Variant abrufen N/A model.SelectedVariant;
Variant festlegen N/A model.SelectVariant();
Herunterladen eines Modells mgr.DownloadModelAsync("aliasOrModelId"); model.DownloadAsync()
Laden eines Modells mgr.LoadModelAsync("aliasOrModelId"); model.LoadAsync()
Entladen eines Modells mgr.UnloadModelAsync("aliasOrModelId"); model.UnloadAsync()
Geladene Modelle auflisten mgr.ListLoadedModelsAsync(); catalog.GetLoadedModelsAsync();
Modellpfad abrufen N/A model.GetPathAsync()
Dienst starten mgr.StartServiceAsync(); mgr.StartWebServerAsync();
Dienst beenden mgr.StopServiceAsync(); mgr.StopWebServerAsync();
Cachespeicherort mgr.GetCacheLocationAsync(); config.ModelCacheDir
Zwischengespeicherte Modelle auflisten mgr.ListCachedModelsAsync(); catalog.GetCachedModelsAsync();

Die API ermöglicht die Konfiguration von Foundry Local über den Webserver, die Protokollierung, den Cachespeicherort und die Modellvariantenauswahl. Die Configuration Klasse ermöglicht es Ihnen, beispielsweise den Anwendungsnamen, den Protokollierungsgrad, die Webserver-URLs sowie die Verzeichnisse für Anwendungsdaten, Modellcache und Protokolle einzurichten:

var config = new Configuration
{
    AppName = "app-name",
    LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information,
    Web = new Configuration.WebService
    {
        Urls = "http://127.0.0.1:55588"
    },
    AppDataDir = "./foundry_local_data",
    ModelCacheDir = "{AppDataDir}/model_cache",
    LogsDir = "{AppDataDir}/logs"
};

In der vorherigen Version des Foundry Local C# SDK konnten Sie diese Einstellungen nicht direkt über das SDK konfigurieren, wodurch Die Möglichkeit zum Anpassen des Verhaltens des Diensts eingeschränkt wurde.

Projekteinrichtungshandbuch

Es gibt zwei NuGet-Pakete für das Foundry Local SDK – ein WinML und ein plattformübergreifendes Paket – die dieselbe API-Oberfläche aufweisen, aber für verschiedene Plattformen optimiert sind:

  • Windows: Verwendet das Microsoft.AI.Foundry.Local.WinML für Windows-Anwendungen spezifische Paket, das das Windows Machine Learning (WinML)-Framework verwendet, um optimale Leistung und Benutzererfahrung auf Windows-Geräten zu erzielen.
  • Plattformübergreifend: Verwenden Sie das Microsoft.AI.Foundry.Local Paket, das für plattformübergreifende Anwendungen (Windows, Linux, macOS) verwendet werden kann.

Befolgen Sie je nach Zielplattform die folgenden Anweisungen, um eine neue C#-Anwendung zu erstellen und die erforderlichen Abhängigkeiten hinzuzufügen:

Verwenden Sie Foundry Local in Ihrem C#-Projekt, indem Sie die folgenden Windows-spezifischen oder plattformübergreifenden Anweisungen (macOS/Linux/Windows) befolgen:

  1. Erstellen Sie ein neues C#-Projekt, und navigieren Sie zu diesem Projekt: 
    dotnet new console -n app-name
cd app-name
  2. Öffnen und bearbeiten Sie die app-name.csproj Datei in: 
    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0-windows10.0.26100</TargetFramework>
    <RootNamespace>app-name</RootNamespace>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
    <WindowsPackageType>None</WindowsPackageType>
    <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AI.Foundry.Local.WinML" Version="0.8.2.1" />
    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.10" />
    <PackageReference Include="OpenAI" Version="2.5.0" />
  </ItemGroup>

</Project>
  3. Erstellen Sie eine nuget.config Datei im Projektstamm mit dem folgenden Inhalt, damit die Pakete ordnungsgemäß wiederhergestellt werden: 
    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="ORT" value="https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="ORT">
      <package pattern="*Foundry*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Verringern der Größe des Anwendungspakets

Das Foundry Local SDK zieht das Microsoft.ML.OnnxRuntime.Foundry NuGet-Paket als Abhängigkeit ein. Das Microsoft.ML.OnnxRuntime.Foundry Paket stellt das Ableitungs-Laufzeitbundle bereit, bei dem es sich um den Satz von Bibliotheken handelt, die erforderlich sind, um die Ableitung auf bestimmten Hardwaregeräten des Herstellers effizient auszuführen. Das Ableitungs-Laufzeitpaket enthält die folgenden Komponenten:

  • ONNX-Runtime-Bibliothek: Das Kern-Ableitungsmodul (onnxruntime.dll).
  • ONNX Runtime Execution Provider (EP)-Bibliothek. Ein hardwarespezifisches Back-End in ONNX-Runtime, das Teile eines Modells für maschinelles Lernen optimiert und auf einem Hardwarebeschleuniger ausführt. Beispiel:
    • CUDA EP: onnxruntime_providers_cuda.dll
    • QNN EP: onnxruntime_providers_qnn.dll
  • Unabhängige Hardwareanbieterbibliotheken (IHV). Beispiel:
    • WebGPU: DirectX-Abhängigkeiten (dxcompiler.dll, dxil.dll)
    • QNN: Qualcomm QNN-Abhängigkeiten (QnnSystem.dllusw.)

Die folgende Tabelle fasst zusammen, welche EP- und IHV-Bibliotheken mit Ihrer Anwendung gebündelt sind und welche WinML zur Laufzeit herunterladen/installieren wird:

Abbildung einer Tabelle mit EP- und IHV-Bibliotheken.

In allen Plattformen/Architekturen ist die CPU-EPU erforderlich. Die WebGPU EP- und IHV-Bibliotheken sind klein (z. B. fügt WebGPU ihrem Anwendungspaket nur ~7 MB hinzu) und sind in Windows und macOS erforderlich. Die CUDA- und QNN-EPs sind jedoch groß (z. B. fügt CUDA Ihrem Anwendungspaket ~1 GB hinzu), daher empfehlen wir, diese EPs aus Ihrem Anwendungspaket auszuschließen . WinML lädt CUDA und QNN zur Laufzeit herunter/ installiert, wenn der Endbenutzer über kompatible Hardware verfügt.

Hinweis

Wir arbeiten daran, die CUDA- und QNN-EPs aus dem Microsoft.ML.OnnxRuntime.Foundry-Paket in zukünftigen Versionen zu entfernen, damit Sie keine ExcludeExtraLibs.props-Datei einschließen müssen, um sie aus Ihrem Anwendungspaket zu entfernen.

Um die Größe Ihres Anwendungspakets zu verringern, können Sie eine ExcludeExtraLibs.props Datei in Ihrem Projektverzeichnis mit dem folgenden Inhalt erstellen, der die CUDA- und QNN-EP- und IHV-Bibliotheken ausschließt, wenn Sie Ihre Anwendung veröffentlichen:

<Project>
  <!-- we want to ensure we're using the onnxruntime libraries from Foundry Local Core so 
  we delete the WindowsAppSdk versions once they're unzipped. -->
  <Target Name="ExcludeOnnxRuntimeLibs" AfterTargets="ExtractMicrosoftWindowsAppSDKMsixFiles">
    <Delete Files="$(MicrosoftWindowsAppSDKMsixContent)\onnxruntime.dll"/>
    <Delete Files="$(MicrosoftWindowsAppSDKMsixContent)\onnxruntime_providers_shared.dll"/>
    <Message Importance="Normal" Text="Deleted onnxruntime libraries from $(MicrosoftWindowsAppSDKMsixContent)." />
  </Target>

  <!-- Remove CUDA EP and IHV libraries on Windows x64 -->
  <Target Name="ExcludeCudaLibs" Condition="'$(RuntimeIdentifier)'=='win-x64'" AfterTargets="ResolvePackageAssets">
    <ItemGroup>
      <!-- match onnxruntime*cuda.* (we're matching %(Filename) which excludes the extension) -->
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)', 
                                      '^onnxruntime.*cuda.*', RegexOptions.IgnoreCase))" />
    </ItemGroup>
    <Message Importance="Normal" Text="Excluded onnxruntime CUDA libraries from package." />
  </Target>

  <!-- Remove QNN EP and IHV libraries on Windows arm64 -->
  <Target Name="ExcludeQnnLibs" Condition="'$(RuntimeIdentifier)'=='win-arm64'" AfterTargets="ResolvePackageAssets">
    <ItemGroup>
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)%(Extension)', 
                                      '^QNN.*\.dll', RegexOptions.IgnoreCase))" />
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)', 
                                      '^libQNNhtp.*', RegexOptions.IgnoreCase))" />
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="'%(FileName)%(Extension)' == 'onnxruntime_providers_qnn.dll'" />
    </ItemGroup>
    <Message Importance="Normal" Text="Excluded onnxruntime QNN libraries from package." />
  </Target>

  <!-- need to manually copy on linux-x64 due to the nuget packages not having the correct props file setup -->
  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <!-- 'Update' as the Core package will add these dependencies, but we want to be explicit about the version -->
    <PackageReference Update="Microsoft.ML.OnnxRuntime.Gpu" />
    <PackageReference Update="Microsoft.ML.OnnxRuntimeGenAI.Cuda" />
    <OrtNativeLibs Include="$(NuGetPackageRoot)microsoft.ml.onnxruntime.gpu.linux/$(OnnxRuntimeVersion)/runtimes/$(RuntimeIdentifier)/native/*" />
    <OrtGenAINativeLibs Include="$(NuGetPackageRoot)microsoft.ml.onnxruntimegenai.cuda/$(OnnxRuntimeGenAIVersion)/runtimes/$(RuntimeIdentifier)/native/*" />
  </ItemGroup>

  <Target Name="CopyOrtNativeLibs" AfterTargets="Build" Condition=" '$(RuntimeIdentifier)' == 'linux-x64'">
    <Copy SourceFiles="@(OrtNativeLibs)" DestinationFolder="$(OutputPath)"></Copy>
    <Copy SourceFiles="@(OrtGenAINativeLibs)" DestinationFolder="$(OutputPath)"></Copy>
  </Target>
</Project>

Fügen Sie in der Projektdatei (.csproj) die folgende Zeile hinzu, um die ExcludeExtraLibs.props Datei zu importieren:

<!-- other project file content -->
  
<Import Project="ExcludeExtraLibs.props" />

Linux: CUDA-Abhängigkeiten

Das CUDA EP wird über Microsoft.ML.OnnxRuntime.Foundry in Ihre Linux-Anwendung integriert, aber wir schließen die IHV-Bibliotheken nicht ein. Wenn Sie Ihren Endbenutzern mit CUDA-fähigen Geräten erlauben möchten, von einer höheren Leistung zu profitieren, müssen Sie Ihrer Anwendung die folgenden CUDA IHV-Bibliotheken hinzufügen :

Warnung

Durch Das Hinzufügen der CUDA EP- und IHV-Bibliotheken zu Ihrer Anwendung wird die Größe des Anwendungspakets um 1 GB erhöht.

Beispiele

API-Referenz

Rust SDK-Referenz

Das Rust SDK für Foundry Local bietet eine Möglichkeit, Modelle zu verwalten, den Cache zu steuern und mit dem lokalen Foundry-Dienst zu interagieren.

Installation

Um das Foundry Local Rust SDK zu verwenden, fügen Sie Folgendes zu Ihrem Cargo.toml:

[dependencies]
foundry-local-sdk = "0.1"

Alternativ können Sie das Lokal-Paket "Foundry" hinzufügen, indem Sie cargo verwenden:

cargo add foundry-local

FoundryLocalManager

Manager für lokale SDK-Operationen bei Foundry.

Felder

  • service_uri: Option<String> — URI des Foundry-Diensts.
  • client: Option<HttpClient> – HTTP-Client für API-Anforderungen.
  • catalog_list: Option<Vec<FoundryModelInfo>> – Zwischengespeicherte Liste der Katalogmodelle.
  • catalog_dict: Option<HashMap<String, FoundryModelInfo>> — Zwischengespeichertes Wörterbuch von Katalogmodellen.
  • timeout: Option<u64> – Optionaler HTTP-Client-Timeout.

Methodik

  • pub fn builder() -> FoundryLocalManagerBuilder
    Erstellen Sie einen neuen Generator für FoundryLocalManager.

  • pub fn service_uri(&self) -> Result<&str>
    Rufen Sie den Dienst-URI ab.
    Ertrag: URI des Foundry-Diensts.

  • fn client(&self) -> Result<&HttpClient>
    Rufen Sie die HTTP-Clientinstanz ab.
    Rückgabewert: HTTP-Client.

  • pub fn endpoint(&self) -> Result<String>
    Rufen Sie den Endpunkt für den Dienst ab.
    Ertrag: Endpunkt-URL.

  • pub fn api_key(&self) -> String
    Rufen Sie den API-Schlüssel für die Authentifizierung ab.
    Rückgabe: API-Schlüssel.

  • pub fn is_service_running(&mut self) -> bool
    Überprüfen Sie, ob der Dienst ausgeführt wird, und legen Sie den Dienst-URI fest, falls gefunden.
    Rückgabe:true wenn es läuft, false andernfalls.

  • pub fn start_service(&mut self) -> Result<()>
    Starten Sie den Dienst "Foundry Local".

  • pub async fn list_catalog_models(&mut self) -> Result<&Vec<FoundryModelInfo>>
    Rufen Sie eine Liste der verfügbaren Modelle im Katalog ab.

  • pub fn refresh_catalog(&mut self)
    Aktualisieren Sie den Katalogcache.

  • pub async fn get_model_info(&mut self, alias_or_model_id: &str, raise_on_not_found: bool) -> Result<FoundryModelInfo>
    Informationen zum Modell mittels Alias oder ID abrufen.
    Argumente:

    • alias_or_model_id: Alias oder Modell-ID.
    • raise_on_not_found: Wenn wahr, Fehler, wenn nicht gefunden.

  • pub async fn get_cache_location(&self) -> Result<String>
    Rufen Sie den Cachespeicherort als Zeichenfolge ab.

  • pub async fn list_cached_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    Zwischengespeicherte Modelle auflisten.

  • pub async fn download_model(&mut self, alias_or_model_id: &str, token: Option<&str>, force: bool) -> Result<FoundryModelInfo>
    Laden Sie ein Modell herunter.
    Argumente:

    • alias_or_model_id: Alias oder Modell-ID.
    • token: Optionales Authentifizierungstoken.
    • force: Den erneuten Download erzwingen, wenn er bereits zwischengespeichert ist.

  • pub async fn load_model(&mut self, alias_or_model_id: &str, ttl: Option<i32>) -> Result<FoundryModelInfo>
    Laden sie ein Modell für die Ableitung.
    Argumente:

    • alias_or_model_id: Alias oder Modell-ID.
    • ttl: Optionale Lebensdauer in Sekunden.

  • pub async fn unload_model(&mut self, alias_or_model_id: &str, force: bool) -> Result<()>
    Entladen eines Modells.
    Argumente:

    • alias_or_model_id: Alias oder Modell-ID.
    • force: Erzwingen Sie das Entladen, auch wenn es verwendet wird.

  • pub async fn list_loaded_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    Geladene Modelle auflisten.

FoundryLocalManagerBuilder

Generator zum Erstellen einer FoundryLocalManager Instanz.

Felder

  • alias_or_model_id: Option<String> — Alias- oder Modell-ID zum Herunterladen und Laden.
  • bootstrap: bool — Gibt an, ob der Dienst gestartet werden soll, wenn er nicht ausgeführt wird.
  • timeout_secs: Option<u64> – HTTP-Client-Timeout in Sekunden.

Methodik

  • pub fn new() -> Self
    Erstellen Sie eine neue Generatorinstanz.

  • pub fn alias_or_model_id(mut self, alias_or_model_id: impl Into<String>) -> Self
    Alias- oder Modell-ID zum Herunterladen und Laden.

  • pub fn bootstrap(mut self, bootstrap: bool) -> Self
    Legen Sie fest, ob der Dienst gestartet werden soll, wenn er nicht ausgeführt wird.

  • pub fn timeout_secs(mut self, timeout_secs: u64) -> Self
    Legen Sie das HTTP-Clienttimeout in Sekunden fest.

  • pub async fn build(self) -> Result<FoundryLocalManager>
    Erstellen Sie die FoundryLocalManager Instanz.

FoundryModelInfo

Stellt Informationen zu einem Modell dar.

Felder

  • alias: String — Der Modellalias.
  • id: String — Die Modell-ID.
  • version: String — Die Modellversion.
  • runtime: ExecutionProvider — Der Ausführungsanbieter (CPU, CUDA usw.).
  • uri: String — Der Modell-URI.
  • file_size_mb: i32 — Modelldateigröße in MB.
  • prompt_template: serde_json::Value – Promptvorlage für das Modell.
  • provider: String — Anbietername.
  • publisher: String — Herausgebername.
  • license: String — Lizenztyp.
  • task: String — Modellaufgabe (z. B. Textgenerierung).

Methodik

  • from_list_response(response: &FoundryListResponseModel) -> Self
    Erstellt eine FoundryModelInfo aus einer Katalogantwort.

  • to_download_body(&self) -> serde_json::Value
    Konvertiert die Modellinformationen in einen JSON-Textkörper für Downloadanforderungen.

ExecutionProvider

Enum für unterstützte Ausführungsanbieter.

  • CPU
  • WebGPU
  • CUDA
  • QNN
Methodik
  • get_alias(&self) -> String
    Gibt einen Zeichenfolgenalias für den Ausführungsanbieter zurück.

ModelRuntime

Beschreibt die Laufzeitumgebung für ein Modell.

  • device_type: DeviceType
  • execution_provider: ExecutionProvider
  • Last updated on