Delen via

Referentie voor Foundry Local SDK

Belangrijk

  • Foundry Local is beschikbaar in preview. Openbare preview-versies bieden vroege toegang tot functies die actief zijn geïmplementeerd.
  • Functies, benaderingen en processen kunnen worden gewijzigd of beperkte mogelijkheden hebben, voordat algemene beschikbaarheid (GA) wordt uitgevoerd.

De Foundry Local SDK vereenvoudigt het beheer van AI-modellen in lokale omgevingen door besturingsvlakbewerkingen gescheiden van de deductiecode van het gegevensvlak te bieden. In deze referentiedocumentatie worden SDK-implementaties voor Python, JavaScript, C# en Rust beschreven.

Python SDK Referentie

Installatie

Installeer het Python-pakket:

pip install foundry-local-sdk

FoundryLocalManager-klasse

De FoundryLocalManager klasse biedt methoden voor het beheren van modellen, cache en de Foundry Local-service.

Initialisatie

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: (optioneel) Alias of Model-ID om bij de opstart te downloaden en te laden.
  • bootstrap: (standaard True) Als dit Waar is, start de service indien deze niet actief is en wordt het model geladen indien opgegeven.

Een notitie over aliassen

Veel methoden die in deze verwijzing worden beschreven, hebben een alias_or_model_id parameter in de handtekening. U kunt in de methode een alias of model-ID als waarde gebruiken. Als u een alias gebruikt, doet u het volgende:

  • Selecteer het beste model voor de beschikbare hardware. Als er bijvoorbeeld een Nvidia CUDA GPU beschikbaar is, selecteert Foundry Local het CUDA-model. Als er een ondersteunde NPU beschikbaar is, selecteert Foundry Local het NPU-model.
  • Hiermee kunt u een kortere naam gebruiken zonder dat u de model-id hoeft te onthouden.

Aanbeveling

Wij raden u aan een alias_or_model_id door te geven als parameter, omdat Foundry Local bij de implementatie van uw toepassing tijdens de uitvoeringstijd het optimale model selecteert voor de computer van de eindgebruiker.

Opmerking

Als u een Intel NPU in Windows hebt, moet u ervoor zorgen dat u het Intel NPU-stuurprogramma hebt geïnstalleerd voor optimale NPU-versnelling.

Servicebeheer

Methode Handtekening Beschrijving
is_service_running() () -> bool Controleert of de Foundry Local-service draait.
start_service() () -> None Start de lokale service Foundry.
service_uri @property -> str Retourneert de service-URI.
endpoint @property -> str Retourneert het service-eindpunt.
api_key @property -> str Retourneert de API-sleutel (van env of standaard).

Catalogusbeheer

Methode Handtekening Beschrijving
list_catalog_models() () -> list[ FoundryModelInfo] Een lijst met alle beschikbare modellen in de catalogus.
refresh_catalog() () -> None Hiermee vernieuwt u de modelcatalogus.
get_model_info() (alias_or_model_id: str, raise_on_not_found=False) -> FoundryModelInfo or None Hiermee haalt u modelgegevens op basis van alias of id op.

Cachebeheer

Methode Handtekening Beschrijving
get_cache_location() () -> str Retourneert het pad naar de cachemap van het model.
list_cached_models() () -> list[ FoundryModelInfo] Hier vindt u een lijst met modellen die zijn gedownload naar de lokale cache.

Modelbeheer

Methode Handtekening Beschrijving
download_model() (alias_or_model_id: str, token: str = None, force: bool = False) -> FoundryModelInfo] Hiermee downloadt u een model naar de lokale cache.
load_model() (alias_or_model_id: str, ttl: int = 600) -> FoundryModelInfo] Laadt een model in de deductieserver.
unload_model() (alias_or_model_id: str, force: bool = False) -> None Hiermee wordt een model van de deductieserver verwijderd.
list_loaded_models() () -> list[ FoundryModelInfo] Geeft een lijst weer van alle modellen die momenteel in de service zijn geladen.

FoundryModelInfo

De methodenlist_catalog_models()list_cached_models() en list_loaded_models() retourneren een lijst FoundryModelInfo met objecten. U kunt de informatie in dit object gebruiken om de lijst verder te verfijnen. Of haal de informatie voor een model rechtstreeks op door de get_model_info(alias_or_model_id) methode aan te roepen.

Deze objecten bevatten de volgende velden:

Veld Typologie Beschrijving
alias str Alias van het model
id str Unieke identificatie van het model
version str Versie van het model
execution_provider str De accelerator (uitvoeringsprovider) die wordt gebruikt om het model uit te voeren.
device_type DeviceType Apparaattype van het model: CPU, GPU, NPU
uri str URI van het model
file_size_mb int Grootte van het model op schijf in MB
supports_tool_calling bool Of het model ondersteuning biedt voor het aanroepen van hulpprogramma's
prompt_template dict \| None Sjabloon vragen voor het model
provider str Provider van het model waar het model wordt gepubliceerd
publisher str Uitgever van het model dat het model heeft gepubliceerd
license str De naam van de licentie van het model
task str Taak van het model. Een van de chat-aanvullingen en automatische spraakherkenning
ep_override str \| None Overschrijven voor de uitvoeringsprovider, indien anders dan de standaardwaarde van het model

Uitvoeringsproviders

Een van de volgende:

  • CPUExecutionProvider - Uitvoering op basis van CPU
  • CUDAExecutionProvider - UITVOERING VAN NVIDIA CUDA GPU
  • WebGpuExecutionProvider - WebGPU-uitvoering
  • QNNExecutionProvider - Qualcomm Neural Network verwerking (NPU)
  • OpenVINOExecutionProvider - Intel OpenVINO-uitvoering
  • NvTensorRTRTXExecutionProvider - NVIDIA TensorRT-uitvoering
  • VitisAIExecutionProvider - AMD Vitis AI-uitvoering

Voorbeeldgebruik

De volgende code laat zien hoe u de FoundryManager klasse gebruikt om modellen te beheren en te communiceren met de Foundry Local-service.

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)

Integreren met OpenAI SDK

Installeer het OpenAI-pakket:

pip install openai

De volgende code laat zien hoe u de FoundryLocalManager met de OpenAI SDK integreert om te communiceren met een lokaal model.

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 Referentie

Installatie

Installeer het pakket vanuit npm:

npm install foundry-local-sdk

FoundryLocalManager-klasse

Met FoundryLocalManager de klasse kunt u modellen beheren, de cache beheren en communiceren met de Lokale service Foundry in zowel browser- als Node.js omgevingen.

Initialisatie

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

const foundryLocalManager = new FoundryLocalManager();

Beschikbare opties:

  • serviceUrl: Basis-URL van de lokale service Foundry
  • fetch: (optioneel) Aangepaste fetch-implementatie voor omgevingen zoals Node.js

Een notitie over aliassen

Veel methoden die in deze verwijzing worden beschreven, hebben een aliasOrModelId parameter in de handtekening. U kunt in de methode een alias of model-ID als waarde gebruiken. Als u een alias gebruikt, doet u het volgende:

  • Selecteer het beste model voor de beschikbare hardware. Als er bijvoorbeeld een Nvidia CUDA GPU beschikbaar is, selecteert Foundry Local het CUDA-model. Als er een ondersteunde NPU beschikbaar is, selecteert Foundry Local het NPU-model.
  • Hiermee kunt u een kortere naam gebruiken zonder dat u de model-id hoeft te onthouden.

Aanbeveling

Wij raden u aan een aliasOrModelId door te geven als parameter, omdat Foundry Local bij de implementatie van uw toepassing tijdens de uitvoeringstijd het optimale model selecteert voor de computer van de eindgebruiker.

Opmerking

Als u een Intel NPU in Windows hebt, moet u ervoor zorgen dat u het Intel NPU-stuurprogramma hebt geïnstalleerd voor optimale NPU-versnelling.

Servicebeheer

Methode Handtekening Beschrijving
init() (aliasOrModelId?: string) => Promise<void> Initialiseert de SDK en laadt eventueel een model.
isServiceRunning() () => Promise<boolean> Controleert of de Foundry Local-service draait.
startService() () => Promise<void> Start de lokale service Foundry.
serviceUrl string De basis-URL van de Foundry Local-service.
endpoint string Het API-eindpunt (serviceUrl + /v1).
apiKey string De API-sleutel (geen).

Catalogusbeheer

Methode Handtekening Beschrijving
listCatalogModels() () => Promise<FoundryModelInfo[]> Een lijst met alle beschikbare modellen in de catalogus.
refreshCatalog() () => Promise<void> Hiermee vernieuwt u de modelcatalogus.
getModelInfo() (aliasOrModelId: string, throwOnNotFound = false) => Promise<FoundryModelInfo \| null> Hiermee haalt u modelgegevens op basis van alias of id op.

Cachebeheer

Methode Handtekening Beschrijving
getCacheLocation() () => Promise<string> Retourneert het pad naar de cachemap van het model.
listCachedModels() () => Promise<FoundryModelInfo[]> Hier vindt u een lijst met modellen die zijn gedownload naar de lokale cache.

Modelbeheer

Methode Handtekening Beschrijving
downloadModel() (aliasOrModelId: string, token?: string, force = false, onProgress?) => Promise<FoundryModelInfo> Hiermee downloadt u een model naar de lokale cache.
loadModel() (aliasOrModelId: string, ttl = 600) => Promise<FoundryModelInfo> Laadt een model in de deductieserver.
unloadModel() (aliasOrModelId: string, force = false) => Promise<void> Hiermee wordt een model van de deductieserver verwijderd.
listLoadedModels() () => Promise<FoundryModelInfo[]> Geeft een lijst weer van alle modellen die momenteel in de service zijn geladen.

Voorbeeldgebruik

De volgende code laat zien hoe u de FoundryLocalManager klasse gebruikt om modellen te beheren en te communiceren met de Foundry Local-service.

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

Integratie met OpenAI-client

Installeer het OpenAI-pakket:

npm install openai

De volgende code laat zien hoe u de FoundryLocalManager met de OpenAI-client integreert om te communiceren met een lokaal model.

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

Browsergebruik

De SDK bevat een browsercompatibele versie waarin u de service-URL handmatig moet opgeven:

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

Opmerking

De browserversie biedt geen ondersteuning voor de init, isServiceRunningen startService methoden. U moet ervoor zorgen dat de Foundry Local-service wordt uitgevoerd voordat u de SDK in een browseromgeving gebruikt. U kunt de service starten met behulp van de lokale CLI van Foundry: foundry service start. U kunt de service-URL uit de CLI-uitvoer bekijken.

Voorbeeldgebruik

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

Naslaginformatie voor C# SDK

Nieuw ontwerp

Om uw mogelijkheden voor het verzenden van toepassingen met AI op het apparaat te verbeteren, zijn er aanzienlijke wijzigingen in de architectuur van de C#-SDK in versie 0.8.0 en hoger. In deze sectie wordt een overzicht gegeven van de belangrijkste wijzigingen die u helpen bij het migreren van uw toepassingen naar de nieuwste versie van de SDK.

Opmerking

In de SDK-versie 0.8.0 en hoger zijn er belangrijke wijzigingen in de API van eerdere versies.

Architectuurwijzigingen

In het volgende diagram ziet u hoe de vorige architectuur , voor versies ouder dan 0.8.0 - sterk afhankelijk was van het gebruik van een REST-webserver voor het beheren van modellen en deductie zoals voltooiingen van chats:

Diagram van de vorige architectuur voor Foundry Local.

De SDK gebruikt een Remote Procedure Call (RPC) om het uitvoerbare bestand foundry Local CLI op de computer te vinden, de webserver te starten en er vervolgens mee te communiceren via HTTP. Deze architectuur had verschillende beperkingen, waaronder:

  • Complexiteit bij het beheren van de levenscyclus van de webserver.
  • Uitdagende implementatie: eindgebruikers moesten de Lokale CLI van Foundry installeren op hun computers en uw toepassing.
  • Versiebeheer van de CLI en SDK kan leiden tot compatibiliteitsproblemen.

Om deze problemen op te lossen, gebruikt de opnieuw ontworpen architectuur in versie 0.8.0 en later een meer gestroomlijnde benadering. De nieuwe architectuur is als volgt:

Diagram van de nieuwe architectuur voor Foundry Local.

In deze nieuwe architectuur:

  • Uw toepassing is zelfstandig. Het vereist niet dat de Lokale CLI van Foundry afzonderlijk op de computer van de eindgebruiker wordt geïnstalleerd, zodat u toepassingen eenvoudiger kunt implementeren.
  • De REST-webserver is optioneel. U kunt de webserver nog steeds gebruiken als u wilt integreren met andere hulpprogramma's die via HTTP communiceren. Lees Chatvoltooiingen gebruiken via REST-server met Foundry Local voor meer informatie over het gebruik van deze functie.
  • De SDK biedt systeemeigen ondersteuning voor chatvoltooiingen en audiotranscripties, zodat u conversationele AI-toepassingen met minder afhankelijkheden kunt bouwen. Lees de API voor het gebruik van Foundry Local native chat voor meer informatie over het gebruik van deze functie.
  • Op Windows-apparaten kunt u een Windows ML-build gebruiken die hardwareversnelling voor modellen op het apparaat afhandelt door de juiste runtime en stuurprogramma's in te trekken.

API-wijzigingen

Versie 0.8.0 en hoger biedt een meer objectgeoriënteerde en composeerbare API. Het belangrijkste toegangspunt blijft de FoundryLocalManager klasse, maar in plaats van een platte set methoden te zijn die werken via statische aanroepen naar een stateless HTTP-API, biedt de SDK nu methoden voor het FoundryLocalManager exemplaar dat de status over de service en modellen onderhoudt.

Primitief Versie < 0.8.0 Versie >= 0.8.0
Configuration N/A config = Configuration(...)
Manager ophalen mgr = FoundryLocalManager(); await FoundryLocalManager.CreateAsync(config, logger);
var mgr = FoundryLocalManager.Instance;
Catalogus ophalen N/A catalog = await mgr.GetCatalogAsync();
Modellen weergeven mgr.ListCatalogModelsAsync(); catalog.ListModelsAsync();
Model ophalen mgr.GetModelInfoAsync("aliasOrModelId"); catalog.GetModelAsync(alias: "alias");
Variant ophalen N/A model.SelectedVariant;
Variant instellen N/A model.SelectVariant();
Een model downloaden mgr.DownloadModelAsync("aliasOrModelId"); model.DownloadAsync()
Een model laden mgr.LoadModelAsync("aliasOrModelId"); model.LoadAsync()
Een model uitpakken mgr.UnloadModelAsync("aliasOrModelId"); model.UnloadAsync()
Geladen modellen weergeven mgr.ListLoadedModelsAsync(); catalog.GetLoadedModelsAsync();
Modelpad ophalen N/A model.GetPathAsync()
Service starten mgr.StartServiceAsync(); mgr.StartWebServerAsync();
Service stoppen mgr.StopServiceAsync(); mgr.StopWebServerAsync();
Cachelocatie mgr.GetCacheLocationAsync(); config.ModelCacheDir
In cache opgeslagen modellen weergeven mgr.ListCachedModelsAsync(); catalog.GetCachedModelsAsync();

Met de API kan Foundry Local beter worden geconfigureerd via de webserver, logboekregistratie, cachelocatie en modelvariantselectie. Met de Configuration klasse kunt u bijvoorbeeld de naam van de toepassing, logboekregistratieniveau, webserver-URL's en mappen instellen voor toepassingsgegevens, modelcache en logboeken:

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 de vorige versie van de Foundry Local C#SDK kon u deze instellingen niet rechtstreeks configureren via de SDK, waardoor uw mogelijkheid om het gedrag van de service aan te passen werd beperkt.

Installatiehandleiding voor project

Er zijn twee NuGet-pakketten voor de Foundry Local SDK - een WinML en een platformoverschrijdend pakket - die hetzelfde API-oppervlak hebben, maar zijn geoptimaliseerd voor verschillende platforms:

  • Windows: maakt gebruik van het Microsoft.AI.Foundry.Local.WinML pakket dat specifiek is voor Windows-toepassingen, dat gebruikmaakt van het Windows Machine Learning-framework (WinML) om optimale prestaties en gebruikerservaring op Windows-apparaten te bieden.
  • Platformoverschrijdend: gebruik het Microsoft.AI.Foundry.Local pakket dat kan worden gebruikt voor platformoverschrijdende toepassingen (Windows, Linux, macOS).

Afhankelijk van uw doelplatform volgt u deze instructies om een nieuwe C#-toepassing te maken en de benodigde afhankelijkheden toe te voegen:

Gebruik Foundry Local in uw C#-project door de volgende Windows-specifieke of platformoverschrijdende instructies (macOS/Linux/Windows) te volgen:

  1. Maak een nieuw C#-project en navigeer ernaartoe: 
    dotnet new console -n app-name
cd app-name
  2. Open het bestand app-name.csproj om te bewerken: 
    <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. Maak een nuget.config bestand in de hoofdmap van het project met de volgende inhoud, zodat de pakketten correct worden hersteld: 
    <?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>

De grootte van het toepassingspakket verkleinen

De Foundry Local SDK haalt het NuGet-pakket als een afhankelijkheid binnen via Microsoft.ML.OnnxRuntime.Foundry. Het Microsoft.ML.OnnxRuntime.Foundry pakket biedt de deductieruntimebundel. Dit is de set bibliotheken die nodig zijn om deductie efficiënt uit te voeren op specifieke hardwareapparaten van de leverancier. De deductieruntimebundel bevat de volgende onderdelen:

  • ONNX Runtime-bibliotheek: De kerndeductie-engine (onnxruntime.dll).
  • ONNX Runtime Execution Provider (EP) bibliotheek. Een hardwarespecifieke back-end in ONNX Runtime die onderdelen van een machine learning-model optimaliseert en uitvoert, een hardwareversneller. Bijvoorbeeld:
    • CUDA EP: onnxruntime_providers_cuda.dll
    • QNN EP: onnxruntime_providers_qnn.dll
  • IHV-bibliotheken (Independent Hardware Vendor). Bijvoorbeeld:
    • WebGPU: DirectX-afhankelijkheden (dxcompiler.dll, dxil.dll)
    • QNN: de afhankelijkheden van Qualcomm QNN (QnnSystem.dll, enz.)

De volgende tabel bevat een overzicht van welke EP- en IHV-bibliotheken zijn gebundeld met uw toepassing en wat WinML tijdens runtime gaat downloaden/installeren:

Afbeelding van een tabel met EP- en IHV-bibliotheken.

In alle platformen/architectuur is de CPU-EPU vereist. De WebGPU EP- en IHV-bibliotheken zijn klein (webGPU voegt bijvoorbeeld alleen ~7 MB toe aan uw toepassingspakket) en zijn vereist in Windows en macOS. De CUDA- en QNN-IP's zijn echter groot (CUDA voegt bijvoorbeeld ~1 GB toe aan uw toepassingspakket), dus we raden u aan deze IP's uit uw toepassingspakket uit te sluiten . WinML downloadt/installeert CUDA en QNN tijdens runtime als de eindgebruiker compatibele hardware heeft.

