Referentie voor de Foundry Local REST API

2025-06-10

Belangrijk

Foundry Local is beschikbaar in preview. Openbare preview-versies bieden vroege toegang tot functies die actief zijn geïmplementeerd.
Functies, benaderingen en processen kunnen worden gewijzigd of beperkte mogelijkheden hebben, voordat algemene beschikbaarheid (GA) wordt uitgevoerd.

Waarschuwing

Deze API wordt actief ontwikkeld en kan belangrijke wijzigingen bevatten zonder kennisgeving. We raden u ten zeerste aan om het wijzigingenlogboek te controleren voordat u productietoepassingen bouwt.

OpenAI v1-compatibiliteit

POST /v1/chat/voltooiingen

Dit eindpunt verwerkt aanvragen voor chatvoltooiing.
Volledig compatibel met de OpenAI Chat Completions-API

Inhoud van het verzoek:

---Standard OpenAI-eigenschappen---

model (tekenreeks)
Het specifieke model dat moet worden gebruikt voor voltooiing.
messages (array)
De gespreksgeschiedenis als een lijst met berichten.
- Voor elk bericht is het volgende vereist:
  - role (tekenreeks)
    De rol van de afzender van het bericht. Moet zijn system, userof assistant.
  - content (tekenreeks)
    De werkelijke berichttekst.
temperature (getal, optioneel)
Bepaalt willekeurigheid, variërend van 0 tot 2. Hogere waarden (0,8) maken gevarieerde uitvoer, terwijl lagere waarden (0.2) gerichte, consistente uitvoer maken.
top_p (getal, optioneel)
Hiermee bepaalt u de diversiteit van tokenselectie van 0 tot en met 1. Een waarde van 0,1 betekent dat alleen de tokens in de top 10% kans worden overwogen.
n (geheel getal, optioneel)
Aantal alternatieve voltooiingen dat moet worden gegenereerd voor elk invoerbericht.
stream (Booleaanse waarde, optioneel)
Wanneer waar, worden gedeeltelijke berichtreacties verzonden als door de server verzonden gebeurtenissen verzonden, eindigend op een data: [DONE] bericht.
stop (tekenreeks of matrix, optioneel)
Maximaal vier reeksen waardoor het model stopt met het genereren van verdere tokens.
max_tokens (geheel getal, optioneel)
Maximaal aantal tokens dat moet worden gegenereerd. Gebruik in plaats daarvan voor nieuwere modellen max_completion_tokens .
max_completion_token (geheel getal, optioneel)
Maximale tokenlimiet voor het genereren, inclusief zowel zichtbare uitvoer als redeneringstokens.
presence_penalty (getal, optioneel)
Waarde tussen -2.0 en 2.0. Positieve waarden stimuleren het model om nieuwe onderwerpen te bespreken door tokens te bestraffen die al zijn verschenen.
frequency_penalty (getal, optioneel)
Waarde tussen -2.0 en 2.0. Positieve waarden ontmoedigen herhaling door tokens te straffen op basis van hun frequentie in de tekst.
logit_bias (kaart, optioneel)
Hiermee past u de kans aan dat specifieke tokens verschijnen in de voltooiing.
user (tekenreeks, optioneel)
Een unieke id voor uw eindgebruiker die helpt bij het bewaken en voorkomen van misbruik.
functions (array, optioneel)
Beschikbare functies waarvoor het model JSON-invoer kan genereren.
- Elke functie moet het volgende bevatten:
  - name (tekenreeks)
    Functienaam.
  - description (tekenreeks)
    Functiebeschrijving.
  - parameters (object)
    Functieparameters die worden beschreven als een JSON-schemaobject.
function_call (tekenreeks ofwel object, optioneel)
Hiermee bepaalt u hoe het model reageert op functie-aanroepen.
- Indien van toepassing kan het object het volgende bevatten:
  - name (tekenreeks, optioneel)
    De naam van de functie die moet worden aangeroepen.
  - arguments (object, optioneel)
    De argumenten die moeten worden doorgegeven aan de functie.
