ringkasan API Runtime Windows ML

Important

API ML Runtime Windows saat ini bersifat eksperimental dan tidak didukung untuk digunakan di lingkungan produksi. Aplikasi yang menggunakan API ini tidak boleh diterbitkan ke Microsoft Store.

Important

API Windows ML Runtime saat ini tersedia di C++ dan Python; C# saat ini tidak didukung. Beri tahu kami jika Anda tertarik menggunakan API ini dari C# dengan memposting masalah di repositori GitHub ML Windows!

WINDOWS ML Runtime API adalah kerangka kerja inferensi AI lokal C/C++ asli yang dibuat khusus untuk Windows. Dengan WINDOWS ML Runtime API, Anda dapat memuat model, memilih target eksekusi CPU, GPU, atau NPU (termasuk adaptor DXCore tertentu atau perangkat D3D12), mengikat tensor ke target tersebut, menyusun model dan tahap prosesor ke dalam alur, mengkompilasi alur, dan menjalankannya untuk menghasilkan tensor output.

API Pembuatan Teks dan Pengenalan Ucapan opsional menggabungkan objek Runtime yang sama ini menjadi alur kerja tingkat lebih tinggi untuk model yang disediakan aplikasi Anda: lihat Membuat teks dengan model bahasa Anda sendiri menggunakan Windows ML dan Kenali ucapan dengan model Whisper Anda sendiri menggunakan Windows ML.

Runtime API vs ONNX Runtime

Jika aplikasi Anda hanya menargetkan Windows (dan Anda bersedia menggunakan API yang saat ini bersifat eksperimental), gunakan API Runtime. Ini memberikan kontrol eksplisit atas pemilihan perangkat keras (termasuk adaptor DXCore tertentu atau perangkat D3D12), residensi tensor, penempatan alur multi-tahap, dan kompilasi.

Jika tidak, jika aplikasi Anda perlu berjalan di platform lain, atau sudah memiliki kode sesi ONNX Runtime lintas platform yang berfungsi, gunakan ONNX Runtime API yang disertakan dalam Windows ML sebagai gantinya.

Model objek inti

Konsep API Utama Description
Runtime IWinMLRuntime Antarmuka yang dikembalikan oleh WinMLCreateRuntime; memuat file model, membuat target eksekusi, dan membuat penyusun alur.
Model IWinMLModel Artefak model opak yang tidak dapat diubah dimuat dari file atau buffer. Cerminkan skema yang dinyatakan melalui IWinMLModelSchema.
Target Eksekusi IWinMLExecutionTarget Token penempatan CPU, GPU, atau NPU yang digunakan untuk membangun tahapan dan membuat tensor.
Pembangun pipeline IWinMLPipelineBuilder Menambahkan tahap model dan prosesor, menghubungkannya, dan membangun alur yang disiapkan.
Pipeline IWinMLPipeline Grafik yang disiapkan dan segera dapat dijalankan yang mengeksekusi tensor terikat dan menghasilkan tensor output.
Stage IWinMLStage Langkah dalam pipeline yang menetapkan pengikatan input dan output posisi serta target eksekusi hasil resolusi.
Tenser IWinMLTensor Data multi-dimensi bertipe yang terikat ke input dan output tahapan.
Pembuatan teks /pengenalan ucapan Windows API Pembuatan Teks dan Pengenalan Ucapan ML Alur kerja tingkat yang lebih tinggi terdiri atas objek Runtime yang dimiliki pemanggil, dengan sesi, aliran, dan hasil bertipe.

Pilih backend dan target eksekusi

LoadModelFromFile memilih backend dari ekstensi file artefak model. Aplikasi Anda menggunakan objek Runtime yang sama — model, target eksekusi, penyusun alur, tahapan, pengikatan, dan Run — apa pun backend yang memuat file.

Berkas model Backend Akselerasi perangkat keras
.onnx, .ort ONNX Runtime Penyedia eksekusi (EPs) yang diinstal dan terus diperbarui oleh Windows melalui katalog EP ML Windows
.gguf llama.cpp Modul CPU lokal aplikasi, ditambah modul CUDA opsional untuk GPU NVIDIA yang Anda sebarkan bersama aplikasi Anda. CPU dan CUDA adalah satu-satunya backend llama.cpp Windows ML yang divalidasi untuk rilis ini.

Target eksekusi mewakili kelas perangkat keras — CPU, GPU, atau NPU — yang dibuat dengan IWinMLRuntime. Gunakan kembali target untuk membangun tahapan dan membuat tensor: menggunakan kembali satu target menunjukkan afinitas target yang sama, sambil menggunakan target yang berbeda membuat batas transfer lintas target menjadi eksplisit. Ketika metode penyusun Build alur berjalan, runtime menempatkan setiap tahap pada backend eksekusi untuk targetnya dan memastikan kompatibilitas target dan backend.

Untuk kelas perangkat keras tanpa mencacah perangkat sendiri, panggil CreateExecutionTarget dengan WINML_EXECUTION_TARGET_KIND dan WINML_EXECUTION_TARGET_PREFERENCE yang memberi peringkat kandidat dari kelas tersebut, seperti GPU terintegrasi versus GPU diskrit. Perlakukan ERROR_NOT_FOUND dan ERROR_NOT_SUPPORTED sama dan kembali ke kelas lain:

ComPtr<IWinMLExecutionTarget> target;
HRESULT hr = runtime->CreateExecutionTarget(
    WINML_EXECUTION_TARGET_KIND_NPU,
    WINML_EXECUTION_TARGET_PREFERENCE_EFFICIENCY,
    target.GetAddressOf());
if (hr == HRESULT_FROM_WIN32(ERROR_NOT_FOUND) ||
    hr == HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED))
{
    THROW_IF_FAILED(runtime->CreateExecutionTarget(
        WINML_EXECUTION_TARGET_KIND_GPU,
        WINML_EXECUTION_TARGET_PREFERENCE_PERFORMANCE,
        target.GetAddressOf()));
}
else
{
    THROW_IF_FAILED(hr);
}

CreateCpuExecutionTarget setara dengan meminta jenis CPU. CreateExecutionTargetFromAdapter dan CreateExecutionTargetFromD3D12 mengikat target ke adaptor DXCore tertentu atau perangkat D3D12 alih-alih membiarkan Runtime memilih salah satu. Untuk model ONNX yang bergantung pada penyedia eksekusi (EP) yang diinstal, lapisan kompatibilitas ONNX Runtime opsional memungkinkan Anda mengunci penyedia yang telah Anda daftarkan. Setiap backend menangani target-target ini secara berbeda — misalnya, backend llama.cpp yang digunakan oleh .gguf model memerlukan setidaknya offload GPU parsial agar memenuhi target GPU, dan tidak mendukung target NPU atau penyematan penyedia. Untuk matriks resolusi target lengkap per backend, dan untuk panduan menjalankan model GGUF, lihat konsep API Windows ML Runtime.

Langkah berikutnya

  • Terakhir diperbarui pada