Foundry 로컬 SDK 마이그레이션 가이드

이 가이드에서는 레거시 버전의 Foundry 로컬 SDK에서 현재 버전으로 코드를 마이그레이션하기 위한 지침을 제공합니다. 새 SDK는 Foundry 로컬 CLI에 대한 종속성을 제거하므로 사용자가 CLI를 설치하거나 로컬 Foundry 환경을 설정하지 않고도 애플리케이션을 배송할 수 있습니다. 또한 새로운 SDK에는 더 나은 유용성과 성능을 위해 API가 개선되었습니다.

C# SDK 마이그레이션 가이드

디바이스 내 AI를 사용하여 애플리케이션을 배송하는 기능을 향상시키기 위해 버전 0.8.0 이상에서 C# SDK의 아키텍처가 크게 변경되었습니다. 이 섹션에서는 애플리케이션을 최신 버전의 SDK로 마이그레이션하는 데 도움이 되는 주요 변경 내용을 간략하게 설명합니다.

메모

SDK 버전 0.8.0 이상에서는 이전 버전 (<=0.3.0)의 API와 호환되지 않는 중대한 변경 사항이 있습니다.

다음 다이어그램은 0.8.0 이전 버전에서의 이전 아키텍처가 REST 웹 서버를 사용하여 모델과 채팅 완료 처리 같은 추론을 관리하는 데 크게 의존하는 방법을 나타냅니다.

Foundry Local에 대한 이전 아키텍처의 다이어그램

SDK는 RPC(원격 절차 호출)를 사용하여 컴퓨터에서 Foundry 로컬 CLI 실행 파일을 찾고, 웹 서버를 시작한 다음, HTTP를 통해 통신합니다. 이 아키텍처에는 다음을 비롯한 몇 가지 제한 사항이 있습니다.

  • 웹 서버 수명 주기 관리의 복잡성.
  • 까다로운 배포: 최종 사용자는 컴퓨터 및 애플리케이션에 Foundry 로컬 CLI를 설치해야 했습니다.
  • CLI 및 SDK의 버전 관리로 인해 호환성 문제가 발생할 수 있습니다.

이러한 문제를 해결하기 위해 버전 및 이후 버전 0.8.0 에서 새롭게 디자인된 아키텍처는 보다 간소화된 접근 방식을 사용합니다. 새 아키텍처는 다음과 같습니다.

Foundry Local의 새 아키텍처 다이어그램

이 새 아키텍처에서는 다음을 수행합니다.

  • 애플리케이션이 자체적으로 포함되어 있습니다. 최종 사용자의 컴퓨터에 Foundry 로컬 CLI를 별도로 설치할 필요가 없으므로 애플리케이션을 더 쉽게 배포할 수 있습니다.
  • REST 웹 서버는 선택 사항입니다. HTTP를 통해 통신하는 다른 도구와 통합하려는 경우에도 웹 서버를 사용할 수 있습니다. 이 기능을 사용하는 방법에 대한 자세한 내용은 Foundry Local과 함께 REST 서버를 통해 채팅 완료를 참조 하세요.
  • SDK는 채팅 완료 및 오디오 전사를 기본적으로 지원하므로 종속성이 적은 대화형 AI 애플리케이션을 빌드할 수 있습니다. 이 기능을 사용하는 방법에 대한 자세한 내용은 Foundry 로컬 네이티브 채팅 완료 API를 참조 하세요.
  • Windows 디바이스에서는 적절한 런타임과 드라이버를 불러와서 디바이스의 모델에 대해 하드웨어 가속을 처리하는 Windows ML 빌드를 사용할 수 있습니다.

API 변경 사항

버전 0.8.0 이상에서는 보다 개체 지향적이고 구성 가능한 API를 제공합니다. 기본 진입점은 계속해서 FoundryLocalManager 클래스가 되지만, 상태 비저장 HTTP API에 대한 정적 호출을 통해 작동하는 단일 메서드 집합 대신, 이제 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"
};

API 참조

JavaScript SDK 마이그레이션 가이드

디바이스 내 AI를 사용하여 애플리케이션을 배송하는 기능을 향상시키기 위해 JavaScript SDK의 아키텍처가 크게 변경되었습니다. 이 섹션에서는 애플리케이션을 최신 버전의 SDK로 마이그레이션하는 데 도움이 되는 주요 변경 내용을 간략하게 설명합니다.

메모

JavaScript SDK 버전 0.9.0 이후의 API에는 이전 버전(<=0.5.0)과 호환되지 않는 변경사항이 있습니다.

다음 다이어그램에서는 이전 아키텍처가 REST 웹 서버를 사용하여 모델을 관리하고 채팅 완료와 같은 유추를 많이 사용하는 방법을 보여 줍니다.

Foundry Local에 대한 이전 아키텍처의 다이어그램

SDK는 RPC(원격 절차 호출)를 사용하여 컴퓨터에서 Foundry 로컬 CLI 실행 파일을 찾고, 웹 서버를 시작한 다음, HTTP를 통해 통신합니다. 이 아키텍처에는 다음을 비롯한 몇 가지 제한 사항이 있습니다.

  • 웹 서버 수명 주기 관리의 복잡성.
  • 까다로운 배포: 최종 사용자는 컴퓨터 및 애플리케이션에 Foundry 로컬 CLI를 설치해야 했습니다.
  • CLI 및 SDK의 버전 관리로 인해 호환성 문제가 발생할 수 있습니다.

이러한 문제를 해결하기 위해 새롭게 디자인된 아키텍처는 보다 간소화된 접근 방식을 사용합니다. 새 아키텍처는 다음과 같습니다.

Foundry Local의 새 아키텍처 다이어그램

이 새 아키텍처에서는 다음을 수행합니다.

  • 애플리케이션이 자체적으로 포함되어 있습니다. 최종 사용자의 컴퓨터에 Foundry 로컬 CLI를 별도로 설치할 필요가 없으므로 애플리케이션을 더 쉽게 배포할 수 있습니다.
  • REST 웹 서버는 선택 사항입니다. HTTP를 통해 통신하는 다른 도구와 통합하려는 경우에도 웹 서버를 사용할 수 있습니다.
  • SDK는 채팅 완료 및 오디오 전사를 기본적으로 지원하므로 종속성이 적은 대화형 AI 애플리케이션을 빌드할 수 있습니다.

API 변경 사항

최신 버전은 보다 개체 지향적이고 구성 가능한 API를 제공합니다. 기본 진입점은 계속해서 FoundryLocalManager 클래스가 되지만, 상태 비저장 HTTP API에 대한 정적 호출을 통해 작동하는 단일 메서드 집합 대신, 이제 SDK는 서비스와 모델에 대한 상태를 유지하는 FoundryLocalManager 인스턴스의 메서드를 제공합니다.

원시적인 이전 버전 현재 버전
Configuration N/A config = { appName: "app-name", ... }
관리자 가져오기 mgr = new FoundryLocalManager(); mgr = FoundryLocalManager.create(config);
카탈로그 가져오기 N/A catalog = mgr.catalog;
모델 나열 mgr.listCatalogModels(); catalog.getModels();
모델 가져오기 mgr.getModelInfo("aliasOrModelId"); catalog.getModel(alias);
변형 가져오기 N/A model.id;
변형 설정 N/A model.selectVariant(modelId);
모델 다운로드 mgr.downloadModel("aliasOrModelId"); model.download();
모델 로드 mgr.loadModel("aliasOrModelId"); model.load();
모델 언로드 mgr.unloadModel("aliasOrModelId"); model.unload();
로드된 모델 나열 mgr.listLoadedModels(); catalog.getLoadedModels();
모델 경로 가져오기 N/A model.path;
서비스 시작 mgr.startService(); mgr.startWebService();
서비스 중지 N/A mgr.stopWebService();
캐시 위치 mgr.getCacheLocation(); config.modelCacheDir
캐시된 모델 나열 mgr.listCachedModels(); catalog.getCachedModels();

API를 사용하면 웹 서버, 로깅, 캐시 위치 및 모델 변형 선택을 통해 Foundry Local을 보다 쉽게 구성할 수 있습니다. 예를 들어 애플리케이션 이름, config 로깅 수준, 웹 서버 URL 및 애플리케이션 데이터, 모델 캐시 및 로그에 대한 디렉터리를 설정할 수 있습니다.

const config = {
  appName: "app-name",
  logLevel: "info",
  webServiceUrls: "http://127.0.0.1:55588",
  appDataDir: "./foundry_local_data",
  modelCacheDir: "{appDataDir}/model_cache",
  logsDir: "{appDataDir}/logs",
};

이전 버전의 Foundry 로컬 JavaScript SDK에서는 SDK를 통해 이러한 설정을 직접 구성할 수 없으므로 서비스 동작을 사용자 지정하는 기능이 제한되었습니다.

참조

Python SDK 마이그레이션 가이드

디바이스 내 AI를 사용하여 애플리케이션을 배송하는 기능을 향상시키기 위해 Python SDK의 아키텍처가 크게 변경되었습니다. 이 섹션에서는 애플리케이션을 최신 버전의 SDK로 마이그레이션하는 데 도움이 되는 주요 변경 내용을 간략하게 설명합니다.

메모

최신 Python SDK 버전(1.0.0)에는 이전 버전(<=0.5.1)의 API와의 비호환성이 발생하는 변경 사항이 있습니다.

다음 다이어그램에서는 이전 아키텍처가 REST 웹 서버를 사용하여 모델을 관리하고 채팅 완료와 같은 유추를 많이 사용하는 방법을 보여 줍니다.

Foundry Local에 대한 이전 아키텍처의 다이어그램

SDK는 RPC(원격 절차 호출)를 사용하여 컴퓨터에서 Foundry 로컬 CLI 실행 파일을 찾고, 웹 서버를 시작한 다음, HTTP를 통해 통신합니다. 이 아키텍처에는 다음을 비롯한 몇 가지 제한 사항이 있습니다.

  • 웹 서버 수명 주기 관리의 복잡성.
  • 까다로운 배포: 최종 사용자는 컴퓨터 및 애플리케이션에 Foundry 로컬 CLI를 설치해야 했습니다.
  • CLI 및 SDK의 버전 관리로 인해 호환성 문제가 발생할 수 있습니다.

이러한 문제를 해결하기 위해 새롭게 디자인된 아키텍처는 보다 간소화된 접근 방식을 사용합니다. 새 아키텍처는 다음과 같습니다.

Foundry Local의 새 아키텍처 다이어그램

이 새 아키텍처에서는 다음을 수행합니다.

  • 애플리케이션이 자체적으로 포함되어 있습니다. 최종 사용자의 컴퓨터에 Foundry 로컬 CLI를 별도로 설치할 필요가 없으므로 애플리케이션을 더 쉽게 배포할 수 있습니다.
  • REST 웹 서버는 선택 사항입니다. HTTP를 통해 통신하는 다른 도구와 통합하려는 경우에도 웹 서버를 사용할 수 있습니다.
  • SDK는 채팅 완료 및 오디오 전사를 기본적으로 지원하므로 종속성이 적은 대화형 AI 애플리케이션을 빌드할 수 있습니다.

API 변경 사항

최신 버전은 보다 개체 지향적이고 구성 가능한 API를 제공합니다. 주 진입점은 계속해서 FoundryLocalManager 클래스이지만 초기화 패턴, 모델 관리 및 유추가 모두 크게 변경되었습니다.

원시적인 이전 버전(foundry-local) 현재 버전(foundry-local-sdk)
패키지 pip install foundry-local pip install foundry-local-sdk
가져오기 from foundry_local import FoundryLocalManager from foundry_local_sdk import Configuration, FoundryLocalManager
Configuration N/A config = Configuration(app_name="app-name")
관리자 가져오기 manager = FoundryLocalManager(alias) FoundryLocalManager.initialize(config)
manager = FoundryLocalManager.instance
카탈로그 가져오기 N/A catalog = manager.catalog
모델 나열 manager.list_catalog_models() catalog.list_models()
모델 가져오기 manager.get_model_info(alias) catalog.get_model(alias)
모델 다운로드 manager.download_model(alias) model.download(progress_callback)
모델 로드 manager.load_model(alias) model.load()
모델 언로드 manager.unload_model(alias) model.unload()
로드된 모델 나열 manager.list_loaded_models() catalog.get_loaded_models()
캐시된 모델 나열 manager.list_cached_models() catalog.get_cached_models()
캐시 위치 manager.get_cache_location() config.model_cache_dir
서비스 시작 manager.start_service() manager.start_web_service()
서비스 엔드포인트 manager.endpoint manager.urls

API를 사용하면 웹 서버, 로깅, 캐시 위치 및 모델 변형 선택을 통해 Foundry Local을 보다 쉽게 구성할 수 있습니다. 예를 들어 클래스를 Configuration 사용하면 애플리케이션 이름, 로깅 수준, 웹 서버 URL 및 애플리케이션 데이터, 모델 캐시 및 로그에 대한 디렉터리를 설정할 수 있습니다.

from foundry_local_sdk import Configuration

config = Configuration(
    app_name="app-name",
    log_level="info",
    web={"urls": "http://127.0.0.1:55588"},
    model_cache_dir="./foundry_local_data/model_cache",
)

참조

Rust SDK 마이그레이션 가이드

디바이스 내 AI를 사용하여 애플리케이션을 배송하는 기능을 향상시키기 위해 Rust SDK의 아키텍처가 크게 변경되었습니다. 이 섹션에서는 애플리케이션을 최신 버전의 SDK로 마이그레이션하는 데 도움이 되는 주요 변경 내용을 간략하게 설명합니다.

메모

최신 Rust SDK 버전(1.0.0)에는 이전 버전의 API에 호환성이 손상되는 변경이 있습니다. 상자의 이름이 foundry-local에서 foundry-local-sdk로 변경되었습니다.

다음 다이어그램에서는 이전 아키텍처가 REST 웹 서버를 사용하여 모델을 관리하고 채팅 완료와 같은 유추를 많이 사용하는 방법을 보여 줍니다.

Foundry Local에 대한 이전 아키텍처의 다이어그램

SDK는 RPC(원격 절차 호출)를 사용하여 컴퓨터에서 Foundry 로컬 CLI 실행 파일을 찾고, 웹 서버를 시작한 다음, HTTP를 통해 통신합니다. 이 아키텍처에는 다음을 비롯한 몇 가지 제한 사항이 있습니다.

  • 웹 서버 수명 주기 관리의 복잡성.
  • 까다로운 배포: 최종 사용자는 컴퓨터 및 애플리케이션에 Foundry 로컬 CLI를 설치해야 했습니다.
  • CLI 및 SDK의 버전 관리로 인해 호환성 문제가 발생할 수 있습니다.

이러한 문제를 해결하기 위해 새롭게 디자인된 아키텍처는 보다 간소화된 접근 방식을 사용합니다. 새 아키텍처는 다음과 같습니다.

Foundry Local의 새 아키텍처 다이어그램

이 새 아키텍처에서는 다음을 수행합니다.

  • 애플리케이션이 자체적으로 포함되어 있습니다. 최종 사용자의 컴퓨터에 Foundry 로컬 CLI를 별도로 설치할 필요가 없으므로 애플리케이션을 더 쉽게 배포할 수 있습니다.
  • REST 웹 서버는 선택 사항입니다. HTTP를 통해 통신하는 다른 도구와 통합하려는 경우에도 웹 서버를 사용할 수 있습니다.
  • SDK는 채팅 완료 및 오디오 전사를 기본적으로 지원하므로 종속성이 적은 대화형 AI 애플리케이션을 빌드할 수 있습니다.

API 변경 사항

최신 버전은 보다 개체 지향적이고 구성 가능한 API를 제공합니다. 작성기 패턴이 구성 기반 접근 방법으로 대체되었으며 모델 관리에서 이제 전용 Model 개체를 사용합니다.

원시적인 이전 버전(foundry-local) 현재 버전(foundry-local-sdk)
상자 foundry-local foundry-local-sdk
Configuration N/A FoundryLocalConfig::new("app-name")
관리자 가져오기 FoundryLocalManager::builder().build().await? FoundryLocalManager::create(config)?
카탈로그 가져오기 N/A manager.catalog()
모델 나열 manager.list_catalog_models().await? manager.catalog().get_models().await?
모델 가져오기 manager.get_model_info(alias).await? manager.catalog().get_model(alias).await?
모델 다운로드 manager.download_model(alias).await? model.download(callback).await?
모델 로드 manager.load_model(alias).await? model.load().await?
모델 언로드 manager.unload_model(alias).await? model.unload().await?
로드된 모델 나열 manager.list_loaded_models().await? manager.catalog().get_loaded_models().await?
캐시된 모델 나열 manager.list_cached_models().await? manager.catalog().get_cached_models().await?
서비스 시작 manager.start_service()? manager.start_web_service().await?
엔드포인트 manager.endpoint()? manager.urls()
HTTP 호출 reqwest::Client (수동 REST) 네이티브 SDK: model.create_chat_client()

새 SDK는 네이티브 채팅 및 오디오 클라이언트를 제공하므로 대부분의 경우 수동 HTTP 요청이 필요하지 않습니다.

use foundry_local_sdk::{FoundryLocalConfig, FoundryLocalManager};

let config = FoundryLocalConfig::new("app-name");
let manager = FoundryLocalManager::create(config)?;

let model = manager.catalog().get_model("qwen2.5-0.5b").await?;
model.download(None).await?;
model.load().await?;

// Native chat client - no HTTP server needed
let client = model.create_chat_client().temperature(0.7).max_tokens(256);

참조

  • 에 마지막으로 업데이트됨