Informazioni di riferimento sulle API REST locali di Foundry

2025-05-20

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 modificare o avere funzionalità limitate, prima della disponibilità generale.

Attenzione

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.

Compatibilità openAI v1

POST /v1/chat/completions

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

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_token (integer, facoltativo)
Limite massimo di token per la generazione, 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 l'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:

Corpo della richiesta

{
  "model": "Phi-4-mini-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": "Phi-4-mini-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
  }
}

POST /v1/embeddings

Gestisce le richieste di generazione di incorporazione.
Compatibile con l'API OpenAI Embeddings

Corpo della richiesta:

model (stringa)
Modello di incorporamento da usare, ad esempio "text-embedding-ada-002".
input (stringa o matrice)
Testo di input da incorporare. Può essere una singola stringa o una matrice di stringhe/token.
encoding_format (stringa, facoltativa)
Formato di codifica ("base64" o "float").

Corpo della risposta:

object (stringa)
Sempre "list".
data (matrice)
Elenco di oggetti di incorporamento, ognuno dei quali contiene:
- object (stringa)
  Sempre "embedding".
- embedding (matrice)
  Rappresentazione vettoriale del testo di input.
- index (intero)
  Posizione di questo incorporamento nella matrice di input.
model (stringa)
Modello utilizzato nella generazione di embedding.
usage (oggetto)
Statistiche sull'utilizzo dei token:
- prompt_tokens (intero)
  Numero di token nel prompt.
- total_tokens (intero)
  Totale dei token usati.

Esempio:

Corpo della richiesta

{
  "model": "qwen_w_embeddings",
  "input": "Hello, how are you?"
}

Corpo della risposta

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.1, 0.2, 0.3, ...],
      "index": 0
    }
  ],
  "model": "qwen_w_embeddings",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}

API personalizzata

GET /foundry/list

Recupera un elenco di tutti i modelli Foundry Local disponibili nel catalogo.

Risposta:

models (matrice)
Elenco di oggetti modello, ognuno contenente:
- 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 l'esecuzione (ad esempio, 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.

POST /openai/register

Registra un provider di modelli esterno per l'uso con Foundry Local.

Corpo della richiesta:

TypeName (stringa)
Nome provider (ad esempio, "deepseek")
ModelName (stringa)
Nome del modello da registrare (ad esempio, "deepseek-chat")
BaseUri (stringa)
URI di base compatibile con OpenAI per il provider

Risposta:

200 Va bene
Corpo della risposta vuoto

Esempio:

Corpo della richiesta

{
  "TypeName": "deepseek",
  "ModelName": "deepseek-chat",
  "BaseUri": "https://api.deepseek.com/v1"
}

GET /openai/models

Recupera tutti i modelli disponibili, inclusi i modelli locali e i modelli esterni 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"]

GET /openai/load/{name}

Carica 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, 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}

Scarica un modello dalla memoria.

Parametri URI:

name (stringa)
Nome del modello da scaricare.

Parametri di query:

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

Risposta:

200 Va bene
Corpo della 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

Recupera un elenco di 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

Recupera l'ID dispositivo GPU attualmente selezionato.

Risposta:

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

GET /openai/setgpudevice/{deviceId}

Imposta 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 /openai/download

Scarica un modello nell'archiviazione locale.

Annotazioni

I download dei modelli possono richiedere molto tempo, soprattutto per i modelli di grandi dimensioni. È consigliabile impostare un timeout elevato per questa richiesta per evitare la chiusura prematura.

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)
  Il percorso remoto in cui è memorizzato il modello. Ad esempio, in un repository Hugging Face, si tratta del percorso dei file del modello.
- PromptTemplate (Dictionary<string, string>, facoltativo)
  Contiene:
  - 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:

Testo della richiesta

{
  "model":{
    "Uri": "azureml://registries/azureml/models/Phi-4-mini-instruct-generic-cpu/versions/4",
    "ProviderType": "AzureFoundryLocal",
    "Name": "Phi-4-mini-instruct-generic-cpu",
    "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/status

Recupera le 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"
}

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:

Corpo 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
}
```

Condividi tramite

Informazioni di riferimento sulle API REST locali di Foundry

Compatibilità openAI v1

POST /v1/chat/completions

POST /v1/embeddings

API personalizzata

GET /foundry/list

POST /openai/register

GET /openai/models

GET /openai/load/{name}

GET /openai/unload/{name}

GET /openai/unloadall

GET /openai/loadedmodels

GET /openai/getgpudevice

GET /openai/setgpudevice/{deviceId}

POST /openai/download

GET /openai/status

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

Commenti e suggerimenti

Risorse aggiuntive