ใช้คีย์ API ของคุณเอง

Perch รันด้วยข้อมูลรับรองตัวตนสำหรับโมเดลของคุณเองแทนของเราได้ การใช้งานบนคีย์ของคุณเองไม่ถูกนับรวมใน Perch Token ที่รวมอยู่ในแพ็กเกจของคุณ การใช้งานรายเดือนที่รวมอยู่ในแพ็กเกจจึงไม่ถูกแตะเลยระหว่างที่คุณใช้คีย์นั้น

ความสามารถนี้ใช้ได้ใน ทุกแพ็กเกจ รวมถึงแพ็กเกจฟรี นี่เป็นฟีเจอร์ ไม่ใช่ระดับแพ็กเกจ จึงไม่มีอะไรต้องอัปเกรดหรือเปลี่ยนไปใช้

มีสองแบบ

• คีย์บนคลาวด์ของคุณเอง คีย์จากผู้ให้บริการโมเดล ที่บันทึกไว้ในบัญชีของคุณครั้งเดียวและใช้ได้จากเว็บ เดสก์ท็อป และ CLI
• endpoint ของคุณเอง อะไรก็ได้ที่ใช้ API ที่เข้ากันได้กับ OpenAI รวมถึงโมเดลที่รันบนเครื่องของคุณเอง โมเดลบนเครื่องของคุณเองใช้ได้เฉพาะ CLI ด้วยเหตุผลที่อธิบายไว้ในendpoint ในเครื่อง

คีย์บนคลาวด์ของคุณเอง

ตั้งค่าครั้งเดียวบนเว็บ แล้วคีย์จะตามบัญชีของคุณไปทุกที่ เพราะคีย์ถูกเก็บไว้ฝั่งเซิร์ฟเวอร์โดยผูกกับบัญชีของคุณ ไม่ได้เก็บไว้บนอุปกรณ์เครื่องเดียว คีย์ถูกเข้ารหัสขณะจัดเก็บ และจะไม่ถูกส่งกลับไปยังเบราว์เซอร์อีกเลยหลังจากคุณบันทึก

1. ไปที่ Settings → Models & Keys
2. เลือกผู้ให้บริการของคุณจากรายการ แล้ววางคีย์ API ของคุณ
3. กด Test ขั้นตอนนี้จะส่งคำขอจริงขนาดเล็กมากหนึ่งครั้งด้วยคีย์ของคุณ แล้วรายงานว่าใช้ได้หรือไม่ และโมเดลเรียกใช้เครื่องมือได้หรือไม่
4. กด Save
5. กด Use for chat บนคีย์ที่บันทึกไว้

ขั้นตอนที่ 5 คือขั้นตอนที่คนมักพลาด การบันทึกคีย์เป็นแค่การเก็บคีย์ไว้ ส่วน Use for chat คือสิ่งที่ทำให้เทิร์นของคุณถูก routing ผ่านคีย์นั้นจริงๆ เมื่อเปิดอยู่ ตัวเลือกโมเดลในช่องพิมพ์ข้อความจะถูกแทนที่ด้วย Your key · <provider> และ Settings จะบอกคุณว่าแชตกำลังรันบนคีย์ของคุณและไม่ถูกวัดตามปริมาณการใช้งาน

หากต้องการกลับไปใช้โมเดลที่ Perch โฮสต์ ให้ปิด Use for chat คีย์ของคุณจะยังบันทึกอยู่

คีย์ใช้ร่วมกันทั้งบัญชี แต่การเลือกใช้คีย์เป็นการตั้งค่าแยกตามอุปกรณ์ การเปิดใช้ในเบราว์เซอร์ไม่ได้เปิดใช้ใน CLI ด้วย และในทางกลับกันก็เช่นกัน นี่เป็นความตั้งใจ เพราะช่วยให้คุณรันเทอร์มินัลตัวหนึ่งบนคีย์ของคุณเองได้ ขณะที่ส่วนที่เหลือของเซสชันยังใช้ Perch อยู่

ผู้ให้บริการใดก็ได้ โมเดลใดก็ได้

ถ้าผู้ให้บริการของคุณไม่อยู่ในรายการ ให้เลือก Custom (OpenAI-compatible) แล้วระบุข้อมูลสามอย่างให้ Perch

model id จะถูกส่งต่อไปโดยไม่มีการแก้ไข โมเดลที่ Perch ไม่เคยรู้จักจึงใช้ได้ ตราบใดที่ endpoint ของคุณให้บริการโมเดลนั้น คัดลอก id จากเอกสารของผู้ให้บริการให้ตรงทุกตัวอักษร รวมถึง prefix ใดๆ ที่มี

มีข้อกำหนดสองข้อที่ฟอร์มจะบังคับใช้

• base URL ต้องเป็น https และต้องเป็นแอดเดรสสาธารณะ อะไรก็ตามที่อยู่บนเครือข่ายส่วนตัวหรือเครือข่ายภายในจะถูกปฏิเสธ รวมถึง localhost เซิร์ฟเวอร์ของเราเข้าถึงเครื่องของคุณเองไม่ได้ สำหรับกรณีนั้นให้ใช้วิธีผ่าน CLI ด้านล่าง
• โมเดลต้องรองรับการเรียกใช้เครื่องมือ Perch ทำงานด้วยการอ่านไฟล์ รันคำสั่ง และเรียกใช้เครื่องมือ โมเดลที่ทำสิ่งเหล่านี้ไม่ได้จะล้มเหลวกลางคันระหว่างทำงานจริง ไม่ใช่ตั้งแต่เริ่มต้น หากโมเดลอยู่ในแค็ตตาล็อกโมเดลสาธารณะ และแค็ตตาล็อกนั้นระบุว่าโมเดลเรียกใช้เครื่องมือไม่ได้ ระบบจะไม่ยอมบันทึกและแสดงข้อความแจ้งว่าเป็นเช่นนั้น โมเดลที่แค็ตตาล็อกไม่รู้จักจะได้รับอนุญาตให้ผ่าน เพราะโมเดลที่ใหม่กว่าและโมเดลส่วนตัวส่วนใหญ่ยังไม่อยู่ในรายการ

เมื่อแค็ตตาล็อกรู้จักโมเดลของคุณ Perch จะใช้ขนาด context window จริงของโมเดลนั้นด้วย โมเดลที่รองรับบริบทยาวจึงได้ใช้ context window เต็มขนาด แทนที่จะได้ค่าเริ่มต้นแบบระมัดระวัง

เดสก์ท็อป

แอปเดสก์ท็อปลงชื่อเข้าใช้บัญชีเดียวกัน คีย์ที่บันทึกไว้บนเว็บจึงอยู่ในแอปแล้ว แผงเดียวกันอยู่ในแอปที่ Settings → Models & Keys และทำงานเหมือนกันทุกอย่าง

สิ่งเดียวที่ไม่ตามมาด้วยคือการเลือก Use for chat ซึ่งเป็นการตั้งค่าแยกตามอุปกรณ์ เปิดใช้ครั้งเดียวในแอป

ปัจจุบันโมเดลที่รันบนเครื่องของคุณเองใช้ได้เฉพาะ CLI ดูendpoint ในเครื่อง

CLI

CLI ลงชื่อเข้าใช้บัญชีเดียวกัน คีย์ใดก็ตามที่คุณบันทึกไว้บนเว็บจึงพร้อมให้ CLI ใช้อยู่แล้ว การเลือกคีย์เป็นอีกขั้นตอนหนึ่งแยกต่างหาก เพราะการเลือกเป็นการตั้งค่าแยกตามอุปกรณ์

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

ภายในเซสชัน /byok ทำสิ่งเดียวกัน โดย /byok อย่างเดียวจะรายงานว่าคุณกำลังรันบนอะไร /byok <provider> ใช้สลับ และ /byok off ใช้สลับกลับ ทั้ง perch status และ /status มีแถว byok

คุณยังจัดการตัวคีย์เองได้โดยไม่ต้องออกจากเทอร์มินัล

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

คีย์จะถูกส่งไปยังบัญชีของคุณและเข้ารหัสที่นั่น เหมือนกับที่แผงบนเว็บทำทุกประการ สิ่งเดียวที่ถูกเขียนลงเครื่องที่คุณใช้พิมพ์คีย์คือผู้ให้บริการที่คุณเลือก

โมเดลบนเครื่องของคุณเอง

กรณีนี้ใช้คำสั่งอื่น เพราะ endpoint ยังคงอยู่บนอุปกรณ์ของคุณ

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

ตัวอย่างเช่น กับ Ollama

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

--key จะใส่หรือไม่ก็ได้ runtime ในเครื่องส่วนใหญ่ไม่ต้องใช้คีย์ และ Perch จะไม่ใส่ authorization header เลย แทนที่จะส่งค่า placeholder ไป

perch byolm test จะส่งคำขอเล็กๆ หนึ่งครั้ง แล้วรายงานว่า endpoint ตอบกลับหรือไม่ และโมเดลเรียกใช้เครื่องมือหรือไม่ ให้รันคำสั่งนี้ก่อนเริ่มงานจริง ไม่เช่นนั้นโมเดลในเครื่องที่เรียกใช้เครื่องมือไม่ได้จะดูเหมือนใช้งานได้ แล้วไปค้างตอนอ่านไฟล์ครั้งแรก

endpoint ในเครื่อง

endpoint ในเครื่องอยู่บนเครื่องของคุณ จึงตั้งค่าได้จาก CLI เท่านั้น ไม่ใช่จากเว็บหรือแอปเดสก์ท็อปเลย นี่ไม่ใช่ข้อจำกัดที่เราเลือกเพราะความสะดวก ทั้งเว็บและแอปเดสก์ท็อปส่งการเรียกโมเดลผ่านเซิร์ฟเวอร์ของเรา และเซิร์ฟเวอร์ของเราเข้าถึง localhost บนคอมพิวเตอร์ของคุณไม่ได้ ส่วน CLI รันการเรียกโมเดลในโปรเซสของตัวเองบนเครื่องของคุณ ซึ่งเป็นที่เดียวที่เข้าถึง endpoint ในเครื่องได้จริง การเก็บไว้ที่นั่นยังหมายความว่าแอดเดรสและคีย์ใดๆ จะไม่ออกไปจากเครื่องของคุณ

อะไรก็ได้ที่เข้ากันได้กับ OpenAI ใช้ได้ทั้งหมด รวมถึง Ollama, LM Studio, เซิร์ฟเวอร์ของ llama.cpp และ vLLM

การรองรับโมเดลในเครื่องบนเดสก์ท็อปยังไม่เปิดให้ใช้ ระหว่างนี้ให้ใช้ CLI หรือใช้คีย์บนคลาวด์ในแอป

สิ่งที่เปลี่ยนไปเมื่อคุณใช้คีย์ของคุณเอง

• การวัดการใช้งาน เทิร์นที่ใช้คีย์ของคุณไม่ถูกนับรวมใน Perch Token ที่รวมอยู่ในแพ็กเกจของคุณ และจะไม่มีค่าใช้จ่าย Perch Token ปรากฏสำหรับเทิร์นเหล่านั้น
• การ routing โมเดล Perch จะ routing ไปยังผู้ให้บริการของคุณเท่านั้น และจะไม่สลับกลับไปใช้โมเดลที่ Perch โฮสต์แบบเงียบๆ เด็ดขาด เพราะนั่นจะส่งพรอมต์ของคุณไปยังที่ที่คุณไม่ได้เลือก และเรียกเก็บเงินคุณสำหรับสิ่งนั้น ถ้า endpoint ของคุณล่ม เทิร์นนั้นจะล้มเหลวและแจ้งให้ทราบ
• การเลือกโมเดล ตัวเลือกระดับของ Roost ไม่มีผล เพราะ Perch ไม่ได้เป็นฝ่ายเลือกโมเดลให้คุณแล้ว
• ทุกอย่างที่เหลือ เวิร์กสเปซ หน่วยความจำ การดึงข้อมูล การตรวจสอบการอ้างอิง และส่วนอื่นๆ ของ harness ทำงานเหมือนกับบนโมเดลแบบโฮสต์ทุกประการ

การแก้ปัญหา

"Your key was accepted, but no model this workspace can run is available." (คีย์ของคุณได้รับการยอมรับ แต่ไม่มีโมเดลที่เวิร์กสเปซนี้รันได้) คีย์ถูกต้อง แต่ตอนนี้ไม่มีโมเดลใดบนผู้ให้บริการนั้นที่ routing ให้บัญชีของคุณได้ นี่คือการบอกตามจริงว่าการทดสอบล้มเหลว และหมายความว่าเทิร์นจริงก็จะล้มเหลวด้วย ลองใช้ผู้ให้บริการอื่น หรือใช้ Custom แล้วระบุชื่อโมเดลให้ชัดเจน

ปุ่ม Test ผ่าน แต่เทิร์นจริงล้มเหลว โปรดรายงานปัญหานี้ การทดสอบที่ผ่านควร routing ไปยังที่เดียวกับที่เทิร์นจริง routing ไปทุกประการ ความไม่ตรงกันแบบนี้จึงเป็นบั๊กฝั่งเรา ไม่ใช่สิ่งที่คุณต้องหาทางเลี่ยง

"...does not support tool calling." (...ไม่รองรับการเรียกใช้เครื่องมือ) แค็ตตาล็อกสาธารณะระบุว่าโมเดลนั้นเรียกใช้เครื่องมือไม่ได้ Perch จึงไม่บันทึกโมเดลนั้น แทนที่จะปล่อยให้ล้มเหลวกลางงาน เลือกโมเดลที่รองรับการเรียกใช้เครื่องมือหรือ function calling โมเดล instruct และโมเดลเขียนโค้ดรุ่นปัจจุบันส่วนใหญ่รองรับ

บันทึก endpoint ในเครื่องบนเว็บไม่ได้ เป็นเรื่องที่คาดไว้อยู่แล้ว ใช้ perch byolm set บน CLI

เทิร์นยังใช้โมเดลของ Perch อยู่ ตรวจสอบว่าได้เลือกคีย์ไว้บนอุปกรณ์ที่คุณกำลังใช้ทำงาน การบันทึกคีย์ไม่ได้ทำให้เทิร์นถูก routing ผ่านคีย์ ในแอปต้องใช้ Use for chat และในเทอร์มินัลต้องใช้ perch byok use <provider> ทั้ง perch byok status และ /status จะบอกว่าคุณกำลังใช้อะไรอยู่

หน้าที่เกี่ยวข้อง

• โมเดล อธิบายว่ามีอะไรอยู่ในกลุ่มโมเดลแบบโฮสต์ และแต่ละแพ็กเกจรวมอะไรไว้บ้าง
• Perch Roost อธิบายการ routing แบบโฮสต์ ซึ่งเป็นสิ่งที่คีย์ของคุณเข้ามาแทน
• CLI อธิบายส่วนที่เหลือของ command line