Справочник по локальному устаревшему SDK для Foundry

Справочник по пакету SDK Python

Необходимые условия

• Установите локальный интерфейс командной строки Foundry и убедитесь, foundry что команда доступна в вашей PATHсреде.
• Используйте Python версии 3.9 или более поздней версии.

Installation

Установите пакет Python:

pip install foundry-local-sdk==0.5.1

Быстрый старт

Используйте этот фрагмент кода, чтобы убедиться, что пакет SDK может запустить службу и получить доступ к локальному каталогу.

from foundry_local import FoundryLocalManager

manager = FoundryLocalManager()
manager.start_service()

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

В этом примере выводится ненулевое число при запуске службы, а каталог доступен.

Ссылки:

• Интеграция с пакетами SDK для вывода

Класс FoundryLocalManager

Класс FoundryLocalManager предоставляет методы для управления моделями, кэшем и локальной службой Foundry.

Инициализация

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: (необязательно) Псевдоним или идентификатор модели для скачивания и загрузки при запуске.
• bootstrap: (по умолчанию true) Если значение true, запускает службу, если она не запущена и загружает модель, если она указана.

Примечание по псевдонимам

Многие методы, описанные в этой ссылке, имеют alias_or_model_id параметр в сигнатуре. Можно передать в метод псевдоним или идентификатор модели в качестве значения. Использование псевдонима позволит:

• Выберите лучшую модель для доступного оборудования. Например, если gpu Nvidia CUDA доступен, Foundry Local выбирает модель CUDA. Если доступен поддерживаемый NPU, Foundry Local выбирает модель NPU.
• Позволяет использовать более короткое имя без необходимости запоминать идентификатор модели.

Управление сервисом

Управление каталогами

Управление кэшем

Управление моделями

FoundryModelInfo

Методы list_catalog_models()list_cached_models()и list_loaded_models() возвращает список FoundryModelInfo объектов. Для дальнейшего уточнения списка можно использовать сведения, содержащиеся в этом объекте. Или получите сведения для модели непосредственно путем вызова get_model_info(alias_or_model_id) метода.

Эти объекты содержат следующие поля:

Поставщики выполнения

Одно из:

• CPUExecutionProvider — выполнение на базе ЦПУ
• CUDAExecutionProvider — выполнение GPU NVIDIA CUDA
• WebGpuExecutionProvider — выполнение WebGPU
• QNNExecutionProvider - Выполнение нейронной сети Qualcomm (NPU)
• OpenVINOExecutionProvider — Выполнение Intel OpenVINO
• NvTensorRTRTXExecutionProvider — выполнение NVIDIA TensorRT
• VitisAIExecutionProvider — выполнение ИИ AMD Vitis

Пример использования

В следующем коде показано, как использовать FoundryLocalManager класс для управления моделями и взаимодействия с локальной службой 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)

В этом примере перечислены модели, загружается и скачивается одна из них, а затем выгружается.

Ссылки:

• Интеграция с пакетами SDK для вывода

Интеграция с пакетом SDK OpenAI

Установите пакет OpenAI:

pip install openai

В следующем коде демонстрируется, как интегрировать FoundryLocalManager с SDK OpenAI для взаимодействия с локальной моделью.

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)

В этом примере выполняется потоковая передача ответа на завершение чата из локальной модели.

Ссылки:

• Интеграция с пакетами SDK для вывода

Справочник по пакету SDK для JavaScript

Необходимые условия

• Установите локальный интерфейс командной строки Foundry и убедитесь, foundry что команда доступна в вашей PATHсреде.

Installation

Установите пакет из npm:

npm install foundry-local-sdk@0.5.0

Быстрый старт

Используйте этот фрагмент кода, чтобы убедиться, что пакет SDK может запустить службу и получить доступ к локальному каталогу.

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

В этом примере выводится ненулевое число при запуске службы, а каталог доступен.

Ссылки:

• Интеграция с пакетами SDK для вывода

Класс FoundryLocalManager

Класс FoundryLocalManager позволяет управлять моделями, управлять кэшем и взаимодействовать с локальной службой Foundry в браузерах и Node.js средах.

Инициализация

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

const foundryLocalManager = new FoundryLocalManager();

Доступные варианты:

• host: базовый URL-адрес локальной службы Foundry
• fetch: (необязательно) Настраиваемая функция извлечения для таких сред, как Node.js

Примечание по псевдонимам

Многие методы, описанные в этой ссылке, имеют aliasOrModelId параметр в сигнатуре. Можно передать в метод псевдоним или идентификатор модели в качестве значения. Использование псевдонима позволит:

• Выберите лучшую модель для доступного оборудования. Например, если gpu Nvidia CUDA доступен, Foundry Local выбирает модель CUDA. Если доступен поддерживаемый NPU, Foundry Local выбирает модель NPU.
• Позволяет использовать более короткое имя без необходимости запоминать идентификатор модели.

Управление сервисом

Управление каталогами

Управление кэшем

Управление моделями

Пример использования

В следующем коде показано, как использовать FoundryLocalManager класс для управления моделями и взаимодействия с локальной службой 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);

В этом примере скачиваются и загружаются модели, а затем перечисляются кэшированные и загруженные модели.

Ссылки:

• Интеграция с пакетами SDK для вывода

Интеграция с клиентом OpenAI

Установите пакет OpenAI:

npm install openai

В следующем коде показано, как интегрировать FoundryLocalManager с клиентом OpenAI для взаимодействия с локальной моделью.

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

В этом примере выполняется потоковая передача ответа на завершение чата из локальной модели.

Ссылки:

• Интеграция с пакетами SDK для вывода

Использование браузера

Пакет SDK включает версию, совместимую с браузером, где необходимо указать URL-адрес узла вручную:

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

Пример использования

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

Ссылки:

• Интеграция с пакетами SDK для вывода

Справочник по пакету SDK для C#

Необходимые условия

• Установите локальный интерфейс командной строки Foundry и убедитесь, foundry что команда доступна в вашей PATHсреде.

Installation

Чтобы использовать Local C# SDK Foundry, необходимо установить пакет NuGet:

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

Примечание по псевдонимам

Многие методы, описанные в этой ссылке, имеют aliasOrModelId параметр в сигнатуре. Можно передать в метод псевдоним или идентификатор модели в качестве значения. Использование псевдонима позволит:

• Выберите лучшую модель для доступного оборудования. Например, если gpu Nvidia CUDA доступен, Foundry Local выбирает модель CUDA. Если доступен поддерживаемый NPU, Foundry Local выбирает модель NPU.
• Позволяет использовать более короткое имя без необходимости запоминать идентификатор модели.

Перечисления

DeviceType

Представляет тип устройства, используемого для выполнения модели.

ExecutionProvider

Представляет поставщика выполнения для вывода модели.

Класс FoundryLocalManager

Основная точка входа для управления моделями, кэшем и локальной службой Foundry.

Строительство

var manager = new FoundryLocalManager();

Свойства

Управление сервисом

Запуск службы

await manager.StartServiceAsync(CancellationToken.None);

Запускает локальную службу Foundry, если она еще не запущена.

Остановка службы

await manager.StopServiceAsync(CancellationToken.None);

Останавливает локальную службу Foundry.

Запуск и загрузка модели (статическое вспомогательное средство)

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

Запускает службу и загружает указанную модель.

Управление каталогами

Перечислить все модели каталога

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

Возвращает все доступные модели в каталоге.

Обновление каталога

manager.RefreshCatalog();

Очищает кэшированный каталог, чтобы он был перезагружен при следующем доступе.

Получение сведений о модели по псевдониму или идентификатору

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

Возвращает сведения о модели или null, если не найдено.

Управление кэшем

Получение расположения кэша

string cachePath = await manager.GetCacheLocationAsync();

Возвращает путь к каталогу, в котором кэшируются модели.

Список кэшированных моделей

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

Возвращает модели, скачанные в локальный кэш.

Управление моделями

Скачивание модели

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

Загружает модель в локальный кэш.

Скачивание модели с прогрессом

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

Потоки обновляют информацию о ходе загрузки.

Загрузка модели

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

Загружает модель на сервер вывода.

Список загруженных моделей

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

Выводит список всех моделей, загруженных в настоящее время в сервисе.

Выгрузите модель

await manager.UnloadModelAsync("aliasOrModelId");

Выгружает модель с сервера вывода.

Устранение

Реализует оба IDisposable и IAsyncDisposable для правильной очистки.

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

Типы моделей

На этой странице описаны ключевые типы данных, используемые пакетом SDK для Foundry Local C# для описания моделей, загрузки и сведений о среде выполнения.

PromptTemplate

Представляет шаблон подсказки для модели.

Runtime

Описывает среду выполнения для модели.

ModelSettings

Представляет параметры, относящиеся к модели.

ModelInfo

Описывает модель в локальном каталоге Или кэше Foundry.

ModelDownloadProgress

Представляет ход выполнения операции скачивания модели.

Статические методы:

• Progress(double percentage): Подготовьте обновление хода выполнения.
• Completed(ModelInfo modelInfo): создайте завершенный результат выполнения.
• Error(string errorMessage): создать сообщение об ошибке.

Пример использования

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

Справочник по пакету SDK Rust

Пакет SDK Rust для Foundry Local позволяет управлять моделями, управлять кэшем и взаимодействовать с локальной службой Foundry.

Необходимые условия

• Установите локальный интерфейс командной строки Foundry и убедитесь, foundry что команда доступна в вашей PATHсреде.
• Используйте Rust 1.70.0 или более поздней версии.

Installation

Чтобы использовать локальный SDK Foundry для Rust, добавьте следующее в Cargo.toml:

[dependencies]
foundry-local = "0.1.0"

Кроме того, можно добавить локальный модуль Foundry с помощью cargo:

cargo add foundry-local@0

Быстрый старт

Используйте этот фрагмент кода, чтобы убедиться, что пакет SDK может запустить службу и прочитать локальный каталог.

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

В этом примере выводится ненулевое число, когда служба запущена, и каталог доступен.

Ссылки:

• Локальная документация по Foundry
• документация по обнаружению локального ящика

FoundryLocalManager

Менеджер по операциям с локальным SDK для Foundry.

Fields

• service_uri: Option<String>: URI службы Foundry.
• client: Option<HttpClient>: HTTP-клиент для запросов API.
• catalog_list: Option<Vec<FoundryModelInfo>>: кэшированный список моделей каталога.
• catalog_dict: Option<HashMap<String, FoundryModelInfo>>: кэшированный словарь моделей каталога.
• timeout: Option<u64>: Необязательный тайм-аут для HTTP-клиента.

Методы

• pub fn builder() -> FoundryLocalManagerBuilder
  Создайте нового построителя для FoundryLocalManager.

• pub fn service_uri(&self) -> Result<&str>
  Получите идентификатор ресурса (URI) службы.
  Возвращает: URI службы Foundry.

• fn client(&self) -> Result<&HttpClient>
  Получите экземпляр клиента HTTP.
  Возвращает: HTTP-клиент.

• pub fn endpoint(&self) -> Result<String>
  Получите конечную точку для службы.
  Возвращает: URL-адрес конечной точки.

• pub fn api_key(&self) -> String
  Получите ключ API для проверки подлинности.
  Возвращает: Ключ API.

• pub fn is_service_running(&mut self) -> bool
  Проверьте, запущена ли служба и задайте универсальный код ресурса (URI) службы, если он найден.
  Возвращает:true если выполняется, false в противном случае.

• pub fn start_service(&mut self) -> Result<()>
  Запустите локальную службу Foundry.

• pub async fn list_catalog_models(&mut self) -> Result<&Vec<FoundryModelInfo>>
  Получите список доступных моделей в каталоге.

• pub fn refresh_catalog(&mut self)
  Обновите кэш каталога.

• pub async fn get_model_info(&mut self, alias_or_model_id: &str, raise_on_not_found: bool) -> Result<FoundryModelInfo>
  Получение сведений о модели по псевдониму или идентификатору.
  Аргументы:

  • alias_or_model_id: псевдоним или идентификатор модели.
  • raise_on_not_found: если значение истинно, ошибка, если не найдено.

• pub async fn get_cache_location(&self) -> Result<String>
  Получение расположения кэша в виде строки.

• pub async fn list_cached_models(&mut self) -> Result<Vec<FoundryModelInfo>>
  Список кэшированных моделей.

• pub async fn download_model(&mut self, alias_or_model_id: &str, token: Option<&str>, force: bool) -> Result<FoundryModelInfo>
  Скачайте модель.
  Аргументы:

  • alias_or_model_id: псевдоним или идентификатор модели.
  • token: необязательный маркер проверки подлинности.
  • force: принудительно скачать заново, если файл уже кэширован.

• pub async fn load_model(&mut self, alias_or_model_id: &str, ttl: Option<i32>) -> Result<FoundryModelInfo>
  Загрузите модель для вывода.
  Аргументы:

  • alias_or_model_id: псевдоним или идентификатор модели.
  • ttl: необязательное время жизни в секундах.

• pub async fn unload_model(&mut self, alias_or_model_id: &str, force: bool) -> Result<()>
  Выгрузить модель.
  Аргументы:

  • alias_or_model_id: псевдоним или идентификатор модели.
  • force: принудительно выгружает, даже если используется.

• pub async fn list_loaded_models(&mut self) -> Result<Vec<FoundryModelInfo>>
  Список загруженных моделей.

FoundryLocalManagerBuilder

Конструктор для создания экземпляра FoundryLocalManager.

Fields

• alias_or_model_id: Option<String> — псевдоним или идентификатор модели для скачивания и загрузки.
• bootstrap: bool — следует ли запускать службу, если она не запущена.
• timeout_secs: Option<u64> — время ожидания клиента HTTP в секундах.

Методы

• pub fn new() -> Self
  Создайте новый экземпляр билдера.

• pub fn alias_or_model_id(mut self, alias_or_model_id: impl Into<String>) -> Self
  Задайте псевдоним или идентификатор модели для скачивания и загрузки.

• pub fn bootstrap(mut self, bootstrap: bool) -> Self
  Задайте, следует ли запускать службу, если она не запущена.

• pub fn timeout_secs(mut self, timeout_secs: u64) -> Self
  Задайте время ожидания клиента HTTP в секундах.

• pub async fn build(self) -> Result<FoundryLocalManager>
  Создайте экземпляр FoundryLocalManager.

FoundryModelInfo

Представляет сведения о модели.

Fields

• alias: String — псевдоним модели.
• id: String — идентификатор модели.
• version: String — версия модели.
• runtime: ExecutionProvider — поставщик выполнения (ЦП, CUDA и т. д.).
• uri: String — идентификатор ресурса (URI) модели.
• file_size_mb: i32 — размер файла модели в МБ.
• prompt_template: serde_json::Value — шаблон подсказки для модели.
• provider: String — имя поставщика.
• publisher: String — имя Publisher.
• license: String — тип лицензии.
• task: String — задача модели (например, создание текста).

Методы

• from_list_response(response: &FoundryListResponseModel) -> Self
  Создает объект FoundryModelInfo из ответа каталога.

• to_download_body(&self) -> serde_json::Value
  Преобразует сведения о модели в текст JSON для запросов на скачивание.

ExecutionProvider

Перечисление поддерживаемых поставщиков сред выполнения.

• CPU
• WebGPU
• CUDA
• QNN

Методы

• get_alias(&self) -> String
  Возвращает строковый псевдоним для поставщика выполнения.

ModelRuntime

Описывает среду выполнения для модели.

• device_type: DeviceType
• execution_provider: ExecutionProvider