Referensi CLI Lokal Foundry

Important

  • 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 server lokal, 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.

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 server 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 server:

status server foundry '''

Perintah ini mencetak apakah daemon Foundry Local berjalan dan menyertakan titik akhir lokalnya.

Referensi: Perintah server

Ikhtisar

Gunakan bantuan bawaan untuk menjelajahi perintah dan opsi.

CLI mengatur perintah ke dalam grup berikut:

  • Model: model, cache
  • Jalankan: run, chat, complete, transcribe
  • Server: server
  • Penyetelan: config
  • Bantuan: status, report

Tabel berikut ini meringkas perintah tingkat atas:

Command Description
foundry model Menemukan, memeriksa, mengunduh, memuat, dan membongkar model lokal.
foundry chat <model> Memulai sesi obrolan lokal interaktif.
foundry complete <model> <prompt> Menghasilkan satu penyelesaian teks stateless.
foundry run <model> Menjalankan model dengan perutean otomatis ke obrolan atau transkripsi.
foundry server Memulai, menghentikan, memulai ulang, memeriksa, dan memecahkan masalah daemon Foundry lokal.
foundry cache Memeriksa dan mengelola entri cache model yang diunduh.
foundry config Menampilkan dan mengedit pengaturan CLI Foundry persisten.
foundry status Menampilkan diagnostik sistem, layanan, model, dan konektivitas.
foundry report Membuka masalah GitHub yang telah diisi sebelumnya dengan diagnostik.
foundry transcribe Memulai sesi transkripsi ucapan lokal interaktif atau mentranskripsikan file.

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 run qwen2.5-0.5b-instruct-generic-cpu.

Command Description
foundry model --help Menampilkan semua perintah terkait model yang tersedia dan penggunaannya.
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 info <model> Menampilkan informasi terperinci tentang 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

Gunakan opsi eksplisit untuk foundry model list mempersempit atau memperluas hasilnya.

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.

Option Description
--device <device> Memfilter model menurut perangkat.
--type <type> Memfilter model menurut jenis.
--search <query> Memfilter model menurut kueri pencarian.
--cached Memfilter daftar ke model yang di-cache.
--loaded Memfilter daftar ke model yang dimuat.
--variants Menyertakan varian model dalam daftar.

Examples

foundry model list --device gpu
foundry model list --type chat
foundry model list --search qwen
foundry model list --cached
foundry model list --loaded
foundry model list --variants

Contoh ini memfilter atau memperluas daftar model dengan menggunakan opsi yang didukung.

Referensi: Pemfilteran daftar model

Menjalankan model secara interaktif

Jalankan model dan berinteraksi dengannya langsung di terminal:

foundry chat 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?

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 server

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

Command Description
foundry server --help Menampilkan semua perintah terkait server yang tersedia dan penggunaannya.
foundry server start Memulai daemon Lokal Foundry dan layanan lokal yang kompatibel dengan OpenAI.
foundry server start --port <port> Memulai layanan lokal pada port TCP yang ditentukan. Gunakan 0 untuk port yang ditetapkan OS.
foundry server start --idle-timeout <minutes> Menghentikan daemon setelah jumlah menit tidak aktif yang ditentukan. Gunakan 0 untuk menjaga daemon tetap berjalan.
foundry server stop Menghentikan daemon Foundry Local.
foundry server restart Memulai ulang daemon Lokal Foundry dan layanan lokal.
foundry server restart --port <port> --idle-timeout 0 Memulai ulang layanan lokal pada port TCP yang ditentukan dan menjaga daemon tetap berjalan.
foundry server status Menampilkan status daemon, URL layanan lokal, ID proses, waktu aktif, dan lokasi log.
foundry server logs Menampilkan daemon Lokal Foundry dan log SDK.

Server lokal port tetap

Untuk memulai layanan lokal pada port tetap dan menjaga daemon tetap berjalan, gunakan --port dengan --idle-timeout 0:

foundry server start --port 39839 --idle-timeout 0

Jika daemon sudah berjalan dan Anda perlu menerapkan port baru, mulai ulang dengan opsi yang sama:

foundry server restart --port 39839 --idle-timeout 0

Untuk memverifikasi URL titik akhir lokal, jalankan:

foundry server status

Perintah cache

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

Command Description
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 run qwen2.5-0.5b


1. Get your local endpoint URL:

```bash
foundry server status

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

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

  2. 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.

  3. Pilih model dari menu dropdown dan mulai mengobrol.

Tip

Jika tidak ada model yang muncul, jalankan foundry run <model> di terminal dan muat ulang Open WebUI. Jika koneksi gagal, konfirmasikan port dengan foundry server 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 server status'.

Mulai ulang layanan :

foundry server restart

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

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

  • Last updated on