metadata (object, optioneel)
Een woordenlijst met sleutel-waardeparen voor metagegevens.
top_k (getal, optioneel)
Het aantal hoogst waarschijnlijkheidstokens dat moet worden bewaard voor top-k-filtering.
random_seed (geheel getal, optioneel)
Seed voor het genereren van reproduceerbare willekeurige getallen.
ep (tekenreeks, optioneel)
Overschrijf de provider voor ONNX-modellen. Ondersteunt: "dml", "cuda", "qnn", , "cpu". "webgpu"
ttl (geheel getal, optioneel)
De levensduur in seconden van het model in het geheugen.
tools (object, optioneel)
Hulpprogramma's die voor de aanvraag zijn berekend.

Hoofdtekst van antwoord:

id (tekenreeks)
Unieke id voor het voltooien van de chat.
object (tekenreeks)
Het objecttype, altijd "chat.completion".
created (geheel getal)
Tijdstempel van creatie in epoch-seconden.
model (tekenreeks)
Het model dat wordt gebruikt voor voltooiing.
choices (array)
Lijst met voltooiingskeuzen, elk met:
- index (geheel getal)
  De index van deze keuze.
- message (object)
  Het gegenereerde bericht met:
  - role (tekenreeks)
    Altijd "assistant" voor antwoorden.
  - content (tekenreeks)
    De werkelijke gegenereerde tekst.
- finish_reason (tekenreeks)
  Waarom de generatie is gestopt (bijvoorbeeld "stop", "length", "function_call").
usage (object)
Gebruiksstatistieken van tokens:
- prompt_tokens (geheel getal)
  Token in de prompt.
- completion_tokens (geheel getal)
  Tokens bij de afronding.
- total_tokens (geheel getal)
  Totaal aantal gebruikte tokens.

Voorbeeld:

Aanvraaginhoud

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

Hoofdtekst van antwoord

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

Behandelt aanvragen voor het genereren van embeddings.
Compatibel met de OpenAI Embeddings-API

Inhoud van het verzoek:

model (tekenreeks)
Het insluitmodel dat moet worden gebruikt (bijvoorbeeld "text-embedding-ada-002").
input (string of array)
Invoertekst om in te sluiten. Kan één tekenreeks of een matrix met tekenreeksen/tokens zijn.
encoding_format (tekenreeks, optioneel)
De coderingsindeling ("base64" of "float").

Hoofdtekst van antwoord:

object (tekenreeks)
Altijd "list".
data (array)
Lijst met insluitobjecten, elk met:
- object (tekenreeks)
  Altijd "embedding".
- embedding (array)
  De vectorweergave van de invoertekst.
- index (geheel getal)
  De positie van deze insluiting in de invoermatrix.
model (tekenreeks)
Het model dat wordt gebruikt voor embedgeneratie.
usage (object)
Gebruiksstatistieken van tokens:
- prompt_tokens (geheel getal)
  Aantal tokens in de prompt.
- total_tokens (geheel getal)
  Totaal aantal gebruikte tokens.

Voorbeeld:

Aanvraaginhoud

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

Hoofdtekst van antwoord

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

Aangepaste API

GET /foundry/list

Hiermee haalt u een lijst op met alle beschikbare Lokale modellen van Foundry in de catalogus.

Antwoord:

models (array)
Lijst met modelobjecten, elk met:
- name: de unieke id voor het model.
- displayName: Een door mensen leesbare naam voor het model, vaak hetzelfde als de naam.
- providerType: Het type provider dat als host fungeert voor het model (bijvoorbeeld AzureFoundry).
- uri: De resource-URI die verwijst naar de locatie van het model in het register.
- version: het versienummer van het model.
- modelType: De indeling of het type van het model (bijvoorbeeld ONNX).
- promptTemplate:
  - assistant: De sjabloon voor het antwoord van de assistent.
  - prompt: De sjabloon voor de interactie met de gebruikersassistent.
