Foundry Local SDK-referens

Python SDK-referens

Installation

Installera Python-paketet:

pip install foundry-local-sdk

FoundryLocalManager-klass

Klassen FoundryLocalManager innehåller metoder för att hantera modeller, cacheminnen och den lokala foundry-tjänsten.

Initialisering

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: (valfritt) Alias eller modell-ID för nedladdning och inläsning vid start.
• bootstrap: (standardvärde sant) Om sant, startar tjänsten om den inte körs och laddar in modellen om den tillhandahålls.

En anteckning om alias

Många metoder som beskrivs i den här referensen har en alias_or_model_id parameter i signaturen. Du kan skicka till metoden antingen ett alias eller modell-ID som ett värde. Om du använder ett alias kommer:

• Välj den bästa modellen för den tillgängliga maskinvaran. Om till exempel en Nvidia CUDA GPU är tillgänglig väljer Foundry Local CUDA-modellen. Om en NPU som stöds är tillgänglig väljer Foundry Local NPU-modellen.
• Gör att du kan använda ett kortare namn utan att behöva komma ihåg modell-ID:t.

Tjänsthantering

Kataloghantering

Cachehantering

Modellhantering

Exempel på användning

Följande kod visar hur du använder FoundryManager klassen för att hantera modeller och interagera med den lokala foundry-tjänsten.

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)

Integrera med OpenAI SDK

Installera OpenAI-paketet:

pip install openai

Följande kod visar hur du integrerar FoundryLocalManager med OpenAI SDK för att interagera med en lokal modell.

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 us es 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)

JavaScript SDK-referens

Installation

Installera paketet från npm:

npm install foundry-local-sdk

FoundryLocalManager-klass

Med FoundryLocalManager klassen kan du hantera modeller, styra cacheminnet och interagera med den lokala foundry-tjänsten i både webbläsare och Node.js miljöer.

Initialisering

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

const foundryLocalManager = new FoundryLocalManager();

Tillgängliga alternativ:

• serviceUrl: Bas-URL för den lokala foundry-tjänsten
• fetch: (valfritt) Anpassad hämtningsimplementering för miljöer som Node.js

En anteckning om alias

Många metoder som beskrivs i den här referensen har en aliasOrModelId parameter i signaturen. Du kan skicka till metoden antingen ett alias eller modell-ID som ett värde. Om du använder ett alias kommer:

• Välj den bästa modellen för den tillgängliga maskinvaran. Om till exempel en Nvidia CUDA GPU är tillgänglig väljer Foundry Local CUDA-modellen. Om en NPU som stöds är tillgänglig väljer Foundry Local NPU-modellen.
• Gör att du kan använda ett kortare namn utan att behöva komma ihåg modell-ID:t.

Tjänsthantering

Kataloghantering

Cachehantering

Modellhantering

Exempel på användning

Följande kod visar hur du använder FoundryLocalManager klassen för att hantera modeller och interagera med den lokala foundry-tjänsten.

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

Integrering med OpenAI-klient

Installera OpenAI-paketet:

npm install openai

Följande kod visar hur du integrerar FoundryLocalManager med OpenAI-klienten för att interagera med en lokal modell.

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

Webbläsaranvändning

SDK innehåller en webbläsarkompatibel version där du måste ange tjänstens URL manuellt:

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 endpoint = "ENDPOINT";

const manager = new FoundryLocalManager({ serviceUrl: endpoint });

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

Exempel på användning

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 endpoint = "ENDPOINT";

const manager = new FoundryLocalManager({ serviceUrl: endpoint });

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.listLocalModels();
console.log("Cached models:", catalog);

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

C# SDK-referens

Installation

Om du vill använda Foundry Local C# SDK måste du installera NuGet-paketet:

dotnet add package Microsoft.AI.Foundry.Local

En anteckning om alias

Många metoder som beskrivs i den här referensen har en aliasOrModelId parameter i signaturen. Du kan skicka till metoden antingen ett alias eller modell-ID som ett värde. Om du använder ett alias kommer:

• Välj den bästa modellen för den tillgängliga maskinvaran. Om till exempel en Nvidia CUDA GPU är tillgänglig väljer Foundry Local CUDA-modellen. Om en NPU som stöds är tillgänglig väljer Foundry Local NPU-modellen.
• Gör att du kan använda ett kortare namn utan att behöva komma ihåg modell-ID:t.

Uppräkningar

DeviceType

Representerar typen av enhet som används för modellutförande.

ExecutionProvider

Representerar exekveringsleverantören för modellslutledning.

FoundryLocalManager-klass

Den viktigaste startpunkten för att hantera modeller, cache och den Foundry Local-tjänsten.

Byggnation

var manager = new FoundryLocalManager();

Egenskaper

Tjänsthantering

Starta tjänsten

await manager.StartServiceAsync(CancellationToken.None);

Startar Foundry-lokaltjänsten om den inte redan körs.

Stoppa tjänsten

await manager.StopServiceAsync(CancellationToken.None);

Stänger Foundry Local-tjänsten.

Starta och läsa in en modell (statisk hjälp)

var manager = await FoundryLocalManager.StartModelAsync("aliasOrModelId");

Startar tjänsten och läser in den angivna modellen.

Kataloghantering

Visa en lista över alla katalogmodeller

List<ModelInfo> models = await manager.ListCatalogModelsAsync();

Returnerar alla tillgängliga modeller i katalogen.

Uppdatera katalogen

manager.RefreshCatalog();

Rensar den cachelagrade katalogen så att den läses in igen vid nästa åtkomst.

Hämta modellinformation efter alias eller ID

ModelInfo? info = await manager.GetModelInfoAsync("aliasOrModelId");

Returnerar modellinformation eller null om den inte hittas.

Cachehantering

Hämta cacheplats

string cachePath = await manager.GetCacheLocationAsync();

Returnerar katalogsökvägen där modeller cachelagras.

Lista cachelagrade modeller

List<ModelInfo> cached = await manager.ListCachedModelsAsync();

Returnerar modeller som laddats ned till den lokala cachen.

Modellhantering

Ladda ned en modell

ModelInfo? model = await manager.DownloadModelAsync("aliasOrModelId");

Laddar ned en modell till den lokala cachen.

Ladda ned en modell med förlopp

await foreach (var progress in manager.DownloadModelWithProgressAsync("aliasOrModelId"))
{
    // progress.Percentage, progress.Status, etc.
}

Strömmar laddar ned förloppsuppdateringar.

Ladda en modell

ModelInfo loaded = await manager.LoadModelAsync("aliasOrModelId");

Läser in en modell på slutsatsdragningsservern.

Lista inlästa modeller

List<ModelInfo> loaded = await manager.ListLoadedModelsAsync();

Visar en lista över alla modeller som för närvarande är inlästa i tjänsten.

Ta bort en modell

await manager.UnloadModelAsync("aliasOrModelId");

Tar bort en modell från slutsatsdragningsservern.

Avfallshantering

Implementerar både IDisposable och IAsyncDisposable för korrekt rensning.

manager.Dispose();
// or
await manager.DisposeAsync();

Modelltyper

På den här sidan dokumenteras de viktiga datatyper som används av Foundry Local C# SDK för att beskriva modeller, nedladdningar och körningsinformation.

PromptTemplate

Representerar promptmallen för en modell.

Runtime

Beskriver körningsmiljön för en modell.

ModelSettings

Representerar modellspecifika parametrar.

ModelInfo

Beskriver en modell i Foundry Local-katalogen eller cacheminnet.

ModelDownloadProgress

Representerar förloppet för en modellnedladdningsåtgärd.

Statiska metoder:

• Progress(double percentage): Skapa en förloppsuppdatering.
• Completed(ModelInfo modelInfo): Skapa ett slutfört framstegsresultat.
• Error(string errorMessage): Skapa ett felresultat.

Exempel på användning

using Microsoft.AI.Foundry.Local;

var manager = new FoundryLocalManager();
await manager.StartServiceAsync();

var models = await manager.ListCatalogModelsAsync();
var alias = "qwen2.5-0.5b";

await manager.DownloadModelAsync(alias);
await manager.LoadModelAsync(alias);

var loaded = await manager.ListLoadedModelsAsync();

await manager.UnloadModelAsync(alias);

manager.Dispose();

Rust SDK-referens

Med Rust SDK för Foundry Local kan du hantera modeller, kontrollera cacheminnet och interagera med den lokala foundry-tjänsten.

Installation

Om du vill använda Foundry Local Rust SDK lägger du till följande i :Cargo.toml

[dependencies]
foundry-local-sdk = "0.1"

Du kan alternativt lägga till Foundry Local-lådan genom att använda cargo:

cargo add foundry-local

FoundryLocalManager

Chef för Foundry Local SDK-verksamhet.

Fält

• service_uri: Option<String> — URI för foundry-tjänsten.
• client: Option<HttpClient> — HTTP-klient för API-begäranden.
• catalog_list: Option<Vec<FoundryModelInfo>> — Cachelagrad lista över katalogmodeller.
• catalog_dict: Option<HashMap<String, FoundryModelInfo>> – Cachelagrad ordlista över katalogmodeller.
• timeout: Option<u64> – Valfri tidsgräns för HTTP-klienten.

Metoder

• pub fn builder() -> FoundryLocalManagerBuilder
  Skapa en ny byggare för FoundryLocalManager.

• pub fn service_uri(&self) -> Result<&str>
  Hämta tjänstens URI.
  Returnerar: URI för Foundry-tjänsten.

• fn client(&self) -> Result<&HttpClient>
  Hämta HTTP-klientinstansen.
  Returnerar: HTTP-klient.

• pub fn endpoint(&self) -> Result<String>
  Hämta slutpunkten för tjänsten.
  Returnerar: Endpunkt-URL.

• pub fn api_key(&self) -> String
  Hämta API-nyckeln för autentisering.
  Returnerar: API-nyckel.

• pub fn is_service_running(&mut self) -> bool
  Kontrollera om tjänsten körs och ange tjänst-URI:n om den hittas.
  Returnerar:true om körs, false annars.

• pub fn start_service(&mut self) -> Result<()>
  Starta Foundry Local-tjänsten.

• pub async fn list_catalog_models(&mut self) -> Result<&Vec<FoundryModelInfo>>
  Hämta en lista över tillgängliga modeller i katalogen.

• pub fn refresh_catalog(&mut self)
  Uppdatera katalogcachen.

• pub async fn get_model_info(&mut self, alias_or_model_id: &str, raise_on_not_found: bool) -> Result<FoundryModelInfo>
  Hämta modellinformation efter alias eller ID.
  Argument:

  • alias_or_model_id: Alias eller modell-ID.
  • raise_on_not_found: Om sant, fel om det inte hittas.

• pub async fn get_cache_location(&self) -> Result<String>
  Hämta cacheplatsen som en sträng.

• pub async fn list_cached_models(&mut self) -> Result<Vec<FoundryModelInfo>>
  Lista cachelagrade modeller.

• pub async fn download_model(&mut self, alias_or_model_id: &str, token: Option<&str>, force: bool) -> Result<FoundryModelInfo>
  Ladda ned en modell.
  Argument:

  • alias_or_model_id: Alias eller modell-ID.
  • token: Valfri autentiseringstoken.
  • force: Framtvinga ny nedladdning om det redan har cachelagrats.

• pub async fn load_model(&mut self, alias_or_model_id: &str, ttl: Option<i32>) -> Result<FoundryModelInfo>
  Läs in en modell för slutsatsdragning.
  Argument:

  • alias_or_model_id: Alias eller modell-ID.
  • ttl: Valfri time-to-live i sekunder.

• pub async fn unload_model(&mut self, alias_or_model_id: &str, force: bool) -> Result<()>
  Ta bort en modell.
  Argument:

  • alias_or_model_id: Alias eller modell-ID.
  • force: Tvångsavlasta även om det används.

• pub async fn list_loaded_models(&mut self) -> Result<Vec<FoundryModelInfo>>
  Visa en lista över inlästa modeller.

FoundryLocalManagerBuilder

Konstruktor för att skapa en FoundryLocalManager instans.

Fält

• alias_or_model_id: Option<String> – Alias eller modell-ID för att ladda ned och läsa in.
• bootstrap: bool — Om tjänsten ska startas själv om den inte redan är igång.
• timeout_secs: Option<u64> — HTTP-klientens timeout på några sekunder.

Metoder

• pub fn new() -> Self
  Skapa en ny builder-instans.

• pub fn alias_or_model_id(mut self, alias_or_model_id: impl Into<String>) -> Self
  Ange alias eller modell-ID för att ladda ned och ladda in.

• pub fn bootstrap(mut self, bootstrap: bool) -> Self
  Ange om tjänsten ska startas om den inte körs.

• pub fn timeout_secs(mut self, timeout_secs: u64) -> Self
  Ange tidsgränsen för HTTP-klienten i sekunder.

• pub async fn build(self) -> Result<FoundryLocalManager>
  Skapa instansen FoundryLocalManager .

FoundryModelInfo

Representerar information om en modell.

Fält

• alias: String – Modellaliaset.
• id: String — Modell-ID.
• version: String — Modellversionen.
• runtime: ExecutionProvider — Exekveringsleverantören (CPU, CUDA osv.).
• uri: String – Modellens URI.
• file_size_mb: i32 – Modellfilstorlek i MB.
• prompt_template: serde_json::Value – Fråga efter mall för modellen.
• provider: String — Providernamn.
• publisher: String – Utgivarens namn.
• license: String – Licenstyp.
• task: String — Modellaktivitet (t.ex. textgenerering).

Metoder

• from_list_response(response: &FoundryListResponseModel) -> Self
  Skapar ett FoundryModelInfo från ett katalogsvar.

• to_download_body(&self) -> serde_json::Value
  Konverterar modellinformationen till en JSON-brödtext för nedladdningsbegäranden.

ExecutionProvider

Enum för exekveringsleverantörer som stöds.

• CPU
• WebGPU
• CUDA
• QNN

Metoder

• get_alias(&self) -> String
  Returnerar ett strängalias för exekveringsprovidern.

ModelRuntime

Beskriver körningsmiljön för en modell.

• device_type: DeviceType
• execution_provider: ExecutionProvider