Aracılığıyla paylaş

Foundry Yerel SDK referansı

Önemli

  • Foundry Local önizleme aşamasındadır. Genel önizleme sürümleri, etkin dağıtımdaki özelliklere erken erişim sağlar.
  • Özellikler, yaklaşımlar ve işlemler, Genel Kullanılabilirlik (GA) öncesinde değişebilir veya sınırlı özelliklere sahip olabilir.

Foundry Local SDK, veri düzlemi çıkarım kodundan ayrı denetim düzlemi işlemleri sağlayarak yerel ortamlarda yapay zeka modeli yönetimini basitleştirir. Bu başvuru Python, JavaScript, C# ve Rust için SDK uygulamalarını belgelemektedir.

Python SDK Referansı

Önkoşullar

  • Foundry Local'ı yükleyin ve foundry üzerinde PATH komutunun kullanılabilir olduğundan emin olun.
  • Python 3.9 veya sonraki bir sürümü kullanın.

Kurulum

Python paketini yükleyin:

pip install foundry-local-sdk

Hızlı Başlangıç

SDK'nın hizmeti başlatıp yerel kataloğa ulaşabildiğini doğrulamak için bu kod parçacığını kullanın.

from foundry_local import FoundryLocalManager

manager = FoundryLocalManager()
manager.start_service()

catalog = manager.list_catalog_models()
print(f"Catalog models available: {len(catalog)}")

Bu örnek, hizmet çalışırken ve katalog kullanılabilir olduğunda sıfır olmayan bir sayı yazdırır.

Kaynaklar:

FoundryLocalManager Sınıfı

sınıfı FoundryLocalManager modelleri, önbelleği ve Foundry Local hizmetini yönetmek için yöntemler sağlar.

Başlatma Aşaması

from foundry_local import FoundryLocalManager

# Initialize and optionally bootstrap with a model
manager = FoundryLocalManager(alias_or_model_id=None, bootstrap=True)
  • alias_or_model_id: (isteğe bağlı) Başlangıçta indirmek ve yüklemek için takma ad veya Model Kimliği.
  • bootstrap: (varsayılan True) True ise, çalışmıyorsa hizmeti başlatır ve sağlanırsa modeli yükler.

Diğer adlar hakkında bir not

Bu kaynakta özetlenen birçok yöntemin tanımında bir alias_or_model_id parametresi vardır. Bir takma adı veya model kimliğini yöntemine değer olarak geçirebilirsiniz. Bir takma ad kullanmanın sonuçları:

  • Kullanılabilir donanım için en iyi modeli seçin. Örneğin, bir Nvidia CUDA GPU varsa, Foundry Local CUDA modelini seçer. Desteklenen bir NPU varsa, Foundry Local NPU modelini seçer.
  • Model kimliğini hatırlamanıza gerek kalmadan daha kısa bir ad kullanmanıza olanak sağlar.

Tavsiye

alias_or_model_id parametresine bir diğer ad geçirmenizi öneriyoruz çünkü uygulamanızı dağıttığınızda Foundry Local, çalışma anında son kullanıcının makinesi için en iyi modeli edinir.

Uyarı

Windows üzerinde bir Intel NPU'nuz varsa, en iyi NPU hızlandırması için Intel NPU sürücüsünü yüklediğinizden emin olun.

Servis Yönetimi

Yöntem Signature Description
is_service_running() () -> bool Foundry Local hizmetinin çalışıp çalışmadığını denetler.
start_service() () -> None Foundry Local hizmetini başlatır.
service_uri @property -> str Hizmet URI'sini döndürür.
endpoint @property -> str Hizmet uç noktasını döndürür.
api_key @property -> str API anahtarını döndürür (env veya varsayılandan).

Katalog Yönetimi

Yöntem Signature Description
list_catalog_models() () -> list[FoundryModelInfo] Katalogdaki tüm kullanılabilir modelleri listeler.
refresh_catalog() () -> None Model kataloğunu yeniler.
get_model_info() (alias_or_model_id: str, raise_on_not_found=False) -> FoundryModelInfo \| None Diğer ad veya kimlikle model bilgilerini alır.

Önbellek Yönetimi

Yöntem Signature Description
get_cache_location() () -> str Model önbelleği dizin yolunu döndürür.
list_cached_models() () -> list[FoundryModelInfo] Yerel önbelleğe indirilen modelleri listeler.

Model Yönetimi

Yöntem Signature Description
download_model() (alias_or_model_id: str, token: str = None, force: bool = False) -> FoundryModelInfo Modeli yerel önbelleğe indirir.
load_model() (alias_or_model_id: str, ttl: int = 600) -> FoundryModelInfo Modeli çıkarım sunucusuna yükler.
unload_model() (alias_or_model_id: str, force: bool = False) -> None Bir modeli çıkarım sunucusundan kaldırır.
list_loaded_models() () -> list[FoundryModelInfo] Hizmette yüklü olan tüm modelleri listeler.

FoundryModelInfo

, list_catalog_models()ve list_cached_models() yöntemleri list_loaded_models()nesnelerin listesini FoundryModelInfo döndürür. Listeyi daha da daraltmak için bu nesnede yer alan bilgileri kullanabilirsiniz. Ya da get_model_info(alias_or_model_id) yöntemini çağırarak bir modelin bilgilerini doğrudan edinin.

