Foundry 로컬 REST API 참조

중요합니다

Foundry Local은 미리 보기로 제공됩니다. 공개 미리 보기 릴리스에서는 현재 적극적으로 배포되고 있는 기능에 대한 조기 액세스를 제공합니다.
GA(일반 공급) 전에는 기능, 방식 및 프로세스가 변경되거나 기능이 제한될 수 있습니다.

주의

이 API는 Foundry 로컬 CLI에서 사용할 수 있는 REST API를 나타냅니다. 이 API는 현재 개발 중이며 예고 없이 호환성이 손상되는 변경이 포함될 수 있습니다. 프로덕션 애플리케이션을 빌드하기 전에 변경 로그를 모니터링하는 것이 좋습니다.

POST /v1/chat/completions

이 엔드포인트는 채팅 완료 요청을 처리합니다.
OpenAI 채팅 완료 API와 완벽하게 호환됩니다.

요청 본문:

---표준 OpenAI 속성---

model (문자열)
완료에 사용할 특정 모델입니다.
messages (배열)
메시지 목록인 대화 기록입니다.
- 각 메시지에는 다음이 필요합니다.
  - role (문자열)
    메시지 보낸 사람의 역할입니다. system, user 또는 assistant여야 합니다.
  - content (문자열)
    실제 메시지 텍스트.
temperature (숫자, 선택 사항)
0에서 2까지의 임의성을 제어합니다. 값(0.8)이 높을수록 다양한 출력이 생성되고, 값(0.2)이 낮을수록 집중되고 일관된 출력이 생성됩니다.
top_p (숫자, 선택 사항)
0에서 1까지의 토큰 선택 다양성을 제어합니다. 값이 0.1이면 상위 10개% 확률의 토큰만 고려됩니다.
n (정수, 선택 사항)
각 입력 메시지에 대해 생성할 대체 완료 수입니다.
stream (부울, 선택 사항)
true이면 서버에서 보낸 이벤트로 부분 메시지 응답을 보내고 메시지로 data: [DONE] 끝납니다.
stop (문자열 또는 배열, 선택 사항)
모델이 추가 토큰 생성을 중지하는 최대 4개의 시퀀스입니다.
max_tokens (정수, 선택 사항)
생성할 최대 토큰 수. 최신 모델의 경우 대신 사용합니다 max_completion_tokens .
max_completion_tokens (정수, 선택 사항)
표시되는 출력 및 추론 토큰을 포함하여 모델이 생성할 수 있는 최대 토큰 수입니다.
presence_penalty (숫자, 선택 사항)
-2.0에서 2.0 사이의 값입니다. 양수 값은 모델이 이미 나타난 토큰을 처벌하여 새 토픽을 논의하도록 장려합니다.
frequency_penalty (숫자, 선택 사항)
-2.0에서 2.0 사이의 값입니다. 양수 값은 텍스트의 빈도에 따라 토큰을 처벌하여 반복을 권장하지 않습니다.
logit_bias (map, 선택 사항)
완료 시 특정 토큰이 나타날 확률을 조정합니다.
user (문자열, 선택 사항)
모니터링 및 남용 방지에 도움이 되는 최종 사용자의 고유 식별자입니다.
functions (배열, 선택 사항)
모델이 JSON 입력을 생성할 수 있는 사용 가능한 함수입니다.
- 각 함수에는 다음이 포함되어야 합니다.
  - name (문자열)
    함수 이름.
  - description (문자열)
    함수 설명입니다.
  - parameters (객체)
    JSON 스키마 개체로 설명된 함수 매개 변수입니다.
function_call (문자열 또는 개체, 선택 사항)
모델이 함수 호출에 응답하는 방식을 제어합니다.
- 개체인 경우 다음을 포함할 수 있습니다.
  - name (문자열, 선택 사항)
    호출할 함수의 이름입니다.
  - arguments (개체, 선택 사항)
    함수에 전달할 인수입니다.
metadata (개체, 선택 사항)
메타데이터 키-값 쌍의 사전입니다.
top_k (숫자, 선택 사항)
상위 k 필터링을 위해 유지할 가장 높은 확률 어휘 토큰의 수입니다.
random_seed (정수, 선택 사항)
재현 가능한 난수 생성을 위한 시드입니다.
ep (문자열, 선택 사항)
ONNX 모델의 공급자를 덮어쓰세요. 지원: "dml", "cuda", "qnn""cpu", "webgpu".
ttl (정수, 선택 사항)
모델이 메모리에서 유지되는 시간(초)입니다.
tools (개체, 선택 사항)
요청에 대해 계산된 도구입니다.

응답 본문:

id (문자열)
채팅 완료를 위한 고유 식별자입니다.
object (문자열)
객체 유형은 항상 "chat.completion"입니다.
created (정수)
생성 시간은 epoch 초로 표시됩니다.
model (문자열)
완성에 사용되는 모델입니다.
choices (배열)
각 항목이 포함된 완료 선택 항목 목록:
- index (정수)
  이 선택 항목의 인덱스입니다.
- message (객체)
  생성된 메시지는 다음과 같습니다.
  - role (문자열)
    응답 시 항상 "assistant"를 사용하세요.
  - content (문자열)
    실제 생성된 텍스트입니다.
- finish_reason (문자열)
  생성이 중지된 이유(예: "stop", , "length""function_call").
usage (객체)
토큰 사용 통계:
- prompt_tokens (정수)
  프롬프트의 토큰입니다.
- completion_tokens (정수)
  완료 속 토큰.
- total_tokens (정수)
  사용된 총 토큰입니다.

Example:

요청 메시지 본문

  {
    "model": "qwen2.5-0.5b-instruct-generic-cpu",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ],
    "temperature": 0.7,
    "top_p": 1,
    "n": 1,
    "stream": false,
    "stop": null,
    "max_tokens": 100,
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "logit_bias": {},
    "user": "user_id_123",
    "functions": [],
    "function_call": null,
    "metadata": {}
  }

응답 메시지 본문

  {
    "id": "chatcmpl-1234567890",
    "object": "chat.completion",
    "created": 1677851234,
    "model": "qwen2.5-0.5b-instruct-generic-cpu",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "I'm doing well, thank you! How can I assist you today?"
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 10,
      "completion_tokens": 20,
      "total_tokens": 30
    }
  }

GET /openai/status

서버 상태 정보를 가져옵니다.

응답 본문:

Endpoints (문자열 배열)
HTTP 서버 바인딩 엔드포인트입니다.
ModelDirPath (문자열)
로컬 모델이 저장되는 디렉터리입니다.
PipeName (문자열)
현재 NamedPipe 서버 이름입니다.

Example:

응답 메시지 본문

  {
    "Endpoints": ["http://localhost:5272"],
    "ModelDirPath": "/path/to/models",
    "PipeName": "inference_agent"
  }

GET /foundry/list

카탈로그에서 사용 가능한 Foundry 로컬 모델 목록을 가져옵니다.

응답:

models (배열)
모델 개체의 배열입니다. 각 모델에는 다음이 포함됩니다.
- name: 모델의 고유 식별자입니다.
- displayName: 모델에 대해 사람이 읽을 수 있는 이름으로, 종종 이름과 동일합니다.
- providerType: 모델을 호스팅하는 공급자의 유형입니다(예: AzureFoundry).
- uri: 레지스트리에서 모델의 위치를 가리키는 리소스 URI입니다.
- version: 모델의 버전 번호입니다.
- modelType: 모델의 형식 또는 형식(예: ONNX)입니다.
- promptTemplate:
  - assistant: 도우미의 응답에 대한 템플릿입니다.
  - prompt: 사용자 도우미 상호 작용을 위한 템플릿입니다.
- publisher: 모델을 게시한 엔터티 또는 조직입니다.
- task: 모델이 수행하도록 설계된 기본 작업(예: 채팅 완료)입니다.
- runtime:
  - deviceType: 모델이 실행되도록 설계된 하드웨어 유형(예: CPU)입니다.
  - executionProvider: 모델을 실행하는 데 사용되는 실행 공급자입니다.
- fileSizeMb: 모델 파일의 크기(메가바이트)입니다.
- modelSettings:
  - parameters: 모델에 대한 구성 가능한 매개 변수 목록입니다.
- alias: 모델의 대체 이름 또는 약식
- supportsToolCalling: 모델이 도구 호출 기능을 지원하는지 여부를 나타냅니다.
- license: 모델이 배포되는 라이선스 유형입니다.
- licenseDescription: 사용 조건에 대한 자세한 설명 또는 링크입니다.
- parentModelUri: 이 모델이 파생된 부모 모델의 URI입니다.

GET /openai/models

로컬 및 등록된 외부 모델을 포함하여 캐시된 모델 목록을 가져옵니다.

응답:

200 확인
문자열로 사용되는 모델 이름의 배열입니다.

Example:

응답 메시지 본문

  ["Phi-4-mini-instruct-generic-cpu", "phi-3.5-mini-instruct-generic-cpu"]

POST /openai/download

카탈로그에서 로컬 스토리지로 모델을 다운로드합니다.

비고

대형 모델 다운로드에는 시간이 오래 걸릴 수 있습니다. 이 요청에 대한 높은 시간 제한을 설정하여 조기 종료를 방지합니다.

요청 본문:

model (WorkspaceInferenceModel 객체)
- Uri (문자열)
  다운로드할 모델 URI입니다.
- Name (string) 모델 이름입니다.
- ProviderType (문자열, 선택 사항)
  공급자 유형입니다(예: <a0/.).
- Path (문자열, 선택 사항)
  모델 파일의 원격 경로입니다. 예를 들어 Hugging Face 리포지토리에서 모델 파일의 경로입니다.
- PromptTemplate (Dictionary<string, string>, 선택 사항)
  포함 항목:
  - system (문자열, 선택 사항)
    시스템 메시지의 템플릿입니다.
  - user (문자열, 선택 사항) 사용자 메시지에 대한 템플릿입니다.
  - assistant (문자열, 선택 사항)
    도우미의 응답에 대한 템플릿입니다.
  - prompt (문자열, 선택 사항)
    사용자 도우미 상호 작용을 위한 템플릿입니다.
- Publisher (문자열, 선택 사항)
  모델의 게시자입니다.
token (문자열, 선택 사항)
보호된 모델(GitHub 또는 Hugging Face)에 대한 인증 토큰입니다.
progressToken (개체, 선택 사항)
AITK에만 해당합니다. 다운로드 진행률을 추적하는 토큰입니다.
customDirPath (문자열, 선택 사항)
사용자 지정 다운로드 디렉터리(CLI에 사용되며 AITK에는 필요하지 않음).
bufferSize (정수, 선택 사항)
HTTP 다운로드 버퍼 크기(KB)입니다. NIM 또는 Azure Foundry 모델에는 영향을 주지 않습니다.
ignorePipeReport (부울, 선택 사항)
경우 true파이프 대신 HTTP 스트림을 통해 진행률 보고를 강제로 합니다. 기본값은 AITK의 경우 false, Foundry Local의 경우 true으로 설정됩니다.

스트리밍 응답:

다운로드하는 동안 서버는 진행률 업데이트를 다음과 같은 형식으로 스트리밍합니다.

("file name", percentage_complete)

최종 응답 본문:

Success(부울)
다운로드가 성공적으로 완료되었는지 여부입니다.
ErrorMessage (문자열, 선택 사항)
다운로드에 실패한 경우 오류 세부 정보입니다.

Example:

URI 요청

POST /openai/download

요청 메시지 본문

버전 접미사는 모델 이름에 제공되어야 합니다.

{
  "model": {
    "Uri": "azureml://registries/azureml/models/Phi-4-mini-instruct-generic-cpu/versions/4",
    "ProviderType": "AzureFoundryLocal",
    "Name": "Phi-4-mini-instruct-generic-cpu:4",
    "Publisher": "",
    "PromptTemplate": {
      "system": "<|system|>{Content}<|end|>",
      "user": "<|user|>{Content}<|end|>",
      "assistant": "<|assistant|>{Content}<|end|>",
      "prompt": "<|user|>{Content}<|end|><|assistant|>"
    }
  }
}

응답 스트림

  ("genai_config.json", 0.01)
  ("genai_config.json", 0.2)
  ("model.onnx.data", 0.5)
  ("model.onnx.data", 0.78)
  ...
  ("", 1)

최종 응답

  {
    "Success": true,
    "ErrorMessage": null
  }

GET /openai/load/{name}

더 빠른 유추를 위해 모델을 메모리에 로드합니다.

URI 매개 변수:

name (문자열)
로드할 모델 이름입니다.

쿼리 매개 변수:

unload (부울, 선택 사항)
유휴 시간 후에 모델을 자동으로 언로드할지 여부입니다. 기본값은 true입니다.
ttl (정수, 선택 사항)
초 단위로 지정된 유효 시간입니다. 0보다 크면 이 값이 unload 매개 변수를 재정의합니다.
ep (문자열, 선택 사항)
이 모델을 실행할 실행 공급자입니다. 지원: "dml", "cuda", "qnn""cpu", "webgpu".
지정하지 않으면 .의 genai_config.json설정을 사용합니다.

응답:

200 확인
빈 응답 본문

Example:

URI 요청

  GET /openai/load/Phi-4-mini-instruct-generic-cpu?ttl=3600&ep=dml

GET /openai/unload/{name}

메모리에서 모델을 언로드합니다.

URI 매개 변수:

name (string) 언로드할 모델 이름입니다.

쿼리 매개 변수:

force (부울, 선택 사항) 이면 trueTTL 설정을 무시하고 즉시 언로드합니다.

응답:

200 OK 빈 응답 본문

Example:

URI 요청

GET /openai/unload/Phi-4-mini-instruct-generic-cpu?force=true

GET /openai/unloadall

메모리에서 모든 모델을 언로드합니다.

응답:

200 확인
빈 응답 본문

GET /openai/loadedmodels

현재 로드된 모델 목록을 가져옵니다.

응답:

200 확인
문자열로 사용되는 모델 이름의 배열입니다.

Example:

응답 메시지 본문

["Phi-4-mini-instruct-generic-cpu", "phi-3.5-mini-instruct-generic-cpu"]

GET /openai/getgpudevice

현재 GPU 디바이스 ID를 가져옵니다.

응답:

200 확인
현재 GPU 디바이스 ID를 나타내는 정수입니다.

GET /openai/setgpudevice/{deviceId}

활성 GPU 디바이스를 설정합니다.

URI 매개 변수:

deviceId (정수)
사용할 GPU 디바이스 ID입니다.

응답:

200 확인
빈 응답 본문

Example:

요청 URI
```
GET /openai/setgpudevice/1
```

POST /v1/chat/completions/tokenizer/encode/count

유추를 수행하지 않고 지정된 채팅 완료 요청에 대한 토큰 수를 계산합니다.

요청 본문:

Content-Type: application/json
형식의 ChatCompletionCreateRequest JSON 개체는 다음과 같습니다.
- model (문자열)
  토큰화에 사용할 모델입니다.
- messages (배열)
  메시지 개체들과 role 및 content이 있는 배열.

응답 본문:

Content-Type: application/json
토큰 수가 있는 JSON 개체:
- tokenCount (정수)
  요청에 있는 토큰 수.

Example:

요청 메시지 본문

  {
    "messages": [
      {
        "role": "system",
        "content": "This is a system message"
      },
      {
        "role": "user",
        "content": "Hello, what is Microsoft?"
      }
    ],
    "model": "Phi-4-mini-instruct-cuda-gpu"
  }

응답 메시지 본문

  {
    "tokenCount": 23
  }

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-02-28

다음을 통해 공유

Foundry 로컬 REST API 참조

POST /v1/chat/completions

GET /openai/status

GET /foundry/list

GET /openai/models

POST /openai/download

GET /openai/load/{name}

GET /openai/unload/{name}

GET /openai/unloadall

GET /openai/loadedmodels

GET /openai/getgpudevice

GET /openai/setgpudevice/{deviceId}

POST /v1/chat/completions/tokenizer/encode/count

피드백

추가 리소스