Usar tu propia clave de API

Perch puede funcionar con tus propias credenciales de modelo en lugar de las nuestras. El uso con tu propia clave no se descuenta de tus Perch Tokens incluidos, así que tu uso incluido mensual queda intacto mientras la usas.

Está disponible en todos los planes, incluido el gratis. Es una función, no un nivel, así que no hay nada a lo que cambiarte ni que mejorar.

Hay dos tipos:

• Tu propia clave en la nube. Una clave de un proveedor de modelos, que guardas una vez en tu cuenta y puedes usar desde Web, escritorio y CLI.
• Tu propio endpoint. Cualquier cosa que hable la API compatible con OpenAI, incluido un modelo que se ejecuta en tu propia máquina. Un modelo en tu propia máquina es exclusivo de la CLI, por la razón que se explica en Endpoints locales.

Tu propia clave en la nube

Configúrala una vez en la web y te acompaña en toda tu cuenta, porque la clave se guarda en el servidor asociada a tu cuenta y no en un solo dispositivo. Se almacena cifrada y nunca se vuelve a enviar al navegador después de que la guardas.

1. Ve a Settings → Models & Keys.
2. Elige tu proveedor de la lista y pega tu clave de API.
3. Presiona Test. Esto hace una solicitud real y muy pequeña con tu clave e indica si funcionó y si el modelo puede llamar herramientas.
4. Presiona Save.
5. Presiona Use for chat en la clave guardada.

El paso 5 es el que la gente se salta. Guardar una clave la almacena; Use for chat es lo que realmente enruta tus turnos a través de ella. Cuando está activado, el selector de modelos del cuadro de mensaje se reemplaza por Your key · <provider>, y Settings te indica que el chat se está ejecutando con tu clave y que no se mide.

Para volver a los modelos alojados por Perch, desactiva Use for chat. Tu clave sigue guardada.

La clave se comparte en toda tu cuenta, pero la decisión de usarla es por dispositivo. Activarla en el navegador no la activa en la CLI, y viceversa. Es intencional: te permite usar tu propia clave en una terminal mientras el resto de tu sesión sigue en Perch.

Cualquier proveedor, cualquier modelo

Si tu proveedor no está en la lista, elige Custom (OpenAI-compatible) y dale a Perch tres datos:

El id del modelo se pasa sin cambios, así que un modelo del que Perch nunca ha oído hablar funciona siempre que tu endpoint lo sirva. Copia el id exactamente como aparece en la documentación de tu proveedor, incluido cualquier prefijo.

El formulario exige dos requisitos:

• La URL base debe usar https y debe ser una dirección pública. Se rechaza cualquier cosa en una red privada o interna, incluido localhost. Nuestros servidores no pueden llegar a tu propia máquina, así que para eso usa la ruta de la CLI que se describe abajo.
• El modelo debe admitir llamadas a herramientas. Perch funciona leyendo archivos, ejecutando comandos y llamando herramientas; un modelo que no puede hacerlo falla a mitad del trabajo real y no al principio. Cuando el modelo está en el catálogo público de modelos y ese catálogo dice que no puede llamar herramientas, se rechaza el guardado con un mensaje que lo indica. Los modelos que el catálogo no conoce se permiten, porque la mayoría de los modelos más nuevos y privados todavía no aparecen.

Cuando el catálogo sí conoce tu modelo, Perch también toma su ventana de contexto real, así que un modelo de contexto largo obtiene su ventana completa en lugar de un valor predeterminado conservador.

Desktop

Desktop inicia sesión en la misma cuenta, así que una clave guardada en la web ya está ahí. El mismo panel está en la app, en Settings → Models & Keys, y funciona de la misma forma.

Lo único que no se transfiere es la opción Use for chat, que es por dispositivo. Actívala una vez en la app.

Por ahora, un modelo que se ejecuta en tu propia máquina es exclusivo de la CLI. Consulta Endpoints locales.

CLI

La CLI inicia sesión en la misma cuenta, así que cualquier clave que guardaste en la web ya está disponible. Seleccionarla es un paso aparte, porque la elección es por dispositivo:

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

Dentro de una sesión, /byok hace lo mismo: /byok solo indica con qué estás trabajando, /byok <provider> cambia de proveedor y /byok off vuelve atrás. perch status y /status incluyen una fila byok.

También puedes administrar las claves sin salir de la 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

La clave se envía a tu cuenta y se cifra ahí, exactamente igual que con el panel web. En la máquina donde la escribiste solo se guarda tu elección de proveedor.

Un modelo en tu propia máquina

Ese es otro comando, porque el endpoint se queda en tu dispositivo:

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

Por ejemplo, con Ollama:

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

--key es opcional; la mayoría de los entornos de ejecución locales no lo necesitan, y Perch omite por completo el encabezado de autorización en lugar de enviar un valor de relleno.

perch byolm test envía una solicitud pequeña e indica si el endpoint respondió y si el modelo llamó una herramienta. Ejecútalo antes del trabajo real: de lo contrario, un modelo local que no puede llamar herramientas parecerá funcionar y luego se trabará en la primera lectura de archivos.

Endpoints locales

Un endpoint local vive en tu máquina, así que se configura solo desde la CLI, nunca desde la web ni desde la app de escritorio. No es una limitación que elegimos por comodidad: ambas ejecutan sus llamadas a modelos a través de nuestros servidores, y nuestros servidores no pueden llegar a localhost en tu computadora. La CLI hace la llamada en su propio proceso en tu máquina, que es el único lugar desde donde realmente se puede llegar a un endpoint local. Mantenerlo ahí también significa que la dirección y cualquier clave nunca salen de tu máquina.

Funciona cualquier cosa compatible con OpenAI, incluidos Ollama, LM Studio, el servidor de llama.cpp y vLLM.

Todavía no se lanzó la compatibilidad con modelos locales en Desktop. Mientras tanto, usa la CLI o una clave en la nube en la app.

Qué cambia cuando usas tu propia clave

• Medición. Los turnos con tu clave no se descuentan de tus Perch Tokens incluidos, y no aparece ningún cargo en Perch Tokens por ellos.
• Enrutamiento de modelos. Perch enruta solo a tu proveedor. Nunca cambia en silencio a un modelo alojado por Perch, porque eso enviaría tu prompt a un lugar que no elegiste y te lo cobraría. Si tu endpoint no está disponible, el turno falla y lo indica.
• Selección de modelos. El selector de niveles de Roost no se aplica, porque Perch ya no elige un modelo por ti.
• Todo lo demás. El espacio de trabajo, la memoria, la recuperación, la verificación de citas y el resto del harness funcionan exactamente igual que con los modelos alojados.

Solución de problemas

"Your key was accepted, but no model this workspace can run is available." (Tu clave fue aceptada, pero no hay ningún modelo disponible que este espacio de trabajo pueda ejecutar). La clave es válida, pero en este momento no se puede enrutar nada de ese proveedor para tu cuenta. Es la versión honesta de una prueba fallida, y significa que los turnos reales también fallarían. Prueba con otro proveedor o usa Custom e indica un modelo explícitamente.

El botón Test pasa, pero los turnos reales fallan. Repórtalo. Una prueba exitosa debe enrutar exactamente al mismo lugar que un turno real, así que esta discrepancia en particular es un error de nuestra parte, no algo que debas sortear.

"...does not support tool calling." (...no admite llamadas a herramientas). El catálogo público indica que ese modelo no puede llamar herramientas, así que Perch se negó a guardarlo en lugar de dejar que falle a mitad de una tarea. Elige un modelo que admita llamadas a herramientas o a funciones; la mayoría de los modelos instruct y de programación actuales lo hacen.

Un endpoint local no se guarda en la web. Es lo esperado. Usa perch byolm set en la CLI.

Los turnos siguen usando modelos de Perch. Comprueba que la clave esté seleccionada en el dispositivo desde el que trabajas. Guardar una clave no enruta los turnos: en la app, eso lo hace Use for chat, y en la terminal, perch byok use <provider>. perch byok status y /status indican cuál estás usando.

Relacionado

• Modelos explica qué hay en los grupos de modelos alojados y qué incluye cada plan.
• Perch Roost explica el enrutamiento alojado, que es lo que tu clave reemplaza.
• CLI cubre el resto de la línea de comandos.