Pakai kunci API sendiri

Perch dapat berjalan dengan kredensial model milik Anda sendiri, bukan milik kami. Penggunaan dengan kunci Anda sendiri tidak dihitung terhadap Perch Token yang sudah termasuk dalam paket Anda, sehingga penggunaan bulanan yang sudah termasuk tidak tersentuh selama Anda memakainya.

Fitur ini tersedia di semua paket, termasuk yang gratis. Ini adalah fitur, bukan tingkatan paket, jadi tidak ada yang perlu di-upgrade atau diganti.

Ada dua jenis:

• Kunci cloud Anda sendiri. Kunci dari penyedia model, disimpan sekali ke akun Anda dan dapat dipakai dari Web, Desktop, dan CLI.
• Endpoint Anda sendiri. Apa pun yang mendukung API yang kompatibel dengan OpenAI, termasuk model yang berjalan di komputer Anda sendiri. Model di komputer Anda sendiri hanya untuk CLI, dengan alasan yang dijelaskan di Endpoint lokal.

Kunci cloud Anda sendiri

Atur ini sekali di web dan kunci akan mengikuti akun Anda ke mana pun, karena kunci disimpan di sisi server pada akun Anda, bukan di satu perangkat. Kunci dienkripsi saat disimpan dan tidak pernah dikirim kembali ke browser setelah Anda menyimpannya.

1. Buka Settings → Models & Keys.
2. Pilih penyedia Anda dari daftar dan tempelkan kunci API Anda.
3. Tekan Test. Langkah ini menjalankan satu permintaan sungguhan yang sangat kecil dengan kunci Anda dan melaporkan apakah permintaan itu berhasil dan apakah model dapat memanggil tool.
4. Tekan Save.
5. Tekan Use for chat pada kunci yang sudah disimpan.

Langkah 5 adalah yang sering terlewat. Menyimpan kunci hanya menyimpannya; justru Use for chat yang benar-benar mengarahkan giliran Anda melalui kunci itu. Saat aktif, pemilih model di kolom pesan diganti dengan Your key · <provider>, dan Settings memberi tahu bahwa chat berjalan dengan kunci Anda dan tidak diukur penggunaannya.

Untuk kembali ke model yang di-host oleh Perch, nonaktifkan Use for chat. Kunci Anda tetap tersimpan.

Kunci dipakai bersama di seluruh akun Anda, tetapi pilihan untuk memakainya berlaku per perangkat. Mengaktifkannya di browser tidak mengaktifkannya di CLI, begitu pula sebaliknya. Ini disengaja: Anda bisa menjalankan satu terminal dengan kunci Anda sendiri sementara sesi Anda yang lain tetap memakai Perch.

Penyedia apa pun, model apa pun

Jika penyedia Anda tidak ada di daftar, pilih Custom (OpenAI-compatible) dan berikan tiga hal kepada Perch:

Model id diteruskan tanpa diubah, jadi model yang belum pernah dikenal Perch tetap berfungsi selama endpoint Anda menyediakannya. Salin id persis dari dokumentasi penyedia Anda, termasuk prefiks apa pun.

Dua persyaratan yang akan diberlakukan oleh formulir:

• Base URL harus memakai https dan harus berupa alamat publik. Apa pun yang berada di jaringan privat atau internal ditolak, termasuk localhost. Komputer Anda sendiri tidak dapat dijangkau dari server kami, jadi gunakan jalur CLI di bawah untuk itu.
• Model harus mendukung tool calling. Perch bekerja dengan membaca file, menjalankan perintah, dan memanggil tool; model yang tidak mampu melakukannya akan gagal di tengah pekerjaan sungguhan, bukan di awal. Jika model tercantum di katalog model publik dan katalog tersebut menyatakan model itu tidak dapat memanggil tool, penyimpanan ditolak dengan pesan yang menjelaskannya. Model yang tidak dikenal katalog tetap diizinkan, karena sebagian besar model yang lebih baru dan model privat belum tercantum.

Jika katalog mengenali model Anda, Perch juga mengambil jendela konteks sebenarnya dari model tersebut, sehingga model dengan konteks panjang mendapatkan jendela penuhnya, bukan nilai default yang konservatif.

Desktop

Desktop masuk ke akun yang sama, jadi kunci yang disimpan di web sudah tersedia di sana. Panel yang sama ada di aplikasi di bawah Settings → Models & Keys, dan perilakunya identik.

Satu hal yang tidak ikut terbawa adalah pilihan Use for chat, yang berlaku per perangkat. Aktifkan sekali di aplikasi.

Model yang berjalan di komputer Anda sendiri saat ini hanya untuk CLI. Lihat Endpoint lokal.

CLI

CLI masuk ke akun yang sama, jadi kunci apa pun yang Anda simpan di web sudah tersedia untuknya. Memilih salah satunya adalah langkah terpisah, karena pilihan itu berlaku per perangkat:

perch byok list                  # keys saved on your account
perch byok use openai            # run this terminal's turns on that key
perch byok status                # what turns are running on right now
perch byok off                   # back to Perch-hosted models

Di dalam sesi, /byok melakukan hal yang sama: /byok saja melaporkan apa yang sedang Anda pakai, /byok <provider> berpindah, dan /byok off kembali. perch status dan /status sama-sama memuat baris byok.

Anda juga bisa mengelola kunci itu sendiri tanpa meninggalkan terminal:

perch byok set openai --key sk-...                     # save a key to your account
perch byok set custom --key sk-... \
  --url https://api.example.com/v1 --model acme/model-x  # your own endpoint
perch byok test [provider]                             # probe it with one real request
perch byok remove openai                               # delete the saved key

Kunci dikirim ke akun Anda dan dienkripsi di sana, persis seperti yang dilakukan panel web. Tidak ada yang ditulis ke komputer tempat Anda mengetiknya selain pilihan penyedia Anda.

Model di komputer Anda sendiri

Untuk ini perintahnya berbeda, karena endpoint tetap berada di perangkat Anda:

perch byolm set <baseUrl> <modelId> [--key <key>]
perch byolm status
perch byolm test
perch byolm clear

Contohnya, dengan Ollama:

perch byolm set http://localhost:11434/v1 llama3.1
perch byolm test

--key bersifat opsional; sebagian besar runtime lokal tidak memerlukannya, dan Perch akan menghilangkan header otorisasi sepenuhnya alih-alih mengirim nilai pengganti.

perch byolm test mengirim satu permintaan kecil dan melaporkan apakah endpoint menjawab dan apakah model memanggil tool. Jalankan sebelum pekerjaan sungguhan: jika tidak, model lokal yang tidak dapat memanggil tool akan tampak berfungsi lalu macet saat pertama kali membaca file.

Endpoint lokal

Endpoint lokal berada di komputer Anda, sehingga hanya dikonfigurasi dari CLI, tidak pernah dari web atau aplikasi desktop. Ini bukan batasan yang kami pilih demi kemudahan: keduanya menjalankan panggilan model melalui server kami, dan server kami tidak dapat menjangkau localhost di komputer Anda. CLI menjalankan panggilan dalam prosesnya sendiri di komputer Anda, satu-satunya tempat endpoint lokal benar-benar dapat dijangkau. Menyimpannya di sana juga berarti alamat dan kunci apa pun tidak pernah meninggalkan komputer Anda.

Apa pun yang kompatibel dengan OpenAI dapat dipakai, termasuk Ollama, LM Studio, server llama.cpp, dan vLLM.

Dukungan Desktop untuk model lokal belum dirilis. Sampai saat itu, gunakan CLI, atau gunakan kunci cloud di aplikasi.

Apa yang berubah saat Anda memakai kunci sendiri

• Pengukuran penggunaan. Giliran dengan kunci Anda tidak dihitung terhadap Perch Token yang sudah termasuk dalam paket Anda, dan tidak ada tagihan Perch Token yang muncul untuknya.
• Routing model. Perch hanya melakukan routing ke penyedia Anda. Perch tidak akan pernah diam-diam beralih ke model yang di-host oleh Perch, karena itu berarti mengirim prompt Anda ke tempat yang tidak Anda pilih dan menagih Anda untuknya. Jika endpoint Anda sedang tidak aktif, giliran tersebut gagal dan menyatakannya.
• Pemilihan model. Pemilih tingkatan Roost tidak berlaku, karena Perch tidak lagi memilihkan model untuk Anda.
• Selebihnya. Ruang kerja, memori, retrieval, pemeriksaan sitasi, dan bagian harness lainnya bekerja persis sama seperti pada model yang di-host.

Pemecahan masalah

"Your key was accepted, but no model this workspace can run is available." Kuncinya valid, tetapi tidak ada model di penyedia tersebut yang saat ini dapat di-routing untuk akun Anda. Ini adalah versi jujur dari tes yang gagal, dan artinya giliran sungguhan juga akan gagal. Coba penyedia lain, atau gunakan Custom dan sebutkan model secara eksplisit.

Tombol Test lolos, tetapi giliran sungguhan gagal. Laporkan masalah ini. Tes yang lolos seharusnya melakukan routing persis ke tempat yang sama dengan giliran sungguhan, jadi ketidakcocokan khusus ini adalah bug di pihak kami, bukan sesuatu yang perlu Anda akali.

"...does not support tool calling." Katalog publik mencantumkan model itu sebagai tidak mampu memanggil tool, jadi Perch menolak menyimpannya alih-alih membiarkannya gagal di tengah tugas. Pilih model yang mendukung tool calling atau function calling; sebagian besar model instruct dan model coding saat ini mendukungnya.

Endpoint lokal tidak bisa disimpan di web. Itu memang seharusnya. Gunakan perch byolm set di CLI.

Giliran masih memakai model Perch. Pastikan kunci sudah dipilih di perangkat yang sedang Anda pakai. Menyimpan kunci tidak mengarahkan giliran: di aplikasi, yang melakukannya adalah Use for chat, dan di terminal adalah perch byok use <provider>. perch byok status dan /status sama-sama menunjukkan mana yang sedang Anda pakai.

Terkait

• Model menjelaskan apa saja yang ada di kumpulan model yang di-host dan apa yang termasuk dalam setiap paket.
• Perch Roost menjelaskan routing model yang di-host, yang digantikan oleh kunci Anda.
• CLI membahas bagian lain dari command line.