Bagikan melalui

Referensi CLI 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).

Artikel ini menyediakan referensi komprehensif untuk antarmuka baris perintah (CLI) Foundry Local. CLI mengatur perintah ke dalam kategori logis untuk membantu Anda mengelola model, mengontrol layanan, dan memelihara cache lokal Anda.

Prasyarat

  • Instal Foundry Local.
  • Terminal lokal tempat foundry CLI tersedia.
  • Pastikan Anda memiliki akses internet untuk pengunduhan pertama (penyedia eksekusi dan model).
  • Azure RBAC: Tidak berlaku (berjalan secara lokal).
  • Jika Anda memiliki Intel NPU pada Windows, instal driver NPU Intel untuk akselerasi NPU yang optimal.

Instal Foundry Local

Instal Foundry Local dengan menggunakan manajer paket untuk sistem operasi Anda.

  • Windows: Buka terminal dan jalankan:
    winget install Microsoft.FoundryLocal
  • macOS: Buka terminal dan jalankan: 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    Atau, unduh alat penginstal dari repositori GitHub Foundry Local.

Verifikasi penginstalan:

foundry --version

Pastikan Anda memiliki hak admin untuk menginstal perangkat lunak.

Tip

Jika Anda melihat kesalahan koneksi layanan setelah penginstalan (misalnya, Request to local service failed), jalankan foundry service restart.

Verifikasi cepat

Jalankan perintah ini untuk mengonfirmasi bahwa CLI diinstal dan layanan dapat dijangkau.

  1. Tampilkan bantuan CLI:

     foundry --help

    Perintah ini mencetak informasi penggunaan dan daftar grup perintah yang tersedia.

    Referensi: Gambaran Umum

  2. Periksa status layanan:

     foundry service status

    Perintah ini menampilkan status apakah layanan Foundry Local berjalan serta menyertakan titik akhir lokalnya.

    Referensi: Perintah layanan

Gambaran Umum

Gunakan bantuan bawaan untuk menjelajahi perintah dan opsi.

CLI mengatur perintah ke dalam tiga kategori utama:

  • Model: Perintah untuk mengelola dan menjalankan model AI
  • Layanan: Perintah untuk mengontrol layanan Foundry Local
  • Cache: Perintah untuk mengelola penyimpanan model lokal Anda

Perintah model

Tabel berikut ini meringkas perintah yang terkait dengan mengelola dan menjalankan model:

Nota

Anda dapat menentukan model argumen dengan alias atau ID modelnya. Menggunakan alias:

  • Memilih model terbaik untuk perangkat keras yang tersedia secara otomatis. Misalnya, jika Anda memiliki GPU Nvidia yang tersedia, Foundry Local memilih model GPU terbaik. Jika Anda memiliki NPU yang tersedia dan didukung, Foundry Local akan memilih model NPU.
  • Memungkinkan Anda menggunakan nama yang lebih pendek tanpa perlu mengingat ID model.

Jika Anda ingin menjalankan model tertentu, gunakan ID model. Misalnya, untuk menjalankan qwen2.5-0.5b pada CPU - terlepas dari perangkat keras Anda yang tersedia - gunakan: foundry model run qwen2.5-0.5b-instruct-generic-cpu.

Perintah Deskripsi
foundry model --help Menampilkan semua perintah terkait model yang tersedia dan penggunaannya.
foundry model run <model> Menjalankan model tertentu, mengunduhnya jika tidak di-cache, dan memulai interaksi.
foundry model list Mencantumkan semua model yang tersedia untuk penggunaan lokal. Pada eksekusi pertama, ia mengunduh penyedia eksekusi (EPs) untuk perangkat keras Anda.
foundry model list --filter <key>=<value> Mencantumkan model yang difilter berdasarkan kriteria yang ditentukan (perangkat, tugas, alias, penyedia).
foundry model info <model> Menampilkan informasi terperinci tentang model tertentu.
foundry model info <model> --license Menampilkan informasi lisensi untuk model tertentu.
foundry model download <model> Mengunduh model ke cache lokal tanpa menjalankannya.
foundry model load <model> Memuat model ke dalam layanan.
foundry model unload <model> Menghapus model dari layanan.

