Perfiles de modelos, contexto y Extra JSON

Qué define un perfil

En Sapphire I.C.D.S., el modelo describe las capacidades técnicas y el perfil define las reglas para utilizarlas. Por ejemplo, para un modelo pueden crearse un perfil estricto de soporte, uno conciso de clasificación y otro ampliado de análisis. Cada uno tendrá su propia instrucción del sistema, longitud de respuesta y presupuesto de contexto, pero todos deben permanecer dentro de los límites del mismo modelo registrado.

En la sección AI Settings → Profiles, seleccione el proveedor y el modelo. Deben corresponderse: un perfil no puede vincularse con el modelo de otro proveedor. Profile key es un identificador de máquina estable, por ejemplo support_ru. No use el nombre de un empleado ni el número temporal de una tarea. Un perfil activado está disponible para seleccionarlo, mientras que el perfil predeterminado se utiliza cuando el cliente no especifica un registro concreto. Asígnelo como default solo después de probarlo.

Instrucción del sistema y formato de respuesta

System prompt define el rol y las reglas permanentes del modo seleccionado. Escríbalo como un contrato verificable: ámbito de tareas, idioma, formato del resultado, restricciones y criterio de finalización. No incluya claves de API, datos personales, todo el contenido de la base de conocimiento ni instrucciones que el operador deba cambiar en cada solicitud.

Al iniciarse, el sistema comienza con la instrucción del sistema del perfil y añade las instrucciones de gestión activadas como política corporativa obligatoria. El historial y el resumen de la sesión siguen siendo datos. La memoria y la base de conocimiento no se cargan completas en el prompt: el modelo las obtiene cuando las necesita mediante las herramientas autorizadas. Por tanto, ampliar el system prompt no sustituye la configuración de instrucciones, memoria, conocimiento y permisos de herramientas.

Defina Response format únicamente con una forma que comprendan el adaptador y el modelo seleccionados. Para una conversación normal, una respuesta de texto es un punto de partida seguro. Si necesita JSON estructurado, compruebe primero que tanto el modelo como el consumidor lo admitan: una cadena en el perfil no garantiza por sí sola el cumplimiento de su esquema de negocio.

Reasoning, Temperature y Top P

Utilice Reasoning effort solo con modelos que documenten ese modo. No copie un valor de otra familia. Temperature y Top P tienen interruptores separados. Si un parámetro está desactivado, el perfil no debe imponerlo al proveedor; esto es preferible a enviar accidentalmente un valor cero. Normalmente basta con controlar un método de variabilidad y dejar desactivado el otro. Para la extracción de datos y la clasificación se eligen ajustes más estables; para generar variantes, otros más libres, pero el intervalo concreto debe contrastarse siempre con la documentación del modelo.

Cómo se calcula el contexto

El registro del modelo contiene tres límites superiores: contexto total, entrada máxima y salida máxima. El perfil establece cuatro valores operativos. Max output tokens limita una respuesta. Active context tokens es el presupuesto que puede utilizar el agente. Compaction reserve tokens es la parte de ese presupuesto reservada para una compactación segura. El umbral automático es:

active_context_tokens - compaction_reserve_tokens

La reserva debe ser positiva y estrictamente inferior al presupuesto activo. El presupuesto activo no puede superar la entrada máxima del modelo, el límite de respuesta no puede superar la salida máxima y la suma de ambos no puede superar el contexto total. Por ejemplo, con contexto 128000, entrada 120000 y salida 8192, puede definirse un presupuesto activo de 64000, una reserva de 16000 y una respuesta de 4096. El umbral de compactación será 48000. Es solo un ejemplo aritmético, no una recomendación universal para cualquier modelo.

Maximum agent rounds limita el número de ciclos modelo-herramienta, y Maximum agent runtime, el tiempo total en segundos. El valor 0 significa que no existe ese límite concreto del perfil, pero no anula los límites del proveedor, la cancelación por el usuario, la protección frente a la falta de progreso ni las restricciones del sistema. Para un escenario crítico o costoso, defina valores finitos explícitos y mida el funcionamiento real antes de aumentarlos.

Streaming y cambio de modelo

El interruptor de streaming determina el modo preferido de entrega de la respuesta. No convierte una API síncrona en streaming si el proveedor no lo admite. Al cambiar de modelo, cree un perfil nuevo o vuelva a calcular cuidadosamente todos los presupuestos. El estado de compactación asociado a un proveedor y modelo no puede considerarse transferible a otra pareja.

Extra JSON sin sorpresas ocultas

Extra JSON es un objeto JSON opcional para parámetros adicionales documentados por un proveedor concreto. Es una extensión, no un segundo perfil. Comience con un objeto vacío:

{}

Si la API realmente requiere una opción adicional, añada solo esa opción. Ejemplo neutral de la forma:

{
  "metadata": {
    "integration": "sapphire-docs"
  }
}

El ejemplo solo es válido cuando la API seleccionada admite el campo metadata. El JSON debe ser un objeto con comillas dobles, sin comentarios ni comas finales. No incluya secret, Authorization, base URL, model key, identificadores de usuario ni contenido confidencial.

No duplique en Extra JSON campos principales de la solicitud, como el modelo, las herramientas, la selección de herramientas, los mensajes de entrada, temperature, Top P o max output tokens. Un conflicto dificulta el diagnóstico y puede cambiar el comportamiento tras actualizar el adaptador. El campo enable_tools no permite eludir la gestión de herramientas, y una configuración arbitraria no debe sustituir la política de contexto gestionada. Las herramientas se autorizan mediante el catálogo del servidor, los permisos del grupo y la selección de la sesión.

Comprobar el perfil

1. Guarde el perfil activado, pero no lo designe todavía como predeterminado.
2. Cree una sesión nueva y seleccione el perfil expresamente.
3. Compruebe una respuesta breve, la instrucción del sistema y el formato declarado.
4. Realice una prueba larga observando el umbral de contexto y la compactación.
5. Compruebe la detención por rondas y tiempo si los límites no son cero.
6. Añada las claves de Extra JSON una por una y repita la prueba.
7. Solo entonces asigne el perfil como default.

Si se rechaza la solicitud, primero vacíe Extra JSON, desactive los parámetros opcionales de sampling y repita la prueba mínima. Después verifique los límites y la compatibilidad con reasoning/response format. Este orden separa un error en el registro básico de una opción adicional incompatible.

Cómo elegir el tamaño del presupuesto

No empiece por el máximo del modelo, sino por un escenario operativo medido. Calcule la longitud de la instrucción del sistema, el historial típico, los resultados de herramientas esperados y el margen para la respuesta. Un active context demasiado grande eleva el coste y el tiempo de procesamiento; uno demasiado pequeño provoca compactaciones frecuentes. La reserva debe permitir crear un resumen correcto antes de alcanzar el límite estricto, por lo que no puede reducirse a un valor simbólico.

Separe los perfiles de tareas distintas cuando difieran sus requisitos de longitud, reasoning o tiempo. Un único perfil «universal» es más difícil de probar y modificar con seguridad. Registre la finalidad del perfil en el nombre y la descripción del procedimiento de trabajo, pero no incruste el enrutamiento ni los permisos en el system prompt: otros niveles controlan la selección del perfil y la autorización de herramientas.