Foundry Lokale REST-API-Referenz

2025-06-16

Von Bedeutung

Foundry Local ist in der Vorschau verfügbar. Öffentliche Vorschauversionen bieten frühzeitigen Zugriff auf Features, die sich in der aktiven Bereitstellung befinden.
Features, Ansätze und Prozesse können sich vor der allgemeinen Verfügbarkeit (General Availability, GA) noch ändern oder eine eingeschränkte Funktionalität aufweisen.

Vorsicht

Diese API befindet sich in der aktiven Entwicklung und kann unterbrechungslose Änderungen enthalten. Sie sollten sich das Änderungsprotokoll unbedingt ansehen, bevor Sie Produktionsanwendungen erstellen.

OpenAI v1-Kompatibilität

POST /v1/chat/completions

Dieser Endpunkt verarbeitet Chatabschlussanforderungen.
Vollständig kompatibel mit der OpenAI-Chat-Abschluss-API

Anforderungstext:

---Standard OpenAI-Eigenschaften---

model (Zeichenfolge)
Das spezifische Modell, das für die Vervollständigung verwendet werden soll.
messages (Array)
Der Konversationsverlauf als Liste von Nachrichten.
- Jede Nachricht erfordert Folgendes:
  - role (Zeichenfolge)
    Die Rolle des Absenders der Nachricht. Muss system, user oder assistant sein.
  - content (Zeichenfolge)
    Der eigentliche Nachrichtentext.
temperature (Zahl, optional)
Steuert die Zufälligkeit, im Bereich von 0 bis 2. Höhere Werte (0,8) erzeugen unterschiedliche Ausgaben, während niedrigere Werte (0,2) fokussierte, konsistente Ausgaben erzeugen.
top_p (Zahl, optional)
Steuert die Tokenauswahlvielfalt von 0 bis 1. Ein Wert von 0,1 bedeutet, dass nur die Token mit der höchsten Wahrscheinlichkeit von 10 % berücksichtigt werden.
n (ganze Zahl, optional)
Anzahl der alternativen Vervollständigungen, die für jede Eingabenachricht generiert werden sollen.
stream (boolescher Wert, optional)
Wenn wahr, sendet Teilnachrichtenantworten als servergesendete Ereignisse, die mit einer data: [DONE] Nachricht enden.
stop (Zeichenfolge oder Array, optional)
Bis zu 4 Sequenzen, die dazu führen, dass das Modell das Generieren weiterer Token beendet.
max_tokens (ganze Zahl, optional)
Maximale Anzahl der zu generierenden Token. Verwenden Sie max_completion_tokens stattdessen für neuere Modelle.
max_completion_token (ganze Zahl, optional)
Maximaler Tokengrenzwert für die Generierung, einschließlich sichtbarer Ausgabe- und Schlussfolgerungs-Token.
presence_penalty (Zahl, optional)
Wert zwischen -2,0 und 2,0. Positive Werte ermutigen das Modell, neue Themen zu diskutieren, indem Token bestraft werden, die bereits erschienen sind.
frequency_penalty (Zahl, optional)
Wert zwischen -2,0 und 2,0. Positive Werte verhindern Wiederholungen, indem Token basierend auf ihrer Häufigkeit im Text bestraft werden.
logit_bias (Zuordnung, optional)
Passt die Wahrscheinlichkeit an, dass bestimmte Token in der Vervollständigung auftauchen.
user (Zeichenfolge, optional)
Ein eindeutiger Bezeichner für Ihren Endbenutzer, der bei der Überwachung und Missbrauchsprävention hilft.
functions (Array, optional)
Verfügbare Funktionen, für die das Modell JSON-Eingaben generieren kann.
- Jede Funktion muss Folgendes enthalten:
  - name (Zeichenfolge)
    Funktionsname.
  - description (Zeichenfolge)
    Funktionsbeschreibung.
  - parameters (Objekt)
    Funktionsparameter, die als JSON-Schemaobjekt beschrieben werden.
function_call (Zeichenfolge oder Objekt, optional)
Steuert, wie das Modell auf Funktionsaufrufe reagiert.
- Wenn dieser Wert ein Objekt ist, kann er Folgendes umfassen:
  - name (Zeichenfolge, optional)
    Der Name der aufzurufenden Funktion.
  - arguments (Objekt, optional)
    Die Argumente, die an die Funktion übergeben werden sollen.
