Referenční informace k local SDK od Foundry

Sada Foundry Local SDK umožňuje nasazovat funkce AI ve vašich aplikacích, které používají 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 reference dokumentuje implementace sady SDK pro C#, 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ů

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

  <ItemGroup>
    <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 Cílí na verzi .NET vyžadovanou ukázkou.
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 Balíček Foundry Local SDK pro Windows, macOS a Linux.

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ů

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

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

cargo add foundry-local-sdk
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:

Referenční příručka sady C++ SDK

Prerequisites

Sada C++ SDK poskytuje obálku tvořenou pouze hlavičkovými soubory nad nativním runtime Foundry Local. Nasazená aplikace nevyžaduje Foundry Local CLI ani modul runtime .NET.

Naklonujte ukázku nativního chatu a začněte s nakonfigurovaným projektem CMake:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/cpp/foundry-local/native-chat-completions

Ukázky C++ vyžadují:

Nakonfigurujte a sestavte ukázku:

cmake -S . -B build
cmake --build build --config Release

Během konfigurace ukázka obnoví balíček NuGet verze 2.2.1 Microsoft.AI.Foundry.Local.Runtime do build/_packages. Balíček obsahuje hlavičky C++ a nativní knihovny pro Windows, Linux a macOS. Nepotřebujete samostatný balíček WinML.

Konfigurace CMake vybere prostředky modulu runtime pro váš operační systém a architekturu a zkopíruje požadované nativní knihovny vedle spustitelného souboru. V systému macOS a Linux spusťte spustitelný soubor z build. V systému Windows spusťte soubor .exe z umístění build.

Vyberte nativní prostředky, které odpovídají operačnímu systému a architektuře vaší aplikace:

Operační systém Architecture Identifikátor modulu runtime (RID)
Windows x64 nebo ARM64 win-x64 nebo win-arm64
Linux x64 nebo ARM64 linux-x64 nebo linux-arm64
macOS Čip Apple (ARM64) osx-arm64

Přidat build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include do cesty pro zahrnované soubory kompilátoru. Propojte nativní knihovnu z balíčku build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native adresář:

  • foundry_local.libna Windows.
  • libfoundry_local.so v Linuxu.
  • libfoundry_local.dylib v systému macOS.

Nasaďte odpovídající nativní běhové prostředí a knihovny závislostí vedle spustitelného souboru nebo do cesty hledání knihoven platformy. Uchovávejte obnovené verze balíčků pohromadě. Nekombinujte hlavičky a nativní knihovny z různých verzí.

Rychlý start

Nahraďte v ukázce main.cpp následujícím kódem, který inicializuje sadu SDK a spočítá modely v katalogu:

#include <foundry_local/foundry_local_cpp.h>

#include <iostream>

using namespace foundry_local;

int main() {
    try {
        Manager manager{Configuration("app-name")};
        auto models = manager.GetCatalog().GetModels();
        std::cout << "Models available: " << models.size() << "\n";
    } catch (const Error& error) {
        std::cerr << "Foundry Local error [" << error.Code()
                  << "]: " << error.what() << "\n";
        return 1;
    }
    return 0;
}

Příklad vytiskne Models available:, za kterým následuje počet modelů katalogu. Nestahuje ani nenačítá model. Během používání objektů katalogu, modelu nebo metadat získaných z něj udržujte správce naživu.

Reference: Deklarace obálky jazyka C++ pro Configuration, Manager a Catalog.

Základní rozhraní API

Obal používá princip „získání prostředku je inicializace“ (RAII) k uvolnění nativních popisovačů, když objekty přestanou být v platnosti.

API Description
Manager{Configuration("app-name")} Inicializovat správce s názvem aplikace.
manager.GetCatalog() Získejte katalog modelů.
catalog.GetModels() Vypište seznam modelů v katalogu.
catalog.GetModel(alias) Vyhledejte model podle aliasu. Před použitím vráceného ukazatele jej zkontrolujte.
model->Download() Stáhněte model do místní mezipaměti.
model->Load() Načtení modelu pro odvozování
model->Unload() Uvolněte model z paměti.
ChatSession::ProcessRequest(request) Spusťte žádost o chat a vraťte odpověď.

Referenční informace k rozhraní API a ukázky

Pro kompletní pracovní postupy rozhraní API a inference použijte veřejnou hlavičku a udržované příklady: