Cherry Studio es un cliente de IA de escritorio muy utilizado que permite cambiar entre varios proveedores y modelos y trabajar con asistentes y bases de conocimiento. No ofrece modelos por sí mismo: los modelos provienen de la API que configures. Muchos usuarios se atascan en el mismo paso: qué poner en la Base URL, dónde guardar la clave y cómo añadir el ID del modelo. Este artículo recorre el proceso completo con las versiones habituales actuales.
Nota: Cherry Studio es un producto de su titular; este artículo solo ofrece una explicación técnica de integración. Los nombres de la interfaz y las rutas de acceso pueden cambiar según la versión; toma como referencia la versión actual. Los modelos y precios se indican en los precios de modelos del sitio.
1. Prepara tres elementos antes de empezar
Sea cual sea el gateway que uses, un proveedor personalizado solo necesita tres parámetros:
- API Key: créala en la consola tras registrarte en ZSQH AI Gateway; ponle un nombre por proyecto o entorno.
- Base URL: la dirección compatible con OpenAI del gateway, normalmente
https://ai.zhongshangqihang.com/v1. - ID del modelo: cópialo de la página de precios de modelos; asegúrate de copiar el identificador de API y no el nombre visible.
Antes de entrar en la configuración del cliente, verifica con un comando si la clave y el modelo funcionan; te ahorrará muchos rodeos:
export ZSQH_API_KEY="sk-tu-clave"
curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
-H "Authorization: Bearer $ZSQH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tu-modelo-id",
"messages": [{"role": "user", "content": "Responde solo OK"}]
}'
Si la respuesta incluye choices, significa que la clave, la dirección y el modelo al menos funcionan, y cualquier problema estará en la configuración del cliente.
2. Cómo rellenar la Base URL
Los nombres de los campos de Cherry Studio pueden variar según la versión; los más habituales son «API Address» o «API Host». Se recomienda seguir estos valores:
| Elemento | Valor recomendado | Nota |
|---|---|---|
| Tipo de proveedor | OpenAI | Usa el protocolo compatible con OpenAI |
| Dirección de API | https://ai.zhongshangqihang.com/v1 |
Sin barra al final |
| Clave de API | sk-... |
Clave creada en la consola |
| ID del modelo | Según la página de precios | Revísalo con especial cuidado al añadirlo manualmente |
Las distintas versiones tratan /v1 de forma diferente: algunas lo añaden automáticamente y otras exigen la dirección completa. La forma de saberlo es sencilla: un 401 suele ser un problema de clave y un 404, un problema de ruta. Si con la dirección completa obtienes 404, prueba a quitar /v1; si con el dominio obtienes 404, añade /v1. Cambia solo una variable a la vez; no cambies al mismo tiempo la clave, la dirección y el modelo.
3. Añadir un proveedor personalizado
Con las versiones habituales actuales, el orden de las operaciones es el siguiente (los nombres de los botones dependen de tu versión):
- Abre Cherry Studio y pulsa el icono de ajustes (engranaje) en la esquina inferior izquierda.
- Entra en «Model Services» o «Model Providers».
- Pulsa «+ Add Provider».
- Selecciona OpenAI como tipo de proveedor, o la opción compatible con OpenAI.
- Rellena el nombre del proveedor, la clave de API y la dirección de API.
- Guarda y vuelve a la lista de modelos para añadir el ID del modelo.
Si tu versión no tiene «Add Provider», actualiza el cliente. Las versiones antiguas pueden tener accesos y campos distintos, y seguir un tutorial antiguo al pie de la letra suele acabar con la configuración en el lugar equivocado.
4. Añadir el ID del modelo
Después de guardar el proveedor, hay dos formas de añadir modelos:
- Obtener la lista de modelos: el cliente solicita al gateway los modelos disponibles y, si la operación funciona, marca los que necesites.
- Añadir manualmente: pulsa el botón «+» e introduce directamente el ID del modelo. Usa este método cuando el gateway no exponga la interfaz de lista de modelos o cuando la lista no se cargue.
El ID del modelo debe coincidir exactamente con el de la página de precios, incluidas mayúsculas y minúsculas, sufijo de versión y guiones. Al añadirlo manualmente, confirma también que el tipo de modelo es «chat» o «conversación»; si eliges un tipo incorrecto, el modelo no aparecerá en el selector de la interfaz de chat.
| Tipo de modelo | Uso habitual | Atención |
|---|---|---|
| Modelo de chat | Preguntas diarias, redacción, código | El más común; configúralo primero |
| Modelo de razonamiento | Análisis complejo, matemáticas, planificación | La latencia y el coste suelen ser mayores |
| Modelo de visión | Comprensión de imágenes, preguntas sobre capturas | Confirma si el gateway admite entrada de imágenes |
| Modelo de embeddings | Bases de conocimiento, búsqueda vectorial | Hay que confirmar la interfaz y el modelo por separado |
Si vas a usar una base de conocimiento, el modelo de embeddings también debe estar disponible en el gateway; si solo configuras un modelo de chat, seguirás recibiendo errores al subir documentos. En ese caso, confirma primero si el gateway ofrece una interfaz de embeddings y después decide si necesitas configurar un proveedor de embeddings aparte.
5. Verificación y orden de resolución de problemas
Cuando termines la configuración, crea una conversación, selecciona el modelo que acabas de añadir y envía «Responde solo OK». Si falla, sigue este orden y no reinstales el cliente a la primera:
| Síntoma | Causa habitual | Solución |
|---|---|---|
401 Unauthorized |
Clave incorrecta, caducada o sin guardar | Vuelve a pegar la clave y revisa los espacios del principio y del final |
404 Not Found |
El /v1 de la Base URL no es correcto |
Añade o quita /v1 como se explica en la sección anterior |
model not found |
ID del modelo incorrecto o no habilitado | Copia el identificador exacto de la página de precios |
| Error al obtener la lista de modelos | El gateway no expone la interfaz de lista | Añade el ID del modelo manualmente |
| La conversación se corta a mitad | Inestabilidad de red o tiempo de espera | Revisa el proxy, reduce la concurrencia y reintenta |
| Error en la base de conocimiento | Modelo de embeddings sin configurar | Configura un modelo de embeddings disponible |
Hay otro punto que suele pasarse por alto: las redes corporativas o el software de proxy pueden bloquear las respuestas SSE en streaming, lo que se manifiesta como «la solicitud sale, pero no vuelve nada». Desactiva temporalmente la salida en streaming para probar; si la respuesta sin streaming funciona, revisa el proxy y el firewall.
6. Varios modelos y uso diario
El valor de Cherry Studio está en separar las distintas tareas. Una forma práctica de usarlo es:
- Configurar un modelo general para las preguntas diarias, con respuesta rápida y coste controlable.
- Configurar un modelo de contexto largo para resumir textos extensos, en un asistente aparte.
- Configurar un modelo con mejores capacidades de código para las tareas de programación.
- Preparar un modelo de embeddings específico para la base de conocimiento.
- Escribir el prompt de sistema de cada asistente para no repetir las mismas instrucciones cada vez.
Cuantos más modelos uses, más importante es controlar la longitud del contexto. Meter un documento entero en la conversación una y otra vez encarece cada solicitud; lo que pueda ir a la base de conocimiento debe ir allí primero, y lo que pueda resumirse debe resumirse primero.
7. Seguridad y uso en equipo
- La clave se guarda en el equipo local; si se comparte el ordenador, conviene aislar las cuentas del sistema.
- No guardes claves de larga duración en equipos compartidos de la empresa.
- Emite claves por proyecto para poder consultar el uso y revocarlas desde el gateway.
- No pegues datos privados de clientes, contratos originales ni datos sin anonimizar en el cliente.
- Revisa periódicamente el uso del gateway; ante un aumento anómalo, desactiva la clave primero y luego investiga.
Preguntas frecuentes
¿Cherry Studio es gratuito?
El cliente se puede usar gratuitamente, pero el coste de las llamadas a los modelos lo cobra el proveedor de API que configures. Consulta la versión actual del cliente y la página de precios del gateway.
¿Por qué sigo recibiendo 401 después de introducir la clave?
Primero confirma que la clave no tiene espacios de más y después que pertenece a la plataforma correspondiente a la Base URL actual. Las claves de distintos gateways no se pueden mezclar; comprueba también si la clave se ha eliminado o si la cuota se ha agotado.
¿La Base URL debe incluir /v1?
Depende de lo que indique tu versión actual. La mayoría de las configuraciones compatibles con OpenAI necesitan /v1, pero algunos clientes lo añaden automáticamente. El criterio es si la solicitud llega a /v1/chat/completions; si recibes 404, ajusta el final.
¿Puedo usar modelos de Claude o Gemini?
Sí, siempre que el gateway ofrezca el modelo correspondiente en formato compatible con OpenAI y pongas el ID exacto de ese modelo. En modelos con protocolos nativos distintos, algunos parámetros pueden no ser compatibles; consulta la documentación del sitio.
¿Puedo usarlo sin conexión después de configurarlo?
No. El cliente es solo la interfaz; la inferencia ocurre en la API remota. Sin red o si el gateway no es accesible, la conversación no se puede completar.
Próximos pasos
Configurar Cherry Studio no es complicado; lo difícil es alinear la Base URL, la clave y el ID del modelo. Se recomienda probar primero con curl y después pasar al cliente; si surge un problema, revisa en el orden 401, 404 y model not found. Si necesitas un punto de acceso unificado a modelos y gestión de uso, puedes registrarte en ZSQH AI Gateway; los modelos y precios se indican en la página de precios de modelos.
Lecturas relacionadas:
