Condividi tramite

Informazioni di riferimento sulle API REST locali di Foundry

Importante

  • Foundry Local è disponibile in anteprima. Le versioni di anteprima pubblica consentono l'accesso anticipato alle funzionalità in fase di distribuzione attiva.
  • Funzionalità, approcci e processi possono subire variazioni o avere funzionalità limitate, prima della disponibilità generale (GA).

Attenzione

Questa API fa riferimento all'API REST disponibile nell'interfaccia della riga di comando locale di Foundry. Questa API è in fase di sviluppo attivo e può includere modifiche di rilievo senza preavviso. È consigliabile monitorare il log delle modifiche prima di compilare applicazioni di produzione.

POST /v1/chat/completions

Questo endpoint elabora le richieste di completamento della chat.
È completamente compatibile con l'API OpenAI Chat Completions.

Corpo della richiesta:

---Proprietà OpenAI standard---

  • model (stringa)
    Modello specifico da usare per il completamento.
  • messages (matrice)
    Cronologia delle conversazioni come elenco di messaggi.
    • Ogni messaggio richiede:
      • role (stringa)
        Ruolo del mittente del messaggio. Deve essere system, usero assistant.
      • content (stringa)
        Testo effettivo del messaggio.
  • temperature (numero, facoltativo)
    Controlla la casualità, compreso tra 0 e 2. I valori più alti (0,8) creano output diversi, mentre i valori inferiori (0,2) creano output mirati e coerenti.
  • top_p (numero, facoltativo)
    Controlla la diversità di selezione dei token da 0 a 1. Un valore pari a 0,1 indica che vengono considerati solo i token con probabilità più alta tra le prime 10%.
  • n (integer, facoltativo)
    Numero di completamenti alternativi da generare per ogni messaggio di input.
  • stream (booleano, facoltativo)
    Quando è vero, invia risposte parziali ai messaggi come eventi inviati dal server, terminando con un messaggio data: [DONE].
  • stop (stringa o matrice, facoltativo)
    Fino a 4 sequenze che causeranno l'arresto della generazione di altri token da parte del modello.
  • max_tokens (integer, facoltativo)
    Numero massimo di token da generare. Per i modelli più recenti, usare max_completion_tokens invece .
  • max_completion_tokens (integer, facoltativo)
    Numero massimo di token che il modello può generare, inclusi l'output visibile e i token di ragionamento.
  • presence_penalty (numero, facoltativo)
    Valore compreso tra -2.0 e 2.0. I valori positivi incoraggiano il modello a discutere nuovi argomenti penalizzando i token già apparsi.
  • frequency_penalty (numero, facoltativo)
    Valore compreso tra -2.0 e 2.0. I valori positivi scoraggiano la ripetizione penalizzando i token in base alla loro frequenza nel testo.
  • logit_bias (mappa, facoltativo)
    Regola la probabilità di token specifici visualizzati nel completamento.
  • user (stringa, facoltativa)
    Identificatore univoco per l'utente finale che consente di monitorare e prevenire gli abusi.
  • functions (matrice, facoltativo)
    Funzioni disponibili per le quali il modello può generare input JSON.
    • Ogni funzione deve includere:
      • name (stringa)
        Nome della funzione.
      • description (stringa)
        Descrizione della funzione.
      • parameters (oggetto)
        Parametri della funzione descritti come oggetto Schema JSON.
  • function_call (stringa o oggetto, facoltativo)
    Controlla la modalità di risposta del modello alle chiamate di funzione.
    • Se oggetto, può includere:
      • name (stringa, facoltativa)
        Nome della funzione da chiamare.
      • arguments (oggetto, facoltativo)
        Argomenti da passare alla funzione.
  • metadata (oggetto, facoltativo)
    Dizionario di coppie chiave-valore di metadati.
  • top_k (numero, facoltativo)
    Numero di token di vocabolario di probabilità più elevati da mantenere per il filtro top-k.
  • random_seed (integer, facoltativo)
    Seme per la generazione di numeri casuali riproducibili.
  • ep (stringa, facoltativa)
    Sovrascrivi il provider per i modelli ONNX. Supporta: "dml", "cuda", "qnn", "cpu", "webgpu".
  • ttl (integer, facoltativo)
    Tempo di durata in secondi per il modello in memoria.
  • tools (oggetto, facoltativo)
    Strumenti calcolati per la richiesta.

Corpo della risposta:

  • id (stringa)
    Identificatore univoco per il completamento della chat.
  • object (stringa)
    Tipo di oggetto, sempre "chat.completion".
  • created (intero)
    Timestamp di creazione in secondi dell'epoca.
  • model (stringa)
    Modello usato per il completamento.
  • choices (matrice)
    Elenco di scelte di completamento, ognuna contenente:
    • index (intero)
      Indice di questa scelta.
    • message (oggetto)
      Messaggio generato con:
      • role (stringa)
        Sempre "assistant" per le risposte.
      • content (stringa)
        Il testo realmente generato.
    • finish_reason (stringa)
      Perché la generazione si è fermata (ad esempio, "stop", "length", "function_call").
  • usage (oggetto)
    Statistiche sull'utilizzo dei token:
    • prompt_tokens (intero)
      Token nel prompt.
    • completion_tokens (intero)
      Token nel completamento.
    • total_tokens (intero)
      Totale dei token usati.

Esempio:

Testo della richiesta

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

Corpo della risposta

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

Ottenere informazioni sullo stato del server.

Corpo della risposta:

  • Endpoints (matrice di stringhe)
    Endpoint di associazione del server HTTP.
  • ModelDirPath (stringa)
    Directory in cui vengono archiviati i modelli locali.
  • PipeName (stringa)
    Nome corrente del server NamedPipe.

Esempio:

Corpo della risposta

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

GET /foundry/list

Ottieni un elenco dei Foundry modelli locali disponibili nel catalogo.

Risposta:

  • models (matrice)
    Matrice di oggetti modello. Ogni modello include:
    • name: identificatore univoco per il modello.
    • displayName: nome leggibile per il modello, spesso uguale al nome.
    • providerType: tipo di provider che ospita il modello, ad esempio AzureFoundry.
    • uri: URI della risorsa che punta alla posizione del modello nel registro.
    • version: numero di versione del modello.
    • modelType: formato o tipo del modello , ad esempio ONNX.
    • promptTemplate:
      • assistant: modello per la risposta dell'assistente.
      • prompt: modello per l'interazione con l'assistente utente.
    • publisher: entità o organizzazione che ha pubblicato il modello.
    • task: l'attività primaria che il modello è progettato per eseguire (ad esempio, il completamento della chat).
    • runtime:
      • deviceType: il tipo di hardware in cui il modello è progettato per l'esecuzione (ad esempio, CPU).
      • executionProvider: provider di esecuzione usato per l'esecuzione del modello.
    • fileSizeMb: dimensioni del file del modello in megabyte.
    • modelSettings:
      • parameters: elenco di parametri configurabili per il modello.
    • alias: nome alternativo o abbreviato per il modello
    • supportsToolCalling: indica se il modello supporta la funzionalità di chiamata degli strumenti.
    • license: tipo di licenza con cui viene distribuito il modello.
    • licenseDescription: una descrizione dettagliata o un collegamento alle condizioni di licenza.
    • parentModelUri: URI del modello padre da cui deriva questo modello.

GET /openai/models

Ottenere un elenco di modelli memorizzati nella cache, inclusi modelli esterni locali e registrati.

Risposta:

  • 200 Va bene
    Matrice di nomi di modello come stringhe.

Esempio:

Corpo della risposta

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

POST /openai/download

Scaricare un modello dal catalogo all'archiviazione locale.

Annotazioni

I download di modelli di grandi dimensioni possono richiedere molto tempo. Impostare un timeout elevato per questa richiesta per evitare la terminazione anticipata.

Corpo della richiesta:

  • model (WorkspaceInferenceModel oggetto)
    • Uri (stringa)
      URI del modello da scaricare.
    • Name (string) Nome del modello.
    • ProviderType (stringa, facoltativa)
      Tipo di provider , ad esempio "AzureFoundryLocal", "HuggingFace".
    • Path (stringa, facoltativa)
      Percorso remoto dei file del modello. Ad esempio, in un repository Hugging Face, si tratta del percorso dei file del modello.
    • PromptTemplate (Dictionary<string, string>, facoltativo)
      Include:
      • system (stringa, facoltativa)
        Modello per il messaggio di sistema.
      • user (stringa, facoltativa) Modello per il messaggio dell'utente.
      • assistant (stringa, facoltativa)
        Modello per la risposta dell'assistente.
      • prompt (stringa, facoltativa)
        Modello per l'interazione con l'assistente utente.
    • Publisher (stringa, facoltativa)
      Editore del modello.
  • token (stringa, facoltativa)
    Token di autenticazione per i modelli protetti (GitHub o Hugging Face).
  • progressToken (oggetto, facoltativo)
    Solo per AITK. Token per tenere traccia dello stato di avanzamento del download.
  • customDirPath (stringa, facoltativa)
    Directory di download personalizzata (usata per l'interfaccia della riga di comando, non necessaria per AITK).
  • bufferSize (integer, facoltativo)
    Dimensioni del buffer di download HTTP in KB. Nessun effetto sui modelli NIM o Azure Foundry.
  • ignorePipeReport (booleano, facoltativo)
    Se true, impone la segnalazione del progresso tramite flusso HTTP invece di tramite pipe. La configurazione di default è false per AITK e true per Foundry Local.

Risposta in streaming:

Durante il download, il server trasmette gli aggiornamenti dello stato di avanzamento nel formato:

("file name", percentage_complete)

Corpo della risposta finale:

  • Success (booleano)
    Indica se il download è stato completato correttamente.
  • ErrorMessage (stringa, facoltativa)
    Dettagli errore se il download non è riuscito.

Esempio:

URI della richiesta

POST /openai/download

Testo della richiesta

Si noti che il suffisso della versione deve essere specificato nel nome del modello.

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

Flusso di risposta

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

Risposta finale

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

GET /openai/load/{name}

Caricare un modello in memoria per un'inferenza più veloce.

Parametri URI:

  • name (stringa)
    Nome del modello da caricare.

Parametri di query:

  • unload (booleano, facoltativo)
    Indica se scaricare automaticamente il modello dopo il tempo di inattività. Il valore predefinito è true.
  • ttl (integer, facoltativo)
    Durata di vita in secondi. Se è maggiore di 0, questo valore esegue l'override del unload parametro .
  • ep (stringa, facoltativa)
    Fornitore di esecuzione per far funzionare questo modello. Supporta: "dml", "cuda", "qnn", "cpu", "webgpu".
    Se non specificato, usa le impostazioni di genai_config.json.

Risposta:

  • 200 Va bene
    Corpo della risposta vuoto

Esempio:

URI della richiesta

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

GET /openai/unload/{name}

Scaricare un modello dalla memoria.

Parametri URI:

  • name (string) Nome del modello da scaricare.

Parametri di query:

  • force (booleano, facoltativo) Se true, ignora le impostazioni TTL e scarica immediatamente.

Risposta:

  • 200 OK Corpo risposta vuoto

Esempio:

URI della richiesta

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

GET /openai/unloadall

Scarica tutti i modelli dalla memoria.

Risposta:

  • 200 Va bene
    Corpo della risposta vuoto

GET /openai/loadedmodels

Ottenere l'elenco dei modelli attualmente caricati.

Risposta:

  • 200 Va bene
    Matrice di nomi di modello come stringhe.

Esempio:

Corpo della risposta

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

GET /openai/getgpudevice

Ottieni l'ID corrente del dispositivo GPU.

Risposta:

  • 200 Va bene
    Numero intero che rappresenta l'ID del dispositivo GPU corrente.

GET /openai/setgpudevice/{deviceId}

Impostare il dispositivo GPU attivo.

Parametri URI:

  • deviceId (intero)
    ID GPU del dispositivo da usare.

Risposta:

  • 200 Va bene
    Corpo della risposta vuoto

Esempio:

  • URI della richiesta 
    GET /openai/setgpudevice/1

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

Conta i token per una determinata richiesta di completamento della chat senza eseguire l'inferenza.

Corpo della richiesta:

  • Tipo di contenuto: applicazione/json
  • Oggetto JSON nel formato ChatCompletionCreateRequest con:
    • model (stringa)
      Modello da usare per la tokenizzazione.
    • messages (matrice)
      Matrice di oggetti messaggio con role e content.

Corpo della risposta:

  • Tipo di contenuto: applicazione/json
  • Oggetto JSON con numero di token:
    • tokenCount (intero)
      Numero di token nella richiesta.

Esempio:

Testo della richiesta

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

Corpo della risposta

  {
    "tokenCount": 23
  }
  • Last updated on