PowerShell에서 Azure Local Foundry CLI 사용하기

추론 비용이 상승하고 있습니다. Anthropic, OpenAI, 그리고 Microsoft는 올해 모두 토큰 할당량(token quotas)을 강화했습니다. 보조금이 지원되던 생성형 AI (generative AI)의 시대가 조용히 끝나가고 있습니다. 모든 작업에 프런티어 모델 (frontier model)이 필요한 것은 아닙니다. 서식 지정 작업이나 빠른 요약을 위해 클라우드 토큰을 태우는 것은 그저 돈 낭비일 뿐입니다. 개인정보 보호와 데이터 보호는 두 번째 제약 사항을 추가합니다. 일부 워크로드 (workloads)는 단순히 여러분의 경계(perimeter)를 벗어날 수 없습니다. 여기에는 GDPR이 시행되는 유럽 사용자들도 포함됩니다. EU Cloud act 또한 곧 더 많은 제약을 추가할 것입니다. 바로 이 지점에서 로컬 모델 (local models)이 등장합니다. Ollama는 가장 좋은 참조 사례 중 하나로, 견고한 API를 제공하며 OpenCode와 같은 도구들과 잘 작동하고 수많은 모델을 제공합니다. NPU 칩이 탑재된 새 노트북을 얻었을 때, 저는 Microsoft Local Foundry를 테스트해 보았습니다. 전제 조건은 간단합니다: AI 가속기 (AI accelerator)를 사용하여 로컬에서 추론을 실행하며, 더 이상 클라우드 제공업체가 개입하지 않는 것입니다. Local Foundry는 SDK (Windows, Linux, macOS) 및 프리뷰 단계의 CLI (Windows 및 macOS) 형태로 제공됩니다. 이 포스트는 CLI에 초점을 맞춥니다. Foundry local을 설치하려면 셸(shell)에서 다음 한 줄을 실행하십시오. Windows에서는 winget install Microsoft.FoundryLocal, macOS에서는 brew install microsoft/foundrylocal/foundrylocal을 실행합니다. 모델을 관리하기 위한 세 가지 명령어가 있습니다. list는 사용 가능한 모델의 상세 목록을 보여주고, download는 모델을 로컬 캐시로 가져오며, load는 실행 중인 서비스에 모델을 올립니다. run은 이 모든 과정을 한 번에 수행하며, 빠른 테스트에 유용합니다.

foundry model list
foundry model run deepseek-r1-14b
foundry model download deepseek-r1-14b
foundry model load deepseek-r1-14b
foundry model run deepseek-r1-14b

CLI는 대화형 사용에 매우 훌륭합니다. 하지만 PowerShell에서 이를 자동화하고 싶다면 어떻게 해야 할까요? 두 가지 통합 경로가 있습니다: SDK (Python, C#, Rust, JavaScript) 또는 CLI가 노출하는 REST API입니다. PowerShell에는 직접적인 SDK 바인딩이 없으므로, 우리는 REST 경로를 택할 것입니다. API 호출 전 세 가지 전제 조건이 있습니다: 서비스가 실행 중이어야 하고, 모델이 로드되어 있어야 하며, REST API URI가 필요합니다. 이 스크립트는 서비스가 중지되어 있다면 서비스를 시작하고 REST API URI를 가져올 것입니다.

function get-foundryServiceStatus { return & foundry service status }
$getServiceStatus = get-foundryServiceStatus
if ( $getServiceStatus -like "*service is not running*" ) {
    & foundry service start | Out-Null
    $getServiceStatus = get-foundryServiceStatus
}
# 서비스의 URI를 가져오기 위해 모델을 로드합니다
& foundry model load phi-3-mini-128k | Out-Null
$pattern = 'https?://[^\s"\']+'
$uri = [ regex ]:: Match ( $getServiceStatus , $pattern ) . Value
$uri = $uri -replace '/openai/status$' , ''
$uri

이제 올바른 형식으로 REST API를 호출하는 함수를 만들 수 있습니다.

function Invoke-FoundryRequest {
    param (
        [ Parameter ( Mandatory )]
        [ string ] $Method ,
        [ Parameter ( Mandatory )]
        [ string ] $FoundryBaseUrl ,
        [ Parameter ( Mandatory )]
        [ string ] $Path ,
        [ hashtable ] $Headers ,
        $Body
    )
    $uri = " $FoundryBaseUrl$Path "
    $params = @{ Method = $Method Uri = $uri }
    if ( $Headers ) {
        $params . Headers = $Headers
    }
    if ( $Body ) {
        $params . Body = ( $Body | ConvertTo-Json -Depth 10 )
        $params . ContentType = "application/json"
    }
    return Invoke-RestMethod @ params
}

이제부터 API를 본격적으로 사용해 볼 수 있습니다. 로컬에서 사용 가능한 모델 목록을 가져오려면 다음과 같이 입력합니다.

Invoke-FoundryRequest -Method GET -Path "/openai/models" -FoundryBaseUrl $uri

하지만 로컬 에이전트(Local Agent)를 사용할 때 가장 중요한 부분은 채팅을 시작하는 것입니다. 이 경우 알아두어야 할 몇 가지 사항이 있습니다. Local Foundry REST API는 OpenAI Chat Completion과 호환됩니다. 원문 텍스트(Raw text)를 보내는 것이 아니라, 역할(Role)/내용(Content) 쌍으로 구성된 구조화된 배열을 보냅니다. 역할(Role)에는 system, user, assistant가 있습니다. 내용(Content)은 프롬프트(Prompt)입니다. 모델에 프롬프트를 보내려면 두 가지 역할이 필요합니다. assistant의 동작, 어조 및 컨텍스트를 설정하기 위한 system 역할과 입력을 위한 user 역할입니다. assistant는 모델에서 생성된 콘텐츠에 사용되는 역할입니다. 사용하려는 모델의 이름을 제공해야 하는데, 이는 모델을 로드하거나 실행할 때 사용하는 이름이 아니라 이전 명령에서 나열된 전체 이름이어야 합니다. 여기에서는 phi-3-mini-128k-instruct-qnn-npu:3를 사용합니다.

창의성은 temperature (온도) 파라미터로 조정할 수 있습니다. 0과 2 사이의 값을 사용하여 응답의 창의성을 조정합니다 (값이 높을수록 더 높은 창의성을 의미합니다). 다른 많은 파라미터들을 사용할 수 있으며, 해당 내용은 이 페이지 https://learn.microsoft.com/en-us/azure/foundry-local/reference/reference-rest#post-v1chatcompletions 에 나열되어 있습니다. chat completion (채팅 완성) API를 사용하려면, JSON 데이터와 함께 API 경로 /v1/chat/completions로 POST 요청을 보내야 합니다. 이 작업을 처리하는 데 도움이 되는 함수를 작성해 보겠습니다.

function New-FoundryChatCompletion {
    [ CmdletBinding ()]
    param (
        [ string ] $Model = "phi-3-mini-128k-instruct-qnn-npu:3" ,
        [ Parameter ( Mandatory )]
        [ array ] $Messages ,
        [ Parameter ( Mandatory )]
        [ string ] $FoundryBaseUrl ,
        [ double ] $Temperature ,
        [ double ] $TopP ,
        [ int ] $MaxTokens
    )
    $body = @{
        model = $Model
        messages = $Messages
        max_tokens = 2048
        max_completion_tokens = 2048
    }
    if ( $PSBoundParameters . ContainsKey ( 'Temperature' )) {
        $body . temperature = $Temperature
    }
    if ( $PSBoundParameters . ContainsKey ( 'TopP' )) {
        $body . top_p = $TopP
    }
    Invoke-FoundryRequest -Method POST -Path "/v1/chat/completions" -Body $body -FoundryBaseUrl $FoundryBaseUrl
}

이를 사용하려면 두 가지 역할 (role)이 포함된 메시지 배열이 필요합니다.

$messages = @(
    @{ role = "system" ; content = "You are a PowerShell coding assistant. Only give code if requested." },
    @{ role = "user" ; content = "Give me a PowerShell script to list all files in a directory." }
)

$chat = New-FoundryChatCompletion -FoundryBaseUrl "http://127.0.0.1:52236" -Temperature 0.2 -Messages $messages

모델의 응답은 choice라는 이름의 배열에서 찾을 수 있습니다.

$chat . choices [ 0 ] . message . content

REST API를 사용하면 놀라울 정도로 많은 것을 할 수 있지만, 한계가 있습니다. 다음 포스트에서는 PowerShell에서 모든 기능을 활용할 수 있게 해주는 .NET SDK를 다룹니다.