Configuración de Modelos

Introducción

Esta guía te llevará a través del proceso completo de configuración de un modelo de análisis, desde la planificación inicial hasta tu primer análisis de prueba.

Un modelo bien configurado es la base para obtener análisis precisos y relevantes de tus llamadas.

Flujo de Configuración

1. Planificación del Modelo

Antes de crear tu modelo, define claramente:

Objetivo

¿Qué quieres medir? ¿Calidad de servicio, cumplimiento de script, habilidades de venta?

Tipo de Llamadas

¿Servicio al cliente, ventas, soporte técnico, cobranza?

Criterios Clave

¿Cuáles son los comportamientos críticos que deben evaluarse?

Segmentación

¿Cómo querrás filtrar y agrupar los análisis? ¿Por campaña, producto, región?

Ejemplo de Planificación

Para un modelo de Evaluación de Ventas:

Aspecto	Definición
Objetivo	Evaluar habilidades de venta y cumplimiento de protocolo
Categorías	Apertura, Descubrimiento, Presentación, Cierre
Variables clave	Saludo, identificación de necesidades, manejo de objeciones
Metadata	Campaña, producto, región

2. Crear el Modelo Base

Desde la Aplicación Web

Navega a Configuración > Modelos
Haz clic en + Nuevo Modelo
Completa la información básica:
- Nombre: Identificador único (ej: “Evaluación Ventas Q1”)
- Descripción: Propósito del modelo
- Prompt: Instrucciones para el análisis de IA

Vía API

POST /v1/models

{
  "name": "Evaluación Ventas Q1",
  "description": "Modelo para evaluar llamadas del equipo de ventas durante Q1",
  "prompt": "Evalúa esta llamada de ventas considerando: saludo profesional, identificación de necesidades del cliente, presentación de beneficios, manejo de objeciones y cierre efectivo."
}

Respuesta:

{
  "id": 15,
  "name": "Evaluación Ventas Q1",
  "description": "Modelo para evaluar llamadas del equipo de ventas durante Q1",
  "prompt": "...",
  "created_at": "2025-01-20T10:00:00Z"
}

Guarda el id del modelo (15 en este ejemplo) — lo necesitarás para los siguientes pasos.

3. Definir Categorías

Las categorías organizan tu evaluación en fases lógicas de la llamada.

Estructura Recomendada

Categoría	Descripción	Peso Sugerido
Apertura	Saludo e identificación	15-20%
Descubrimiento	Identificación de necesidades	20-25%
Presentación	Exposición de solución/producto	25-30%
Cierre	Confirmación y próximos pasos	25-30%

Crear Categoría vía API

POST /v1/models/15/categories

{
  "name": "Apertura",
  "description": "Evaluación del saludo e identificación inicial",
  "order_number": 1
}

Respuesta:

{
  "id": 42,
  "model_id": 15,
  "name": "Apertura",
  "description": "Evaluación del saludo e identificación inicial",
  "order_number": 1
}

Repite este proceso para cada categoría. El order_number determina el orden de aparición en los reportes.

Ejemplo Completo de Categorías

categories = [
    {"name": "Apertura", "description": "Saludo e identificación", "order_number": 1},
    {"name": "Descubrimiento", "description": "Identificación de necesidades", "order_number": 2},
    {"name": "Presentación", "description": "Exposición de la solución", "order_number": 3},
    {"name": "Cierre", "description": "Confirmación y siguientes pasos", "order_number": 4}
]

for cat in categories:
    response = requests.post(
        f"{base_url}/v1/models/15/categories",
        headers=headers,
        json=cat
    )
    print(f"Creada categoría: {response.json()['name']} (ID: {response.json()['id']})")

4. Agregar Variables

Las variables son los criterios específicos de evaluación dentro de cada categoría.

Tipos de Variables

Tipo	Uso	Ejemplo
`INTEGER`	Puntuación numérica (0-10)	Calidad del saludo
`BOOLEAN`	Sí/No	¿Mencionó el nombre del cliente?
`STRING`	Texto extraído	Producto de interés
`DECIMAL`	Puntuación con decimales	Score de empatía

Crear Variable vía API

POST /v1/models/15/variables

{
  "key": "greeting_quality",
  "readable_name": "Calidad del Saludo",
  "description": "Evalúa si el agente saludó de forma profesional y cordial",
  "type": "INTEGER",
  "weight": 10,
  "category_id": 42,
  "required": true
}

Respuesta:

{
  "id": 101,
  "model_id": 15,
  "category_id": 42,
  "key": "greeting_quality",
  "readable_name": "Calidad del Saludo",
  "description": "Evalúa si el agente saludó de forma profesional y cordial",
  "type": "INTEGER",
  "weight": 10,
  "required": true
}

Distribución de Pesos

La suma de los pesos de todas las variables debe ser coherente con tu escala de evaluación (típicamente 100 puntos total).

Ejemplo de distribución:

Total: 100 puntos

Apertura: 20 puntos

Calidad del saludo: 10

Identificación correcta: 10

Descubrimiento: 25 puntos

Preguntas abiertas: 10

Escucha activa: 10

Resumen de necesidades: 5

Presentación: 30 puntos

Presentación de beneficios: 15

Manejo de objeciones: 15

Cierre: 25 puntos

Propuesta clara: 10

Confirmación de próximos pasos: 15

Variables de Extracción

Además de variables de puntuación, puedes extraer información:

{
  "key": "product_interest",
  "readable_name": "Producto de Interés",
  "description": "El producto principal que el cliente mencionó o mostró interés",
  "type": "STRING",
  "weight": 0,
  "category_id": 43,
  "required": false
}

Las variables con weight: 0 no afectan el NeuraScore pero capturan información valiosa.

5. Configurar Metadata

La metadata permite segmentar y filtrar análisis en dashboards.

Campos Comunes de Metadata

Campo	Descripción	Uso
campaign	Nombre de la campaña	Comparar rendimiento entre campañas
product	Producto o servicio	Análisis por línea de producto
region	Región geográfica	Comparativas regionales
team	Equipo o supervisor	Métricas por equipo

Crear Campo de Metadata vía API

POST /v1/models/15/metadata

{
  "key": "campaign",
  "readable_name": "Campaña",
  "type": "STRING",
  "grouping_field": true
}

Respuesta:

{
  "id": 201,
  "model_id": 15,
  "key": "campaign",
  "readable_name": "Campaña",
  "type": "STRING",
  "grouping_field": true
}

Los campos con grouping_field: true aparecerán como opciones de filtro en los dashboards.

6. Verificar la Configuración

Antes de usar el modelo, verifica que todo esté correcto.

Obtener Modelo Completo

GET /v1/models/15

Esto devuelve el modelo con todas sus categorías, variables y metadata.

Checklist de Verificación

Información del Modelo

✓ Nombre descriptivo y único✓ Descripción clara del propósito✓ Prompt con instrucciones específicas

Categorías

✓ Cubren todas las fases de la llamada✓ Orden lógico establecido✓ Descripciones claras

Variables

✓ Cada categoría tiene variables asignadas✓ Los pesos suman el total esperado✓ Tipos correctos (INTEGER, BOOLEAN, STRING)✓ Variables requeridas marcadas

Metadata

✓ Campos de segmentación necesarios✓ Campos de agrupación habilitados

7. Primer Análisis de Prueba

Una vez verificado el modelo, realiza un análisis de prueba.

Crear Análisis de Prueba

POST /v1/call-analysis

Con los parámetros:

audio_file: Archivo de audio de una llamada representativa
model_name: “Evaluación Ventas Q1”
agent_id y agent_name: Datos del agente
additional_parameters: Metadata (campaña, producto, etc.)

Evaluar Resultados

Revisa el análisis generado:

NeuraScore: ¿El puntaje refleja la calidad real de la llamada?
Variables: ¿Los valores capturados son correctos?
Insights: ¿Las observaciones son relevantes?

Si los resultados no son los esperados, ajusta las descripciones de las variables o el prompt del modelo.

Errores Comunes

Error 409: Modelo con Análisis Existentes

{
  "detail": "Cannot modify model with existing analyses"
}

Solución: Una vez que un modelo tiene análisis asociados, no se pueden modificar sus variables ni categorías. Crea una nueva versión del modelo si necesitas hacer cambios estructurales.

Variables sin Categoría

Las variables deben estar asociadas a una categoría válida del modelo.

Pesos Desbalanceados

Si los pesos no suman 100, el NeuraScore podría no reflejar correctamente la evaluación.

Recursos Relacionados

API de Modelos

Referencia completa de la API

Conceptos: Modelos

Fundamentos de los modelos de análisis

Categorías

Guía detallada de categorías

Variables

Tipos y configuración de variables

Introducción

Primeros Pasos

Guía de Usuario

Conceptos

​Introducción

​Flujo de Configuración

​1. Planificación del Modelo

Objetivo

Tipo de Llamadas

Criterios Clave

Segmentación

​Ejemplo de Planificación

​2. Crear el Modelo Base

​Desde la Aplicación Web

​Vía API

​3. Definir Categorías

​Estructura Recomendada

​Crear Categoría vía API

​Ejemplo Completo de Categorías

​4. Agregar Variables

​Tipos de Variables

​Crear Variable vía API

​Distribución de Pesos

​Variables de Extracción

​5. Configurar Metadata

​Campos Comunes de Metadata

​Crear Campo de Metadata vía API

​6. Verificar la Configuración

​Obtener Modelo Completo

​Checklist de Verificación

​7. Primer Análisis de Prueba

​Crear Análisis de Prueba

​Evaluar Resultados

​Errores Comunes

​Error 409: Modelo con Análisis Existentes

​Variables sin Categoría

​Pesos Desbalanceados

​Recursos Relacionados

API de Modelos

Conceptos: Modelos

Categorías

Variables

Introducción

Flujo de Configuración

1. Planificación del Modelo

Ejemplo de Planificación

2. Crear el Modelo Base

Desde la Aplicación Web

Vía API

3. Definir Categorías

Estructura Recomendada

Crear Categoría vía API

Ejemplo Completo de Categorías

4. Agregar Variables

Tipos de Variables

Crear Variable vía API

Distribución de Pesos

Variables de Extracción

5. Configurar Metadata

Campos Comunes de Metadata

Crear Campo de Metadata vía API

6. Verificar la Configuración

Obtener Modelo Completo

Checklist de Verificación

7. Primer Análisis de Prueba

Crear Análisis de Prueba

Evaluar Resultados

Errores Comunes

Error 409: Modelo con Análisis Existentes

Variables sin Categoría

Pesos Desbalanceados

Recursos Relacionados