Bu nesneler aşağıdaki alanları içerir:

Alan Türü Description
alias str Modelin takma adı.
id str Modelin benzersiz tanımlayıcısı.
version str Modelin sürümü.
execution_provider str Modeli çalıştırmak için kullanılan hızlandırıcı (yürütme sağlayıcısı).
device_type DeviceType Modelin cihaz türü: CPU, GPU, NPU.
uri str Modelin URI'sini seçin.
file_size_mb int Diskteki modelin MB cinsinden boyutu.
supports_tool_calling bool Modelin araç çağrısını destekleyip desteklemediği.
prompt_template dict \| None Model için şablon iste.
provider str Modelin sağlayıcısı (modelin yayımlandığı yer).
publisher str Modelin yayımcısı (modeli yayımlayan).
license str Modelin lisansının adı.
task str Modelin görevi. chat-completions veya automatic-speech-recognition'den biri.
ep_override str \| None Modelin varsayılanından farklıysa yürütme sağlayıcısı için geçersiz kılın.

Yürütme Sağlayıcıları

Bunlardan biri:

  • CPUExecutionProvider - CPU tabanlı yürütme
  • CUDAExecutionProvider - NVIDIA CUDA GPU yürütme
  • WebGpuExecutionProvider - WebGPU yürütme
  • QNNExecutionProvider - Qualcomm Sinir Ağı İşlemcisi (NPU)
  • OpenVINOExecutionProvider - Intel OpenVINO çalıştırma
  • NvTensorRTRTXExecutionProvider - NVIDIA TensorRT yürütme
  • VitisAIExecutionProvider - AMD Vitis AI çalıştırma

Örnek Kullanım

Aşağıdaki kod, modelleri yönetmek ve Foundry Local hizmetiyle etkileşime geçmek için sınıfının nasıl kullanılacağını FoundryLocalManager gösterir.

from foundry_local import FoundryLocalManager

# By using an alias, the most suitable model will be selected
# to your end-user's device.
alias = "qwen2.5-0.5b"

# Create a FoundryLocalManager instance. This will start the Foundry.
manager = FoundryLocalManager()

# List available models in the catalog
catalog = manager.list_catalog_models()
print(f"Available models in the catalog: {catalog}")

# Download and load a model
model_info = manager.download_model(alias)
model_info = manager.load_model(alias)
print(f"Model info: {model_info}")

# List models in cache
local_models = manager.list_cached_models()
print(f"Models in cache: {local_models}")

# List loaded models
loaded = manager.list_loaded_models()
print(f"Models running in the service: {loaded}")

# Unload a model
manager.unload_model(alias)

Bu örnekte modeller listelenir, bir model indirilir ve yüklenir ve ardından kaldırılır.

Kaynaklar:

OpenAI SDK ile tümleştirme

OpenAI paketini yükleyin:

pip install openai

Aşağıdaki kod, yerel bir model ile etkileşim kurmak için OpenAI SDK'sı ile FoundryLocalManager entegrasyonunu nasıl yapacağınızı gösterir.

import openai
from foundry_local import FoundryLocalManager

# By using an alias, the most suitable model will be downloaded
# to your end-user's device.
alias = "qwen2.5-0.5b"

# Create a FoundryLocalManager instance. This will start the Foundry
# Local service if it is not already running and load the specified model.
manager = FoundryLocalManager(alias)

# The remaining code uses the OpenAI Python SDK to interact with the local model.

# Configure the client to use the local Foundry service
client = openai.OpenAI(
    base_url=manager.endpoint,
    api_key=manager.api_key  # API key is not required for local usage
)

# Set the model to use and generate a streaming response
stream = client.chat.completions.create(
    model=manager.get_model_info(alias).id,
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True
)

# Print the streaming response
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)

Bu örnek, yerel modelden bir sohbet tamamlama yanıtının akışını gerçekleştirir.

Kaynaklar:

JavaScript SDK Dokümanı

Önkoşullar

  • Foundry Local'ı yükleyin ve foundry üzerinde PATH komutunun kullanılabilir olduğundan emin olun.

Kurulum

Paketi npm'den yükleyin:

npm install foundry-local-sdk

Hızlı Başlangıç

SDK'nın hizmeti başlatıp yerel kataloğa ulaşabildiğini doğrulamak için bu kod parçacığını kullanın.

import { FoundryLocalManager } from "foundry-local-sdk";

const manager = new FoundryLocalManager();

await manager.startService();
const catalogModels = await manager.listCatalogModels();

console.log(`Catalog models available: ${catalogModels.length}`);

Bu örnek, hizmet çalışırken ve katalog kullanılabilir olduğunda sıfır olmayan bir sayı yazdırır.

Kaynaklar:

FoundryLocalManager Sınıfı

sınıfı, FoundryLocalManager modelleri yönetmenize, önbelleği denetlemenize ve hem tarayıcıda hem de Node.js ortamlarda Foundry Local hizmetiyle etkileşim kurmanıza olanak tanır.

Başlatma Aşaması

import { FoundryLocalManager } from "foundry-local-sdk";

