Foundry Yerel SDK referansı

Foundry Yerel SDK'sı, uygulamalarınızda yerel yapay zeka modellerini kullanan yapay zeka özelliklerini basit ve sezgisel bir API aracılığıyla sunmanızı sağlar. SDK, yapay zeka modellerini yönetmenin karmaşıklıklarını soyutlar ve yerel yapay zeka özelliklerini uygulamalarınızla tümleştirmek için sorunsuz bir deneyim sunar. Bu başvuru C#, C++, JavaScript, Python ve Rust için SDK uygulamalarını belgelemektedir.

SDK, Son kullanıcılar makinesine Foundry Local CLI'nın yüklenmesini gerektirmez ve kullanıcılarınız için ek kurulum adımları olmadan uygulamalarınızı göndermenize olanak tanır. Uygulamalarınız bağımsızdır. Foundry Yerel SDK'sının şu ek avantajları vardır:

  • Donanım algılama ve iyileştirme: GPU, NPU ve CPU için otomatik yetenek değerlendirmesi.
  • Execution sağlayıcı yönetimi (Windows): Cihaz özelliklerine göre uygun ONNX Çalışma Zamanı yürütme sağlayıcılarının (CUDA, Vitis, QNN, OpenVINO, TensorRT) otomatik olarak indirilmesi ve kaydedilmesi.
  • WebGpu (macOS) aracılığıyla metal desteği: Apple Silicon'da modelleri en iyi duruma getirilmiş performansla çalıştırmak için yerel destek.
  • Model edinme: Sürüm oluşturma, güncellemeler ve geri alma desteğiyle otomatik olarak donanım için optimize edilmiş model seçimiyle Foundry Model Kataloğu'ndan sorunsuz indirme.
  • Verimli çalışma zamanı: Uygulama boyutuna yaklaşık 20 MB ekler, cep telefonlarından masaüstlerine kadar cihazlarda çalışır.
  • OpenAI API uyumluluğu: OpenAI modelleri ve araçlarıyla kolay tümleştirme.
  • İsteğe bağlı REST sunucusu: Foundry Local'ı diğer uygulamalar tarafından erişilebilen bir yerel hizmet olarak çalıştırın.

C# SDK Referansı

Paketleri yükleme

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

GitHub deposundaki C# örnekleri önceden yapılandırılmış projelerdir. Sıfırdan oluşturuyorsanız, C# projenizi Foundry Local ile nasıl ayarlayacağınız hakkında daha fazla ayrıntı için Foundry Yerel SDK başvurusunu okumalısınız.

proje yapılandırması

Örnek depolar, platform algılamayı otomatik olarak işleyen bir .csproj dosya içerir. Sıfırdan bir proje oluşturuyorsanız bu yapılandırmayı başvuru olarak kullanın:

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

Aşağıdaki tabloda anahtar proje ayarları açıklanmaktadır:

Setting Açıklama
TargetFramework Örneğin gerektirdiği .NET sürümünü hedefler.
RuntimeIdentifier Varsayılan olarak geçerli SDK'nın çalışma zamanı tanımlayıcısını kullanır ve doğru platform ikili dosyalarının seçildiğinden emin olur.
Microsoft.AI.Foundry.Local Windows, macOS ve Linux için Foundry Yerel SDK paketi.

Hızlı Başlangıç

SDK'nin yerel model kataloğunu başlatıp erişebildiğini doğrulamak için bu kod parçacığını kullanın.

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

Bu örnek, donanımınız için kullanılabilen model sayısını yazdırır.

Örnekleri

API referansı

Doğal Ses Transkripsiyonu API'si

C# SDK'sı, Fısıltı modellerini kullanarak cihazdaki ses dosyalarının transkribesine yönelik yerel bir ses istemcisi içerir. Bu, REST web sunucusuna gerek kalmadan çıkarım işlemini çalıştırır.

Ses istemcisi alma

Whisper modelini yükledikten sonra bir ses istemcisi alın:

var audioClient = await model.GetAudioClientAsync();

Ses transkripsiyon yöntemleri

Yöntem Signature Açıklama
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> Döküm sonuçlarını öbeklere göre öbek olarak akışla gönderir. Her öbek bir Text özelliğe sahiptir.

AudioClient ayarları

Mülkiyet Türü Açıklama
Language string ISO 639-1 dil kodu (örneğin, "en"). Doğruluğu artırır.
Temperature float Örnekleme sıcaklığı (0,0–1,0). Düşük değerler daha belirleyicidir.

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

Referanslar:

JavaScript SDK Dokümanı

Paketleri yükleme

npm install foundry-local-sdk openai

Hızlı Başlangıç

SDK'nin yerel model kataloğunu başlatıp erişebildiğini doğrulamak için bu kod parçacığını kullanın.

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

Bu örnek, donanımınız için kullanılabilir modellerin listesini oluşturur.

Örnekleri

API referansı

Referanslar

Python SDK Referansı

Paketleri yükleme

pip install foundry-local-sdk openai

Hızlı Başlangıç

SDK'nin yerel model kataloğunu başlatıp erişebildiğini doğrulamak için bu kod parçacığını kullanın.

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

Bu örnek, donanımınız için kullanılabilen model sayısını yazdırır.

Örnekleri

Konfigürasyon

sınıfı SDK Configuration davranışını özelleştirmenize olanak tanır:

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"},
)
Parametre Türü Açıklama
app_name str Uygulamanızın adı.
log_level str Günlük düzeyi (örneğin, "info", "debug").
model_cache_dir str Önbelleğe alınmış modeller için dizin.
web dict Anahtarla web urls hizmeti yapılandırması.

Çekirdek API

Yöntem Açıklama
FoundryLocalManager.initialize(config) singleton yöneticisini Configuration ile başlatın.
FoundryLocalManager.instance Başlatılan yönetici örneğine erişin.
manager.catalog.list_models() Katalogdaki tüm kullanılabilir modelleri listeleyin.
manager.catalog.get_model(alias) Diğer adlara göre model alma.
manager.catalog.get_cached_models() Modelleri yerel önbellekte listeleyin.
manager.catalog.get_loaded_models() Şu anda yüklü olan modelleri listeleyin.
model.download(progress_callback) Modeli indirin (önbelleğe alınmışsa atlar).
model.load() Çıkarım için modeli yükleyin.
model.unload() Modeli kaldırın.
model.is_cached Modelin yerel olarak önbelleğe alınılıp alınmadığını denetleyin.
model.is_loaded Modelin yüklenip yüklenmediğini denetleyin.

Yerleşik Sohbet Tamamlama API'si

Modeli yükledikten sonra bir sohbet istemcisi alın:

client = model.get_chat_client()
Yöntem Açıklama
client.complete_chat(messages) Eksiksiz bir sohbet yanıtı oluşturun.
client.complete_streaming_chat(messages) Sohbet yanıt parçalarını akışla ilet.

Doğal Ses Transkripsiyonu API'si

Whisper modelini yükledikten sonra bir ses istemcisi alın:

audio_client = model.get_audio_client()
Yöntem Açıklama
audio_client.transcribe(file_path) Ses dosyasını yazıya dökme. Özelliği olan bir text nesne döndürür.

Referanslar:

Rust SDK Referans

Paketleri yükleme

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

Hızlı Başlangıç

SDK'nin yerel model kataloğunu başlatıp erişebildiğini doğrulamak için bu kod parçacığını kullanın.

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

Bu örnek, donanımınız için kullanılabilen model sayısını yazdırır.

Örnekleri

Konfigürasyon

Yapısı, FoundryLocalConfig SDK davranışını özelleştirmenize olanak tanır:

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

Çekirdek API

Yöntem Açıklama
FoundryLocalManager::create(config) yeni bir FoundryLocalConfig ile yönetici oluşturun.
manager.catalog().get_models().await Kullanılabilir tüm modelleri listeleyin.
manager.catalog().get_model(alias).await Diğer adlara göre model alma.
manager.catalog().get_cached_models().await Modelleri yerel önbellekte listeleyin.
manager.catalog().get_loaded_models().await Şu anda yüklü olan modelleri listeleyin.
model.download(callback).await Modeli indirin (önbelleğe alınmışsa atlar).
model.load().await Çıkarım için modeli yükleyin.
model.unload().await Modeli kaldırın.

Yerleşik Sohbet Tamamlama API'si

Modeli yükledikten sonra, isteğe bağlı ayarlarla bir sohbet istemcisi oluşturun:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
Yöntem Açıklama
client.complete_chat(&messages, tools).await Eksiksiz bir sohbet yanıtı oluşturun.
client.complete_streaming_chat(&messages, tools).await Sohbet yanıt parçalarını akışla ilet.

İleti türleri: ChatCompletionRequestSystemMessage, ChatCompletionRequestUserMessage, ChatCompletionRequestMessage.

Doğal Ses Transkripsiyonu API'si

Whisper modelini yükledikten sonra bir ses istemcisi oluşturun:

let audio_client = model.create_audio_client();
Yöntem Açıklama
audio_client.transcribe(file_path).await Ses dosyasını yazıya dökme. Alanı olan bir text nesne döndürür.

Referanslar:

C++ SDK referansı

Prerequisites

C++ SDK, yerel Foundry Local çalışma zamanını temel alan yalnızca başlık dosyasından oluşan bir sarmalayıcı sağlar. Dağıtılan uygulamanız Için Foundry Yerel CLI veya .NET çalışma zamanı gerekmez.

Yapılandırılmış bir CMake projesiyle başlamak için yerel sohbet örneğini kopyalayın:

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

C++ örnekleri şunları gerektirir:

  • CMake 3.20 veya üzeri.
  • C++20 derleyicisi.
  • PATH üzerindeki NuGet CLI.

Örneği yapılandırın ve derleyin:

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

Yapılandırma sırasında örnek, Microsoft.AI.Foundry.Local.Runtime NuGet paketinin 2.2.1 sürümünü build/_packages geri yükler. Paket Windows, Linux ve macOS için C++ başlık dosyalarını ve yerel kitaplıkları içerir. Ayrı bir WinML paketine ihtiyacınız yoktur.

CMake yapılandırması, işletim sisteminiz ve mimariniz için çalışma zamanı varlıklarını seçer ve gerekli yerel kitaplıkları yürütülebilir dosyanın yanına kopyalar. macOS ve Linux'ta, build içinden yürütülebilir dosyayı çalıştırın. Windows'ta, build konumundaki .exe dosyasını çalıştırın.

Uygulamanızın işletim sistemi ve mimarisiyle eşleşen yerel varlıkları seçin:

İşletim Sistemi Architecture Çalışma zamanı tanımlayıcısı (RID)
Windows x64 veya ARM64 win-x64 veya win-arm64
Linux x64 veya ARM64 linux-x64 veya linux-arm64
macOS Apple silikon (ARM64) osx-arm64

ekle build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include öğesini derleyicinizin include yoluna ekleyin. Paketin içindeki yerel kitaplığı bağlayın build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native dizin:

  • foundry_local.libWindows'ta.
  • libfoundry_local.so linux'ta.
  • libfoundry_local.dylib macOS'ta.

Eşleşen yerel çalışma zamanını ve bağımlılık kitaplıklarını yürütülebilir dosyanızın yanına veya platformun kitaplık arama yoluna dağıtın. Geri yüklenen paket sürümlerini birlikte tutun. Farklı sürümlerdeki üst bilgileri ve yerel kitaplıkları karıştırmayın.

Hızlı Başlangıç

SDK'yi başlatmak ve katalogdaki modelleri saymak için örneğin main.cpp öğesini aşağıdaki kodla değiştirin:

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

Örnek, Models available: öğesini ve ardından kataloğun model sayısını yazdırır. Bir modeli indirmez veya yüklemez. Katalog, model veya ondan alınan meta veri nesnelerini kullanırken yöneticiyi canlı tutun.

Referans: Manager, Catalog ve Configuration için C++ sarmalayıcı bildirimleri.

Çekirdek API

Sarmalayıcı, nesneler kapsam dışına çıktığında yerel tanıtıcıları serbest bırakmak için resource acquisition is initialization (RAII) kullanır.

API Açıklama
Manager{Configuration("app-name")} Bir yönetici nesnesini uygulama adıyla başlatın.
manager.GetCatalog() Model kataloğunu alın.
catalog.GetModels() Katalogdaki modelleri listeleyin.
catalog.GetModel(alias) Takma ada göre model arayın. Kullanmadan önce döndürülen işaretçiyi denetleyin.
model->Download() Modeli yerel önbelleğe indirin.
model->Load() Çıkarım için bir model yükleyin.
model->Unload() Modeli bellekten kaldırın.
ChatSession::ProcessRequest(request) Bir sohbet isteği çalıştırın ve bir yanıt döndürün.

API referansı ve örnekleri

Tam API ve çıkarım iş akışları için public header dosyasını ve bakımlı örnekleri kullanın:

  • Son güncelleştirme: