Sdílet prostřednictvím

Referenční informace k local SDK od Foundry

Důležité

  • Foundry Local je k dispozici ve verzi Preview. Verze Public Preview poskytují dřívější přístup k funkcím, které jsou v aktivním nasazení.
  • Funkce, přístupy a procesy se můžou před obecnou dostupností měnit nebo mít omezené možnosti.

Sada Foundry Local SDK umožňuje dodávat funkce AI ve vašich aplikacích, které umožňují využívat místní modely AI prostřednictvím jednoduchého a intuitivního rozhraní API. Sada SDK abstrahuje složitost správy modelů AI a poskytuje bezproblémové prostředí pro integraci místních funkcí AI do vašich aplikací. Tento referenční dokument popisuje implementace SDK pro JavaScript a C#. Další jazyky budou přidány v budoucnu.

Sada SDK nevyžaduje instalaci rozhraní příkazového řádku Foundry Local CLI na počítači koncových uživatelů, což vám umožní dodávat aplikace bez dalších kroků nastavení pro vaše uživatele – vaše aplikace jsou samostatné. Mezi další výhody místní sady SDK Foundry patří:

  • Detekce a optimalizace hardwaru: Automatické posouzení schopností pro GPU, NPU a procesor.
  • Správa zprostředkovatele spouštění (Windows): Automatické stahování a registrace příslušných zprostředkovatelů spouštění modulu runtime ONNX (CUDA, Vitis, QNN, OpenVINO, TensorRT) na základě možností zařízení.
  • Podpora kovu přes WebGpu (macOS): Nativní podpora spouštění modelů na Apple Silicon s optimalizovaným výkonem.
  • Získání modelu: Bezproblémové stahování z Katalogu modelů Foundry s podporou správy verzí, aktualizací a automatického výběru modelu optimalizovaného pro hardware s podporou náhradní verze.
  • Efektivní modul runtime: Zvětší velikost aplikace o <20 MB, běží na zařízeních od mobilních telefonů po stolní počítače.
  • Kompatibilita rozhraní API OpenAI: Snadná integrace s modely a nástroji OpenAI
  • Volitelný server REST: Spusťte Foundry Local jako místní službu přístupnou jinými aplikacemi.

Referenční informace k sadě JavaScript SDK

Nastavení projektu

Základní architektura sady Foundry Local SDK je následující:

Diagram nové architektury pro Foundry Local

Sada SDK je lehká obálka kolem rozhraní API foundry Local Core C (.dll/.so/.dylib), která poskytuje uživatelsky přívětivější rozhraní pro vývojáře v JavaScriptu. Sada SDK zpracovává načítání nativní knihovny, správu paměti a převod datových typů mezi JavaScriptem a C. Rozhraní FOUNDRY Local Core C API má dvě varianty, ale stejnou plochu rozhraní API:

  • WindowsML (WinML) – Specifické pro Windows, které používají WindowsML k získání potřebných ovladačů a poskytovatelů spouštění pro dostupný hardware. Tato možnost je doporučená pro uživatele Windows, protože poskytuje lepší výkon a kompatibilitu s širokou škálou hardwaru.
  • Multiplatformní – lze použít ve Windows, macOS a Linuxu. Je třeba poznamenat, že na zařízeních s macOS, která mají Apple Silicon, bude SDK pro různé platformy používat Metal framework společnosti Apple k hardwarové akceleraci prostřednictvím poskytovatele vykonávání WebGPU v modulu runtime ONNX.

Při instalaci balíčku Foundry Local SDK do projektu se můžete rozhodnout nainstalovat WinML nebo multiplatformní verzi.

Postupujte podle těchto pokynů specifických pro Windows nebo pro multiplatformní systémy (macOS/Linux/Windows) pro použití Foundry Local ve vašem projektu JavaScript:

  1. Vytvořte nový projekt JavaScriptu: 
    mkdir app-name
cd app-name
npm init -y
npm pkg set type=module
  2. Nainstalujte balíček Foundry Local SDK: 
    npm install --winml foundry-local-sdk
npm install openai

Rychlý start

Pomocí tohoto úryvku kódu ověřte, že SDK může inicializovat a přistupovat k místnímu katalogu modelů.

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

Tento příklad zobrazí seznam dostupných modelů pro váš hardware.

Ukázky

Referenční informace k rozhraní API

Odkazy

Referenční informace k sadě C# SDK

Průvodce nastavením projektu

Pro sadu Foundry Local SDK existují dva balíčky NuGet – WinML a multiplatformní balíček – které mají stejnou plochu rozhraní API, ale jsou optimalizované pro různé platformy:

  • Windows: Používá balíček Microsoft.AI.Foundry.Local.WinML specifický pro aplikace systému Windows, který používá architekturu Windows Machine Learning (WinML).
  • Multiplatformní: Používá Microsoft.AI.Foundry.Local balíček, který lze použít pro multiplatformní aplikace (Windows, Linux, macOS).

V závislosti na cílové platformě podle těchto pokynů vytvořte novou aplikaci jazyka C# a přidejte potřebné závislosti:

Postupujte podle těchto pokynů specifických pro Windows nebo pro různé platformy (macOS/Linux/Windows), abyste použili Foundry Local ve vašem projektu v C#:

  1. Vytvořte nový projekt C# a přejděte do něj: 
    dotnet new console -n app-name
cd app-name
  2. Otevřete a upravte soubor app-name.csproj: 
    <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>

  <PropertyGroup Condition="'$(RuntimeIdentifier)'==''">
    <RuntimeIdentifier>$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
  </PropertyGroup>

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

</Project>
  3. V kořenovém adresáři projektu vytvořte nuget.config soubor s následujícím obsahem, aby se balíčky obnovily správně: 
    <?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>

Poznámka:

Balíček NuGet Microsoft.AI.Foundry.Local cílí na net8.0. Díky dopředné kompatibilitě .NET funguje bez problémů v projektech, které cílí na .NET 9, .NET 10 a novější – nevyžaduje žádnou další konfiguraci. Sada SDK používá pouze rozhraní API .NET 8 a neobsahuje žádné cesty kódu specifické pro architekturu, takže chování je stejné bez ohledu na to, na které modul runtime cílí vaše aplikace. My cílíme na .NET 8, protože se jedná o aktuální verzi dlouhodobé podpory (LTS) s nejširší instalační základnou.

Rychlý start

Pomocí tohoto úryvku kódu ověřte, že SDK může inicializovat a přistupovat k místnímu katalogu modelů.

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

Tento příklad vytiskne počet modelů dostupných pro váš hardware.

Ukázky

Referenční informace k rozhraní API

Nativní rozhraní API pro přepis zvuku

Sada SDK pro C# obsahuje nativního audio klienta pro přepis zvukových souborů na zařízení pomocí modelů Whisper. Tím se spustí proces odvozování bez nutnosti webového serveru REST.

Získání zvukového klienta

Po načtení modelu Whisper získejte zvukového klienta:

var audioClient = await model.GetAudioClientAsync();

Metody přepisu zvuku

Metoda Signature Description
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> Přenáší transkripční výsledky po částech. Každý blok dat má Text vlastnost.

Nastavení AudioClient

Vlastnictví Typ Description
Language string Kód jazyka ISO 639-1 (například "en"). Zlepšuje přesnost.
Temperature float Vzorkovací teplota (0,0–1,0). Nižší hodnoty jsou determinističtější.

Příklad

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

Referenční informace:

  • Last updated on