Dokumentacja lokalnego interfejsu API REST usługi Foundry

POST /v1/chat/completions

Ten punkt końcowy przetwarza żądania ukończenia czatu.
Jest w pełni zgodna z API OpenAI Chat Completions.

Treść żądania :

---Standard OpenAI Properties---

• model (ciąg)
  Konkretny model do dokończenia.
• messages (tablica)
  Historia konwersacji jako lista wiadomości.
  • Każdy komunikat wymaga:
    • role (ciąg)
      Rola nadawcy wiadomości. Musi mieć wartość system, userlub assistant.
    • content (ciąg)
      Rzeczywisty tekst wiadomości.
• temperature (liczba, opcjonalnie)
  Kontroluje losowość, od 0 do 2. Wyższe wartości (0,8) tworzą różne dane wyjściowe, podczas gdy niższe wartości (0,2) tworzą ukierunkowane, spójne dane wyjściowe.
• top_p (liczba, opcjonalnie)
  Steruje różnorodnością wyboru tokenów z zakresu od 0 do 1. Wartość 0,1 oznacza, że uwzględniane są tylko tokeny z najwyższego 10% prawdopodobieństwa.
• n (liczba całkowita, opcjonalna)
  Liczba alternatywnych zakończeń, które należy wygenerować dla każdej wiadomości wejściowej.
• stream (wartość logiczna, opcjonalnie)
  Jeśli ustawienie jest na true, wysyła częściowe odpowiedzi jako zdarzenia wysyłane przez serwer, zakończone komunikatem data: [DONE].
• stop (ciąg lub tablica, opcjonalnie)
  Maksymalnie 4 sekwencje, które spowodują, że model przestanie generować kolejne tokeny.
• max_tokens (liczba całkowita, opcjonalna)
  Maksymalna liczba tokenów do wygenerowania. W przypadku nowszych modeli użyj max_completion_tokens zamiast tego.
• max_completion_tokens (liczba całkowita, opcjonalna)
  Maksymalna liczba tokenów, które może wygenerować model, w tym widoczne dane wyjściowe i tokeny rozumowania.
• presence_penalty (liczba, opcjonalnie)
  Wartość z zakresu od -2.0 do 2.0. Dodatnie wartości zachęcają model do omawiania nowych tematów, karząc tokeny, które już się pojawiły.
• frequency_penalty (liczba, opcjonalnie)
  Wartość z zakresu od -2.0 do 2.0. Dodatnie wartości zniechęcają do powtarzania, nakładając kary na tokeny w zależności od ich częstotliwości w tekście.
• logit_bias (mapa, opcjonalnie)
  Dostosowuje prawdopodobieństwo wystąpienia określonych tokenów w zakończeniu.
• user (ciąg, opcjonalny)
  Unikatowy identyfikator użytkownika końcowego, który pomaga w monitorowaniu i zapobieganiu nadużyciom.
• functions (tablica, opcjonalnie)
  Dostępne funkcje, dla których model może generować dane wejściowe JSON.
  • Każda funkcja musi zawierać następujące elementy:
    • name (ciąg)
      Nazwa funkcji.
    • description (ciąg)
      Opis funkcji.
    • parameters (obiekt)
      Parametry funkcji opisane jako obiekt schematu JSON.
• function_call (ciąg lub obiekt, opcjonalnie)
  Określa sposób, w jaki model reaguje na wywołania funkcji.
  • Jeśli obiekt może zawierać następujące elementy:
    • name (ciąg, opcjonalny)
      Nazwa funkcji do wywołania.
    • arguments (obiekt, opcjonalnie)
      Argumenty, które mają być przekazywane do funkcji.
• metadata (obiekt, opcjonalnie)
  Słownik par klucz-wartość metadanych.
• top_k (liczba, opcjonalnie)
  Liczba tokenów słownictwa o najwyższym prawdopodobieństwie, które należy zachować na potrzeby filtrowania top-k.
• random_seed (liczba całkowita, opcjonalna)
  Ziarno do powtarzalnego generowania liczb losowych.
• ep (ciąg, opcjonalny)
  Nadpisz dostawcę modeli ONNX. Obsługuje: "dml", "cuda", "qnn", "cpu", "webgpu".
• ttl (liczba całkowita, opcjonalna)
  Czas wygaśnięcia w sekundach dla modelu w pamięci.
• tools (obiekt, opcjonalnie)
  Narzędzia obliczane dla żądania.

Treść odpowiedzi:

• id (ciąg)
  Unikatowy identyfikator dla ukończenia czatu.
• object (ciąg)
  Typ obiektu, zawsze "chat.completion".
• created (liczba całkowita)
  Znacznik czasu utworzenia w sekundach epoki.
• model (ciąg)
  Model używany do ukończenia.
• choices (tablica)
  Lista opcji ukończenia, z których każda zawiera:
  • index (liczba całkowita)
    Indeks tego wyboru.
  • message (obiekt)
    Wygenerowany komunikat z:
    • role (ciąg)
      Zawsze "assistant" w przypadku odpowiedzi.
    • content (ciąg)
      Rzeczywisty wygenerowany tekst.
  • finish_reason (ciąg)
    Dlaczego generacja została zatrzymana (np. "stop", "length", "function_call").
• usage (obiekt)
  Statystyki użycia tokenu:
  • prompt_tokens (liczba całkowita)
    Tokeny w podpowiedzi.
  • completion_tokens (liczba całkowita)
    Tokeny w ramach zakończenia.
  • total_tokens (liczba całkowita)
    Łączna liczba użytych tokenów.

Przykład:

Ciało żądania

  {
    "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": {}
  }

Ciało odpowiedzi

  {
    "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

Uzyskaj informacje o stanie serwera.

Treść odpowiedzi:

• Endpoints (tablica ciągów znaków)
  Punkty końcowe powiązania serwera HTTP.
• ModelDirPath (ciąg)
  Katalog, w którym są przechowywane modele lokalne.
• PipeName (ciąg)
  Bieżąca nazwa serwera NamedPipe.

Przykład:

Ciało odpowiedzi

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

GET /foundry/list

Pobierz listę dostępnych modeli lokalnych programu Foundry w katalogu.

Odpowiedź:

• models (tablica)
  Tablica obiektów modelu. Każdy model obejmuje:
  • name: unikatowy identyfikator modelu.
  • displayName: czytelna dla człowieka nazwa modelu, często taka sama jak nazwa.
  • providerType: typ dostawcy hostowania modelu (na przykład AzureFoundry).
  • uri: identyfikator URI zasobu wskazujący lokalizację modelu w rejestrze.
  • version: numer wersji modelu.
  • modelType: format lub typ modelu (na przykład ONNX).
  • promptTemplate:
    • assistant: szablon odpowiedzi asystenta.
    • prompt: szablon interakcji asystenta użytkownika.
  • publisher: jednostka lub organizacja, która opublikowała model.
  • task: Podstawowe zadanie, które model jest przeznaczony do wykonania (na przykład ukończenie czatu).
  • runtime:
    • deviceType: Typ sprzętu, na którym model jest przeznaczony do uruchamiania (na przykład procesor).
    • executionProvider: dostawca usługi wykonywania używany do uruchamiania modelu.
  • fileSizeMb: rozmiar pliku modelu w megabajtach.
  • modelSettings:
    • parameters: lista konfigurowalnych parametrów dla modelu.
  • alias: alternatywna nazwa lub skrót modelu
  • supportsToolCalling: wskazuje, czy model obsługuje funkcje wywoływania narzędzi.
  • license: typ licencji, w ramach którego model jest dystrybuowany.
  • licenseDescription: szczegółowy opis lub link do postanowień licencyjnych.
  • parentModelUri: identyfikator URI modelu nadrzędnego, z którego wywodzi się ten model.

GET /openai/models

Pobierz listę buforowanych modeli, w tym lokalnych i zarejestrowanych modeli zewnętrznych.

Odpowiedź:

• 200 OK
  Tablica nazw modeli jako ciągi znaków.

Przykład:

Ciało odpowiedzi

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

POST /openai/download

Pobierz model z katalogu do magazynu lokalnego.

Treść żądania :

• model (WorkspaceInferenceModel obiekt)
  • Uri (ciąg)
    Identyfikator URI modelu do pobrania.
  • Name (ciąg) Nazwa modelu.
  • ProviderType (ciąg, opcjonalny)
    Typ dostawcy (na przykład "AzureFoundryLocal", "HuggingFace").
  • Path (ciąg, opcjonalny)
    Ścieżka zdalna do plików modelu. Na przykład w repozytorium Hugging Face jest to ścieżka do plików modelu.
  • PromptTemplate (Dictionary<string, string>, opcjonalnie)
    Uwzględnione funkcje:
    • system (ciąg, opcjonalny)
      Szablon komunikatu systemowego.
    • user (ciąg, opcjonalny) Szablon wiadomości użytkownika.
    • assistant (ciąg, opcjonalny)
      Szablon odpowiedzi asystenta.
    • prompt (ciąg, opcjonalny)
      Szablon interakcji asystenta użytkownika.
  • Publisher (ciąg, opcjonalny)
    Wydawca modelu.
• token (ciąg, opcjonalny)
  Token uwierzytelniania dla modeli chronionych (GitHub lub Hugging Face).
• progressToken (obiekt, opcjonalnie)
  Tylko w przypadku zestawu AITK. Token do śledzenia postępu pobierania.
• customDirPath (ciąg, opcjonalny)
  Niestandardowy katalog pobierania (używany dla interfejsu wiersza polecenia, nie jest wymagany w przypadku zestawu AITK).
• bufferSize (liczba całkowita, opcjonalna)
  Rozmiar buforu pobierania HTTP w kb. Nie ma wpływu na modele NIM ani Azure Foundry.
• ignorePipeReport (wartość logiczna, opcjonalnie)
  Jeśli truewartość , wymusza raportowanie postępu za pośrednictwem strumienia HTTP zamiast potoku. Wartość domyślna false dla zestawu AITK i true dla lokalnego zestawu narzędzi Foundry.

Odpowiedź na przesyłanie strumieniowe:

Podczas pobierania serwer przesyła strumieniowo aktualizacje postępu w formacie:

("file name", percentage_complete)

Treść końcowej odpowiedzi:

• Success (wartość logiczna)
  Czy pobieranie zostało ukończone pomyślnie.
• ErrorMessage (ciąg, opcjonalny)
  Szczegóły błędu, jeśli pobieranie nie powiodło się.

Przykład:

Żądanie URI

POST /openai/download

Ciało żądania

Należy pamiętać, że sufiks wersji musi być podany w nazwie modelu.

{
  "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|>"
    }
  }
}

Strumień odpowiedzi

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

Ostateczna odpowiedź

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

GET /openai/load/{name}

Załaduj model do pamięci, aby szybciej wnioskować.

Parametry identyfikatora URI:

• name (ciąg)
  Nazwa modelu do załadowania.

Parametry zapytania:

• unload (wartość logiczna, opcjonalnie)
  Czy należy automatycznie zwalniać model po okresie bezczynności? Wartość domyślna to true.
• ttl (liczba całkowita, opcjonalna)
  Czas życia w sekundach. Jeśli wartość jest większa niż 0, zastępuje unload parametr .
• ep (ciąg, opcjonalny)
  Usługodawca do uruchomienia tego modelu. Obsługuje: "dml", "cuda", "qnn", "cpu", "webgpu".
  Jeśli nie zostanie określone, użyj ustawień z genai_config.json.

Odpowiedź:

• 200 OK
  Pusta treść odpowiedzi

Przykład:

Żądanie URI

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

GET /openai/unload/{name}

Zwalnianie modelu z pamięci.

Parametry identyfikatora URI:

• name (ciąg)
  Nazwa modelu do zwolnienia.

Parametry zapytania:

• force (wartość logiczna, opcjonalnie)
  Jeśli trueprogram ignoruje ustawienia czasu wygaśnięcia i zwalnia natychmiast.

Odpowiedź:

• 200 OK
  Pusta treść odpowiedzi

Przykład:

Żądanie URI

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

GET /openai/unloadall

Zwalnia wszystkie modele z pamięci.

Odpowiedź:

• 200 OK
  Pusta treść odpowiedzi

GET /openai/loadedmodels

Pobierz listę aktualnie załadowanych modeli.

Odpowiedź:

• 200 OK
  Tablica nazw modeli jako ciągi znaków.

Przykład:

Ciało odpowiedzi

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

GET /openai/getgpudevice

Pobierz bieżący identyfikator urządzenia z procesorem GPU.

Odpowiedź:

• 200 OK
  Liczba całkowita reprezentująca bieżący identyfikator urządzenia gpu.

GET /openai/setgpudevice/{deviceId}

Ustaw aktywne urządzenie GPU.

Parametry identyfikatora URI:

• deviceId (liczba całkowita)
  Identyfikator urządzenia z procesorem GPU do użycia.

Odpowiedź:

• 200 OK
  Pusta treść odpowiedzi

Przykład:

• Żądanie URI

  GET /openai/setgpudevice/1
  

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

Zlicza tokeny dla danego żądania ukończenia czatu bez wnioskowania.

Treść żądania :

• Typ zawartości: application/json
• Obiekt JSON w formacie ChatCompletionCreateRequest z:
  • model (ciąg)
    Model do użycia na potrzeby tokenizacji.
  • messages (tablica)
    Tablica obiektów wiadomości z elementami role i content.

Treść odpowiedzi:

• Typ zawartości: application/json
• Obiekt JSON z liczbą tokenów:
  • tokenCount (liczba całkowita)
    Liczba tokenów w żądaniu.

Przykład:

Ciało żądania

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

Ciało odpowiedzi

  {
    "tokenCount": 23
  }