Lokalne odniesienia do zestawu SDK Foundry

Foundry Local SDK umożliwia dostarczanie funkcji sztucznej inteligencji w aplikacjach korzystających z lokalnych modeli sztucznej inteligencji za pomocą prostego i intuicyjnego interfejsu API. Zestaw SDK wyodrębnia złożoność zarządzania modelami sztucznej inteligencji i zapewnia bezproblemowe środowisko integracji lokalnych funkcji sztucznej inteligencji z aplikacjami. W tej dokumentacji przedstawiono implementacje zestawu SDK dla języków C#, C++, JavaScript, Python i Rust.

SDK nie wymaga zainstalowania lokalnego interfejsu wiersza polecenia Foundry na komputerze użytkowników końcowych, co umożliwia dostarczanie aplikacji bez dodatkowych kroków konfiguracji dla użytkowników — Twoje aplikacje są samodzielne. Dodatkowe korzyści lokalnego zestawu SDK Foundry obejmują:

  • Wykrywanie i optymalizacja sprzętu: automatyczna ocena możliwości procesora GPU, procesora NPU i procesora CPU.
  • Zarządzanie dostawcami wykonawczymi (Windows): Automatyczne pobieranie i rejestrowanie odpowiednich dostawców wykonawczych ONNX Runtime (CUDA, Vitis, QNN, OpenVINO, TensorRT) na podstawie możliwości urządzenia.
  • Obsługa systemu operacyjnego za pośrednictwem protokołu WebGpu (macOS): natywna obsługa uruchamiania modeli w systemie Apple Silicon ze zoptymalizowaną wydajnością.
  • Pozyskiwanie modelu: bezproblemowe pobieranie z Foundry Model Catalog z obsługą wersji, aktualizacji i automatycznym wyborem modelu zoptymalizowanego pod kątem sprzętu oraz z możliwością stosowania rezerwowych rozwiązań.
  • Wydajne środowisko uruchomieniowe: dodaje około 20 MB do rozmiaru aplikacji, działa na urządzeniach od telefonów komórkowych do komputerów stacjonarnych.
  • Zgodność interfejsu API openAI: łatwa integracja z modelami i narzędziami OpenAI.
  • Opcjonalny serwer REST: uruchom narzędzie Foundry Local jako usługę lokalną dostępną dla innych aplikacji.

Dokumentacja zestawu SDK języka C#

Instalowanie pakietów

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

Przykłady języka C# w repozytorium GitHub to wstępnie skonfigurowane projekty. Jeśli tworzysz od podstaw, zapoznaj się z dokumentacją zestawu SDK lokalnego rozwiązania Foundry , aby uzyskać więcej informacji na temat sposobu konfigurowania projektu w języku C# przy użyciu rozwiązania Foundry Local.

Konfiguracja projektu

Przykładowe repozytoria zawierają .csproj plik, który automatycznie obsługuje wykrywanie platformy. Jeśli tworzysz projekt od podstaw, użyj tej konfiguracji jako odwołania:

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

W poniższej tabeli opisano kluczowe ustawienia projektu:

Setting Opis
TargetFramework Dotyczy wersji .NET wymaganej przez przykład.
RuntimeIdentifier Domyślnie jest to identyfikator czasu wykonywania bieżącego pakietu SDK, zapewniając, że wybrano prawidłowe pliki binarne dla platformy.
Microsoft.AI.Foundry.Local Pakiet lokalnego zestawu SDK usługi Foundry dla Windows, macOS i Linux.

Szybki start

Użyj tego fragmentu kodu, aby sprawdzić, czy zestaw SDK może zainicjować katalog modeli lokalnych i uzyskać do niego dostęp.

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

W tym przykładzie wyświetlana jest liczba modeli dostępnych dla twojego sprzętu.

Próbki

Odniesienie do API

Natywny interfejs API transkrypcji audio

Zestaw SDK języka C# zawiera natywnego klienta audio do transkrypcji plików audio na urządzeniu przy użyciu modeli Whisper. Spowoduje to uruchomienie wnioskowania w procesie bez konieczności korzystania z serwera internetowego REST.

Pobierz klienta audio

Po załadowaniu modelu Whisper pobierz klienta audio:

var audioClient = await model.GetAudioClientAsync();

Metody transkrypcji audio

Metoda Signature Opis
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> Przesyła strumieniowo wyniki transkrypcji według fragmentu. Każdy fragment ma Text właściwość .

Ustawienia elementu AudioClient

Majątek Typ Opis
Language string Kod języka ISO 639-1 (na przykład "en"). Poprawia dokładność.
Temperature float Temperatura próbkowania (0,0–1,0). Niższe wartości są bardziej deterministyczne.

Przykład

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

Dokumentacja:

Dokumentacja zestawu SDK języka JavaScript

Instalowanie pakietów

npm install foundry-local-sdk openai

Szybki start

Użyj tego fragmentu kodu, aby sprawdzić, czy zestaw SDK może zainicjować katalog modeli lokalnych i uzyskać do niego dostęp.

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

W tym przykładzie zostanie wyświetlona lista dostępnych modeli sprzętu.

Próbki

Odniesienie do API

References

Dokumentacja zestawu SDK Python

Instalowanie pakietów

pip install foundry-local-sdk openai

Szybki start

Użyj tego fragmentu kodu, aby sprawdzić, czy zestaw SDK może zainicjować katalog modeli lokalnych i uzyskać do niego dostęp.

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

W tym przykładzie wyświetlana jest liczba modeli dostępnych dla twojego sprzętu.

Próbki

  • Aby uzyskać przykładowe aplikacje pokazujące, jak używać lokalnego SDK Python w rozwiązaniu Foundry, zobacz repozytorium GitHub: Foundry Local SDK Samples.

Konfiguracja

Klasa Configuration umożliwia dostosowanie zachowania zestawu 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"},
)
Parametr Typ Opis
app_name str Nazwa aplikacji.
log_level str Poziom rejestrowania (na przykład "info", "debug").
model_cache_dir str Katalog dla buforowanych modeli.
web dict Konfiguracja usługi internetowej z kluczem urls .

Główne API

Metoda Opis
FoundryLocalManager.initialize(config) Zainicjuj menedżera singletona za pomocą Configuration.
FoundryLocalManager.instance Uzyskaj dostęp do zainicjowanej instancji menedżera.
manager.catalog.list_models() Wyświetl listę wszystkich dostępnych modeli w wykazie.
manager.catalog.get_model(alias) Pozyskaj model po aliasie.
manager.catalog.get_cached_models() Wyświetlanie listy modeli w lokalnej pamięci podręcznej.
manager.catalog.get_loaded_models() Wyświetl listę aktualnie załadowanych modeli.
model.download(progress_callback) Pobierz model (pomija, jeśli jest buforowany).
model.load() Załaduj model do wnioskowania.
model.unload() Odładuj model.
model.is_cached Sprawdź, czy model jest buforowany lokalnie.
model.is_loaded Sprawdź, czy model został załadowany.

Natywny Interfejs API uzupełniania czatów

Po załadowaniu modelu pobierz klienta czatu:

client = model.get_chat_client()
Metoda Opis
client.complete_chat(messages) Wygeneruj pełną odpowiedź na czat.
client.complete_streaming_chat(messages) Fragmenty odpowiedzi czatu strumieniowego.

Natywny interfejs API transkrypcji audio

Po załadowaniu modelu Whisper pobierz klienta audio:

audio_client = model.get_audio_client()
Metoda Opis
audio_client.transcribe(file_path) Transkrypcja pliku audio. Zwraca obiekt z właściwością text .

Dokumentacja:

Dokumentacja zestawu Rust SDK

Instalowanie pakietów

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

Szybki start

Użyj tego fragmentu kodu, aby sprawdzić, czy zestaw SDK może zainicjować katalog modeli lokalnych i uzyskać do niego dostęp.

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

W tym przykładzie wyświetlana jest liczba modeli dostępnych dla twojego sprzętu.

Próbki

Konfiguracja

Struktura FoundryLocalConfig umożliwia dostosowanie zachowania zestawu 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");

Główne API

Metoda Opis
FoundryLocalManager::create(config) Utwórz nowego menedżera za pomocą polecenia FoundryLocalConfig.
manager.catalog().get_models().await Wyświetl listę wszystkich dostępnych modeli.
manager.catalog().get_model(alias).await Pozyskaj model po aliasie.
manager.catalog().get_cached_models().await Wyświetlanie listy modeli w lokalnej pamięci podręcznej.
manager.catalog().get_loaded_models().await Wyświetl listę aktualnie załadowanych modeli.
model.download(callback).await Pobierz model (pomija, jeśli jest buforowany).
model.load().await Załaduj model do wnioskowania.
model.unload().await Odładuj model.

Natywny Interfejs API uzupełniania czatów

