Conexión de un proveedor de IA y registro de un modelo

Tres niveles que no deben confundirse

La conexión de un modelo en Sapphire I.C.D.S. consta de tres registros independientes. El proveedor describe el servicio externo: su clave estable, la URL base, el adaptador instalado y el secreto de acceso. El modelo almacena el identificador del modelo en ese proveedor y sus límites técnicos. El perfil define el comportamiento operativo: instrucción del sistema, presupuesto de contexto, extensión de la respuesta y parámetros adicionales. Esta separación permite utilizar un modelo en varios modos, evita duplicar la clave de API e impide sustituir los límites reales del modelo por la configuración de una tarea concreta.

La configuración se realiza en la sección administrativa AI Settings. El acceso debe concederse mediante Helix. Antes de empezar, obtenga del proveedor los valores actuales de base URL, model ID y los límites del modelo elegido, y compruebe que el adaptador correspondiente ya esté instalado en el entorno de servidor de Sapphire. Un texto introducido en el formulario no instala por sí mismo una biblioteca.

Paso 1. Crear el proveedor

Abra la sección de proveedores y cree un registro. El campo Vendor key debe contener un identificador de máquina breve y estable, por ejemplo acme_ai. Utilice letras latinas minúsculas, números y guiones bajos. No incluya el dominio, la tarifa, la región ni la versión del modelo: la clave vincula configuraciones y debe sobrevivir a los cambios habituales del producto.

Display name está destinado a los operadores y puede ser legible para personas. En Base URL, indique la dirección HTTPS base documentada de la API del proveedor, sin la ruta de un modelo concreto y sin un token en la query string. No copie una URL de la consola del navegador ni añada una ruta final arbitraria. Si el proveedor ofrece varias API compatibles, use la variante para la que está instalado el adaptador.

Vendor key debe coincidir con la variant del proveedor instalado que detecta el cargador estándar de la plataforma. En el runtime actual, el campo Provider library es metadata fallback compatible y, cuando vendor key no está vacío, normalmente no determina el adaptador. No es una ruta de archivo ni un mecanismo para instalar una biblioteca nueva. Si la provider variant necesaria no está instalada, derive la tarea al administrador de despliegue.

En Secret name normalmente se conserva el nombre de secreto adoptado por ese adaptador, y en Secret value se introduce la clave de API emitida. El secreto no debe incluirse en el nombre, la URL, la descripción, una captura, un ticket ni el JSON del perfil. Después de guardar, la interfaz muestra únicamente que existe un secreto, no su valor original. Al editar, deje vacío el campo de valor si no necesita cambiar la clave; un valor nuevo y no vacío implica rotar el secreto. Un orden práctico consiste en crear primero el proveedor desactivado, guardar el secreto, revisar los demás campos y activar el registro solo después.

Paso 2. Registrar el modelo

Vaya a la sección de modelos y seleccione el proveedor recién creado. Model key debe coincidir exactamente con el identificador que acepta la API, incluidos guiones, puntos y el sufijo de versión. No es un alias arbitrario. Para un nombre cómodo existe un campo Display name separado.

A continuación, copie los tres límites de la ficha oficial del modelo. Maximum context es el límite total de la ventana de contexto. Maximum input es la entrada máxima permitida. Maximum output es el límite de la respuesta generada. Todos los valores se expresan como enteros positivos en tokens. Ni la entrada ni la salida pueden superar por separado el contexto completo. No use un valor de contexto publicitario si la API o la tarifa elegida admite menos.

Tokenizer variant determina cómo se estiman los tokens. Indique la variante compatible exacta si la conoce. Si para una familia nueva solo existe una estimación conservadora, utilice el nombre acordado para esa variante y no el nombre del modelo elegido al azar. El campo es obligatorio: un tokenizador incorrecto no produce solo una desviación estética, sino un cálculo erróneo del momento de compactación y del tamaño de solicitud admisible.

Orden seguro de activación

1. Cree el proveedor con la URL HTTPS correcta y un adaptador instalado.
2. Guarde el secreto y compruebe que la lista muestre el indicador de su existencia.
3. Cree el modelo con el model key exacto y límites confirmados.
4. Cree un perfil separado para ese modelo; sin perfil no hay una política operativa definida.
5. Active primero el modelo y el proveedor para una prueba limitada y asigne después el perfil predeterminado.

Para probarlo, abra una nueva sesión de IA, seleccione expresamente el perfil creado y ejecute una solicitud breve sin herramientas, por ejemplo pedir una sola línea de texto. Una sesión nueva evita la influencia de una selección de perfil anterior y del historial acumulado. Después de obtener la respuesta básica, pruebe el streaming y, solo entonces, los escenarios con herramientas. La disponibilidad de herramientas se gestiona mediante el catálogo y los permisos de grupo, no mediante el registro del proveedor o del modelo.

Errores habituales

• Error de autorización: compruebe que el secreto exista, que no haya caducado y que pertenezca al proyecto correcto; rótelo únicamente si es necesario.
• Model not found: compare el model key carácter por carácter con la documentación de la API y confirme que la cuenta tenga permitido el modelo.
• Ruta incorrecta: compruebe la base URL, el adaptador seleccionado y que la dirección base no contenga una ruta de modelo.
• Rechazo al guardar los límites: los tres valores deben ser positivos, y input y output no deben superar context.
• El modelo no aparece durante el uso: el proveedor, el modelo y el perfil deben estar activados; el perfil debe apuntar a la misma pareja y estar disponible para el usuario actual.

No cambie a la vez el secreto, la URL, el model key y los límites de un perfil activo. Realice un cambio cada vez y registre el resultado de la prueba. Para cambiar de generación de modelo es más seguro registrar un modelo y un perfil nuevos, probarlos por separado y después cambiar el perfil predeterminado. Así se conserva una vía clara de reversión sin alterar el significado de los registros existentes.

Aceptación y mantenimiento

Tras una solicitud mínima satisfactoria, registre en la documentación de trabajo el vendor key, el model key, la finalidad del perfil, la fuente de los límites y la fecha de comprobación. No anote el secreto. Pruebe por separado el comportamiento con el proveedor desactivado temporalmente: el usuario debe recibir un error comprensible, no una espera infinita. Si el servicio dispone de varias regiones o rutas tarifarias, trátelas como configuraciones deliberadas en vez de cambiar la base URL durante el diagnóstico.

Revise periódicamente los límites conforme a la documentación actual del proveedor. Un cambio del nombre comercial del modelo no siempre implica un identificador de API nuevo, y un identificador nuevo no garantiza la misma tokenizer variant. Cualquier cambio de este tipo sigue el mismo ciclo: registro separado, perfil, sesión de prueba, verificación de la respuesta y solo después cambio para los usuarios.