Opmerking

We werken aan het verwijderen van de CUDA- en QNN-EP's uit het Microsoft.ML.OnnxRuntime.Foundry-pakket in toekomstige releases, zodat u geen ExcludeExtraLibs.props-bestand hoeft op te nemen om ze uit uw toepassingspakket te verwijderen.

Als u de grootte van uw toepassingspakket wilt verkleinen, kunt u een ExcludeExtraLibs.props bestand in uw projectmap maken met de volgende inhoud, waarbij de CUDA- en QNN EP- en IHV-bibliotheken worden uitgesloten wanneer u uw toepassing publiceert:

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

Voeg in het projectbestand (.csproj) de volgende regel toe om het ExcludeExtraLibs.props bestand te importeren:

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

Linux: CUDA-afhankelijkheden

Het CUDA EP wordt via uw Linux-toepassing opgehaald, Microsoft.ML.OnnxRuntime.Foundrymaar we nemen de IHV-bibliotheken niet op. Als u wilt dat uw eindgebruikers met CUDA-apparaten profiteren van hogere prestaties, moet u de volgende CUDA IHV-bibliotheken toevoegen aan uw toepassing:

Waarschuwing

Door de CUDA EP- en IHV-bibliotheken toe te voegen aan uw toepassing, wordt de grootte van uw toepassingspakket met 1 GB vergroot.

Samples

API-referentie

Naslag Rust SDK

De Rust SDK voor Foundry Local biedt een manier om modellen te beheren, de cache te beheren en te communiceren met de Foundry Local-service.

Installatie

Als u de Foundry Local Rust SDK wilt gebruiken, voegt u het volgende toe aan uw Cargo.toml:

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

U kunt ook de lokale krat van Foundry toevoegen met behulp van cargo:

cargo add foundry-local

FoundryLocalManager

Manager voor Foundry Local SDK-bewerkingen.

Velden

  • service_uri: Option<String> — URI van de Foundry-service.
  • client: Option<HttpClient> — HTTP-client voor API-aanvragen.
  • catalog_list: Option<Vec<FoundryModelInfo>> — Lijst met catalogusmodellen in cache.
  • catalog_dict: Option<HashMap<String, FoundryModelInfo>> — Gecachte woordenlijst van catalogusmodellen.
  • timeout: Option<u64> — Optionele time-out voor HTTP-client.

Methoden

  • pub fn builder() -> FoundryLocalManagerBuilder
    Maak een nieuwe opbouwfunctie voor FoundryLocalManager.

  • pub fn service_uri(&self) -> Result<&str>
    Haal de service-URI op.
    Retourneert: URI van de Foundry-service.

  • fn client(&self) -> Result<&HttpClient>
    Haal de HTTP-clientexemplaar op.
    Retourneert: HTTP-client.

  • pub fn endpoint(&self) -> Result<String>
    Haal het eindpunt voor de service op.
    Retourneert: URL van het eindpunt.

  • pub fn api_key(&self) -> String
    Haal de API-sleutel op voor verificatie.
    Retourneert: API-sleutel.

  • pub fn is_service_running(&mut self) -> bool
    Controleer of de service wordt uitgevoerd en stel de service-URI in als deze is gevonden.
    Retourneert:true indien actief, false anders.

  • pub fn start_service(&mut self) -> Result<()>
    Start de lokale service Foundry.

  • pub async fn list_catalog_models(&mut self) -> Result<&Vec<FoundryModelInfo>>
    Een lijst met beschikbare modellen in de catalogus ophalen.

  • pub fn refresh_catalog(&mut self)
    Vernieuw de cataloguscache.

  • pub async fn get_model_info(&mut self, alias_or_model_id: &str, raise_on_not_found: bool) -> Result<FoundryModelInfo>
    Modelgegevens ophalen op basis van alias of id.
    Argumenten:

    • alias_or_model_id: alias of model-id.
    • raise_on_not_found: Indien waar, fout indien niet gevonden.

  • pub async fn get_cache_location(&self) -> Result<String>
    Haal de cachelocatie op als een string.

  • pub async fn list_cached_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    In cache opgeslagen modellen weergeven.

  • pub async fn download_model(&mut self, alias_or_model_id: &str, token: Option<&str>, force: bool) -> Result<FoundryModelInfo>
    Download een model.
    Argumenten:

    • alias_or_model_id: alias of model-id.
    • token: Optioneel verificatietoken.
    • force: Forceer opnieuw downloaden als deze al in de cache is opgeslagen.

  • pub async fn load_model(&mut self, alias_or_model_id: &str, ttl: Option<i32>) -> Result<FoundryModelInfo>
    Laad een model voor deductie.
    Argumenten:

    • alias_or_model_id: alias of model-id.
    • ttl: Optionele levensduur in seconden.

  • pub async fn unload_model(&mut self, alias_or_model_id: &str, force: bool) -> Result<()>
    Een model ontladen.
    Argumenten:

    • alias_or_model_id: alias of model-id.
    • force: Forceer het lossen, zelfs als het in gebruik is.

  • pub async fn list_loaded_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    Geladen modellen weergeven.

FoundryLocalManagerBuilder

Opbouwfunctie voor het maken van een FoundryLocalManager exemplaar.

Velden

  • alias_or_model_id: Option<String> — Alias of model-ID voor downloaden en laden.
  • bootstrap: bool — Of de service moet worden gestart als deze niet actief is.
  • timeout_secs: Option<u64> — Time-out voor HTTP-client in seconden.

Methoden

  • pub fn new() -> Self
    Maak een nieuwe builder-instantie.

  • pub fn alias_or_model_id(mut self, alias_or_model_id: impl Into<String>) -> Self
    Stel de alias of model-ID in voor het downloaden en laden.

  • pub fn bootstrap(mut self, bootstrap: bool) -> Self
    Stel in of de service moet worden gestart als deze niet wordt uitgevoerd.

  • pub fn timeout_secs(mut self, timeout_secs: u64) -> Self
    Stel de time-out van de HTTP-client in seconden in.

  • pub async fn build(self) -> Result<FoundryLocalManager>
    Bouw het FoundryLocalManager exemplaar.

FoundryModelInfo

Vertegenwoordigt informatie over een model.

Velden

  • alias: String — Het modelalias.
  • id: String — De model-id.
  • version: String — De modelversie.
  • runtime: ExecutionProvider — De uitvoeringsprovider (CPU, CUDA, enzovoort).
  • uri: String — De model-URI.
  • file_size_mb: i32 — Modelbestandsgrootte in MB.
  • prompt_template: serde_json::Value — Promptsjabloon voor het model.
  • provider: String — Providernaam.
  • publisher: String — Naam van uitgever.
  • license: String — Licentietype.
  • task: String — Modeltaak (bijvoorbeeld tekstgeneratie).

Methoden

  • from_list_response(response: &FoundryListResponseModel) -> Self
    Maakt een FoundryModelInfo aan op basis van een catalogusrespons.

  • to_download_body(&self) -> serde_json::Value
    Converteert de modelgegevens naar een JSON-hoofdtekst voor downloadaanvragen.

ExecutionProvider

Enum voor ondersteunde uitvoeringsproviders.

  • CPU
  • WebGPU
  • CUDA
  • QNN
Methoden
  • get_alias(&self) -> String
    Retourneert een tekenreeksalias voor de uitvoeringsprovider.

ModelRuntime

Beschrijft de runtime-omgeving voor een model.

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