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

Это важно

• Foundry Local доступен в предварительной версии. Общедоступные предварительные выпуски предоставляют ранний доступ к функциям, которые находятся в активном развертывании.
• Функции, подходы и процессы могут изменяться или иметь ограниченные возможности до общедоступной доступности.

Локальный пакет SDK Foundry упрощает управление моделями ИИ в локальных средах, предоставляя операции уровня управления отдельно от кода вывода плоскости данных. В этой справочной документации описаны реализации пакета SDK для Python, JavaScript, C#и Rust.

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

Предпосылки

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

Installation

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

pip install foundry-local-sdk

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

Используйте этот фрагмент кода, чтобы убедиться, что пакет 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.
• Позволяет использовать более короткое имя без необходимости запоминать идентификатор модели.

Подсказка

Рекомендуется передать в параметр alias_or_model_idпсевдоним, так как при развертывании приложения Foundry Local получает наилучшую модель для компьютера конечного пользователя в режиме выполнения.

Замечание

Если у вас есть NPU Intel в Windows, убедитесь, что вы установили драйвер Intel NPU для оптимального ускорения NPU.

Управление службой

Метод	Signature	Description
is_service_running()	() -> bool	Проверяет, запущена ли локальная служба Foundry.
start_service()	() -> None	Запускает локальную службу Foundry.
service_uri	@property -> str	Возвращает универсальный код ресурса (URI) службы.
endpoint	@property -> str	Возвращает конечную точку службы.
api_key	@property -> str	Возвращает ключ API (из env или по умолчанию).

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

Метод	Signature	Description
list_catalog_models()	() -> list[FoundryModelInfo]	Выводит список всех доступных моделей в каталоге.
refresh_catalog()	() -> None	Обновляет каталог моделей.
get_model_info()	(alias_or_model_id: str, raise_on_not_found=False) -> FoundryModelInfo \| None	Возвращает сведения о модели по псевдониму или идентификатору.

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

Метод	Signature	Description
get_cache_location()	() -> str	Возвращает путь к каталогу кэша моделей.
list_cached_models()	() -> list[FoundryModelInfo]	Выводит список моделей, скачанных в локальный кэш.

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

Метод	Signature	Description
download_model()	(alias_or_model_id: str, token: str = None, force: bool = False) -> FoundryModelInfo	Загружает модель в локальный кэш.
load_model()	(alias_or_model_id: str, ttl: int = 600) -> FoundryModelInfo	Загружает модель на сервер вывода.
unload_model()	(alias_or_model_id: str, force: bool = False) -> None	Выгружает модель с сервера вывода.
list_loaded_models()	() -> list[FoundryModelInfo]	Выводит список всех моделей, загруженных в настоящее время в сервисе.

FoundryModelInfo

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

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

Поле	Тип	Description
alias	str	Псевдоним модели.
id	str	Уникальный идентификатор модели.
version	str	Версия модели.
execution_provider	str	Акселератор (поставщик выполнения), используемый для запуска модели.
device_type	DeviceType	Тип устройства модели: ЦП, GPU, NPU.
uri	str	универсальный код ресурса (URI) модели.
file_size_mb	int	Размер модели на диске в МБ.
supports_tool_calling	bool	Поддерживает ли модель вызов инструментов.
prompt_template	dict \| None	Шаблон запроса для модели.
provider	str	Поставщик модели (где публикуется модель).
publisher	str	Издатель модели (которая опубликовала модель).
license	str	Имя лицензии модели.
task	str	Задача модели. Один из chat-completions или automatic-speech-recognition.
ep_override	str \| None	Переопределение для поставщика выполнения, если отличается от модели по умолчанию.

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

Одно из:

• 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 Local и убедитесь, что команда foundry доступна в вашей системе PATH.

Installation

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

npm install foundry-local-sdk

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

Используйте этот фрагмент кода, чтобы убедиться, что пакет 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.
• Позволяет использовать более короткое имя без необходимости запоминать идентификатор модели.

Подсказка

Рекомендуется передать в параметр aliasOrModelIdпсевдоним, так как при развертывании приложения Foundry Local получает наилучшую модель для компьютера конечного пользователя в режиме выполнения.

Замечание

Если у вас есть NPU Intel в Windows, убедитесь, что вы установили драйвер Intel NPU для оптимального ускорения NPU.

Управление службой

Метод	Signature	Description
init()	(aliasOrModelId?: string) => Promise<FoundryModelInfo \| void>	Инициализирует пакет SDK и при необходимости загружает модель.
isServiceRunning()	() => Promise<boolean>	Проверяет, запущена ли локальная служба Foundry.
startService()	() => Promise<void>	Запускает локальную службу Foundry.
serviceUrl	string	Базовый URL-адрес локальной службы Foundry.
endpoint	string	Конечная точка API (serviceUrl + /v1).
apiKey	string	Ключ API (нет).

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

Метод	Signature	Description
listCatalogModels()	() => Promise<FoundryModelInfo[]>	Выводит список всех доступных моделей в каталоге.
refreshCatalog()	() => Promise<void>	Обновляет каталог моделей.
getModelInfo()	(aliasOrModelId: string, throwOnNotFound = false) => Promise<FoundryModelInfo \| null>	Возвращает сведения о модели по псевдониму или идентификатору.

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

Метод	Signature	Description
getCacheLocation()	() => Promise<string>	Возвращает путь к каталогу кэша моделей.
listCachedModels()	() => Promise<FoundryModelInfo[]>	Выводит список моделей, скачанных в локальный кэш.

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

Метод	Signature	Description
downloadModel()	(aliasOrModelId: string, token?: string, force = false, onProgress?) => Promise<FoundryModelInfo>	Загружает модель в локальный кэш.
loadModel()	(aliasOrModelId: string, ttl = 600) => Promise<FoundryModelInfo>	Загружает модель на сервер вывода.
unloadModel()	(aliasOrModelId: string, force = false) => Promise<void>	Выгружает модель с сервера вывода.
listLoadedModels()	() => Promise<FoundryModelInfo[]>	Выводит список всех моделей, загруженных в настоящее время в сервисе.

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

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

Замечание

Версия браузера не поддерживает методы init, isServiceRunning и startService. Перед использованием пакета SDK в среде браузера необходимо убедиться, что локальная служба Foundry запущена. Вы можете запустить службу с помощью локального интерфейса командной строки Foundry: foundry service start. 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 });

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#

Руководство по настройке проекта

Существует два пакета NuGet для локального пакета SDK Foundry — WinML и кроссплатформенного пакета, которые имеют одну область API, но оптимизированы для разных платформ:

• Windows: использует Microsoft.AI.Foundry.Local.WinML пакет, относящийся к приложениям Windows, использующим платформу Windows Machine Learning (WinML).
• КроссплатформенныйMicrosoft.AI.Foundry.Local: использует пакет, который можно использовать для кроссплатформенных приложений (Windows, Linux, macOS).

В зависимости от целевой платформы выполните следующие инструкции, чтобы создать новое приложение C# и добавить необходимые зависимости:

Используйте Foundry Local в проекте C#, следуя инструкциям, специфичным для Windows, или кроссплатформенным (macOS/Linux/Windows).

Виндоус

1. Создайте проект C# и перейдите в него:

   dotnet new console -n app-name
   cd app-name
   

2. Откройте файл app-name.csproj и измените его:

   <Project Sdk="Microsoft.NET.Sdk">
   
     <PropertyGroup>
       <OutputType>Exe</OutputType>
       <TargetFramework>net9.0-windows10.0.26100</TargetFramework>
       <RootNamespace>app-name</RootNamespace>
       <ImplicitUsings>enable</ImplicitUsings>
       <Nullable>enable</Nullable>
       <WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
       <WindowsPackageType>None</WindowsPackageType>
       <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
     </PropertyGroup>
   
     <ItemGroup>
       <PackageReference Include="Microsoft.AI.Foundry.Local.WinML" Version="0.8.2.1" />
       <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.10" />
       <PackageReference Include="OpenAI" Version="2.5.0" />
     </ItemGroup>
   
   </Project>
   

3. nuget.config Создайте файл в корневом каталоге проекта со следующим содержимым, чтобы пакеты были правильно восстановлены:

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <packageSources>
       <clear />
       <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
       <add key="ORT" value="https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT/nuget/v3/index.json" />
     </packageSources>
     <packageSourceMapping>
       <packageSource key="nuget.org">
         <package pattern="*" />
       </packageSource>
       <packageSource key="ORT">
         <package pattern="*Foundry*" />
       </packageSource>
     </packageSourceMapping>
   </configuration>
   

Кроссплатформенная платформа

1. Создайте проект C# и перейдите в него:

   dotnet new console -n app-name
   cd app-name
   

2. Откройте файл app-name.csproj и измените его:

   <Project Sdk="Microsoft.NET.Sdk">
   
       <PropertyGroup>
         <OutputType>Exe</OutputType>
         <TargetFramework>net9.0</TargetFramework>
         <ImplicitUsings>enable</ImplicitUsings>
         <Nullable>enable</Nullable>
       </PropertyGroup>
   
       <ItemGroup>
         <PackageReference Include="Microsoft.AI.Foundry.Local" Version="0.8.2.1" />
         <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.10" />
         <PackageReference Include="OpenAI" Version="2.5.0" />
       </ItemGroup>
   
   </Project>
   

3. nuget.config Создайте файл в корневом каталоге проекта со следующим содержимым, чтобы пакеты были правильно восстановлены:

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <packageSources>
       <clear />
       <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
       <add key="ORT" value="https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT/nuget/v3/index.json" />
     </packageSources>
     <packageSourceMapping>
       <packageSource key="nuget.org">
         <package pattern="*" />
       </packageSource>
       <packageSource key="ORT">
         <package pattern="*Foundry*" />
       </packageSource>
     </packageSourceMapping>
   </configuration>
   

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

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

using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging;
using System.Linq;

var config = new Configuration
{
  AppName = "app-name",
  LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information,
};

using var loggerFactory = LoggerFactory.Create(builder =>
{
  builder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Information);
});
var logger = loggerFactory.CreateLogger<Program>();

await FoundryLocalManager.CreateAsync(config, logger);
var manager = FoundryLocalManager.Instance;

var catalog = await manager.GetCatalogAsync();
var models = await catalog.ListModelsAsync();

Console.WriteLine($"Models available: {models.Count()}");

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

Ссылки:

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

Перепроектирование

Чтобы улучшить возможность отправки приложений с использованием встроенного искусственного интеллекта, в версии 0.8.0 и более поздних существуют существенные изменения в архитектуре SDK на C#. В этом разделе описаны основные изменения, которые помогут перенести приложения в последнюю версию пакета SDK.

Замечание

В версии 0.8.0 пакета SDK и последующих версиях в API есть критические изменения по сравнению с предыдущими версиями.

На следующей схеме показано, как предыдущая архитектура для более ранних 0.8.0 версий зависит от использования веб-сервера REST для управления моделями и выводами, такими как завершение чата:

Пакет SDK будет использовать удаленный процедурный вызов (RPC) для поиска исполняемого файла Foundry Local CLI на компьютере, запуска веб-сервера и обмена данными с ним по протоколу HTTP. Эта архитектура имеет несколько ограничений, в том числе:

• Сложность управления жизненным циклом веб-сервера.
• Сложное развертывание. Конечные пользователи должны установить локальный интерфейс командной строки Foundry на своих компьютерах и приложении.
• Управление версиями интерфейса командной строки и пакета SDK может привести к проблемам совместимости.

Для решения этих проблем переработанная архитектура в версии и более поздних версиях 0.8.0 использует более упрощенный подход. Новая архитектура выглядит следующим образом:

В этой новой архитектуре:

• Приложение самодостаточено. Для развертывания приложений не требуется устанавливать Foundry Local CLI отдельно на машину конечного пользователя, что облегчает процесс развертывания.
• Веб-сервер REST необязателен. Вы по-прежнему можете использовать веб-сервер, если вы хотите интегрировать с другими средствами, которые взаимодействуют по протоколу HTTP. Дополнительные сведения об использовании этой функции см. в разделе «Использование функций завершения чата через сервер REST с Foundry Local».
• Пакет SDK имеет встроенную поддержку завершения чата и транскрибирования звука, что позволяет создавать приложения ИИ для общения с меньшим количеством зависимостей. Дополнительные сведения об использовании этой функции см. в API локальных завершений чата в Foundry.
• На устройствах Windows можно использовать сборку Windows ML, которая обрабатывает аппаратное ускорение для моделей на устройстве, извлекая нужные среды выполнения и драйверы.

Изменения API

Версия 0.8.0 и более поздние предлагают более объектно-ориентированный и композируемый API. Основная точка входа по-прежнему является FoundryLocalManager классом, но вместо набора методов, которые работают через статические вызовы к API HTTP, не имеющему состояния, пакет SDK теперь предоставляет методы экземпляра FoundryLocalManager, поддерживающего состояние службы и моделей.

Примитивный	< Версия 0.8.0	Версия >= 0.8.0
Configuration	N/A	config = Configuration(...)
Получение менеджера	mgr = FoundryLocalManager();	await FoundryLocalManager.CreateAsync(config, logger); var mgr = FoundryLocalManager.Instance;
Получить каталог	N/A	catalog = await mgr.GetCatalogAsync();
Список моделей	mgr.ListCatalogModelsAsync();	catalog.ListModelsAsync();
Получите модель	mgr.GetModelInfoAsync("aliasOrModelId");	catalog.GetModelAsync(alias: "alias");
Получить вариант	N/A	model.SelectedVariant;
Задать вариант	N/A	model.SelectVariant();
Скачивание модели	mgr.DownloadModelAsync("aliasOrModelId");	model.DownloadAsync()
Загрузка модели	mgr.LoadModelAsync("aliasOrModelId");	model.LoadAsync()
Выгрузка модели	mgr.UnloadModelAsync("aliasOrModelId");	model.UnloadAsync()
Список загруженных моделей	mgr.ListLoadedModelsAsync();	catalog.GetLoadedModelsAsync();
Получение пути модели	N/A	model.GetPathAsync()
Запуск службы	mgr.StartServiceAsync();	mgr.StartWebServerAsync();
Остановка службы	mgr.StopServiceAsync();	mgr.StopWebServerAsync();
Расположение кэша	mgr.GetCacheLocationAsync();	config.ModelCacheDir
Список кэшированных моделей	mgr.ListCachedModelsAsync();	catalog.GetCachedModelsAsync();

API позволяет более гибко настраивать Foundry Local в отношении веб-сервера, ведения журнала, расположения кэша и выбора варианта модели. Например, Configuration класс позволяет настроить имя приложения, уровень ведения журнала, URL-адреса веб-сервера и каталоги для данных приложения, кэша моделей и журналов:

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

Ссылки:

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

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

Уменьшение размера пакета приложения

Локальный SDK Foundry подключает пакет NuGet в качестве зависимости Microsoft.ML.OnnxRuntime.Foundry. Пакет Microsoft.ML.OnnxRuntime.Foundry предоставляет пакет среды выполнения вывода, который является набором библиотек, необходимых для эффективного выполнения вывода на определенных аппаратных устройствах поставщика. Пакет среды выполнения вывода включает следующие компоненты:

• Библиотека среды выполнения ONNX: ядро подсистемы вывода (onnxruntime.dll).
• Библиотека поставщика выполнения ONNX (EP). Серверная часть ONNX Runtime, ориентированная на конкретное оборудование, которая оптимизирует и выполняет части модели машинного обучения с использованием аппаратного ускорителя. Например:
  • CUDA EP: onnxruntime_providers_cuda.dll
  • QNN EP: onnxruntime_providers_qnn.dll
• Библиотеки независимого поставщика аппаратного обеспечения (IHV). Например:
  • WebGPU: зависимости от DirectX (dxcompiler.dll, dxil.dll)
  • QNN: зависимости Qualcomm QNN (QnnSystem.dll, и т. д.)

В следующей таблице приведены сведения о том, какие библиотеки EP и IHV упаковываются в приложение, и что WinML скачивает или устанавливает во время выполнения:

Во всех платформах и архитектурах требуется ЦП EP. Библиотеки EP и IHV WebGPU имеют небольшой размер (например, WebGPU добавляет в пакет приложения только 7 МБ) и требуются в Windows и macOS. Однако EPS CUDA и QNN имеют большой размер (например, CUDA добавляет ~1 ГБ в пакет приложения), поэтому рекомендуется исключить эти EPS из пакета приложения. WinML скачивает и устанавливает CUDA и QNN во время выполнения, если конечный пользователь имеет совместимое оборудование.

Замечание

Мы работаем над удалением EPs CUDA и QNN из Microsoft.ML.OnnxRuntime.Foundry пакета в будущих выпусках, чтобы вам не пришлось включать ExcludeExtraLibs.props файл для их удаления из пакета приложения.

Чтобы уменьшить размер пакета приложения, можно создать ExcludeExtraLibs.props файл в каталоге проекта со следующим содержимым, который исключает библиотеки CUDA и QNN EP и IHV при публикации приложения:

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

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

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

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

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

В файле проекта (.csproj) добавьте следующую строку для импорта ExcludeExtraLibs.props файла:

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

Windows: зависимости CUDA

EP CUDA подключается к вашему приложению Linux через Microsoft.ML.OnnxRuntime.Foundry, но мы не включаем библиотеки IHV. Если вы хотите предоставить пользователям–конечным устройств с поддержкой CUDA возможность получения более высокой производительности, вам необходимо добавить в ваше приложение следующие библиотеки CUDA IHV:

• CUBLAS версии 12.8.4 (скачать с сайта NVIDIA Developer)
  • cublas64_12.dll
  • cublasLt64_12.dll
• CUDA RT версии 12.8.90 (скачивание от разработчика NVIDIA)
  • cudart64_12.dll
• CUDNN версии 9.8.0 (скачать с NVIDIA Developer)
  • cudnn_graph64_9.dll
  • cudnn_ops64_9.dll
  • cudnn64_9.dll
• CUDA FFT версии 11.3.3.83 (скачать с NVIDIA Developer)
  • cufft64_11.dll

Предупреждение

Добавление библиотек CUDA EP и IHV в приложение увеличивает размер пакета приложения на 1 ГБ.

Образцы

• Для примеров приложений, демонстрирующих, как использовать SDK Foundry Local C#, см. репозиторий GitHub Foundry Local C# SDK Samples.

Справочник по API

• Для получения более подробной информации о Foundry Local C# SDK см. справочник по API Foundry Local C# SDK.

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

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

Предпосылки

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

Installation

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

[dependencies]
foundry-local = "0.1.0"

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

cargo add foundry-local

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

Используйте этот фрагмент кода, чтобы убедиться, что пакет 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 — имя издателя.
• 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