你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

Foundry Local SDK 参考

Foundry Local SDK 使你能够通过简单直观的 API,在应用程序中提供使用本地 AI 模型的 AI 功能。 SDK 将管理 AI 模型的复杂性抽象化,并提供无缝体验,用于将本地 AI 功能集成到应用程序中。 此参考文档介绍了适用于 C#、C++、JavaScript、Python 和 Rust 的 SDK 实现。

SDK 不需要在最终用户计算机上安装 Foundry Local CLI,因此无需为用户提供额外的设置步骤即可交付应用程序 - 应用程序是自包含的。 Foundry Local SDK 的额外优势包括:

  • 硬件检测和优化:GPU、NPU 和 CPU 的自动功能评估。
  • 执行提供者管理(Windows):基于设备功能自动下载和注册适当的 ONNX 运行时执行提供者(CUDA、Vitis、QNN、OpenVINO、TensorRT)。
  • 通过 WebGpu 支持 Metal (macOS):原生支持在 Apple Silicon 上运行模型,性能经过优化。
  • 模型获取:从 Foundry 模型目录无缝下载,支持版本管理、更新以及自动进行硬件优化的模型选择,并提供回退支持。
  • 高效运行时:将大约 20 MB 添加到应用大小,在手机到台式机的设备上运行。
  • OpenAI API 兼容性:与 OpenAI 模型和工具轻松集成。
  • 可选 REST 服务器:将 Foundry Local 作为其他应用程序可访问的本地服务运行。

C# SDK 参考

安装软件包

dotnet add package Microsoft.AI.Foundry.Local
dotnet add package OpenAI

GitHub存储库中的 C# 示例是预配置项目。 如果要从头开始生成,则应阅读 Foundry Local SDK 参考 ,详细了解如何使用 Foundry Local 设置 C# 项目。

项目配置

示例存储库包含一个自动处理平台检测的 .csproj 文件。 如果要从头开始生成项目,请使用此配置作为参考:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <!-- Windows: target Windows SDK for WinML hardware acceleration -->
  <PropertyGroup Condition="$([MSBuild]::IsOSPlatform('Windows'))">
    <TargetFramework>net9.0-windows10.0.19041.0</TargetFramework>
    <Platforms>ARM64;x64</Platforms>
    <WindowsPackageType>None</WindowsPackageType>
    <EnableCoreMrtTooling>false</EnableCoreMrtTooling>
  </PropertyGroup>

  <!-- Non-Windows: standard .NET -->
  <PropertyGroup Condition="!$([MSBuild]::IsOSPlatform('Windows'))">
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(RuntimeIdentifier)'==''">
    <RuntimeIdentifier>$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AI.Foundry.Local" />
  </ItemGroup>

  <!-- Linux GPU support -->
  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <PackageReference Include="Microsoft.ML.OnnxRuntime.Gpu" />
    <PackageReference Include="Microsoft.ML.OnnxRuntimeGenAI.Cuda" />
  </ItemGroup>

  <!-- Shared utilities -->
  <ItemGroup>
    <Compile Include="../Shared/*.cs" />
  </ItemGroup>

</Project>

下表说明了关键项目设置:

设置 说明
TargetFramework 以示例所需的.NET版本为目标。
RuntimeIdentifier 默认为当前 SDK 的运行时标识符,以确保能够选择正确的平台二进制文件。
Microsoft.AI.Foundry.Local 适用于 Windows、macOS 和 Linux 的 Foundry 本地 SDK 包。

快速入门

使用此代码片段验证 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()}");

此示例打印你的硬件支持的模型数量。

示例

API 参考

本机音频转录 API

C# SDK 包括一个本机音频客户端,用于使用 Whisper 模型在设备上转录音频文件。 这会在进程内运行推理,而无需 REST Web 服务器。

获取音频客户端

加载 Whisper 模型后,获取音频客户端:

var audioClient = await model.GetAudioClientAsync();

音频听录方法

方法 Signature 说明
TranscribeAudioStreamingAsync() (string audioFilePath, CancellationToken ct) => IAsyncEnumerable<TranscriptionChunk> 按区块流式传输听录结果。 每个区块都有一个 Text 属性。

AudioClient 设置

财产 类型 说明
Language string ISO 639-1 语言代码(例如, "en")。 提高准确性。
Temperature float 采样温度(0.0–1.0)。 较低的值更具确定性。

示例

var audioClient = await model.GetAudioClientAsync();
audioClient.Settings.Language = "en";
audioClient.Settings.Temperature = 0.0f;

await foreach (var chunk in audioClient.TranscribeAudioStreamingAsync(
    "recording.mp3", CancellationToken.None))
{
    Console.Write(chunk.Text);
}

参考:

JavaScript SDK 参考文档

安装软件包

npm install foundry-local-sdk openai

快速入门

使用此代码片段验证 SDK 是否可以初始化和访问本地模型目录。

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

console.log('Initializing Foundry Local SDK...');

const manager = FoundryLocalManager.create({
    appName: 'foundry_local_samples',
    logLevel: 'info'
});
console.log('✓ SDK initialized successfully');

// Explore available models
console.log('\nFetching available models...');
const catalog = manager.catalog;
const models = await catalog.getModels();

console.log(`Found ${models.length} models:`);
for (const model of models) {
    console.log(`  - ${model.alias}`);
}

此示例输出硬件的可用模型列表。

示例

API 参考

参考

Python SDK 参考

安装软件包

pip install foundry-local-sdk openai

快速入门

使用此代码片段验证 SDK 是否可以初始化和访问本地模型目录。

import asyncio
from foundry_local_sdk import Configuration, FoundryLocalManager


async def main():
    config = Configuration(app_name="app-name")
    FoundryLocalManager.initialize(config)
    manager = FoundryLocalManager.instance

    models = manager.catalog.list_models()
    print(f"Models available: {len(models)}")


if __name__ == "__main__":
    asyncio.run(main())

此示例打印你的硬件支持的模型数量。

示例

配置

类 Configuration 允许自定义 SDK 行为:

from foundry_local_sdk import Configuration

config = Configuration(
    app_name="app-name",
    log_level="info",
    model_cache_dir="./foundry_local_data/model_cache",
    web={"urls": "http://127.0.0.1:55588"},
)
参数 类型 说明
app_name str 应用程序的名称。
log_level str 日志记录级别(例如,"info", "debug")。
model_cache_dir str 缓存模型的目录。
web dict 使用urls密钥的Web服务配置。

核心 API

方法 说明
FoundryLocalManager.initialize(config) 使用Configuration初始化单例管理器。
FoundryLocalManager.instance 访问初始化的管理器实例。
manager.catalog.list_models() 列出目录中的所有可用模型。
manager.catalog.get_model(alias) 通过别名获取模型。
manager.catalog.get_cached_models() 列出本地缓存中的模型。
manager.catalog.get_loaded_models() 列出当前加载的模型。
model.download(progress_callback) 下载模型(如果缓存的话跳过)。
model.load() 加载模型进行推理。
model.unload() 卸载模型。
model.is_cached 检查模型是否在本地缓存。
model.is_loaded 检查模型是否已加载。

原生聊天补全 API

加载模型后,获取聊天客户端:

client = model.get_chat_client()
方法 说明
client.complete_chat(messages) 生成完整的聊天响应。
client.complete_streaming_chat(messages) 流式传输聊天响应分块。

本机音频转录 API

加载 Whisper 模型后,获取音频客户端:

audio_client = model.get_audio_client()
方法 说明
audio_client.transcribe(file_path) 转录音频文件。 返回具有 text 属性的对象。

参考:

Rust SDK 文档参考

安装软件包

cargo add foundry-local-sdk
cargo add tokio --features full
cargo add tokio-stream anyhow

快速入门

使用此代码片段验证 SDK 是否可以初始化和访问本地模型目录。

use foundry_local_sdk::{FoundryLocalConfig, FoundryLocalManager};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let manager = FoundryLocalManager::create(FoundryLocalConfig::new("app-name"))?;

    let models = manager.catalog().get_models().await?;
    println!("Models available: {}", models.len());

    Ok(())
}

此示例打印你的硬件支持的模型数量。

示例

配置

该 FoundryLocalConfig 结构允许自定义 SDK 行为:

use foundry_local_sdk::FoundryLocalConfig;

let config = FoundryLocalConfig::new("app-name")
    .with_log_level("info")
    .with_model_cache_dir("./foundry_local_data/model_cache")
    .with_web_urls("http://127.0.0.1:55588");

核心 API

方法 说明
FoundryLocalManager::create(config) 使用 FoundryLocalConfig. 创建一个新管理器。
manager.catalog().get_models().await 列出所有可用模型。
manager.catalog().get_model(alias).await 通过别名获取模型。
manager.catalog().get_cached_models().await 列出本地缓存中的模型。
manager.catalog().get_loaded_models().await 列出当前加载的模型。
model.download(callback).await 下载模型(如果缓存的话跳过)。
model.load().await 加载模型进行推理。
model.unload().await 卸载模型。

原生聊天补全 API

加载模型后,使用可选设置创建聊天客户端:

let client = model.create_chat_client()
    .temperature(0.7)
    .max_tokens(256);
方法 说明
client.complete_chat(&messages, tools).await 生成完整的聊天响应。
client.complete_streaming_chat(&messages, tools).await 流式传输聊天响应分块。

消息类型:ChatCompletionRequestSystemMessage、、ChatCompletionRequestUserMessageChatCompletionRequestMessage.

本机音频转录 API

加载 Whisper 模型后,创建音频客户端:

let audio_client = model.create_audio_client();
方法 说明
audio_client.transcribe(file_path).await 转录音频文件。 返回具有 text 字段的对象。

参考:

C++ SDK 参考

Prerequisites

C++ SDK 提供了对原生 Foundry Local 运行时的纯头文件封装。 部署的应用程序不需要 Foundry Local CLI 或 .NET 运行时。

克隆原生聊天示例以从配置好的 CMake 项目开始:

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/cpp/foundry-local/native-chat-completions

C++ 示例需要:

  • CMake 3.20 或更高版本。
  • C++20 编译器。
  • 你的PATH上的NuGet CLI。

配置并生成示例:

cmake -S . -B build
cmake --build build --config Release

在配置期间,示例将版本 2.2.1 的 Microsoft.AI.Foundry.Local.Runtime NuGet 包还原到 build/_packages。 该包包含用于 Windows、Linux 和 macOS 的 C++ 标头和本机库。 不需要单独的 WinML 包。

CMake 配置为你的操作系统和体系结构选择运行时资源,并将所需的本机库复制到可执行文件旁边。 在 macOS 和 Linux 上,从 build中运行可执行文件。 在 Windows 上,运行位于 .exe 的 build 文件。

选择与应用程序的操作系统和体系结构匹配的本机资产:

操作系统 Architecture 运行时标识符(RID)
Windows操作系统 x64 或 ARM64 win-x64 或 win-arm64
Linux x64 或 ARM64 linux-x64 或 linux-arm64
macOS 苹果硅 (ARM64) osx-arm64

添加 将 build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/build/native/include 添加到编译器的包含路径中。 链接包中的本机库 build/_packages/Microsoft.AI.Foundry.Local.Runtime.2.2.1/runtimes/<rid>/native 目录:

  • foundry_local.lib在Windows上。
  • libfoundry_local.so(在 Linux 上)。
  • libfoundry_local.dylib 在 macOS 上。

在可执行文件旁边或平台的库搜索路径中部署匹配的本机运行时和依赖项库。 将还原的各包版本放在一起。 不要将标头和本机库与不同的版本混合使用。

快速入门

用以下代码替换示例中的 main.cpp 以初始化 SDK 并统计目录中的模型数量:

#include <foundry_local/foundry_local_cpp.h>

#include <iostream>

using namespace foundry_local;

int main() {
    try {
        Manager manager{Configuration("app-name")};
        auto models = manager.GetCatalog().GetModels();
        std::cout << "Models available: " << models.size() << "\n";
    } catch (const Error& error) {
        std::cerr << "Foundry Local error [" << error.Code()
                  << "]: " << error.what() << "\n";
        return 1;
    }
    return 0;
}

该示例打印Models available:,后跟目录中的模型数量。 它无法下载或加载模型。 使用从中获取的目录、模型或元数据对象时,使管理器保持活动状态。

参考:用于 Configuration、Manager 和 Catalog 的 C++ 包装器声明。

核心 API

包装器使用资源获取即初始化(RAII),以便在对象离开作用域时释放本机句柄。

API 说明
Manager{Configuration("app-name")} 使用应用程序名称初始化管理器。
manager.GetCatalog() 获取模型目录。
catalog.GetModels() 列出目录中的模型。
catalog.GetModel(alias) 按别名查找模型。 使用前检查返回的指针。
model->Download() 将模型下载到本地缓存。
model->Load() 加载用于推理的模型。
model->Unload() 从内存中卸载模型。
ChatSession::ProcessRequest(request) 运行聊天请求并返回响应。

API 参考和示例

有关完整的 API 和推理工作流,请参阅公共头文件和持续维护的示例: