Condividi tramite

Informazioni di riferimento su Foundry Local Legacy SDK

Avviso

Questo riferimento si applica alle versioni precedenti di Foundry Local SDK che dipendono dall'interfaccia della riga di comando locale di Foundry per la gestione dei servizi.

Per il nuovo sviluppo, usare il riferimento all'SDK corrente.

La tabella seguente illustra le versioni dell'SDK in cui è presente una dipendenza dall'interfaccia della riga di comando:

Lingua Package Versioni dipendenti dall'interfaccia della riga di comando
C# Microsoft. Intelligenza artificiale. Foundry.Local 0.3.0 e versioni precedenti
JavaScript foundry-local-sdk 0.5.0 e versioni precedenti
Python foundry-local-sdk 0.5.1 e versioni precedenti
Rust foundry-local/foundry-local-sdk 0.x

Il supporto per le versioni dipendenti dall'interfaccia della riga di comando termina il 31 agosto 2026.

Informazioni di riferimento su Python SDK

Prerequisiti

  • Installare l'interfaccia della riga di comando locale di Foundry e assicurarsi che il comando sia disponibile nell'oggetto foundryPATH.
  • Usare Python 3.9 o versione successiva.

Installazione

Installare il pacchetto Python:

pip install foundry-local-sdk==0.5.1

Avvio rapido

Usare questo frammento di codice per verificare che l'SDK possa avviare il servizio e raggiungere il catalogo locale.

from foundry_local import FoundryLocalManager

manager = FoundryLocalManager()
manager.start_service()

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

In questo esempio viene stampato un numero diverso da zero quando il servizio è in esecuzione e il catalogo è disponibile.

Riferimenti:

Classe FoundryLocalManager

La FoundryLocalManager classe fornisce metodi per gestire modelli, cache e il servizio locale Foundry.

Inizializzazione

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: (facoltativo) Alias o ID modello da scaricare e caricare all'avvio.
  • bootstrap: (valore predefinito True) Se True, avvia il servizio se non è in esecuzione e carica il modello, se specificato.

Nota sugli alias

Molti metodi descritti in questo riferimento hanno un alias_or_model_id parametro nella firma. È possibile passare al metodo un alias o un ID modello come valore. L'uso di un alias porterà a:

  • Selezionare il modello migliore per l'hardware disponibile. Ad esempio, se è disponibile una GPU Nvidia CUDA, Foundry Local seleziona il modello CUDA. Se è disponibile una NPU supportata, Foundry Local seleziona il modello NPU.
  • Consente di usare un nome più breve senza dover ricordare l'ID modello.

Suggerimento

È consigliabile passare al alias_or_model_id parametro un alias perché quando si distribuisce l'applicazione, Foundry Local acquisisce il modello migliore per il computer dell'utente finale in fase di esecuzione.

Annotazioni

Se si dispone di una NPU Intel in Windows, assicurarsi di aver installato il driver Intel NPU per un'accelerazione NPU ottimale.

Gestione dei servizi

metodo Signature Descrizione
is_service_running() () -> bool Controlla se il servizio locale Foundry è in esecuzione.
start_service() () -> None Avvia il servizio Foundry Locale.
service_uri @property -> str Restituisce l'URI del servizio.
endpoint @property -> str Restituisce l'endpoint del servizio.
api_key @property -> str Restituisce la chiave API (da env o default).

Gestione catalogo

metodo Signature Descrizione
list_catalog_models() () -> list[FoundryModelInfo] Elenca tutti i modelli disponibili nel catalogo.
refresh_catalog() () -> None Aggiorna il catalogo dei modelli.
get_model_info() (alias_or_model_id: str, raise_on_not_found=False) -> FoundryModelInfo \| None Ottiene informazioni sul modello in base all'alias o all'ID.

Gestione cache

metodo Signature Descrizione
get_cache_location() () -> str Restituisce il percorso della directory della cache del modello.
list_cached_models() () -> list[FoundryModelInfo] Elenca i modelli scaricati nella cache locale.

Gestione modelli

metodo Signature Descrizione
download_model() (alias_or_model_id: str, token: str = None, force: bool = False) -> FoundryModelInfo Scarica un modello nella cache locale.
load_model() (alias_or_model_id: str, ttl: int = 600) -> FoundryModelInfo Carica un modello nel server di inferenza.
unload_model() (alias_or_model_id: str, force: bool = False) -> None Scarica un modello dal server di inferenza.
list_loaded_models() () -> list[FoundryModelInfo] Elenca tutti i modelli attualmente caricati nel servizio.

FoundryModelInfo

I metodi list_catalog_models(), list_cached_models()e list_loaded_models() restituiscono un elenco di FoundryModelInfo oggetti . È possibile utilizzare le informazioni contenute in questo oggetto per perfezionare ulteriormente l'elenco. In alternativa, ottenere le informazioni per un modello direttamente chiamando il get_model_info(alias_or_model_id) metodo .

Questi oggetti contengono i campi seguenti:

Campo Tipo Descrizione
alias str Alias del modello.
id str Identificatore univoco del modello.
version str Versione del modello.
execution_provider str Acceleratore (provider di esecuzione) utilizzato per eseguire il modello.
device_type DeviceType Tipo di dispositivo del modello: CPU, GPU, NPU.
uri str URI del modello.
file_size_mb int Dimensioni del modello su disco in MB.
supports_tool_calling bool Indica se il modello supporta la chiamata allo strumento.
prompt_template dict \| None Modello di richiesta per il modello.
provider str Provider del modello (dove è pubblicato il modello).
publisher str Publisher del modello (che ha pubblicato il modello).
license str Nome della licenza del modello.
task str Attività del modello. Uno tra chat-completions e automatic-speech-recognition.
ep_override str \| None Eseguire l'override per il provider di esecuzione, se diverso dall'impostazione predefinita del modello.

Fornitori di esecuzione

Uno dei seguenti:

  • CPUExecutionProvider - Esecuzione basata sulla CPU
  • CUDAExecutionProvider - Esecuzione GPU NVIDIA CUDA
  • WebGpuExecutionProvider - Esecuzione di WebGPU
  • QNNExecutionProvider - Esecuzione della rete neurale Qualcomm (NPU)
  • OpenVINOExecutionProvider - Esecuzione di Intel OpenVINO
  • NvTensorRTRTXExecutionProvider - Esecuzione di NVIDIA TensorRT
  • VitisAIExecutionProvider - Esecuzione dell'intelligenza artificiale AMD Vitis

Esempio di utilizzo

Il codice seguente illustra come usare la FoundryLocalManager classe per gestire i modelli e interagire con il servizio locale Foundry.

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)

Questo esempio elenca modelli, ne scarica uno, lo carica e poi lo rimuove.

Riferimenti:

Eseguire l'integrazione con OpenAI SDK

Installare il pacchetto OpenAI:

pip install openai

Il codice seguente illustra come integrare FoundryLocalManager con l'SDK di OpenAI per interagire con un modello locale.

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)

Questo esempio trasmette una risposta di completamento della chat dal modello locale.

Riferimenti:

Informazioni di riferimento su JavaScript SDK

Prerequisiti

  • Installare l'interfaccia della riga di comando locale di Foundry e assicurarsi che il comando sia disponibile nell'oggetto foundryPATH.

Installazione

Installare il pacchetto da npm:

npm install foundry-local-sdk@0.5.0

Avvio rapido

Usare questo frammento di codice per verificare che l'SDK possa avviare il servizio e raggiungere il catalogo locale.

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

In questo esempio viene stampato un numero diverso da zero quando il servizio è in esecuzione e il catalogo è disponibile.

Riferimenti:

Classe FoundryLocalManager

La FoundryLocalManager classe consente di gestire modelli, controllare la cache e interagire con il servizio locale Foundry in ambienti browser e Node.js.

Inizializzazione

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

const foundryLocalManager = new FoundryLocalManager();

Opzioni disponibili:

  • host: URL di base del servizio locale Foundry
  • fetch: (facoltativo) Implementazione di recupero personalizzato per ambienti come Node.js

Nota sugli alias

Molti metodi descritti in questo riferimento hanno un aliasOrModelId parametro nella firma. È possibile passare al metodo un alias o un ID modello come valore. L'uso di un alias porterà a:

  • Selezionare il modello migliore per l'hardware disponibile. Ad esempio, se è disponibile una GPU Nvidia CUDA, Foundry Local seleziona il modello CUDA. Se è disponibile una NPU supportata, Foundry Local seleziona il modello NPU.
  • Consente di usare un nome più breve senza dover ricordare l'ID modello.

Suggerimento

È consigliabile passare al aliasOrModelId parametro un alias perché quando si distribuisce l'applicazione, Foundry Local acquisisce il modello migliore per il computer dell'utente finale in fase di esecuzione.

Annotazioni

Se si dispone di una NPU Intel in Windows, assicurarsi di aver installato il driver Intel NPU per un'accelerazione NPU ottimale.

Gestione dei servizi

metodo Signature Descrizione
init() (aliasOrModelId?: string) => Promise<FoundryModelInfo \| void> Inizializza l'SDK e, facoltativamente, carica un modello.
isServiceRunning() () => Promise<boolean> Controlla se il servizio locale Foundry è in esecuzione.
startService() () => Promise<void> Avvia il servizio Foundry Locale.
serviceUrl string URL di base del servizio locale Foundry.
endpoint string L'endpoint dell'API (serviceUrl + /v1).
apiKey string Chiave API (nessuno).

Gestione catalogo

metodo Signature Descrizione
listCatalogModels() () => Promise<FoundryModelInfo[]> Elenca tutti i modelli disponibili nel catalogo.
refreshCatalog() () => Promise<void> Aggiorna il catalogo dei modelli.
getModelInfo() (aliasOrModelId: string, throwOnNotFound = false) => Promise<FoundryModelInfo \| null> Ottiene informazioni sul modello in base all'alias o all'ID.

Gestione cache

metodo Signature Descrizione
getCacheLocation() () => Promise<string> Restituisce il percorso della directory della cache del modello.
listCachedModels() () => Promise<FoundryModelInfo[]> Elenca i modelli scaricati nella cache locale.

Gestione modelli

metodo Signature Descrizione
downloadModel() (aliasOrModelId: string, token?: string, force = false, onProgress?) => Promise<FoundryModelInfo> Scarica un modello nella cache locale.
loadModel() (aliasOrModelId: string, ttl = 600) => Promise<FoundryModelInfo> Carica un modello nel server di inferenza.
unloadModel() (aliasOrModelId: string, force = false) => Promise<void> Scarica un modello dal server di inferenza.
listLoadedModels() () => Promise<FoundryModelInfo[]> Elenca tutti i modelli attualmente caricati nel servizio.

Esempio di utilizzo

Il codice seguente illustra come usare la FoundryLocalManager classe per gestire i modelli e interagire con il servizio locale Foundry.

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

Questo esempio scarica e carica un modello, quindi elenca i modelli memorizzati nella cache e caricati.

Riferimenti:

Integrazione con il client OpenAI

Installare il pacchetto OpenAI:

npm install openai

Il codice seguente illustra come integrare con FoundryLocalManager il client OpenAI per interagire con un modello locale.

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

Questo esempio trasmette una risposta di completamento della chat dal modello locale.

Riferimenti:

Utilizzo del browser

L'SDK include una versione compatibile con browser in cui è necessario specificare manualmente l'URL host:

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

Annotazioni

La versione del browser non supporta i metodi init, isServiceRunning e startService. È necessario assicurarsi che il servizio locale Foundry sia in esecuzione prima di usare l'SDK in un ambiente browser. È possibile avviare il servizio usando l'interfaccia della riga di comando locale di Foundry: foundry service start. È possibile ottenere l'URL del servizio dall'output dell'interfaccia della riga di comando.

Esempio di utilizzo

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

Riferimenti:

Informazioni di riferimento su C# SDK

Prerequisiti

  • Installare l'interfaccia della riga di comando locale di Foundry e assicurarsi che il comando sia disponibile nell'oggetto foundryPATH.

Installazione

Per usare Foundry Local C# SDK, è necessario installare il pacchetto NuGet:

dotnet add package Microsoft.AI.Foundry.Local --version 0.3.0

Nota sugli alias

Molti metodi descritti in questo riferimento hanno un aliasOrModelId parametro nella firma. È possibile passare al metodo un alias o un ID modello come valore. L'uso di un alias porterà a:

  • Selezionare il modello migliore per l'hardware disponibile. Ad esempio, se è disponibile una GPU Nvidia CUDA, Foundry Local seleziona il modello CUDA. Se è disponibile una NPU supportata, Foundry Local seleziona il modello NPU.
  • Consente di usare un nome più breve senza dover ricordare l'ID modello.

Suggerimento

