Partilhar via

Referência do SDK Legado Local da Fundição

Advertência

Esta referência aplica-se a versões anteriores do Foundry Local SDK que dependem da CLI Foundry Local para gestão de serviços.

Para novos desenvolvimentos, use a referência atual do SDK.

A tabela seguinte mostra as versões do SDK onde havia dependência da CLI:

Linguagem Package Versões dependentes da CLI
C# Microsoft. IA. Foundry.Local 0.3.0 e anteriores
JavaScript Foundry-local-SDK 0.5.0 e anteriores
Python Foundry-local-SDK 0.5.1 e anteriores
Ferrugem Fundição-local / Fundição-local-SDK 0.x

O suporte para versões dependentes de CLI termina a 31 de agosto de 2026.

Referência do SDK Python

Pré-requisitos

  • Instale a CLI local do Foundry e certifique-se de que o foundry comando está disponível no seu PATHarquivo .
  • Usa Python 3.9 ou posterior.

Instalação

Instale o pacote Python:

pip install foundry-local-sdk==0.5.1

Início Rápido

Use este excerto para verificar se o SDK pode iniciar o serviço e aceder ao catálogo local.

from foundry_local import FoundryLocalManager

manager = FoundryLocalManager()
manager.start_service()

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

Este exemplo imprime um número diferente de zero quando o serviço está em execução e o catálogo está disponível.

Referências:

Classe FoundryLocalManager

A FoundryLocalManager classe fornece métodos para gerenciar modelos, cache e o serviço Foundry Local.

Inicialização

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: (opcional) Alias ou ID do modelo para baixar e carregar na inicialização.
  • bootstrap: (padrão True) Se True, inicia o serviço se não estiver em execução e carrega o modelo, se fornecido.

Uma nota sobre pseudónimos

Muitos métodos descritos nesta referência têm um alias_or_model_id parâmetro na assinatura. Você pode passar para o método um alias ou ID de modelo como um valor. O uso de um alias irá:

  • Selecione o melhor modelo para o hardware disponível. Por exemplo, se uma GPU Nvidia CUDA estiver disponível, o Foundry Local selecionará o modelo CUDA. Se uma NPU suportada estiver disponível, o Foundry Local selecionará o modelo de NPU.
  • Permitir que você use um nome mais curto sem precisar lembrar o ID do modelo.

Sugestão

Recomendamos passar para o alias_or_model_id parâmetro um alias porque quando você implanta seu aplicativo, o Foundry Local adquire o melhor modelo para a máquina do usuário final em tempo de execução.

Observação

Se tiver uma NPU Intel na Windows, certifique-se de que instalou o driver NPU Intel para uma aceleração NPU ótima.

Gestão de Serviços

Método Signature Descrição
is_service_running() () -> bool Verifica se o serviço Foundry Local está em execução.
start_service() () -> None Inicia o serviço Foundry Local.
service_uri @property -> str Retorna o URI do serviço.
endpoint @property -> str Retorna o ponto de extremidade do serviço.
api_key @property -> str Retorna a chave da API (de env ou padrão).

Gestão de Catálogos

Método Signature Descrição
list_catalog_models() () -> list[FoundryModelInfo] Lista todos os modelos disponíveis no catálogo.
refresh_catalog() () -> None Atualiza o catálogo de modelos.
get_model_info() (alias_or_model_id: str, raise_on_not_found=False) -> FoundryModelInfo \| None Obtém informações do modelo por alias ou ID.

Gerenciamento de cache

Método Signature Descrição
get_cache_location() () -> str Retorna o caminho do diretório de cache do modelo.
list_cached_models() () -> list[FoundryModelInfo] Lista os modelos baixados para o cache local.

Gestão de Modelos

Método Signature Descrição
download_model() (alias_or_model_id: str, token: str = None, force: bool = False) -> FoundryModelInfo Baixa um modelo para o cache local.
load_model() (alias_or_model_id: str, ttl: int = 600) -> FoundryModelInfo Carrega um modelo no servidor de inferência.
unload_model() (alias_or_model_id: str, force: bool = False) -> None Descarrega um modelo do servidor de inferência.
list_loaded_models() () -> list[FoundryModelInfo] Lista todos os modelos atualmente carregados no serviço.

FoundryModelInfo

Os métodos list_catalog_models(), , e list_cached_models() retornam uma lista de list_loaded_models() objetosFoundryModelInfo. Pode usar a informação contida neste objeto para refinar ainda mais a lista. Ou obter a informação de um modelo diretamente chamando o get_model_info(alias_or_model_id) método.

Estes objetos contêm os seguintes campos:

Campo Tipo Descrição
alias str Pseudónimo do modelo.
id str Identificador exclusivo do modelo.
version str Versão do modelo.
execution_provider str O acelerador (fornecedor de execução) era usado para executar o modelo.
device_type DeviceType Tipo de dispositivo do modelo: CPU, GPU, NPU.
uri str URI do modelo.
file_size_mb int Tamanho do modelo no disco em MB.
supports_tool_calling bool Se o modelo permite chamadas de ferramentas.
prompt_template dict \| None Modelo de prompt para o modelo.
provider str Fornecedor do modelo (onde o modelo é publicado).
publisher str Publisher do modelo (que publicou o modelo).
license str O nome da licença do modelo.
task str Tarefa do modelo. Um dos chat-completions ou automatic-speech-recognition.
ep_override str \| None Override para o fornecedor de execução, se for diferente do padrão do modelo.

Fornecedores de Execução

Um dos seguintes:

  • CPUExecutionProvider - Execução baseada em CPU
  • CUDAExecutionProvider - Execução de GPU NVIDIA CUDA
  • WebGpuExecutionProvider - Execução WebGPU
  • QNNExecutionProvider - Execução de Rede Neural Qualcomm (NPU)
  • OpenVINOExecutionProvider - Execução Intel OpenVINO
  • NvTensorRTRTXExecutionProvider - Execução NVIDIA TensorRT
  • VitisAIExecutionProvider - Execução de IA AMD Vitis

Exemplo de Utilização

O código a seguir demonstra como usar a FoundryLocalManager classe para gerenciar modelos e interagir com o serviço Foundry Local.

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)

Este exemplo lista modelos, faz o download e carrega um modelo, e depois liberta-o.

Referências:

Integração com OpenAI SDK

Instale o pacote OpenAI:

pip install openai

O código a seguir demonstra como integrar o FoundryLocalManager com o OpenAI SDK para interagir com um modelo local.

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)

Este exemplo transmite uma resposta de conclusão de chat a partir do modelo local.

Referências:

Referência do SDK JavaScript

Pré-requisitos

  • Instale a CLI local do Foundry e certifique-se de que o comando foundry está disponível no seu PATH sistema.

Instalação

Instale o pacote a partir do npm:

npm install foundry-local-sdk@0.5.0

Início Rápido

Use este excerto para verificar se o SDK pode iniciar o serviço e aceder ao catálogo local.

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

Este exemplo imprime um número diferente de zero quando o serviço está em execução e o catálogo está disponível.

Referências:

Classe FoundryLocalManager

A FoundryLocalManager classe permite gerenciar modelos, controlar o cache e interagir com o serviço Foundry Local em ambientes de navegador e Node.js.

Inicialização

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

const foundryLocalManager = new FoundryLocalManager();

Opções disponíveis:

  • host: URL base do serviço Foundry Local
  • fetch: (opcional) Implementação de busca personalizada para ambientes como Node.js

Uma nota sobre pseudónimos

Muitos métodos descritos nesta referência têm um aliasOrModelId parâmetro na assinatura. Você pode passar para o método um alias ou ID de modelo como um valor. O uso de um alias irá:

  • Selecione o melhor modelo para o hardware disponível. Por exemplo, se uma GPU Nvidia CUDA estiver disponível, o Foundry Local selecionará o modelo CUDA. Se uma NPU suportada estiver disponível, o Foundry Local selecionará o modelo de NPU.
  • Permitir que você use um nome mais curto sem precisar lembrar o ID do modelo.

Sugestão

Recomendamos passar para o aliasOrModelId parâmetro um alias porque quando você implanta seu aplicativo, o Foundry Local adquire o melhor modelo para a máquina do usuário final em tempo de execução.

Observação

Se tiver uma NPU Intel na Windows, certifique-se de que instalou o driver NPU Intel para uma aceleração NPU ótima.

Gestão de Serviços

Método Signature Descrição
init() (aliasOrModelId?: string) => Promise<FoundryModelInfo \| void> Inicializa o SDK e, opcionalmente, carrega um modelo.
isServiceRunning() () => Promise<boolean> Verifica se o serviço Foundry Local está em execução.
startService() () => Promise<void> Inicia o serviço Foundry Local.
serviceUrl string A URL base do serviço Foundry Local.
endpoint string O ponto de extremidade da API (serviceUrl + /v1).
apiKey string Chave da API (nenhuma)

Gestão de Catálogos

Método Signature Descrição
listCatalogModels() () => Promise<FoundryModelInfo[]> Lista todos os modelos disponíveis no catálogo.
refreshCatalog() () => Promise<void> Atualiza o catálogo de modelos.
getModelInfo() (aliasOrModelId: string, throwOnNotFound = false) => Promise<FoundryModelInfo \| null> Obtém informações do modelo por alias ou ID.

Gerenciamento de cache

Método Signature Descrição
getCacheLocation() () => Promise<string> Retorna o caminho do diretório de cache do modelo.
listCachedModels() () => Promise<FoundryModelInfo[]> Lista os modelos baixados para o cache local.

Gestão de Modelos

Método Signature Descrição
downloadModel() (aliasOrModelId: string, token?: string, force = false, onProgress?) => Promise<FoundryModelInfo> Baixa um modelo para o cache local.
loadModel() (aliasOrModelId: string, ttl = 600) => Promise<FoundryModelInfo> Carrega um modelo no servidor de inferência.
unloadModel() (aliasOrModelId: string, force = false) => Promise<void> Descarrega um modelo do servidor de inferência.
listLoadedModels() () => Promise<FoundryModelInfo[]> Lista todos os modelos atualmente carregados no serviço.

Exemplo de Utilização

O código a seguir demonstra como usar a FoundryLocalManager classe para gerenciar modelos e interagir com o serviço Foundry Local.

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

Este exemplo descarrega e carrega um modelo, depois lista os modelos em cache e carregados.

Referências:

Integração com OpenAI Client

Instale o pacote OpenAI:

npm install openai

O código a seguir demonstra como integrar o FoundryLocalManager com o cliente OpenAI para interagir com um modelo local.

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

Este exemplo transmite uma resposta de conclusão de chat a partir do modelo local.

Referências:

Utilização do navegador

O SDK inclui uma versão compatível com browser, onde deve especificar manualmente a URL do anfitrião:

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

Observação

A versão do navegador não suporta os initmétodos , isServiceRunninge startService . Você deve garantir que o serviço Foundry Local esteja em execução antes de usar o SDK em um ambiente de navegador. Você pode iniciar o serviço usando a CLI local do Foundry: foundry service start. Você pode obter a URL do serviço a partir da saída da CLI.

Exemplo de Utilização

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

Referências:

Referência do SDK do C#

Pré-requisitos

  • Instale a CLI local do Foundry e certifique-se de que o foundry comando está disponível no seu PATHarquivo .

Instalação

Para usar o SDK do C# Local do Foundry, você precisa instalar o pacote NuGet:

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

Uma nota sobre pseudónimos

Muitos métodos descritos nesta referência têm um aliasOrModelId parâmetro na assinatura. Você pode passar para o método um alias ou ID de modelo como um valor. O uso de um alias irá:

  • Selecione o melhor modelo para o hardware disponível. Por exemplo, se uma GPU Nvidia CUDA estiver disponível, o Foundry Local selecionará o modelo CUDA. Se uma NPU suportada estiver disponível, o Foundry Local selecionará o modelo de NPU.
  • Permitir que você use um nome mais curto sem precisar lembrar o ID do modelo.

Sugestão

Recomendamos passar para o aliasOrModelId parâmetro um alias porque quando você implanta seu aplicativo, o Foundry Local adquire o melhor modelo para a máquina do usuário final em tempo de execução.

Observação

Se tiver uma NPU Intel na Windows, certifique-se de que instalou o driver NPU Intel para uma aceleração NPU ótima.

Enumerações

DeviceType

Representa o tipo de dispositivo usado para a execução do modelo.

Valor Descrição
CPU Dispositivo CPU
GPU Dispositivo GPU
NPU (Unidade de Processamento Neural) Dispositivo NPU
Inválido Inválido/desconhecido

ExecutionProvider

Representa o provedor de execução para inferência de modelo.

Valor Descrição
Inválido Provedor inválido
ProvedorDeExecuçãoCPU Execução da CPU
WebGpuExecutionProvider Execução de WebGPU
Provedor de Execução CUDA (CUDAExecutionProvider) Execução de GPU CUDA
QNNExecutionProvider Execução de NPU Qualcomm
OpenVINOExecutionProvider Execução do Intel OpenVINO
NvTensorRTRTXExecutionProvider Execução NVIDIA TensorRT
VitisAIExecutionProvider Execução de IA AMD Vitis

FoundryLocalManager Classe

O principal ponto de entrada para gerenciar modelos, cache e o serviço Foundry Local.

Construção

var manager = new FoundryLocalManager();

Propriedades

Propriedade Tipo Descrição
ServiceUri Uri O URI base do serviço Foundry Local.
Ponto final Uri O ponto de extremidade da API (ServiceUri + /v1).
ApiKey string A chave da API (padrão: "OPENAI_API_KEY").
IsServiceRunning bool Indica se o serviço está em execução.

Gestão de Serviços

Iniciar o serviço
await manager.StartServiceAsync(CancellationToken.None);

Inicia o serviço Foundry Local se ainda não estiver em execução.

Parar o serviço
await manager.StopServiceAsync(CancellationToken.None);

Interrompe o serviço local da Foundry.

Iniciar e carregar um modelo (auxiliar estático)
var manager = await FoundryLocalManager.StartModelAsync("aliasOrModelId");

Inicia o serviço e carrega o modelo especificado.

Gestão de Catálogos

Listar todos os modelos de catálogo
List<ModelInfo> models = await manager.ListCatalogModelsAsync();

Retorna todos os modelos disponíveis no catálogo.

Atualizar o catálogo
manager.RefreshCatalog();

Limpa o catálogo armazenado em cache para que ele seja recarregado no próximo acesso.

Obter informações do modelo por alias ou ID
ModelInfo? info = await manager.GetModelInfoAsync("aliasOrModelId");

Retorna as informações do modelo ou null se não forem encontradas.

Gerenciamento de cache

Obter localização do cache
string cachePath = await manager.GetCacheLocationAsync();

Retorna o caminho do diretório onde os modelos são armazenados em cache.

Listar modelos armazenados em cache
List<ModelInfo> cached = await manager.ListCachedModelsAsync();

Retorna modelos baixados para o cache local.

Gestão de Modelos

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

Baixa um modelo para o cache local.

Faça o download de um modelo com acompanhamento de progresso
await foreach (var progress in manager.DownloadModelWithProgressAsync("aliasOrModelId"))
{
    // progress.Percentage, progress.Status, etc.
}

Os streams baixam atualizações de progresso.

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

Carrega um modelo no servidor de inferência.

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

Lista todos os modelos atualmente carregados no serviço.

Descarregar um modelo
await manager.UnloadModelAsync("aliasOrModelId");

Descarrega um modelo do servidor de inferência.

Eliminação

Implementa ambos IDisposable e IAsyncDisposable para uma limpeza adequada.

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

Tipos de modelo

Esta página documenta os principais tipos de dados usados pelo SDK C# Local do Foundry para descrever modelos, downloads e informações de tempo de execução.

PromptTemplate

Representa o modelo de prompt para um sistema.

Propriedade Tipo Descrição
Assistente cadeia (de caracteres) O modelo de prompt do assistente.
Prompt cadeia (de caracteres) O modelo de aviso do usuário.

Runtime

Descreve o ambiente de tempo de execução para um modelo.

Propriedade Tipo Descrição
Tipo de dispositivo DeviceType O tipo de dispositivo (CPU, GPU, etc).
ExecutionProvider ExecutionProvider O provedor de execução (CUDA, CPU, etc).

ModelSettings

Representa parâmetros específicos do modelo.

Propriedade Tipo Descrição
Parâmetros Lista<JsonElement> Coleção de parâmetros do modelo

ModelInfo

Descreve um modelo no catálogo ou cache do Foundry Local.

Propriedade Tipo Descrição
ModelId cadeia (de caracteres) Identificador de modelo único.
Nome de Exibição cadeia (de caracteres) Nome do modelo legível por humanos.
Tipo de provedor cadeia (de caracteres) Tipo de provedor (por exemplo, "CUDA", "CPU").
Uri cadeia (de caracteres) Descarregar URI do modelo.
Versão cadeia (de caracteres) Versão do modelo.
Tipo de modelo cadeia (de caracteres) Tipo de modelo (por exemplo, "llm").
PromptTemplate PromptTemplate Modelo de prompt para o modelo.
Publisher cadeia (de caracteres) Publisher do modelo.
Tarefa cadeia (de caracteres) Tipo de tarefa (por exemplo, "chat", "conclusão").
Tempo de execução Tempo de execução Informações do ambiente de tempo de execução.
Tamanho do arquivoMb long Tamanho do ficheiro do modelo em MB.
Configurações do Modelo Configurações do Modelo Configurações específicas do modelo.
Alias cadeia (de caracteres) Alias para o modelo.
SupportsToolCalling booleano Se a chamada de ferramentas é suportada.
Licença cadeia (de caracteres) Identificador de licença.
Descrição da Licença cadeia (de caracteres) Descrição da licença.
ParentModelUri cadeia (de caracteres) URI do modelo pai, se houver.

ModelDownloadProgress

Representa o progresso de uma operação de download de modelo.

Propriedade Tipo Descrição
Percentagem duplo Percentagem de conclusão do download (0-100).
EstáConcluído booleano Se o download está concluído.
ModelInfo ModelInfo? Informações do modelo caso o download seja concluído.
Mensagem de Erro string? Mensagem de erro se o download falhar.

Métodos estáticos:

  • Progress(double percentage): Crie uma atualização de progresso.
  • Completed(ModelInfo modelInfo): Crie um resultado de progresso concluído.
  • Error(string errorMessage): Crie um resultado de erro.

Exemplo de Utilização

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

Referência do SDK do Rust

O SDK do Rust para Foundry Local fornece uma maneira de gerenciar modelos, controlar o cache e interagir com o serviço Foundry Local.

Pré-requisitos

  • Instale a CLI local do Foundry e certifique-se de que o foundry comando está disponível no seu PATHarquivo .
  • Usa o Rust 1.70.0 ou posterior.

Instalação

Para usar o SDK do Foundry Local Rust, adicione o seguinte ao seu Cargo.toml:

[dependencies]
foundry-local = "0.1.0"

Como alternativa, pode adicionar a caixa Foundry Local usando cargo:

cargo add foundry-local@0

Início Rápido

Use este excerto para verificar se o SDK pode iniciar o serviço e ler o catálogo local.

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

Este exemplo imprime um número não nulo quando o serviço está a correr e o catálogo está disponível.

Referências:

FoundryLocalManager

Gerente de operações do SDK local do Foundry.

Fields

  • service_uri: Option<String>: URI do serviço Foundry.
  • client: Option<HttpClient>: Cliente HTTP para pedidos de API.
  • catalog_list: Option<Vec<FoundryModelInfo>>: Lista em cache de modelos de catálogo.
  • catalog_dict: Option<HashMap<String, FoundryModelInfo>>: Dicionário em cache de modelos de catálogo.
  • timeout: Option<u64>: Time out opcional do cliente HTTP.

Methods

  • pub fn builder() -> FoundryLocalManagerBuilder
    Crie um novo construtor para FoundryLocalManager.

  • pub fn service_uri(&self) -> Result<&str>
    Obtenha o URI de serviço.
    Retorno: URI do serviço Foundry.

  • fn client(&self) -> Result<&HttpClient>
    Obtenha a instância do cliente HTTP.
    Devoluções: Cliente HTTP.

  • pub fn endpoint(&self) -> Result<String>
    Obtenha o ponto final para o serviço.
    Devoluções: URL do ponto final.

  • pub fn api_key(&self) -> String
    Obtenha a chave de API para autenticação.
    Devoluções: Chave da API.

  • pub fn is_service_running(&mut self) -> bool
    Verifique se o serviço está em execução e defina o URI do serviço, se encontrado.
    Devoluções:true se estiver em execução, false caso contrário.

  • pub fn start_service(&mut self) -> Result<()>
    Inicie o serviço Foundry Local.

  • pub async fn list_catalog_models(&mut self) -> Result<&Vec<FoundryModelInfo>>
    Obtenha uma lista de modelos disponíveis no catálogo.

  • pub fn refresh_catalog(&mut self)
    Atualize o cache do catálogo.

  • pub async fn get_model_info(&mut self, alias_or_model_id: &str, raise_on_not_found: bool) -> Result<FoundryModelInfo>
    Obtenha informações do modelo por alias ou ID.
    Argumentos:

    • alias_or_model_id: Alias ou ID do modelo.
    • raise_on_not_found: Se verdadeiro, erro se não encontrado.

  • pub async fn get_cache_location(&self) -> Result<String>
    Obtenha o local do cache como uma cadeia de caracteres.

  • pub async fn list_cached_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    Listar modelos armazenados em cache.

  • pub async fn download_model(&mut self, alias_or_model_id: &str, token: Option<&str>, force: bool) -> Result<FoundryModelInfo>
    Faça o download de um modelo.
    Argumentos:

    • alias_or_model_id: Alias ou ID do modelo.
    • token: Token de autenticação opcional.
    • force: Forçar o download se já estiver em cache.

  • pub async fn load_model(&mut self, alias_or_model_id: &str, ttl: Option<i32>) -> Result<FoundryModelInfo>
    Carregue um modelo para inferência.
    Argumentos:

    • alias_or_model_id: Alias ou ID do modelo.
    • ttl: Tempo de vida opcional em segundos.

  • pub async fn unload_model(&mut self, alias_or_model_id: &str, force: bool) -> Result<()>
    Descarregue um modelo.
    Argumentos:

    • alias_or_model_id: Alias ou ID do modelo.
    • force: Descarregamento forçado mesmo que esteja em uso.

  • pub async fn list_loaded_models(&mut self) -> Result<Vec<FoundryModelInfo>>
    Listar modelos carregados.

FoundryLocalManagerBuilder

Construtor para criar uma FoundryLocalManager instância.

Fields

  • alias_or_model_id: Option<String> — Alias ou ID do modelo para baixar e carregar.
  • bootstrap: bool — Se o serviço deve ser iniciado se não estiver em execução.
  • timeout_secs: Option<u64> — Tempo limite do cliente HTTP em segundos.

Methods

  • pub fn new() -> Self
    Crie uma nova instância do construtor.

  • pub fn alias_or_model_id(mut self, alias_or_model_id: impl Into<String>) -> Self
    Defina o alias ou ID do modelo para baixar e carregar.

  • pub fn bootstrap(mut self, bootstrap: bool) -> Self
    Defina se o serviço deve ser iniciado se não estiver em execução.

  • pub fn timeout_secs(mut self, timeout_secs: u64) -> Self
    Defina o tempo limite do cliente HTTP em segundos.

  • pub async fn build(self) -> Result<FoundryLocalManager>
    Crie a FoundryLocalManager instância.

FoundryModelInfo

Representa informações sobre um modelo.

Fields

  • alias: String — O alias do modelo.
  • id: String — O ID do modelo.
  • version: String — A versão do modelo.
  • runtime: ExecutionProvider — O provedor de execução (CPU, CUDA, etc.).
  • uri: String — O modelo URI.
  • file_size_mb: i32 — Tamanho do ficheiro do modelo em MB.
  • prompt_template: serde_json::Value — Modelo de prompt para o modelo.
  • provider: String — Nome do fornecedor.
  • publisher: String — Nome do Publicador.
  • license: String — Tipo de licença.
  • task: String — Tarefa de modelar (por exemplo, geração de texto).

Methods

  • from_list_response(response: &FoundryListResponseModel) -> Self
    Cria um FoundryModelInfo a partir de uma resposta do catálogo.

  • to_download_body(&self) -> serde_json::Value
    Converte as informações do modelo em um corpo JSON para solicitações de download.

ExecutionProvider

Enum para provedores de execução suportados.

  • CPU
  • WebGPU
  • CUDA
  • QNN
Methods
  • get_alias(&self) -> String
    Retorna um alias de cadeia de caracteres para o provedor de execução.

ModelRuntime

Descreve o ambiente de tempo de execução para um modelo.

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