Pengurutan daftar model

Saat beberapa varian ID model tersedia untuk alias, daftar model menampilkan model dalam urutan prioritas. Model pertama dalam daftar adalah model yang berjalan saat Anda menentukan model dengan alias.

Pemfilteran daftar model

Perintah foundry model list ini mendukung model pemfilteran dengan menggunakan --filter opsi . Anda dapat memfilter model berdasarkan satu atribut dengan menggunakan pasangan kunci-nilai.

foundry model list --filter <key>=<value>

Perintah ini mencetak model yang cocok dengan kunci dan nilai filter.

Referensi: Pemfilteran daftar model

Nota

Saat Anda menjalankan foundry model list untuk pertama kalinya setelah penginstalan, Foundry Local secara otomatis mengunduh penyedia eksekusi (EP) yang relevan untuk konfigurasi perangkat keras komputer Anda. Anda melihat bilah kemajuan yang menunjukkan penyelesaian unduhan sebelum daftar model muncul.

Kunci filter yang didukung:

perangkat - Jenis Perangkat Keras

Memfilter model menurut perangkat keras tempat model dijalankan.

Nilai yang mungkin:

  • CPU - Model unit pemrosesan pusat
  • GPU - Model unit pengolah grafis
  • NPU - Model Unit Pemrosesan Syaraf

penyedia - Penyedia Eksekusi

Memfilter model menurut penyedia eksekusi atau runtimenya.

Nilai yang mungkin:

  • CPUExecutionProvider - Eksekusi berbasis CPU
  • CUDAExecutionProvider - Pelaksanaan GPU NVIDIA CUDA
  • WebGpuExecutionProvider - Eksekusi WebGPU
  • QNNExecutionProvider - Pelaksanaan Jaringan Neural Qualcomm (NPU)
  • OpenVINOExecutionProvider - Eksekusi Intel OpenVINO
  • NvTensorRTRTXExecutionProvider - Eksekusi NVIDIA TensorRT
  • VitisAIExecutionProvider - Eksekusi AMD Vitis AI

tugas - Jenis Tugas Model

Memfilter model berdasarkan kasus penggunaan atau tugas yang dimaksudkan.

Nilai umum:

  • chat-completion: Model AI Percakapan
  • text-generation: Model pembuatan teks

alias - Alias dari Model

Memfilter model menurut pengidentifikasi aliasnya. Mendukung pencocokan karakter pengganti dengan akhiran *.

Nilai sampel:

  • phi4-cpu
  • qwen2.5-coder-0.5b-instruct-generic-cpu
  • deepseek-r1-distill-qwen-1.5b-generic-cpu
  • phi-4-mini-instruct-generic-cpu

Fitur filter khusus

Dukungan Negasi: Awali nilai apa pun dengan ! untuk mengecualikan model yang cocok.

foundry model list --filter device=!GPU

Perintah ini mengecualikan model GPU dari hasil.

Referensi: Fitur filter khusus

Pencocokan karakter pengganti (hanya alias): Gunakan * untuk mencocokkan awalan saat memfilter berdasarkan alias.

foundry model list --filter alias=qwen*

Perintah ini mengembalikan model yang aliasnya dimulai dengan qwen.

Referensi: Fitur filter khusus

Contoh

foundry model list --filter device=GPU
foundry model list --filter task=chat-completion
foundry model list --filter provider=CUDAExecutionProvider

Contoh-contoh ini memfilter daftar model menurut perangkat, tugas, dan penyedia eksekusi.

Referensi: Pemfilteran daftar model

Nota

  • Semua perbandingan tidak sensitif huruf besar/kecil.
  • Hanya satu filter yang dapat digunakan per perintah.
  • Kunci filter yang tidak dikenal mengakibatkan kesalahan.

Menjalankan model secara interaktif

Jalankan model dan berinteraksi dengannya langsung di terminal:

foundry model run qwen2.5-0.5b

Foundry Local mengunduh model saat pertama kali dijalankan, lalu memulai sesi interaktif. Masukkan perintah untuk mendapatkan respons:

Why is the sky blue?

Cuplikan layar output dari perintah eksekusi Lokal Foundry.

Tip

Ganti qwen2.5-0.5b dengan alias model apa pun dari katalog. Jalankan foundry model list untuk melihat model yang tersedia. Foundry Local mengunduh varian yang paling cocok dengan perangkat keras Anda — misalnya, varian CUDA untuk GPU NVIDIA atau varian NPU untuk NPU Qualcomm.

Perintah layanan

Tabel berikut ini meringkas perintah yang terkait dengan pengelolaan dan menjalankan layanan Foundry Local:

Perintah Deskripsi
foundry service --help Menampilkan semua perintah terkait layanan yang tersedia dan penggunaannya.
foundry service start Memulai layanan Foundry Local.
foundry service stop Menghentikan layanan Foundry Local.
foundry service restart Memulai ulang layanan Foundry Local.
foundry service status Menampilkan status layanan Foundry Local saat ini.
foundry service ps Mencantumkan semua model yang saat ini dimuat di layanan Foundry Local.
foundry service diag Menampilkan log layanan Foundry Local.
foundry service set <options> Mengatur konfigurasi layanan Foundry Local.

Perintah cache

Tabel berikut ini meringkas perintah untuk mengelola cache lokal tempat model disimpan:

Perintah Deskripsi
foundry cache --help Memperlihatkan semua perintah terkait cache yang tersedia dan penggunaannya.
foundry cache location Memperlihatkan direktori cache saat ini.
foundry cache list Mencantumkan semua model yang disimpan dalam cache lokal.
foundry cache cd <path> Mengubah direktori cache ke jalur yang ditentukan.
foundry cache remove <model> Menghapus model dari cache lokal.

Penyedia pelaksanaan

Penyedia eksekusi adalah pustaka akselerasi khusus perangkat keras yang menjalankan model seefisien mungkin di perangkat Anda.

Penyedia eksekusi bawaan

Foundry Local mencakup penyedia eksekusi CPU, penyedia eksekusi WebGPU, dan penyedia eksekusi CUDA.

Penyedia eksekusi CPU menggunakan Microsoft Linear Algebra Subroutines (MLAS) untuk berjalan pada CPU apa pun dan merupakan fallback CPU untuk Foundry Local.

Penyedia pelaksana WebGPU menggunakan Dawn, implementasi asli dari API berbasis web, untuk akselerasi pada GPU apa pun, dan merupakan cadangan GPU untuk Foundry Local.

Penyedia eksekusi CUDA menggunakan NVIDIA CUDA untuk akselerasi pada GPU NVIDIA. Ini memerlukan seri NVIDIA GeForce RTX 30 dan yang lebih baru dengan driver minimum yang direkomendasikan versi 32.0.15.5585 dan CUDA versi 12.5. Ini tunduk pada persyaratan lisensi berikut: Perjanjian Lisensi untuk Kit Pengembangan Perangkat Lunak NVIDIA—EULA.

Penyedia pelaksanaan plugin

Penyedia eksekusi yang tercantum dalam tabel berikut ini tersedia untuk unduhan dan pendaftaran dinamis pada Windows, tergantung pada kompatibilitas perangkat dan driver. Mereka tunduk pada persyaratan lisensi yang ditentukan.

Foundry Local secara otomatis mengunduh penyedia eksekusi ini saat pertama kali dijalankan. Penyedia eksekusi plugin secara otomatis memperbarui ketika versi baru tersedia.

Nama (Vendor) Persyaratan Ketentuan lisensi
NvTensorRTRTXExecutionProvider (NVIDIA) NVIDIA GeForce RTX 30XX dan versi yang lebih baru dengan driver minimum yang direkomendasikan versi 32.0.15.5585 dan CUDA versi 12.5 Perjanjian Lisensi untuk Kit Pengembangan Perangkat Lunak NVIDIA—EULA
OpenVINOExecutionProvider (Intel) CPU: Intel TigerLake (Generasi ke-11) dan versi selanjutnya dengan driver minimum yang direkomendasikan 32.0.100.9565
GPU: Intel AlderLake (Gen ke-12) dan versi yang lebih baru dengan driver yang direkomendasikan min 32.0.101.1029
NPU: Intel ArrowLake generasi ke-15 dan versi-versi selanjutnya dengan driver minimum yang direkomendasikan 32.0.100.4239		 Perjanjian Lisensi Penggunaan Komersial Distribusi Intel OBL v2025.02.12
QNNExecutionProvider (Qualcomm) Snapdragon(R) X Elite - X1Exxxxx - Qualcomm(R) Hexagon(TM) NPU dengan driver minimum versi 30.0.140.0 dan versi yang lebih baru
Snapdragon(R) X Plus - X1Pxxxxx - Qualcomm(R) Hexagon(TM) NPU dengan driver minimum versi 30.0.140.0 dan versi yang lebih baru		 Untuk melihat Lisensi QNN, unduh Qualcomm® Neural Processing SDK, ekstrak ZIP, dan buka file LICENSE.pdf.
VitisAIExecutionProvider (AMD) Min: Adrenalin Edition 25.6.3 dengan driver NPU 32.00.0203.280
Maks: Adrenalin Edition 25.9.1 dengan driver NPU 32.00.0203.297		 Tidak diperlukan lisensi tambahan

Menggunakan Open WebUI dengan server lokal

Sambungkan Open WebUI ke Foundry Local untuk antarmuka obrolan berbasis browser yang berjalan sepenuhnya di perangkat Anda.

  1. Mulai model dan biarkan terminal terbuka:

    foundry model run qwen2.5-0.5b

  2. Dapatkan URL titik akhir lokal Anda:

    foundry service status

    Salin URL titik akhir. Foundry Local menetapkan port dinamis setiap kali layanan dimulai.

  3. Instal dan luncurkan Open WebUI, lalu buka http://localhost:8080 di browser Anda.

  4. Sambungkan Open WebUI ke Foundry Local:

    1. Buka Pengaturan>Pengaturan>Koneksi Admin dan aktifkan Koneksi Langsung.
    2. Buka Pengaturan>Koneksi>Kelola Koneksi Langsung dan pilih +.
    3. Atur URL ke http://localhost:PORT/v1 (ganti PORT dengan port dari langkah 2) dan Auth ke Tidak Ada.
    4. Pilih Simpan.

  5. Pilih model dari menu dropdown dan mulai mengobrol.

Tip

Jika tidak ada model yang muncul, jalankan foundry model run <model> di terminal dan muat ulang Open WebUI. Jika koneksi gagal, konfirmasikan port dengan foundry service status.

Mutakhirkan Foundry Local

Jalankan perintah untuk sistem operasi Anda untuk memutakhirkan Foundry Local.

  • Windows:
    winget upgrade --id Microsoft.FoundryLocal
  • macOS: 
    brew upgrade foundrylocal

Copot pemasangan Foundry Local

Jalankan perintah untuk sistem operasi Anda untuk menghapus instalasi Foundry Local.

  • Windows:
    winget uninstall Microsoft.FoundryLocal
  • macOS: 
    brew rm foundrylocal
brew untap microsoft/foundrylocal
brew cleanup --scrub

Troubleshooting

Masalah koneksi layanan

Jika Anda melihat kesalahan ini saat menjalankan perintah seperti foundry model list:

Exception: Request to local service failed.
Uri: http://127.0.0.1:0/foundry/list

The requested address is not valid in its context. (127.0.0.1:0)

Please check service status with 'foundry service status'.

Mulai ulang layanan :

foundry service restart

Perintah ini memperbaiki kasus di mana layanan berjalan tetapi tidak dapat diakses karena masalah pengikatan port.

Untuk panduan pemecahan masalah selengkapnya, lihat Praktik terbaik dan pemecahan masalah.

  • Last updated on