- publisher: de entiteit of organisatie die het model heeft gepubliceerd.
- task: De primaire taak waarvoor het model is ontworpen (bijvoorbeeld het voltooien van een chat).
- runtime:
  - deviceType: Het type hardware waarop het model wordt uitgevoerd (bijvoorbeeld CPU).
  - executionProvider: De uitvoeringsprovider die wordt gebruikt voor het uitvoeren van het model.
- fileSizeMb: De grootte van het modelbestand in megabytes.
- modelSettings:
  - parameters: Een lijst met configureerbare parameters voor het model.
- alias: Een alternatieve naam of afkorting voor het model
- supportsToolCalling: Geeft aan of het model functionaliteit voor het aanroepen van hulpprogramma's ondersteunt.
- license: het licentietype waaronder het model wordt gedistribueerd.
- licenseDescription: Een gedetailleerde beschrijving of koppeling naar de licentievoorwaarden.
- parentModelUri: De URI van het bovenliggende model waaruit dit model is afgeleid.

POST /openai/register

Registreert een externe modelprovider voor gebruik met Foundry Local.

Inhoud van het verzoek:

TypeName (tekenreeks)
Providernaam (bijvoorbeeld "deepseek")
ModelName (tekenreeks)
Modelnaam die moet worden geregistreerd (bijvoorbeeld "deepseek-chat")
BaseUri (tekenreeks)
De openAI-compatibele basis-URI voor de provider

Antwoord:

200 OK
Lege hoofdtekst van antwoord

Voorbeeld:

Aanvraaginhoud

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

GET /openai/models

Hiermee worden alle beschikbare modellen opgehaald, waaronder zowel lokale modellen als geregistreerde externe modellen.

Antwoord:

200 OK
Een matrix met modelnamen als tekenreeksen.

Voorbeeld:

Hoofdtekst van antwoord

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

GET /openai/load/{name}

Laadt een model in het geheugen voor snellere deductie.

URI-parameters:

name (tekenreeks)
De modelnaam die moet worden geladen.

Queryparameters:

unload (Booleaanse waarde, optioneel)
Of het model automatisch moet worden ontladen na een periode van inactiviteit. Standaardwaarde is true.
ttl (geheel getal, optioneel)
Levensduur in seconden. Als groter dan 0, overschrijft de unload parameter.
ep (tekenreeks, optioneel)
Uitvoeringsprovider om dit model uit te voeren. Ondersteunt: "dml", "cuda", "qnn", , "cpu". "webgpu"
Als dit niet is opgegeven, gebruikt u instellingen van genai_config.json.

Antwoord:

200 OK
Lege hoofdtekst van antwoord

Voorbeeld:

Aanvraag-URI

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

GET /openai/unload/{name}

Laadt een model uit het geheugen.

URI-parameters:

name (tekenreeks)
De naam van het model dat moet worden uitgeladen.

Queryparameters:

force (Booleaanse waarde, optioneel)
Als true, worden de TTL-instellingen genegeerd en direct uitgeladen.

Antwoord:

200 OK
Lege hoofdtekst van antwoord

Voorbeeld:

Aanvraag-URI

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

GET /openai/unloadall

Alle modellen worden uit het geheugen verwijderd.

Antwoord:

200 OK
Lege hoofdtekst van antwoord

GET /openai/loadedmodels

Hiermee wordt een lijst met momenteel geladen modellen opgehaald.

Antwoord:

200 OK
Een matrix met modelnamen als tekenreeksen.

Voorbeeld:

Hoofdtekst van antwoord

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

GET /openai/getgpudevice

Hiermee haalt u de geselecteerde GPU-apparaat-id op.

Antwoord:

200 OK
Een geheel getal dat de huidige GPU-apparaat-id vertegenwoordigt.

GET /openai/setgpudevice/{deviceId}

Hiermee stelt u het actieve GPU-apparaat in.

URI-parameters:

deviceId (geheel getal)
De GPU-apparaat-id die moet worden gebruikt.

Antwoord:

200 OK
Lege hoofdtekst van antwoord

Voorbeeld:

Aanvraag-URI
```
GET /openai/setgpudevice/1
```

POST /openai/download

Hiermee downloadt u een model naar lokale opslag.

Opmerking

Het downloaden van modellen kan veel tijd in beslag nemen, met name voor grote modellen. We raden u aan een hoge time-out in te stellen voor deze aanvraag om voortijdige beëindiging te voorkomen.

Inhoud van het verzoek:

model (WorkspaceInferenceModel object)
- Uri (tekenreeks)
  De model-URI die moet worden gedownload.
- Name (tekenreeks) De modelnaam.
- ProviderType (tekenreeks, optioneel)
  Het providertype (bijvoorbeeld "AzureFoundryLocal","HuggingFace").
- Path (tekenreeks, optioneel)
  Het externe pad waar het model is opgeslagen. In een Hugging Face-opslagplaats is dit bijvoorbeeld het pad naar de modelbestanden.
- PromptTemplate (Dictionary<string, string>, optioneel)
  Bevat:
  - system (tekenreeks, optioneel)
    De sjabloon voor het systeembericht.
  - user (tekenreeks, optioneel) De sjabloon voor het bericht van de gebruiker.
  - assistant (tekenreeks, optioneel)
    De sjabloon voor het antwoord van de assistent.
  - prompt (tekenreeks, optioneel)
    De sjabloon voor de interactie tussen gebruikersassistenten.
- Publisher (tekenreeks, optioneel)
  De uitgever van het model.
token (tekenreeks, optioneel)
Verificatietoken voor beveiligde modellen (GitHub of Hugging Face).
progressToken (object, optioneel)
Alleen voor AITK. Token om de voortgang van het downloaden bij te houden.
customDirPath (tekenreeks, optioneel)
Aangepaste downloadmap (gebruikt voor CLI, niet nodig voor AITK).
bufferSize (geheel getal, optioneel)
HTTP-downloadbuffergrootte in KB. Geen effect op NIM- of Azure Foundry-modellen.
ignorePipeReport (Booleaanse waarde, optioneel)
Als true, wordt voortgangsrapportage afgedwongen via een HTTP-stream in plaats van via een pipe. De standaardinstelling is false voor AITK en true voor Foundry Local.

Streaming-antwoord:

Tijdens het downloaden streamt de server voortgangsupdates in een bepaald formaat.

("file name", percentage_complete)

Hoofdtekst van laatste antwoord:

Success (booleaanse waarde)
Of het downloaden is voltooid.
ErrorMessage (tekenreeks, optioneel)
Foutdetails wanneer het downloaden is mislukt.

Voorbeeld:

Inhoud van het verzoek

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

Antwoordstroom

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

Laatste antwoord

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

GET /openai/status

Hiermee haalt u informatie over de serverstatus op.

Hoofdtekst van antwoord:

Endpoints (matrix met tekenreeksen)
De bindingseindpunten van de HTTP-server.
ModelDirPath (tekenreeks)
Map waarin lokale modellen zijn opgeslagen.
PipeName (tekenreeks)
De naam van de huidige NamedPipe-server.

Voorbeeld:

Hoofdtekst van antwoord

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

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

Telt tokens voor een bepaalde chat-voltooiingsaanvraag zonder inferentie uit te voeren.

Inhoud van het verzoek:

Inhoudstype: toepassing/json
JSON-object in ChatCompletionCreateRequest indeling met:
- model (tekenreeks)
  Model dat moet worden gebruikt voor tokenisatie.
- messages (array)
  Matrix van berichtobjecten met role en content.

Hoofdtekst van antwoord:

Inhoudstype: toepassing/json
JSON-object met tokenaantal:
- tokenCount (geheel getal)
  Aantal tokens in de aanvraag.

Voorbeeld:

Aanvraaginhoud

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

Hoofdtekst van antwoord
```
{
  "tokenCount": 23
}
```

Delen via

Referentie voor de Foundry Local REST API

OpenAI v1-compatibiliteit

POST /v1/chat/voltooiingen

POST /v1/embeddings

Aangepaste API

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

Feedback

Aanvullende resources