Foundry helyi REST API-referencia

Fontos

• Az Foundry helyi parancssori felület előzetes verzióban érhető el. A nyilvános előzetes verziójú kiadások korai access biztosítanak az aktív üzembe helyezésben lévő funkciók számára.
• A funkciók, a megközelítések és a folyamatok az általános rendelkezésre állás (GA) előtt változhatnak vagy korlátozott képességekkel rendelkezhetnek.

Caution

Ez az API az Foundry helyi parancssori felületén elérhető REST API-ra hivatkozik. Ez az API aktív fejlesztés alatt áll, és előzetes értesítés nélküli kompatibilitástörő módosításokat is tartalmazhat. Javasoljuk, hogy éles alkalmazások létrehozása előtt figyelje a változásnaplót.

POST /v1/chat/completions

Ez a végpont feldolgozza a csevegés befejezésére vonatkozó kéréseket.
Teljes mértékben kompatibilis az OpenAI Chat Completions API-val.

Kérelem Törzse:

---Standard OpenAI-tulajdonságok---

• model (sztring)
  A befejezéshez használni kívánt modell.
• messages (tömb)
  A beszélgetési előzmények az üzenetek listájaként.
  • Minden üzenethez a következőre van szükség:
    • role (sztring)
      Az üzenet feladójának szerepköre. system Kell lennie, user vagy assistant.
    • content (sztring)
      A tényleges üzenet szövege.
• temperature (szám, nem kötelező)
  0 és 2 közötti véletlenszerűséget szabályoz. A magasabb értékek (0,8) változatos kimeneteket hoznak létre, míg az alacsonyabb értékek (0,2) szűrt, konzisztens kimeneteket hoznak létre.
• top_p (szám, nem kötelező)
  A tokenek kiválasztási változatosságát szabályozza 0 és 1 között. A 0,1 érték azt jelenti, hogy csak az első 10% valószínűségben lévő tokeneket veszi figyelembe.
• n (egész szám, nem kötelező)
  Az egyes bemeneti üzenetekhez létrehozandó alternatív kiegészítések száma.
• stream (logikai, nem kötelező)
  Ha igaz, részleges üzenetválaszokat küld kiszolgáló által küldött eseményként, üzenettel data: [DONE] végződve.
• stop (sztring vagy tömb, nem kötelező)
  Legfeljebb 4 szekvencia, amelyek miatt a modell leállítja a tokenek generálását.
• max_tokens (egész szám, nem kötelező)
  A generálható jogkivonatok maximális száma. Az újabb modellekhez használja max_completion_tokens inkább.
• max_completion_tokens (egész szám, nem kötelező)
  A modell által generálható tokenek maximális száma, beleértve a látható kimenetet és az érveléshez kapcsolódó tokeneket.
• presence_penalty (szám, nem kötelező)
  -2.0 és 2.0 közötti érték. A pozitív értékek arra ösztönzik a modellt, hogy új témaköröket tárgyaljon azáltal, hogy megbünteti azokat a tokeneket, amelyek már megjelentek.
• frequency_penalty (szám, nem kötelező)
  -2.0 és 2.0 közötti érték. A pozitív értékek visszatartják az ismétlődést azáltal, hogy a tokeneket a szövegbeni gyakoriságuk alapján büntetik.
• logit_bias (térkép, nem kötelező)
  A befejezés során megjelenő konkrét tokenek valószínűségét állítja be.
• user (sztring, nem kötelező)
  A végfelhasználó egyedi azonosítója, amely segít a monitorozásban és a visszaélések megelőzésében.
• functions (tömb, választható)
  Rendelkezésre álló függvények, amelyekhez a modell JSON-bemeneteket hozhat létre.
  • Minden függvénynek tartalmaznia kell a következőket:
    • name (sztring)
      Függvény neve.
    • description (sztring)
      Függvény leírása.
    • parameters (objektum)
      A JSON-sémaobjektumként leírt függvényparaméterek.
• function_call (sztring vagy objektum, nem kötelező)
  Szabályozza, hogy a modell hogyan reagál a függvényhívásokra.
  • Ha objektum, a következőket tartalmazhatja:
    • name (sztring, nem kötelező)
      A meghívandó függvény neve.
    • arguments (objektum, nem kötelező)
      A függvénynek átadni kívánt argumentumok.
• metadata (objektum, nem kötelező)
  Metaadatkulcs-érték párok szótára.
• top_k (szám, nem kötelező)
  A legnagyobb valószínűségű szókincs tokenek száma, amely a top-k szűréshez megtartandó.
• random_seed (egész szám, nem kötelező)
  A reprodukálható véletlenszerű számgenerálás magja.
• ep (sztring, nem kötelező)
  Írja felül az ONNX-modellek szolgáltatóját. Támogatja: "dml", "cuda", "qnn", "cpu". "webgpu"
• ttl (egész szám, nem kötelező)
  A modell memóriában való élettartama másodpercekben.
• tools (objektum, nem kötelező)
  A kérés alapján számított eszközök.

Válasz törzse:

• id (sztring)
  A csevegés befejezésének egyedi azonosítója.
• object (sztring)
  Az objektum típusa, mindig "chat.completion".
• created (egész szám)
  A létrehozás időbélyege epoch-idő szerint másodpercekben.
• model (sztring)
  A befejezéshez használt modell.
• choices (tömb)
  A befejezési lehetőségek listája, amelyek mindegyike a következőket tartalmazza:
  • index (egész szám)
    A választás indexe.
  • message (objektum)
    A létrehozott üzenet a következőkkel:
    • role (sztring)
      Mindig "assistant" a válaszokért.
    • content (sztring)
      A ténylegesen létrehozott szöveg.
  • finish_reason (sztring)
    Miért állt le a generálás (pl. "stop", "length", "function_call").
• usage (objektum)
  Token használati statisztikák:
  • prompt_tokens (egész szám)
    Tokenek a promptban.
  • completion_tokens (egész szám)
    Jogkivonatok a befejezéskor.
  • total_tokens (egész szám)
    Felhasznált összes token.

Example:

Kérés tartalma

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

Válaszüzenet tartalma

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

POST /v1/audio/átiratok

Ez a végpont szöveggé irányítja át a hangfájlokat. Kompatibilis az OpenAI Audio Transcriptions API-val.

Kérelem formátuma:multipart/form-data

Kérelemmezők:

• file (fájl, kötelező)
  Az átírandó hangfájl. A támogatott formátumok közé tartozik az MP3, a WAV, a FLAC, az OGG és a WebM.
• model (sztring, kötelező)
  Az átíráshoz használandó modellazonosító. Használja a Whisper-modell betöltésekor visszaadott azonosítót (például a betöltés whisper-tinyután).
• language (sztring, nem kötelező)
  A hang nyelve ISO 639-1 formátumban (például "en"). Ennek biztosítása javítja a pontosságot és a sebességet.
• temperature (szám, nem kötelező)
  Mintavételi hőmérséklet 0 és 1 között. Az alacsonyabb értékek determinisztikusabb eredményeket eredményeznek.
• response_format (sztring, nem kötelező)
  A válasz formátuma. Beállítások: json (alapértelmezett), text, verbose_json.

Válasz törzse:

• text (sztring)
  Az átírt szöveg.

Example:

kérelem

curl -X POST http://localhost:<PORT>/v1/audio/transcriptions \
  -F "file=@recording.wav" \
  -F "model=<MODEL_ID>" \
  -F "language=en"

Fontos

Cserélje le <PORT> az Foundry Local szolgáltatás dinamikus portjára és <MODEL_ID> a modell betöltésekor visszaadott modellazonosítóra. Az SDK-ban használja manager.endpoint a (JS) vagy config.Web.Urls a (C#) végpontot – soha ne kódolja a portot.

Válaszüzenet tartalma

{
  "text": "This is the transcribed text from the audio file."
}

Tip

A Whisper-modell elérhető aliasai közé tartoznak a whisper-tinykövetkezők: , whisper-baseés whisper-small. Ezeket az aliasokat az SDK-val használhatja modellek letöltéséhez és betöltéséhez – például manager.catalog.getModel("whisper-tiny") JavaScriptben.

GET /openai/status

A kiszolgáló állapotadatainak lekérése.

Válasz törzse:

• Endpoints (sztringek tömbje)
  A HTTP-kiszolgáló kötési végpontjai.
• ModelDirPath (sztring)
  A helyi modellek tárolására szolgáló könyvtár.
• PipeName (sztring)
  Az aktuális NamedPipe-kiszolgáló neve.

Example:

Válaszüzenet tartalma

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

Nincs szükség javításokra, mivel az API végpontok gyakran változtatás nélkül maradnak a programozási környezetekben használtak egységessége miatt.

Szerezze be a katalógusban elérhető Foundry Local modellek listáját.

Válasz:

• models (tömb)
  Modellobjektumok tömbje. Minden modell a következőket tartalmazza:
  • name: A modell egyedi azonosítója.
  • displayName: A modell emberileg olvasható neve, gyakran ugyanaz, mint a név.
  • providerType: A modellt üzemeltető szolgáltató típusa (például AzureFoundry).
  • uri: Az erőforrás URI-ja, amely a modell beállításjegyzékbeli helyére mutat.
  • version: A modell verziószáma.
  • modelType: A modell formátuma vagy típusa (például ONNX).
  • promptTemplate:
    • assistant: Az asszisztens válaszának sablonja.
    • prompt: A felhasználó-asszisztens interakció sablonja.
  • publisher: A modellt közzétevő entitás vagy szervezet.
  • task: A modell elsődleges feladata (például csevegés befejezése).
  • runtime:
    • deviceType: A modell által futtatandó hardver típusa (például CPU).
    • executionProvider: A modell futtatásához használt végrehajtási szolgáltató.
  • fileSizeMb: A modellfájl mérete megabájtban.
  • modelSettings:
    • parameters: A modell konfigurálható paramétereinek listája.
  • alias: A modell alternatív neve vagy rövidített neve
  • supportsToolCalling: Azt jelzi, hogy a modell támogatja-e az eszközhívási funkciókat.
  • license: A modell terjesztésének licenctípusa.
  • licenseDescription: A licencfeltételek részletes leírása vagy hivatkozása.
  • parentModelUri: Annak a szülőmodellnek az URI-ja, amelyből a modell származik.

GET /openai/models

Lekérheti a gyorsítótárazott modellek listáját, beleértve a helyi és a regisztrált külső modelleket is.

Válasz:

• 200 OK
  Modellnevek tömbje karakterláncokként.

Example:

Válaszüzenet tartalma

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

POST /openai/download

Töltse le a modellt a katalógusból a helyi storage.

Megjegyzés:

A nagy modellletöltések hosszú időt is igénybe vehetnek. Állítson be egy magas időtúllépést a kéréshez a korai leállás elkerülése érdekében.

Kérelem Törzse:

• model (WorkspaceInferenceModel objektum)
  • Uri (sztring)
    A letöltendő modell URI-ja.
  • Name (sztring) A modell neve.
  • ProviderType (sztring, nem kötelező)
    A szolgáltató típusa. Használja a providerType visszaadott GET /foundry/list értéket (például "AzureFoundry" vagy "HuggingFace").
  • Path (sztring, nem kötelező)
    A modellfájlok távoli elérési útja. Egy Ölelő arc adattárban például ez a modellfájlok elérési útja.
  • PromptTemplate (Dictionary<string, string>nem kötelező)
    Tartalma:
    • system (sztring, nem kötelező)
      A rendszerüzenet sablonja.
    • user (sztring, nem kötelező) A felhasználó üzenetének sablonja.
    • assistant (sztring, nem kötelező)
      Az asszisztens válaszának sablonja.
    • prompt (sztring, nem kötelező)
      A felhasználó-asszisztens interakció sablonja.
  • Publisher (sztring, nem kötelező)
    A modell publisher.
• token (sztring, nem kötelező)
  Hitelesítési jogkivonat védett modellekhez (GitHub vagy Arc ölelése).
• progressToken (objektum, nem kötelező)
  Csak AITK esetén. Letöltési folyamat követésére szolgáló token.
• customDirPath (sztring, nem kötelező)
  Egyéni letöltési könyvtár (cli-hez használatos, nem szükséges az AITK-hoz).
• bufferSize (egész szám, nem kötelező)
  HTTP-letöltési puffer mérete KB-ban. Nincs hatása a NIM- vagy Azure Foundry-modellekre.
• ignorePipeReport (logikai, nem kötelező)
  Ha truea folyamatjelentést a cső helyett HTTP-adatfolyamon keresztül kényszeríti. Alapértelmezetten false az AITK és true a Foundry Local esetében.

Adatfolyam válasz:

A letöltés során a kiszolgáló streameli a frissítéseket a következő formátumban:

("file name", percentage_complete)

Végső válasz törzse:

• Success (logikai)
  Azt jelzi, hogy a letöltés sikeresen befejeződött-e.
• ErrorMessage (sztring, nem kötelező)
  Hiba részletei, ha a letöltés sikertelen volt.

Example:

URI-kérés

POST /openai/download

Kérés tartalma

Vegye figyelembe, hogy a verzió utótagját a modell nevében kell megadni.

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

Válasz folyam

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

Végső válasz

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

GET /openai/load/{name}

A gyorsabb következtetés érdekében töltsön be egy modellt a memóriába.

URI-paraméterek:

• name (sztring)
  A betöltendő modell neve.

Lekérdezési paraméterek:

• unload (logikai, nem kötelező)
  Azt határozza meg, hogy az inaktív idő után automatikusan eltávolítja-e a modellt. Alapértelmezett érték: true.
• ttl (egész szám, nem kötelező)
  Itt az idő, hogy másodpercek alatt éljünk. Ha 0-nál nagyobb, ez az érték felülírja a paramétert unload .
• ep (sztring, nem kötelező)
  Végrehajtási szolgáltató a modell futtatásához. Támogatja: "dml", "cuda", "qnn", "cpu". "webgpu"
  Ha nincs megadva, a genai_config.json beállításait használja.

Válasz:

• 200 OK
  Üres válasz törzse

Example:

URI-kérés

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

GET /openai/unload/{name}

Modell eltávolítása a memóriából.

URI-paraméterek:

• name (sztring) A kiürítendő modell neve.

Lekérdezési paraméterek:

• force (logikai, nem kötelező) Ha true, figyelmen kívül hagyja a TTL-beállításokat, és azonnal eltávolítja azokat.

Válasz:

• 200 OK Üres válasz törzse

Example:

URI-kérés

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

GET /openai/unloadall

Eltávolítja az összes modellt a memóriából.

Válasz:

• 200 OK
  Üres válasz törzse

GET /openai/loadedmodels

Az aktuálisan betöltött modellek listájának lekérése.

Válasz:

• 200 OK
  Modellnevek tömbje karakterláncokként.

Example:

Válaszüzenet tartalma

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

GET /openai/getgpudevice

Kérje le az aktuális GPU-eszközazonosítót.

Válasz:

• 200 OK
  Az aktuális GPU-eszközazonosítót jelölő egész szám.

GET /openai/setgpudevice/{deviceId}

Állítsa be az aktív GPU-eszközt.

URI-paraméterek:

• deviceId (egész szám)
  A használni kívánt GPU-eszközazonosító.

Válasz:

• 200 OK
  Üres válasz törzse

Example:

• URI kérése

  GET /openai/setgpudevice/1
  

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

Az adott csevegés-befejezési kérelem tokenjeinek számlálása következtetés nélkül.

Kérelem Törzse:

• Tartalomtípus: alkalmazás/json
• JSON-objektum formátuma a ChatCompletionCreateRequest következőkkel:
  • model (sztring)
    Tokenizáláshoz használandó modell.
  • messages (tömb)
    Üzenetobjektumok tömbje role és content.

Válasz törzse:

• Tartalomtípus: alkalmazás/json
• JSON-objektum tokenszámmal:
  • tokenCount (egész szám)
    A kérelemben szereplő jogkivonatok száma.

Example:

Kérés tartalma

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

Válaszüzenet tartalma

  {
    "tokenCount": 23
  }