Configurar proveedores de IA personalizados y API Keys en PandaNpc

Los proveedores personalizados permiten que PandaNpc use una cuenta de API, una puerta de enlace privada o un endpoint de modelo local que usted controle. Esto se conoce comúnmente como BYOK: traiga su propia clave. Es útil cuando necesita un modelo fuera del catálogo integrado, facturación del lado del proveedor, un proxy interno, Ollama, LM Studio o un servicio autohospedado compatible con OpenAI.

Para el chat directo compatible, PandaNpc envía la solicitud a su endpoint configurado en lugar de sustituir un modelo integrado. Su proveedor ascendente aún controla los precios, la retención, los límites de tasa, la disponibilidad de modelos y el uso aceptable.

Requisitos previos y límites de seguridad

Antes de agregar un proveedor, recoja:

• La API Key del proveedor o el token de autenticación local.
• Su API Base URL, generalmente terminando en /v1 para un servicio compatible con OpenAI.
• El identificador exacto del modelo aceptado por la API.
• La ventana de contexto documentada y el límite máximo de salida, si planea sobrescribir los valores predeterminados.

Use una clave dedicada con los permisos mínimos necesarios y un límite de gasto donde el proveedor lo admita. Nunca coloque la clave en documentación, indicaciones de chat, capturas de pantalla, salida de la consola del navegador o un repositorio Git.

En un navegador web, las solicitudes directas están sujetas a CORS. El proveedor debe permitir solicitudes desde https://pandanpc.com. Una Base URL como http://localhost:11434/v1 se refiere a la computadora que ejecuta el navegador, no automáticamente a la máquina remota PandaPaw. La aplicación de escritorio puede ser más adecuada para endpoints locales porque no está limitada por el CORS del navegador de la misma manera.

Paso 1: Abrir la configuración de modelos

Inicie sesión en PandaNpc y abra Model Configuration. Los proveedores y los modelos son registros separados: el proveedor almacena los detalles de conexión y autenticación, mientras que cada modelo almacena el identificador y los límites enviados a esa conexión.

Si ya aparece un proveedor oficial, configúrelo o cópielo en lugar de inventar un protocolo diferente. Para una nueva puerta de enlace compatible con OpenAI, seleccione Agregar proveedor.

Paso 2: Agregar el proveedor

Complete el formulario del proveedor:

PandaNpc elimina las barras diagonales finales de la Base URL y agrega /chat/completions para la solicitud de chat directa compatible con OpenAI. Por lo tanto, ingrese:

https://api.example.com/v1

no:

https://api.example.com/v1/chat/completions

Guarde el proveedor antes de agregar un modelo. Al editar un proveedor existente, un campo de API Key o Secreto vacío significa "conservar el valor configurado"; no expone el secreto almacenado de vuelta al formulario.

Paso 3: Agregar un modelo

Elija Agregar modelo debajo del proveedor y complete estos campos:

Display Name se puede cambiar sin afectar la llamada a la API. Model Value no se puede adivinar a partir de un nombre de marketing; cópielo de la documentación de API del proveedor o del endpoint de lista de modelos.

Deje Context Window y Max Tokens vacíos cuando no esté seguro. Un valor predeterminado conservador es más seguro que declarar una ventana de contexto más grande de lo que el servidor admite. Estos campos son especialmente importantes para PandaCode porque influyen en la compactación y el presupuesto de salida.

Ejemplos de endpoints comunes

Los siguientes patrones ilustran la forma de la URL; la disponibilidad y los IDs de modelo dependen de su instalación o cuenta de proveedor:

No asuma que todo servicio que anuncia "compatible con OpenAI" implementa streaming, llamadas a herramientas, imágenes, campos de razonamiento o respuestas de error idénticas. Pruebe las características exactas que su flujo de trabajo necesita.

Verificar el proveedor y el modelo

Use una solicitud de bajo costo y no sensible antes de confiar en la configuración:

1. Seleccione el nuevo modelo en una conversación nueva.
2. Envíe Reply with exactly: provider connected.
3. Confirme que la respuesta se transmite y que el panel del proveedor registra la solicitud.
4. Envíe un mensaje de seguimiento corto para verificar el historial de la conversación.
5. Si necesita herramientas, imágenes o contexto largo, pruebe cada capacidad por separado.

Para un endpoint local, verifíquelo primero fuera de PandaNpc. Una lista de modelos compatible con OpenAI suele estar disponible con:

curl http://localhost:11434/v1/models

Use la respuesta solo para confirmar la accesibilidad y el ID del modelo. No coloque una API Key de producción directamente en el historial de la shell.

Usar modelos personalizados con PandaCode

PandaCode puede proporcionar un flujo de trabajo de codificación estilo Claude Code mientras utiliza un backend de modelo que usted elija, incluidos DeepSeek, Qwen, una puerta de enlace compatible con OpenAI o un servicio interno. Después de configurar el proveedor y el modelo, seleccione ese modelo para la conexión o tarea relevante de PandaCode.

El modelo debe admitir el patrón de interacción requerido por el motor de codificación. Un proveedor que funciona para el chat simple puede fallar en llamadas a herramientas, transmisiones de larga duración o contenido estructurado. Consulte Modelos de IA compatibles con PandaNpc para conocer la diferencia entre modelos de chat y motores de codificación locales, y Instalación y comandos de PandaPaw para la configuración del motor remoto.

Solución de problemas

Error de autenticación `401` o `403`

Cree una nueva clave de proveedor, confirme que esté activa y vuelva a ingresarla. Verifique si el servicio ascendente requiere una organización, proyecto o método de autenticación diferente. Una clave enmascarada copiada de una pantalla de edición no es el secreto original.

`404` endpoint o modelo no encontrado

Elimine /chat/completions de la Base URL configurada porque PandaNpc lo agrega. Confirme que /v1 esté presente cuando se requiera y que Model Value coincida exactamente con el ID de modelo ascendente. Un proveedor puede devolver el mismo 404 tanto para una URL incorrecta como para un modelo no disponible.

El navegador informa un error de red o CORS

Abra la consola de desarrollador del navegador solo para identificar el origen bloqueado; no pegue secretos allí. Configure el proveedor para permitir https://pandanpc.com, use su endpoint HTTPS o use la aplicación de escritorio PandaNpc. Las reglas de contenido mixto bloquean que una página HTTPS llame a algunos endpoints HTTP simples.

No se puede acceder a Ollama o LM Studio locales

Asegúrese de que el servidor se esté ejecutando en la misma computadora que el cliente que realiza la solicitud y esté escuchando en la interfaz y el puerto configurados. Si el servidor de modelos se ejecuta en otra computadora, localhost es incorrecto; use un nombre de host o IP privada alcanzable y asegure el servicio antes de exponerlo.

La respuesta comienza pero se detiene o no tiene contenido

Confirme que la API admite Chat Completions transmitidos y emite eventos data: estándar. Reduzca Max Tokens, pruebe un mensaje de solo texto y desactive las matrices de contenido estructurado solo si el proveedor documenta que acepta contenido de cadena exclusivamente.

Las sesiones largas fallan cerca del límite de contexto

Reduzca la Context Window configurada al límite real admitido por el proveedor y reserve espacio para la salida, las instrucciones del sistema y los resultados de las herramientas. Inicie una sesión nueva después de cambiar la configuración del modelo para que los nuevos límites se apliquen de manera consistente.

Para detalles sobre cuotas a nivel de cuenta y flujo de datos, lea Cuentas, planes y costos de API de PandaNpc y la Política de privacidad.