Skip to content

Pregunta de puntuación Score: puntúa según la escala que tú defines ​

La Choice de la lección anterior consiste en elegir una opción de un conjunto fijo. Pero muchas valoraciones no son «cuál elegir», sino «en qué grado»: qué tan grave es un bug, qué tan enfadado está un cliente, qué tan experto es un candidato en Python.

Para este tipo de preguntas se usa Score: tú proporcionas una escala ordenada y Jev coloca el contenido en una posición de la escala, devolviendo junto con ello la probabilidad de cada nivel y la confianza.

En realidad ya lo viste en la primera petición: el frustration del ejemplo de tickets era una pregunta Score de tres niveles que devolvió 0.67. Esta lección lo explica a fondo, en 10 minutos.

Qué podrás hacer al terminar ​

  • Definir con criteria una escala ordenada (se recomiendan al menos dos niveles, con un máximo de 10 niveles), para que Jev Score puntúe cualquier contenido según tu escala
  • Interpretar los cinco campos devueltos: score, legend, probabilities, confidence, type
  • Explicar cómo se calcula una puntuación como 1.43 que «cae entre dos niveles»
  • Usar score para superar umbrales y confidence para decidir si escalar a humano
  • Dividir una valoración multidimensional en varias preguntas Score y combinarlas con normalización y ponderación en el código

Tu problema actual ​

  • Pedir a GPT que puntúe un ticket de 1–10: el mismo ticket obtiene 6 una vez y 8 la siguiente, así que es imposible fijar un umbral de «por encima de cuántos puntos se escala a humano»
  • Los criterios de puntuación los improvisa el modelo: mi «gravedad media» no coincide con lo que él entiende, y al cambiar de versión del prompt hay que repuntuar todos los históricos
  • Obtener un 7 y ya está, sin saber si es un 7 casi seguro o un 7 resultante de mitad 6 y mitad 8; cuáles requieren revisión humana es pura adivinanza

Cuándo usar esta técnica ​

Cuando necesitas:

  • Situar contenido en un espectro: gravedad, nivel de frustración, nivel de habilidad, calidad de un informe
  • Que las puntuaciones entren directamente en el código: umbrales, ordenación, sumas ponderadas
  • La probabilidad de cada nivel y la confianza global, como señal de «¿hace falta que un humano le eche un vistazo?»

Y no quieres:

  • Dejar que un modelo de chat improvise un «ponle una nota del 1–10» y luego escribir código de parsing para extraer el texto que devuelve
  • Mezclar los criterios de puntuación en el prompt, de modo que al cambiar de modelo los criterios se desvíen
  • Dejar que se ejecute automáticamente incluso cuando el modelo no está seguro

🎒 Preparativos antes de empezar ​

  • Has completado State estado: sabes que el contenido a puntuar se coloca en state (una cadena, un objeto JSON o un array de textos, todo vale)
  • Has ejecutado con éxito la primera petición: .venv tiene instalado typesafe-sdk y TYPESAFE_API_KEY ya está en las variables de entorno

Idea central ​

Score responde «en qué grado». Escenarios de uso oficiales: qué tan grave es un bug, qué tan satisfecho está un cliente, cuánta experiencia en Python tiene un candidato. La respuesta está en un espectro y además puedes describir ese espectro nivel por nivel: ese es el requisito previo para usar Score.

La escala es criteria. Una pregunta Score tiene solo tres campos:

CampoQué se escribeEjemplo
typeFijo "score"—
instructionsUna frase que aclara qué se evalúaHow severe is the reported issue?
criteriaLista de niveles ordenados, de menor a mayor, con una descripción por nivelVer la escala de tres niveles del paso 1

La numeración de los niveles es el índice del array, empezando por 0: una escala de tres niveles es 0, 1, 2. El modelo solo ve la descripción textual de cada nivel: no ve los números de nivel ni los niveles adyacentes.

Devuelve cinco campos.

CampoQué es
scorePosición en la escala, de 0 al número de nivel más alto; puede caer entre dos niveles, por ejemplo 1.43
legendMapa de número de nivel → descripción del nivel, para ayudarte a interpretar la puntuación
probabilitiesProbabilidad de cada nivel, que suman aproximadamente 1
confidence0–1;cuanto más concentrada esté la probabilidad en un solo nivel, más alto es
type"score"

score se calcula, no se inventa. Cada número de nivel se multiplica por su probabilidad y luego se suman:0×0.0 + 1×0.57 + 2×0.43 = 1.43.

Cómo elegir entre los tres tipos de pregunta.

Tipo de preguntaForma de la respuestaUso en el código
ChoiceElegir una opción fija, sin orden entre las opcionesSe mapea a N rutas de código
Score (esta lección)Posición en un espectro, cada nivel puedes describirloComparar con umbrales, ordenar
NoulUn sí/no limpio, la probabilidad misma es la señalUn solo if

Criterio oficial: si la respuesta está en un espectro y cada nivel se puede describir → Score; opciones fijas, sin orden → Choice; un sí/no limpio → Noul. Cuando se parece a ambos, elige el cuya respuesta pueda ser accionada directamente por el código. Tampoco uses Noul para preguntar «¿es fuerte en Python el candidato?»—cuando «fuerte» no está definido, noul 0.5 solo da mitad acierto y mitad error, no significa «nivel intermedio»; para medir nivel, usa las definiciones de niveles de Score.

Hazlo conmigo ​

Paso 1: define tu escala Jev Score (criteria como niveles ordenados) ​

Por qué: al juzgar, el modelo solo recibe las descripciones de niveles que tú escribes—no ve los números de nivel ni los niveles vecinos. Si las descripciones se escriben como «situaciones», el modelo puede hacerlas corresponder con el state; si se escriben como números o palabras de grado como «gravedad media», no tiene nada con qué comparar (las consecuencias están en el aviso de errores comunes, punto 1).

Esta lección usa la escala de gravedad de bugs de la documentación oficial, con tres niveles:

text
0: Cosmetic; no impact to functionality
1: Broken or degraded feature, but workaround exists
2: Blocking issue; no workaround exists

De bajo a alto: nivel 0 «problema estético, no afecta la funcionalidad», nivel 1 «la funcionalidad está rota pero hay alternativa», nivel 2 «bloqueo total, sin alternativa».

Reglas oficiales para escribir la escala:

  • Describe situaciones, no grados: «la funcionalidad está rota pero hay alternativa» se puede contrastar con la configuración, «gravedad media» no
  • Escribe tantos niveles como puedas describir con claridad, con un máximo de 10 niveles; tres niveles son muy comunes
  • Una pregunta mide una sola dimensión—«puntual, inteligente, con experiencia» son tres preguntas (ver aviso de errores comunes, punto 2)
  • Si en el extremo superior de la escala hay casos raros que requieren tratamiento especial, dales un nivel aparte (ver aviso de errores comunes, punto 4)

Deberías ver: tres descripciones de nivel, cada una una situación concreta que se puede comparar directamente con el reporte de bug.

  • Cada descripción de nivel mía es una situación, sin palabras de grado tipo «leve/media/grave» ni números sueltos

Paso 2: envía la primera solicitud de puntuación Score con typesafe-sdk ​

Por qué: primero haz funcionar tal cual el ejemplo oficial de una sola pregunta, y luego cámbialo por tu propia escala y lógica—así siempre tendrás una línea base «conocida como correcta» al depurar.

Crea score_bug.py y pega el ejemplo oficial:

python
from typesafe_sdk import Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.",
        questions={
            "bug_severity": Score(
                instructions="How severe is the reported issue?",
                criteria=[
                    "Cosmetic; no impact to functionality",
                    "Broken or degraded feature, but workaround exists",
                    "Blocking issue; no workaround exists",
                ],
            ),
        },
    )

    print(response.answers["bug_severity"].score)

Ejecútalo:

bash
.venv/bin/python score_bug.py

Deberías ver:

text
1.43

1.43 cae entre el nivel 1 y el nivel 2. La interpretación oficial de este ejemplo: la exportación se rompe en Safari, la mayoría de los clientes puede recurrir a Chrome como alternativa (nivel 1), pero los clientes que solo usan Safari no tienen alternativa (nivel 2)—el modelo se divide entre los dos niveles, con inclinación hacia el nivel 1. Los valores del ejemplo pueden cambiar según la versión de Jev; no te obsesiones con las diferencias tras el punto decimal.

  • Vi un número que cae entre dos niveles (el valor del ejemplo es 1.43)

💡 ¿Se puede puntuar contenido en chino?

Sí. La explicación oficial: el inglés es el idioma principal de entrenamiento y el de mejor precisión; otros idiomas, incluido el chino, funcionan pero con menor precisión. Antes de poner en producción un caso de uso en chino, ejecuta primero un lote con tus propios datos para ver el resultado, prestando atención a la distribución de confidence.

Paso 3: entiende el score devuelto, el legend y la distribución de probabilidad ​

Por qué: en proyectos reales la puntuación nunca se usa sola—el legend te ayuda a interpretarla, y probabilities y confidence te dicen qué tan «sólida» es esa puntuación.

La respuesta completa del ejemplo oficial:

json
{
  "model": "jev-1.13.0",
  "answers": {
    "bug_severity": {
      "type": "score",
      "score": 1.43,
      "confidence": 0.35,
      "legend": {
        "0": "Cosmetic; no impact to functionality",
        "1": "Broken or degraded feature, but workaround exists",
        "2": "Blocking issue; no workaround exists"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.57,
        "2": 0.43
      }
    }
  },
  "usage": {
    "input_tokens": 332,
    "output_tokens": 18
  }
}

Deberías ver: el objeto de respuesta tiene cinco campos, score coincide con lo que imprimiste en 1.43, y legend mapea 0/1/2 de vuelta a las tres descripciones de nivel que escribiste. El "model": "jev-1.13.0" del ejemplo corresponde a la versión que usaba la documentación oficial al grabar el ejemplo; si lo ejecutas ahora con jev-latest, ese campo muestra la versión actual del modelo.

Desglosémoslos uno por uno:

CampoValor en este ejemploCómo leerlo
score1.430×0.0 + 1×0.57 + 2×0.43: posición ponderada por probabilidad
legend0 → estético, 1 → hay alternativa, 2 → bloqueolos números de nivel se mapean de vuelta a las descripciones de nivel
probabilities1 nivel 0.57, 2 nivel 0.43el modelo se divide entre dos niveles
confidence0.35la probabilidad se reparte entre dos niveles, por eso es bajo

En la respuesta HTTP, las claves de legend y probabilities son cadenas "0"/"1"/"2"; el SDK de Python ya las ha convertido en claves enteras (answer.legend[1], answer.probabilities[1]), y los campos de ScoreAnswer están tipados.

Una misma pregunta, cinco tickets distintos (ejemplo comparativo de la documentación oficial):

Contenido del ticketscoreconfidenceProbabilidad (niveles 0/1/2)
El botón de exportación está desplazado unos píxeles0.01.01.0 / 0.0 / 0.0
La exportación a PDF no responde al hacer clic; todavía se puede exportar CSV y convertirlo uno mismo, pero lleva mucho tiempo1.01.00.0 / 1.0 / 0.0
La exportación se queda girando sin terminar; a algunos colegas el CSV todavía les funciona, a otros también se les rompió1.110.840.0 / 0.89 / 0.11
Safari se cuelga, Chrome funciona bien, y hay un cliente que solo usa Safari1.430.350.0 / 0.57 / 0.43
Todo el equipo no puede entrar al sistema desde esta mañana, cada vez 5002.01.00.0 / 0.0 / 1.0

Dos ideas clave:

  • La misma puntuación puede venir de distribuciones distintas. 1.0 puede ser «todo apostado al nivel 1», o también «mitad nivel 0 y mitad nivel 2» — la puntuación es igual, pero el significado es completamente distinto. Por eso hay que leer probabilities y confidence juntos.
  • confidence 1.0 describe la distribución, no es una garantía de que «la respuesta es correcta». Cuando la distribución apuesta todo a un nivel, es 1.0; cuando el modelo no distingue entre niveles, baja.

Un score decimal es simplemente una posición: se puede usar directamente para ordenar (cola de severidad); cuando el código necesita un nivel explícito, se redondea al nivel más cercano y luego se actúa — en la página del escenario Búsqueda y coincidencia hay ejemplos prácticos de usar «redondear al nivel más cercano» para tomar decisiones.

Paso 4: fijar umbrales según score y confidence, procesamiento automático o derivar a humano ​

Por qué: una puntuación solo se aprovecha de verdad cuando se convierte en acción. El patrón oficial: si score supera el umbral, va por flujo automático; si confidence es bajo, significa que el modelo no está seguro y se deriva a humano.

Siguiendo el response escrito en el paso 2:

python
answer = response.answers["bug_severity"]

if answer.score >= 1.5:
    action = "P1:立即处理"
elif answer.confidence < 0.5:
    action = "转人工复核"
else:
    action = "进正常队列"

print(action)

Deberías ver (para el ticket de Safari):

text
转人工复核

El score 1.43 no superó 1.5, y la confidence 0.35 quedó por debajo de 0.5 — el modelo está dividido entre dos niveles, justamente la señal de que conviene que un humano le eche un vistazo.

1.5 y 0.5 son valores ilustrativos. El uso oficial en tres tramos: confidence alta, ejecución automática directa; media, confirmar, etiquetar o pedir más información; baja, no hacer nada, derivar a humano o retroceder.

El umbral escala según el riesgo: en el ejemplo oficial 0.5 es el suelo de seguridad, y operaciones de alto riesgo como approve_transfer exigen > 0.9 para ejecutarse sin supervisión. La fórmula completa y ejemplos están en la lección Confidence.

Paso 5: dividir en varias preguntas Score atómicas y combinarlas ponderadas en el código ​

Por qué: «¿este ticket hay que priorizarlo?» es un juicio multidimensional — severidad, frustración del cliente y calidad del informe pesan cada uno un poco. La práctica oficial: una pregunta Score por dimensión, enviadas en paralelo en una sola petición, y combinación ponderada en el código. Cambiar los pesos es cambiar código, sin retocar ningún prompt.

python
from typesafe_sdk import Score, TypeSafeClient

TRIAGE_QUESTIONS = {
    "severity": Score(
        instructions="How severe is the reported issue?",
        criteria=[
            "Cosmetic; no impact to functionality",
            "Broken or degraded feature, but workaround exists",
            "Blocking issue; no workaround exists",
        ],
    ),
    "frustration": Score(
        instructions="How frustrated is the customer?",
        criteria=[
            "Calm, just stating facts",
            "Frustrated but civil",
            "Very angry, strong language or threatening to leave",
        ],
    ),
    "report_quality": Score(
        instructions="How much does the report give an engineer to work with?",
        criteria=[
            "No detail; just says something is broken",
            "Names the feature but no steps or environment",
            "Steps to reproduce or environment, but not both",
            "Steps to reproduce and environment",
        ],
    ),
}


def normalized(answers, question_id: str) -> float:
    """Put a score on 0 to 1 by dividing by its top level number."""
    top_level = len(TRIAGE_QUESTIONS[question_id].criteria) - 1
    return answers[question_id].score / top_level


def priority(ticket: str) -> float:
    with TypeSafeClient() as client:
        response = client.system_one(
            state=ticket,
            questions=TRIAGE_QUESTIONS,
        )
    answers = response.answers

    severity = normalized(answers, "severity")
    frustration = normalized(answers, "frustration")
    report_quality = normalized(answers, "report_quality")

    # A detailed report helps an engineer investigate, so it raises priority a little.
    return 0.6 * severity + 0.3 * frustration + 0.1 * report_quality

Dos detalles:

  • Normalizar antes de combinar. La puntuación máxima de una escala de tres niveles es 2, la de cuatro es 3 — sin normalizar, las preguntas de cuatro niveles pesan naturalmente más. Divide cada pregunta por su número de nivel más alto len(criteria) - 1, deja que todas caigan en 0–1, y así los pesos cobran sentido: la severity con peso 0.6 pesa exactamente el doble que la frustration con 0.3.
  • Añadir preguntas sin añadir peticiones. El ejemplo oficial (el mismo ticket de «se queda girando» del paso 3, con más contexto añadido) devuelve: severity 1.24 (confidence 0.64), frustration 1.28 (0.58), report_quality 3.0 (1.0); tras normalizar, 0.62 / 0.64 / 1.0, prioridad = 0.6×0.62 + 0.3×0.64 + 0.1×1.0 = 0.66. Varias preguntas evaluadas en paralelo casi no aumentan el tiempo de respuesta; solo cuestan un poco más de tokens de pregunta.

Deberías ver: priority() devuelve un número en 0–1; para el ticket del ejemplo oficial sale 0.66. Si luego el orden no te parece correcto, basta con ajustar los pesos y volver a ejecutar; para añadir una dimensión nueva, agrega una pregunta a TRIAGE_QUESTIONS y el número de peticiones no cambia.

Este enfoque de «dividir en puntuaciones atómicas y ponderar en código» es el patrón oficial de Composite scoring (puntuación compuesta), desarrollado por completo en la lección Puntuación compuesta.

Punto de control ✅ ​

  • Sé que la numeración de niveles es el índice del array de criteria, empezando desde 0
  • Obtuve 1.43 y puedo verificarlo a mano: 0×0.0 + 1×0.57 + 2×0.43
  • Sé que la misma puntuación puede provenir de distribuciones diferentes, así que hay que leerla junto con probabilities y confidence
  • Mi escala describe una situación en cada nivel, y cada pregunta mide una sola dimensión
  • Sé que en los juicios multidimensionales hay que normalizar (÷ número de nivel más alto) antes de combinar ponderado

Aviso de errores comunes ​

❌ Escribir solo números en la escala ​

text
instructions: "Rate severity from 0 to 2, where 2 is worst"
criteria: ["0", "1", "2"]
→ score 0.55, confidence 0.33, probabilities 0: 0.45, 1: 0.55, 2: 0.0

El equipo oficial hizo este experimento: el mismo ticket de «botón desalineado», con una escala de solo números dio 0.55 y confidence 0.33 — las probabilidades repartidas al azar entre los niveles 0 y 1; al cambiarlo por descripciones situacionales de tres niveles, score 0.0 y confidence 1.0.

El modelo solo usa las descripciones para compararlas con el state; una pregunta tipo «ponle una nota del 1–10» ni siquiera el propio Jev la resuelve bien. La forma correcta: escribir para cada nivel una situación comparable, y no esperar que los números en las instructions surtan efecto.

❌ Medir varias cosas con una sola pregunta ​

Si la descripción del nivel dice «puntual, inteligente, con experiencia», esa pregunta está midiendo tres cosas a la vez — una entrada con un rasgo alto y otro bajo no tiene dónde ubicarse, la confidence baja y el significado del score se enturbia. La forma correcta: una cosa por pregunta Score, y combinar los resultados en el código (el enfoque del paso 5).

❌ Usar la puntuación sin mirar la distribución ​

Un score de 1.0 puede ser todo apostado al nivel 1 (confidence alta), o mitad nivel 0 y mitad nivel 2 (confidence baja). El equipo oficial también dio una comparación de cómo la posición de la división afecta la confidence: en una escala de tres niveles, la confidence de las probabilidades (0, 0.5, 0.5) es 0.25, y la de (0.5, 0, 0.5) es 0 — dividirse entre dos niveles adyacentes pesa menos; dividirse entre los extremos del espectro pesa más.

Lo correcto: leer score junto con probabilities y confidence. Una confidence baja suele indicar que los niveles se solapan, que la pregunta mide más de una cosa, o que falta información en el state: deriva a revisión humana o completa la información, no fuerces la ejecución automática.

❌ Los casos extremos raros no tienen su propio nivel ​

En el extremo superior de la escala de emociones está «muy enfadado», y los mensajes con insultos y amenazas también se apiñan cerca de ese extremo: mirando solo el score no se separan, y precisamente esos son los mensajes que más necesitan un tratamiento especial. Enfoque oficial: dar a los casos extremos raros un nivel propio, por ejemplo añadir «insultos o amenazas» por encima de «muy enfadado».

Más modos de fallo (interpretación literal, conteos poco fiables, comparaciones de fechas que deben hacerse en código) en el manual de trampas de Jev 1.13.

Técnicas avanzadas (opcional) ​

Los niveles pueden escribirse como objetos. Si el modelo siempre puntúa entre dos niveles en entradas que consideras claras, cambia cada nivel de cadena a objeto: un campo dice qué cubre ese nivel y otro da algunos ejemplos de casos (mantén los mismos nombres de campo en todos los niveles):

json
"1": {
  "what": "Broken or degraded feature, but workaround exists",
  "examples": ["export fails in one browser but works in another"]
}

El equipo oficial hizo una comparación con el mismo ticket de Safari: con cadenas puras, score 1.43, confidence 0.35; al añadir ejemplos pertinentes («la exportación falla en un navegador y funciona en otro») pasó a 1.03, 0.96; con ejemplos añadidos ajenos al navegador, se mantuvo en 1.43, 0.35.

Los ejemplos solo sirven si se parecen a tus entradas reales; que la confidence suba tampoco significa que la respuesta sea correcta: tras ajustar las descripciones de los niveles, prueba con otras entradas antes de dar por definitiva la versión.

Probar la escala sin escribir código. En el Playground de la consola (https://console.typesafe.ai/playground) pega el state y añade la pregunta para una experiencia sin código.

Conectarte a la API directamente, saltándote el SDK. POST https://api.typesafe.ai/v1/systemone; el JSON sin procesar de una pregunta score se ve así (ejemplo oficial):

json
{
  "model": "jev-latest",
  "state": "I was charged twice for my subscription this month. Please refund the extra charge.",
  "questions": {
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this message?",
      "criteria": ["Can wait", "Needs attention this week", "Needs attention today"]
    }
  }
}

La definición completa de las restricciones de campos (límite de elementos del array criteria, los cinco campos de la respuesta) está en Referencia rápida de la API.

Resumen de la lección ​

✅ Jev Uso de Score: define una escala ordenada en criteria (se recomiendan al menos dos niveles, con un máximo de 10), Jev coloca el contenido en la escala y devuelve cinco campos.

✅ Los cinco campos: score (posición ponderada por probabilidad, puede caer entre dos niveles), legend, probabilities, confidence, type.

✅ Las puntuaciones van al código: aplicar umbrales, ordenar; con confidence baja, derivar a revisión humana y no forzar la ejecución automática.

✅ Divide los juicios complejos en Scores de una sola dimensión: normaliza (÷ número del nivel más alto) y combina con ponderación: ese es el patrón de puntuación compuesta.

Repaso de los campos de configuración clave:

CampoEscritura recomendadaDescripción
type"score"valor fijo
instructionsuna frase que aclare qué se evalúacomo How severe is the reported issue?
criteriadescripción de contextos, de bajo a alto; se recomienda ≥ 2 niveles, máximo 10el número de nivel = índice del array, desde 0; una dimensión por pregunta
acceso a la respuestaresponse.answers["id"].scoreen el SDK, legend / probabilities usan el número de nivel entero como clave

Para ver cómo se usa Score en escenarios reales: Búsqueda y coincidencia (reordenamiento con Score, redondeo al nivel más cercano); para la idea de combinar tipos de pregunta como filtro del contenido que entra al contexto, ver Filtrado de pasajes para RAG.

Avance de la próxima lección ​

En el otro extremo del espectro está el sí/no limpio: Noul, pregunta de sí/no: obtén la probabilidad real de 0 a 1.

Aprenderás:

  • noul es la probabilidad de 0–1; la respuesta no incluye un confidence aparte
  • 0.5 significa fifty-fifty, no «grado medio»: el grado se mide con el Score de esta lección
  • Umbrales de partida: yes ≥ 0.7, no ≤ 0.3
  • Cuándo cambiar Score por Noul y cuándo preguntar ambas cosas a la vez
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.