metadata (Objekt, optional)
Ein Wörterbuch mit Metadatenschlüssel-Wert-Paaren.
top_k (Zahl, optional)
Die Anzahl der Token mit der höchsten Wahrscheinlichkeit im Vokabular, die bei der Top-k-Filterung beibehalten werden.
random_seed (ganze Zahl, optional)
Seed für reproduzierbare Zufallszahlengenerierung.
ep (Zeichenfolge, optional)
Überschreiben Sie den Anbieter für ONNX-Modelle. Unterstützt: "dml", "cuda", "qnn", "cpu", "webgpu".
ttl (ganze Zahl, optional)
Gültigkeitsdauer für das Modell im Arbeitsspeicher in Sekunden.
tools (Objekt, optional)
Für die Anforderung berechnete Tools.

Antworttext:

id (Zeichenfolge)
Eindeutiger Bezeichner für den Chatabschluss.
object (Zeichenfolge)
Der Objekttyp, immer "chat.completion".
created (ganze Zahl)
Zeitstempel der Erstellung in Epochensekunden.
model (Zeichenfolge)
Das für die Vervollständigung verwendete Modell
choices (Array)
Liste der Abschlussoptionen, die jeweils Folgendes enthalten:
- index (ganze Zahl)
  Der Index dieser Auswahl.
- message (Objekt)
  Die generierte Nachricht mit:
  - role (Zeichenfolge)
    Für Antworten immer "assistant".
  - content (Zeichenfolge)
    Der tatsächlich generierte Text.
- finish_reason (Zeichenfolge)
  Warum die Erzeugung gestoppt wurde (z. B. "stop", "length", "function_call").
usage (Objekt)
Tokenverwendungsstatistiken:
- prompt_tokens (ganze Zahl)
  Token im Prompt.
- completion_tokens (ganze Zahl)
  Token im Abschluss.
- total_tokens (ganze Zahl)
  Gesamtanzahl der verwendeten Tokens.

Beispiel:

Anforderungstext

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

Antworttext

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

Verarbeitet Einbettungsgenerierungsanforderungen.
Kompatibel mit der OpenAI Embeddings-API

Anforderungstext:

model (Zeichenfolge)
Das zu verwendende Einbettungsmodell (z. B. "text-embedding-ada-002").
input (Zeichenfolge oder Array)
Eingabetext zum Einbetten. Dies kann eine einzelne Zeichenfolge oder ein Array von Zeichenfolgen/Token sein.
encoding_format (Zeichenfolge, optional)
Das Codierungsformat ("base64" oder "float").

Antworttext:

object (Zeichenfolge)
Immer "list".
data (Array)
Liste der Einbettungsobjekte, die jeweils Folgendes enthalten:
- object (Zeichenfolge)
  Immer "embedding".
- embedding (Array)
  Die Vektordarstellung des Eingabetexts.
- index (ganze Zahl)
  Die Position dieser Einbettung in das Eingabearray.
model (Zeichenfolge)
Das Modell, das für die Einbettungsgenerierung verwendet wird.
usage (Objekt)
Tokenverwendungsstatistiken:
- prompt_tokens (ganze Zahl)
  Anzahl der Token im Prompt.
- total_tokens (ganze Zahl)
  Gesamtanzahl der verwendeten Tokens.

Beispiel:

Anforderungstext

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

Antworttext

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

Benutzerdefinierte API

GET /foundry/list

Ruft eine Liste aller verfügbaren lokalen Foundry-Modelle im Katalog ab.

Antwort:

models (Array)
Liste der Modellobjekte, die jeweils Folgendes enthalten:
- name: Der eindeutige Bezeichner für das Modell.
- displayName: Ein lesbarer Name für das Modell, häufig identisch mit dem Namen.
- providerType: Der Typ des Anbieters, der das Modell hosten (z. B. AzureFoundry).
- uri: Die Ressourcen-URI, die auf den Speicherort des Modells im Verzeichnis verweist.
- version: Die Versionsnummer des Modells.
- modelType: Das Format oder der Typ des Modells (z. B. ONNX).
- promptTemplate:
  - assistant: Die Vorlage für die Antwort des Assistenten.
  - prompt: Die Vorlage für die Benutzer-Assistent-Interaktion.
- publisher: Die Entität oder Organisation, die das Modell veröffentlicht hat.
- task: Die primäre Aufgabe, die das Modell ausführen soll (z. B. Chatabschluss).
- runtime:
  - deviceType: Der Typ der Hardware, auf der das Modell ausgeführt werden soll (z. B. CPU).
  - executionProvider: Der Ausführungsanbieter, der für die Ausführung des Modells verwendet wird.
- fileSizeMb: Die Größe der Modelldatei in Megabyte.
- modelSettings:
  - parameters: Eine Liste konfigurierbarer Parameter für das Modell.
- alias: Ein alternativer Name oder eine Kurzform für das Modell
- supportsToolCalling: Gibt an, ob das Modell Funktionen zum Aufrufen von Tools unterstützt.
- license: Der Lizenztyp, unter dem das Modell verteilt wird.
- licenseDescription: Eine detaillierte Beschreibung oder ein Link zu den Lizenzbedingungen.
- parentModelUri: Der URI des übergeordneten Modells, von dem dieses Modell abgeleitet wird.

POST /openai/register

Registriert einen externen Modellanbieter für die Verwendung mit Foundry Local.

Anforderungstext:

TypeName (Zeichenfolge)
Anbietername (z. B. "deepseek")
ModelName (Zeichenfolge)
Modellname für die Registrierung (z. B. "deepseek-chat")
BaseUri (Zeichenfolge)
Der OpenAI-kompatible Basis-URI für den Anbieter

Antwort:

200 OK (Anforderung erfolgreich)
Leerer Antwortkörper

Beispiel:

Anforderungstext

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

GET /openai/models

Ruft alle verfügbaren Modelle ab, einschließlich lokaler Modelle und registrierter externer Modelle.

Antwort:

200 OK (Anforderung erfolgreich)
Ein Zeichenfolgenarray von Modellnamen.

Beispiel:

Antworttext

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

GET /openai/load/{name}

Lädt ein Modell in den Arbeitsspeicher, um eine schnellere Ableitung zu ermöglichen.

URI-Parameter:

name (Zeichenfolge)
Der zu ladende Modellname.

Abfrageparameter:

unload (boolescher Wert, optional)
Gibt an, ob das Modell nach Leerlaufzeit automatisch entladen werden soll. Wird standardmäßig auf true festgelegt.
ttl (ganze Zahl, optional)
Gültigkeitsdauer in Sekunden. Wenn größer als 0, überschreibt den Parameter unload.
ep (Zeichenfolge, optional)
Ausführungsanbieter für dieses Modell. Unterstützt: "dml", "cuda", "qnn", "cpu", "webgpu".
Wenn nicht angegeben, werden die Einstellungen von genai_config.json verwendet.

Antwort:

200 OK (Anforderung erfolgreich)
Leerer Antwortkörper

Beispiel:

Anforderungs-URI

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

GET /openai/unload/{name}

Entlädt ein Modell aus dem Speicher.

URI-Parameter:

name (Zeichenfolge)
Der Name des zu entfernenden Modells.

Abfrageparameter:

force (boolescher Wert, optional)
Wenn dieser Wert true ist, werden TTL-Einstellungen ignoriert und die Entfernung sofort durchgeführt.

Antwort:

200 OK (Anforderung erfolgreich)
Leerer Antwortkörper

Beispiel:

Anforderungs-URI

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

GET /openai/unloadall

Entlädt alle Modelle aus dem Arbeitsspeicher.

Antwort:

200 OK (Anforderung erfolgreich)
Leerer Antwortkörper

GET /openai/loadedmodels

Ruft eine Liste der derzeit geladenen Modelle ab.

Antwort:

200 OK (Anforderung erfolgreich)
Ein Zeichenfolgenarray von Modellnamen.

Beispiel:

Antworttext

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

GET /openai/getgpudevice

Ruft die aktuell ausgewählte GPU-Geräte-ID ab.

Antwort:

200 OK (Anforderung erfolgreich)
Eine ganze Zahl, die die aktuelle GPU-Geräte-ID darstellt.

GET /openai/setgpudevice/{deviceId}

Legt das aktive GPU-Gerät fest.

URI-Parameter:

