Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
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
- Ukázkové aplikace, které ukazují, jak používat Foundry Local C# SDK sadu, najdete v GitHub úložišti s ukázkami Foundry Local C# SDK.
Referenční informace k rozhraní API
- Další podrobnosti o sadě Foundry Local C# SDK najdete v referenčních informacích k rozhraní API sady Foundry Local C# SDK.
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
- Pro ukázky aplikací, které demonstrují, jak používat Foundry Local JavaScript SDK, navštivte GitHub úložiště Foundry Local JavaScript SDK Samples.
Referenční informace k rozhraní API
- Další podrobnosti o sadě Foundry Local JavaScript SDK najdete v referenčních informacích k rozhraní API sady Foundry Local JavaScript SDK.
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
- Ukázkové aplikace demonstrující použití sady Foundry Local Python SDK najdete v GitHub úložišti Foundry Local SDK Samples.
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
- Ukázkové aplikace, které demonstrují, jak používat Foundry Local Rust SDK, najdete v GitHub úložišti Foundry Local SDK Samples.
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í:
- CMake 3.20 nebo novější
- Kompilátor C++20.
- Rozhraní příkazového řádku NuGet ve vašem
PATH.
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.sov Linuxu. -
libfoundry_local.dylibv 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: