Informazioni di riferimento sulle API REST locali di Foundry

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.

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
  }