Referenční informace k local SDK od Foundry

Sada Foundry Local SDK umožňuje dodávat funkce AI ve vašich aplikacích, které umožňují použí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í. Tato referenční dokumentace dokumentuje implementaci sady SDK pro C#, JavaScript, Python a Rust.

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 poskytovatelů zpracování (Windows): Automatické stahování a registrace příslušných poskytovatelů zpracování ONNX Runtime (CUDA, Vitis, QNN, OpenVINO, TensorRT) na základě schopností 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 řízením verzí, aktualizacemi a automatickým výběrem modelů optimalizovaných pro hardware s podporou záložního řešení.
  • Efektivní runtime: Do velikosti aplikace se přidává přibližně 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ě C# SDK

Instalace balíčků

Pokud vyvíjíte nebo vydáváte aplikace na Windows, vyberte kartu Windows. Balíček Windows se integruje s runtime modulem Windows ML — poskytuje stejné rozhraní API a nabízí širší možnosti hardwarové akcelerace.

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

Ukázky jazyka C# v úložišti GitHub jsou předkonfigurované projekty. Pokud vytváříte úplně od začátku, měli byste si přečíst referenční informace k místní sadě SDK Foundry , kde najdete další podrobnosti o tom, jak nastavit projekt jazyka C# pomocí Foundry Local.

konfigurace projektu

Ukázková úložiště obsahují .csproj soubor, který automaticky zpracovává detekci platformy. Pokud vytváříte projekt úplně od začátku, použijte tuto konfiguraci jako referenci:

<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.18362.0</TargetFramework>
    <Platforms>ARM64;x64</Platforms>
    <WindowsPackageType>None</WindowsPackageType>
    <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
  </PropertyGroup>

  <!-- Non-Windows: standard .NET -->
  <PropertyGroup Condition="!$([MSBuild]::IsOSPlatform('Windows'))">
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

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

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

V následující tabulce jsou vysvětlená klíčová nastavení projektu:

Setting Description
TargetFramework Na Windows cílí na hardwarovou akceleraci WinML net9.0-windows10.0.26100. Na jiných platformách cíle net9.0.
WindowsAppSDKSelfContained Nastavte na hodnotu false tak, aby používala systémovou nainstalovanou Windows App SDK místo jeho sdružování.
WindowsPackageType Nastavte None pro sestavení jako nerozbalenou desktopovou aplikaci (bez balení MSIX).
EnableCoreMrtTooling Nastavte na false pro zakázání nástrojů prostředků MRT Core, které nejsou potřeba pro konzolové aplikace.
RuntimeIdentifier Výchozím nastavením je použití identifikátoru běhového prostředí aktuální sady SDK, což zajišťuje výběr správných binárních souborů pro danou platformu.
Microsoft.AI.Foundry.Local.WinML Windows balíček, který používá WinML pro hardwarovou akceleraci a automatickou správu poskytovatele spouštění.
Microsoft.AI.Foundry.Local Multiplatformní balíček pro macOS, Linux a Windows bez WinML.
Microsoft.ML.OnnxRuntime.Gpu / OnnxRuntimeGenAI.Cuda Linux GPU podporuje balíčky hardwaru s podporou CUDA.

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:

Referenční informace k sadě JavaScript SDK

Instalace balíčků

Pokud vyvíjíte nebo vydáváte aplikace na Windows, vyberte kartu Windows. Balíček Windows se integruje s runtime modulem Windows ML — poskytuje stejné rozhraní API a nabízí širší možnosti hardwarové akcelerace.

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

Instalace balíčků

Pokud vyvíjíte nebo vydáváte aplikace na Windows, vyberte kartu Windows. Balíček Windows se integruje s runtime modulem Windows ML — poskytuje stejné rozhraní API a nabízí širší možnosti hardwarové akcelerace.

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

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

Ukázky

Konfigurace

Třída Configuration umožňuje přizpůsobit chování sady SDK:

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 Description
app_name str Název aplikace.
log_level str Úroveň protokolování (například "info", "debug").
model_cache_dir str Adresář pro modely uložené v mezipaměti
web dict Konfigurace webové služby s urls klíčem

Základní rozhraní API

Metoda Description
FoundryLocalManager.initialize(config) Inicializace singletonového manažera Configurationpomocí .
FoundryLocalManager.instance Získejte přístup k inicializované instanci správce.
manager.catalog.list_models() Zobrazí seznam všech dostupných modelů v katalogu.
manager.catalog.get_model(alias) Získejte model podle aliasu
manager.catalog.get_cached_models() Vypisujte modely v místní mezipaměti.
manager.catalog.get_loaded_models() Seznam aktuálně načtených modelů
model.download(progress_callback) Stáhněte si model (přeskočí se, pokud je uložený v mezipaměti).
model.load() Načtěte model pro odvozování.
model.unload() Uvolněte model.
model.is_cached Zkontrolujte, jestli je model místně uložený v mezipaměti.
model.is_loaded Zkontrolujte, jestli je model načtený.

Rozhraní API pro automatické dokončování nativních chatů

Po načtení modelu získejte chatovacího klienta:

client = model.get_chat_client()
Metoda Description
client.complete_chat(messages) Vygenerujte úplnou odpověď chatu.
client.complete_streaming_chat(messages) Streamování bloků odpovědí chatu

Nativní rozhraní API pro přepis zvuku

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

audio_client = model.get_audio_client()
Metoda Description
audio_client.transcribe(file_path) Přepis zvukového souboru. Vrátí objekt s text vlastností.

Referenční informace:

Referenční informace k sadě Rust SDK

Instalace balíčků

Pokud vyvíjíte nebo vydáváte aplikace na Windows, vyberte kartu Windows. Balíček Windows se integruje s runtime modulem Windows ML — poskytuje stejné rozhraní API a nabízí širší možnosti hardwarové akcelerace.

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

Rychlý start

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

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

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

Ukázky

Konfigurace

Struktura FoundryLocalConfig umožňuje přizpůsobit chování sady SDK:

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

Základní rozhraní API

Metoda Description
FoundryLocalManager::create(config) Vytvořte nového manažera pomocí příkazu FoundryLocalConfig.
manager.catalog().get_models().await Zobrazí seznam všech dostupných modelů.
manager.catalog().get_model(alias).await Získejte model podle aliasu
manager.catalog().get_cached_models().await Vypisujte modely v místní mezipaměti.
manager.catalog().get_loaded_models().await Seznam aktuálně načtených modelů
model.download(callback).await Stáhněte si model (přeskočí se, pokud je uložený v mezipaměti).
model.load().await Načtěte model pro odvozování.
model.unload().await Uvolněte model.

Rozhraní API pro automatické dokončování nativních chatů

Po načtení modelu vytvořte chatovacího klienta s volitelným nastavením:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
Metoda Description
client.complete_chat(&messages, tools).await Vygenerujte úplnou odpověď chatu.
client.complete_streaming_chat(&messages, tools).await Streamování bloků odpovědí chatu

Typy zpráv: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage. ChatCompletionRequestMessage

Nativní rozhraní API pro přepis zvuku

Po načtení modelu Whisper vytvořte zvukového klienta:

let audio_client = model.create_audio_client();
Metoda Description
audio_client.transcribe(file_path).await Přepis zvukového souboru. Vrátí objekt s polem text .

Referenční informace:

  • Last updated on