deviceId (ganze Zahl)
Die zu verwendende GPU-Geräte-ID.

Antwort:

200 OK (Anforderung erfolgreich)
Leerer Antwortkörper

Beispiel:

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

POST /openai/download

Lädt ein Modell in den lokalen Speicher herunter.

Hinweis

Modelldownloads können erhebliche Zeit in Anspruch nehmen, insbesondere für große Modelle. Es wird empfohlen, einen hohen Timeout für diese Anforderung festzulegen, um vorzeitige Kündigungen zu vermeiden.

Anforderungstext:

model (WorkspaceInferenceModel Objekt)
- Uri (Zeichenfolge)
  Der Modell-URI, der heruntergeladen werden soll.
- Name (Zeichenfolge) Der Modellname.
- ProviderType (Zeichenfolge, optional)
  Der Anbietertyp (z. B. "AzureFoundryLocal","HuggingFace").
- Path (Zeichenfolge, optional)
  Der Remotepfad, in dem das Modell gespeichert ist. In einem Repository "Hugging Face" wäre dies beispielsweise der Pfad zu den Modelldateien.
- PromptTemplate (Dictionary<string, string>, fakultativ)
  Enthält:
  - system (Zeichenfolge, optional)
    Die Vorlage für die Systemmeldung.
  - user (Zeichenfolge, optional) Die Vorlage für die Nachricht des Benutzers.
  - assistant (Zeichenfolge, optional)
    Die Vorlage für die Antwort des Assistenten.
  - prompt (Zeichenfolge, optional)
    Die Vorlage für die Benutzer-Assistent-Interaktion.
- Publisher (Zeichenfolge, optional)
  Der Herausgeber des Modells.
token (Zeichenfolge, optional)
Authentifizierungstoken für geschützte Modelle (GitHub oder Hugging Face).
progressToken (Objekt, optional)
Nur für AITK. Token zum Nachverfolgen des Downloadfortschritts.
customDirPath (Zeichenfolge, optional)
Benutzerdefiniertes Downloadverzeichnis (für CLI verwendet, für AITK nicht erforderlich).
bufferSize (ganze Zahl, optional)
GRÖßE des HTTP-Downloadpuffers in KB. Keine Auswirkung auf NIM- oder Azure Foundry-Modelle.
ignorePipeReport (boolescher Wert, optional)
Wenn dieser Wert true ist, wird die Statusberichterstattung über HTTP-Datenstrom anstelle von Pipe erzwungen. Für AITK standardmäßig false und für Foundry Local true.

Streamingantwort:

Während des Downloads streamt der Server Statusaktualisierungen im Format:

("file name", percentage_complete)

Endgültiger Antworttext:

Success (boolesch)
Ob der Download erfolgreich abgeschlossen wurde.
ErrorMessage (Zeichenfolge, optional)
Fehlerdetails, wenn der Download fehlgeschlagen ist.

Beispiel:

Anfragekörper

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

Antwortstrom

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

Endgültige Antwort

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

GET /openai/status

Ruft Serverstatusinformationen ab.

Antworttext:

Endpoints (Array von Zeichenfolgen)
Die Bindungsendpunkte des HTTP-Servers.
ModelDirPath (Zeichenfolge)
Verzeichnis, in dem lokale Modelle gespeichert werden.
PipeName (Zeichenfolge)
Der aktuelle Name des NamedPipe-Servers.

Beispiel:

Antworttext

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

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

Zählt Token für eine bestimmte Chat-Abschlussanforderung ohne Ableitung.

Anforderungstext:

Content-Type: application/json
JSON-Objekt im ChatCompletionCreateRequest Format mit:
- model (Zeichenfolge)
  Modell, das für die Tokenisierung verwendet werden soll.
- messages (Array)
  Array von Nachrichtenobjekten mit role und content.

Antworttext:

Content-Type: application/json
JSON-Objekt mit Tokenanzahl:
- tokenCount (ganze Zahl)
  Anzahl der Token in der Anforderung.

Beispiel:

Anforderungstext

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

Antworttext
```
{
  "tokenCount": 23
}
```

Freigeben über

Foundry Lokale REST-API-Referenz

OpenAI v1-Kompatibilität

POST /v1/chat/completions

POST /v1/embeddings

Benutzerdefinierte 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

Zusätzliche Ressourcen