const foundryLocalManager = new FoundryLocalManager();

Mevcut seçenekler:

  • host: Dökümhane Yerel hizmetinin temel URL'si
  • fetch: (isteğe bağlı) Node.js gibi ortamlar için özel getirme uygulaması

Diğer adlar hakkında bir not

Bu kaynakta özetlenen birçok yöntemin tanımında bir aliasOrModelId parametresi vardır. Bir takma adı veya model kimliğini yöntemine değer olarak geçirebilirsiniz. Bir takma ad kullanmanın sonuçları:

  • Kullanılabilir donanım için en iyi modeli seçin. Örneğin, bir Nvidia CUDA GPU varsa, Foundry Local CUDA modelini seçer. Desteklenen bir NPU varsa, Foundry Local NPU modelini seçer.
  • Model kimliğini hatırlamanıza gerek kalmadan daha kısa bir ad kullanmanıza olanak sağlar.

Tavsiye

aliasOrModelId parametresine bir diğer ad geçirmenizi öneriyoruz çünkü uygulamanızı dağıttığınızda Foundry Local, çalışma anında son kullanıcının makinesi için en iyi modeli edinir.

Uyarı

Windows üzerinde bir Intel NPU'nuz varsa, en iyi NPU hızlandırması için Intel NPU sürücüsünü yüklediğinizden emin olun.

Servis Yönetimi

Yöntem Signature Description
init() (aliasOrModelId?: string) => Promise<FoundryModelInfo \| void> SDK'yi başlatır ve isteğe bağlı olarak bir model yükler.
isServiceRunning() () => Promise<boolean> Foundry Local hizmetinin çalışıp çalışmadığını denetler.
startService() () => Promise<void> Foundry Local hizmetini başlatır.
serviceUrl string Foundry Local hizmetinin temel URL'si.
endpoint string API uç noktası (serviceUrl + /v1).
apiKey string API anahtarı (yok).

Katalog Yönetimi

Yöntem Signature Description
listCatalogModels() () => Promise<FoundryModelInfo[]> Katalogdaki tüm kullanılabilir modelleri listeler.
refreshCatalog() () => Promise<void> Model kataloğunu yeniler.
getModelInfo() (aliasOrModelId: string, throwOnNotFound = false) => Promise<FoundryModelInfo \| null> Diğer ad veya kimlikle model bilgilerini alır.

Önbellek Yönetimi

Yöntem Signature Description
getCacheLocation() () => Promise<string> Model önbelleği dizin yolunu döndürür.
listCachedModels() () => Promise<FoundryModelInfo[]> Yerel önbelleğe indirilen modelleri listeler.

Model Yönetimi

Yöntem Signature Description
downloadModel() (aliasOrModelId: string, token?: string, force = false, onProgress?) => Promise<FoundryModelInfo> Modeli yerel önbelleğe indirir.
loadModel() (aliasOrModelId: string, ttl = 600) => Promise<FoundryModelInfo> Modeli çıkarım sunucusuna yükler.
unloadModel() (aliasOrModelId: string, force = false) => Promise<void> Bir modeli çıkarım sunucusundan kaldırır.
listLoadedModels() () => Promise<FoundryModelInfo[]> Hizmette yüklü olan tüm modelleri listeler.

Örnek Kullanım

Aşağıdaki kod, modelleri yönetmek ve Foundry Local hizmetiyle etkileşime geçmek için sınıfının nasıl kullanılacağını FoundryLocalManager gösterir.

import { FoundryLocalManager } from "foundry-local-sdk";

// By using an alias, the most suitable model will be downloaded
// to your end-user's device.
// TIP: You can find a list of available models by running the
// following command in your terminal: `foundry model list`.
const alias = "qwen2.5-0.5b";

const manager = new FoundryLocalManager();

// Initialize the SDK and optionally load a model
const modelInfo = await manager.init(alias);
console.log("Model Info:", modelInfo);

// Check if the service is running
const isRunning = await manager.isServiceRunning();
console.log(`Service running: ${isRunning}`);

// List available models in the catalog
const catalog = await manager.listCatalogModels();

// Download and load a model
await manager.downloadModel(alias);
await manager.loadModel(alias);

// List models in cache
const localModels = await manager.listCachedModels();

// List loaded models
const loaded = await manager.listLoadedModels();

// Unload a model
await manager.unloadModel(alias);

Bu örnek bir modeli indirip yükler, ardından önbelleğe alınmış ve yüklenen modelleri listeler.

Kaynaklar:

OpenAI İstemcisi ile Tümleştirme

OpenAI paketini yükleyin:

npm install openai

Aşağıdaki kod, yerel bir modelle etkileşime geçmek için FoundryLocalManager ile OpenAI istemcisi entegrasyonunu gösterir.

import { OpenAI } from "openai";
import { FoundryLocalManager } from "foundry-local-sdk";

// By using an alias, the most suitable model will be downloaded
// to your end-user's device.
// TIP: You can find a list of available models by running the
// following command in your terminal: `foundry model list`.
const alias = "qwen2.5-0.5b";

// Create a FoundryLocalManager instance. This will start the Foundry
// Local service if it is not already running.
const foundryLocalManager = new FoundryLocalManager();

