Referensi REST API Lokal Foundry

Penting

Foundry Local CLI tersedia dalam pratinjau. Rilis pratinjau publik menyediakan access awal untuk fitur yang berada dalam penyebaran aktif.
Fitur, pendekatan, dan proses dapat berubah atau memiliki kemampuan terbatas, sebelum Ketersediaan Umum (GA).

Perhatian

API ini mengacu pada REST API yang tersedia di Foundry Local CLI. API ini sedang dikembangkan secara aktif dan dapat mencakup perubahan yang mengganggu tanpa pemberitahuan. Kami sangat menyarankan untuk memantau changelog sebelum membangun aplikasi produksi.

POST /v1/chat/completions

Titik akhir ini memproses permintaan penyelesaian obrolan.
Ini sepenuhnya kompatibel dengan OpenAI Chat Completions API.

Isi Permintaan :

---Properti Standar OpenAI---

model (String)
Model spesifik yang digunakan untuk penyelesaian.
messages (larik)
Riwayat percakapan sebagai daftar pesan.
- Setiap pesan memerlukan:
  - role (String)
    Peran pengirim pesan. Harus system, , useratau assistant.
  - content (String)
    Teks pesan aktual.
temperature (angka, opsional)
Mengontrol keacakan, mulai dari 0 hingga 2. Nilai yang lebih tinggi (0,8) membuat output yang bervariasi, sementara nilai yang lebih rendah (0,2) membuat output yang berfokus dan konsisten.
top_p (angka, opsional)
Mengontrol keragaman pilihan token dari 0 hingga 1. Nilai 0,1 berarti hanya token dengan probabilitas tertinggi 10 besar% yang dipertimbangkan.
n (bilangan bulat, opsional)
Jumlah penyelesaian alternatif yang dihasilkan untuk setiap pesan input.
stream (boolean, opsional)
Jika benar, akan mengirim respons pesan parsial sebagai peristiwa yang dikirim oleh server, diakhiri dengan pesan data: [DONE].
stop (string atau array, opsional)
Hingga 4 urutan yang akan menyebabkan model berhenti menghasilkan token lebih lanjut.
max_tokens (bilangan bulat, opsional)
Jumlah maksimum token yang akan dihasilkan. Untuk model yang lebih baru, gunakan max_completion_tokens sebagai gantinya.
max_completion_tokens (bilangan bulat, opsional)
Jumlah maksimum token yang dapat dihasilkan model, termasuk output yang terlihat dan token penalaran.
presence_penalty (angka, opsional)
Nilai antara -2.0 dan 2.0. Nilai positif mendorong model untuk mendiskusikan topik baru dengan memberikan hukuman pada token yang telah muncul.
frequency_penalty (angka, opsional)
Nilai antara -2.0 dan 2.0. Nilai positif mencegah pengulangan dengan memberikan penalti pada token berdasarkan frekuensinya dalam teks.
logit_bias (peta, opsional)
Menyesuaikan probabilitas token tertentu yang muncul dalam penyelesaian.
user (string, opsional)
Pengidentifikasi unik untuk pengguna akhir Anda yang membantu pemantauan dan pencegahan penyalahgunaan.
functions (array, opsional)
Fungsi yang tersedia di mana model dapat menghasilkan input JSON.
- Setiap fungsi harus mencakup:
  - name (String)
    Nama fungsi.
  - description (String)
    Deskripsi fungsi.
  - parameters (objek)
    Parameter fungsi yang dijelaskan sebagai objek Skema JSON.
function_call (string atau objek, opsional)
Mengontrol bagaimana model merespons panggilan fungsi.
- Jika objek, dapat mencakup:
  - name (string, opsional)
    Nama fungsi yang akan dipanggil.
  - arguments (objek, opsional)
    Argumen yang akan diteruskan ke fungsi.
metadata (objek, opsional)
Kamus pasangan nilai-kunci metadata.
top_k (angka, opsional)
Jumlah token kosakata probabilitas tertinggi yang disimpan untuk penyaringan k atas.
random_seed (bilangan bulat, opsional)
Seed untuk pembuatan angka acak yang dapat direproduksi.
ep (string, opsional)
Timpa penyedia layanan untuk model ONNX. Mendukung: "dml", "cuda", "qnn", "cpu", "webgpu".
ttl (bilangan bulat, opsional)
Masa hidup model dalam memori dalam hitungan detik.
tools (objek, opsional)
Alat yang telah ditentukan untuk permintaan.

Isi respons:

id (String)
Pengidentifikasi unik untuk selesainya obrolan.
object (String)
Jenis objek, selalu "chat.completion".
created (bilangan bulat)
Tanda waktu pembuatan dalam detik epoch.
model (String)
Model yang digunakan untuk penyelesaian tugas.
choices (larik)
Daftar pilihan penyelesaian, masing-masing berisi:
- index (bilangan bulat)
  Indeks pilihan ini.
- message (objek)
  Pesan yang dihasilkan dengan:
  - role (String)
    Selalu "assistant" untuk respons.
  - content (String)
    Teks aktual yang dihasilkan.
- finish_reason (String)
  Mengapa pembuatan itu terhenti (misalnya, "stop", "length", "function_call").
usage (objek)
Statistik penggunaan token:
- prompt_tokens (bilangan bulat)
  Token dalam perintah.
- completion_tokens (bilangan bulat)
  Token selama penyelesaian.
- total_tokens (bilangan bulat)
  Total token yang digunakan.

Example:

Isi dari permintaan

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

Badan respons

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

Titik akhir ini mentranskripsikan file audio ke teks. Ini kompatibel dengan OPENAI Audio Transcriptions API.

Format permintaan:multipart/form-data

Bidang permintaan:

file (file, diperlukan)
File audio yang akan ditranskripsikan. Format yang didukung termasuk MP3, WAV, FLAC, OGG, dan WebM.
model (string, diperlukan)
ID model yang digunakan untuk transkripsi. Gunakan ID yang dikembalikan saat memuat model Whisper (misalnya, setelah memuat whisper-tiny).
language (string, opsional)
Bahasa audio dalam format ISO 639-1 (misalnya, "en"). Memberikan ini meningkatkan akurasi dan kecepatan.
temperature (angka, opsional)
Suhu pengambilan sampel antara 0 dan 1. Nilai yang lebih rendah menghasilkan hasil yang lebih deterministik.
response_format (string, opsional)
Format respons. Opsi: json (default), text, verbose_json.

Isi respons:

text (String)
Teks yang ditranskripsikan.

Example:

Permintaan

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

Penting

Ganti <PORT> dengan port dinamis layanan Foundry Local dan <MODEL_ID> dengan ID model dikembalikan saat model dimuat. Di SDK, gunakan manager.endpoint (JS) atau config.Web.Urls (C#) untuk mendapatkan titik akhir — jangan pernah hardcode port.

Badan respons

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

Tip

Alias model Whisper yang tersedia meliputi whisper-tiny, , whisper-basedan whisper-small. Gunakan alias ini dengan SDK untuk mengunduh dan memuat model — misalnya, manager.catalog.getModel("whisper-tiny") di JavaScript.

GET /openai/status

Dapatkan informasi status server.

Isi respons:

Endpoints (array dari string-string)
Titik akhir pengikatan server HTTP.
ModelDirPath (String)
Direktori tempat model lokal disimpan.
PipeName (String)
Nama server NamedPipe saat ini.

Example:

Badan respons

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

GET /foundry/list

Dapatkan daftar model Foundry Local yang tersedia di katalog.

Jawaban:

models (larik)
Larik objek model. Setiap model meliputi:
- name: Identitas unik untuk model.
- displayName: Nama yang dapat dibaca manusia untuk model, seringkali sama dengan namanya.
- providerType: Jenis penyedia yang menghosting model (misalnya, AzureFoundry).
- uri: URI sumber daya yang menunjuk ke lokasi model di registri.
- version: Nomor versi model.
- modelType: Format atau jenis model (misalnya, ONNX).
- promptTemplate:
  - assistant: Templat untuk respons asisten.
  - prompt: Templat untuk interaksi asisten pengguna.
- publisher: Entitas atau organisasi yang menerbitkan model.
- task: Tugas utama yang dirancang model untuk dilakukan (misalnya, penyelesaian obrolan).
- runtime:
  - deviceType: Jenis perangkat keras yang dirancang untuk dijalankan model (misalnya, CPU).
  - executionProvider: Penyedia eksekusi yang digunakan untuk menjalankan model.
- fileSizeMb: Ukuran file model dalam megabyte.
- modelSettings:
  - parameters: Daftar parameter yang dapat dikonfigurasi untuk model.
- alias: Nama alternatif atau singkatan untuk model
- supportsToolCalling: Menunjukkan apakah model mendukung fungsionalitas panggilan alat.
- license: Jenis lisensi tempat model didistribusikan.
- licenseDescription: Deskripsi terperinci atau tautan ke persyaratan lisensi.
- parentModelUri: URI model induk dari mana model ini berasal.

GET /openai/models

Dapatkan daftar model yang di-cache, termasuk model eksternal lokal dan terdaftar.

Jawaban:

200 OK (Permintaan berhasil)
Sekumpulan nama model dalam bentuk string.

Example:

Badan respons

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

POST /openai/download

Unduh model dari katalog ke storage lokal.

Nota

Unduhan model besar dapat memakan waktu lama. Tetapkan batas waktu tinggi untuk permintaan ini untuk menghindari penghentian dini.

Isi Permintaan :

model (WorkspaceInferenceModel objek)
- Uri (String)
  URI model untuk diunduh.
- Name (String) Nama model.
- ProviderType (string, opsional)
  Jenis penyedia (misalnya, "AzureFoundryLocal", "HuggingFace").
- Path (string, opsional)
  Jalur jarak jauh ke file model. Misalnya, dalam repositori Hugging Face, ini adalah jalur ke file model.
- PromptTemplate (Dictionary<string, string>, opsional)
  Termasuk:
  - system (string, opsional)
    Templat untuk pesan sistem.
  - user (string, opsional) Templat untuk pesan pengguna.
  - assistant (string, opsional)
    Templat untuk respons asisten.
  - prompt (string, opsional)
    Templat untuk interaksi asisten pengguna.
- Publisher (string, opsional)
  Publisher model.
token (string, opsional)
Token autentikasi untuk model yang dilindungi (GitHub atau Hugging Face).
progressToken (objek, opsional)
Hanya untuk AITK. Token untuk melacak kemajuan pengunduhan.
customDirPath (string, opsional)
Direktori unduhan kustom (digunakan untuk CLI, tidak diperlukan untuk AITK).
bufferSize (bilangan bulat, opsional)
Ukuran buffer unduhan HTTP dalam KB. Tidak ada efek pada model NIM atau Azure Foundry.
ignorePipeReport (boolean, opsional)
Jika true, memaksa kemajuan pelaporan melalui aliran HTTP alih-alih pipa. Setelan default ke false untuk AITK dan true untuk Foundry Local.

Respons Streaming:

Selama pengunduhan, server mengalirkan pembaruan kemajuan dalam format:

("file name", percentage_complete)

Isi Respons Akhir:

Success (Boolean)
Apakah pengunduhan berhasil diselesaikan.
ErrorMessage (string, opsional)
Detail kesalahan jika pengunduhan gagal.

Example:

Memohon URI

POST /openai/download

Isi dari permintaan

Perhatikan bahwa akhiran versi harus disediakan dalam nama model.

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

Aliran respons

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

Respons akhir

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

GET /openai/load/{name}

Muat model ke dalam memori untuk inferensi yang lebih cepat.

Parameter URI:

name (String)
Nama model yang akan dimuat.

Parameter Pencarian:

unload (boolean, opsional)
Apakah akan secara otomatis membongkar model setelah waktu diam. Secara default menjadi true.
ttl (bilangan bulat, opsional)
Waktu untuk hidup dalam hitung detik. Jika lebih besar dari 0, nilai ini akan mengambil alih unload parameter.
ep (string, opsional)
Penyedia eksekusi untuk menjalankan model ini. Mendukung: "dml", "cuda", "qnn", "cpu", "webgpu".
Jika tidak ditentukan, menggunakan pengaturan dari genai_config.json.

Jawaban:

200 OK (Permintaan berhasil)
Badan respons kosong

Example:

Memohon URI

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

GET /openai/unload/{name}

Membongkar model dari memori.

Parameter URI:

name (String) Nama model untuk dibongkar.

Parameter Pencarian:

force (boolean, opsional) Jika true, segera mengabaikan pengaturan dan pembongkaran TTL.

Jawaban:

Isi respons Kosong OK 200

Example:

Memohon URI

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

GET /openai/unloadall

Membongkar semua model dari memori.

Jawaban:

200 OK (Permintaan berhasil)
Badan respons kosong

GET /openai/loadedmodels

Dapatkan daftar model yang saat ini dimuat.

Jawaban:

200 OK (Permintaan berhasil)
Sekumpulan nama model dalam bentuk string.

Example:

Badan respons

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

GET /openai/getgpudevice

Dapatkan ID perangkat GPU saat ini.

Jawaban:

200 OK (Permintaan berhasil)
Bilangan bulat yang mewakili ID perangkat GPU saat ini.

GET /openai/setgpudevice/{deviceId}

Atur perangkat GPU aktif.

Parameter URI:

deviceId (bilangan bulat)
ID perangkat GPU yang akan digunakan.

Jawaban:

200 OK (Permintaan berhasil)
Badan respons kosong

Example:

Meminta URI
```
GET /openai/setgpudevice/1
```

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

Menghitung token untuk permintaan penyelesaian obrolan tertentu tanpa melakukan inferensi.

Isi Permintaan :

Jenis Konten: aplikasi/json
Objek JSON dalam ChatCompletionCreateRequest format dengan:
- model (String)
  Model yang digunakan untuk tokenisasi.
- messages (larik)
  Sekumpulan objek pesan yang memiliki role dan content.

Isi Respons:

Jenis Konten: aplikasi/json
Objek JSON dengan jumlah token:
- tokenCount (bilangan bulat)
  Jumlah token dalam permintaan.

Example:

Isi dari permintaan

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

Badan respons

  {
    "tokenCount": 23
  }

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-25

Bagikan melalui

Referensi REST API Lokal Foundry

POST /v1/chat/completions

POST /v1/audio/transcriptions

GET /openai/status

GET /foundry/list

GET /openai/models

POST /openai/download

GET /openai/load/{name}

GET /openai/unload/{name}

GET /openai/unloadall

GET /openai/loadedmodels

GET /openai/getgpudevice

GET /openai/setgpudevice/{deviceId}

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

Saran dan Komentar

Sumber Daya Tambahan: