Dùng khóa API của riêng bạn

Chạy Perch bằng khóa mô hình hoặc endpoint của riêng bạn, trên mọi gói kể cả gói miễn phí. Thiết lập cho Web, Desktop và CLI, cùng cách tính với mức sử dụng đi kèm.

Perch có thể chạy bằng thông tin xác thực mô hình của bạn thay vì của chúng tôi. Mức sử dụng bằng khóa của bạn không được tính vào Perch Token đi kèm, nên mức sử dụng đi kèm hằng tháng được giữ nguyên khi bạn dùng khóa đó.

Tính năng này có trên mọi gói, kể cả gói miễn phí. Đây là tính năng, không phải cấp gói, nên không cần nâng cấp hay chuyển sang gói nào.

Có hai loại:

Khóa đám mây của riêng bạn. Khóa từ nhà cung cấp mô hình, lưu một lần vào tài khoản và dùng được từ Web, Desktop và CLI.
Endpoint của riêng bạn. Bất cứ thứ gì dùng API tương thích với OpenAI, kể cả mô hình chạy trên máy của bạn. Mô hình trên máy của bạn chỉ dùng được với CLI, vì lý do nêu trong Endpoint cục bộ.

Khóa đám mây của riêng bạn

Thiết lập một lần trên web và khóa sẽ khả dụng ở mọi nơi bạn dùng tài khoản, vì khóa được lưu ở phía máy chủ gắn với tài khoản chứ không phải trên một thiết bị. Khóa được mã hóa khi lưu trữ và không bao giờ gửi lại trình duyệt sau khi bạn lưu.

Vào Settings → Models & Keys.
Chọn nhà cung cấp từ danh sách và dán khóa API.
Nhấn Test. Thao tác này gửi một yêu cầu thực, rất nhỏ bằng khóa của bạn và báo liệu có thành công hay không và mô hình có thể gọi công cụ hay không.
Nhấn Save.
Nhấn Use for chat trên khóa đã lưu.

Bước 5 là bước mọi người hay bỏ sót. Lưu khóa chỉ lưu trữ khóa; Use for chat mới thực sự định tuyến các lượt qua khóa đó. Khi bật, bộ chọn mô hình trong ô soạn tin được thay bằng Your key · <provider>, và Settings cho biết trò chuyện đang chạy bằng khóa của bạn và không được đo mức sử dụng.

Để trở lại mô hình do Perch lưu trữ, tắt Use for chat. Khóa của bạn vẫn được lưu.

Khóa được dùng chung trong tài khoản, nhưng lựa chọn sử dụng là riêng cho từng thiết bị. Bật trong trình duyệt không bật trong CLI, và ngược lại. Đây là chủ ý: bạn có thể chạy một terminal bằng khóa của riêng mình trong khi phần còn lại của phiên vẫn dùng Perch.

Mọi nhà cung cấp, mọi mô hình

Nếu nhà cung cấp không có trong danh sách, chọn Custom (OpenAI-compatible) và cung cấp ba thông tin cho Perch:

Trường	Ví dụ
Base URL	`https://api.example.com/v1`
API key	khóa của bạn
Model id	chính xác như tên nhà cung cấp đặt

Mã định danh mô hình được truyền qua nguyên vẹn, nên mô hình Perch chưa từng biết vẫn hoạt động miễn là endpoint của bạn cung cấp nó. Sao chép chính xác mã định danh từ tài liệu nhà cung cấp, bao gồm mọi tiền tố.

Biểu mẫu sẽ kiểm tra hai yêu cầu:

URL cơ sở phải là https và phải là địa chỉ công khai. Mọi địa chỉ trên mạng riêng hoặc nội bộ đều bị từ chối, kể cả localhost. Máy của bạn không thể được truy cập từ máy chủ của chúng tôi, nên hãy dùng cách qua CLI bên dưới.
Mô hình phải hỗ trợ gọi công cụ. Perch hoạt động bằng cách đọc tệp, chạy lệnh và gọi công cụ; mô hình không làm được sẽ gặp lỗi giữa chừng khi làm việc thực tế thay vì ngay từ đầu. Khi mô hình có trong danh mục mô hình công khai và danh mục nói nó không thể gọi công cụ, việc lưu bị từ chối kèm thông báo nêu rõ điều đó. Mô hình chưa có trong danh mục vẫn được chấp nhận, vì phần lớn mô hình mới và riêng chưa được liệt kê.

Khi danh mục biết mô hình của bạn, Perch cũng lấy cửa sổ ngữ cảnh thực của nó, nên mô hình ngữ cảnh dài có toàn bộ cửa sổ thay vì giá trị mặc định thận trọng.

Desktop

Desktop đăng nhập cùng tài khoản, nên khóa lưu trên web đã có sẵn. Cùng bảng đó nằm trong ứng dụng tại Settings → Models & Keys và hoạt động giống hệt.

Điều duy nhất không chuyển sang là lựa chọn Use for chat, vì lựa chọn này riêng cho từng thiết bị. Bật một lần trong ứng dụng.

Hiện mô hình chạy trên máy của bạn chỉ dùng được với CLI. Xem Endpoint cục bộ.

CLI

CLI đăng nhập cùng tài khoản, nên mọi khóa bạn đã lưu trên web đều có sẵn. Chọn khóa là bước riêng vì lựa chọn riêng cho từng thiết bị:

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

Trong phiên, /byok làm cùng việc: riêng /byok báo bạn đang dùng gì, /byok <provider> chuyển đổi và /byok off quay lại. Cả perch status và /status đều có dòng byok.

Bạn cũng có thể quản lý các khóa mà không rời 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

Khóa được gửi đến tài khoản và mã hóa ở đó, giống hệt cách bảng trên web thực hiện. Chỉ lựa chọn nhà cung cấp được ghi lên máy bạn nhập lệnh.

Mô hình trên máy của bạn

Đó là lệnh khác, vì endpoint nằm trên thiết bị của bạn:

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

Ví dụ với Ollama:

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

--key là tùy chọn; phần lớn môi trường chạy cục bộ không cần khóa, và Perch bỏ hoàn toàn header xác thực thay vì gửi giá trị thay thế.

perch byolm test gửi một yêu cầu nhỏ và báo liệu endpoint đã trả lời hay chưa và mô hình đã gọi công cụ hay chưa. Chạy trước khi làm việc thực tế: nếu không, mô hình cục bộ không gọi được công cụ sẽ có vẻ hoạt động rồi mắc kẹt ngay ở lần đọc tệp đầu tiên.

Endpoint cục bộ

Endpoint cục bộ nằm trên máy của bạn, nên chỉ được cấu hình từ CLI, không bao giờ từ web hay ứng dụng máy tính. Đây không phải giới hạn được chọn vì sự tiện lợi: cả hai đều thực hiện lệnh gọi mô hình qua máy chủ của chúng tôi, và máy chủ không thể truy cập localhost trên máy tính của bạn. CLI chạy lệnh gọi trong tiến trình riêng trên máy bạn, là nơi duy nhất có thể thực sự truy cập endpoint cục bộ. Giữ cấu hình ở đó cũng có nghĩa địa chỉ và mọi khóa không bao giờ rời máy của bạn.

Mọi thứ tương thích với OpenAI đều hoạt động, bao gồm Ollama, LM Studio, máy chủ của llama.cpp và vLLM.

Hỗ trợ mô hình cục bộ trên Desktop chưa được phát hành. Cho đến khi có, hãy dùng CLI hoặc khóa đám mây trong ứng dụng.

Điều gì thay đổi khi dùng khóa của riêng bạn

Đo mức sử dụng. Các lượt dùng khóa của bạn không được tính vào Perch Token đi kèm và không xuất hiện khoản tính phí Perch Token cho chúng.
Định tuyến mô hình. Perch chỉ định tuyến đến nhà cung cấp của bạn. Perch không bao giờ âm thầm chuyển sang mô hình do Perch lưu trữ, vì làm vậy sẽ gửi prompt đến nơi bạn không chọn và tính phí cho bạn. Nếu endpoint ngừng hoạt động, lượt gặp lỗi và báo rõ.
Chọn mô hình. Bộ chọn cấp Roost không áp dụng vì Perch không còn chọn mô hình thay bạn.
Mọi thứ khác. Không gian làm việc, bộ nhớ, truy xuất, kiểm tra trích dẫn và phần còn lại của harness hoạt động giống hệt như với mô hình do Perch lưu trữ.

Khắc phục sự cố

"Your key was accepted, but no model this workspace can run is available." Khóa hợp lệ, nhưng hiện không có mô hình nào của nhà cung cấp đó có thể được định tuyến cho tài khoản của bạn. Đây là thông báo đúng thực trạng khi kiểm tra thất bại, và nghĩa là các lượt thực cũng sẽ thất bại. Thử nhà cung cấp khác hoặc dùng Custom và nêu rõ mô hình.

Nút Test báo thành công nhưng các lượt thực thất bại. Hãy báo lỗi. Kiểm tra thành công phải định tuyến chính xác đến nơi lượt thực định tuyến, nên sự không khớp cụ thể này là lỗi phía chúng tôi chứ không phải điều bạn cần tìm cách khắc phục vòng ngoài.

"...does not support tool calling." Danh mục công khai liệt kê mô hình đó là không thể gọi công cụ, nên Perch từ chối lưu thay vì để nó thất bại giữa tác vụ. Chọn mô hình hỗ trợ gọi công cụ hoặc hàm; phần lớn mô hình làm theo chỉ dẫn và lập trình hiện tại đều hỗ trợ.

Không lưu được endpoint cục bộ trên web. Đó là hành vi dự kiến. Dùng perch byolm set trên CLI.

Các lượt vẫn dùng mô hình Perch. Kiểm tra rằng khóa đã được chọn trên thiết bị bạn đang làm việc. Lưu khóa không định tuyến các lượt: trong ứng dụng là Use for chat, còn trong terminal là perch byok use <provider>. Cả perch byok status và /status đều cho biết bạn đang dùng lựa chọn nào.

Mô hình trình bày các mô hình trong nhóm do Perch lưu trữ và những gì từng gói bao gồm.
Perch Roost giải thích định tuyến mô hình do Perch lưu trữ, là phần khóa của bạn thay thế.
CLI trình bày phần còn lại của dòng lệnh.

Dùng khóa API của riêng bạn

Trên trang này