// Initialize the manager with a model. This will download the model
// if it is not already present on the user's device.
const modelInfo = await foundryLocalManager.init(alias);
console.log("Model Info:", modelInfo);

const openai = new OpenAI({
  baseURL: foundryLocalManager.endpoint,
  apiKey: foundryLocalManager.apiKey,
});

async function streamCompletion() {
  const stream = await openai.chat.completions.create({
    model: modelInfo.id,
    messages: [{ role: "user", content: "What is the golden ratio?" }],
    stream: true,
  });

  for await (const chunk of stream) {
    if (chunk.choices[0]?.delta?.content) {
      process.stdout.write(chunk.choices[0].delta.content);
    }
  }
}

streamCompletion();

Bu örnek, yerel modelden bir sohbet tamamlama yanıtının akışını gerçekleştirir.

Kaynaklar:

Tarayıcı Kullanımı

SDK, ana bilgisayar URL'sini el ile belirtmeniz gereken tarayıcı uyumlu bir sürüm içerir:

import { FoundryLocalManager } from "foundry-local-sdk/browser";

// Specify the service URL
// Run the Foundry Local service using the CLI: `foundry service start`
// and use the URL from the CLI output
const host = "HOST";

const manager = new FoundryLocalManager({ host });

// Note: The `init`, `isServiceRunning`, and `startService` methods
// are not available in the browser version

Uyarı

Tarayıcı sürümü, init, isServiceRunning ve startService yöntemlerini desteklemez. SDK'yi bir tarayıcı ortamında kullanmadan önce Foundry Local hizmetinin çalıştığından emin olmanız gerekir. Hizmeti, Foundry Yerel CLI'yi kullanarak başlatabilirsiniz: foundry service start. CLI çıktı bilgilerini kullanarak hizmet URL'sini çıkarabilirsiniz.

Örnek Kullanım

import { FoundryLocalManager } from "foundry-local-sdk/browser";

// Specify the service URL
// Run the Foundry Local service using the CLI: `foundry service start`
// and use the URL from the CLI output
const host = "HOST";

const manager = new FoundryLocalManager({ host });

const alias = "qwen2.5-0.5b";

// Get all available models
const catalog = await manager.listCatalogModels();
console.log("Available models in catalog:", catalog);

// Download and load a specific model
await manager.downloadModel(alias);
await manager.loadModel(alias);

// View models in your local cache
const localModels = await manager.listCachedModels();
console.log("Cached models:", localModels);

// Check which models are currently loaded
const loaded = await manager.listLoadedModels();
console.log("Loaded models in inference service:", loaded);

// Unload a model when finished
await manager.unloadModel(alias);

Kaynaklar:

C# SDK Referansı

Proje kurulum kılavuzu

Foundry Yerel SDK'sı için aynı API yüzeyine sahip ancak farklı platformlar için iyileştirilmiş iki NuGet paketi vardır: WinML ve platformlar arası paket:

  • Windows: Windows Machine Learning (WinML) çerçevesini kullanan Windows uygulamalarına özgü paketi kullanır Microsoft.AI.Foundry.Local.WinML .
  • Platformlar arası: Platformlar arası uygulamalar (Windows, Linux, macOS) için kullanılabilecek paketi kullanır Microsoft.AI.Foundry.Local .

Hedef platformunuza bağlı olarak, yeni bir C# uygulaması oluşturmak ve gerekli bağımlılıkları eklemek için şu yönergeleri izleyin:

Şu Windows'a özgü veya Platformlar Arası (macOS/Linux/Windows) yönergelerini izleyerek C# projenizde Foundry Local kullanın:

  1. Yeni bir C# projesi oluşturun ve bu projeye gidin: 
    dotnet new console -n app-name
cd app-name
  2. Dosyayı açın ve şu şekilde düzenleyin app-name.csproj : 
    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0-windows10.0.26100</TargetFramework>
    <RootNamespace>app-name</RootNamespace>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
    <WindowsPackageType>None</WindowsPackageType>
    <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AI.Foundry.Local.WinML" Version="0.8.2.1" />
    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.10" />
    <PackageReference Include="OpenAI" Version="2.5.0" />
  </ItemGroup>

</Project>
  3. Paketlerin doğru şekilde geri yüklenmesi için proje kökünde aşağıdaki içeriğe sahip bir nuget.config dosya oluşturun: 
    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="ORT" value="https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="ORT">
      <package pattern="*Foundry*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Hızlı Başlangıç

SDK'nın yerel model kataloğunu başlatıp bunlara 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.

Kaynaklar:

Yeniden tasarla

Cihaz içi yapay zeka kullanarak uygulama gönderme becerinizi geliştirmek için, sürüm ve sonraki sürümlerde 0.8.0 C# SDK'sının mimarisinde önemli değişiklikler vardır. Bu bölümde, uygulamalarınızı SDK'nın en son sürümüne geçirmenize yardımcı olacak önemli değişiklikleri özetleyeceğiz.

Uyarı

SDK'nin 0.8.0 ve sonraki sürümlerinde, API'de önceki sürümler ile uyumsuzluk yaratan değişiklikler bulunmaktadır.

Aşağıdaki diyagramda, önceki mimarinin (önceki 0.8.0 sürümler için) modelleri ve sohbet tamamlamaları gibi çıkarımları yönetmek için bir REST web sunucusu kullanmaya nasıl dayandığı gösterilmektedir:

Foundry Local için önceki mimarinin diyagramı.

SDK, makinede Foundry Yerel CLI yürütülebilir dosyasını bulmak, web sunucusunu başlatmak ve ardından HTTP üzerinden onunla iletişim kurmak için bir Uzak Yordam Çağrısı (RPC) kullanacaktır. Bu mimarinin aşağıdakiler dahil olmak üzere çeşitli sınırlamaları vardır:

  • Web sunucusu yaşam döngüsünü yönetme karmaşıklığı.
  • Zorlu dağıtım: Son kullanıcıların makinelerinde ve uygulamanızda Foundry Yerel CLI'sinin yüklü olması gerekiyordu.
  • CLI ve SDK'nın sürüm yönetimi uyumluluk sorunlarına yol açabilir.

Bu sorunları gidermek için, 0.8.0 ve sonraki sürümlerde yeniden tasarlanan mimari daha yalın bir yaklaşım kullanır. Yeni mimari aşağıdaki gibidir:

Foundry Local için yeni mimarinin diyagramı.

Bu yeni mimaride:

  • Uygulamanız bağımsızdır. Dökümhane Yerel CLI'sinin son kullanıcının makinesine ayrı olarak yüklenmesi gerekmez ve bu da uygulamaları dağıtmanızı kolaylaştırır.
  • REST web sunucusu isteğe bağlıdır. HTTP üzerinden iletişim kuran diğer araçlarla tümleştirmek istiyorsanız web sunucusunu kullanmaya devam edebilirsiniz. Bu özelliğin nasıl kullanılacağı hakkında ayrıntılı bilgi için REST sunucusu üzerinden Foundry Local ile sohbet tamamlama kullanma başlıklı yazıyı okuyun.
  • SDK, sohbet tamamlamaları ve sesli transkripsiyonlar için yerel desteğe sahiptir ve daha az bağımlılıkla konuşma yapay zekası uygulamaları oluşturmanıza olanak tanır. Bu özelliğin nasıl kullanılacağı hakkında ayrıntılı bilgi için Use Foundry Local Native Chat Completions API'yi kullanma üzerine detayları okuyun.
  • Windows cihazlarda, doğru çalışma zamanını ve sürücüleri çekerek cihazdaki modeller için donanım hızlandırmayı işleyen bir Windows ML derlemesi kullanabilirsiniz.

API değişiklikleri

Sürüm 0.8.0 ve sonraki sürümler daha nesne odaklı ve oluşturulabilir bir API sağlar. Ana giriş noktası FoundryLocalManager olmaya devam ediyor; ancak durum bilgisi olmayan bir HTTP API'sine statik çağrılarla çalışan sabit bir yöntem seti yerine, SDK artık örnek üzerinde durum bilgisi tutan hizmet ve modellere ait yöntemleri FoundryLocalManager sağlar.

İlkel Sürüm < 0.8.0 Sürümler >= 0.8.0
Configuration Mevcut Değil config = Configuration(...)
YöneticiYi Al mgr = FoundryLocalManager(); await FoundryLocalManager.CreateAsync(config, logger);
var mgr = FoundryLocalManager.Instance;
Kataloğu Al Mevcut Değil catalog = await mgr.GetCatalogAsync();
Modelleri Listele mgr.ListCatalogModelsAsync(); catalog.ListModelsAsync();
Modeli Al mgr.GetModelInfoAsync("aliasOrModelId"); catalog.GetModelAsync(alias: "alias");
Varyantı Al Mevcut Değil model.SelectedVariant;
Değişken Ayarla Mevcut Değil model.SelectVariant();
Model indirme mgr.DownloadModelAsync("aliasOrModelId"); model.DownloadAsync()
Model yükleme mgr.LoadModelAsync("aliasOrModelId"); model.LoadAsync()
Modeli kaldırma mgr.UnloadModelAsync("aliasOrModelId"); model.UnloadAsync()
Yüklenen modelleri listeleme mgr.ListLoadedModelsAsync(); catalog.GetLoadedModelsAsync();
Model yolunu al Mevcut Değil model.GetPathAsync()
Hizmeti başlat mgr.StartServiceAsync(); mgr.StartWebServerAsync();
Hizmeti durdur mgr.StopServiceAsync(); mgr.StopWebServerAsync();
Önbellek konumu mgr.GetCacheLocationAsync(); config.ModelCacheDir
Önbelleğe alınan modelleri listeleme mgr.ListCachedModelsAsync(); catalog.GetCachedModelsAsync();

API, Foundry Local'ın web sunucusu, günlük, önbellek konumu ve model değişkeni seçimi üzerinden daha yapılandırılabilir olmasını sağlar. Örneğin, Configuration sınıfı uygulama adını, günlük seviyesini, web sunucusu URL'lerini ve uygulama verileri, model önbelleği ve günlükler için dizinleri ayarlamanıza olanak tanır:

var config = new Configuration
{
    AppName = "app-name",
    LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information,
    Web = new Configuration.WebService
    {
        Urls = "http://127.0.0.1:55588"
    },
    AppDataDir = "./foundry_local_data",
    ModelCacheDir = "{AppDataDir}/model_cache",
    LogsDir = "{AppDataDir}/logs"
};

Kaynaklar:

Foundry Local C# SDK'sının önceki sürümünde, bu ayarları doğrudan SDK aracılığıyla yapılandıramadınız ve bu da hizmetin davranışını özelleştirme yeteneğinizi kısıtlamıştı.

Uygulama paketi boyutunu küçültme

Foundry Yerel SDK'sı Microsoft.ML.OnnxRuntime.Foundry NuGet paketini bağımlılık olarak kullanır. Paket Microsoft.ML.OnnxRuntime.Foundry, belirli satıcı donanım cihazlarında çıkarsamayı verimli bir şekilde çalıştırmak için gereken kütüphane setini içeren çıkarsama çalışma zamanı demetini sağlar. Çıkarım çalışma zamanı paketi aşağıdaki bileşenleri içerir:

  • ONNX Çalışma Zamanı kitaplığı: Çekirdek çıkarım altyapısı (onnxruntime.dll).
  • ONNX Çalışma Zamanı Yürütme Sağlayıcısı (EP) kitaplığı. ONNX Çalışma Zamanı'nda, bir makine öğrenmesi modelinin parçalarını bir donanım hızlandırıcısı kullanarak optimize eden ve yürüten donanıma özel bir altyapı. Örneğin:
    • CUDA EP: onnxruntime_providers_cuda.dll
    • QNN EP: onnxruntime_providers_qnn.dll
  • Bağımsız Donanım Tedarikçisi (IHV) kitaplıkları. Örneğin:
    • WebGPU: DirectX bağımlılıkları (dxcompiler.dll, dxil.dll)
    • QNN: Qualcomm QNN bağımlılıkları (QnnSystem.dllvb.)

Aşağıdaki tabloda hangi EP ve IHV kitaplıklarının uygulamanızla birlikte paketlendiğini ve WinML'nin çalışma zamanında indireceği/yükleyeceği öğeler özetlenmiştir:

EP ve IHV kitaplıklarını gösteren bir tablo çizimi.

Tüm platformlarda ve mimarilerde CPU EP gereklidir. WebGPU EP ve IHV kitaplıklarının boyutu küçüktür (örneğin, WebGPU uygulama paketinize yalnızca ~7 MB ekler) ve Windows ve macOS'ta gereklidir. Ancak CUDA ve QNN EP'lerinin boyutu büyüktür (örneğin, CUDA uygulama paketinize yaklaşık 1 GB ekler), bu nedenle bu IP'leri uygulama paketinizden dışlamanızı öneririz. WinML, son kullanıcının uyumlu donanımı varsa cuda ve QNN'yi çalışma zamanında indirir/yükler.

Uyarı

Gelecekteki sürümlerde CUDA ve QNN EP'lerini Microsoft.ML.OnnxRuntime.Foundry paketinden çıkararak, uygulama paketinizden kaldırmak için bir ExcludeExtraLibs.props dosyası eklemenize gerek kalmayacak şekilde çalışıyoruz.

Uygulama paketinizin boyutunu küçültmek için proje dizininizde aşağıdaki içeriğe sahip bir ExcludeExtraLibs.props dosya oluşturabilirsiniz. Bu dosya, uygulamanızı yayımladığınızda CUDA ve QNN EP ve IHV kitaplıklarını dışlar:

<Project>
  <!-- we want to ensure we're using the onnxruntime libraries from Foundry Local Core so 
  we delete the WindowsAppSdk versions once they're unzipped. -->
  <Target Name="ExcludeOnnxRuntimeLibs" AfterTargets="ExtractMicrosoftWindowsAppSDKMsixFiles">
    <Delete Files="$(MicrosoftWindowsAppSDKMsixContent)\onnxruntime.dll"/>
    <Delete Files="$(MicrosoftWindowsAppSDKMsixContent)\onnxruntime_providers_shared.dll"/>
    <Message Importance="Normal" Text="Deleted onnxruntime libraries from $(MicrosoftWindowsAppSDKMsixContent)." />
  </Target>

  <!-- Remove CUDA EP and IHV libraries on Windows x64 -->
  <Target Name="ExcludeCudaLibs" Condition="'$(RuntimeIdentifier)'=='win-x64'" AfterTargets="ResolvePackageAssets">
    <ItemGroup>
      <!-- match onnxruntime*cuda.* (we're matching %(Filename) which excludes the extension) -->
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)', 
                                      '^onnxruntime.*cuda.*', RegexOptions.IgnoreCase))" />
    </ItemGroup>
    <Message Importance="Normal" Text="Excluded onnxruntime CUDA libraries from package." />
  </Target>

  <!-- Remove QNN EP and IHV libraries on Windows arm64 -->
  <Target Name="ExcludeQnnLibs" Condition="'$(RuntimeIdentifier)'=='win-arm64'" AfterTargets="ResolvePackageAssets">
    <ItemGroup>
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)%(Extension)', 
                                      '^QNN.*\.dll', RegexOptions.IgnoreCase))" />
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="$([System.Text.RegularExpressions.Regex]::IsMatch('%(Filename)', 
                                      '^libQNNhtp.*', RegexOptions.IgnoreCase))" />
      <NativeCopyLocalItems Remove="@(NativeCopyLocalItems)"
                            Condition="'%(FileName)%(Extension)' == 'onnxruntime_providers_qnn.dll'" />
    </ItemGroup>
    <Message Importance="Normal" Text="Excluded onnxruntime QNN libraries from package." />
  </Target>

  <!-- need to manually copy on linux-x64 due to the nuget packages not having the correct props file setup -->
  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <!-- 'Update' as the Core package will add these dependencies, but we want to be explicit about the version -->
    <PackageReference Update="Microsoft.ML.OnnxRuntime.Gpu" />
    <PackageReference Update="Microsoft.ML.OnnxRuntimeGenAI.Cuda" />
    <OrtNativeLibs Include="$(NuGetPackageRoot)microsoft.ml.onnxruntime.gpu.linux/$(OnnxRuntimeVersion)/runtimes/$(RuntimeIdentifier)/native/*" />
    <OrtGenAINativeLibs Include="$(NuGetPackageRoot)microsoft.ml.onnxruntimegenai.cuda/$(OnnxRuntimeGenAIVersion)/runtimes/$(RuntimeIdentifier)/native/*" />
  </ItemGroup>

  <Target Name="CopyOrtNativeLibs" AfterTargets="Build" Condition=" '$(RuntimeIdentifier)' == 'linux-x64'">
    <Copy SourceFiles="@(OrtNativeLibs)" DestinationFolder="$(OutputPath)"></Copy>
    <Copy SourceFiles="@(OrtGenAINativeLibs)" DestinationFolder="$(OutputPath)"></Copy>
  </Target>
</Project>

Proje dosyanıza ().csproj dosyasını içeri aktarmak ExcludeExtraLibs.props için aşağıdaki satırı ekleyin:

<!-- other project file content -->
  
<Import Project="ExcludeExtraLibs.props" />

Windows: CUDA bağımlılıkları

CUDA EP, Linux uygulamanıza Microsoft.ML.OnnxRuntime.Foundry aracılığıyla entegre edilir, ancak IHV kitaplıkları içerilmez. CUDA özellikli cihazlara sahip son kullanıcılarınızın daha yüksek performanstan yararlanmasına izin vermek istiyorsanız, uygulamanıza aşağıdaki CUDA IHV kitaplıklarını eklemeniz gerekir:

Uyarı

CUDA EP ve IHV kitaplıklarını uygulamanıza eklemek, uygulama paketinizin boyutunu 1 GB artırır.

Samples

API referansı

Rust SDK referansları

Foundry Local için Rust SDK modelleri yönetmek, önbelleği denetlemek ve Foundry Local hizmetiyle etkileşime geçmek için bir yol sağlar.

Önkoşullar

  • Foundry Local'ı yükleyin ve foundry üzerinde PATH komutunun kullanılabilir olduğundan emin olun.
  • Rust 1.70.0 veya üzerini kullanın.

Kurulum

Foundry Local Rust SDK'sını kullanmak için aşağıdakini ekleyin Cargo.toml:

[dependencies]
foundry-local = "0.1.0"

Alternatif olarak, cargo kullanarak Foundry Local kasasını ekleyebilirsiniz.

cargo add foundry-local

Hızlı Başlangıç

SDK'nın hizmeti başlatıp yerel kataloğu okuyabildiğini doğrulamak için bu kod parçacığını kullanın.

use anyhow::Result;
use foundry_local::FoundryLocalManager;

#[tokio::main]
async fn main() -> Result<()> {
  let mut manager = FoundryLocalManager::builder().bootstrap(true).build().await?;

  let models = manager.list_catalog_models().await?;
  println!("Catalog models available: {}", models.len());

  Ok(())
}

Bu örnek, hizmet çalışırken ve katalog kullanılabilir olduğunda sıfır olmayan bir sayı yazdırır.

Kaynaklar:

FoundryLocalManager

Foundry Yerel SDK işlemleri yöneticisi.

Fields

  • service_uri: Option<String> — Dökümhane hizmetinin URI'si.
  • client: Option<HttpClient> — API istekleri için HTTP istemcisi.
  • catalog_list: Option<Vec<FoundryModelInfo>> — Katalog modellerinin önbelleğe alınmış listesi.
  • catalog_dict: Option<HashMap<String, FoundryModelInfo>> — Katalog modellerinin önbelleğe alınmış sözlüğü.
  • timeout: Option<u64> — İsteğe bağlı HTTP istemcisi zaman aşımı.

Methods

  • pub fn builder() -> FoundryLocalManagerBuilder
    FoundryLocalManager için yeni bir oluşturucu oluşturun.

  • pub fn service_uri(&self) -> Result<&str>
    Hizmet URI'sini alın.
    Döndürür: Foundry hizmetinin URI'si.

  • fn client(&self) -> Result<&HttpClient>
    HTTP istemci örneğini alın.
    Döndürür: HTTP istemcisi.

  • pub fn endpoint(&self) -> Result<String>
    Hizmetin uç noktasını edinin.
    Döndürür: Uç nokta URL'si.

  • pub fn api_key(&self) -> String
    Kimlik doğrulaması için API anahtarını alın.
    Döndürür: API anahtarı.

  • pub fn is_service_running(&mut self) -> bool
    Hizmetin çalışıp çalışmadığını denetleyin ve bulunursa hizmet URI'sini ayarlayın.
    Dönen değer:true çalışıyorsa, false aksi takdirde.

  • pub fn start_service(&mut self) -> Result<()>
    Foundry Yerel hizmetini başlatın.

  • pub async fn list_catalog_models(&mut self) -> Result<&Vec<FoundryModelInfo>>
    Katalogdaki kullanılabilir modellerin listesini alın.

  • pub fn refresh_catalog(&mut self)
    Katalog önbelleğini yenileyin.

  • pub async fn get_model_info(&mut self, alias_or_model_id: &str, raise_on_not_found: bool) -> Result<FoundryModelInfo>
    Takma ad veya kimlik ile model bilgilerini alın.
    Argümanlar:

    • alias_or_model_id: Takma ad veya Model Kimliği.
    • raise_on_not_found: True ise, bulunamazsa hata.

  • pub async fn get_cache_location(&self) -> Result<String>
    Önbellek konumunu dize olarak alın.

  • pub async fn list_cached_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    Önbelleğe alınan modelleri listeleyin.

  • pub async fn download_model(&mut self, alias_or_model_id: &str, token: Option<&str>, force: bool) -> Result<FoundryModelInfo>
    Bir model indirin.
    Argümanlar:

    • alias_or_model_id: Takma ad veya Model Kimliği.
    • token: İsteğe bağlı kimlik doğrulama belirteci.
    • force: Önceden önbelleğe alınmışsa yeniden indirmeye zorla.

  • pub async fn load_model(&mut self, alias_or_model_id: &str, ttl: Option<i32>) -> Result<FoundryModelInfo>
    Çıkarım için bir model yükleyin.
    Argümanlar:

    • alias_or_model_id: Takma ad veya Model Kimliği.
    • ttl: İsteğe bağlı yaşam süresi (saniye cinsinden).

  • pub async fn unload_model(&mut self, alias_or_model_id: &str, force: bool) -> Result<()>
    Bir modeli boşalt.
    Argümanlar:

    • alias_or_model_id: Takma ad veya Model Kimliği.
    • force: Kullanımda olsa bile zorla boşalt.

  • pub async fn list_loaded_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    Yüklenen modelleri listeleyin.

FoundryLocalManagerBuilder

FoundryLocalManager örneği oluşturmak için yapıcı.

Fields

  • alias_or_model_id: Option<String> — İndirilecek ve yüklenecek takma ad veya model kimliği.
  • bootstrap: bool — Çalışmıyorsa hizmetin başlatılıp başlatılmaymayacağı.
  • timeout_secs: Option<u64> — HTTP istemcisi zaman aşımı süresi, saniye cinsinden.

Methods

  • pub fn new() -> Self
    Yeni bir oluşturucu örneği oluşturun.

  • pub fn alias_or_model_id(mut self, alias_or_model_id: impl Into<String>) -> Self
    İndirmek ve yüklemek için diğer adı veya model kimliğini belirleyin.

  • pub fn bootstrap(mut self, bootstrap: bool) -> Self
    Çalışmıyorsa hizmetin başlatılıp başlatılmayacağını ayarlayın.

  • pub fn timeout_secs(mut self, timeout_secs: u64) -> Self
    HTTP istemcisi zaman aşımını saniye olarak ayarlayın.

  • pub async fn build(self) -> Result<FoundryLocalManager>
    FoundryLocalManager Örneği oluşturun.

FoundryModelInfo

Model hakkındaki bilgileri temsil eder.

Fields

  • alias: String — Model takma adı.
  • id: String — Model kimliği.
  • version: String — Model sürümü.
  • runtime: ExecutionProvider — Yürütme sağlayıcısı (CPU, CUDA vb.).
  • uri: String — Model URI'si.
  • file_size_mb: i32 — MB cinsinden model dosyası boyutu.
  • prompt_template: serde_json::Value — Model için istem şablonu.
  • provider: String — Sağlayıcı adı.
  • publisher: String — Yayımcı adı.
  • license: String — Lisans türü.
  • task: String — Modelleme görevi (örneğin, metin oluşturma).

Methods

  • from_list_response(response: &FoundryListResponseModel) -> Self
    Katalog yanıtından bir FoundryModelInfo oluşturur.

  • to_download_body(&self) -> serde_json::Value
    İndirme istekleri için model bilgilerini bir JSON gövdesine dönüştürür.

ExecutionProvider

Desteklenen yürütme sağlayıcıları için enum sabitleri.

  • CPU
  • WebGPU
  • CUDA
  • QNN
Methods
  • get_alias(&self) -> String
    Yürütme sağlayıcısı için bir dizgi takma adı döndürür.

ModelRuntime

Modelin çalışma zamanı ortamını açıklar.

  • device_type: DeviceType
  • execution_provider: ExecutionProvider
  • Last updated on