다음을 통해 공유

Foundry 로컬 SDK 참조

Foundry 로컬 SDK를 사용하면 간단하고 직관적인 API를 통해 로컬 AI 모델을 사용할 수 있는 AI 기능을 애플리케이션에 제공할 수 있습니다. SDK는 AI 모델 관리의 복잡성을 추상화하고 로컬 AI 기능을 애플리케이션에 통합하기 위한 원활한 환경을 제공합니다. 이 참조는 C#, JavaScript, Python 및 Rust에 대한 SDK 구현을 설명합니다.

SDK는 최종 사용자 컴퓨터에 Foundry 로컬 CLI를 설치할 필요가 없으므로 사용자를 위한 추가 설정 단계 없이 애플리케이션을 배송할 수 있습니다. 애플리케이션은 자체 포함됩니다. Foundry 로컬 SDK의 추가 이점은 다음과 같습니다.

  • 하드웨어 검색 및 최적화: GPU, NPU 및 CPU에 대한 자동 기능 평가입니다.
  • Windows(확장 공급자 관리): 디바이스 기능에 따라 적절한 ONNX 런타임 실행 공급자(CUDA, Vitis, QNN, OpenVINO, TensorRT)의 자동 다운로드 및 등록
  • WebGpu(macOS)을 통한 Metal 지원: Apple Silicon에서 최적화된 성능으로 모델을 실행할 수 있도록 기본적으로 지원합니다.
  • 모델 획득: Foundry 모델 카탈로그에서 버전 관리와 업데이트를 통해 자동으로 하드웨어 최적화 모델을 선택하여 원활하게 다운로드하며, 대체 지원을 제공합니다.
  • 효율적인 런타임: 앱 크기에 약 20MB를 추가하고 휴대폰에서 데스크톱에 이르는 디바이스에서 실행됩니다.
  • OpenAI API 호환성: OpenAI 모델 및 도구와 쉽게 통합합니다.
  • 선택적 REST 서버: 다른 애플리케이션에서 액세스할 수 있는 로컬 서비스로 Foundry Local을 실행합니다.

C# SDK 참조

패키지 설치

Windows 개발하거나 배송하는 경우 Windows 탭을 선택합니다. Windows 패키지는 Windows ML 런타임과 통합되어 광범위한 하드웨어 가속으로 동일한 API 노출 영역을 제공합니다.

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

GitHub 리포지토리의 C# 샘플은 미리 구성된 프로젝트입니다. 처음부터 빌드하는 경우 Foundry Local을 사용하여 C# 프로젝트를 설정하는 방법에 대한 자세한 내용은 Foundry 로컬 SDK 참조 를 참조하세요.

프로젝트 설정

샘플 리포지토리에는 플랫폼 검색을 .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.26100</TargetFramework>
    <WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
    <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>

  <!-- Windows: WinML for hardware acceleration -->
  <ItemGroup Condition="$([MSBuild]::IsOSPlatform('Windows'))">
    <PackageReference Include="Microsoft.AI.Foundry.Local.WinML" />
  </ItemGroup>

  <!-- Non-Windows: standard SDK -->
  <ItemGroup Condition="!$([MSBuild]::IsOSPlatform('Windows'))">
    <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 Windows에서 net9.0-windows10.0.26100은 WinML 하드웨어 가속을 목표로 합니다. 다른 플랫폼에서는 net9.0 대상을 사용합니다.
WindowsAppSDKSelfContained 묶는 대신 시스템 설치 Windows 앱 SDK 사용하려면 false로 설정합니다.
WindowsPackageType 패키지되지 않은 데스크톱 앱으로 빌드하도록 None 설정합니다(MSIX 패키징 없음).
EnableCoreMrtTooling MRT Core 리소스 도구가 콘솔 애플리케이션에는 필요하지 않으므로 false로 설정하여 비활성화합니다.
RuntimeIdentifier 기본값은 현재 SDK의 런타임 식별자로, 올바른 플랫폼 이진 파일이 선택되도록 합니다.
Microsoft.AI.Foundry.Local.WinML 하드웨어 가속 및 자동 실행 공급자 관리에 WinML을 사용하는 Windows 전용 패키지입니다.
Microsoft.AI.Foundry.Local WinML이 없는 macOS, Linux 및 Windows 대한 플랫폼 간 패키지입니다.
Microsoft.ML.OnnxRuntime.Gpu / OnnxRuntimeGenAI.Cuda Linux GPU는 CUDA 지원 하드웨어용 패키지를 지원합니다.

빠른 시작

이 코드 조각을 사용하여 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에는 위스퍼 모델을 사용하여 디바이스에서 오디오 파일을 전사하기 위한 네이티브 오디오 클라이언트가 포함되어 있습니다. REST 웹 서버 없이 인프로세스에서 유추가 수행됩니다.

오디오 클라이언트 가져오기

위스퍼 모델을 로드한 후 오디오 클라이언트를 가져옵니다.

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 참조

패키지 설치

Windows 개발하거나 배송하는 경우 Windows 탭을 선택합니다. Windows 패키지는 Windows ML 런타임과 통합되어 광범위한 하드웨어 가속으로 동일한 API 노출 영역을 제공합니다.

npm install foundry-local-sdk-winml 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 참조

패키지 설치

Windows 개발하거나 배송하는 경우 Windows 탭을 선택합니다. Windows 패키지는 Windows ML 런타임과 통합되어 광범위한 하드웨어 가속으로 동일한 API 노출 영역을 제공합니다.

pip install foundry-local-sdk-winml 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

클래스 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 웹 서비스 구성입니다.

핵심 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

위스퍼 모델을 로드한 후 오디오 클라이언트를 가져옵니다.

audio_client = model.get_audio_client()
메서드 설명
audio_client.transcribe(file_path) 오디오 파일을 전사합니다. 속성이 있는 개체를 text 반환합니다.

참조:

Rust SDK 참조

패키지 설치

Windows 개발하거나 배송하는 경우 Windows 탭을 선택합니다. Windows 패키지는 Windows ML 런타임과 통합되어 광범위한 하드웨어 가속으로 동일한 API 노출 영역을 제공합니다.

cargo add foundry-local-sdk --features winml
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(())
}

다음은 하드웨어에 사용할 수 있는 모델 수를 인쇄하는 예제입니다.

견본

Configuration

이 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, ChatCompletionRequestUserMessage. ChatCompletionRequestMessage

원어 오디오 전사 API

Whisper 모델을 로드한 후 오디오 클라이언트를 만듭니다.

let audio_client = model.create_audio_client();
메서드 설명
audio_client.transcribe(file_path).await 오디오 파일로부터 텍스트를 만듭니다. text 필드를 갖는 객체를 반환합니다.

참조:

  • Last updated on