È consigliabile passare al aliasOrModelId parametro un alias perché quando si distribuisce l'applicazione, Foundry Local acquisisce il modello migliore per il computer dell'utente finale in fase di esecuzione.

Annotazioni

Se si dispone di una NPU Intel in Windows, assicurarsi di aver installato il driver Intel NPU per un'accelerazione NPU ottimale.

Enumerazioni

DeviceType

Rappresenta il tipo di dispositivo utilizzato per l'esecuzione del modello.

Valore Descrizione
CPU (unità centrale di elaborazione) Dispositivo CPU
GPU (Unità di Elaborazione Grafica) Dispositivo GPU
NPU Dispositivo NPU
Non valido Non valido/sconosciuto

ExecutionProvider

Rappresenta il provider di esecuzione per l'inferenza sui modelli.

Valore Descrizione
Non valido Provider non valido
CPUExecutionProvider Esecuzione della CPU
WebGpuExecutionProvider Esecuzione di GPU Web
CUDAExecutionProvider Esecuzione di GPU CUDA
QNNExecutionProvider Esecuzione di NPU Qualcomm
OpenVINOExecutionProvider Esecuzione di Intel OpenVINO
NvTensorRTRTXExecutionProvider Esecuzione di NVIDIA TensorRT
VitisAIExecutionProvider Esecuzione di Vitis AI di AMD

Classe FoundryLocalManager

Punto di ingresso principale per la gestione di modelli, cache e servizio locale Foundry.

Costruzione

var manager = new FoundryLocalManager();

Proprietà

Proprietà Tipo Descrizione
ServiceUri Uri URI di base del servizio locale Foundry.
Punto finale Uri L'endpoint dell'API (ServiceUri + /v1).
ApiKey string Chiave API (impostazione predefinita: "OPENAI_API_KEY").
IsServiceRunning bool Indica se il servizio è in esecuzione.

Gestione dei servizi

Avviare il servizio
await manager.StartServiceAsync(CancellationToken.None);

Avvia il servizio locale Foundry se non è già in esecuzione.

Interrompere il servizio
await manager.StopServiceAsync(CancellationToken.None);

Arresta il servizio Foundry Local.

Avviare e caricare un modello (helper statico)
var manager = await FoundryLocalManager.StartModelAsync("aliasOrModelId");

Avvia il servizio e carica il modello specificato.

Gestione catalogo

Elencare tutti i modelli di catalogo
List<ModelInfo> models = await manager.ListCatalogModelsAsync();

Restituisce tutti i modelli disponibili nel catalogo.

Aggiornare il catalogo
manager.RefreshCatalog();

Cancella il catalogo memorizzato nella cache in modo che venga ricaricato al successivo accesso.

Ottenere informazioni sul modello in base all'alias o all'ID
ModelInfo? info = await manager.GetModelInfoAsync("aliasOrModelId");

Restituisce informazioni sul modello o null se non vengono trovate.

Gestione cache

Ottenere il percorso della cache
string cachePath = await manager.GetCacheLocationAsync();

Restituisce il percorso della directory in cui vengono memorizzati i modelli nella cache.

Elencare i modelli memorizzati nella cache
List<ModelInfo> cached = await manager.ListCachedModelsAsync();

Restituisce i modelli scaricati nella cache locale.

Gestione modelli

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

Scarica un modello nella cache locale.

Scaricare un modello con lo stato di avanzamento
await foreach (var progress in manager.DownloadModelWithProgressAsync("aliasOrModelId"))
{
    // progress.Percentage, progress.Status, etc.
}

Trasmette aggiornamenti sullo stato del download.

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

Carica un modello nel server di inferenza.

Elencare i modelli caricati
List<ModelInfo> loaded = await manager.ListLoadedModelsAsync();

Elenca tutti i modelli attualmente caricati nel servizio.

Scaricare un modello
await manager.UnloadModelAsync("aliasOrModelId");

Scarica un modello dal server di inferenza.

Disposizione

Implementa sia IDisposable che IAsyncDisposable per una pulizia corretta.

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

Tipi di modello

Questa pagina documenta i tipi di dati chiave usati da Foundry Local C# SDK per descrivere modelli, download e informazioni di runtime.

PromptTemplate

Rappresenta il modello di richiesta per un modello.

Proprietà Tipo Descrizione
Assistente string Il modello di richiesta dell'assistente.
Rapido string Modello di richiesta dell'utente.

Runtime

Descrive l'ambiente di runtime per un modello.

Proprietà Tipo Descrizione
Tipo di dispositivo DeviceType Tipo di dispositivo (CPU, GPU e così via).
Fornitore di Esecuzione ExecutionProvider Fornitore di esecuzione (CUDA, CPU e così via).

ModelSettings

Rappresenta i parametri specifici del modello.

Proprietà Tipo Descrizione
Parametri Lista<JsonElement> Raccolta di parametri del modello

ModelInfo

Descrive un modello nel catalogo locale o nella cache Foundry.

Proprietà Tipo Descrizione
ModelId string Identificatore univoco del modello.
DisplayName string Nome del modello leggibile da un umano.
ProviderType string Tipo di provider (ad esempio, "CUDA", "CPU").
Uri string Scarica l'URI per il modello.
Versione string Versione del modello.
Tipo di Modello string Tipo di modello (ad esempio, "llm").
PromptTemplate PromptTemplate Modello di richiesta per il modello.
Editore string Publisher del modello.
Attività string Tipo di attività (ad esempio, "chat", "completamento").
Runtime Runtime Informazioni sull'ambiente di runtime.
FileSizeMb long Dimensioni del file del modello in MB.
Impostazioni del modello Impostazioni del modello Impostazioni specifiche del modello.
Alias string Alias per il modello.
SupportsToolCalling bool Indica se la chiamata agli strumenti è supportata.
Licenza string Identificatore di licenza.
Descrizione della licenza string Descrizione della licenza.
ParentModelUri string URI del modello padre, se presente.

ModelDownloadProgress

Rappresenta lo stato di avanzamento di un'operazione di download del modello.

Proprietà Tipo Descrizione
Percentuale double Percentuale di completamento del download (0-100).
IsCompleted bool Indica se il download è stato completato.
ModelInfo ModelInfo? Informazioni sul modello se il download è stato completato.
messaggio di errore string? Messaggio di errore se il download non è riuscito.

Metodi statici:

  • Progress(double percentage): crea un aggiornamento dello stato di avanzamento.
  • Completed(ModelInfo modelInfo): creare un risultato dello stato completato.
  • Error(string errorMessage): creare un risultato di errore.

Esempio di utilizzo

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

Informazioni di riferimento su Rust SDK

Rust SDK per Foundry Local consente di gestire i modelli, controllare la cache e interagire con il servizio locale Foundry.

Prerequisiti

  • Installare l'interfaccia della riga di comando locale di Foundry e assicurarsi che il comando sia disponibile nell'oggetto foundryPATH.
  • Usare Rust 1.70.0 o versione successiva.

Installazione

Per usare Foundry Local Rust SDK, aggiungere quanto segue a Cargo.toml:

[dependencies]
foundry-local = "0.1.0"

In alternativa, è possibile aggiungere il crate cassa Foundry Local usando cargo:

cargo add foundry-local@0

Avvio rapido

Usare questo frammento di codice per verificare che l'SDK possa avviare il servizio e leggere il catalogo locale.

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

In questo esempio viene stampato un numero diverso da zero quando il servizio è in esecuzione e il catalogo è disponibile.

Riferimenti:

FoundryLocalManager

Responsabile delle operazioni di Foundry Local SDK.

Fields

  • service_uri: Option<String>: URI del servizio Foundry.
  • client: Option<HttpClient>: client HTTP per le richieste API.
  • catalog_list: Option<Vec<FoundryModelInfo>>: elenco memorizzato nella cache dei modelli di catalogo.
  • catalog_dict: Option<HashMap<String, FoundryModelInfo>>: dizionario memorizzato nella cache dei modelli di catalogo.
  • timeout: Option<u64>: timeout client HTTP facoltativo.

Methods

  • pub fn builder() -> FoundryLocalManagerBuilder
    Creare un nuovo generatore per FoundryLocalManager.

  • pub fn service_uri(&self) -> Result<&str>
    Ottenere l'URI del servizio.
    Restituisce: URI del servizio Foundry.

  • fn client(&self) -> Result<&HttpClient>
    Ottenere l'istanza del client HTTP.
    Restituisce: client HTTP.

  • pub fn endpoint(&self) -> Result<String>
    Ottenere l'endpoint per il servizio.
    Restituisce: endpoint URL.

  • pub fn api_key(&self) -> String
    Ottenere la chiave API per l'autenticazione.
    Restituisce: chiave API.

  • pub fn is_service_running(&mut self) -> bool
    Controllare se il servizio è in esecuzione e impostare l'URI del servizio, se trovato.
    Restituisce:true se è in esecuzione, altrimenti false.

  • pub fn start_service(&mut self) -> Result<()>
    Avvia il servizio locale Foundry.

  • pub async fn list_catalog_models(&mut self) -> Result<&Vec<FoundryModelInfo>>
    Ottenere un elenco dei modelli disponibili nel catalogo.

  • pub fn refresh_catalog(&mut self)
    Aggiornare la cache del catalogo.

  • pub async fn get_model_info(&mut self, alias_or_model_id: &str, raise_on_not_found: bool) -> Result<FoundryModelInfo>
    Ottenere informazioni sul modello in base all'alias o all'ID.
    Argomenti:

    • alias_or_model_id: alias o ID modello.
    • raise_on_not_found: Se true, errore se non trovato.

  • pub async fn get_cache_location(&self) -> Result<String>
    Ottieni il percorso della cache come stringa.

  • pub async fn list_cached_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    Elencare i modelli memorizzati nella cache.

  • pub async fn download_model(&mut self, alias_or_model_id: &str, token: Option<&str>, force: bool) -> Result<FoundryModelInfo>
    Scaricare un modello.
    Argomenti:

    • alias_or_model_id: alias o ID modello.
    • token: token di autenticazione facoltativo.
    • force: forzare il download se già memorizzato nella cache.

  • pub async fn load_model(&mut self, alias_or_model_id: &str, ttl: Option<i32>) -> Result<FoundryModelInfo>
    Caricare un modello per l'inferenza.
    Argomenti:

    • alias_or_model_id: alias o ID modello.
    • ttl: time-to-live opzionale in secondi.

  • pub async fn unload_model(&mut self, alias_or_model_id: &str, force: bool) -> Result<()>
    Scaricare un modello.
    Argomenti:

    • alias_or_model_id: alias o ID modello.
    • force: forza lo scaricamento anche se in uso.

  • pub async fn list_loaded_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    Elencare i modelli caricati.

FoundryLocalManagerBuilder

Generatore per la creazione di un'istanza FoundryLocalManager.

Fields

  • alias_or_model_id: Option<String> — Alias o ID del modello da scaricare e caricare.
  • bootstrap: bool — Indica se avviare il servizio se non è in esecuzione.
  • timeout_secs: Option<u64> — Timeout del client HTTP in secondi.

Methods

  • pub fn new() -> Self
    Creare una nuova istanza di generatore.

  • pub fn alias_or_model_id(mut self, alias_or_model_id: impl Into<String>) -> Self
    Impostare l'alias o l'ID modello per il download e il caricamento.

  • pub fn bootstrap(mut self, bootstrap: bool) -> Self
    Imposta se avviare il servizio quando non è in esecuzione.

  • pub fn timeout_secs(mut self, timeout_secs: u64) -> Self
    Impostare un timeout del client HTTP in secondi.

  • pub async fn build(self) -> Result<FoundryLocalManager>
    Creare l'istanza FoundryLocalManager.

FoundryModelInfo

Rappresenta informazioni su un modello.

Fields

  • alias: String — L'alias del modello.
  • id: String — ID modello.
  • version: String — La versione del modello.
  • runtime: ExecutionProvider — Il provider di esecuzione (CPU, CUDA e così via).
  • uri: String — URI del modello.
  • file_size_mb: i32 — Dimensioni del file del modello in MB.
  • prompt_template: serde_json::Value — Richiedi modello per il modello.
  • provider: String — Nome del provider.
  • publisher: String : nome Publisher.
  • license: String — Tipo di licenza.
  • task: String — Attività modello (ad esempio, generazione di testo).

Methods

  • from_list_response(response: &FoundryListResponseModel) -> Self
    Crea un oggetto FoundryModelInfo da una risposta del catalogo.

  • to_download_body(&self) -> serde_json::Value
    Converte le informazioni sul modello in un corpo JSON per le richieste di download.

ExecutionProvider

Enumerazione per i provider di esecuzione supportati.

  • CPU
  • WebGPU
  • CUDA
  • QNN
Methods
  • get_alias(&self) -> String
    Restituisce un alias stringa per il provider di esecuzione.

ModelRuntime

Descrive l'ambiente di runtime per un modello.

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