Referensi SDK Lokal Foundry

Foundry Local SDK memungkinkan Anda untuk menghadirkan fitur AI dalam aplikasi Anda yang menggunakan model AI lokal melalui API sederhana dan intuitif. SDK mengabstraksi kompleksitas pengelolaan model AI dan memberikan pengalaman yang mulus untuk mengintegrasikan kemampuan AI lokal ke dalam aplikasi Anda. Referensi ini mendokumentasikan implementasi SDK untuk C#, C++, JavaScript, Python, dan Rust.

SDK tidak mengharuskan Foundry Local CLI diinstal pada komputer pengguna akhir, memungkinkan Anda untuk mengirim aplikasi Anda tanpa langkah-langkah penyiapan tambahan untuk pengguna Anda - aplikasi Anda mandiri. Manfaat tambahan dari Foundry Local SDK meliputi:

Deteksi dan pengoptimalan perangkat keras: Penilaian kemampuan otomatis untuk GPU, NPU, dan CPU.
Manajemen penyedia eksekusi (Windows): Pengunduhan dan pendaftaran otomatis penyedia eksekusi ONNX Runtime yang sesuai (CUDA, Vitis, QNN, OpenVINO, TensorRT) berdasarkan kemampuan perangkat.
Dukungan logam melalui WebGpu (macOS): Dukungan asli untuk menjalankan model di Apple Silicon dengan performa yang dioptimalkan.
Akuisisi model: Unduhan tanpa hambatan dari Foundry Model Catalog dengan penerapan versi, pembaruan, dan pemilihan model yang dioptimalkan perangkat keras secara otomatis dengan dukungan fallback.
Runtime yang efisien: Menambahkan sekitar 20 MB ke ukuran aplikasi, berjalan pada perangkat dari ponsel ke desktop.
Kompatibilitas OPENAI API: Integrasi mudah dengan model dan alat OpenAI.
Server REST opsional: Jalankan Foundry Local sebagai layanan lokal yang dapat diakses oleh aplikasi lain.

Referensi C# SDK

Memasang paket

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

Sampel C# di repositori GitHub adalah proyek yang telah dikonfigurasi sebelumnya. Jika Anda membangun dari awal, Anda harus membaca referensi Foundry Local SDK untuk detail selengkapnya tentang cara menyiapkan proyek C# Anda dengan Foundry Local.

konfigurasi proyek

Repositori sampel menyertakan .csproj file yang menangani deteksi platform secara otomatis. Jika Anda membangun proyek dari awal, gunakan konfigurasi ini sebagai referensi:

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

Tabel berikut menjelaskan pengaturan proyek utama:

Setting	Deskripsi
`TargetFramework`	Menargetkan versi .NET yang diperlukan oleh contoh.
`RuntimeIdentifier`	Default ke pengidentifikasi runtime SDK saat ini, memastikan biner platform yang benar dipilih.
`Microsoft.AI.Foundry.Local`	Paket SDK Lokal Foundry untuk Windows, macOS, dan Linux.

Mulai Cepat

Gunakan cuplikan ini untuk memverifikasi bahwa SDK dapat menginisialisasi dan mengakses katalog model lokal.

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

Contoh ini mencetak jumlah model yang tersedia untuk perangkat keras Anda.

Samples

Untuk aplikasi sampel yang menunjukkan cara menggunakan Foundry Local C# SDK, lihat sampel Foundry Local C# SDK GitHub repositori.

Referensi API

Untuk detail selengkapnya tentang Foundry Local C# SDK baca Foundry Local C# SDK API Reference.

API Transkripsi Audio Asli

C# SDK menyertakan klien audio bawaan untuk mentranskripsi file audio di perangkat menggunakan model Whisper. Ini menjalankan inferensi dalam proses tanpa memerlukan server web REST.

Dapatkan klien perangkat lunak audio

Setelah memuat model Whisper, dapatkan klien audio:

var audioClient = await model.GetAudioClientAsync();

Metode transkripsi audio

Metode	Signature	Deskripsi
`TranscribeAudioStreamingAsync()`	`(string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk>`	Mengalirkan hasil transkripsi sepotong demi sepotong. Setiap gugus memiliki properti `Text`.

Pengaturan AudioClient

Harta benda	Tipe	Deskripsi
`Language`	`string`	Kode bahasa ISO 639-1 (misalnya, `"en"`). Meningkatkan akurasi.
`Temperature`	`float`	Suhu pengambilan sampel (0,0–1,0). Nilai yang lebih rendah lebih deterministik.

Example

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

Referensi:

Mentranskripsikan file audio dengan Foundry Local

Referensi JavaScript SDK

Memasang paket

npm install foundry-local-sdk openai

Mulai Cepat

Gunakan cuplikan ini untuk memverifikasi bahwa SDK dapat menginisialisasi dan mengakses katalog model lokal.

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

Contoh ini menghasilkan daftar model yang tersedia untuk perangkat keras Anda.

Samples

Untuk aplikasi sampel yang menunjukkan cara menggunakan Foundry Local JavaScript SDK, lihat Sampel SDK JavaScript Lokal Foundry GitHub repositori.

Referensi API

Untuk detail selengkapnya tentang Foundry Local JavaScript SDK baca Foundry Local JavaScript SDK API Reference.

Referensi

Referensi SDK Python

Memasang paket

pip install foundry-local-sdk openai

Mulai Cepat

Gunakan cuplikan ini untuk memverifikasi bahwa SDK dapat menginisialisasi dan mengakses katalog model lokal.

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

Contoh ini mencetak jumlah model yang tersedia untuk perangkat keras Anda.

Samples

Untuk aplikasi sampel yang menunjukkan cara menggunakan Foundry Local Python SDK, lihat sampel SDK Lokal Foundry GitHub repositori.

Konfigurasi

Kelas ini Configuration memungkinkan Anda untuk menyesuaikan perilaku 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	Tipe	Deskripsi
`app_name`	`str`	Nama aplikasi Anda.
`log_level`	`str`	Tingkat pengelogan (misalnya, `"info"`, `"debug"`).
`model_cache_dir`	`str`	Direktori untuk model yang di-cache.
`web`	`dict`	Konfigurasi layanan web dengan `urls` kunci.

API Inti

Metode	Deskripsi
`FoundryLocalManager.initialize(config)`	Inisialisasi manajer singleton dengan `Configuration`.
`FoundryLocalManager.instance`	Akses instans manajer yang diinisialisasi.
`manager.catalog.list_models()`	Cantumkan semua model yang tersedia di katalog.
`manager.catalog.get_model(alias)`	Dapatkan model dengan alias.
`manager.catalog.get_cached_models()`	Mencantumkan model di cache lokal.
`manager.catalog.get_loaded_models()`	Daftar model yang saat ini dimuat.
`model.download(progress_callback)`	Unduh model (lompati jika di-cache).
`model.load()`	Muat model untuk inferensi.
`model.unload()`	Membongkar model.
`model.is_cached`	Periksa apakah model di-cache secara lokal.
`model.is_loaded`	Periksa apakah model dimuat.

API Penyelesaian Obrolan Bawaan

Setelah memuat model, dapatkan klien obrolan:

client = model.get_chat_client()

Metode	Deskripsi
`client.complete_chat(messages)`	Hasilkan respons obrolan lengkap.
`client.complete_streaming_chat(messages)`	Streaming potongan respons obrolan.

API Transkripsi Audio Asli

Setelah memuat model Whisper, dapatkan klien audio:

audio_client = model.get_audio_client()

Metode	Deskripsi
`audio_client.transcribe(file_path)`	Mentranskripsikan file audio. Mengembalikan objek dengan properti `text`.

Referensi:

Referensi SDK Rust

Memasang paket

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

Mulai Cepat

Gunakan cuplikan ini untuk memverifikasi bahwa SDK dapat menginisialisasi dan mengakses katalog model lokal.

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

Contoh ini mencetak jumlah model yang tersedia untuk perangkat keras Anda.

Samples

Untuk aplikasi sampel yang menunjukkan cara menggunakan Foundry Local Rust SDK, lihat repositori GitHub Foundry Local SDK Samples.

Konfigurasi

Struct FoundryLocalConfig memungkinkan Anda untuk menyesuaikan perilaku 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");

API Inti

Metode	Deskripsi
`FoundryLocalManager::create(config)`	Buat manajer baru dengan `FoundryLocalConfig`.
`manager.catalog().get_models().await`	Mencantumkan semua model yang tersedia.
`manager.catalog().get_model(alias).await`	Dapatkan model dengan alias.
`manager.catalog().get_cached_models().await`	Mencantumkan model di cache lokal.
`manager.catalog().get_loaded_models().await`	Daftar model yang saat ini dimuat.
`model.download(callback).await`	Unduh model (lompati jika di-cache).
`model.load().await`	Muat model untuk inferensi.
`model.unload().await`	Membongkar model.

API Penyelesaian Obrolan Bawaan

Setelah memuat model, buat klien obrolan dengan pengaturan opsional:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);

Metode	Deskripsi
`client.complete_chat(&messages, tools).await`	Hasilkan respons obrolan lengkap.
`client.complete_streaming_chat(&messages, tools).await`	Streaming potongan respons obrolan.

Jenis pesan: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage, ChatCompletionRequestMessage.

API Transkripsi Audio Asli

Setelah memuat model Whisper, buat klien audio:

let audio_client = model.create_audio_client();

Metode	Deskripsi
`audio_client.transcribe(file_path).await`	Mentranskripsikan file audio. Mengembalikan objek dengan `text` field.

Referensi:

Referensi C++ SDK

Prerequisites

SDK C++ menyediakan wrapper header-only di atas runtime Foundry Local native. Aplikasi yang Anda sebarkan tidak memerlukan Foundry Local CLI atau runtime .NET.

Klon sampel obrolan asli untuk memulai dengan proyek CMake yang dikonfigurasi:

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

Sampel C++ memerlukan:

CMake 3.20 atau yang lebih baru.
Kompiler C++20.
NuGet CLI di PATH Anda.

Konfigurasikan dan buat sampel:

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

Selama konfigurasi, sampel memulihkan versi 2.2.1 dari Microsoft.AI.Foundry.Local.Runtime paket NuGet ke build/_packages. Paket berisi header C++ dan pustaka asli untuk Windows, Linux, dan macOS. Anda tidak memerlukan paket WinML terpisah.

Konfigurasi CMake memilih aset runtime untuk sistem operasi dan arsitektur Anda dan menyalin pustaka asli yang diperlukan di samping file executable. Di macOS dan Linux, jalankan executable dari build. Pada Windows, jalankan .exe file dari build.

Pilih aset asli yang cocok dengan sistem operasi dan arsitektur aplikasi Anda:

Sistem operasi	Architecture	Pengidentifikasi runtime (RID)
Windows	x64 atau ARM64	`win-x64` atau `win-arm64`
Linux	x64 atau ARM64	`linux-x64` atau `linux-arm64`
macOS	Silikon Apple (ARM64)	`osx-arm64`

Tambahkan build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include ke jalur include kompilator Anda. Menautkan pustaka asli dari "paket" build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native direktori:

foundry_local.libdi Windows.
libfoundry_local.so di Linux.
libfoundry_local.dylib di macOS.

Tempatkan pustaka runtime dan dependensi asli yang cocok di samping executable Anda atau di jalur pencarian pustaka platform. Simpan versi paket yang dipulihkan tetap bersama. Jangan mencampur header dan pustaka asli dari rilis yang berbeda.

Mulai Cepat

Ganti main.cpp milik sampel dengan kode berikut untuk menginisialisasi SDK dan menghitung model dalam katalog:

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

Contoh mencetak Models available: diikuti dengan jumlah model katalog. Tidak mengunduh atau memuat model. Pertahankan manajer tetap aktif saat Anda menggunakan katalog, model, atau objek metadata yang diperoleh darinya.

Referensi: Deklarasi pembungkus C++ untuk Configuration, Manager, dan Catalog.

API Inti

Wrapper menggunakan Resource Acquisition Is Initialization (RAII) untuk melepaskan native handle saat objek keluar dari scope.

API	Deskripsi
`Manager{Configuration("app-name")}`	Menginisialisasi manajer dengan nama aplikasi.
`manager.GetCatalog()`	Dapatkan katalog model.
`catalog.GetModels()`	Cantumkan model dalam katalog.
`catalog.GetModel(alias)`	Cari model berdasarkan alias. Periksa penunjuk yang dikembalikan sebelum menggunakannya.
`model->Download()`	Unduh model ke cache lokal.
`model->Load()`	Muat model untuk inferensi.
`model->Unload()`	Membongkar model dari memori.
`ChatSession::ProcessRequest(request)`	Jalankan permintaan obrolan dan kembalikan respons.

Referensi API dan sampel

Gunakan header publik dan contoh yang dipertahankan untuk API lengkap dan alur kerja inferensi:

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-11-05

Referensi SDK Lokal Foundry

Referensi C# SDK

Memasang paket

konfigurasi proyek

Mulai Cepat

Samples

Referensi API

API Transkripsi Audio Asli

Dapatkan klien perangkat lunak audio

Metode transkripsi audio

Pengaturan AudioClient

Example

Referensi JavaScript SDK

Memasang paket

Mulai Cepat

Samples

Referensi API

Referensi

Referensi SDK Python

Memasang paket

Mulai Cepat

Samples

Konfigurasi

API Inti

API Penyelesaian Obrolan Bawaan

API Transkripsi Audio Asli

Referensi SDK Rust

Memasang paket

Mulai Cepat

Samples

Konfigurasi

API Inti

API Penyelesaian Obrolan Bawaan

API Transkripsi Audio Asli

Referensi C++ SDK

Prerequisites

Mulai Cepat

API Inti

Referensi API dan sampel

Saran dan Komentar

Sumber Daya Tambahan: