Foundry 로컬 SDK 참조

Python SDK 참조

설치

Python 패키지를 설치합니다.

pip install foundry-local-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: (선택 사항) 시작 시 다운로드 및 로드할 별칭 또는 모델 ID입니다.
• bootstrap: (기본 True) True이면 실행되지 않는 경우 서비스를 시작하고 제공된 경우 모델을 로드합니다.

별칭에 대한 메모

이 참조에 설명된 많은 메서드에는 서명에 alias_or_model_id 매개 변수가 있습니다. 메서드에 별칭 또는 모델 ID를 값으로 전달할 수 있습니다. 별칭을 사용하면 다음이 수행됩니다.

• 사용 가능한 하드웨어에 가장 적합한 모델을 선택합니다. 예를 들어 Nvidia CUDA GPU를 사용할 수 있는 경우 Foundry Local은 CUDA 모델을 선택합니다. 지원되는 NPU를 사용할 수 있는 경우 Foundry Local은 NPU 모델을 선택합니다.
• 모델 ID를 기억할 필요 없이 더 짧은 이름을 사용할 수 있습니다.

서비스 관리

카탈로그 관리

캐시 관리

모델 관리

사용 예시

다음 코드에서는 클래스를 사용하여 FoundryManager 모델을 관리하고 Foundry 로컬 서비스와 상호 작용하는 방법을 보여 줍니다.

from foundry_local import FoundryLocalManager

# By using an alias, the most suitable model will be selected 
# to your end-user's device.
alias = "phi-3.5-mini"

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

OpenAI SDK와 통합

OpenAI 패키지를 설치합니다.

pip install openai

다음 코드에서는 OpenAI SDK와 통합 FoundryLocalManager 하여 로컬 모델과 상호 작용하는 방법을 보여 줍니다.

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 = "phi-3.5-mini"

# 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 us es 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)

JavaScript SDK 참조

설치

npm에서 패키지를 설치합니다.

npm install foundry-local-sdk

FoundryLocalManager 클래스

이 FoundryLocalManager 클래스를 사용하면 브라우저 및 Node.js 환경에서 모델을 관리하고, 캐시를 제어하고, Foundry 로컬 서비스와 상호 작용할 수 있습니다.

초기화

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

const foundryLocalManager = new FoundryLocalManager()

사용 가능한 옵션:

• serviceUrl: Foundry 로컬 서비스의 기본 URL
• fetch: (선택 사항) Node.js 같은 환경에 대한 사용자 지정 페치 구현

별칭에 대한 메모

이 참조에 설명된 많은 메서드에는 서명에 aliasOrModelId 매개 변수가 있습니다. 메서드에 별칭 또는 모델 ID를 값으로 전달할 수 있습니다. 별칭을 사용하면 다음이 수행됩니다.

• 사용 가능한 하드웨어에 가장 적합한 모델을 선택합니다. 예를 들어 Nvidia CUDA GPU를 사용할 수 있는 경우 Foundry Local은 CUDA 모델을 선택합니다. 지원되는 NPU를 사용할 수 있는 경우 Foundry Local은 NPU 모델을 선택합니다.
• 모델 ID를 기억할 필요 없이 더 짧은 이름을 사용할 수 있습니다.

서비스 관리

카탈로그 관리

캐시 관리

모델 관리

사용 예시

다음 코드에서는 클래스를 사용하여 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 = "phi-3.5-mini";

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)

OpenAI 클라이언트와 통합

OpenAI 패키지를 설치합니다.

npm install openai

다음 코드는 OpenAI 클라이언트에 FoundryLocalManager을 통합하여 로컬 모델과 상호 작용하는 방법을 보여줍니다.

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 = "phi-3.5-mini";

// 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에는 서비스 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 endpoint = "ENDPOINT"

const manager = new FoundryLocalManager({serviceUrl: endpoint})

// 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 endpoint = "ENDPOINT"

const manager = new FoundryLocalManager({serviceUrl: endpoint})

const alias = 'phi-3.5-mini'

// 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.listLocalModels()
console.log("Cached models:", catalog)

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

C# SDK 참조

설치

Foundry 로컬 C# SDK를 사용하려면 NuGet 패키지를 설치해야 합니다.

dotnet add package Microsoft.AI.Foundry.Local

별칭에 대한 메모

이 참조에 설명된 많은 메서드에는 서명에 aliasOrModelId 매개 변수가 있습니다. 메서드에 별칭 또는 모델 ID를 값으로 전달할 수 있습니다. 별칭을 사용하면 다음이 수행됩니다.

• 사용 가능한 하드웨어에 가장 적합한 모델을 선택합니다. 예를 들어 Nvidia CUDA GPU를 사용할 수 있는 경우 Foundry Local은 CUDA 모델을 선택합니다. 지원되는 NPU를 사용할 수 있는 경우 Foundry Local은 NPU 모델을 선택합니다.
• 모델 ID를 기억할 필요 없이 더 짧은 이름을 사용할 수 있습니다.

열거형

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

다음 액세스에서 다시 로드되도록 캐시된 카탈로그를 지웁니다.

별칭 또는 ID로 모델 정보 가져오기

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

모델 형식

이 페이지에서는 모델, 다운로드 및 런타임 정보를 설명하기 위해 Foundry 로컬 C# SDK에서 사용하는 주요 데이터 형식을 설명합니다.

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 = "phi-3.5-mini";

await manager.DownloadModelAsync(alias);
await manager.LoadModelAsync(alias);

var loaded = await manager.ListLoadedModelsAsync();

await manager.UnloadModelAsync(alias);

manager.Dispose();

Rust SDK 참조

Foundry Local용 Rust SDK는 모델을 관리하고, 캐시를 제어하고, Foundry 로컬 서비스와 상호 작용하는 방법을 제공합니다.

설치

Foundry Local Rust SDK를 사용하려면 Cargo.toml에 다음을 추가합니다.

[dependencies]
foundry-local-sdk = "0.1"

또는 cargo를 사용하여 Foundry Local 크레이트를 추가할 수 있습니다.

cargo add foundry-local

FoundryLocalManager

Foundry 로컬 SDK 작업 관리자입니다.

분야

• service_uri: Option<String> — Foundry 서비스의 URI입니다.
• client: Option<HttpClient> — API 요청에 대한 HTTP 클라이언트입니다.
• 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를 가져옵니다.
  반환: Foundry 서비스의 URI입니다.

• 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>
  별칭 또는 ID로 모델 정보를 가져옵니다.
  인수:

  • alias_or_model_id: 별칭 또는 모델 ID입니다.
  • raise_on_not_found: true이지만 찾을 수 없으면 오류가 발생합니다.

• 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: 별칭 또는 모델 ID입니다.
  • token: 선택적 인증 토큰입니다.
  • force: 이미 캐시된 경우 강제로 다시 다운로드합니다.

• pub async fn load_model(&mut self, alias_or_model_id: &str, ttl: Option<i32>) -> Result<FoundryModelInfo>
  유추를 위해 모델을 로드합니다.
  인수:

  • alias_or_model_id: 별칭 또는 모델 ID입니다.
  • ttl: 선택적 수명 제한(초 단위로).

• pub async fn unload_model(&mut self, alias_or_model_id: &str, force: bool) -> Result<()>
  모델을 언로드합니다.
  인수:

  • alias_or_model_id: 별칭 또는 모델 ID입니다.
  • force: 사용 중인 경우에도 강제로 언로드합니다.

• pub async fn list_loaded_models(&mut self) -> Result<Vec<FoundryModelInfo>>
  로드된 모델을 나열합니다.

FoundryLocalManagerBuilder

FoundryLocalManager 인스턴스를 생성하는 빌더입니다.

분야

• alias_or_model_id: Option<String> — 다운로드 및 로드할 별칭 또는 모델 ID입니다.
• 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
  다운로드하고 로드할 별칭 또는 모델 ID를 설정합니다.

• 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

모델에 대한 정보를 나타냅니다.

분야

• alias: String — 모델 별칭입니다.
• id: String — 모델 ID입니다.
• version: String — 모델 버전입니다.
• runtime: ExecutionProvider — 실행 공급자(CPU, CUDA 등)입니다.
• uri: String — 모델 URI입니다.
• file_size_mb: i32 — 모델 파일 크기(MB)입니다.
• 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