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
criteriauna 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:
.venvtiene instaladotypesafe-sdkyTYPESAFE_API_KEYya 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:
| Campo | Qué se escribe | Ejemplo |
|---|---|---|
type | Fijo "score" | — |
instructions | Una frase que aclara qué se evalúa | How severe is the reported issue? |
criteria | Lista de niveles ordenados, de menor a mayor, con una descripción por nivel | Ver 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.
| Campo | Qué es |
|---|---|
score | Posición en la escala, de 0 al número de nivel más alto; puede caer entre dos niveles, por ejemplo 1.43 |
legend | Mapa de número de nivel → descripción del nivel, para ayudarte a interpretar la puntuación |
probabilities | Probabilidad de cada nivel, que suman aproximadamente 1 |
confidence | 0–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 pregunta | Forma de la respuesta | Uso en el código |
|---|---|---|
| Choice | Elegir una opción fija, sin orden entre las opciones | Se mapea a N rutas de código |
| Score (esta lección) | Posición en un espectro, cada nivel puedes describirlo | Comparar con umbrales, ordenar |
| Noul | Un sí/no limpio, la probabilidad misma es la señal | Un 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:
0: Cosmetic; no impact to functionality
1: Broken or degraded feature, but workaround exists
2: Blocking issue; no workaround existsDe 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:
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:
.venv/bin/python score_bug.pyDeberías ver:
1.431.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:
{
"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:
| Campo | Valor en este ejemplo | Cómo leerlo |
|---|---|---|
score | 1.43 | 0×0.0 + 1×0.57 + 2×0.43: posición ponderada por probabilidad |
legend | 0 → estético, 1 → hay alternativa, 2 → bloqueo | los números de nivel se mapean de vuelta a las descripciones de nivel |
probabilities | 1 nivel 0.57, 2 nivel 0.43 | el modelo se divide entre dos niveles |
confidence | 0.35 | la 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 ticket | score | confidence | Probabilidad (niveles 0/1/2) |
|---|---|---|---|
| El botón de exportación está desplazado unos píxeles | 0.0 | 1.0 | 1.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 tiempo | 1.0 | 1.0 | 0.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.11 | 0.84 | 0.0 / 0.89 / 0.11 |
| Safari se cuelga, Chrome funciona bien, y hay un cliente que solo usa Safari | 1.43 | 0.35 | 0.0 / 0.57 / 0.43 |
| Todo el equipo no puede entrar al sistema desde esta mañana, cada vez 500 | 2.0 | 1.0 | 0.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
probabilitiesyconfidencejuntos. - 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:
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):
转人工复核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.
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_qualityDos 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
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.0El 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):
"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):
{
"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:
| Campo | Escritura recomendada | Descripción |
|---|---|---|
type | "score" | valor fijo |
instructions | una frase que aclare qué se evalúa | como How severe is the reported issue? |
criteria | descripción de contextos, de bajo a alto; se recomienda ≥ 2 niveles, máximo 10 | el número de nivel = índice del array, desde 0; una dimensión por pregunta |
| acceso a la respuesta | response.answers["id"].score | en 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:
noules 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