Po załadowaniu modelu utwórz klienta czatu z opcjonalnymi ustawieniami:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
Metoda Opis
client.complete_chat(&messages, tools).await Wygeneruj pełną odpowiedź na czat.
client.complete_streaming_chat(&messages, tools).await Fragmenty odpowiedzi czatu strumieniowego.

Typy komunikatów: ChatCompletionRequestSystemMessage, , ChatCompletionRequestUserMessageChatCompletionRequestMessage.

Natywny interfejs API transkrypcji audio

Po załadowaniu modelu Whisper utwórz klienta audio:

let audio_client = model.create_audio_client();
Metoda Opis
audio_client.transcribe(file_path).await Transkrypcja pliku audio. Zwraca obiekt z polem text .

Dokumentacja:

Dokumentacja referencyjna zestawu SDK języka C++

Prerequisites

Zestaw SDK języka C++ udostępnia wrapper wyłącznie nagłówkowy dla natywnego środowiska uruchomieniowego Foundry Local. Wdrożona aplikacja nie wymaga narzędzia Foundry Local CLI ani środowiska uruchomieniowego .NET.

Sklonuj przykład czatu natywnego, aby rozpocząć od skonfigurowanego projektu CMake:

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

Przykłady języka C++ wymagają:

Skonfiguruj i skompiluj przykład:

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

Podczas konfiguracji przykład odtwarza pakiet NuGet w wersji 2.2.1 z Microsoft.AI.Foundry.Local.Runtime do build/_packages. Pakiet zawiera nagłówki języka C++ i biblioteki natywne dla Windows, Linux i macOS. Nie potrzebujesz oddzielnego pakietu WinML.

Konfiguracja narzędzia CMake wybiera zasoby środowiska uruchomieniowego dla Twojego systemu operacyjnego i architektury oraz kopiuje wymagane biblioteki natywne obok pliku wykonywalnego. W systemach macOS i Linux uruchom plik wykonywalny z build. W systemie Windows uruchom plik z build.

Wybierz zasoby natywne zgodne z systemem operacyjnym i architekturą aplikacji:

System operacyjny Architecture Identyfikator środowiska uruchomieniowego (RID)
Windows x64 lub ARM64 win-x64 lub win-arm64
Linux x64 lub ARM64 linux-x64 lub linux-arm64
macOS Apple silicon (ARM64) osx-arm64

Dodaj build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include do ścieżki dołączania kompilatora. Połącz bibliotekę natywną z pakietu build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native katalog:

  • foundry_local.lib w systemie Windows.
  • libfoundry_local.so w systemie Linux.
  • libfoundry_local.dylib w systemie macOS.

Umieść pasujące natywne biblioteki środowiska uruchomieniowego i zależności obok pliku wykonywalnego lub w ścieżce wyszukiwania bibliotek platformy. Zachowaj przywrócone wersje pakietów razem. Nie mieszaj nagłówków i bibliotek natywnych z różnych wersji.

Szybki start

Zastąp element main.cpp w przykładzie następującym kodem, aby zainicjować zestaw SDK i zliczyć modele w 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;
}

Przykład wypisuje Models available:, po którym następuje liczba modeli katalogu. Nie pobiera ani nie ładuje modelu. Utrzymuj menedżera przy życiu podczas korzystania z katalogu, modelu lub obiektów metadanych uzyskanych za jego pomocą.

Informacje referencyjne: deklaracje otoki języka C++ dla elementów Configuration, Manager i Catalog.

Główne API

Klasa opakowująca używa idiomu resource acquisition is initialization (RAII) w celu zwolnienia natywnych uchwytów, gdy obiekty wychodzą poza zakres.

API Opis
Manager{Configuration("app-name")} Zainicjuj menedżera z nazwą aplikacji.
manager.GetCatalog() Pobierz wykaz modeli.
catalog.GetModels() Wyświetl modele w katalogu.
catalog.GetModel(alias) Wyszukaj model według aliasu. Przed jego użyciem sprawdź zwrócony wskaźnik.
model->Download() Pobierz model do lokalnej pamięci podręcznej.
model->Load() Załaduj model do wnioskowania.
model->Unload() Zwolnij model z pamięci.
ChatSession::ProcessRequest(request) Uruchom żądanie czatu i zwróć odpowiedź.

Dokumentacja interfejsu API i przykłady

Użyj nagłówka publicznego i obsługiwanych przykładów dla kompletnego interfejsu API i przepływów pracy wnioskowania:

  • Ostatnia aktualizacja o